feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 8242e730b4
482 changed files with 37029 additions and 0 deletions
@@ -0,0 +1,53 @@
+# D-03 · 收付款分配接入 REST + API 集成测试
+
+| 字段 | 值 |
+|---|---|
+| 项目 | dealerhub · `Desktop/gj/dealerhub/backend` |
+| 优先级 | P0 · M3 |
+| 建议模型 | deepseek-v4.1-flash（主）/ glm-5.3-flash（回归） |
+| 依赖 | 无（与 D-01 并行安全） |
+| 预估 | 2 天 |
+
+## 一、背景（为什么做）
+
+dealerhub 迭代 5 自列"下一轮最高价值项"第 2 条：**收款/付款分配 service 已存在但未接入 REST action，且缺 API 集成测试**（`PROGRESS_AGI_ITERATION_5.md`）。这是财务闭环的关键断点——分销/进销存系统的资金流必须能从 API 层完整驱动，否则业务员在前端无法完成核销动作。
+
+## 二、目标（交付物）
+
+1. 盘点现有 collection/payment allocation service（收款分配/付款分配/核销逻辑），确认其函数契约。
+2. **接入 REST action**：
+   - 收款单核销 action（如 `POST /api/finance/receipts/{id}/allocate`）
+   - 付款单核销 action（如 `POST /api/finance/payments/{id}/allocate`）
+   - 参数校验（分配金额合计 ≤ 单头金额、对象存在、幂等约束）——全部服务端强制
+3. **API 集成测试**（本卡核心交付之一）：
+   - 正常分配、部分分配、超额分配（拒绝）、重复分配（幂等/拒绝——行为先定义）、并发分配（PG 下）
+   - 跨租户访问拒绝（与 D-01 的授权层协同）
+   - 分配后余额/账龄数据正确性断言
+4. 前端接口对接说明（若前端已有页面则接线；没有则记录遗留）。
+
+## 三、验收标准
+
+- [ ] 收款/付款核销可全流程经 REST 完成（附 curl/pytest 证据）
+- [ ] 超额分配被拒（400/409 语义明确）；重复提交行为定义且用例覆盖
+- [ ] 分配后：应收/应付余额、账龄桶数据正确（断言）
+- [ ] 跨租户越权用例通过
+- [ ] `makemigrations --check --dry-run` 干净；既有 460 用例零回归
+- [ ] 新增用例 ≥10 条
+
+## 四、验收命令（参考）
+
+```bash
+cd backend && pytest -q -k "allocation or allocate or receipt or payment"
+pytest -q            # 全量回归
+python manage.py makemigrations --check --dry-run
+```
+
+## 五、边界（不许做）
+
+- 不重写 service 层逻辑（只做接入与暴露；发现 bug 记 PROGRESS）
+- 不改单据状态机既有流转
+- 不接入真实支付通道（内部核销动作）
+
+## 六、交接
+
+写 `PROGRESS_D-03.md`（含核销全流程证据、边界用例清单、余额断言输出）。