fix: docs

2026-06-13 11:44:15 +08:00
parent 0bcaa2db44
commit 9a1c92febf
10 changed files with 195 additions and 57 deletions
--- a/docs/2026-06-12_business_red_flush_api.md
+++ b/docs/2026-06-12_business_red_flush_api.md
@@ -73,3 +73,16 @@ The API first scopes order lookup by `request.user.employee.merchant`. The servi
 ## 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.
+
+## Test Coverage
+
+The dedicated regression suite is:
+
+```bash
+python manage.py test business.tests.test_red_flush_services api_v1.tests.BusinessRedFlushAPITestCase --settings=flower.settings_test
+```
+
+Coverage expectations:
+
+- Service tests cover all six order types, balance reversal, inventory reversal, duplicate blocking, merchant isolation, missing balance/stock records, transaction rollback, and external payment/receipt rejection.
+- API tests cover all six endpoints, required `reason`, employee permission rejection, merchant-scoped 404, non-approved orders, duplicate red flush, external payment/receipt rejection, stock-validation error mapping, and sampled balance/stock side effects.
--- a/docs/2026-06-12_business_red_flush_design.md
+++ b/docs/2026-06-12_business_red_flush_design.md
@@ -4,7 +4,7 @@

 ## 目标

-在 `business` 模块为已审核正式单据增加整单红冲能力。第一阶段只实现 service 和测试，不新增 API。
+在 `business` 模块为已审核正式单据增加整单红冲能力，并通过独立 API 对外开放。

 ## 已确认口径

@@ -14,7 +14,7 @@
 - `red_flush_id` 用于跨表、跨记录追踪同一次红冲涉及的所有数据，是审计关联批次 ID。
 - 不新增 `red_flush_no`。该编号只适合人工展示，目前无需求。
 - 第一版只支持整单红冲，不支持部分红冲。
- API 在 service 与测试完成、覆盖率达标后再增加；API 层红冲原因必填。
+- API 已开放独立 `/red-flush/` action，API 层红冲原因必填。
 - API 权限复用现有审批/作废权限，不新增独立红冲权限。
 - 多商户隔离必须下沉到 service。红冲 service 调用方必须传入当前 `merchant`，service 在解析单据后校验单据所属商户。

@@ -136,7 +136,17 @@
 - 库存记录未完成或已红冲时报错。
 - 事务回滚场景。

-目标：`business` 模块覆盖率 90%+。
+API 测试覆盖：
+
+- 6 类单据 `/red-flush/` 成功路径。
+- `reason` 必填。
+- 无员工身份权限拒绝。
+- 跨商户查询隔离。
+- 外部付款/收款单拒绝。
+- 未审核、重复红冲、缺库存记录等 service 校验错误映射为 400。
+- 成功响应包含 `is_red_flushed`、`red_flush_id`、`red_flushed_at`，并抽样断言余额/库存副作用。
+
+目标：red flush 关键 service/API 路径需要有定向测试覆盖。

 ## 测试命令

@@ -144,14 +154,14 @@

 ```bash
 docker compose exec -T -e DB_HOST=postgres -e DB_PORT=5432 web \
-  uv run python manage.py test business.tests --keepdb --noinput
+  uv run python manage.py test business.tests.test_red_flush_services api_v1.tests.BusinessRedFlushAPITestCase --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
+  uv run coverage run --source=business,api_v1 manage.py test business.tests.test_red_flush_services api_v1.tests.BusinessRedFlushAPITestCase --keepdb --noinput
 ```

 ```bash
--- a/docs/business_api_reference.md
+++ b/docs/business_api_reference.md
@@ -284,7 +284,30 @@
  - `delta / balance_before / balance_after / direction`：记录本次增减与余额快照
  - `offset_to / offset_id`：预留冲抵链路，与库存 `StockSnapshot` 设计一致
  - `request_id / extra_meta`：用于幂等和记录审批上下文（操作者、触发渠道等）
- **用途**：对账、审计、未来的余额红冲。目前未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
+- **用途**：对账、审计和红冲追踪。业务单据红冲会生成反向 `BalanceChangeRecord`，并通过 `offset_to / offset_id / red_flush_id` 与原记录关联。目前余额变动记录仍未开放对外查询 API，可在内部管理端或报表服务中直接访问；若后续开放，请提供分页、时间范围与 `source_type` 过滤能力。
+
+### 6.4 业务单据红冲（Red Flush）
+
+正式业务单据已开放整单红冲入口，详细说明请参阅独立文档 `docs/2026-06-12_business_red_flush_api.md`。
+
+| API | 方法 | 描述 |
+|-----|------|------|
+| `/purchase-orders/<id>/red-flush/` | POST | 红冲已审批采购单，反向余额和库存影响 |
+| `/sales-orders/<id>/red-flush/` | POST | 红冲已审批销售单，反向余额和库存影响 |
+| `/purchase-return-orders/<id>/red-flush/` | POST | 红冲已审批采购退货单，反向余额和库存影响 |
+| `/sales-return-orders/<id>/red-flush/` | POST | 红冲已审批销售退货单，反向余额和库存影响 |
+| `/payment-orders/<id>/red-flush/` | POST | 红冲已审批付款单，反向供应商余额 |
+| `/receipt-orders/<id>/red-flush/` | POST | 红冲已审批收款单，反向客户余额 |
+
+请求体：
+
+```json
+{
+  "reason": "录入错误，需要红冲"
+}
+```
+
+`reason` 必填且不能为空。红冲成功后原单据状态保持已审批，并返回 `is_red_flushed=true`、`red_flush_id`、`red_flushed_at`。外部来源付款/收款单不允许红冲。

 ## 7. 对账单（Statements）

@@ -314,13 +337,15 @@
 | 非本商户数据 | 403 | `{"error": "forbidden", "message": "无权限访问"}` |
 | 单据不存在 | 404 | `{"error": "purchase_order_not_found"}` 等 |
 | 审批非法状态 | 400 | 例如 `{"error": "purchase_order_has_stock_records"}`、`{"error": "receipt_order_already_approved"}` |
-| 余额功能未实现 | 501 | 仅限未来拓展，例如库存红冲尚未开放 |
+| 红冲非法状态 | 400 | 例如未审批、重复红冲、缺少可红冲库存/余额记录、外部来源单据不允许红冲 |

 ---

 ## 9. 参考文档

- `docs/purchase_order_approval_and_red_flush.md`：采购单审批及未来红冲方案。
+- `docs/2026-06-12_business_red_flush_api.md`：业务单据红冲独立 API 文档。
+- `docs/2026-06-12_business_red_flush_design.md`：业务单据红冲 service/API 设计备查。
+- `docs/purchase_order_approval_and_red_flush.md`：采购单审批与红冲背景。
 - `docs/sales_order_approval_and_red_flush.md`：销售单审批与严出模式说明。
 - `docs/payment_receipt_workflow.md`：资金类单据与余额表写入逻辑。

--- a/docs/purchase_order_approval_and_red_flush.md
+++ b/docs/purchase_order_approval_and_red_flush.md
@@ -61,44 +61,41 @@

 ---

-## 7. 下一阶段：库存红冲（对冲）方案规划
+## 7. 红冲（对冲）落地状态

 ### 6.1 目标与原则

- **目标**：允许在采购单及其衍生的出入库记录完成后，通过“红冲”方式撤销或抵消错误的库存变动，同时保持库存快照与主库存的可追溯性。
+- **当前状态**：采购单已支持整单红冲。已审批采购单可通过 `POST /api/v1/purchase-orders/<id>/red-flush/` 触发，生成反向余额记录和反向库存记录，同时保持库存快照与主库存的可追溯性。
 - **原则**：
  - 采用“新增反向记录”方式对冲，而非直接修改原记录；保留每一次实际发生的库存变更。
  - 红冲记录需要指向原 `StockChangeRecord` / `StockSnapshot`（如 `offset_to`、`offset_id` 字段），便于审计。
-  - 红冲动作必须与业务流程挂钩（例如采购单作废或红冲），避免孤立的库存操作。
+  - 红冲动作必须与业务流程挂钩（例如采购单红冲），避免孤立的库存操作。

 ### 6.2 行动步骤

 1. **业务入口确定**  
-   - 定义哪些业务对象可以触发红冲（采购单、销售单等）。  
-   - 明确触发条件：如采购单审批通过后，允许“创建红冲请求”并指向原采购单。
+   - 当前支持采购、销售、采购退货、销售退货、付款、收款 6 类正式单据整单红冲。  
+   - 触发条件：单据必须已审批，且尚未红冲。

 2. **库存服务层改造**  
-   - 在 `stock.services.StockFlowService` 或相关函数中增加创建红冲记录的能力：  
-     - 根据原 `StockChangeRecord` 生成反向 `StockChangeRecord` 和明细。  
-     - 更新 `StockSnapshot` 的 `offset_to` / `offset_id` / `cancelled` 字段，确保链路闭环。  
-   - 确保 `Inventory` 调整遵循相同的原子逻辑（事务 + 快照）。
+   - `stock.services.StockFlowService.offset_stock_change()` 已负责根据原 `StockChangeRecord` 生成反向 `StockChangeRecord` 和明细。  
+   - 更新 `StockSnapshot` 的 `offset_to` / `offset_id` / `cancelled` 字段，确保链路闭环。  
+   - `Inventory` 调整遵循相同的原子逻辑（事务 + 快照）。

 3. **业务服务与模型扩展**  
-   - 在 `business.services` 中引入“红冲采购单”或“撤销审批”的新方法：  
-     - 校验：原单是否允许红冲、是否存在未处理的红冲记录。  
-     - 调用库存红冲服务并记录关联。
-   - 必要时在 `PurchaseOrder` 或新模型中记录红冲状态/引用。
+   - `business.services.red_flush_purchase_order(...)` 负责校验原单是否允许红冲、阻止重复红冲，并调用库存红冲服务记录关联。
+   - `PurchaseOrder` 记录 `is_red_flushed`、`red_flush_id`、`red_flushed_at`。

 4. **API 与文档更新**  
-   - 设计新的红冲 API（例如 `/api/v1/purchase-orders/<id>/offset/`），请求体注明原因、操作者。  
-   - 文档中要说明红冲流程与限制（只能对已审批单据、需管理员权限等）。
+   - 红冲 API 为 `POST /api/v1/purchase-orders/<id>/red-flush/`，请求体必须包含 `reason`。  
+   - 权限复用现有业务单据员工权限，多商户数据先由 API 查询隔离，再由 service 二次校验。

 5. **测试与审计**  
   - 单元测试：业务 Service、库存 Service、API 都要覆盖正常流程与错误场景。  
-   - 集成测试：验证红冲后库存数量恢复、快照关系正确、消息/通知链路是否需要补充。
+   - 集成测试：已覆盖红冲后库存数量恢复、快照/库存记录关系、余额反向记录和 API 错误映射。
   - 如有需要，增加日志或审计表，记录红冲操作人、时间、关联记录。

-通过以上步骤，审批流程与红冲机制可以衔接：审批负责“正向入库”与任务分发，红冲负责在业务需要时生成配对的反向库存记录，保持库存账实一致，同时具备可回溯、可审计的业务闭环。 
+审批流程与红冲机制已衔接：审批负责“正向入库”与任务分发，红冲负责在业务需要时生成配对的反向库存记录，保持库存账实一致，同时具备可回溯、可审计的业务闭环。详细 API 见 `docs/2026-06-12_business_red_flush_api.md`。 

 ---

--- a/docs/sales_order_approval_and_red_flush.md
+++ b/docs/sales_order_approval_and_red_flush.md
@@ -68,13 +68,13 @@

 > 说明：在严出模式下，`consume_detail_ids` 列表中的 ID 必须为同仓库、同商户且未被消耗的入库明细 ID。系统会在审批通过时逐条扣减对应库存。

-## 8. 红冲（对冲）规划
+## 8. 红冲（对冲）落地状态

-与采购单一致，后续将通过库存红冲入口（`StockFlowService.offset_stock_change` 占位方法）实现销售单出库的反向抵销。关键原则：
+与采购单一致，销售单已支持整单红冲。已审批销售单可通过 `POST /api/v1/sales-orders/<id>/red-flush/` 触发，生成反向余额记录和反向库存记录。关键原则：

 - 采用新增反向记录的方式，保留所有历史变动。
 - 红冲记录需要指向原 `StockChangeRecord` / `StockSnapshot`，保证审计可追溯。
 - 红冲需与业务对象绑定，避免孤立库存操作。

-文档与测试应在红冲能力落地时同步更新，确保审批、出库、红冲形成闭环。 
+红冲能力已补充独立 API 文档与定向测试，确保审批、出库、红冲形成闭环。详细 API 见 `docs/2026-06-12_business_red_flush_api.md`。 

--- a/docs/stock_api_overview.md
+++ b/docs/stock_api_overview.md
@@ -596,35 +596,18 @@ Warehouses can operate in different modes:
 }
 ```

-### 8. Stock Change Offset (Red Flush Placeholder)
+### 8. Stock Change Offset 与业务红冲

- **URL**: `POST /api/v1/stock-change/<id>/offset/`
- **Description**: 面向未来的库存红冲入口。当前仅提供占位实现，用于锁定最终接口形态；实际红冲逻辑尚未上线，因此调用会返回 `501 Not Implemented`，方便前端或上游业务在流程编排中预留节点。
- **Request**:
-```json
-{
-  "reason": "审批错误，需要冲销",
-  "items": [
-    {
-      "product_id": 1,
-      "quantities": ["50.00"]
-    }
-  ],
-  "request_id": "po-123-offset",
-  "extra_meta": {
-    "source": "purchase_order",
-    "operator": "warehouse_admin"
-  }
-}
-```
- **Response（当前占位行为）**:
-```json
-{
-  "error": "stock_offset_not_ready",
-  "message": "库存红冲功能尚未实现",
-  "record_id": 25
-}
-```
+`POST /api/v1/stock-change/<id>/offset/` 已在上文“库存红冲（Stock Change Offset）”说明。业务单据红冲会通过 `business` service 调用同一库存对冲能力，并把同一个 `red_flush_id` 写入原库存记录和反向库存记录。
+
+面向前端或业务系统的正式业务红冲入口请优先使用 `business` 单据 API，例如：
+
+- `POST /api/v1/purchase-orders/<id>/red-flush/`
+- `POST /api/v1/sales-orders/<id>/red-flush/`
+- `POST /api/v1/purchase-return-orders/<id>/red-flush/`
+- `POST /api/v1/sales-return-orders/<id>/red-flush/`
+
+完整业务 API 见 `docs/2026-06-12_business_red_flush_api.md`。

 ## Examples