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

## 一、项目概述

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

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

---

## 二、技术架构

| 组件 | 技术 |
|------|------|
| Web 框架 | [Gin v1.11.0](https://github.com/gin-gonic/gin) |
| ORM | [GORM v1.31.1](https://gorm.io/) + 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）

```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` | 出库单库位变更记录 |

---

## 九、启动与运行

### 本地开发

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

# 安装依赖
go mod download

# 运行项目
go run main.go
```

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

### 配置说明

1. 确保 MySQL 服务运行，并创建 `psi` 数据库
2. 根据实际的 MySQL 账号密码修改 `config.yaml`
3. 如需启用 OCR，确保 `ocr/OCRService.exe` 存在
4. 如需启用 Elasticsearch，取消 `main.go` 中 ES 初始化代码的注释，并配置 `config.yaml` 中的 `es` 节点
5. 执行 `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*