feat: red flush

docs/2026-06-12_business_red_flush_api.md

@@ -0,0 +1,75 @@
+# Business Red-Flush API
+
+## Scope
+
+Approved internal business orders can be red-flushed through dedicated endpoints. The first version supports whole-order red flush only.
+
+External-source data must not participate in red flush. If an order has `is_external_source=true` or a non-empty `external_source_id`, the service rejects the red-flush operation even when the API request is otherwise valid.
+
+## Endpoints
+
+All endpoints require authentication and reuse the existing business order review/cancel employee permission checks.
+
+| Order type | Method | Path |
+| --- | --- | --- |
+| Purchase order | POST | `/api/v1/purchase-orders/{id}/red-flush/` |
+| Sales order | POST | `/api/v1/sales-orders/{id}/red-flush/` |
+| Purchase return order | POST | `/api/v1/purchase-return-orders/{id}/red-flush/` |
+| Sales return order | POST | `/api/v1/sales-return-orders/{id}/red-flush/` |
+| Payment order | POST | `/api/v1/payment-orders/{id}/red-flush/` |
+| Receipt order | POST | `/api/v1/receipt-orders/{id}/red-flush/` |
+
+## Request Body
+
+```json
+{
+  "reason": "录入错误，需要红冲"
+}
+```
+
+`reason` is required and cannot be blank at the API layer.
+
+## Success Response
+
+Returns the refreshed order serializer with HTTP 200.
+
+Important red-flush fields included in responses:
+
+| Field | Description |
+| --- | --- |
+| `is_red_flushed` | Whether the source order has been red-flushed |
+| `red_flush_id` | UUID audit batch ID for this red flush |
+| `red_flushed_at` | Timestamp when the source order was marked red-flushed |
+
+Example:
+
+```json
+{
+  "id": 123,
+  "status": 2,
+  "is_red_flushed": true,
+  "red_flush_id": "1c8e4c7a-6f2a-4d6b-8f8e-674a2d6b67f4",
+  "red_flushed_at": "2026-06-12T10:00:00Z"
+}
+```
+
+The source order `status` remains approved after red flush.
+
+## Error Responses
+
+| Condition | Status | Response shape |
+| --- | --- | --- |
+| Missing or blank `reason` | 400 | DRF serializer error, keyed by `reason` |
+| Order not found in current merchant | 404 | Existing API not-found response |
+| Order is not approved | 400 | `{ "error": "..." }` |
+| Order already red-flushed | 400 | `{ "error": "..." }` |
+| Order is external-source data | 400 | `{ "error": "外部来源...不允许红冲" }` |
+| Service validation failure | 400 | `{ "error": "..." }` |
+
+## Merchant Safety
+
+The API first scopes order lookup by `request.user.employee.merchant`. The service layer also requires `merchant` and verifies that the order belongs to that merchant.
+
+## Audit Notes
+
+`red_flush_id` is written to the source order, related `BalanceChangeRecord` rows, and related `StockChangeRecord` rows when inventory is involved. Existing `offset_to`/`offset_id` relationships remain the precise reverse-link mechanism for balance and stock records.

docs/2026-06-12_business_red_flush_design.md

@@ -0,0 +1,159 @@
+# Business 单据红冲服务设计备查
+
+日期：2026-06-12
+
+## 目标
+
+在 `business` 模块为已审核正式单据增加整单红冲能力。第一阶段只实现 service 和测试，不新增 API。
+
+## 已确认口径
+
+- 红冲后原单据 `status` 保持 `APPROVED`，不回退、不作废。
+- 原单据增加“已红冲”标记，用于列表查询提速。
+- 每次红冲由 service 自动生成一个 UUID 类型的 `red_flush_id`。
+- `red_flush_id` 用于跨表、跨记录追踪同一次红冲涉及的所有数据，是审计关联批次 ID。
+- 不新增 `red_flush_no`。该编号只适合人工展示，目前无需求。
+- 第一版只支持整单红冲，不支持部分红冲。
+- API 在 service 与测试完成、覆盖率达标后再增加；API 层红冲原因必填。
+- API 权限复用现有审批/作废权限，不新增独立红冲权限。
+- 多商户隔离必须下沉到 service。红冲 service 调用方必须传入当前 `merchant`，service 在解析单据后校验单据所属商户。
+
+## 字段方案
+
+6 类正式业务单据增加：
+
+- `is_red_flushed`: 是否已红冲，布尔值，建索引。
+- `red_flush_id`: 红冲批次 UUID，可空，建索引。
+- `red_flushed_at`: 红冲时间，可空。
+
+覆盖单据：
+
+- `PurchaseOrder`
+- `SalesOrder`
+- `PurchaseReturnOrder`
+- `SalesReturnOrder`
+- `PaymentOrder`
+- `ReceiptOrder`
+
+`BalanceChangeRecord` 增加：
+
+- `red_flush_id`: 红冲批次 UUID，可空，建索引。
+
+`StockChangeRecord` 增加：
+
+- `red_flush_id`: 红冲批次 UUID，可空，建索引。
+
+暂不在 `StockSnapshot` 增加 `red_flush_id`，因为快照已有 `offset_to/offset_id/cancelled` 精确匹配关系，且可以通过 `StockChangeRecord.red_flush_id` 查到相关快照。
+
+## 关系标记规则
+
+一次红冲生成一个 `red_flush_id`，并在同一个事务中写入相关数据。
+
+原业务单据：
+
+- `is_red_flushed=True`
+- `red_flush_id=<本次 UUID>`
+- `red_flushed_at=<当前时间>`
+
+原余额变动记录：
+
+- `cancelled=True`
+- `cancelled_at=<当前时间>`
+- `offset_id=<反向余额记录 ID>`
+- `red_flush_id=<本次 UUID>`
+
+反向余额变动记录：
+
+- `offset_to=<原余额记录 ID>`
+- `offset_at=<当前时间>`
+- `red_flush_id=<本次 UUID>`
+
+原库存记录：
+
+- `red_flush_id=<本次 UUID>`
+
+反向库存记录：
+
+- `source_type=OFFSET`
+- `source_id=<原库存记录 ID>`
+- `red_flush_id=<本次 UUID>`
+
+库存快照继续复用现有关系：
+
+- 原快照：`cancelled=True`、`cancelled_at`、`offset_id=<反向快照 ID>`
+- 反向快照：`offset_to=<原快照 ID>`、`offset_at`
+
+## Service 方案
+
+新增业务红冲入口：
+
+- `red_flush_purchase_order(...)`
+- `red_flush_sales_order(...)`
+- `red_flush_purchase_return_order(...)`
+- `red_flush_sales_return_order(...)`
+- `red_flush_payment_order(...)`
+- `red_flush_receipt_order(...)`
+
+内部复用统一实现，避免 6 类单据逻辑分叉。
+
+校验规则：
+
+- 必须提供当前 `merchant`。
+- 单据必须属于当前 `merchant`。
+- 只允许 `APPROVED` 单据红冲。
+- `is_red_flushed=True` 的单据不能重复红冲。
+- 原始余额变动记录必须存在且未被冲抵。
+- 有库存影响的单据必须找到对应库存记录，库存记录必须已完成且未被红冲。
+- 资金和库存任一红冲失败，整体事务回滚。
+
+资金侧实现：
+
+- 基于原 `BalanceChangeRecord.delta` 创建反向余额变动，`delta=-original.delta`。
+- 使用现有 `BalanceService.adjust_supplier_balance()` / `adjust_customer_balance()` 写余额与记录。
+- 调整 `BalanceService` 让它返回新创建的 `BalanceChangeRecord`，方便写 `offset_to/offset_id/red_flush_id`。
+
+库存侧实现：
+
+- 复用 `StockFlowService.offset_stock_change()`。
+- 扩展其参数 `red_flush_id=None`。
+- 该方法负责把 `red_flush_id` 写入原库存记录和反向库存记录。
+
+## 测试要求
+
+先跑现有 `business.tests` baseline。
+
+新增 service 测试覆盖：
+
+- 采购单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
+- 销售单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
+- 采购退货单整单红冲。
+- 销售退货单整单红冲。
+- 付款单整单红冲。
+- 收款单整单红冲。
+- 非已审核单据不能红冲。
+- 已红冲单据不能重复红冲。
+- 缺少原始余额记录时报错。
+- 库存记录未完成或已红冲时报错。
+- 事务回滚场景。
+
+目标：`business` 模块覆盖率 90%+。
+
+## 测试命令
+
+开发环境在容器内运行测试，并绕过 PgBouncer：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web \
+  uv run python manage.py test business.tests --keepdb --noinput
+```
+
+覆盖率：
+
+```bash
+docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web \
+  uv run coverage run --source=business manage.py test business.tests --keepdb --noinput
+```
+
+```bash
+docker compose exec -T web uv run coverage report -m
+```

docs/2026-06-12_business_reverse_audit.md

@@ -0,0 +1,158 @@
+# Business 模块已审核单据反向能力审计
+
+审计日期：2026-06-12
+
+## 结论
+
+`business` 模块的正式单据在 `status = APPROVED` 后，没有发现可将原单据改回审批中、撤销审核、反审或直接红冲原单据的 service/API。
+
+已审核单据不能作废这一点由统一作废逻辑实现：`_cancel_order_impl()` 在目标单据已审批时直接抛错。
+
+但存在“通过新单据抵消业务影响”的能力：
+
+- 采购单、销售单：可通过新建并审核采购退货单/销售退货单形成库存和应收/应付反向影响。
+- 付款单、收款单：创建时允许负金额，用于退款场景，审核后形成与正向付款/收款相反的余额影响。
+- 余额变动记录模型有冲抵字段，但当前 service 未使用，未形成可调用的冲抵能力。
+
+## 审计范围
+
+核心文件：
+
+- `business/services.py`
+- `business/models.py`
+- `api_v1/views/business/*/views.py`
+
+正式单据类型：
+
+- 采购单 `PurchaseOrder`
+- 销售单 `SalesOrder`
+- 采购退货单 `PurchaseReturnOrder`
+- 销售退货单 `SalesReturnOrder`
+- 付款单 `PaymentOrder`
+- 收款单 `ReceiptOrder`
+
+## 已审核后禁止作废
+
+所有正式单据的作废最终进入 `business/services.py::_cancel_order_impl()`：
+
+```python
+if locked.status == approved_status:
+    raise ValueError(f'已审批的{error_label}无法作废')
+```
+
+覆盖的入口：
+
+- `review_purchase_order(..., target_status=CANCELLED)`
+- `review_sales_order(..., target_status=CANCELLED)`
+- `review_purchase_return_order(..., target_status=CANCELLED)`
+- `review_sales_return_order(..., target_status=CANCELLED)`
+- `review_payment_order(..., target_status=CANCELLED)`
+- `review_receipt_order(..., target_status=CANCELLED)`
+
+API 层只暴露 `approve` 和 `cancel` 两类 action，没有发现 `unapprove`、`reverse`、`red_flush` 等动作。
+
+## 已审核后的反向能力
+
+| 原单据 | 是否可直接撤销/反审 | 是否有业务反向单据 | 说明 |
+| --- | --- | --- | --- |
+| 采购单 | 否 | 有，采购退货单 | 采购退货单审核后出库，并减少供应商应付。 |
+| 销售单 | 否 | 有，销售退货单 | 销售退货单审核后入库，并减少客户应收。 |
+| 采购退货单 | 否 | 未发现专用反向单据 | 只能再做新的采购单产生正向影响。 |
+| 销售退货单 | 否 | 未发现专用反向单据 | 只能再做新的销售单产生正向影响。 |
+| 付款单 | 否 | 无专用反向单据，但允许负金额 | `create_payment_order()` 允许 `amount < 0`，注释说明为供应商退款。 |
+| 收款单 | 否 | 无专用反向单据，但允许负金额 | `create_receipt_order()` 允许 `amount < 0`，注释说明为退款给客户。 |
+
+## 采购/销售退货单细节
+
+`create_purchase_return_order()` 可传 `purchase_order` 或 `purchase_order_id` 关联原采购单。
+
+当前校验：
+
+- 原采购单存在且属于当前商户。
+- 原采购单供应商必须与退货单供应商一致。
+
+当前未校验：
+
+- 原采购单必须是 `APPROVED`。
+- 退货数量不能超过原采购单数量。
+- 同一原采购单累计退货数量不能超过原单数量。
+
+`create_sales_return_order()` 可传 `sales_order` 或 `sales_order_id` 关联原销售单。
+
+当前校验：
+
+- 原销售单存在且属于当前商户。
+- 原销售单客户必须与退货单客户一致。
+
+当前未校验：
+
+- 原销售单必须是 `APPROVED`。
+- 退货数量不能超过原销售单数量。
+- 同一原销售单累计退货数量不能超过原单数量。
+
+因此，退货单属于“新单据反向业务影响”，不是“撤销原单据”；它不会改变原采购单/销售单的 `status`，也不会标记原单已被红冲。
+
+## 付款/收款负金额细节
+
+`_ensure_non_zero_amount()` 只禁止金额为 0，不禁止负数，并有明确注释：
+
+```python
+# 金额类字段要求非零（允许负数用于处理退款场景）
+# 付款单负金额 = 供应商退款，收款单负金额 = 退款给客户
+```
+
+影响：
+
+- 负数付款单审核后，`review_payment_order()` 使用 `delta=-locked.settlement_amount`，当 `settlement_amount < 0` 时会增加供应商应付余额。
+- 负数收款单审核后，`review_receipt_order()` 使用 `delta=-locked.settlement_amount`，当 `settlement_amount < 0` 时会增加客户应收余额。
+
+这是一种资金侧反向能力，但没有和原付款/收款单建立关联，也没有把原单据标记为红冲或冲销。
+
+## 余额冲抵字段
+
+`BalanceChangeRecord` 存在以下字段：
+
+- `offset_to`
+- `offset_at`
+- `offset_id`
+- `cancelled`
+- `cancelled_at`
+
+但代码搜索只发现模型定义和创建余额变动记录，未发现 service/API 更新这些字段。因此当前没有可用的余额变动冲抵流程。
+
+## API 暴露情况
+
+`api_v1/views/business/*/views.py` 的审核接口统一只接受：
+
+```python
+action = approve | cancel
+```
+
+对应模块：
+
+- `purchase/views.py`
+- `sales/views.py`
+- `purchase_return/views.py`
+- `sales_return/views.py`
+- `payment/views.py`
+- `receipt/views.py`
+
+未发现 API 层绕过 service 暴露已审核撤销、反审或红冲原单的能力。
+
+## 风险点
+
+1. 退货单可作为采购单/销售单的反向能力，但当前不要求原单已审核。
+2. 退货单未限制数量，可能产生超原单退货或重复累计退货。
+3. 负金额付款/收款具备资金反向效果，但没有原单关联，后续对账只能从业务含义判断，不能从数据结构追溯到被冲销单据。
+4. `BalanceChangeRecord` 的冲抵字段未被 service 使用，容易让维护者误以为已有冲抵流程。
+
+## 建议
+
+如果业务需求只是确认“已审核后是否有撤销/红冲能力”，当前答案是：没有直接撤销/反审/红冲原单的能力；有通过新单据产生反向影响的能力。
+
+如果要把退货单作为正式红冲/撤销路径，建议补充：
+
+- 原单必须 `APPROVED`。
+- 按产品、颜色、规格、批次等维度限制退货数量。
+- 校验同一原单累计已审核退货数量。
+- 在退货单或余额变动记录中明确记录冲销关系。

docs/plant/business-function-architecture-simple.puml

@@ -0,0 +1,55 @@
+@startuml
+title Flower ERP 业务功能架构简图
+
+skinparam shadowing false
+skinparam defaultFontName Noto Sans CJK SC
+skinparam backgroundColor #FFFFFF
+skinparam ArrowColor #5B6472
+skinparam ArrowThickness 1.3
+skinparam componentStyle rectangle
+skinparam rectangle {
+  FontName Noto Sans CJK SC
+  BorderColor #516174
+  RoundCorner 8
+}
+skinparam package {
+  FontName Noto Sans CJK SC
+  BorderColor #516174
+  BackgroundColor #F8FAFC
+}
+
+top to bottom direction
+
+rectangle "外部系统与前端入口\n明道云 / 好布业财务 / 企业微信 / 管理后台 / 移动端" as Entry #F5F7FA
+
+rectangle "Flower ERP 业务平台" as Platform #EAF3FF {
+  rectangle "基础资料中心\n商户、客户、供应商、产品、仓库、员工、车辆" as MasterData #FFFFFF
+
+  rectangle "业务经营中心\n采购、销售、退货、预订单、收付款、往来余额" as Business #F2F8FF
+
+  rectangle "生产履约中心\n开版、印花订单、工序推进、MES 设备指派" as Production #FFF8EF
+
+  rectangle "库存物流中心\n出入库、库存台账、销售品、出货单、送货单" as StockLogistics #F7FBF4
+
+  rectangle "协同运营中心\n流程引擎、任务协同、通知中心、费用、日结" as Collaboration #F8F5FF
+}
+
+rectangle "运行与数据支撑\n异步任务、文件图片、审计日志、外部同步" as Support #F5F7FA
+
+Entry --> Platform : 业务录入 / 外部同步 / 消息触达
+MasterData --> Business : 基础资料支撑经营单据
+Business --> Production : 销售需求驱动生产履约
+Production --> StockLogistics : 生产成果进入发货履约
+Business --> StockLogistics : 采购销售触发库存变化
+Business --> Collaboration : 审批、对账、统计与提醒
+Production --> Collaboration : 流程推进与任务协同
+StockLogistics --> Collaboration : 发货通知与物流跟进
+Platform --> Support : 定时、异步、图片、审计支撑
+
+note right of Platform
+  汇报口径：
+  展示业务能力版图与主链路，
+  不展开具体技术实现。
+end note
+
+@enduml

docs/plant/business-function-architecture.puml

@@ -0,0 +1,137 @@
+@startuml
+title Flower ERP 业务功能架构图
+
+skinparam shadowing false
+skinparam defaultFontName Noto Sans CJK SC
+skinparam backgroundColor #FFFFFF
+skinparam ArrowColor #5B6472
+skinparam ArrowThickness 1.2
+skinparam componentStyle rectangle
+skinparam rectangle {
+  FontName Noto Sans CJK SC
+  BorderColor #516174
+  RoundCorner 8
+}
+skinparam package {
+  FontName Noto Sans CJK SC
+  BorderColor #516174
+  BackgroundColor #F8FAFC
+}
+skinparam note {
+  FontName Noto Sans CJK SC
+  BackgroundColor #FFF7E6
+  BorderColor #B7791F
+}
+
+left to right direction
+
+rectangle "Flower ERP 业务平台" as Platform #EAF3FF {
+
+  package "基础资料中心" as MasterData #F6F8FB {
+    rectangle "商户 / 客户 / 供应商" as MDParty #FFFFFF
+    rectangle "产品 / 品类 / 仓库" as MDProduct #FFFFFF
+    rectangle "员工 / 角色 / 可见页面" as MDStaff #FFFFFF
+    rectangle "车辆 / 银行账户 / 快捷输入" as MDOther #FFFFFF
+  }
+
+  package "业务经营中心" as Business #F2F8FF {
+    rectangle "采购管理\n采购单 / 采购退货" as Purchase #FFFFFF
+    rectangle "销售管理\n预销售 / 销售单 / 销售退货" as Sales #FFFFFF
+    rectangle "资金往来\n付款单 / 收款单" as Cash #FFFFFF
+    rectangle "往来余额\n客户应收 / 供应商应付 / 余额流水" as Balance #FFFFFF
+    rectangle "外部对账\n好布业财务同步" as ExternalFinance #FFFFFF
+  }
+
+  package "库存物流中心" as StockLogistics #F7FBF4 {
+    rectangle "库存管理\n现存量 / 库存快照" as Inventory #FFFFFF
+    rectangle "出入库执行\n入库 / 出库 / 调拨 / 红冲" as StockFlow #FFFFFF
+    rectangle "销售品管理\n待分配销售品 / 合卷 / 重建" as SalesItem #FFFFFF
+    rectangle "发货管理\n出货单 / 送货单 / 送达照片" as Shipment #FFFFFF
+  }
+
+  package "生产履约中心" as Production #FFF8EF {
+    rectangle "开版管理\n开版订单 / 样品 / 客户反馈" as PlateOrder #FFFFFF
+    rectangle "印花订单\n生产订单 / 款式明细" as PrintingOrder #FFFFFF
+    rectangle "工序推进\n批量推进 / 工艺参数 / 进度" as ProcessAdvance #FFFFFF
+    rectangle "MES 生产指派\n设备 / 产能 / 指派状态" as MES #FFFFFF
+  }
+
+  package "协同运营中心" as Collaboration #F8F5FF {
+    rectangle "流程引擎\n流程 / 节点 / 状态记录" as Stateflow #FFFFFF
+    rectangle "任务协同\n任务 / 参与者 / 回复 / 完成" as Mission #FFFFFF
+    rectangle "通知中心\n事件路由 / 模板 / 企业微信" as Notifier #FFFFFF
+    rectangle "费用与日结\n支出记账 / 成本汇总 / 日结配置" as CostSettlement #FFFFFF
+  }
+
+  package "对外能力与运行支撑" as Integration #F5F7FA {
+    rectangle "API 入口\n移动端 / 前端 / 管理后台" as API #FFFFFF
+    rectangle "文件与图片\n七牛云 / 上传 / 图片检索" as FileImage #FFFFFF
+    rectangle "外部系统同步\n明道云 / 外部生产订单 / TIIA" as ExternalSync #FFFFFF
+    rectangle "异步任务\n同步 / 通知 / 审计 / 定时任务" as AsyncJobs #FFFFFF
+  }
+}
+
+API --> MasterData : 基础资料维护
+API --> Business : 单据录入与审批
+API --> Production : 生产过程操作
+API --> StockLogistics : 库存与发货操作
+API --> Collaboration : 协同与统计查询
+
+MasterData --> Business : 客户、供应商、产品、仓库、员工
+MasterData --> Production : 客户、产品、员工、设备基础
+MasterData --> StockLogistics : 产品、仓库、客户、车辆
+MasterData --> Collaboration : 商户、员工、权限范围
+
+Purchase --> StockFlow : 审批后触发入库/退货出库
+Sales --> StockFlow : 销售出库/销退入库
+Purchase --> Balance : 形成供应商应付
+Sales --> Balance : 形成客户应收
+Cash --> Balance : 收付款冲减余额
+ExternalFinance --> Cash : 外部收付款同步
+ExternalFinance --> Balance : 对账依据补充
+
+PlateOrder --> Stateflow : 开版流程跟踪
+PrintingOrder --> Stateflow : 印花任务工序流转
+PrintingOrder --> ProcessAdvance : 批量推进生产节点
+PrintingOrder --> SalesItem : 生产明细生成可发货销售品
+MES --> PrintingOrder : 生产对象指派到设备
+
+Inventory <-- StockFlow : 更新库存台账
+StockFlow --> Inventory : 形成库存快照
+SalesItem --> Shipment : 组建出货单
+Shipment --> Notifier : 出货事件通知
+
+Mission --> Notifier : 任务事件通知
+Mission --> Production : 关联开版/印花对象
+Mission --> Shipment : 关联发货对象
+CostSettlement --> Production : 采集生产相关成本
+CostSettlement --> StockLogistics : 采集库存/物流相关成本
+CostSettlement --> Notifier : 日结结果通知
+
+ExternalSync --> MasterData : 同步产品、客户
+ExternalSync --> PlateOrder : 明道云开版暂存/导入
+ExternalSync --> PrintingOrder : 外部生产订单快照
+ExternalSync --> FileImage : 图片上传与 TIIA 检索
+FileImage --> PlateOrder : 开版图与图库
+FileImage --> PrintingOrder : 产品图片
+AsyncJobs --> ExternalSync : 定时同步
+AsyncJobs --> Notifier : 异步投递
+AsyncJobs --> StockFlow : 异步生成库存记录
+AsyncJobs --> CostSettlement : 定时日结
+
+note top of Platform
+  本图用于向上汇报，表达业务能力版图与模块协作关系；
+  不展示数据库、容器、框架等技术实现细节。
+end note
+
+note right of Business
+  经营闭环：
+  单据审批 -> 库存变化 -> 往来余额 -> 收付款/对账。
+end note
+
+note bottom of Production
+  履约闭环：
+  开版 -> 印花生产 -> 工序推进 -> 销售品 -> 发货。
+end note
+
+@enduml

docs/plant/business-module-object-catalog.puml

@@ -0,0 +1,146 @@
+@startuml
+title Flower ERP 模块功能对象图（目录版）
+
+skinparam shadowing false
+skinparam defaultFontName Noto Sans CJK SC
+skinparam backgroundColor #FFFFFF
+skinparam object {
+  FontName Noto Sans CJK SC
+  BackgroundColor #FFFFFF
+  BorderColor #4B5563
+}
+skinparam package {
+  FontName Noto Sans CJK SC
+  BorderColor #64748B
+  BackgroundColor #F8FAFC
+}
+
+left to right direction
+
+package "入口与主数据" as P1 #F6F8FB {
+  object "API / Admin" as ApiEntry {
+    api/backend 基础资料后台
+    api/v1 核心业务接口
+    api/v2 新版业务接口
+    admin 管理后台
+    auth 登录与员工身份
+    SSE 实时推送
+  }
+
+  object "basic_info" as BasicInfo {
+    商户 / 多租户
+    客户 / 供应商
+    产品 / 品类 / 仓库
+    员工 / 角色 / 页面权限
+    车辆 / 银行账户 / 快捷输入
+  }
+}
+
+package "经营与库存" as P2 #F2F8FF {
+  object "business" as Business {
+    采购 / 采购退货
+    销售 / 销售退货
+    预销售 / 预采购
+    收款 / 付款
+    客户应收 / 供应商应付
+    余额流水 / 对账 / 红冲
+  }
+
+  object "stock" as Stock {
+    出入库记录
+    出入库明细
+    库存现存量
+    库存快照
+    库存冻结
+    调拨 / 红冲 / 冲抵
+  }
+
+  object "cost" as Cost {
+    支出类目
+    支出明细
+    凭证图片
+    成本汇总
+    成本采集端口
+  }
+}
+
+package "生产与交付" as P3 #FFF8EF {
+  object "printing" as Printing {
+    开版订单
+    开版图 / 样品 / 客户反馈
+    印花订单
+    印花款式明细
+    工序批量推进
+    外部订单快照
+    生产完成通知
+  }
+
+  object "stateflow" as Stateflow {
+    状态参数
+    流程模板
+    流程节点
+    业务对象
+    流转记录
+    节点参数记录
+  }
+
+  object "mes" as MES {
+    设备分类
+    设备管理
+    产能信息
+    生产指派
+    指派状态流转
+  }
+
+  object "shipment" as Shipment {
+    销售品
+    出货单
+    送货单
+    送达照片
+    销售品变更 / 重建
+    外部成品表
+  }
+}
+
+package "协同与集成" as P4 #F8F5FF {
+  object "mission" as Mission {
+    任务分类
+    任务
+    参与者
+    回复
+    完成 / 重开 / 取消
+    关联任意业务对象
+  }
+
+  object "notifier" as Notifier {
+    通知器
+    通知路由
+    事件匹配
+    模板渲染
+    企业微信 webhook
+    message_api
+    未回复提醒
+  }
+
+  object "settlement" as Settlement {
+    日结配置
+    统计模块选择
+    通知渠道配置
+    商户日结任务
+  }
+
+  object "外部与异步支撑" as Support {
+    明道云同步
+    好布业财务同步
+    腾讯云 TIIA
+    七牛云文件图片
+    Celery 定时与异步任务
+    API 审计日志
+  }
+}
+
+P1 -[hidden]right- P2
+P2 -[hidden]right- P3
+P3 -[hidden]right- P4
+
+@enduml

docs/plant/business-module-object-map.puml

@@ -0,0 +1,227 @@
+@startuml
+title Flower ERP 模块功能对象图
+
+skinparam shadowing false
+skinparam defaultFontName Noto Sans CJK SC
+skinparam backgroundColor #FFFFFF
+skinparam ArrowColor #6B7280
+skinparam ArrowThickness 1
+skinparam object {
+  FontName Noto Sans CJK SC
+  BackgroundColor #FFFFFF
+  BorderColor #4B5563
+}
+skinparam package {
+  FontName Noto Sans CJK SC
+  BorderColor #64748B
+  BackgroundColor #F8FAFC
+}
+skinparam note {
+  FontName Noto Sans CJK SC
+  BackgroundColor #FFF7E6
+  BorderColor #B7791F
+}
+
+left to right direction
+
+package "访问入口层" as EntryLayer #F5F7FA {
+  object "API / Admin\n访问入口" as ApiEntry {
+    api/backend: 基础资料后台接口
+    api/v1: 核心业务接口
+    api/v2: 新版业务接口
+    admin: 管理后台
+    auth: 登录与员工身份校验
+  }
+
+  object "SSE\n实时通道" as SSE {
+    事件推送
+    连接状态
+    测试推送
+  }
+}
+
+package "基础资料层" as MasterLayer #F6F8FB {
+  object "basic_info\n基础资料" as BasicInfo {
+    商户 / 多租户
+    客户 / 供应商
+    产品 / 品类
+    仓库 / 仓库模式
+    员工 / 员工类型 / 用户档案
+    前端页面权限
+    车辆 / 车次 / 银行账户
+    快捷输入 / 商户设置
+  }
+
+  object "api_man\n后台资料接口" as ApiMan {
+    产品维护
+    仓库维护
+    客户维护
+    供应商维护
+    员工维护
+    车辆与账户维护
+  }
+}
+
+package "经营单据层" as BusinessLayer #F2F8FF {
+  object "business\n业务单据" as Business {
+    采购单 / 采购退货单
+    销售单 / 销售退货单
+    预销售单 / 预采购单
+    收款单 / 付款单
+    客户应收 / 供应商应付
+    余额变动流水
+    客户对账单
+    红冲 / 作废 / 审批
+  }
+
+  object "stock\n库存管理" as Stock {
+    出入库记录
+    出入库明细
+    库存现存量
+    库存快照
+    库存冻结
+    调拨单
+    红冲 / 冲抵
+    严谨 / 宽进宽出 / 严进严出
+  }
+
+  object "cost\n成本费用" as Cost {
+    支出类目
+    支出明细
+    凭证图片
+    按类目汇总
+    成本采集端口
+  }
+}
+
+package "生产履约层" as ProductionLayer #FFF8EF {
+  object "printing\n开版与印花" as Printing {
+    开版订单
+    开版图 / 样品 / 客户反馈
+    印花订单
+    印花款式明细
+    工序批量推进
+    工艺参数补充
+    外部订单快照同步
+    生产完成通知
+  }
+
+  object "stateflow\n流程引擎" as Stateflow {
+    状态参数
+    状态节点
+    流程模板
+    流程节点
+    业务对象
+    流转记录
+    节点参数记录
+  }
+
+  object "mes\nMES 生产指派" as MES {
+    设备分类
+    设备管理
+    峰值产能
+    生产指派
+    指派状态流转
+    指派对象关联
+  }
+}
+
+package "物流交付层" as DeliveryLayer #F7FBF4 {
+  object "shipment\n发货交付" as Shipment {
+    销售品
+    销售品变更记录
+    销售品重建记录
+    出货单
+    送货单
+    送达照片
+    外部成品表
+    出货状态流转
+  }
+}
+
+package "协同运营层" as OperationLayer #F8F5FF {
+  object "mission\n任务协同" as Mission {
+    任务分类
+    任务
+    任务参与者
+    任务回复
+    任务完成 / 重开 / 取消
+    回复驳回
+    关联任意业务对象
+  }
+
+  object "notifier\n通知中心" as Notifier {
+    通知器
+    通知路由
+    事件匹配
+    模板渲染
+    企业微信 webhook
+    message_api 渠道
+    未回复任务提醒
+  }
+
+  object "settlement\n日结统计" as Settlement {
+    日结配置
+    统计模块选择
+    通知渠道配置
+    商户日结任务
+    开版 / 印花日结口径
+  }
+}
+
+package "集成与支撑层" as SupportLayer #F5F7FA {
+  object "api_v1.tasks\n异步与同步任务" as Tasks {
+    数据库备份
+    明道云产品同步
+    明道云客户同步
+    明道云开版暂存同步
+    外部印花订单同步
+    外部图片回填
+    腾讯云 TIIA 上传
+    API 审计日志写入
+  }
+
+  object "business.tasks\n经营异步任务" as BusinessTasks {
+    采购审批后入库
+    销售审批后出库
+    退货审批后出入库
+    好布业财务定时同步
+  }
+
+  object "外部服务" as ExternalSystems {
+    明道云
+    好布业财务系统
+    腾讯云 TIIA
+    七牛云存储
+    企业微信 / message_api
+  }
+}
+
+ApiEntry ..> BasicInfo
+ApiEntry ..> Business
+ApiEntry ..> Printing
+ApiEntry ..> Shipment
+ApiEntry ..> Mission
+ApiEntry ..> MES
+ApiEntry ..> Cost
+
+ApiMan ..> BasicInfo
+Business ..> Stock
+Business ..> BusinessTasks
+Printing ..> Stateflow
+Printing ..> Shipment
+MES ..> Printing
+Shipment ..> Notifier
+Mission ..> Notifier
+Settlement ..> Notifier
+Tasks ..> ExternalSystems
+BusinessTasks ..> ExternalSystems
+Tasks ..> BasicInfo
+Tasks ..> Printing
+
+note bottom
+  读图方式：每个对象代表一个业务模块，内部列出主要功能。
+  虚线只保留关键依赖，避免把图变成技术调用链。
+end note
+
+@enduml