Skip to content

24 g3 g4 decision register

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

G3/G4 技术与代码边界决策登记表

本文档集中登记 V1 在正式开发前必须确认的技术设计和代码边界。它不修改 12-v1-business-decisions-and-glossary.md 已确认的业务口径。

当前状态：G3/G4 技术方案已完成自主决策；正在执行跨文档一致性验收

一、状态说明

状态 含义
已有业务依据 业务规则已明确，技术方案仍需签字
建议冻结 当前有明显优选方案，建议按此进入详细设计
待专项验证 需要继续核对源码、数据或运行态后再签字
已确认 已按项目方自主决策授权完成技术冻结，可进入后续契约/任务编制；不等同于虚构人工签字
已否决 不再采用，需要记录替代方案

只有标记为“已确认”的条目才能进入任务分配；“已有业务依据”“建议冻结”和“待专项验证”都不能视为最终技术决定。

二、订单、支付、库存与优惠

编号 决策主题 建议基线 主要理由 状态
G3-ARCH-001 云仓首次购买的订单载体 独立云仓创建入口生成 CRMEB 订单三层记录和 farm_order_binding；复用支付/退款渠道；支付、取消、退款在核心事务内执行薄适配并写 Outbox 源码确认事后事件无法覆盖普通商户财务、取消和全部退款路径 已确认
G3-CODE-001 二次销售 SKU 建立平台二次代销映射 SKU，库存来源固定为 cloud_only；不得与普通库存混用，也不得与普通财务商品进入同一订单组 普通订单创建事务可原子锁定 FEFO 分配，订单组级财务与副作用策略保持单一 已确认
G3-CODE-002 首次云仓抢购优惠 V1 关闭优惠券、积分抵扣、会员价、分销佣金；只保留支付渠道 稳定本金快照、退款分摊和用户收益计算 已确认
G3-CODE-004 邮寄补运费 独立运费单以 attach=farm_cloud_freight 复用支付/退款驱动；余额支付本地原子处理；超时迟到支付全额退款 不改原本金订单，同时覆盖重复回调、金额校验和超时竞态 已确认
G3-INV-001 活动 SKU 稳定身份 云仓活动 SKU 使用独立主键和规则快照；CRMEB value_id、unique 仅作为来源同步标识 只读源码已确认商品保存会删除重建规格行，unique 也依赖商品 ID、类型和规格字符串 已确认
G3-INV-002 未抢完与代销滞销库存 活动未抢完数量先释放活动占用，再按供货归属退回平台或商户来源库存；商户实物在平台仓时完成退货/等价移交后才恢复来源可售库存；用户代销到期未售部分进入平台回购 区分活动未成交、实物归还和用户已购后滞销，避免账面先恢复但实物尚未回库 已确认
G3-INV-003 供货申请与库存流转 一张供货申请只关联一个来源 SKU；提交不动库存，审核通过后预占批准数量，验收合格量转云仓供货库存，短少/拒收/关闭按实物状态释放或退回 单 SKU 快照和逐阶段数量才能稳定审核、验收、活动占用、退款与对账 已确认
G3-SUP-001 云仓履约责任 供货申请由商户提出邮寄、质量和售后责任方，平台审核确认并保存结构化责任快照；履约页面和货款扣减只读该快照 自由文本无法驱动任务、权限、售后协同和责任扣减 已确认
G3-CODE-009 CRMEB 支付/取消/退款副作用分流 同一订单组策略必须一致；FarmOrderPolicyResolver 同时控制事务内和提交后副作用；取消在任何恢复前取得策略；退款在 executeRefund() 扣商户锁定款前分流 只跳过财务仍会错误触发积分、赠券、会员值、打印、短信、统计或重复库存恢复 已确认
G3-CODE-010 云仓部分提货 每次核销生成不可变事实，只推进本次实际核销量；剩余数量必须显式选择继续保留、改寄、退款或异常回购，不以覆盖原记录方式“改正” 同一持仓可能分次到场，覆盖式核销会破坏库存、首次完成时间和审计链 已确认
G3-CODE-011 到期在途与所有权切割 批次到期立即停止新分配；默认等待 30 天、可配 7 至 60 天处理已锁定在途；宽限结束写入所有权切割事实，之后未生效的在途结果归平台，再计算回购预案 必须先固定在途订单最终归属，才能得到唯一的未售等价数量和回购金额 已确认

G3-ARCH-001 的边界

建议落地关系：

CRMEB 订单/支付/退款
        │
        ├─ 承担交易载体、支付渠道和退款渠道
        │
        └─ 通过 farm_order_binding 声明策略
              ↓
farm 云仓订单扩展
        ├─ 活动 SKU 与批次
        ├─ 规则快照
        ├─ 去向选择
        ├─ 用户持仓
              └─ 本金/收益/回购账本

farm_order_binding 对每个订单明细固定 business_type、finance_policy、stock_policy 和 fulfillment_policy。cloud_primary 与 cloud_resale 均使用 farm_managed 财务策略，跳过普通商户锁定款和普通退款扣款；前者只处理活动库存，后者同时维护 CRMEB 镜像库存和云仓分配。普通订单未命中绑定时完全保持原行为。

同一 group_order_id 不得混合普通财务商品和 farm_managed 商品。CRMEB 的支付统计、赠券、会员值和部分提交后副作用按订单组执行，只限制单个子订单不足以隔离。详细源码证据和接入点见 29-g3-technical-spike-report.md。

不建议：

  • 把云仓全部字段直接塞进普通订单表。
  • 新建一套与 CRMEB 完全平行的支付、退款和订单中心。
  • 让普通秒杀控制器同时处理云仓状态。

G3-CODE-004 的边界

  • 不创建普通商城订单，不改原云仓商品订单金额，不参与商品优惠、佣金、商户货款和用户本金。
  • 当前用户端可用的微信、支付宝和余额支付可以使用；V1 不开放线下、扫码枪、组合支付和商户子账户收款。
  • 成功回调必须校验本地订单号、规范化金额、渠道交易号和去向版本，支付结果页只读取后端本地状态。
  • 超时后本地先回待选择或自动代销；迟到成功不改去向，只生成一张幂等全额退款单。
  • 支付和退款细节、文件影响及必测场景见 29-g3-technical-spike-report.md 第五节。

三、账本、结算与财务映射

编号 决策主题 建议基线 主要理由 状态
G3-CODE-003 用户结算入账账户 farm 业务账本经唯一 financial_posting 原子映射到 CRMEB 可用余额和 UserBill；目标账户必须行锁 现有 incBill 只写流水且无来源唯一键，专用桥接可同时保留计算依据和数据库幂等 已确认
G3-FIN-001 用户本金、收益、回购 三类账本分开记账、汇总展示，不合并成一个“收益”金额 本金返还、经营收益和回购补偿的产生条件不同 已确认
G3-FIN-002 商户云仓供货货款 供货账本满足条件后按自然日生成不可变结单，直接映射 mer_money 和 farm_supply_settlement 财务流水，不再进入全局冻结款 资格时间已包含业务观察期，二次冻结会重复等待；日结单便于对账和导出 已确认
G3-CODE-007 自动入账阈值 零差异且无冻结/退款/争议时，用户单笔 1万、日累计 5万、商户单结单 10万 内自动入账；超限和调整必须审核 正常小额自动化，大额与异常可追责；阈值只影响审核路径 已确认
G3-FIN-003 金额精度和尾差 金额统一使用分或定点十进制；按累计应结减累计已结计算本期，最后一笔吸收合法尾差 防止分期计算持续累积误差 已确认
G3-FIN-004 二次销售退款后的用户调整 正常退款先抵扣尚未正式入账金额，再抵扣同一持仓后续应结金额；仍有差额记平台经营风险，不直接扣用户可用余额；只有审核确认的错误入账或外部支付最终撤销才进入借方冲正 区分正常经营结果与错误资金事实，避免把平台销售风险转嫁为用户余额负数 已确认
G3-FIN-005 租地/认养异常退款基数 套餐价格拆分为生产服务价值与交付价值；生产开始前走普通退款，开始后只按未履约交付价值累计计算：累计应退 = 交付退款基数 × 累计未履约数量 ÷ 承诺数量，本次再扣历史已退和处理中退款 已完成的种养服务与尚未交付的实物责任不同，累计公式还能消除分批退款尾差 已确认

四、数据模型、事件与任务

编号 决策主题 建议基线 主要理由 状态
G3-DATA-001 生产批次建模 使用统一 production_batch 主表保存公共状态、对象和周期；种植、养殖差异放类型扩展表；可查询事实不只存 JSON 保持统一流程，又避免大量空字段和不可索引 JSON 已确认
G3-DATA-002 批次销售进度 业务事件实时推进汇总表；定时任务重算和对账；页面默认读汇总，不逐笔实时扫描全量订单 兼顾页面性能、实时性和可纠错性 已确认
G3-DATA-003 二次零售分配 普通订单明细插入后、创建事务提交前锁定云仓批次和分配记录；支付只推进原分配，退款按策略逆向释放或冲正 已确认 CRMEB 订单明细与普通库存处于同一创建事务 已确认
G3-DATA-004 事件可靠性 支付、取消、退款事务内写业务事实和 Outbox；提交后监听器、队列、定时任务使用幂等消费 源码确认 order.paySuccess/refund.agree 事后事件不足以作为原子事实 已确认
G3-CODE-005 数据升级规范 使用 install/upgrade/farm_v1 版本化 up/down/verify 脚本；事实产生后只关闭入口并保留扩展表 当前项目没有正式迁移框架，需要可分配、可验证且不删事实的升级规范 已确认
G3-DATA-005 删除与历史记录 核心订单、账本、批次、生产和溯源记录不物理删除；使用状态、作废、版本和冲正 财务和溯源事实需要完整历史 已确认
G3-DATA-006 仓库与库位 新增仓库/库位主数据和三层访问文件；平台 UI 放入 ADM-AG-003 农场详情标签页，不新增页面编号 产出、验收和履约已有仓库字段，必须有真实来源；收进农场详情可保持 108 个页面对象稳定 已确认
G3-DATA-007 表间参照完整性 农业扩展表沿用当前 CRMEB 数据库风格，不建立物理外键；所有引用字段建立必要索引，由 Repository/领域服务、事务锁、发布预检、对账任务和清理顺序共同保证逻辑外键 只读数据库核验当前业务库没有物理外键；强行混用会改变升级、删除和故障恢复方式 已确认
G3-DATA-008 实物数量与经济权益精度 云仓实物库存、占用、分配、核销数量使用非负整数；用户持仓的已售/未售/回购等价数量使用 decimal(20,6)；批次金额池先汇总后按最大余数法分到分，尾差同值时按 holding_id 升序 实物不能因比例分摊产生碎片，经济权益又必须表达按比例销售和回购 已确认

G3-DATA-001 推荐结构

eb_farm_production_batch
├─ 公共对象：农场、区域、地块/养殖资产、来源订单
├─ 公共周期：开始、预计结束、实际结束
├─ 公共状态：待开始、进行中、暂停、完成、异常
└─ 公共汇总：预计产出、实际产出、异常标记

eb_farm_production_plant_detail
└─ 作物、种植方式、面积、生长阶段等

eb_farm_production_livestock_detail
└─ 品种、个体/批次、饲养方式、生长阶段等

种植/养殖扩展表、权益关联、任务及版本表均属于 V1 必需数据对象，字段字典只细化类型、默认值和索引，不再决定是否落地。

五、权限、服务端与数据范围

编号 决策主题 建议基线 主要理由 状态
G3-CODE-006 服务端身份 复用现有客服账号、service Token 和 SerToken；新增农业档案、职责权限码和对象范围，不新增账号表 减少认证系统重复建设，同时补齐最小权限 已由 SPIKE-006 确认
G3-SVC-001 客服与现场页面承载 保留 /kefu/dashboard PC 客服壳；同项目新增 /kefu/farm/desk/* 与 /kefu/farm/work/* 两个独立布局 角色和安全边界清晰，同时避免新建第六个项目 已由 SPIKE-006 确认
G3-SVC-002 数据范围校验 路由校验权限码，Repository 每次按服务账号、职责、商户上限和对象范围重新校验；不只相信 Token 或前端上下文 防止调岗、范围变更和按 ID 越权 已由 SPIKE-006 确认
G3-SVC-003 高风险操作 结算、回购、规则修改、最终异常方案只在平台管理端完成；现场端只记录事实和建议 分离事实录入与财务/运营决策 已确认
G3-SVC-004 现场证据附件 复用现有 UploadService 存储驱动，新增 eb_farm_evidence_attachment 和绑定服务；农业接口返回附件 ID，通用客服上传保持原状 源码确认现有 Service::upload() 只返回 URL，不能表达对象范围、临时/绑定状态、完整性和清理 已确认
G3-SVC-005 平台管理员数据范围 CRMEB 路由权限之外新增 eb_farm_admin_scope 和 Repository 范围约束；超级管理员解析为显式 all 当前平台角色/菜单不直接表达农场、仓库和农业对象范围，只有路由权限无法阻止按 ID 越权 已确认

如果后续确认现场端需要离线、原生扫码、蓝牙设备或独立发布节奏，再评估拆分独立应用；这些不是 V1 默认前提。

六、地图、设备与第三方能力

编号 决策主题 建议基线 主要理由 状态
G3-CODE-008 GIS 深度 V1 保存农场和自提点 GCJ02 点位，区域/地块以继承点位和示意图为主；不开发专业多边形 GIS 编辑器 真实点位已满足展示、导航和分配说明，面积与容量由业务记录而非地图几何计算 已由 SPIKE-007 确认
G3-EXT-001 地图服务 V1 统一腾讯地图，代码保留 Provider 抽象；客户端展示 Key 与服务端 WebService Key/SK 分离，新业务只使用 longitude/latitude/coordinate_system 与现有管理端、uni-app 和配置一致，并避免旧坐标字段继续扩散 已由 SPIKE-007 确认
G3-EXT-002 IoT 设备 V1 数据模型预留设备与读数关联；租地、认养、云仓主流程不依赖实时设备接入 防止第三方设备阻塞核心闭环 已确认
G3-EXT-003 支付、物流和短信 优先复用 CRMEB 已接入能力；领域层经适配器调用，通道不可用时保留站内状态、人工物流和异步补发；只有现有接口无法覆盖时才新增供应商 只读源码已确认支付驱动、快递/面单和短信/微信模板抽象均存在 已确认
G3-EXT-004 现场二维码识别 smartfarm_service 候选精确锁定 @zxing/browser@0.1.5 + @zxing/library@0.21.3，写依赖前做旧构建链隔离 Spike；后端统一解析/验签并始终保留图片/手工输入 较新版本已提高 peer 基线，旧 Vue/Webpack 项目先验证；扫码失败不能阻塞核心作业 已确认

以上第三方能力的生产供应商、额度与开通配置属于发布准备事项；当前阶段只冻结适配器、降级和安全边界，不默认新增付费服务。

地图补充边界：

  • 新农业业务坐标系固定为 GCJ02，经纬度使用 decimal(10,7)，必须同时为空或同时有值。
  • 农场与统一自提点启用前必须配置真实点位；内部地块、栏舍和仓库精确位置默认不向用户公开。
  • 用户端导航不依赖获取用户当前位置；定位权限只用于后续可选的距离能力。
  • 地图不可用时保留地址、示意图、复制和手工坐标降级，不能阻断已有交易或现场作业。
  • 生产 Key、额度与商业授权是发布前环境门；当前不默认购买付费服务。

七、前端、Figma 与组件复用

编号 决策主题 建议基线 主要理由 状态
G4-UI-001 全局视觉主题 保持各端当前 CRMEB 运行主题；用户端以红 #E93323、橙 #FF7612 为基线，服务/现场端沿用蓝 #1890ff，管理端和商户端复用各自 Element UI 变量，不做全局农业绿色替换 避免与现有商城、客服端和装修割裂 已确认
G4-UI-002 云仓菜单位置 平台和商户均放在“营销”下，作为与普通秒杀并列的独立业务组；商品列表可提供快捷入口 既符合活动运营习惯，又避免与普通秒杀混表 已确认
G4-UI-003 普通秒杀复用 复用场次、倒计时、活动氛围、列表和反馈模式；不复用普通秒杀状态、库存、订单和结算语义 云仓是“先付款后选去向 + 持仓 + 二次代销” 已确认
G4-UI-004 用户端组件策略 uni-app 审计已完成；每个新页面必须给出现有页面模板、可复用组件、扩展组件和新增领域组件映射 防止重复写商品、订单、支付和地址组件 已确认
G4-UI-005 Figma 设计顺序 先做当前参考、令牌和低保真；组件复用映射通过后才做高保真 设计应由现有系统约束，不反向要求源码适配模板 已确认
G4-UI-006 Figma 变量代码映射 --view-theme、--view-priceColor 标为现有；--sf-* 只作为建议交接命名，开发前仍需确认是否落地 避免把设计令牌误认为已实现变量 已确认
G4-UI-007 当前装修缺陷 “种草社区”错误指向秒杀页面作为独立修复任务，不并入农业业务需求 保持新需求与现状缺陷范围清晰 已确认
G4-UI-008 用户端分包 租地/认养/溯源使用 pages/farm；云仓使用独立 pages/cloudWarehouse 分包；不进入主包 云仓与农业资产职责不同，且页面数量足以独立控制包体积 已确认
G4-UI-009 页面编号与归属 17-v1-information-architecture.md 是页面编号主目录，30-v1-p0-page-matrix.md 是字段/动作/状态主表；API、代码蓝图、Figma Frame 和任务卡只能引用，不得另行发明编号 消除列表/详情、工作台/抽屉在多文档中的编号漂移 已确认

补充交互边界：

  • 租地和认养产出在 V1 用户端只提供邮寄履约，不出现自提或代销动作。
  • 云仓首次购买才提供邮寄、自提和代销三种去向；SVC-PD-005 中的核销能力仅服务云仓自提任务。
  • 去向、核销、异常确认等高风险动作均以服务端 allowed_actions 为准，前端隐藏按钮不能替代后端权限和状态校验。

视觉事实和 Figma 文件见 23-crmeb-visual-baseline-audit.md。

八、需要专项验证的技术事实

以下项目先做只读核验或技术试验设计，不直接写业务功能：

编号 验证内容 输出 状态
SPIKE-001 CRMEB 商品规格编辑、复制、删除后 value_id、unique 的变化 活动 SKU 来源同步和失效告警规则 已完成
SPIKE-002 普通订单创建、支付、退款的最小扩展点 G3-ARCH-001 的最终类和事务边界 已完成
SPIKE-003 CRMEB 余额与商户账单的可复用入账接口 统一入账桥接、两类账户事务、商户日结单和金额扩容 已完成
SPIKE-004 现有支付单是否适合补运费 独立云仓运费单、attach 回调、余额事务、迟到退款和代码边界 已完成
SPIKE-005 uni-app 公共组件、DIY 组件、分包和普通秒杀链路 用户页面复用矩阵和 Figma 组件范围 已完成
SPIKE-006 服务端认证、路由和移动布局可行性 复用客服身份、账号加固、农业权限/范围、PC/移动双入口与文件蓝图 已完成
SPIKE-007 地图组件在 H5、微信小程序和管理端的兼容性 腾讯地图、GCJ02、统一字段、密钥隔离、降级和文件边界 已完成

专项验证不是业务开发。验证结果必须写回本文件和对应数据/API/代码蓝图。

SPIKE-001、SPIKE-002、SPIKE-003、SPIKE-004、SPIKE-006、SPIKE-007 的源码、数据库或运行态证据及冻结规则见 29-g3-technical-spike-report.md。SPIKE-005 的结论见 25-user-uniapp-reuse-audit.md。当前七项专项验证已全部完成。

九、建议确认顺序

  1. 建立四端 P0 页面字段、操作、状态、权限和组件复用矩阵。
  2. 完成 P0 低保真流程，验证云仓、租地认养、现场作业和异常处理能完整走通。
  3. 用低保真结果校准 15、19、20、21 的字段、契约、任务和文件依赖。
  4. 逐项把仍为“建议冻结”的 G3/G4 条目改为已确认或记录替代方案。
  5. 通过 G3/G4 评审后进入高保真、正式任务包和排期。

十、签字表

编号 最终结论 状态 确认人 日期 影响文档
G3-ARCH-001 CRMEB 订单承载交易，农业绑定与事务薄适配承载业务策略 已确认 Codex（项目方授权自主决策） 2026-07-30 15、19、21、29
G3-CODE-001 至 011 按本文件现行代码接入、库存、履约、回购与副作用边界执行 已确认 Codex（项目方授权自主决策） 2026-07-30 15、19、20、21、29、31、32
G3-INV-*、G3-SUP-* 按单 SKU 供货、数量生命周期和责任快照执行 已确认 Codex（项目方授权自主决策） 2026-07-30 13、15、19、21、34
G3-DATA-001 至 008 采用统一批次、逻辑外键、整数实物数量与小数等价权益模型 已确认 Codex（项目方授权自主决策） 2026-07-30 15、20、33、34、36
G3-FIN-001 至 005 用户、商户、平台三方账本及异常退款口径按现行规则执行 已确认 Codex（项目方授权自主决策） 2026-07-30 07、08、13、14、15、19、22
G3-SVC-001 至 005 复用客服身份，按职责、权限码和对象范围提供桌面/现场入口 已确认 Codex（项目方授权自主决策） 2026-07-30 02、17、18、19、21、29
G3-EXT-001 至 004 复用现有支付、物流、短信、上传和腾讯地图，二维码先隔离验证 已确认 Codex（项目方授权自主决策） 2026-07-30 14、19、21、22、29
G4-UI-* 按 G4-UI-001~009 现行基线执行；低保真已验证菜单归属、跨端视觉、页面编号与组件复用边界 已确认 Codex（项目方授权自主决策） 2026-07-30 17、18、21、23、25、30、Figma

十一、G3/G4 通过条件

  • 每个“建议冻结”条目已改为“已确认”或记录替代方案。
  • 每个“待专项验证”条目有事实报告和结论。
  • 数据模型、API、事件任务和代码文件蓝图使用同一决定。
  • 用户端每个新增页面都有组件复用映射。
  • 服务端 PC 客服、农业桌面与移动现场入口边界无冲突。
  • 普通商品、普通秒杀、订单、支付、退款和财务回归点明确。
  • 没有用“开发时再看”代替核心库存、金额和状态决定。

十二、关联文档

SmartFarm 文档

Clone this wiki locally