shanxia2.0/openspec/changes/void-cancel-reason-required/tasks.md

1. Database & Models

• 1.1 编写增量 SQL：为 8 张表增加原因三元组（quote=invalid_*，PL=cancel_*，地磅=void_*）
• 1.2 更新 docs/sql/shanxia2.0.sql 中对应 CREATE TABLE 定义
• 1.3 更新 SQLAlchemy：CrmQuote、PlPlan、车辆四表、PlFreightSettlement、DbWeighingSlip
• 1.4 在测试库执行迁移并确认可空列（47.99.164.66/shanxia2.0，8/8 ALTER 成功）

2. Backend APIs

• 2.1 报价单：invalid_quote 可选 invalidReason，写 invalid_*（原因可空仍写 time/by），停止拼 remark
• 2.2 运输计划 POST .../cancel：可选 body cancelReason，写 cancel_*
• 2.3 加油登记 cancel/restore：cancel 可选写原因；restore 清空三元组
• 2.4 充值 / 维保 / 尿素 apply cancel：可选 body + 落库
• 2.5 运费结算 cancel：可选 body + 落库
• 2.6 地磅 POST .../void：可选 body voidReason，写 void_*
• 2.7 Read/DTO 暴露原因字段（camelCase）；空原因不 400

3. Web Admin

• 3.1 抽取或复用作废原因对话框（原因选填，对齐调价函布局但去掉必填校验）
• 3.2 报价单列表/详情：可选原因；查看有则展示 invalid_*
• 3.3 运输计划列表/详情 + m/pl/plan：可选原因；查看展示
• 3.4 加油 / 充值 / 维保 / 尿素 / 结算：作废弹窗（选填）+ API 传参
• 3.5 地磅作废：弹窗选填 + 传 voidReason；查看展示
• 3.6 更新对应 web-admin/src/api 方法签名

4. Miniprogram

• 4.1 充值申请 list/form：可填作废原因（可空）后调 cancel
• 4.2 加油登记 list：同上
• 4.3 地磅 list：可填 voidReason（可空）后调 void
• 4.4 更新小程序 API 封装

5. Verification

• 5.1 各 cancel/void 无原因可成功；有原因可落库可查；time/by 均有值（2026-09-30 本地联调：fuel/plan/quote/weighing + 造数后 freight/维保/尿素/充值）
• 5.2 加油作废→恢复后三元组为空（本地联调通过）
• 5.3 Web + 小程序冒烟：选填原因、查看展示（Web Playwright：加油汇总有因/空因弹窗+请求体+落库；维保/尿素/运费页可打开。小程序代码已接线，未真机点测）
• 5.4 运行 graphify update / ./scripts/update-graph.sh（若本会话改了代码）