@@ -0,0 +1,298 @@
# 模具制造进销存核心模块分析报告（代码基线：geMoldInsight）
> 文档定位：**业务分析/审计型报告文档**。
> 本文保留一次特定分析基线下的观察结论与流程梳理，不作为当前项目状态或当前架构的权威说明。当前状态见 [../STATUS.md](../STATUS.md)，当前架构见 [../ARCHITECTURE.md](../ARCHITECTURE.md)，演进路线见 [../ROADMAP.md](../ROADMAP.md)。
## 0. 范围与术语映射
- 客户订单（Customer Order）：本仓库实现为 SalesOrder（销售订单），其业务语义更贴近“模具订单/按单生产订单”。对应表：`sales_orders` 、`sales_order_items` 。
- 物料采购订单（Purchase Order）：本仓库实现为 PurchaseOrder。对应表：`purchase_orders` 、`purchase_order_items` 。
- 物料清单（BOM）：本仓库实现为 `product_materials` （
- 成品库存：系统数据模型存在 `products.item_type="finished"` ，但库存管理接口仅面向 `item_type="material"` ，且“交付”不产生任何成品入库/出库流水；因此可视为“零成品库存”设计。
## 1. 业务流程梳理
### 1.1 端到端流程图（客户下单→交付）
``` mermaid
flowchart LR
A[客户下单\nSalesOrder: POST /api/sales-orders] --> B{BOM 是否存在?}
B -- 否 --> B1[订单创建成功\nproduction_status=bom_missing\n不扣料]
B -- 是 --> C[计算物料需求\n按 BOM×订单数量×(1+loss_rate)]
C --> D{默认仓库库存是否足够?}
D -- 否 --> D1[创建失败/回滚\n提示缺料明细]
D -- 是 --> E[创建时自动扣减物料\nInventory.quantity-=需求\nStockMovement=issue_to_production]
B1 --> F[物料需求计划\nGET /api/sales-orders/{id}/production-plan]
E --> F
F --> G[采购下单(手工)\nPurchaseOrder: POST /api/purchase-orders]
G --> H[到货入库\nPOST /api/purchase-orders/{id}/receive\nStockMovement=purchase_in]
H --> I[生产领料(可选)\nPOST /api/sales-orders/{id}/issue-materials]
I --> J[交付客户\nPATCH /api/sales-orders/{id}/status=delivered]
```
### 1.2 节点级状态、角色、输入输出、异常与回退
| 节点 | 负责角色 | 单据/状态 | 输入 | 输出 | 异常分支 | 回退机制 |
|---|---|---|---|---|---|---|
| 客户下单 | 销售/项目 | SalesOrder.status=manufacturing（创建时强制） | customer_id、成品（模具）明细、交期 | sales_orders + sales_order_items | 默认仓库未配置；BOM 存在但库存不足（创建失败） | 事务回滚；不会产生库存/流水 |
| 物料需求计算 | 计划/工艺 | production-plan | 订单明细 + BOM | 需求汇总（含 loss_rate）+ 缺口 | BOM 缺失（返回空计划） | 无（纯查询） |
| 采购申请 | 采购 | 未实现专用单据 | 需求缺口 | 采购单（手工创建） | 无 | 无 |
| 供应商采购 | 采购 | PurchaseOrder.status=draft | supplier_id + 物料行 | purchase_orders + items | 物料不是 material；
| 到货质检 | 质检 | 未实现专用质检单 | 到货信息 | 无 | 无 | 无 |
| 到货入库 | 仓库 | PurchaseOrder.status=partial_received/received | 入库仓库、入库数量 | Inventory.quantity 增加；StockMovement=purchase_in；
| 模具生产/领料 | 生产/仓库 | production_status=material_issued | 发料仓库 | Inventory.quantity 扣减；StockMovement=issue_to_production | BOM 缺失；库存不足；已自动扣料禁止重复领料 | 若后续“修改/删除订单”，会回补已扣料（return_from_production）
| 交付客户 | 销售/项目 | status=delivered | order_id | status 更新 | 状态值非法 | 无 |
关键落地差异（与“采购申请/到货质检/生产工序/交付签收”相比）：
- 采购申请、到货质检、生产工序、交付签收均未建模为独立单据；当前系统以“库存流水 + 订单状态”覆盖部分过程。
## 2. 数据模型与字段审计
### 2.1 核心表字段、主外键关系、索引概览（以 ORM 为准）
以下字段来源于 [database.py ](file:///d:/project/geMoldInsight/src/models/database.py )。
#### 客户订单（SalesOrder / 模具订单）
- 表：`sales_orders`
- PK： `id`
- 关键字段：`order_no` (unique,index)、`customer_id` (FK,index)、`status` 、`production_status` (index)、`production_no` (index)、`planned_material_cost` 、`actual_material_cost` 、`total_amount` 、`received_amount` 、`delivery_date` 、`operator_id` (FK)
- 表：`sales_order_items`
- PK： `id`
- FK： `order_id` (→sales_orders.id)、`product_id` (→products.id)
- 关键字段：`quantity` 、`delivered_quantity` 、`unit_price` 、`amount`
#### 物料清单（BOM）
- 表：`product_materials`
- PK： `id`
- FK： `finished_product_id` (→products.id,index)、`material_product_id` (→products.id,index)
- 关键字段：`quantity` 、`loss_rate`
- 约束：唯一约束 `uq_product_material_unique(finished_product_id, material_product_id)`
#### 采购订单（PurchaseOrder）
- 表：`purchase_orders`
- PK： `id`
- 关键字段：`order_no` (unique,index)、`supplier_id` (FK,index)、`status` 、`total_amount` 、`paid_amount` 、`expected_date` 、`operator_id` (FK)
- 表：`purchase_order_items`
- PK： `id`
- FK： `order_id` (→purchase_orders.id)、`product_id` (→products.id)
- 关键字段：`quantity` 、`received_quantity` 、`unit_price` 、`amount`
#### 供应商/客户主数据
- 表：`suppliers` ： `code` (unique,index)、`name` 、`is_active`
- 表：`customers` ： `code` (unique,index)、`name` 、`credit_limit`
#### 到货明细表（现状映射）
系统未实现独立“到货单/质检单”表：
- 到货数量沉淀在 `purchase_order_items.received_quantity`
- 到货批次/明细流水沉淀在 `stock_movements` （其中 `movement_type="purchase_in"` 、`reference_type="purchase_order"` ）
### 2.2 问题验证与整改清单（以代码检出为依据）
#### A. 缺失约束/索引（高优先）
- `inventory` 缺少数据库层唯一约束 `(product_id, warehouse_id)` ：接口层有重复校验，但并发下可能插入重复行。
- `purchase_order_items.order_id / product_id` 、`sales_order_items.order_id / product_id` 缺少索引：高数据量下会拖慢订单详情/联动查询。
- `stock_movements.warehouse_id` 、`stock_movements(reference_type, reference_id)` 缺少索引：对“按单追溯”与仓库流水分页不友好。
- 修复脚本：见 `scripts/db/002_indexes_and_constraints.sql` 。
#### B. 枚举值不一致（中高优先）
- `sales_orders.status` ：
- DB 默认 `draft`
- 创建/更新强制 `manufacturing`
- 发料接口可能写入 `pending` （但状态更新接口不允许 `pending` ）
- `sales_orders.production_status` ：
- DB 默认 `not_started`
- 业务中出现 `bom_missing/material_issued/completed` ，但缺少统一枚举约束
- 数据修复：`pending→manufacturing` 示例脚本见 `scripts/db/003_data_fixups.sql` 。
#### C. 金额精度风险（高优先）
- 金额/单价字段大量使用 `Float` （IEEE 754），在财务口径下会出现精度丢失与累计误差。
- 建议将以下字段迁移为 `NUMERIC(18,4)` 或 `NUMERIC(18,2)` ：
- `products.cost_price/sale_price`
- `purchase_orders.total_amount/paid_amount`
- `purchase_order_items.unit_price/amount`
- `sales_orders.planned_material_cost/actual_material_cost/total_amount/received_amount`
- `sales_order_items.unit_price/amount`
- `stock_movements.unit_price/total_amount`
#### D. 冗余字段（中优先）
- `sales_orders.received_amount` 与 `purchase_orders.paid_amount` 可能与财务分摊表（`finance_allocations` ）重复表达；若以财务分摊为准，应明确哪一方为“源数据”。
## 3. 业务规则验证（以当前实现为准）
### 3.1 新增模具订单是否自动触发物料需求计算
- 结论：会触发“物料需求计算”，并在满足条件时会进一步触发“自动扣料”。
- 证据：
- 创建销售单后调用 `_issue_materials_for_order_creation()` ，内部调用 `_build_material_plan()` 进行需求汇总，并按默认仓库扣减库存（`issue_to_production` ）。
- 需求计算考虑 `loss_rate` ；不考虑安全库存、在途量。
覆盖情况：
- 损耗率：已支持（`qty * (1 + loss_rate)` ）。
- 安全库存：未支持（`products.min_stock` 仅用于低库存查询，不参与需求计算）。
- 在途量：未支持（系统无“采购在途数量”的统一口径，需通过采购单未收数量推导，但当前逻辑未做）。
### 3.2 修改模具订单对已生成采购订单的联动策略
- 结论：当前系统不存在“客户订单↔采购订单”的显式关联，因此无法实现联动策略与版本控制。
- 现状：
- 修改销售单会回补该销售单曾扣减的物料（按 `stock_movements` 追溯），然后删除旧明细、重建明细、重新计算并扣料。
- 采购单创建完全独立，未记录来源销售单/需求行。
- 建议（整改方向）：
- 增加 `sales_order_material_demands` （需求行）并记录来源、版本号；采购单行引用需求行；修改订单时按版本触发“采购重确认”。
- 为 `sales_orders` 增加 `row_version` （int/bigint）乐观锁；更新时带版本号校验。
### 3.3 禁止对已交付模具订单进行任何字段修改（双重约束）
- 应用层：已实现（PUT/DELETE/PATCH status/issue-materials）对 `status="delivered"` 的拒绝。
- 代码位置：[sales_order_routes.py ](file:///d:/project/geMoldInsight/src/api/inventory/sales_order_routes.py )
- 数据库层（PostgreSQL）：提供触发器脚本，禁止更新/删除订单头与增删改订单明细。
- 脚本：`scripts/db/001_freeze_delivered_sales_orders.sql`
## 4. 库存与成本逻辑审查
### 4.1 库存扣减策略
- 到货入库：`purchase-orders/{id}/receive` 会实时写入 `Inventory.quantity += receive_quantity` ，并记 `StockMovement=purchase_in` 。
- 生产领料：
- 创建模具订单时，若 BOM 存在且库存充足，会实时扣减库存并记 `StockMovement=issue_to_production` 。
- 也支持按单领料接口（若未自动扣料）。
- 结论：系统是“实时更新库存现存量”，不是“到货时更新快照”。
### 4.2 成本核算方式与附加成本
- 现状：无移动加权/FIFO/标准成本核算引擎。
- 采购单明细单价强制取 `products.cost_price` ；入库流水记录 `unit_price` ，但不会更新 `products.cost_price` 的移动平均。
- 发料成本按 `products.cost_price` 估值，不含运费、关税、质检费等分摊。
- 建议：
- 增加“入库批次成本层”或“库存成本层”表以支持 FIFO/移动加权；
- 增加 `purchase_landed_costs` （关税/运费/质检费）并按行/金额比例分摊到入库批次。
### 4.3 “零成品库存”证明与对月结影响
证明要点（以代码行为为准）：
- 库存查询接口仅返回物料（`item_type=="material"` ），成品库存不在日常库存口径。
- 交付（`status=delivered` ）仅更新订单状态，不产生成品入库/出库、也没有销售出库流水。
- 系统未实现销售退货/成品出库/成品调拨等模块。
对财务月结影响（需补齐口径）：
- 目前可获得的成本数据是“发料成本（按物料成本价）”，更接近制造费用的材料消耗口径；
- 若要形成完整月结（在制/完工/成本结转），需补齐工序报工、完工入库（或完工确认）、制造费用分摊与结转规则。
## 5. 接口与集成盘点
- 对外系统集成（ERP/财务/供应商/客户门户）：当前代码未发现任何外部同步实现（无外部 HTTP client、无 webhook、无 MQ、无定时同步、无文件交换）。
- 系统对外提供接口：FastAPI REST（ `/api` 。
建议交付模板（用于后续对接）：
- 《接口清单》：接口名、协议、调用方、频率、数据量、重试/幂等键（例如 `order_no` ）。
- 《字段映射表》：源字段、目标字段、单位/币种换算、枚举映射、空值策略。
## 6. 权限与审计
### 6.1 RBAC 现状与推荐矩阵
现状：
- 仅实现“管理员 is_superuser”级别拦截；大部分写接口只要求登录。
- 数据模型已存在 Role/Permission 以及 `has_permission()` ，但未在业务路由中落地。
推荐矩阵（目标态，需用 permission_code 落地）：
| 角色 | 客户订单 | 采购订单 | 库存/流水 | 主数据(产品/客户/供应商) | 财务 | 用户/角色 |
|---|---|---|---|---|---|---|
| 销售 | C/R/U | R | R | R | R | - |
| 采购 | R | C/R/U | R | R | R | - |
| 仓库 | R | R | C/R/U | R | - | - |
| 财务 | R | R | R | R | C/R/U | - |
| 管理员 | C/R/U/D | C/R/U/D | C/R/U/D | C/R/U/D | C/R/U/D | C/R/U/D |
按“表级 CRUD”口径（用于落地 RBAC 与审计范围界定）：
| 表 | 销售 | 采购 | 仓库 | 财务 | 管理员 |
|---|---|---|---|---|---|
| customers | R | R | R | R | C/R/U/D |
| suppliers | R | R | R | R | C/R/U/D |
| products | R | R | R | R | C/R/U/D |
| product_materials | R | R | R | R | C/R/U/D |
| sales_orders / sales_order_items | C/R/U | R | R | R | C/R/U/D |
| purchase_orders / purchase_order_items | R | C/R/U | R | R | C/R/U/D |
| inventory | R | R | C/R/U | R | C/R/U/D |
| stock_movements | R | R | C/R | R | C/R/U/D |
### 6.2 RLS（行级安全）检查与建议
- 现状：订单/进销存未体现“事业部/组织”字段，数据库未启用 RLS；部分接口甚至未鉴权（与业务无关的历史记录接口）。
- 建议：
- 增加 `org_id` 字段至订单、主数据、库存等关键表；
- Postgres 层启用 RLS，并通过应用设置 `SET app.current_org_id = ...` 绑定会话变量实现隔离。
- 参考脚本：`scripts/db/011_rls_template.sql`
### 6.3 操作日志 180 天可追溯
- 现状：存在 `user_activities` 与 `system_logs` 表，但缺少统一落库策略与留存/归档脚本。
- 建议：
- 关键操作（登录、下单、收货、领料、交付、权限变更）落库记录 old/new、操作人、时间、IP、UA；
- 增加分区表或归档表，并提供 180 天归档/清理策略。
- 参考脚本：`scripts/db/020_audit_trail.sql` （依赖应用层设置会话变量 current_user_id/ip/ua）
## 7. 性能与扩展性评估（方向性建议）
### 7.1 千万级订单量分库分表（建议）
- 优先建议：先做 PostgreSQL 原生分区（比跨库路由成本低）
- 拆分键：`sales_orders.order_date` / `purchase_orders.order_date` 按月 Range 分区
- 历史迁移：`INSERT INTO ... SELECT ... WHERE order_date < ...` ，并校验行数/校验和
- 灰度切换：读写双写→读切换→写切换→下线旧表
- 若必须分库：按 `org_id + 时间` 组合路由（hash(org_id)→库，时间→表）
- 分区模板脚本：`scripts/db/010_partitioning_template.sql`
### 7.2 慢 SQL 风险点与优化脚本
- 高风险点：
- 订单详情按 order_id 读取明细、追溯库存流水、汇总库存，若缺少索引会退化为全表扫。
- BOM 需求计算需要避免 N+1（已在 `_build_material_plan` 做批量化）。
- 索引脚本：见 `scripts/db/002_indexes_and_constraints.sql` 。
### 7.3 并发下新增/修改模具订单锁冲突
风险源：
- 并发创建订单并同时扣减同一物料库存，会竞争同一 `inventory` 行。
- 并发修改订单会先回补再扣减，冲突窗口更大。
建议：
- 在扣减库存时采用“原子更新”语句：`UPDATE inventory SET quantity = quantity - :qty WHERE id=:id AND quantity >= :qty` ，并检查 affected_rows，实现乐观并发控制；
- 或引入 `row_version` （乐观锁）到 inventory/sales_orders。
## 8. 测试与验收标准（仓库内已落地的最小集合）
- 已新增接口自动化用例（示例，覆盖“交付后冻结”核心规则）：
- `tests/test_sales_order_delivered_freeze.py`
- `tests/test_api_inventory_orders.py` （参数化用例，覆盖正常/异常/边界/幂等与约束）
- 建议在 CI 中运行：
- `pytest -q`
- 将 `scripts/db/*.sql` 纳入数据库初始化后的约束/索引校验步骤
## 9. 交付物结构建议
- 报告（建议以 Markdown→Word/PDF 转换）
- `docs/MOLD_ERP_ANALYSIS_REPORT.md`
- `docs/UAT_CHECKLIST.md`
- `docs/INTERFACE_INTEGRATION_CATALOG_TEMPLATE.md`
- `docs/CONFLUENCE_ARCHIVE_STRUCTURE.md`
- 可执行脚本
- `scripts/db/001_freeze_delivered_sales_orders.sql`
- `scripts/db/002_indexes_and_constraints.sql`
- `scripts/db/003_data_fixups.sql`
- `scripts/db/010_partitioning_template.sql`
- `scripts/db/011_rls_template.sql`
- `scripts/db/020_audit_trail.sql`
如需输出 Word+PDF，可使用 pandoc 将本报告导出为 `.docx` 与 `.pdf` ，并将生成物纳入 CI 产物归档。
