# PSI 进销存系统 - 技术分析报告

## 执行摘要

本报告对 PSI 进销存系统进行全面技术分析，涵盖架构设计、代码质量、数据库设计、安全性等多个维度。分析时间：2026年6月5日。

---

## 1. 技术栈深度分析

### 1.1 核心技术选型评估

| 组件 | 技术方案 | 版本 | 优势 | 风险 |
|------|---------|------|------|------|
| Web 框架 | Gin | v1.11.0 | 高性能、成熟社区、中间件丰富 | 升级维护依赖 |
| ORM | GORM | v1.31.1 | 自动迁移、预加载、钩子 | 复杂查询性能需优化 |
| 数据库 | MySQL | - | 事务支持、索引优化 | 无主从配置 |
| 认证 | JWT | v5 | 无状态、跨域友好 | Token 刷新机制 |
| 日志 | Logrus + file-rotatelogs | - | 结构化日志、自动轮转 | 缺少日志聚合 |
| Excel处理 | Excelize | v2 | 高性能读写 | 大文件内存占用 |

### 1.2 依赖包清单与用途

**核心依赖（go.mod）**：

```
github.com/gin-gonic/gin              # Web框架
gorm.io/gorm                          # ORM
gorm.io/driver/mysql                  # MySQL驱动
github.com/golang-jwt/jwt/v5          # JWT认证
github.com/sirupsen/logrus            # 日志
github.com/xuri/excelize/v2           # Excel处理
github.com/boombuler/barcode          # 条码生成
github.com/elastic/go-elasticsearch/v8 # ES搜索（已注释）
```

**间接依赖亮点**：
- `github.com/bytedance/sonic` - 极快的JSON处理
- `github.com/goccy/go-yaml` - YAML配置解析

---

## 2. 架构设计分析

### 2.1 分层架构

```
┌─────────────────────────────────────────────────┐
│  Controller 层 (controllers/)                   │
│  - 请求参数校验                                 │
│  - 响应格式化                                   │
│  - 中间件处理                                   │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────┐
│  Service 层 (service/)                         │
│  - 业务逻辑实现                                 │
│  - 事务管理                                     │
│  - 外部API调用                                  │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────┐
│  Model 层 (models/)                            │
│  - 数据模型定义                                 │
│  - 数据库操作                                   │
│  - 请求/响应结构体                              │
└────────────────┬────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────┐
│  基础设施层                                     │
│  - config/: 配置加载                            │
│  - database/: 数据库连接                        │
│  - middleware/: 中间件                          │
│  - utils/: 工具函数                             │
└─────────────────────────────────────────────────┘
```

**架构优点**：
✅ 清晰的分层职责分离
✅ 代码复用性好
✅ 便于单元测试

**改进建议**：
⚠️ 缺少 Repository 层，Service 直接操作 Model
⚠️ 缺少 DTO 层，Model 和 API 耦合

### 2.2 目录结构评估

```
psi/
├── 优点
│   ├── controllers/ - 按业务模块组织良好
│   ├── models/ - 清晰区分 request/response
│   ├── middleware/ - 认证、CORS、签名职责明确
│   ├── service/ - 业务逻辑独立
│   └── utils/ - 工具函数集中管理
│
└── 可优化
    ├── 缺少 docs/ - API文档存放
    ├── 缺少 tests/ - 单元测试
    ├── 缺少 scripts/ - 部署脚本
    └── 缺少 internal/ - 内部包隔离
```

---

## 3. 数据库设计分析

### 3.1 表设计概览

**表数量**：41张
**核心表**：15张
**辅助表**：26张

### 3.2 核心表关系分析

#### 3.2.1 商品管理链路

```
product_category (商品分类)
    ↓
product (商品) ← product_log (变更日志)
    ↓
product_serial (序列号)
    ↓
product_unit_conversion (单位换算)
```

**设计优点**：
✅ 商品变更有日志记录，支持审核
✅ 支持序列号管理，适合图书行业

**改进建议**：
⚠️ `product.category_id` 缺少外键约束
⚠️ 商品图片使用 JSON 存储，建议单独表

#### 3.2.2 库存管理链路

```
warehouse (仓库) ← logistics (物流)
    ↓
location (库位)
    ↓
inventory (库存) ← inventory_detail (明细)
    ↓
inventory_log (流水)
```

**设计优点**：
✅ 库存支持批次管理（batch_no）
✅ 库存流水记录完整
✅ 支持锁定库存（locked_quantity）

**改进建议**：
⚠️ `inventory_log.location_id` 可以为空，建议明确业务规则
⚠️ 缺少库存预警配置表

#### 3.2.3 采购流程链路

```
supplier (供应商)
    ↓
purchase_order (采购单) ← purchase_order_item (明细)
    ↓
wave_header (波次) ← wave_task (任务) ← wave_task_detail (明细)
    ↓
receiving_order (入库单) ← receiving_order_item (明细)
    ↓
inventory (库存增加) + inventory_log (流水)
```

**设计优点**：
✅ 波次设计支持批量作业
✅ 支持小车容量分配
✅ 完整的单据链路

**改进建议**：
⚠️ `wave_header.related_order_id` 类型是采购单还是销售单不够明确
⚠️ 建议增加 wave_type 枚举字段

#### 3.2.4 销售流程链路

```
customer (客户)
    ↓
sales_order (销售单) ← sales_order_item (明细)
    ↓
wave_header (波次) ← wave_task (任务)
    ↓
outbound_order (出库单) ← outbound_order_item (明细)
    ↓
outbound_order_location_log (库位变更)
    ↓
inventory (库存减少) + inventory_log (流水)
    ↓
shipping_order (发货单) ← shipping_order_item (明细)
```

**设计优点**：
✅ 销售单关联店铺（shop）
✅ 支持分销模式（is_distribution）
✅ 库位变更有记录

**改进建议**：
⚠️ 发货单缺少物流单号字段
⚠️ 建议增加发货状态流转记录

### 3.3 索引设计评估

**已知索引**（从模型推断）：
- `product.barcode` - 条码查询
- `warehouse.code` - 仓库编码唯一
- `location.warehouse_id + code` - 库位唯一
- `purchase_order.po_no` - 采购单号
- `sales_order.so_no` - 销售单号
- `inventory_log.related_order_no` - 单据关联
- `inventory.warehouse_id + product_id + batch_no` - 库存唯一

**缺失索引建议**：
- `inventory_log.created_at` - 时间范围查询
- `wave_header.warehouse_id + status + direction` - 波次查询
- `employee.role` - 权限查询

### 3.4 分账模块新增表分析

**split_account_config（分账配置）**：
- 支持 JSON 格式的规则配置
- 状态管理（启用/禁用）
- 创建/更新人追踪

**split_account_deduction_log（分账扣钱日志）**：
- 关联业务单号
- 记录扣款明细（JSON）
- 记录扣款前后金额

**设计优点**：
✅ JSON 配置灵活
✅ 日志完整可追溯

---

## 4. 代码质量分析

### 4.1 中间件设计分析

**middleware/auth.go - JWT认证**：
```
功能：
- Token 验证
- 员工状态检查
- 租户数据库连接

优点：
✅ 职责单一
✅ 支持租户隔离

改进：
⚠️ Token 过期后缺少刷新机制
⚠️ 建议增加 Token 黑名单
```

**middleware/sign.go - API签名**：
```
功能：
- AppKey 验证
- 时间戳检查（容忍300秒）
- MD5签名验证

优点：
✅ 防篡改
✅ 防重放攻击

改进：
⚠️ MD5 安全性较低，建议升级到 HMAC-SHA256
⚠️ 时间戳容忍度 5 分钟偏长
```

**middleware/cors.go - 跨域处理**：
```
功能：
- 允许所有来源
- 允许所有方法
- 允许所有头

优点：
✅ 开发便利

改进：
⚠️ 生产环境建议限制 Origin 白名单
⚠️ 建议增加预检请求缓存
```

### 4.2 模型设计模式

**统一模式**：
```go
type Model struct {
    ID        int64  // 主键
    CreatedAt int64  // Unix时间戳
    UpdatedAt int64  // Unix时间戳
    IsDel     int8   // 软删除标记
}
```

**优点**：
✅ 统一的时间戳格式（秒）
✅ 软删除支持
✅ ID使用int64避免溢出

**改进建议**：
⚠️ 缺少 `DeletedAt` 字段（有则有值，无则为0）
⚠️ 建议使用 `gorm.Model` 扩展或自定义基类

### 4.3 Service层模式

从文件结构看，Service层实现了完整的CRUD：
- `CreateXxx()`
- `UpdateXxx()`
- `DeleteXxx()`
- `GetXxx()`
- `ListXxx()`

**优点**：
✅ 接口统一
✅ Controller层简洁

**改进建议**：
⚠️ 建议增加事务封装
⚠️ 建议增加业务校验层

---

## 5. 安全性分析

### 5.1 认证安全

| 安全项 | 状态 | 说明 |
|-------|------|------|
| 密码加密 | ❓ | 未知，需检查代码 |
| JWT签名 | ✅ | 使用密钥签名 |
| Token过期 | ✅ | 24小时过期 |
| Token刷新 | ❌ | 未实现 |
| 账号过期 | ✅ | 支持设置 |
| 员工状态 | ✅ | 登录时检查 |

### 5.2 API安全

| 安全项 | 状态 | 说明 |
|-------|------|------|
| API签名 | ✅ | MD5签名 |
| 时间戳验证 | ✅ | 300秒容忍 |
| 防重放 | ⚠️ | 无Nonce机制 |
| 速率限制 | ❌ | 未实现 |
| SQL注入 | ✅ | GORM参数化查询 |
| XSS防护 | ❓ | 未知 |

### 5.3 数据安全

| 安全项 | 状态 | 说明 |
|-------|------|------|
| 敏感字段加密 | ✅ | config中有encrypt_key |
| 软删除 | ✅ | 所有表支持 |
| 操作日志 | ✅ | inventory_log等 |
| 数据备份 | ❌ | 配置中未提及 |

### 5.4 安全建议优先级

**高优先级**：
1. API签名升级为 HMAC-SHA256
2. 实现速率限制
3. 增加 Token 刷新机制
4. 实现防重放的 Nonce 机制

**中优先级**：
5. 生产环境 CORS 限制 Origin
6. 敏感操作增加二次验证
7. 定期数据库备份

**低优先级**：
8. 操作审计日志完善
9. 数据脱敏

---

## 6. 性能分析

### 6.1 潜在性能瓶颈

| 场景 | 瓶颈点 | 建议 |
|------|--------|------|
| 库存查询 | 多表关联 | 增加 Redis 缓存 |
| 波次生成 | 批量计算 | 异步处理 + 消息队列 |
| Excel导出 | 大文件内存 | 流式处理 + 分页 |
| 日志写入 | 同步阻塞 | 异步日志写入 |

### 6.2 数据库性能优化建议

1. **索引优化**：
   - 增加常用查询组合索引
   - 定期分析索引使用情况

2. **查询优化**：
   - 避免 N+1 查询（使用 Preload）
   - 分页查询限制每页数量
   - 大表考虑分库分表

3. **缓存策略**：
   - 商品基础信息缓存
   - 仓库/库位信息缓存
   - 库存汇总缓存（带过期时间）

---

## 7. 外部集成分析

### 7.1 OCR服务集成

**状态**：代码已注释，可启用

**架构**：
```
Gin API → OCR服务 (独立进程)
              ↓
         OCRService.exe
```

**优点**：
✅ 独立进程，不影响主服务
✅ 本地处理，数据安全

**改进**：
⚠️ 建议增加 OCR 服务健康检查
⚠️ 建议增加 OCR 结果缓存

### 7.2 Elasticsearch集成

**状态**：代码已注释，可启用

**用途**：
- 商品全文搜索
- 订单搜索
- 日志分析

**建议**：
⚠️ 增量同步机制
⚠️ 索引别名管理

### 7.3 外部系统API

**配置**：
```yaml
external_api:
  sync_product_url: ...  # 商品同步
  sync_task_url: ...     # 任务创建
  sync_task_body_url: ... # 任务内容
```

**建议**：
⚠️ 增加重试机制
⚠️ 增加熔断保护
⚠️ 增加请求/响应日志
⚠️ 超时时间可配置（当前30秒）

---

## 8. 业务流程深度分析

### 8.1 采购入库流程（波次模式）

```
阶段1: 创建采购单
  ↓ POST /api/purchase-order/create-with-wave
  ↓ 创建 purchase_order + purchase_order_item
  ↓ 创建 wave_header (direction=入库)

阶段2: 释放波次
  ↓ POST /api/wave/release
  ↓ 创建 wave_task + wave_task_detail
  ↓ 根据小车容量分配

阶段3: PDA收货
  ↓ POST /api/receiving/bind-wave
  ↓ 创建 receiving_order
  ↓ PDA扫码逐个收货

阶段4: 提交入库
  ↓ POST /api/receiving/submit
  ↓ 更新 inventory (quantity +=)
  ↓ 记录 inventory_log
```

**业务亮点**：
✅ 支持波次批量作业
✅ 小车容量智能分配
✅ 支持无来源入库

**流程改进**：
⚠️ 建议增加入库质检环节
⚠️ 建议增加异常处理流程

### 8.2 销售出库流程

```
阶段1: 创建销售单
  ↓ POST /api/sales-order/create (公开接口)
  ↓ 创建 sales_order + sales_order_item

阶段2: 生成出库波次
  ↓ POST /api/wave/outbound/create
  ↓ 创建 wave_header (direction=出库)

阶段3: 释放波次
  ↓ POST /api/wave/outbound/release
  ↓ 创建 wave_task

阶段4: PDA拣货
  ↓ POST /api/outbound/bind-wave
  ↓ 创建 outbound_order
  ↓ 记录库位变更 (outbound_order_location_log)

阶段5: 提交出库
  ↓ POST /api/outbound/submit
  ↓ 更新 inventory (quantity -=)
  ↓ 记录 inventory_log

阶段6: 创建发货单
  ↓ POST /api/shipping-order/create
  ↓ 创建 shipping_order + shipping_order_item
  ↓ 填写物流信息
```

**业务亮点**：
✅ 支持多店铺类型（拼多多、孔夫子、闲鱼）
✅ 支持分销模式
✅ 库位变更可追溯

---

## 9. 项目成熟度评估

| 维度 | 评分 | 说明 |
|------|------|------|
| 代码组织 | ⭐⭐⭐⭐ | 分层清晰，模块化好 |
| 数据库设计 | ⭐⭐⭐⭐ | 关系完整，考虑周全 |
| 安全性 | ⭐⭐⭐ | 基础安全有，需加强 |
| 性能优化 | ⭐⭐⭐ | 有优化空间，缺少缓存 |
| 测试覆盖 | ⭐⭐ | 无测试目录 |
| 文档完善 | ⭐⭐⭐⭐ | 有项目说明文档 |
| 运维部署 | ⭐⭐⭐ | 有Linux部署包 |
| 监控告警 | ⭐⭐ | 缺少监控 |

**总体评分**：⭐⭐⭐ (3/5) - 生产可用，有优化空间

---

## 10. 改进建议 roadmap

### 短期（1-2周）

- [ ] 增加单元测试框架
- [ ] API签名升级 HMAC-SHA256
- [ ] 实现速率限制中间件
- [ ] 补充核心业务索引

### 中期（1-2月）

- [ ] 引入 Redis 缓存
- [ ] 实现 Token 刷新机制
- [ ] 增加操作审计日志
- [ ] 数据库分库分表调研

### 长期（3-6月）

- [ ] 引入消息队列（异步处理）
- [ ] 实现微服务拆分
- [ ] 完善监控告警系统
- [ ] CI/CD 流程搭建

---

## 11. 技术债务清单

| 项 | 严重程度 | 说明 |
|----|---------|------|
| ES代码注释 | 低 | 已注释，清理或启用 |
| OCR代码注释 | 低 | 已注释，清理或启用 |
| 缺少测试 | 高 | 无测试目录 |
| 硬编码配置 | 中 | 部分配置硬编码 |
| 错误处理 | 中 | 需统一错误码 |
| 日志规范 | 中 | 日志格式需统一 |

---

## 12. 总结

PSI 进销存系统是一个架构清晰、功能完整的企业级应用。核心业务流程设计合理，支持波次管理、多店铺、分销等高级特性。数据库设计考虑周全，41张表覆盖了进销存全流程。

**主要优点**：
✅ 技术选型成熟稳定
✅ 分层架构清晰
✅ 业务流程完整
✅ 支持波次管理、多店铺
✅ 数据库设计规范

**主要改进方向**：
⚠️ 安全性需加强
⚠️ 性能优化空间大
⚠️ 测试覆盖不足
⚠️ 监控告警缺失
⚠️ 文档可更完善

---

**报告生成时间**：2026年6月5日
**分析工具**：Trae IDE + 人工代码审查
**报告版本**：v1.0