16 pre development design plan

开发前设计与评审计划

本文档用于控制“什么时候可以开始写代码”。V1 不以文档数量为完成标准，而以关键决策、页面、数据、接口、改造范围和验收用例能否相互对应为准。

一、总体原则

• 先确认业务事实，再画页面，再设计数据与接口，最后拆代码任务。
• 原型中的每个操作都要能找到业务规则、状态迁移、接口和权限依据。
• 数据表中的每个核心状态和金额字段都要能找到产生、修改和冲正场景。
• 开发任务中的每个文件改动都要能找到对应接口、页面和验收用例。
• 未完成上一阶段评审，不进入下一阶段实现。
• 当前阶段不把法律、税务和会计科目作为启动开发的阻塞项。

二、阶段与评审门

阶段	目标	必须产出	通过标准
G0 立项统一	大家理解同一个项目	总览、立项、角色、范围、底座审计	项目定位、V1 边界和复用范围无冲突
G1 业务定稿	核心规则可以逐条验收	决策清单、术语、流程、状态机、结算公式、异常规则	无影响主流程的开放问题
G2 产品与原型	所有角色知道如何操作	信息架构、页面清单、低保真、高保真、交互说明、空/错/加载状态	关键用户故事可完整走通
G3 技术设计	研发知道数据和服务如何协作	架构决策、数据库设计、API 契约、事件/任务、权限、错误码	状态、金额和库存能闭合
G4 代码改造蓝图	任务可准确分配到项目与文件	后端/各前端新增与修改文件清单、复用点、重构点、依赖和顺序	不再使用“开发时再看”描述核心改造
G5 测试与交付	上线标准可执行	测试矩阵、验收数据、回归范围、上线/回滚方案、使用教程目录	每条 P0 规则都有测试和责任人
G6 开发启动	正式进入实现	排期、负责人、分支规则、联调计划	G1-G5 已评审并冻结版本

三、当前完成度

内容	当前状态	主要文档
项目定位与端划分	已冻结并通过自主预审	00、01、02
CRMEB 能力与真实菜单基线	已形成	10、11
云仓核心决策	本轮定稿	12、13
租地/认养/溯源方案	本轮形成详细 PRD	14
结算与账本	本轮同步更新后进入评审	07、08、13
业务数据模型	90 张农业表、字段字典、索引、迁移分组和 ER 图已完成	15、34、36
CRMEB 视觉与运行配置基线	已完成运行态、源码、菜单、主题、DIY 和结构化 Figma 参考审计	23
用户端 uni-app 复用审计	已完成路由、DIY、主题、交易链路和组件复用矩阵	25
页面信息架构	四端页面树、菜单、编号和返回路径已冻结	17、30
Figma 文件与基础令牌	9 个页面、61 个变量、10 个文本样式、4 个高保真组件集和 45 个 Variant 已建立	18、23、45、Figma
页面与原型	四端 108 个低保真和 108 个高保真页面、15 条 Flow、60 个流程副本已通过自动审计	18、30、45、Figma
API 契约	P0 路由、字段 DTO、错误码、权限、幂等和写操作注册表已冻结	19、31、37
事件、任务、权限和通知	104 个事件、48 个任务及操作映射、重试和修复策略已冻结	20、32、33
代码文件改造蓝图	五项目文件、页面/API/权限/表/测试映射已冻结	21、35
测试、验收、发布准备和使用教程	421 个领域用例、663 个注册项、发布手册和五类教程已形成	22、38 至 44
G3/G4 决策登记	已结合专项验证和反向审计形成冻结基线；人工启动会确认留痕	24、29
持续目标治理	已建立唯一主清单、工作指引、活动队列和最终完成定义	26、27

开发前设计已完成 Codex 自主预审：业务、页面、数据、API、事件任务、文件蓝图、测试、教程、发布、工作包和 Figma 交付均已形成可执行基线。下一步不是直接散发代码任务，而是召开一次研发启动会，确认 RC-1、负责人和首轮 Ready 任务；人工签字不得由自动审计代替。

持续推进时，以 26-pre-development-master-checklist.md 的活动队列和完成证据为准，执行方式见 27-autonomous-project-work-guide.md。

四、下一步正确顺序

第 1 步：业务规则评审

参与人建议：项目负责人、产品、平台运营、农业运营、财务口径负责人、后端负责人、前端负责人、测试负责人。

逐项评审：

• 云仓首次购买与延后选择。
• 每个订单明细单一去向。
• 活动 SKU 批次与库存池。
• 二次零售的有效售出标准。
• 三种结算模式和累计差额公式。
• 到期回购和异常冲正。
• 商户首次供货货款。
• 租地真实地块分配。
• 认养单体/批次份额。
• 套餐交付数量、农业异常和溯源发布。

产出：对 12 决策清单逐条确认，未确认项不得隐藏在会议记录中。

第 2 步：页面信息架构

先完成页面与流程，不先追求视觉效果。

当前草案见 17-v1-information-architecture.md。

需要输出：

• 平台管理端新增菜单树和页面路由草案。
• 商户中心新增菜单树和页面路由草案。
• 用户端首页、农场专区、集市云仓和“我的”入口关系。
• 服务端不复制平台页：原 PC 客服页保留，农业查询使用独立桌面布局，任务、扫码和事实录入使用独立移动布局。
• 每个页面的使用角色、入口、退出路径和上下游页面。

第 3 步：低保真原型

页面级输入与 Prototype Flow 见 18-v1-page-and-prototype-spec.md。

优先画以下关键流程：

1. 云仓活动创建、活动商品配置和发布校验。
2. 用户抢购、付款、稍后选择、集中选择和超时自动代销。
3. 用户查看批次进度、分期账本、到期回购和最终结算。
4. 平台查看二次零售分配、批次进度和异常暂停。
5. 商户提交供货、查看入库验收和货款。
6. 用户租地选择套餐、支付、分配地块、看农事和收货。
7. 用户认养、查看个体/批次份额、看记录和收货。
8. 现场人员录入记录、产出和异常，运营审核发布。

每个页面必须包含：

• 正常状态。
• 空数据状态。
• 加载状态。
• 无权限状态。
• 校验失败和业务冲突状态。
• 售后、冻结或异常状态。
• 危险操作确认与结果反馈。

第 4 步：高保真与设计规范（已完成）

当前已使用由项目方持有的正式 Figma 文件，后续评审和版本冻结继续在该文件中完成。

CRMEB 源码、运行态、菜单、主题和装修基线已记录在 23-crmeb-visual-baseline-audit.md。目标是扩展现有系统，而不是重做后台框架或商城视觉。

用户端 uni-app 复用审计已记录在 25-user-uniapp-reuse-audit.md。每个新增页面的“现有页面模板 + 可复用组件 + 必须新增领域组件”映射、高保真和结构审计已经完成；登录态原始截图可在开发阶段补录用于像素级回看，不改变当前结构化视觉基线。

当前 Figma 文件：

SmartFarm V1 - CRMEB Baseline & Product Design

当前页面分区：

• 00 Cover & Change Log
• 01 Current CRMEB References
• 02 Components & Tokens
• 03 Platform Admin
• 04 Merchant
• 05 User H5 Mini Program
• 06 Service & Field
• 07 Prototype Flows
• 08 Handoff & Assets

已明确：

• 复用 CRMEB/Element UI/uni-app 现有组件的范围。
• 新增状态标签、进度、账本、时间线、批次和溯源组件。
• 桌面端和移动端响应式边界。
• 字段过长、金额、数量、百分比和多状态展示。
• 图片、视频、二维码、地图示意和报告预览。

第 5 步：数据模型评审

以 15-v1-data-model-draft.md 为起点，逐表确认：

• 表的唯一职责。
• 主键、外键式关联和业务唯一键。
• 状态、金额、数量、比例和快照。
• 写入时机、更新责任服务和删除策略。
• 索引、并发、事务和幂等。
• 历史数据、初始化和升级/回滚方式。
• 与 CRMEB 现有订单、退款、账单、库存的边界。

评审后形成正式 ER 图和字段字典，字段字典至少包含类型、长度、默认值、是否为空、索引、枚举、来源和备注。

第 6 步：API 契约

当前草案见 19-v1-api-contract-draft.md，事件、任务、权限和通知见 20-v1-events-jobs-permissions-notifications.md。

按“端 + 业务域”建立接口清单：

• 平台端农业资产、租地、认养、生产、溯源、云仓、结算接口。
• 商户端供货申请、入库验收查看、订单和货款接口。
• 用户端列表、详情、下单、选择去向、我的云仓、账本、租地认养和溯源接口。
• 服务端/现场端记录、产出、异常和履约接口。
• 内部事件、队列任务、定时任务和回调处理。

每个接口必须写：

• URL、方法、使用端和权限码。
• 请求字段、类型、必填、校验和示例。
• 返回字段、分页、状态码和示例。
• 业务前置状态与成功后的状态迁移。
• 幂等键和重复请求结果。
• 事务边界、失败回滚和错误码。
• 是否影响库存、金额、账本或外部服务。

第 7 步：代码改造蓝图

当前文件级草案见 21-v1-code-change-blueprint.md。

在不写实现代码的情况下，对五个项目逐项列出：

• 新建文件。
• 修改文件。
• 需要复用的现有类、组件和接口。
• 必须隔离的普通商城逻辑。
• 可能重构但不得改变既有行为的公共逻辑。
• 文件负责人、依赖任务和验收用例。

后端至少细化到：

• 路由。
• 控制器。
• Request/验证器。
• Repository。
• Service/领域服务。
• DAO。
• Model。
• 事件/监听器。
• 队列/定时任务。
• 权限菜单和配置。
• 数据升级与回滚脚本。

各前端至少细化到：

• 路由与菜单。
• 页面。
• API 模块。
• 状态管理。
• 公共组件。
• 表单与校验。
• 权限指令。
• 类型/常量/工具。
• 图片和静态资源。
• 埋点与错误提示。

第 8 步：测试与使用说明

当前 G5 首版计划见 22-v1-test-acceptance-release-manual-plan.md。

测试文档按业务事实组织：

• 正常主流程。
• 状态非法迁移。
• 库存并发和支付超时。
• 重复回调和任务幂等。
• 部分退款、全额退款和售后冲正。
• 节点跨越、到期未售和回购。
• 金额精度和批次尾差。
• 数据权限和越权。
• 农业资产重复分配和产出超分配。
• 溯源草稿、审核、版本和撤回。
• CRMEB 普通商品、普通秒杀、优惠券、订单、退款和商户财务回归。

使用说明分角色编写：

• 平台管理员配置与日常运营手册。
• 财务对账与异常处理手册。
• 商户供货、履约和结算手册。
• 农事/养殖/仓库人员操作手册。
• 客服订单、售后和云仓解释手册。
• 用户租地、认养、云仓选择和收益查看帮助。

五、评审记录模板

每次评审至少记录：

字段	内容
评审主题	对应文档和章节
文档版本	提交评审的版本
参与人	姓名与角色
已确认项	可进入下一阶段
待修改项	负责人和截止时间
新增决策	写回 12 决策清单
影响范围	页面、数据、接口、任务、测试
评审结果	通过、有条件通过、不通过
冻结时间	该版本何时成为基线

六、开发启动检查表

只有以下项目全部为“是”，才建议开始 V1 代码实现：

• P0 业务决策全部为已确认。
• 术语在所有文档中统一。
• 云仓、租地、认养和溯源状态机无断点。
• 正常、退款、售后、超时、滞销和农业异常都有处理方案。
• 平台端、商户端、用户端和服务端页面原型已完成自主预审。
• CRMEB 四端视觉基线、运行态主题、装修配置和结构化参考页已审计。
• 用户端 uni-app 页面、分包、公共组件、DIY 组件和交易链路复用矩阵已完成只读审计。
• 每个用户端新增页面已标记直接复用、扩展复用和必须新增的组件。
• 24 中 G3/G4 决策均已确认或记录替代方案。
• 正式数据库字段字典和 ER 图已完成自主预审。
• API 契约和错误码已完成自主预审。
• 代码新建/修改/重构文件清单已完成自主预审。
• 权限矩阵、事件、队列和定时任务已完成自主预审。
• 测试矩阵覆盖每条 P0 业务规则。
• 普通 CRMEB 能力回归范围已确认。
• 数据初始化、升级、回滚和上线验证方案已确认。
• 管理员、商户、现场人员、客服和用户说明目录已确认。
• 任务角色、依赖、估算和联调顺序已形成。
• 研发启动会完成五类角色人工确认、任务认领和 RC-1 留痕。