Skip to content

28 v1 requirement traceability matrix

Jump to bottom
技术老胡 edited this page Jul 30, 2026 · 1 revision

V1 需求全链路追踪矩阵

本文档把 12-v1-business-decisions-and-glossary.md 中的每条已确认业务决策，映射到页面、数据、API/事件、代码文件蓝图和测试。它用于发现“文档里提到了，但没有形成可实现、可验证闭环”的缺口。

当前版本：V1 技术反向冻结审计

当前结论：45 条业务决策均已建立六维追踪行；SPIKE-001 至 007 已完成；四端 108 个页面和 15 条跨端 Flow 已通过结构审计；90 张表、逐写操作、事件任务、状态异常、字段契约与专用测试已经完成反向冻结。高保真、教程和开发任务包属于后续交付门，不再改变本矩阵中的核心业务语义。

一、覆盖口径

维度 主要来源 完整标准
业务 B 12、13、14 决策、默认值、异常和历史快照明确
页面 P 17、18、25、30 使用角色、入口、字段、操作、状态和复用方式明确
数据 D 15、34、36 表、字段、约束、索引、关系、快照和事务明确
API/事件 A 19、20、31、32、37 字段契约、错误码、幂等、写操作、事件和任务明确
代码 C 21、35 新建、修改、复用、回归文件和页面链路明确
测试 T 22、33 正常、异常、并发、幂等、状态竞态和回归用例明确

“已映射”表示六个维度已有稳定入口；带“已验证/已冻结”的行还经过字段、状态或专项证据核对。最终开发启动仍以 26 的全部评审门通过为准。

二、云仓定位、商品与首次购买

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
CW-001 云仓定位 ADM-CW-001~004、USR-CW-001~005 cloud_activity、activity_product、activity_sku、batch cloud/activity/*、cloud/order/* CloudActivity、CloudOrder、云仓独立页面组 CW-ACT-001/007、CW-ORDER-001 已映射
CW-002 商品来源 ADM-CW-003/005/006、MER-CW-001~004 cloud_supply、activity_product、activity_sku 平台/商户 cloud/supply/*、活动商品及来源核验 API CloudSupply、CloudActivityPublishService、CloudSourceSkuMatcher CW-SUP-001~004、CW-ACT-004/007/010~014 已映射，SPIKE-001 已确认
CW-003 先抢购付款 USR-CW-002~004 farm_order_binding、cloud_order_item、库存流水、规则快照 order/check、order/create、CRMEB 支付、事务付款适配 CloudOrderCreateService、FarmOrderPaymentAdapter、CloudOrderPaidService CW-ORDER-001~014 已映射，SPIKE-002 已确认
CW-004 延后选择 USR-CW-004~006 cloud_order_item.choice_deadline_at、状态历史 pay_result、订单中心、提醒/到期任务 CloudOrderPaidService、CloudChoiceReminderJob CW-ORDER-009/010 已映射，低保真通过
CW-005 单一明细去向 USR-CW-006 cloud_order_item.disposition、版本号、持仓/履约 去向 preview/confirm CloudDispositionService、CloudDispositionValidate CW-DISP-001/008/009 已映射
CW-006 三种去向 USR-CW-006~008、SVC-CW-001/002 订单明细、运费单/退款单、持仓、履约 去向确认、补运费、自提凭证 CloudDispositionService、CloudFreightQuoteService、CloudFreightPaymentService、CloudPickup CW-DISP-001~007、CW-FREIGHT-001~018、CW-PICKUP-001~005 已验证，支付载体和页面状态矩阵已冻结
CW-007 选择时限 ADM-CW-003、USR-CW-005/006 活动 SKU 选择天数、订单明细截止时间 规则预览、订单详情、提醒/到期任务 CloudOrderPaidService、CloudChoiceExpireJob CW-ORDER-010、CW-DISP-010 已映射
CW-008 超时自动代销 ADM-CW-007、USR-CW-005/009 订单明细、持仓、状态流水 到期任务、去向结果查询 CloudChoiceExpireJob、CloudDispositionService CW-DISP-007/010 已映射
CW-009 邮寄运费 USR-CW-007 cloud_freight_order、cloud_freight_refund、地址/模板/金额快照 cloud/freight/*、pay_success_farm_cloud_freight、超时/修复/退款任务 CloudFreightQuoteService、CloudFreightPaymentService、CloudFreightRefundService CW-DISP-004~007、CW-FREIGHT-001~016、CW-REFUND-005 已映射，SPIKE-004 已确认

三、批次、二次零售与进度

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
CW-010 每活动 SKU 一批次 ADM-CW-003/008/009 稳定 activity_sku_id、cloud_batch、库存流水 活动 SKU、来源核验、批次列表/详情 CloudActivityPublishService、CloudSourceSkuMatcher、CloudBatchRepository CW-ACT-002/005/007/010~014 已映射，SPIKE-001 已确认
CW-011 截止后批次开售 ADM-CW-007~009、USR-CW-009/010 批次、持仓、resale_stock 批次准备、启动和补偿任务 CloudBatchStartService、CloudBatchStartJob CW-RESALE-001 已映射，活动库存闭合后才允许启动
CW-012 有效代销售出 ADM-CW-009/010、USR-CW-010 farm_order_binding、resale_allocation、batch_progress 二次订单付款/完成、观察期、退款事务适配与事件 FarmOrderPaymentAdapter、FarmOrderRefundAdapter、CloudResaleAllocationService、CloudProgressService CW-EFF-001~005/008、CW-RESALE-011/012 已映射，SPIKE-002 已确认
CW-013 FEFO 与按比例分摊 ADM-CW-009/010、USR-CW-010 farm_order_binding、resale_stock、resale_allocation、持仓 普通订单创建事务适配、分配释放/生效 CloudResaleAllocationService、FarmOrderCancelAdapter CW-RESALE-003~012 已映射，SPIKE-002 已确认
CW-014 三种结算模式 ADM-CW-003/009、USR-CW-010~012 活动 SKU 快照、进度、用户账本 规则详情、持仓进度、账本 API CloudUserSettlementService、CloudSettlementMode CW-SET-F-*、CW-SET-PF-*、CW-SET-PP-* 已验证，正向、跨节点和 75%→70% 逆向固定算例已冻结
CW-015 固定进度节点 ADM-CW-009、USR-CW-010 batch_progress、账本节点 holding/progress、节点任务 CloudProgressService、CloudMilestoneJob 三组结算节点用例 已映射
CW-016 默认结算模式 ADM-CW-003、USR-CW-002/010 activity_sku.settlement_mode 及订单快照 活动 SKU 编辑、规则详情 CloudActivityProductValidate、结算服务 三组结算模式用例 已映射
CW-017 周期和收益率快照 ADM-CW-003、USR-CW-002/003/010 活动 SKU、订单明细和持仓规则快照 活动 SKU 更新、订单创建、持仓详情 CloudActivityPublishService、CloudOrderCreateService CW-ACT-008、结算用例 已映射，快照版本/哈希/来源版本已冻结
CW-018 未抢完退来源库存 ADM-CW-004/009、MER-CW-003/004 供货、活动 SKU、库存流水 activity.ended → unpaid_closed → inventory_released/return_pending → inventory_closed CloudActivityInventoryCloseService、CloudActivityInventoryCloseJob、库存流水 Repository CW-ACT-009A~C 已映射，结束任务链已冻结

四、回购、商户货款与用户账本

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
CW-019 到期滞销回购 ADM-CW-011、USR-CW-010~012 cloud_buyback、持仓、用户账本、库存流水 回购列表/预览/执行、到期任务 CloudBuybackService、CloudMaturityJob、ExecuteCloudBuybackJob CW-BUY-001~006 已映射
CW-020 回购比例 ADM-CW-003/011、USR-CW-002/010 活动 SKU 和订单规则快照、回购 活动 SKU 编辑、回购预览 CloudBuybackService、FarmMoneyService CW-BUY-001~011 已验证，比例、宽限期、在途切割、原子回购和分钱尾差算例已冻结
CW-021 商户货款独立 MER-FN-001/002、平台商户账本/日结单 merchant_supply_ledger、merchant_supply_statement、financial_posting 账本、结单生成/入账和商户查询 API MerchantSupplySettlementService、MerchantSupplyStatementService、FarmMerchantBalancePostingService MER-SET-001~014 已映射，SPIKE-003 已确认
CW-022 商户结算条件 MER-CW-003/004、MER-FN-001/002 供货验收、首次完成时间、观察期、货款账本和结单 验收、首次订单事件、资格与每日结单任务 CloudMerchantEligibilityJob、MerchantSupplySettlementService、结单/入账服务 MER-SET-001~014 已映射，财务接口已确认
CW-023 低价差额平台承担 ADM-CW-009、USR-CW-010~012 二次分配确认金额、平台补贴、用户账本计算快照 二次订单生效和账本详情 CloudUserSettlementService、FarmMoneyService CW-EFF-007 已映射，平台补贴独立快照且不冲减用户应得
CW-024 平台券承担 ADM-CW-009、USR-CW-011/012 resale_allocation.platform_subsidy_amount、用户账本 二次订单优惠分摊事件 CloudResaleAllocationService、结算服务 CW-EFF-006 已映射
CW-025 运营成本由平台承担 ADM-CW-003/009 规则与对账说明 活动 SKU 平台分成、账本计算快照 规则详情和对账说明 CloudUserSettlementService、FarmMoneyService CW-COST-001~003 已验证，成本策略、批次成本和账本只读说明字段均已进入 15/34/37
CW-026 用户账本不为负 ADM-CW-009、ADM-FN-002/005、USR-CW-011/012 cloud_user_ledger、ledger_adjustment、financial_posting 待追偿状态 账本查询、冲正审核、正式入账与待追偿事件 CloudUserLedgerRepository、FarmFinancialReversalService、CloudReconciliationService CW-POST-008~010 已补齐余额不足冻结与后续抵扣口径
CW-034 回购人工审核 ADM-CW-011、ADM-FN-002/005、USR-CW-010/012 cloud_buyback、待回购池、用户账本、正式入账和平台库存流水 回购预案、审核、执行、重试与状态查询 CloudBuybackService、审核/执行权限、ExecuteCloudBuybackJob CW-BUY-001~011 已验证，计算、审核、所有权转入、账本和 Outbox 原子边界已登记

五、首次退款、补运费与完成时间

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
CW-027 批次前整条首次退款 USR-CW-005、平台订单详情 订单绑定、首次明细、库存流水、商户账本冲正 refund/check、refund/apply、拒绝/取消/完成事务适配 FarmOrderRefundAdapter、CloudRefundCompletedListener CW-REFUND-001~008 已映射，SPIKE-002 已确认
CW-028 补运费后邮寄生效 USR-CW-006/007 订单明细、运费单/退款单、履约和地址快照 去向确认、运费支付/结果/取消/退款结果 CloudFreightPaymentService、CloudFreightExpireJob、RefundCloudFreightJob CW-DISP-004~007、CW-FREIGHT-001~016 已映射，SPIKE-004 已确认
CW-029 三种首次完成时间 USR-CW-005/008/009、MER-CW-003 订单明细完成时间、履约/核销/持仓 收货、自提核销、批次启动事件 CloudOrderCompletedListener、商户资格任务 MER-SET-005、CW-PICKUP-001~005、去向用例 已验证，数量级完成事实与整体完成条件已冻结
CW-030 自提逾期人工协同 USR-CW-008、ADM-CW-007、SVC-CW-002 自提履约、异常事件和处理快照 pickup/resolve、服务端逾期处理 CloudPickup、CloudPickupOverdueJob、CloudException CW-DISP-011 已映射，异常低保真通过
CW-031 同批次周期与分成唯一 ADM-CW-003、USR-CW-002 activity_sku 规则及历史快照 SKU 更新、规则详情 CloudActivityProductValidate、发布服务 CW-ACT-008 已映射
CW-032 真实验收库存前置 ADM-CW-005/006、MER-CW-002~004 供货、验收量、活动占用和库存流水 供货验收、活动发布预检 CloudSupply、CloudActivityPublishService CW-ACT-004/007、CW-SUP-* 已验证，供货、来源库存、活动占用的加锁顺序和守恒式已冻结
CW-033 分成率合计 100% ADM-CW-003 活动 SKU 用户/平台分成基点 SKU 更新和发布预检 CloudActivityProductValidate、FarmMoneyService CW-ACT-003 已映射

六、租地与认养

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
LA-001 支付后分配真实地块 USR-LA-001~005、ADM-LA-002~006 farm、zone、plot、land_plan、land_order、plot_occupancy 租地目录、下单、支付结果、候选/预留/确认分配 LandOrderCreateService、PlotAllocationService LAND-001~007、LAND-ALLOC-001~004 已验证，字段、5 分钟预留、锁顺序和过期释放已冻结
LA-002 地块与占用周期分离 ADM-LA-005/006、USR-LA-005 plot、plot_occupancy 分配候选、确认和订单详情 PlotOccupancyRepository、PlotAllocationService LAND-001/002 已映射
LA-003 单体/批次份额认养 USR-AD-001~005、ADM-AD-002~006 animal_asset、breeding_batch、adoption_plan/order 认养目录、下单、候选/预留/确认分配 AdoptionOrderCreateService、AdoptionAllocationService ADOPT-001~006、ADOPT-ALLOC-001~004 已验证，单体唯一、份额容量锁和替换历史已冻结
LA-004 套餐按交付数量承诺 租地/认养详情、下单确认和权益详情 租地/认养套餐与订单规则快照 套餐发布、下单检查和订单详情 LandOrderCreateService、AdoptionOrderCreateService LAND-004、ADOPT-006 已补历史快照专用测试
LA-005 产出只邮寄 USR-LA-005、USR-AD-005、农业履约页 output_allocation、farm_fulfillment 产出履约、地址、运费和收货 API FarmFulfillmentService、用户端农业页面 LAND-007、ADOPT-005 已映射
LA-006 分批产出与邮寄 土地/认养详情、产出和履约列表 output_batch、output_allocation、farm_fulfillment 履约列表、创建、发货、收货 OutputAllocationService、FarmFulfillmentService LAND-005、ADOPT-004、FUL-001 已映射
LA-007 农业异常闭环 ADM-PD-007/008、服务端异常、用户权益详情 farm_exception_event、产出/履约/退款关联 异常列表、详情、审核、执行与通知 FarmExceptionService、FarmException LAND-006、ADOPT-003、FUL-002 已映射，异常低保真通过
LA-008 资产分配预留 ADM-LA-006、ADM-AD-006 plot_occupancy、adoption_allocation 的预留令牌、过期时间和版本 候选、预留、确认、释放和过期任务 PlotAllocationService、AdoptionAllocationService、FarmAllocationReservationExpireJob LAND-ALLOC-*、ADOPT-ALLOC-* 已验证，预留/确认/释放命令和过期任务已进入 31/32

七、溯源

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
TR-001 批次为主、单体补充 ADM-TR-001~004、USR-TR-001 trace_archive、生产/产出批次、动物资产 公开档案、订单详情和档案关联 TraceArchive、TracePublishService、用户 Trace TRACE-001/002、ADOPT-001 已映射
TR-002 完整溯源链路 生产详情、产出详情、溯源编辑和用户档案 生产事件版本、产出、材料、trace_link 唯一约束 提交、审核、发布、撤回和关联 API ProductionEventPublishService、TracePublishService PROD-*、OUTPUT-*、TRACE-002 已映射，关联唯一约束与发布事务已冻结
TR-003 草稿审核发布撤回与版本 ADM-TR-002/003、USR-TR-001 trace_version、trace_material、当前版本 版本保存、审核、发布、撤回、公开查询 TracePublishService、平台 TraceArchive PROD-001~003、TRACE-003/004 已映射

八、服务端与地图技术基础追踪

决策 页面/流程 主要数据 API/事件 代码蓝图 测试 审计状态
G3-CODE-006 复用客服身份 /kefu/entry、原客服和两个农业工作区 store_service、farm_service_profile /ser/login、farm/context Token 中间件加固、平台客服表单、farmContext Store SVC-AUTH-001~005 已映射，SPIKE-006 已确认
G3-SVC-001 PC/移动双入口 SVC-CM/CW/PD 全部页面 无独立业务数据 静态路由与上下文 两个 layout、三路由族、复用请求/Token SVC-UI-001~003、SVC-SCAN-*、SVC-DRAFT-* 已映射，桌面/移动低保真通过
G3-SVC-002 权限与对象范围 所有服务/现场页面 farm_service_scope、审计日志 权限中间件、Repository 范围断言 FarmServicePolicy、FarmServiceScopeRepository SVC-AUTH-006~011 已映射，权限与范围边界已确认
G3-SVC-004 现场证据附件 SVC-PD-003~007 farm_evidence_attachment 临时/绑定生命周期 farm/attachment/upload、业务提交绑定、清理任务 FarmAttachment、FarmEvidenceAttachmentService、现有 UploadService SVC-EVIDENCE-001~003 已映射，源码确认通用上传仅返回 URL
G3-SVC-005 平台对象范围 全部平台农业/云仓页面 farm_admin_scope、审计 路由权限后执行范围解析；越界统一不存在 FarmAdminScopeRepository/Service、各领域 Repository ADM-SCOPE-* 已映射，平台路由权限与数据范围已拆分
G3-CODE-009 核心副作用策略 云仓首次、二次商城订单、退款和取消 Flow farm_order_binding、状态迁移、库存/财务流水 支付、取消、退款事务适配点 FarmOrderPolicyResolver、三适配器、CRMEB 核心最小修改 ORDER-POLICY-*、普通商城回归矩阵 已映射，订单组级策略与插入点已冻结
G3-DATA-006 仓库/库位主数据 ADM-AG-003、ADM-PD-005/006、SVC-PD-005 farm_warehouse、farm_warehouse_location 农场详情主数据 API、验收/产出/履约引用 三层实体文件、Warehouse.php、详情标签组件 WAREHOUSE-* 已映射，不增加页面编号
G3-INV-003 供货库存生命周期 ADM-CW-005/006、MER-CW-001~004 拟供、审批、来源预留、送达、待检、验收、拒收/短缺、活动占用、退回/平台承接数量与流水 供货提交、审核预留、验收、拒收、释放和退回 API/事件 CloudSupplyRepository、供货审核/验收/库存流水服务 CW-SUP-*、库存守恒与并发预留用例 已映射，页面矩阵与字段已补齐
G3-SUP-001 责任方快照 ADM/MER-CW-002/004~006、履约/售后页 运费、质量、售后责任方建议与平台确认快照 供货提交、审核确认、履约 allowed_actions 供货快照、履约策略和商户范围校验 CW-SUP-013/014 已映射
G3-CODE-008 GIS 深度 ADM-AG-002~006/011/012、USR-AG-002/003、USR-CW-008、现场任务位置摘要 农场/区域/地块点位、farm_pickup_point、点位快照 后台 farm/map/*、农场公开位置、自提凭证 GeoPoint、FarmMapService、FarmMapPicker、FarmLocationCard、现场位置摘要 MAP-DATA-*、MAP-UI-*、MAP-FALLBACK-* 已映射，SPIKE-007 已确认
G3-EXT-001 腾讯地图边界 平台点选、用户导航、现场地址/可选地图 longitude/latitude/coordinate_system=GCJ02、客户端与服务端配置 地理编码/逆地址/建议、farm/context.map MapProviderInterface、TencentMapProvider、旧 LBS 兼容适配 MAP-API-*、MAP-SEC-*、MAP-LEGACY-* 已映射，供应商、密钥、超时与降级已确认
G4-UI-009 页面编号主数据 四端 108 个页面追踪对象 无业务表；页面目录与原型元数据 API 表引用 17/30 编号 路由、页面文件和任务卡引用统一编号 页面覆盖脚本、Figma Frame 命名检查 已映射，矩阵与 Figma Frame 名称一致
G3-CODE-010 云仓部分提货 USR-CW-008、ADM-CW-007、SVC-CW-002、SVC-PD-005 cloud_pickup、cloud_pickup_verification、订单明细数量汇总 CW_PICKUP_VERIFY、剩余量处理、数量级完成事件 CloudPickupService、三端 CloudPickup 控制器和现场核销页 CW-PICKUP-001~005 已验证，只复用一套核销接口和幂等事实
G3-CODE-011 到期在途与所有权切割 ADM-CW-009/011、USR-CW-010 批次宽限截止、切割版本、平台承接在途量、回购 CloudMaturityFinalizeJob、farm.cloud.batch.ownership_cutover CloudMaturityService、CloudBuybackService、批次消费者 CW-BUY-007~010 已验证，停止分配、宽限、切割和回购顺序已冻结
G3-DATA-007 逻辑外键 无新增页面 90 张表的 RID/CID、索引和生命周期 写操作预检、事务断言和对账修复 Repository/DAO/升级 verify 脚本 DB-REF-*、删除/作废/孤儿扫描 已验证，沿用现库无物理外键基线
G3-DATA-008 数量精度 云仓批次、持仓、核销和回购页面 实物 QTY、权益 EQTY decimal(20,6)、金额 MONEY 持仓、进度、回购公式快照 CloudProgressService、CloudBuybackService、FarmMoneyService CW-EQTY-*、CW-BUY-011 已验证，先批次金额池后最大余数分钱
G3-FIN-004 正常退款风险边界 ADM-CW-009、ADM-FN-002/005、USR-CW-011/012 未入账抵扣、未来应付抵扣、平台风险承担 二次退款适配、重算和对账事件 CloudUserSettlementService、CloudReconciliationService CW-REFUND-012、75%→70% 三模式算例 已验证，正常经营退款不直接借记用户余额
G3-FIN-005 农业异常退款 ADM-PD-007/008、USR-LA-005、USR-AD-005、USR-PD-001 服务/交付价值快照、累计未履约数量与退款 异常方案、用户确认、退款执行 FarmDeliveryRefundService、FarmExceptionService LAND-EX-*、ADOPT-EX-*、FUL-003~007 已验证，累计公式、等价替换、确认超时和短缺分配均已冻结

九、审计缺口关闭记录

缺口编号 关联决策 关闭结论 证据文档
TRACE-GAP-001 CW-025 平台成本策略、批次成本汇总和账本只读说明均已落入字段模型，不参与用户应得扣减 15、19、22、34、37
TRACE-GAP-002 CW-026 正常退款与错误入账已拆分；前者抵扣未入账/未来应付并由平台吸收不足，后者才使用受审冲正 08、13、15、19、20、22、29、33
TRACE-GAP-003 LA-004 租地和认养套餐均保存发布及订单快照，发布后修改不改变历史订单 14、15、22、34
TRACE-GAP-004 多条云仓决策 订单事务、正式入账、补运费支付/退款、部分提货、在途切割和回购原子边界全部关闭 13、15、19、20、22、24、29、31、32、33
TRACE-GAP-005 页面相关决策 四端 108 个页面、15 条 Flow 和页面/API/文件追踪集合一致 17、18、30、35、figma-state-smartfarm-v1.json、Figma
TRACE-GAP-006 全部决策 建立本矩阵为决策入口，并由 30~37 提供页面、写操作、事件、状态、字段和文件的稳定下钻 28、30、31、32、33、34、35、36、37
TRACE-GAP-007 G3-CODE-006、G3-SVC-001/002 服务端身份、范围、页面入口、逐写操作和字段契约均已关闭 15、17、18、19、20、21、22、24、29、31、37
TRACE-GAP-008 G3-CODE-008、G3-EXT-001 地图 Key 用途、GCJ02 字段、服务端超时、客户端降级和错误映射均已冻结 15、17、18、19、21、22、24、25、29、34、37

十、后续维护规则

  1. 12 新增或修改业务决策时，必须在本矩阵新增或更新对应行。
  2. 页面、API、文件任务和测试用例必须标注关联业务决策编号。
  3. 只有页面、数据、API、代码和测试五个下游维度都有正式证据，决策才可标记“全链路已验证”。
  4. 专项验证改变技术方案时，先更新 24，再更新本矩阵和受影响专题文档。
  5. 最终开发启动评审使用本矩阵检查是否存在空白单元格、临时描述或未关闭缺口。

十一、关联文档

SmartFarm 文档

Clone this wiki locally