DaShangDao/daShangDao_psiServer

Fork 0

Administrator 17a21c4cb4 修改数字

2026-06-15 13:47:39 +08:00

24 KiB

Raw Blame History

PSI 进销存系统 - 项目说明文档

一、项目概述

PSI 是一套基于 Go 语言开发的完整进销存管理系统，涵盖采购、销售、库存、仓库、物流等核心业务环节，支持波次（Wave）管理、OCR 识别、外部系统对接等企业级功能。

项目名称：PSI 进销存系统
技术栈：Go 1.25.7 + Gin + GORM + MySQL
服务端口：9090
项目路径：D:\www\wwwroot\psi

二、技术架构

组件	技术
Web 框架	Gin v1.11.0
ORM	GORM v1.31.1 + MySQL Driver
认证	JWT（golang-jwt/jwt/v5）
日志	Logrus + file-rotatelogs（按时间轮转）
搜索引擎	Elasticsearch v8（可选，当前已注释）
OCR	本地 OCR 服务（可启动独立进程）
Excel 导出	Excelize v2
条形码	boombuler/barcode（二维码/条形码生成）
图像处理	golang.org/x/image
加密	golang.org/x/crypto

三、目录结构

psi/
├── main.go                  # 程序入口
├── config.yaml              # 配置文件
├── go.mod / go.sum         # Go 依赖管理
├── config/                  # 配置加载模块
├── constant/                # 常量定义（日志通道等）
├── controllers/             # HTTP 控制器层（处理请求，32个）
├── middleware/              # 中间件（JWT 认证、CORS、API 签名）
├── models/                 # 数据模型层
│   ├── request/            # 请求参数结构体
│   ├── response/           # 响应结构体
│   ├── book_info.go        # 图书信息模型
│   ├── employee.go         # 员工模型
│   └── ...                # 其他业务模型（共41个表）
├── service/                # 业务逻辑层
├── database/               # 数据库连接初始化
├── routes/                 # 路由定义
├── utils/                  # 工具函数（JWT、加密等）
├── es/                     # Elasticsearch 初始化（可选）
├── ocr/                    # OCR 服务
├── template/               # 模板文件
├── fonts/                  # 字体文件
├── linux/                  # Linux 部署文件
├── runtime/                # 运行时文件（日志等）
├── .idea/                  # IDE 配置
└── sql.txt                 # 数据库补充脚本

四、数据库表关系

4.1 表分类统计

模块	表数量	说明
基础信息	10	员工、供应商、仓库、库位、商品、店铺、客户等
库存管理	5	库存、库存明细、库存流水、盘库等
采购管理	4	采购订单、采购明细、入库单、入库明细
销售出库	7	销售订单、销售明细、出库单、出库明细、发货单等
波次管理	3	波次主表、波次任务、波次任务明细
其他	12	小车、外部任务、打印、分账、统计等
总计	41

4.2 核心表结构

（1）基础信息模块

表名	说明	关键字段
employees	员工表	id, username, role, status, expire_time
supplier	供应商表	id, code, name, status
warehouse	仓库表	id, code, name, logistics_id, type, status
location	库位表	id, warehouse_id, code, type, capacity, status
product	商品表	id, category_id, barcode, name, price, status
shop	店铺表	id, mall_id, shop_type, shop_alias_name, status
customer	客户表	-
logistics	物流模板表	-

（2）库存模块

表名	说明	关键字段
inventory	库存汇总表	id, warehouse_id, product_id, batch_no, quantity, locked_quantity
inventory_log	库存流水表	id, warehouse_id, product_id, location_id, change_type, change_quantity, related_order_no

（3）采购模块

表名	说明	关键字段
purchase_order	采购订单主表	id, po_no, supplier_id, warehouse_id, total_amount, status
receiving_order	入库单主表	id, receiving_no, purchase_order_id, wave_task_id, warehouse_id, status

（4）销售与出库模块

表名	说明	关键字段
sales_order	销售订单主表	id, so_no, customer_id, warehouse_id, shop_type, total_amount, status, is_distribution
outbound_order	出库单主表	id, out_no, wave_task_id, warehouse_id, total_quantity, status
shipping_order	发货单主表	id, shipping_no, customer_id, status, shipping_time

（5）波次管理模块

表名	说明	关键字段
wave_header	波次主表	id, wave_no, direction, type, warehouse_id, related_order_id, status
wave_task	波次任务表	-
wave_task_detail	波次任务明细表	-

4.3 表关系图谱

┌─────────────┐
│  employees  │
└──────┬──────┘
       │ 创建/操作
       ↓
┌───────────────────────────────────────────────────────────────────┐
│                         核心业务流程                                │
├───────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐    │
│  │   supplier   │─────▶│purchase_order│─────▶│  receiving   │    │
│  │  (供应商)     │      │  (采购单)    │      │   (入库单)   │    │
│  └──────────────┘      └──────┬───────┘      └──────┬───────┘    │
│                              │                      │             │
│  ┌──────────────┐           │                      │             │
│  │   product    │◀──────────┘                      │             │
│  │   (商品)     │                                  │             │
│  └──────┬───────┘                                  │             │
│         │                                          │             │
│         │              ┌──────────────┐            │             │
│         └─────────────▶│  inventory   │◀───────────┘             │
│                        │   (库存)     │                          │
│                        └──────┬───────┘                          │
│                               │                                  │
│                               │                                  │
│  ┌──────────────┐            │            ┌──────────────┐      │
│  │   customer   │            │            │    sales     │      │
│  │   (客户)      │◀───────────┴───────────▶│   (销售单)   │      │
│  └──────────────┘                         └──────┬───────┘      │
│                                                 │               │
│  ┌──────────────┐      ┌──────────────┐        │               │
│  │    shop      │      │  outbound    │◀───────┘               │
│  │   (店铺)     │◀────▶│   (出库单)   │                        │
│  └──────────────┘      └──────┬───────┘                        │
│                               │                                │
│                               ▼                                │
│                        ┌──────────────┐                        │
│                        │   shipping   │                        │
│                        │   (发货单)   │                        │
│                        └──────────────┘                        │
└───────────────────────────────────────────────────────────────────┘
                                      ↑
                                      │
                           ┌──────────────┐
                           │  wave_header │
                           │   (波次)     │
                           └──────┬───────┘
                                  │
                           ┌──────────────┐
                           │  wave_task   │
                           │ (波次任务)   │
                           └──────────────┘
                                  ↑
                                  │
                           ┌──────────────┐
                           │     car      │
                           │    (小车)    │
                           └──────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                         基础信息层                               │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                 │
│  │ warehouse│    │ location │    │logistics │                 │
│  │ (仓库)   │───▶│  (库位)  │    │(物流模板)│                 │
│  └──────────┘    └──────────┘    └──────────┘                 │
└─────────────────────────────────────────────────────────────────┘

4.4 关键表关系详细说明

采购入库流程关系

供应商(supplier) → 采购订单(purchase_order)
                              ↓
                         波次(wave_header)
                              ↓
                         波次任务(wave_task)
                              ↓
                         入库单(receiving_order)
                              ↓
                         库存增加(inventory + inventory_log)

purchase_order.supplier_id → supplier.id
purchase_order.warehouse_id → warehouse.id
receiving_order.purchase_order_id → purchase_order.id
receiving_order.wave_task_id → wave_task.id
inventory_log.related_order_no → purchase_order.po_no 或 receiving_order.receiving_no

销售出库流程关系

客户(customer) → 销售订单(sales_order)
                              ↓
                         波次(wave_header)
                              ↓
                         波次任务(wave_task)
                              ↓
                         出库单(outbound_order)
                              ↓
                         库存减少(inventory + inventory_log)
                              ↓
                         发货单(shipping_order)

sales_order.customer_id → customer.id
sales_order.warehouse_id → warehouse.id
sales_order.sales_person_id → shop.id
outbound_order.wave_task_id → wave_task.id
outbound_order.warehouse_id → warehouse.id
inventory_log.related_order_no → sales_order.so_no 或 outbound_order.out_no

库存管理关系

warehouse(仓库) ──┐
                 ├─→ inventory(库存) ←─ product(商品)
location(库位) ──┘       ↑
                         │
                         └─ inventory_log(库存流水)

inventory.warehouse_id → warehouse.id
inventory.product_id → product.id
inventory_log.warehouse_id → warehouse.id
inventory_log.location_id → location.id
inventory_log.product_id → product.id
location.warehouse_id → warehouse.id

五、核心业务模块

5.1 认证与权限

功能	说明
JWT 认证	基于 Bearer Token，有效期 24 小时
角色权限	普通员工（role≠255）/ 管理员（role=255）
API 签名	MD5 签名验证，防篡改（app_key + app_secret）
账号过期	支持设置员工账号过期时间

5.2 员工管理（管理员接口）

员工列表 / 新增 / 修改密码 / 设置级别
设置账号过期时间 / 查看过期状态
PDA 配置（用于手持设备）
员工操作日志

5.3 供应商管理

供应商增删改查
供应商详情查看

5.4 仓库与库位管理

仓库增删改查
库位增删改查
库位批量生成（按规则批量创建库位编号）
库位同步外部系统

5.5 商品管理

商品列表（支持分页、筛选）
商品新增 / 修改（支持图片上传）
商品售价批量修改（公开接口，支持外部调用）
商品导出到 Excel
商品库存查询（按库位/仓库聚合）
商品日志（记录价格/信息变更，支持审核流程）
图书信息获取（对接外部图书 API）
条形码 / 二维码生成

5.6 采购流程（波次模式）

创建采购单 → 生成采购波次 → 释放波次（生成波次任务）
                                      ↓
                              PDA 扫码收货
                                      ↓
                              提交入库单 → 库存增加

POST /api/purchase-order/create-with-wave — 创建采购单并生成波次
POST /api/wave/release — 释放波次，生成波次任务明细
POST /api/receiving/bind-wave — 绑定波次，创建入库单
POST /api/receiving/submit — 提交入库，更新库存
支持**小车（Car）**容量管理，按车容量分配波次任务

5.7 销售与出库流程

创建销售单 → 生成出库波次 → 释放出库波次
                                      ↓
                              PDA 拣货/出库
                                      ↓
                              提交出库单 → 库存减少
                                      ↓
                              创建发货单 → 填写物流信息

POST /api/sales-order/create — 创建销售订单（公开接口）
POST /api/outbound-order/create — 创建出库单
POST /api/wave/outbound/create — 生成出库波次
POST /api/wave/outbound/release — 释放出库波次
POST /api/outbound/bind-wave — 绑定出库波次
POST /api/outbound/submit — 提交出库
POST /api/shipping-order/create — 创建发货单
POST /api/shipping-order/update — 更新物流信息
POST /api/sales-order/cancel — 取消销售单
POST /api/wave/outbound/cancel — 取消出库波次

5.8 库存管理

库存列表（按商品/库位/仓库维度）
库存按商品聚合列表（同商品不同库位合并显示）
库存明细（跟踪每笔出入库记录）
库存变动日志
盘库调整（库存盘点，支持盘盈/盘亏调整）
盘库退货（将盘点差异商品退回）
库存统计

5.9 波次任务管理

波次任务列表（按采购/出库类型）
波次任务详情
波次任务进度跟踪

5.10 店铺与外部对接

店铺管理（增删改查）
外部任务（OutTask）：与外部系统同步任务状态
按店铺查询外部任务
外部任务日志
同步商品到外部系统（external_api.sync_product_url）
同步任务到外部系统（external_api.sync_task_url）

5.11 物流管理

物流模板增删改查
物流模板详情

5.12 分拣设置

获取分拣配置
保存分拣配置（影响波次任务分配逻辑）

5.13 仪表盘统计

仪表盘概览统计（/api/dashboard/statist）
各仓库库存统计（/api/dashboard/warehouse）
订单统计（/api/dashboard/order）

5.14 OCR 识别

POST /api/ocr — 图片文字识别（公开接口）
可启动本地 OCR 服务进程（OCRService.exe）

六、API 接口分类

公开接口（无需认证）

接口	方法	说明
`/api/login/:type`	POST	员工登录
`/api/employee/reg`	POST	员工注册
`/api/ocr`	POST	OCR 文字识别
`/api/sales-order/create`	POST	创建销售单
`/api/product/updatePrice`	POST	批量修改商品售价
`/api/product/getProductInventory`	GET	查询商品库存
`/api/employee/check_code`	GET	校验员工码
`/api/employee/clear_code`	POST	清除员工码
`/api/out-task-log/update`	POST	更新外部任务日志

签名接口（需要 API 签名，无需 JWT）

接口	方法	说明
`/api/location/sync-locations`	POST	同步库位到外部系统
`/api/goods/sync-batch`	POST	批量同步商品到外部系统

需认证接口（JWT + API 签名）

大部分业务接口需要 Authorization: Bearer <token> 请求头，以及 API 签名验证。

管理员接口（需要 role=255）

员工管理、用户类型管理的完整 CRUD。

七、配置说明（config.yaml）

server:
  port: "9090"                          # 服务监听端口
  host: "http://192.168.101.213:9090/" # 服务外部访问地址

database:
  host: localhost
  port: "3306"
  user: root
  password: root
  name: psi                            # 数据库名
  encrypt_key: "..."                    # 敏感字段加密密钥（AES）

jwt:
  secret: "..."                        # JWT 签名密钥
  expire_hours: 24                     # Token 有效期

api_sign:
  app_key: "psi"
  app_secret: "psi_api_sign_secret"    # API 签名密钥
  timestamp_tolerance: 300             # 时间戳容差（秒）

log:
  max_age: 600                         # 日志最大保留时间（秒）
  rotate_time: 600                     # 日志轮转时间间隔（秒）
  root_path: "./runtime/logs"
  channel:                             # 各日志通道文件路径
    sql: "/sql/err.log"
    work: "/work/err.log"
    request: "/request/err.log"
    es: "/es/err.log"
    redis: "/redis/err.log"

ocr:
  service_url: "http://127.0.0.1:35569/ocr"
  exe_url: "./ocr/OCRService.exe"      # OCR 可执行文件路径

external_api:
  sync_product_url: "http://192.168.101.127:8080/zhishu/filterSet/save"
  sync_task_url: "http://192.168.101.156:8080/task/create"
  sync_task_body_url: "http://192.168.101.156:8080/task/setTaskBody"
  timeout: 30

注意：Elasticsearch 配置已注释，ES 同步功能当前未启用。

八、数据库模型一览

模型文件	说明
`employee.go`	员工/用户信息
`employee_level.go`	员工级别配置
`employee_level_log.go`	员工级别变更日志
`employee_settings.go`	员工 PDA 配置
`supplier.go`	供应商
`warehouse.go`	仓库
`location.go`	库位
`product.go`	商品
`product_category.go`	商品分类
`product_unit_conversion.go`	商品单位换算
`product_serial.go`	商品序列号
`product_log.go`	商品变更日志（审核流）
`purchase_order.go`	采购订单
`purchase_order_item.go`	采购订单明细
`receiving_order.go`	入库单
`receiving_order_item.go`	入库单明细
`sales_order.go`	销售订单
`sales_order_item.go`	销售订单明细
`outbound_order.go`	出库单
`outbound_order_item.go`	出库单明细
`shipping_order.go`	发货单
`inventory.go`	库存
`inventory_detail.go`	库存明细
`inventory_log.go`	库存变动日志
`stock_check.go`	盘库单
`stock_check_item.go`	盘库明细
`wave_header.go`	波次头
`wave_task.go`	波次任务
`wave_task_detail.go`	波次任务明细
`car.go`	小车（AGV/搬运车）
`car_shop.go`	小车与店铺关联
`shop.go`	店铺
`logistics.go`	物流模板
`out_task.go`	外部任务
`out_task_log.go`	外部任务日志
`print_log.go`	打印日志
`print_task.go`	打印任务
`sorting_settings.go`	分拣设置
`statist.go`	统计数据
`customer.go`	客户
`user_type.go`	用户类型
`book_info.go`	图书信息（对接外部图书 API）
`split_account_config.go`	分账配置
`split_account_deduction_log.go`	分账扣钱日志
`outbound_order_location_log.go`	出库单库位变更记录

九、启动与运行

本地开发

# 进入项目目录
cd D:\www\wwwroot\psi

# 安装依赖
go mod download

# 运行项目
go run main.go

服务启动后监听 http://localhost:9090。

配置说明

确保 MySQL 服务运行，并创建 psi 数据库
根据实际的 MySQL 账号密码修改 config.yaml
如需启用 OCR，确保 ocr/OCRService.exe 存在
如需启用 Elasticsearch，取消 main.go 中 ES 初始化代码的注释，并配置 config.yaml 中的 es 节点
执行 sql.txt 中的补充 SQL 脚本（分账配置、出库单库位变更记录等）

十、中间件说明

中间件文件	功能
`middleware/cors.go`	跨域资源共享（CORS）处理
`middleware/auth.go`	JWT 认证 + 员工状态校验 + 租户数据库连接
`middleware/sign.go`	API 签名验证（防篡改、防重放攻击）

请求头要求（需认证接口）：

Authorization: Bearer <jwt_token>
X-App-Key: psi
X-Timestamp: <unix_timestamp>
X-Sign: <md5_sign>

签名计算方式：md5(app_key + app_secret + timestamp)

十一、外部系统集成

系统支持与以下外部系统对接：

对接功能	配置项	说明
商品同步	`sync_product_url`	将商品信息推送到外部系统
任务创建	`sync_task_url`	在外部系统创建任务
任务内容同步	`sync_task_body_url`	同步任务详细信息到外部系统
库位同步	`/api/location/sync-locations`	将库位信息推送到外部系统
商品批量同步	`/api/goods/sync-batch`	批量推送商品到外部系统

十二、技术架构亮点

技术特性	说明
GORM ORM	强大的数据库操作，自动关联查询
JWT 认证	无状态认证，有效期 24 小时
API 签名验证	MD5 签名防篡改、防重放攻击
Elasticsearch	可选的搜索引擎集成（代码已注释）
OCR 识别	本地 OCR 服务进程，支持图片文字识别
Excel 处理	Excelize 库，支持数据导入导出
条码生成	boombuler/barcode，支持二维码/条形码
日志轮转	file-rotatelogs，按时间轮转日志
软删除	所有表都支持 IsDel 逻辑删除标记
时间戳	使用 Unix 时间戳（秒）而非 datetime

十三、待完善功能（根据代码注释）

✅ Elasticsearch 同步功能（代码已注释，可启用）
✅ OCR 服务（代码已注释，可启用）
外部系统对接 URL 已在配置中，需确认外部系统接口可用性
main.go 中 ES 和 OCR 的初始化代码已注释，按需启用

文档生成时间：2026-06-05 项目路径：D:\www\wwwroot\psi

24 KiB Raw Blame History Unescape Escape