617 lines
16 KiB
Markdown
617 lines
16 KiB
Markdown
# 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
|