feat: red flush and cost

2026-06-22 22:27:28 +08:00
parent 9a1c92febf
commit 70b3a0d246
25 changed files with 1375 additions and 20 deletions
--- a/docs/2026-06-12_business_red_flush_api.md
+++ b/docs/2026-06-12_business_red_flush_api.md
@@ -72,7 +72,7 @@ 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.
+`red_flush_id` is written to the source order and related `BalanceChangeRecord` rows. It is also written to related `StockChangeRecord` rows when the source order actually has inventory records. Sales orders may be red-flushed without inventory records; in that case only the balance side is reversed. Existing `offset_to`/`offset_id` relationships remain the precise reverse-link mechanism for balance and stock records.

 ## Test Coverage

@@ -85,4 +85,4 @@ python manage.py test business.tests.test_red_flush_services api_v1.tests.Busine
 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.
+- 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, sales red flush without stock records, 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
@@ -10,6 +10,7 @@

 - 红冲后原单据 `status` 保持 `APPROVED`，不回退、不作废。
 - 原单据增加“已红冲”标记，用于列表查询提速。
+- 因为 `status` 保持 `APPROVED`，**对账单 builder 必须额外按 `is_red_flushed=False` 过滤**，否则红冲单会被原值计入 `positive_amount`/`negative_amount`，summary 多算一倍。
 - 每次红冲由 service 自动生成一个 UUID 类型的 `red_flush_id`。
 - `red_flush_id` 用于跨表、跨记录追踪同一次红冲涉及的所有数据，是审计关联批次 ID。
 - 不新增 `red_flush_no`。该编号只适合人工展示，目前无需求。
@@ -103,7 +104,7 @@
 - 只允许 `APPROVED` 单据红冲。
 - `is_red_flushed=True` 的单据不能重复红冲。
 - 原始余额变动记录必须存在且未被冲抵。
- 有库存影响的单据必须找到对应库存记录，库存记录必须已完成且未被红冲。
+- 有库存影响且要求库存闭环的单据必须找到对应库存记录，库存记录必须已完成且未被红冲；销售单允许不存在库存记录，此时只红冲余额。
 - 资金和库存任一红冲失败，整体事务回滚。

 资金侧实现：
@@ -125,7 +126,7 @@
 新增 service 测试覆盖：

 - 采购单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
- 销售单整单红冲：余额反向、库存反向、单据标记、批次 ID 写入。
+- 销售单整单红冲：余额反向、单据标记、批次 ID 写入；若存在销售出库记录则同步库存反向，若无库存记录则跳过库存红冲。
 - 采购退货单整单红冲。
 - 销售退货单整单红冲。
 - 付款单整单红冲。
@@ -143,11 +144,25 @@ API 测试覆盖：
 - 无员工身份权限拒绝。
 - 跨商户查询隔离。
 - 外部付款/收款单拒绝。
- 未审核、重复红冲、缺库存记录等 service 校验错误映射为 400。
+- 未审核、重复红冲、采购等要求库存闭环的单据缺库存记录等 service 校验错误映射为 400。
 - 成功响应包含 `is_red_flushed`、`red_flush_id`、`red_flushed_at`，并抽样断言余额/库存副作用。

 目标：red flush 关键 service/API 路径需要有定向测试覆盖。

+## 对账单 builder 联动修复（2026-06-22）
+
+`business.services._CustomerStatementBuilder._build_sales_records` / `_build_sales_return_records` / `_build_receipt_records` 以及 `_SupplierStatementBuilder._build_purchase_records` / `_build_purchase_return_records` / `_build_payment_records` 之前只过滤 `status=APPROVED`，未过滤 `is_red_flushed`。
+
+红冲后单据 `status` 仍为 `APPROVED`，所以会继续以原金额出现在 `build_customer_statement` / `build_supplier_statement` 的 `records` 列表中，被 `build_statement_summary` 双倍计入 `positive_total`/`negative_total`。
+
+修复办法：6 个 builder queryset 全部追加 `is_red_flushed=False`。
+
+注意：
+- `BalanceService.get_customer_balance` / `get_supplier_balance` 读取 `CustomerBalance/SupplierBalance` 表，红冲服务通过反向 `BalanceChangeRecord` 已经把余额抵消，因此 `current_balance` 字段一直是正确的；只有 `records` 与 `summary` 受影响。
+- `ExternalCustomerStatementOrder` 目前不在 6 类红冲入口里，相关 builder/adjustment 暂不需要过滤，将来若开放外部单红冲必须同步更新。
+
+定向测试：见 `business.tests.test_statement_services.BusinessStatementRedFlushExclusionTestCase`，覆盖 6 类正式单据红冲后 statement 中 `records` 不再包含、`summary` 不再多算。
+
 ## 测试命令

 开发环境在容器内运行测试，并绕过 PgBouncer：
--- a/docs/2026-06-22_balance_before_snapshot_handoff.md
+++ b/docs/2026-06-22_balance_before_snapshot_handoff.md
@@ -0,0 +1,423 @@
+# 四类主要业务单据 `balance_before_snapshot` 实现交接
+
+日期：2026-06-22
+状态：已完成。核心实现、入口扫描、定向测试、API 测试、迁移检查及相关回归测试均已通过。
+
+## 0. 最终完成结果
+
+本任务已于 2026-06-22 完成，当前没有余额快照相关的待实现项。
+
+最终落地内容：
+
+- 四类主单模型均已新增可空 `balance_before_snapshot`。
+- 新增 `0032_order_balance_before_snapshot` 迁移，不回填历史数据。
+- 四个正式创建 service 均必写当前本地往来余额；不存在余额行时写 `0`。
+- 更新、往来单位变更、余额后续变化、审批、作废及红冲均不重算快照。
+- 四类 API serializer 输出该字段并设为只读。
+- 四个 POST 创建响应均显式返回该字段。
+- 生产代码扫描确认没有绕过正式 service 直接创建四类主单的入口。
+- 预销售转正式销售调用 `business_services.create_sales_order()`，已自然覆盖快照逻辑。
+
+新增测试文件：`business/tests/test_balance_before_snapshot.py`，共 4 个测试，覆盖：
+
+- 四类创建读取已有正数/负数余额。
+- 无余额行时四类创建均写 `0` 而非 `NULL`。
+- 四类更新、更换往来单位以及余额后续变化均不重算快照。
+- 四类 API serializer 输出且拒绝客户端写入快照。
+
+另在 `api_v1/tests.py` 四个既有成功创建测试中加入 POST 响应和数据库落值断言。
+
+已在 `web` 容器内使用 `DB_HOST=postgres DB_PORT=5432` 直连 PostgreSQL、绕过 PgBouncer 完成验证：
+
+- `makemigrations --check --dry-run`：通过，`No changes detected`。
+- `manage.py check`：通过，0 issues。
+- 新增余额快照定向测试：4/4 通过。
+- 四类单据 service/API 回归：74/74 通过。
+- 红冲、对账单及红冲 API 共享服务回归：36/36 通过。
+- 本任务相关已跟踪文件 `git diff --check`：通过。
+- 新增迁移与新增测试文件的补丁格式检查：通过。
+
+下文保留了实现细节和原始验收清单，方便以后维护和排查回归；其中“尚未完成”内容已经全部执行完毕。
+
+## 1. 需求目标
+
+为以下四类主要业务单据增加 `balance_before_snapshot` 字段：
+
+1. `PurchaseOrder`（采购单）
+2. `SalesOrder`（销售单）
+3. `PurchaseReturnOrder`（采购退货单）
+4. `SalesReturnOrder`（销售退货单）
+
+字段语义必须保持一致：
+
+- 字段记录单据正常创建时，对应往来单位在本地余额表中的当前余额。
+- 采购单、采购退货单记录供应商余额，即 `SupplierBalance.balance`。
+- 销售单、销售退货单记录客户余额，即 `CustomerBalance.balance`。
+- 对应余额记录不存在时，快照写入 `Decimal('0')`，不能因为数据库字段可空而让正常创建的新单据写入 `NULL`。
+- 数据库字段必须允许 `NULL`，用于兼容迁移前的历史单据。
+- 不对历史数据执行回填或推算；历史行保持 `NULL`。
+- 快照只在创建时写一次。之后即使往来余额发生变化，或者单据被修改、审批、作废、红冲，都不能重新计算或覆盖该字段。
+- 客户快照采用本地 `CustomerBalance` 口径，不叠加 `ExternalCustomerStatementOrder`。当前实现调用 `BalanceService.get_customer_balance()`，没有调用 `get_customer_statement_balance()`。
+
+## 2. 接手前工作区情况
+
+本次任务开始时工作区已有大量未提交修改，主要涉及：
+
+- 业务单据红冲逻辑和测试。
+- 对账单排除已红冲单据。
+- 销售单列表查询过滤。
+- 开版看板序列化与查询优化。
+- 环境、域名、文档及 Celery schedule 文件。
+
+这些改动属于上一轮或用户已有工作，不能清理、回退或覆盖。后续只应增量修改余额快照相关文件。特别不要使用 `git reset --hard`、`git checkout --` 等命令。
+
+在 `business/services.py` 和 `api_v1/views/business/sales/views.py` 中，本次余额快照修改与已有未提交修改位于同一文件。审阅 diff 时应按具体代码块区分，不要把整份文件都视为本任务新增。
+
+## 3. 已写入的实现
+
+### 3.1 模型字段
+
+文件：`business/models.py`
+
+已在四个模型中加入 `balance_before_snapshot`：
+
+```python
+balance_before_snapshot = models.DecimalField(
+    max_digits=15,
+    decimal_places=2,
+    null=True,
+    blank=True,
+    verbose_name='创建前供应商余额快照',  # 客户侧为“创建前客户余额快照”
+)
+```
+
+具体口径：
+
+| 模型 | 快照对象 | verbose_name |
+|---|---|---|
+| `PurchaseOrder` | 供应商余额 | `创建前供应商余额快照` |
+| `SalesOrder` | 客户余额 | `创建前客户余额快照` |
+| `PurchaseReturnOrder` | 供应商余额 | `创建前供应商余额快照` |
+| `SalesReturnOrder` | 客户余额 | `创建前客户余额快照` |
+
+字段没有默认值，数据库允许为空。这样迁移不会给历史单据制造一个看似真实但无法验证的余额。
+
+### 3.2 数据库迁移
+
+文件：`business/migrations/0032_order_balance_before_snapshot.py`
+
+已新增迁移，依赖：
+
+```python
+dependencies = [
+    ('business', '0031_red_flush_fields'),
+]
+```
+
+迁移包含四个 `AddField`，全部是：
+
+- `DecimalField(max_digits=15, decimal_places=2)`
+- `null=True`
+- `blank=True`
+- 无 `default`
+- 无数据迁移和历史回填
+
+需要在后续验证迁移依赖仍然是当前分支最新叶子；当前检查时 `0031_red_flush_fields.py` 是最新已存在迁移，`0032` 是本任务新文件。
+
+### 3.3 正常创建服务写入快照
+
+文件：`business/services.py`
+
+以下四个服务函数的 `objects.create(...)` 已加入快照赋值：
+
+#### `create_purchase_order(...)`
+
+```python
+balance_before_snapshot=BalanceService.get_supplier_balance(
+    merchant=merchant,
+    supplier=supplier,
+),
+```
+
+#### `create_sales_order(...)`
+
+```python
+balance_before_snapshot=BalanceService.get_customer_balance(
+    merchant=merchant,
+    customer=customer,
+),
+```
+
+#### `create_purchase_return_order(...)`
+
+```python
+balance_before_snapshot=BalanceService.get_supplier_balance(
+    merchant=merchant,
+    supplier=supplier,
+),
+```
+
+#### `create_sales_return_order(...)`
+
+```python
+balance_before_snapshot=BalanceService.get_customer_balance(
+    merchant=merchant,
+    customer=customer,
+),
+```
+
+这些调用位于各自已有的 `transaction.atomic()` 中，并在创建主单据时直接写字段。
+
+`BalanceService.get_supplier_balance()` 和 `get_customer_balance()` 的既有行为是：余额行存在则返回其 `balance`；不存在则返回 `Decimal('0')`。因此正常服务创建入口理论上不会写入 `NULL`。
+
+### 3.4 “之后不重算”的当前实现状态
+
+四个更新服务当前均未把 `balance_before_snapshot` 放进赋值或 `update_fields`：
+
+- `update_purchase_order(...)`
+- `update_sales_order(...)`
+- `update_purchase_return_order(...)`
+- `update_sales_return_order(...)`
+
+审批、作废、红冲逻辑也没有写该字段。模型没有为该字段增加 `save()` 自动计算或 signal。因此按照当前代码结构，创建完成后不会自动重算。
+
+这一点尚缺定向测试，必须补测试防止未来回归。
+
+### 3.5 API 输出
+
+以下四个 ModelSerializer 的 `fields` 已加入 `balance_before_snapshot`，同时加入 `read_only_fields`：
+
+- `api_v1/views/business/purchase/views.py`
+  - `PurchaseOrderSerializer`
+- `api_v1/views/business/sales/views.py`
+  - `SalesOrderSerializer`
+- `api_v1/views/business/purchase_return/views.py`
+  - `PurchaseReturnOrderSerializer`
+- `api_v1/views/business/sales_return/views.py`
+  - `SalesReturnOrderSerializer`
+
+因此列表、详情、更新结果、审批结果和红冲结果只要使用上述 serializer，都会输出该字段，且客户端不能通过 serializer 修改它。
+
+四个创建 API 当前返回的是手工构造的精简字典，不走 ModelSerializer，所以创建成功响应中也已显式加入：
+
+```python
+'balance_before_snapshot': order.balance_before_snapshot,
+```
+
+具体变量名分别为：
+
+- `purchase_order.balance_before_snapshot`
+- `sales_order.balance_before_snapshot`
+- `purchase_return.balance_before_snapshot`
+- `sales_return.balance_before_snapshot`
+
+## 4. 已完成的收尾工作（原验收计划）
+
+### 4.1 扫描所有生产创建入口
+
+已确认四个主要 API 创建入口均调用 `business.services` 中对应的 `create_*` 函数，因此已覆盖：
+
+- `POST` 采购单
+- `POST` 销售单
+- `POST` 采购退货单
+- `POST` 销售退货单
+
+但最后一次完整生产代码扫描尚未完成。接手后应再次执行：
+
+```bash
+rg -n "create_(purchase_order|sales_order|purchase_return_order|sales_return_order)\(" \
+  api_v1 business \
+  --glob '!business/services.py' \
+  --glob '!**/tests/**' \
+  --glob '!**/test*.py'
+```
+
+还应扫描是否有生产代码绕过 service 直接创建四类模型：
+
+```bash
+rg -n "(PurchaseOrder|SalesOrder|PurchaseReturnOrder|SalesReturnOrder)\.objects\.(create|get_or_create|update_or_create|bulk_create)" \
+  api_v1 business \
+  --glob '!**/tests/**' \
+  --glob '!**/test*.py'
+```
+
+如果发现正常业务入口绕过 service，应让其改用 service，或在同一创建事务中显式写快照。数据导入、测试 fixture、历史修复脚本不一定属于“正常创建入口”，需要按用途判断，不能盲目强制。
+
+预销售单/预采购单转正式单通常会调用正式单据 service；需要通过上述扫描确认，避免漏掉转换入口。
+
+### 4.2 补定向服务测试
+
+建议新增：
+
+`business/tests/test_balance_before_snapshot.py`
+
+至少覆盖以下场景。
+
+#### 场景 A：四类创建均写当前余额
+
+1. 使用 `create_basic_fixtures()` 创建供应商侧数据。
+2. 建立或更新 `SupplierBalance(balance=Decimal('123.45'))`。
+3. 通过 `create_purchase_order()` 创建采购单，断言快照为 `123.45`。
+4. 通过 `create_purchase_return_order()` 创建采购退货单，断言快照为 `123.45`。
+5. 使用 `create_sales_fixtures()` 创建客户侧数据。
+6. 建立或更新 `CustomerBalance(balance=Decimal('-67.89'))`。
+7. 通过 `create_sales_order()` 创建销售单，断言快照为 `-67.89`。
+8. 通过 `create_sales_return_order()` 创建销售退货单，断言快照为 `-67.89`。
+
+测试应调用正式 service，而不是直接 `objects.create()`，以验证正常入口。
+
+#### 场景 B：余额行不存在时，新单快照写零而不是 NULL
+
+对供应商侧和客户侧至少各测一个：
+
+```python
+self.assertEqual(order.balance_before_snapshot, Decimal('0'))
+self.assertIsNotNone(order.balance_before_snapshot)
+```
+
+这是“数据库允许空”和“正常创建必写”之间最容易回归的边界。
+
+#### 场景 C：余额变化后不重算
+
+1. 余额为 `100.00` 时创建单据。
+2. 创建后把对应 `SupplierBalance`/`CustomerBalance` 改成其他值，或审批另一张会改变余额的单据。
+3. `refresh_from_db()` 原单据。
+4. 断言快照仍为 `100.00`。
+
+#### 场景 D：更新单据后不重算
+
+更新服务允许审批中的单据更换供应商/客户。需要明确验证快照仍是最初创建时的值，而不是新往来单位当前余额：
+
+1. 往来单位 A 余额为 `100.00`，创建单据。
+2. 往来单位 B 余额为 `999.00`。
+3. 调用对应 `update_*` 将单据往来单位改为 B，并提交合法 items。
+4. 断言 `balance_before_snapshot` 仍为 `100.00`。
+
+供应商侧与客户侧至少各覆盖一次。若产品语义认为更换往来单位应另有约束，也不能在更新时重算快照；需求已经明确“之后不重算”。
+
+#### 场景 E：序列化字段只读
+
+可以在 API 测试中验证：
+
+- 创建响应包含正确快照。
+- 列表或详情响应包含正确快照。
+- PATCH/PUT 请求即使携带伪造的 `balance_before_snapshot`，数据库值仍不变。
+
+由于当前 API 更新路径手工提取允许字段，本身不会读取该请求字段；serializer 中也已标记只读。
+
+### 4.3 迁移与系统检查
+
+需要运行：
+
+```bash
+python manage.py makemigrations --check --dry-run
+python manage.py check
+```
+
+预期：
+
+- `makemigrations --check --dry-run` 不再生成额外迁移。
+- `manage.py check` 无本任务引入的问题。
+
+若项目约定在 Docker 内运行，应使用现有项目测试容器，并按当前开发环境配置绕过 PgBouncer。不要擅自修改 `.env`、`docker-compose.yml` 或数据库配置来迁就测试；这些文件已有其他未提交改动。
+
+### 4.4 定向测试命令
+
+新增测试文件后建议先运行：
+
+```bash
+python manage.py test business.tests.test_balance_before_snapshot
+```
+
+然后运行四类既有 service/API 测试，具体模块可根据项目现有测试命名选择：
+
+```bash
+python manage.py test \
+  business.tests.test_purchase_order \
+  business.tests.test_sales_order \
+  business.tests.test_purchase_return \
+  business.tests.test_sales_return
+```
+
+API 测试集中在 `api_v1/tests.py` 时，可至少运行相关 TestCase：
+
+```bash
+python manage.py test \
+  api_v1.tests.PurchaseOrderAPITestCase \
+  api_v1.tests.SalesOrderAPITestCase \
+  api_v1.tests.PurchaseReturnOrderAPITestCase \
+  api_v1.tests.SalesReturnOrderAPITestCase
+```
+
+最后根据时间运行更宽范围回归。由于工作区已有红冲与 statement 修改，如果宽范围测试失败，需先判断失败属于余额快照还是已有未提交工作。
+
+## 5. 需要重点复核的设计点
+
+### 5.1 快照时点
+
+当前实现是在四个创建 service 的 `transaction.atomic()` 内、执行主单 `objects.create()` 参数求值时读取余额。这符合“创建时快照”。
+
+当前读取函数没有使用 `select_for_update()`。在绝大多数正常流程中会读取当时已提交的余额；但如果产品要求与并发余额调整建立严格串行顺序，需要额外评估是否应锁定余额行。
+
+不要未经评估直接把读取改成 `get_or_create(...).select_for_update()`：这会使每次创建单据都创建一行零余额记录，改变现有数据行为。若要增强并发语义，应先查看项目现有并发策略和数据库隔离级别，并补并发测试。
+
+本需求当前未明确要求强锁，建议先保持现有简单读取，完成基础测试后再决定是否扩展。
+
+### 5.2 更新时更换往来单位
+
+当前更新服务允许把审批中的采购类单据改为另一供应商，或把销售类单据改为另一客户。快照仍保留创建时旧往来单位余额。
+
+这看起来可能与更新后的往来单位不一致，但符合“创建时快照，之后不重算”的明确要求。不要在更新 service 中加入重算，除非用户重新定义业务语义。
+
+### 5.3 历史数据
+
+迁移不能回填 `0`，也不能依据当前余额倒推历史余额。历史单据的正确创建前余额通常无法可靠恢复，因此 `NULL` 本身就是“未知”的有效表达。
+
+### 5.4 API 可写性
+
+字段必须是输出字段而不是客户端输入字段。当前 serializer 已标记只读，创建 API 也没有读取客户端传入的同名字段。后续若引入新的 create serializer，要继续把字段设为 read-only，并由 service 计算。
+
+## 6. 建议的完成顺序
+
+1. 用 `git diff` 和 `git status --short` 确认上述八个代码/迁移文件的实际状态。
+2. 扫描所有生产创建入口和直接 ORM 创建点。
+3. 补 `business/tests/test_balance_before_snapshot.py`。
+4. 补必要的 API 字段测试。
+5. 运行 `makemigrations --check --dry-run` 和 `manage.py check`。
+6. 运行定向测试及四类既有回归测试。
+7. 执行 `git diff --check`；注意工作区已有文件可能存在与本任务无关的尾部空行问题，应区分来源。
+8. 最终审阅只聚焦本任务的文件/代码块，保留所有既有未提交修改。
+
+## 7. 本任务相关文件清单
+
+已修改或新增：
+
+- `business/models.py`
+- `business/services.py`
+- `business/migrations/0032_order_balance_before_snapshot.py`（新增、未提交）
+- `api_v1/views/business/purchase/views.py`
+- `api_v1/views/business/sales/views.py`
+- `api_v1/views/business/purchase_return/views.py`
+- `api_v1/views/business/sales_return/views.py`
+
+计划新增：
+
+- `business/tests/test_balance_before_snapshot.py`
+
+可能按测试结果增量修改：
+
+- `api_v1/tests.py`，或拆分后的对应 API 测试文件
+- 业务 API 文档（只有在项目要求公开列出响应字段时再补，不是核心实现的阻塞项）
+
+## 8. 完成判定
+
+只有同时满足以下条件，才能认为本任务完成：
+
+- 四个数据库字段存在且允许 `NULL`。
+- 迁移不回填历史数据。
+- 四个正式创建 service 对余额存在和不存在两种情况均写入非空快照。
+- 所有正常生产创建入口都经过上述逻辑。
+- 更新、审批、作废、红冲以及余额后续变化不会改写快照。
+- 四类 API 能返回快照，且客户端不能写入或篡改。
+- 模型与迁移一致。
+- 定向测试通过，既有四类业务单据测试无本任务引入的回归。
--- a/docs/business_api_reference.md
+++ b/docs/business_api_reference.md
@@ -293,7 +293,7 @@
 | API | 方法 | 描述 |
 |-----|------|------|
 | `/purchase-orders/<id>/red-flush/` | POST | 红冲已审批采购单，反向余额和库存影响 |
-| `/sales-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 | 红冲已审批付款单，反向供应商余额 |
@@ -307,7 +307,7 @@
 }
 ```

-`reason` 必填且不能为空。红冲成功后原单据状态保持已审批，并返回 `is_red_flushed=true`、`red_flush_id`、`red_flushed_at`。外部来源付款/收款单不允许红冲。
+`reason` 必填且不能为空。红冲成功后原单据状态保持已审批，并返回 `is_red_flushed=true`、`red_flush_id`、`red_flushed_at`。销售单没有对应库存记录时只反向余额，不执行库存红冲。外部来源付款/收款单不允许红冲。

 ## 7. 对账单（Statements）

@@ -337,7 +337,7 @@
 | 非本商户数据 | 403 | `{"error": "forbidden", "message": "无权限访问"}` |
 | 单据不存在 | 404 | `{"error": "purchase_order_not_found"}` 等 |
 | 审批非法状态 | 400 | 例如 `{"error": "purchase_order_has_stock_records"}`、`{"error": "receipt_order_already_approved"}` |
-| 红冲非法状态 | 400 | 例如未审批、重复红冲、缺少可红冲库存/余额记录、外部来源单据不允许红冲 |
+| 红冲非法状态 | 400 | 例如未审批、重复红冲、要求库存闭环的单据缺少可红冲库存记录、缺少可红冲余额记录、外部来源单据不允许红冲 |

 ---

--- a/docs/sales_order_approval_and_red_flush.md
+++ b/docs/sales_order_approval_and_red_flush.md
@@ -70,11 +70,11 @@

 ## 8. 红冲（对冲）落地状态

-与采购单一致，销售单已支持整单红冲。已审批销售单可通过 `POST /api/v1/sales-orders/<id>/red-flush/` 触发，生成反向余额记录和反向库存记录。关键原则：
+销售单已支持整单红冲。已审批销售单可通过 `POST /api/v1/sales-orders/<id>/red-flush/` 触发，生成反向余额记录；若原销售单存在 `source_type=SALES` 的出库记录，则同步生成反向库存记录。关键原则：

 - 采用新增反向记录的方式，保留所有历史变动。
- 红冲记录需要指向原 `StockChangeRecord` / `StockSnapshot`，保证审计可追溯。
- 红冲需与业务对象绑定，避免孤立库存操作。
+- 存在库存记录时，红冲记录需要指向原 `StockChangeRecord` / `StockSnapshot`，保证审计可追溯。
+- 红冲需与业务对象绑定；没有库存记录的销售单只处理余额侧，不执行库存红冲。

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

--- a/docs/开版看板-plate-orders接口字段使用清单.md
+++ b/docs/开版看板-plate-orders接口字段使用清单.md
@@ -0,0 +1,102 @@
+# 开版看板 `/api/v1/plate-orders/` GET 接口字段使用清单
+
+整理范围：只统计开版管理看板页面对 `GET /api/v1/plate-orders/` 列表接口返回数据的字段使用情况。
+
+主要代码位置：
+
+- `src/pages/Production/PlateOrderKanban.tsx`
+- `src/pages/Production/PlateOrderDetailModal.tsx`
+- `src/pages/Production/PlatePrintTemplate.tsx`
+
+## 响应结构字段
+
+| 字段 | 用途 |
+|---|---|
+| `results` | 订单列表数据源 |
+| `count` | 判断后端总数是否大于本次加载数量，超出时提示用户缩小“下单时间”范围 |
+
+## 订单对象字段
+
+| 字段 | 用途 |
+|---|---|
+| `id` | 卡片 ID、选择、拖拽、详情、编辑、打印、二维码内容、打印次数对象 ID |
+| `auto_code` | 卡片副标题；打印顶部订单编号，缺失时用 `design_code` 兜底 |
+| `design_code` | 卡片主标题；详情设计编号；打印设计编号；流程弹窗业务对象名称 |
+| `customer_name` | 卡片客户；详情客户名称；打印客户 |
+| `area` | 详情客户区域；打印默认地址/区域 |
+| `salesperson_name` | 详情业务人员；打印业务员 |
+| `merchandiser_name` | 详情跟单人员；打印跟单员 |
+| `fabric_source` | 详情面料来源；打印布料 |
+| `fabric` | 详情面料名称；打印打版面料 |
+| `width` | 详情面料幅宽；打印幅宽 |
+| `plate_type` | 卡片起版情况标签；详情起版情况；打印起版情况 |
+| `plate_date` | 卡片下版时间；详情订单时间；打印订单时间 |
+| `plate_method` | 详情开版方式；打印开版方式 |
+| `plate_image_url` | 卡片图片优先来源；详情图片预览；打印开版图 |
+| `plate_image` | 卡片图片兜底来源 |
+| `plate_notes` | 详情打版备注；打印打版注意事项 |
+| `reprint_reason` | 打印复版原因 |
+| `urgency_level` | 卡片紧急程度；详情紧急程度；打印紧急程度 |
+| `production_method` | 详情做货方式；打印做货方式 |
+| `is_mark_frame` | 打印是否套唛架 |
+| `drawing_rating` | 详情画图评级；打印画图难度 |
+| `color_matching_rating` | 详情调色评级；打印调色难度 |
+| `sample_rating` | 详情套样评级；打印套样难度 |
+| `difficulty_rating` | 详情难度评级；打印难度评级 |
+| `style_name` | 详情款号名称；打印款号名称 |
+| `required_sample_meters` | 打印样品米数 |
+| `required_completion_date` | 详情开版时间；打印开版时间 |
+| `completion_date` | 详情要求时间；打印要求时间 |
+| `approval_result` | 打印审批结果 |
+| `customer_feedback` | 打印客户反馈 |
+| `last_completed_state` | 看板分列依据；卡片状态；动态补充流程列；快速跳转当前状态 |
+| `business_object_id` | 推进、回退、快速跳转；详情/打印加载当前订单工序日志 |
+| `original_id` | 详情原订单入口；打印历史工序入口；批量打印历史工序入口 |
+| `process_name` | 卡片流程标签；详情关联流程；打印开发进程 |
+| `print_count` | 卡片打印次数；判断进入“未打印”或“客户开版”列 |
+| `created_at` | 组装进打印数据，但当前打印模板未实际展示 |
+| `created_by_name` | 打印拥有者/制单人 |
+
+## 去重字段列表
+
+```text
+id
+auto_code
+design_code
+customer_name
+area
+salesperson_name
+merchandiser_name
+fabric_source
+fabric
+width
+plate_type
+plate_date
+plate_method
+plate_image_url
+plate_image
+plate_notes
+reprint_reason
+urgency_level
+production_method
+is_mark_frame
+drawing_rating
+color_matching_rating
+sample_rating
+difficulty_rating
+style_name
+required_sample_meters
+required_completion_date
+completion_date
+approval_result
+customer_feedback
+last_completed_state
+business_object_id
+original_id
+process_name
+print_count
+created_at
+created_by_name
+```
+
+说明：`next`、`previous` 当前看板未使用；`status`、`is_completed`、`is_ordered`、`is_invalid`、`progress_percentage`、`updated_at`、`created_by` 只在复制订单时重置/透传逻辑里出现，不属于当前列表 GET 响应的实际展示或看板流程消费字段，未计入本清单。