vscode-workbench/PLANNING/tasks/D-03-收付款分配接入REST.md

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 条

四、验收命令（参考）

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（含核销全流程证据、边界用例清单、余额断言输出）。