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
业务数据模型	已补活动 SKU、二次库存桥接和基础支撑表，待字段级评审	15
页面信息架构	已有页面树、编号和导航草案，待评审	17
页面与低保真规格	已有字段、状态和关键流程草案，待制作 Figma	18
API 契约	已有首版接口目录、错误码和幂等规则，待 G3 评审	19
事件、任务、权限和通知	已有首版技术设计，待 G3 评审	20
代码文件改造蓝图	已细化到五个项目和推荐文件，待 G4 评审	21
测试、验收、发布准备和使用教程	已有 G5 首版计划，待技术方案冻结后转正式用例	22

“已有草案”不等于已经冻结。当前最重要的工作不是按 21 创建文件，而是把 12、15、19、20、21 中标记为 G3/G4 的决定逐项评审并签字。

四、下一步正确顺序

第 1 步：业务规则评审

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

逐项评审：

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

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

第 2 步：页面信息架构

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

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

需要输出：

• 平台管理端新增菜单树和页面路由草案。
• 商户中心新增菜单树和页面路由草案。
• 用户端首页、农场专区、集市云仓和“我的”入口关系。
• 服务端/现场人员在 V1 复用哪些平台页，哪些需要移动录入页。
• 每个页面的使用角色、入口、退出路径和上下游页面。

第 3 步：低保真原型

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

优先画以下关键流程：

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

每个页面必须包含：

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

第 4 步：高保真与设计规范

建议使用由项目方持有的 Figma 团队项目，而不是个人临时文件。

高保真设计前必须先按 18-v1-page-and-prototype-spec.md 完成 CRMEB 视觉基线审计。目标是扩展现有系统，而不是重做后台框架或商城视觉；需要同时核对前端主题/组件和数据库中的菜单、主题、站点及装修运行配置。

Figma 文件建议分区：

• 00 Cover & Change Log
• 01 Information Architecture
• 02 Components & Tokens
• 03 Platform Admin
• 04 Merchant
• 05 User H5/Mini Program
• 06 Service/Mobile Entry
• 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 四端视觉基线、运行态主题和装修配置已审计，新页面无明显风格割裂。
• 正式数据库字段字典和 ER 图已评审。
• API 契约和错误码已评审。
• 代码新建/修改/重构文件清单已评审。
• 权限矩阵、事件、队列和定时任务已评审。
• 测试矩阵覆盖每条 P0 业务规则。
• 普通 CRMEB 能力回归范围已确认。
• 数据初始化、升级、回滚和上线验证方案已确认。
• 管理员、商户、现场人员、客服和用户说明目录已确认。
• 任务负责人、依赖和联调顺序已确认。