Skip to content

45 v1 design handoff

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

SmartFarm V1 设计交付与研发交接规范

状态:设计交付已完成 Codex 自主预审;人工研发启动评审待项目团队执行

更新时间:2026-07-30

本文规定 SmartFarm V1 如何从已完成的四端低保真进入 CRMEB 风格高保真,并把页面、组件、状态、接口、权限、文件和验收证据无歧义交给研发与测试。本文是交付方法和验收规范,不替代业务规则、页面字段、API 契约或代码蓝图。

一、交付目标与当前事实

1. 最终交付目标

每个 P0 页面在进入开发前都必须回答:

  1. 页面为谁使用、从哪里进入、如何返回。
  2. 首屏展示什么,完整字段、筛选、编辑和只读快照是什么。
  3. 当前状态允许什么操作,权限、对象范围和 allowed_actions 如何共同生效。
  4. 加载、空、错误、无权限、冲突、冻结、异步处理中如何表现。
  5. 页面复用哪个 CRMEB 页面、组件和视觉令牌,哪些才是新增领域表达。
  6. 页面调用哪些 API,写操作如何处理版本、幂等、进度和结果刷新。
  7. 前端页面、API 文件、后端 Controller、Service 和主要数据对象分别落在哪里。
  8. 设计、开发和测试分别以什么证据证明交付完成。

2. 当前 Figma 事实

正式文件:

SmartFarm V1 - CRMEB Baseline & Product Design

当前状态以 figma-state-smartfarm-v1.json 为准:

项目 当前事实
顶级页面 已建立 0008 共 9 个页面
基础令牌 已建立 3 个变量集合、61 个变量和 10 个文本样式
低保真页面 平台 55、商户 10、用户 29、服务端 14,共 108 个
高保真页面 平台 55、商户 10、用户 29、服务端 14,共 108 个;统一使用 HF-{页面编号}
Prototype 15 个 Flow 画板、60 个同页高保真流程副本、15 个唯一 Flow 起点
结构审计 高保真重名、错误尺寸、重叠、占位文案、缺失字体和流程连线问题均为 0
当前阶段 design-handoff-complete
高保真组件 ButtonStatusTagProgressBarDomainCard 共 4 个组件集、45 个 Variant
正式交接标注与资产包 08 Handoff & Assets 已建立 6 个交付区,根节点 59:2
四端运行态参考 01 Current CRMEB References 已完成结构化运行态与源码/数据库审计基线;不冒充浏览器原始截图
项目方人工业务评审 待完成

机器审计和 Codex 自主预审不替代项目团队的产品、设计、前端、后端和测试签字。它们证明交付物已达到可评审、可分配和可追踪状态。

现有 Figma 页面节点:

页面 节点 ID
00 Cover & Change Log 0:1
01 Current CRMEB References 1:2
02 Components & Tokens 1:3
03 Platform Admin 1:4
04 Merchant 1:5
05 User H5 Mini Program 1:6
06 Service & Field 1:7
07 Prototype Flows 1:8
08 Handoff & Assets 1:9

现有低保真母版节点只用于恢复和结构追踪,不得直接当作高保真组件交付:

低保真对象 节点 ID
LF/Desktop Shell 16:6
LF/Desktop Data Region 19:6
LF/Mobile Shell/Terminal=User 20:6
LF/Mobile Shell/Terminal=Service 21:2
LF/State Panel/State=Empty 23:6
LF/State Panel/State=Loading 23:12
LF/State Panel/State=NoPermission 23:16
LF/State Panel/State=Conflict 23:22
LF/State Panel/State=Error 23:28

状态账本中的 pendingValidations=[] 仅表示该次结构化写入没有未完成的机器校验项,不表示人工业务、视觉、交互或交接验收已经完成。

二、事实来源与冲突处理

设计工作按以下主数据分工执行:

内容 唯一主来源
业务规则与默认值 12-v1-business-decisions-and-glossary.md
技术和 UI 决策 24-g3-g4-decision-register.md
页面编号、名称、导航与归属 17-v1-information-architecture.md
页面结构、关键交互和原型要求 18-v1-page-and-prototype-spec.md
CRMEB 四端视觉事实 23-crmeb-visual-baseline-audit.md
用户端 uni-app 复用边界 25-user-uniapp-reuse-audit.md
108 页字段、动作、状态和复用 30-v1-p0-page-matrix.md
页面、API 和代码文件映射 35-v1-page-api-file-trace.md
请求、响应和字段类型 37-v1-api-field-contract-registry.md
真实角色任务与页面用语 3841 四类设计态手册
Figma 节点、数量和当前完成状态 figma-state-smartfarm-v1.json

冲突处理:

  1. 不在 Figma 中临时决定业务规则。
  2. 页面名称或编号冲突时以 17 为准。
  3. 字段、动作或状态冲突时以 3037 为准,并回查 12
  4. 视觉建议与当前 CRMEB 运行态冲突时,以运行态和 23/25 的审计事实为准。
  5. 设计评论只能记录问题,最终决定必须写回对应主文档。
  6. 尚未在源码存在的变量、组件、页面和文件必须标为 建议/待实现,不得标为 现有

三、CRMEB 视觉继承原则

1. 必须继承

  • 平台与商户端继续使用 Vue 2、Element UI 和当前 CRMEB 后台壳的侧栏、顶栏、面包屑、标签页、筛选、表格、分页、表单、抽屉和弹窗节奏。
  • 用户端继续使用当前 uni-app 的导航、DIY 首页、商品、秒杀、价格、订单、支付、地址、物流、售后、空态和安全区风格。
  • 原客服页继续保持桌面三栏工作台;农业桌面和移动现场页复用服务端蓝色、请求、上传、图标和反馈基础。
  • 普通商品、普通秒杀、普通订单和原支付链路的视觉与行为不得被云仓状态覆盖。
  • 状态、金额、数量、长编号和异常必须沿用现有信息密度,不制作另一套“农业品牌后台”。

2. 禁止事项

  • 不把全站红橙或后台主题统一替换成农业绿色。
  • 不整体重做 CRMEB 后台壳、底部导航、字体或图标体系。
  • 不套用 Figma 社区模板后要求现有系统适配模板。
  • 不使用大面积营销 Hero、装饰渐变、漂浮装饰、超大圆角或卡片嵌套卡片。
  • 不把普通秒杀页面仅改标题后当作云仓页面。
  • 不重复绘制或开发第二套图片、价格、空态、地址、支付、物流和普通订单基础组件。
  • 不把桌面表格压缩后直接当作移动现场页面。
  • 不用颜色作为状态的唯一信息载体。

3. 视觉基线值

主基线 页面与控件
平台端 当前管理端主题;代表性蓝 #4073FA,不是强制全局硬编码 背景约 #F3F5F7,正文 14px,辅助信息 12px~13px,常用圆角 4px
商户端 当前商户端 CRMEB/Element UI 主题 保持紧凑筛选、表格、弹窗、批量操作和 selCard 节奏
用户端 当前运行主题主色 #E93323、辅助色 #FF7612 背景 #F5F5F5/#F8F8F8,卡片圆角 16rpx~24rpx,常用间距 20rpx~30rpx
服务端 当前 Element UI 蓝 #1890FF 桌面白色主面板;移动现场单列、稳定底部操作区

Figma 使用 Noto Sans SC 只作为协作字体;运行端继续服从现有系统字体。不得以 Figma 字体替换为前端全局字体作为设计验收条件。

四、四端设计基线

1. 平台管理端

  • 主视口:1440x900;紧凑验收:1280x800
  • 页面外壳、菜单、面包屑和标签页直接继承现有管理端。
  • 列表为主要工作界面,信息密度优先于装饰。
  • 详情页顶部使用业务编号、状态、关键量和主操作摘要,主体使用标签页。
  • 农业工作台只聚合待办和下钻,不制作营销型仪表盘。
  • 地图、库存池、账本公式、回购步骤和农业关系链可以新增领域组合组件。

2. 商户中心

  • 主视口:1440x900;紧凑验收:1280x800
  • 保持平台端同一 CRMEB 设计语言,但只展示当前商户数据。
  • 供货、履约、货款和异议进入现有商品、营销、订单和财务工作流。
  • 不显示用户持仓占比、用户本金/收益或平台二次零售利润。
  • 工作台只增加当前角色待办,不新建另一套后台首页。

3. 用户 H5/小程序

  • 主视口:390x844;必验视口:375x812
  • 同一业务状态同时适配 H5 和微信小程序,不复制两套业务页面。
  • 小程序验证胶囊导航、顶部安全区、分享和支付回跳;H5 验证浏览器历史、微信内授权和返回栈。
  • 不新增第六个永久底部 Tab。
  • 租地、认养、溯源进入 pages/farm 分包;云仓进入 pages/cloudWarehouse 分包。
  • 所有固定底栏、弹层和核销码避开 safe-area-inset-bottom

4. 服务/现场端

  • 原客服:保留 /kefu/dashboard 桌面三栏,不进行移动压缩改造。
  • 农业桌面:1280x8001440x900,用于订单查询、异常协同和审核。
  • 移动现场:主视口 390x844,同时验收 360x800430x932
  • 移动页面使用单列摘要和固定提交区,触控目标最小 44px
  • 桌面表格在移动路由必须改为摘要列表,不允许横向缩放桌面表格。
  • 离线仅保存本机草稿,不把离线保存展示为提交成功。

五、响应式断点与布局行为

断点是设计验收口径,不要求脱离现有工程另建一套 CSS 框架。

名称 宽度 必须验证 布局规则
desktop-wide >=1440px 平台、商户、农业桌面 使用完整筛选、表格和详情区域
desktop-compact 1280px~1439px 平台、商户、农业桌面 收紧非关键间距;筛选可折叠;操作列不遮挡数据
desktop-below-min <1280px 桌面端降级 保留合理最小宽度或局部横向滚动,不把表格字段压成不可读
mobile-compact 360px~374px 现场端必验,用户端冒烟 长词、金额、底栏和弹层不得溢出
mobile-base 375px~429px 用户端和现场端主验收 单列内容、稳定头部和安全区
mobile-wide 430px~767px 现场端必验 内容可放宽但不变成桌面双栏

通用规则:

  • 不使用按视口连续缩放的字体。
  • 文本字号不因宽度变化而跳动;优先换行、截断和展开。
  • 固定格式组件使用明确宽高、比例或网格轨道,避免状态变化引起页面抖动。
  • 同一按钮的“待处理/处理中/成功/失败”保持稳定尺寸。
  • 桌面与移动是端能力边界,不通过隐藏关键字段假装完成响应式。

六、Figma 文件组织与命名

1. 顶级页面

继续使用现有 9 页,不新增同义页面:

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

2. Section 结构

业务页面内统一分为:

00 Index
10 Low Fidelity
20 High Fidelity
30 States & Overlays
40 Review Evidence

平台端在 Section 内再按 CM/AG/LA/AD/PD/TR/CW/FN 分组。不得通过新建顶级页面改变 17 的页面归属。

3. Frame 命名

现有低保真 Frame 保留 LF-{页面编号}-{页面名称},不批量改名破坏状态账本节点。

高保真 Frame 固定使用:

页面编号 / 页面名称 / 状态键 / 视口

示例:

USR-CW-006 / 云仓去向选择 / ready / Mobile 390
ADM-CW-009 / 云仓批次详情 / running / Desktop 1440
SVC-PD-003 / 新增过程记录 / offline-draft / Mobile 390

状态键使用小写英文 kebab-case,展示文案继续使用中文。禁止使用 最终版2新页面改后 等不可追踪名称。

4. Overlay 与子状态命名

页面编号 / Overlay / 组件或动作 / 状态键
页面编号 / State / 状态键 / 视口

示例:

ADM-CW-011 / Overlay / 回购审核 / precheck-failed
USR-CW-007 / State / late-payment-refunding / Mobile 390

5. 组件命名

新增高保真组件使用:

SF/{端}/{领域}/{组件}

示例:

SF/Admin/Cloud/InventoryPools
SF/User/Cloud/BatchProgress
SF/Service/Field/EvidenceUploader

Variant 属性使用稳定枚举:

State=Default|Loading|Disabled|Error
Size=Small|Medium|Large
Terminal=Admin|Merchant|User|Service

现有 CRMEB 组件参考不得伪装为已经建立的 Figma 主组件。SmartFarm 只新增以下农业领域扩展组件,普通按钮、表格、订单、支付、地址、物流和售后继续复用 CRMEB:

组件集 节点 ID Variant 代码交接方向
Button 46:26 12 仅用于统一桌面/移动设计状态;研发优先复用各端现有按钮
StatusTag 46:50 10 对应各端现有 Tag/状态文本,补农业状态语义
ProgressBar 46:99 15 组合现有进度基础,表达批次、任务、结算和预警
DomainCard 47:66 8 用户/现场端农业图片卡;组合现有图片、文本和状态组件

6. 变量与样式命名

变量使用语义名,不以某个页面命名:

color/{terminal}/{semantic}/{state}
space/{scale}
radius/{terminal}/{scale}
size/control/{terminal}/{scale}

代码映射必须带来源:

类型 处理
现有运行变量 标记 Existing,例如 --view-theme--view-priceColor
Element UI/项目现有值 标记 Existing Source,记录现有主题或组件来源
Figma 语义别名 标记 Design Alias,绑定现有值
--sf-* 一律标记 Proposed;未进入代码前不得写成现有变量

不得为每个页面重复建立颜色和文本样式。当前设计系统审计结果:

集合 数量 用途
SF / Color Primitives 22 CRMEB 红橙、后台/服务蓝、灰阶和状态基础色
SF / Semantic Color 24 动作、画布、表面、文字、边框、状态软背景和侧栏别名
SF / Layout 15 间距、圆角和桌面/移动控件尺寸

文本样式共 10 个,覆盖 CRMEB 桌面标题/正文/控件/说明和移动标题/正文/价格。设计协作字体为 Noto Sans SC;运行端仍服从现有项目字体,不要求全局替换。

七、页面状态与反馈规范

1. 每页最低状态集

状态键 页面表现 操作要求
loading 骨架或稳定局部加载区 不闪现敏感数据,不引起布局跳动
empty 说明业务为何为空 只展示有权限的下一步
filtered-empty 保留当前筛选 提供重置筛选
error 显示稳定错误摘要 支持重试,表单内容不丢失
no-permission 不渲染业务数据 提供返回可访问入口
read-only 展示状态和原因 不显示可提交的伪按钮
conflict 提示版本或业务状态已变化 刷新对象后重新确认
duplicate-result 展示首次幂等结果 不重复创建
dependency-degraded 地图、物流、上传等降级 保留不依赖外部能力的主流程
frozen 显示冻结对象、原因和处理入口 禁止非法动作
partial-result 展示逐项成功/失败 仅用于契约明确允许逐项原子的操作
historical 明确历史快照和版本 不用当前配置覆盖历史

2. 页面权限

  • 无页面权限:整页不渲染业务数据。
  • 有页面、无动作权限:页面可读;动作隐藏或禁用的方式服从现有 CRMEB 模式。
  • 有权限但对象不在范围:不得泄露对象存在性。
  • 页面按钮必须同时服从路由权限、对象范围、对象状态和响应 allowed_actions
  • 设计稿中的按钮可见性只是表现规则,不能替代后端校验。

3. 异步进度

返回 AsyncAccepted 的动作必须进入统一进度表达,不使用长时间无结果的按钮 Loading。

进度区至少展示:

  • operation_no 和操作类型。
  • 当前状态。
  • progress_done / progress_total
  • success_count / failure_count
  • 开始时间、完成时间。
  • 结果摘要、错误码和结果文件入口。
  • 当前 allowed_actions

等待、运行、成功、部分失败和失败均需视觉样态;最终 API 枚举以 37 和状态矩阵为准,不在 Figma 发明新状态码。详情入口使用四端各自的 farm/operation/detail/:operation_no 鉴权结果。

4. 支付与资金状态

  • 前端支付组件返回不等于支付成功,支付结果页必须查询后端本地状态。
  • 预计待结算待审核入账中已入账冻结冲正不得合并成一个状态。
  • 正负金额必须同时有符号、类型和文字,不只用红绿。
  • 回购不得把真实销售进度画成 100%。

八、桌面表格、表单、抽屉与弹窗

1. 表格

  • 使用现有 el-table 密度、表头、分页和选择行为。
  • 常用筛选保持一行,更多筛选折叠;查询失败保留筛选值。
  • 业务编号可复制并进入详情;长编号默认单行截断,Tooltip 展示完整值。
  • 操作列固定在右侧;高频动作使用图标和 Tooltip,低频动作进入菜单。
  • 批量操作只在选中数据后出现,并明确是否逐项原子。
  • 金额右对齐,数量和比例使用统一格式;状态列同时显示文字。
  • 宽度不足时优先保留对象、状态、关键金额/数量和操作,辅助列进入列设置或详情。
  • 从详情返回必须保留页码、筛选、排序和滚动位置。

2. 表单

  • 使用现有 el-form、标签宽度、必填标识和字段内错误。
  • 长表单使用分区标题、步骤或标签页,不把每个分区做成浮动卡片。
  • 保存草稿允许不完整字段;发布、审核和执行使用独立预检。
  • 历史规则、责任、地址、点位和金额使用只读快照,不混在可编辑字段中。
  • 版本冲突保留安全草稿,并显示发生变化的对象或字段摘要。
  • 金额、数量和比例输入显示单位,客户端只提交允许字段,不计算最终事实。
  • 高风险操作必须有原因码、备注、对象版本和影响摘要。

3. 抽屉

抽屉用于不丢失列表上下文的详情、审核和关联对象查看:

类型 建议宽度 使用范围
简要详情 480px 摘要、状态和少量操作
标准详情 640px 审核、时间线和关联信息
复杂证据/公式 800px 数量链、证据、账本公式和版本对比

宽度不得超过当前视口可读范围;1280px 下必须验证。抽屉内不再打开第二层抽屉,复杂流程转独立详情页。

4. 弹窗

类型 建议宽度 内容
简单确认 420px 对象、动作、后果和确认
带原因确认 560px 原因码、备注和影响摘要
复杂预检 720px 错误、警告、通过项和下一步
  • 删除、关闭、冻结、审核、回购和入账不能使用只有“确定/取消”的空泛文案。
  • 成功后关闭弹窗并刷新明确对象;失败时保留输入和错误。
  • 禁止弹窗嵌套弹窗。
  • 用户端和现场移动端使用现有 uni-popup 或底部弹层,按钮区预留安全区。

九、uni-app 现有能力复用

1. 直接复用

能力 现有路径
页面安全区和基础容器 components/common/base_container.vue
自定义导航 components/common/base_nav_bar.vue
金额格式 components/priceFormat.vue
图片加载 components/easyLoadimage/easyLoadimage.vue
倒计时 components/countDown/index.vue
空态 components/emptyPage.vue
加载 components/Loading/index.vue
图片/视频轮播 components/productConSwiper/index.vue
富文本 components/jyf-parser/jyf-parser.vue
弹层 uni_modules/uni-popup
日期时间 uni_modules/uni-datetime-picker

2. 扩展复用

现有能力 可复用 必须隔离
productWindow SKU、数量、库存和确认交互 普通购物车和价格语义
AddressSelectoraddressWindow 地址展示和选择 代销与去向状态
DeliveryType 配送选择视觉 云仓三种去向业务
OrderSummary 金额摘要布局 本金、收益和回购公式
DIY seckill 标题、倒计时和商品展示 普通秒杀 API、订单和库存状态
普通秒杀列表 场次、库存反馈和抢购节奏 云仓批次、持仓和回购
用户账单 流水方向、筛选和金额样式 云仓账本类型和公式

3. 禁止整页复制

  • pages/activity/goods_seckill_details/index.vue
  • pages/users/order_confirm/index.vue
  • pages/users/order_list/index.vue
  • pages/order_details/index.vue

高保真旁必须标注“现有页面基准、直接复用、扩展差异、新增领域表达”。没有组件检索证据时,不得在设计稿中标记为“新增公共组件”。

十、页面、API、权限与文件映射

1. 每页实现映射卡

每个高保真主 Frame 旁必须放置一张不参与导出的映射卡:

Page ID:
Page Name:
Figma Node:
Terminal / Viewport:
Role / Data Scope:
Entry / Back:
Route:
Read APIs:
Write APIs / Operation Codes:
Request DTO / Response DTO:
Permission Codes:
allowed_actions:
Frontend Page Files:
Frontend API / Store / Utils:
Backend Controller:
Service / Repository / Main Tables:
States / Error Codes:
Reuse Evidence:
Related Flow:
QA Evidence:

映射值直接引用 303537 及正式权限/写操作登记,不在映射卡中改写契约。

2. 四端映射示例

页面 前端与 API 后端 权限边界
ADM-CW-003 ActivitySkuRuleTable.vue、平台 src/api/farm/cloud.js CloudActivityProduct.php 与发布/供货/二次库存服务 路由权限 + 平台数据范围 + allowed_actions + 活动/SKU 版本
MER-CW-002 cloudSupply/application/edit.vue、商户 src/api/farm/cloud.js 商户 CloudSupply.php、供货生命周期服务 当前商户 + 员工权限 + SKU 归属 + allowed_actions
USR-CW-007 pages/cloudWarehouse/freight_pay.vueapi/farmCloud.js 用户 CloudFreight.php、报价/支付/退款服务 本人订单 + 状态/版本 + 本地支付结果查询
SVC-PD-003 farm/work/production/event.vueproduction.js、证据上传组件 服务端 ProductionEvent.phpFarmAttachment.php 职责 + 对象范围 + 任务归属 + scope_version + allowed_actions

3. 映射验收

  • 列表 Frame 必须能映射到 ListResult<T> 的分页、计数、筛选和动作计数。
  • 详情 Frame 必须能映射 status/version/allowed_actions/timeline/warnings/related
  • 支付结果必须映射 PayResult.next_action/return_path
  • 异步操作必须映射 AsyncAcceptedOperationDetail
  • Figma 中不得出现 API 不返回的最终金额、库存、进度或状态编辑框。
  • 任一页面缺少路由、API、权限、文件或错误状态时,不得标记 Design Ready。

十一、交互注释规范

每个可执行动作至少标注:

注释项 必填内容
触发 点击、提交、选择、扫码、支付回跳或自动任务结果
前置 角色、对象状态、版本、范围和 allowed_actions
输入 DTO、必填、单位、限制、禁止字段
防重复 按钮锁定、request_id/Idempotency-Key 和重复结果
处理中 局部 Loading、支付确认或异步进度
成功 新状态、刷新对象、下一页面和提示
失败 错误码对应文案、保留内容和可重试方式
冲突 刷新对象、保留草稿和重新确认
返回 是否保留筛选、滚动、场次和未提交内容
端差异 H5、小程序、桌面或现场移动差异
审计 是否需要原因、证据、联系记录或操作日志

Prototype 连线只连接真实可执行动作。自动任务、支付回调和异步 Job 不伪装成用户点击连线,应使用注释说明触发和轮询。

十二、标注、切图与资产

1. 开发标注

每个页面至少标注:

  • 画板和内容区尺寸。
  • 网格、内外边距、间距、固定/自适应宽度。
  • 文本样式、行数、截断和展开。
  • 控件高度、状态和禁用原因。
  • 表格列宽、固定列和横向滚动边界。
  • 固定栏、安全区和键盘弹起行为。
  • 图片比例、裁切、占位和失败状态。
  • 地图、二维码、进度条和时间线的稳定尺寸。
  • 对应变量名称及 Existing/Design Alias/Proposed 来源。

2. 资产原则

  • 已有 Iconfont、SvgIcon 或组件图标不重复切图。
  • 商品、农场、证书和用户上传图片属于内容数据,不打包为静态示例资产。
  • 透明图标使用 PNG 或现有 SVG 流程;照片使用项目现有支持的压缩格式。
  • 位图不包含需要国际化、动态变化或无障碍读取的文字。
  • 导出名使用小写 kebab-case
sf-{domain}-{scene}-{variant}@2x.png
  • 每个导出资产记录 Figma 节点、用途、尺寸、格式、压缩要求、版权/来源和替换策略。
  • 未经确认不引入新的图标库或字体文件。

当前资产清单:

资产 本地文件 Figma 来源与处理
农业图像联系表 assets/figma/smartfarm-agriculture-contact-sheet-v1.png 图片节点 45:31imageHash=a7ae2a9d8d91cf144025474b5414fd40159b37bc AI 生成的设计演示资产;正式上线前必须替换为来源、授权、地点和批次可审计的真实素材

其余图标继续复用项目 Iconfont、SvgIcon 或现有组件,不新增重复切图。

十三、可访问性与可用性

1. 通用

  • 正文、关键状态和交互文字达到可读对比度;目标为 WCAG 2.1 AA。
  • 状态同时使用文字、图标或形状,不只使用颜色。
  • 图标按钮有可访问名称和 Tooltip。
  • 表单标签与控件明确关联,错误靠近字段并可被读出。
  • 焦点顺序与视觉顺序一致;键盘可完成桌面核心操作。
  • 弹窗打开后焦点进入弹窗,关闭后返回触发控件。
  • 动态进度和提交结果提供文字,不依赖动画。
  • 用户上传图片、报告和溯源内容具备替代说明或文件名称。

2. 移动端

  • 主要触控目标最小 44x44px
  • 不依赖 hover。
  • 固定底栏、确认按钮、弹层和核销码避开系统安全区。
  • 长金额、长编号、长商品名和长异常原因在 360px 下仍可阅读。
  • 二维码加载失败时保留可复制码、对象摘要和人工入口。
  • 地图失败时保留地址、示意图、复制和重试。

3. 资金与高风险操作

  • 金额同时标明币种、方向、类型和状态。
  • 审核、回购、入账、冲正和库存修复展示对象、影响和不可逆后果。
  • 成功、失败、部分失败和处理中不得仅用 Toast 一闪而过。

十四、真实数据样例

高保真不得使用全是“商品名称”“123456”或 Lorem Ipsum。样例必须为虚构、脱敏且覆盖长文本和边界值。

类型 设计样例
农场编号 SF-FARM-202607-000128
农场名称 成都市郫都区稻香智慧农业示范农场二期
地块 A3-128 号水稻种植地块12.50 亩
商户 蜀禾优选农产品供应链有限公司(演示)
商品/SKU 生态散养谷物鸡蛋 30 枚装 / 一级品 / 礼盒装
云仓批次 CW-BATCH-20260730-000087
首次订单 CW-ORDER-20260730-0000001289
生产批次 PD-PLANT-2026-RICE-000318
用户 王**138****6628
正向金额 ¥12,345.67
冲正金额 -¥1,236.45
实物数量 12,345 件
经济等价数量 123.456789 件
比例 API 3750 基点,页面显示 37.50%
时间 2026-08-31 23:59:59,时区 Asia/Shanghai
异常原因 连续降雨导致采收延期,预计影响第二批次 320.50kg
地图 合法 GCJ02 演示点位;不得使用 0,0
异步进度 已处理 8,742 / 10,000,成功 8,700,失败 42

每个关键页面至少使用一组正常数据和一组边界数据。正式测试数据、编号、金额、异常和并发组合以 43-v1-test-catalog-and-fixtures.md 为准;Figma 使用与其同口径的脱敏代表值,不把设计样例当作数据库种子。

十五、高保真制作顺序

本轮已按以下顺序完成:

  1. 以运行态、源码、数据库菜单和用户端复用审计建立四端结构化视觉基线。
  2. 02 Components & Tokens 核对控件、变量、文本样式和复用来源。
  3. 完成四端代表页并校对 CRMEB 桌面密度、用户红色主题和服务蓝色任务语义。
  4. 建立 4 个高保真组件集和 45 个 Variant。
  5. 按 108 页清单扩展高保真主状态,保留原 108 个低保真 Frame。
  6. 建立空、加载、无权限、冲突、错误和异步进度的统一高保真状态板。
  7. 完成 15 条 Prototype Flow、60 个流程副本、前进动作、移动返回和 Flow 起点。
  8. 08 Handoff & Assets 建立覆盖矩阵、组件、状态、流程、资产、QA 和 RC 标记。
  9. 完成设计冻结评审后,研发才引用冻结版本和节点。

十六、设计 QA

1. 结构 QA

  • 页面编号与 17/30 一致,平台 55、商户 10、用户 29、服务端 14。
  • 15 条 Flow 名称与 30 一致。
  • Frame 无重名、错误尺寸、重叠、裁切和直接文本溢出。
  • 页面、组件、变量和资产遵守命名规则。
  • 参考页、低保真、高保真和交接页没有混写现状与建议。

2. 视觉 QA

  • 四端代表页与当前 CRMEB 参考截图并排比较。
  • 未发生全局农业绿色替换或后台壳重做。
  • 卡片圆角、表格密度、表单节奏、按钮和状态反馈与对应端一致。
  • 无卡片嵌套、装饰渐变和营销型后台 Hero。
  • 1280/1440360/375/390/430 必验视口通过。
  • 长编号、金额、商品名、异常原因和多状态标签不溢出。

3. 交互 QA

  • 每个按钮有前置、权限、请求、处理中、成功、错误和返回说明。
  • 支付、异步、版本冲突、重复提交和范围变化有真实结果页。
  • 列表返回保留筛选、分页、排序和滚动。
  • 用户支付成功后可继续抢购,不被去向弹窗强制阻塞。
  • 云仓一条订单明细没有数量拆分器。
  • 地图、扫码、上传和物流均有降级路径。
  • Prototype 不包含无法实现的演示跳转。

4. 契约 QA

  • 页面字段可由 37 响应取得,客户端不展示可修改的后端最终事实。
  • 每页映射卡可追到 35 的前后端文件。
  • 写操作带版本、幂等和必要原因。
  • 权限、范围和 allowed_actions 三者均已体现。
  • 状态文案与统一状态字典一致。
  • 敏感字段按平台、商户、用户、服务端和公开端裁剪。

5. 证据 QA

每页验收必须保留:

  • 冻结 Figma 节点 URL。
  • 主状态和关键异常截图。
  • 视口截图。
  • 组件/变量使用清单。
  • 页面映射卡。
  • Prototype 起点与终点。
  • QA 检查结果、问题编号和关闭证据。
  • 评审版本、角色和日期。

十七、设计冻结与变更流程

1. 状态

Draft
→ Design Review
→ Contract Review
→ Design Ready
→ Frozen
→ Superseded

只有同时通过视觉、交互、契约、权限、响应式和 QA 的页面才能进入 Design Ready。只有命名版本中的完整页面集合才能标记 Frozen

2. 冻结版本

建议版本名:

SmartFarm V1 / HF / RC-{序号} / YYYY-MM-DD
SmartFarm V1 / HF / FROZEN / YYYY-MM-DD

冻结记录必须包含:

  • Figma 文件键和版本链接。
  • 108 页完成矩阵。
  • 15 条 Flow 完成矩阵。
  • 组件、变量和资产版本。
  • 未决项必须为 0,或明确不进入 V1。
  • 设计、产品、前端、后端和测试评审结论。

当前 RC 标记:

项目 结果
RC 名称 SmartFarm V1 / HF / RC-1 / 2026-07-30
Figma 文件 SmartFarm V1 - CRMEB Baseline & Product Design
机器可验证冻结节点 08 Handoff & AssetsHandoff / SmartFarm V1 RC-1,节点 59:2
原生版本历史 ID 未生成;当前连接的 Figma MCP 不支持 saveVersionHistoryAsync
人工签字 待研发启动会由产品、设计、前端、后端和测试确认

在人工启动会需要 Figma 原生版本历史时,由具备文件权限的成员执行一次“Save to version history”,名称必须与上表 RC 名称一致。该操作不改变设计内容,也不作为本轮文档完整性的阻塞项。

3. 冻结后变更

  1. 建立 DSN-CR-YYYYMMDD-NNN 变更单。
  2. 记录原因、业务决策、页面、状态、API、文件、测试和历史订单影响。
  3. 在冻结版本分支或副本修改,不覆盖冻结证据。
  4. 重新执行受影响页面、组件、Flow 和视口 QA。
  5. 业务规则变化写回 12;技术/UI 决策变化写回 24;总进度和证据写回 26
  6. Figma 评论关闭不等于变更完成。

十八、逐页交付状态说明

下表逐页列出 108 个 P0 对象。当前统一状态:

  • 文档基线:已具备,来源为 17/18/30/35/37
  • 低保真:已落图并通过现有结构审计。
  • 高保真:已按 HF-{页面编号} 落图;平台 55、商户 10、用户 29、服务 14。
  • 状态:主状态已逐页落图;空、加载、无权限、冲突、错误、冻结和异步由统一状态规范派生。
  • 交互:15 条关键 Flow 已在 07 Prototype Flows 建立真实连线。
  • 映射:页面到 API、权限和文件的逐页主数据在 35/37,Figma 交付页提供总入口,不复制 108 份易漂移文本卡。
  • QA:重名、尺寸、顶层重叠、占位文案、缺失字体和流程跳转问题均为 0。

每行状态使用对应 HF-{页面编号} 作为稳定 Figma 名称;节点 ID 由 figma-state-smartfarm-v1.json 和 Figma 文件在交接时读取,避免把易变化的内部节点 ID复制到 108 行文档。

1. 平台管理端 55 页

页面 名称 必验视口 最终交付证据
ADM-CM-001 平台商品管理扩展 1440/1280 已完成(HF-ADM-CM-001
ADM-CM-002 商户商品审核扩展 1440/1280 已完成(HF-ADM-CM-002
ADM-AG-001 农业工作台 1440/1280 已完成(HF-ADM-AG-001
ADM-AG-002 农场列表 1440/1280 已完成(HF-ADM-AG-002
ADM-AG-003 农场详情 1440/1280 已完成(HF-ADM-AG-003
ADM-AG-004 区域列表 1440/1280 已完成(HF-ADM-AG-004
ADM-AG-005 地块列表 1440/1280 已完成(HF-ADM-AG-005
ADM-AG-006 地块详情 1440/1280 已完成(HF-ADM-AG-006
ADM-AG-007 地块占用日历 1440/1280 已完成(HF-ADM-AG-007
ADM-AG-008 栏舍/蜂场列表 1440/1280 已完成(HF-ADM-AG-008
ADM-AG-009 养殖资产列表 1440/1280 已完成(HF-ADM-AG-009
ADM-AG-010 养殖批次列表 1440/1280 已完成(HF-ADM-AG-010
ADM-AG-011 自提点列表 1440/1280 已完成(HF-ADM-AG-011
ADM-AG-012 自提点编辑 1440/1280 已完成(HF-ADM-AG-012
ADM-LA-001 作物列表 1440/1280 已完成(HF-ADM-LA-001
ADM-LA-002 租地套餐列表 1440/1280 已完成(HF-ADM-LA-002
ADM-LA-003 租地套餐编辑 1440/1280 已完成(HF-ADM-LA-003
ADM-LA-004 租地订单列表 1440/1280 已完成(HF-ADM-LA-004
ADM-LA-005 租地订单详情 1440/1280 已完成(HF-ADM-LA-005
ADM-LA-006 地块分配工作台 1440/1280 已完成(HF-ADM-LA-006
ADM-AD-001 认养分类与品种 1440/1280 已完成(HF-ADM-AD-001
ADM-AD-002 认养套餐列表 1440/1280 已完成(HF-ADM-AD-002
ADM-AD-003 认养套餐编辑 1440/1280 已完成(HF-ADM-AD-003
ADM-AD-004 认养订单列表 1440/1280 已完成(HF-ADM-AD-004
ADM-AD-005 认养订单详情 1440/1280 已完成(HF-ADM-AD-005
ADM-AD-006 资产/份额分配工作台 1440/1280 已完成(HF-ADM-AD-006
ADM-PD-001 生产批次列表 1440/1280 已完成(HF-ADM-PD-001
ADM-PD-002 生产批次详情 1440/1280 已完成(HF-ADM-PD-002
ADM-PD-003 过程记录审核 1440/1280 已完成(HF-ADM-PD-003
ADM-PD-004 采收/产出批次列表 1440/1280 已完成(HF-ADM-PD-004
ADM-PD-005 采收/产出批次详情 1440/1280 已完成(HF-ADM-PD-005
ADM-PD-006 邮寄履约列表 1440/1280 已完成(HF-ADM-PD-006
ADM-PD-007 农业异常列表 1440/1280 已完成(HF-ADM-PD-007
ADM-PD-008 农业异常详情 1440/1280 已完成(HF-ADM-PD-008
ADM-TR-001 溯源档案列表 1440/1280 已完成(HF-ADM-TR-001
ADM-TR-002 溯源档案编辑/预览 1440/1280 已完成(HF-ADM-TR-002
ADM-TR-003 报告与证书 1440/1280 已完成(HF-ADM-TR-003
ADM-TR-004 溯源关联 1440/1280 已完成(HF-ADM-TR-004
ADM-CW-001 云仓活动列表 1440/1280 已完成(HF-ADM-CW-001
ADM-CW-002 云仓活动编辑 1440/1280 已完成(HF-ADM-CW-002
ADM-CW-003 云仓活动商品编辑 1440/1280 已完成(HF-ADM-CW-003
ADM-CW-004 云仓活动数据详情 1440/1280 已完成(HF-ADM-CW-004
ADM-CW-005 云仓供货列表 1440/1280 已完成(HF-ADM-CW-005
ADM-CW-006 供货详情 1440/1280 已完成(HF-ADM-CW-006
ADM-CW-007 云仓订单与去向工作台 1440/1280 已完成(HF-ADM-CW-007
ADM-CW-008 云仓批次列表 1440/1280 已完成(HF-ADM-CW-008
ADM-CW-009 云仓批次详情 1440/1280 已完成(HF-ADM-CW-009
ADM-CW-010 二次零售分配 1440/1280 已完成(HF-ADM-CW-010
ADM-CW-011 到期回购 1440/1280 已完成(HF-ADM-CW-011
ADM-CW-012 云仓异常 1440/1280 已完成(HF-ADM-CW-012
ADM-FN-001 商户云仓货款 1440/1280 已完成(HF-ADM-FN-001
ADM-FN-002 用户云仓账本 1440/1280 已完成(HF-ADM-FN-002
ADM-FN-003 商户供货结单 1440/1280 已完成(HF-ADM-FN-003
ADM-FN-004 云仓对账 1440/1280 已完成(HF-ADM-FN-004
ADM-FN-005 账本/入账详情 1440/1280 已完成(HF-ADM-FN-005

2. 商户中心 10 页

页面 名称 必验视口 最终交付证据
MER-HM-001 智慧经营工作台扩展 1440/1280 已完成(HF-MER-HM-001
MER-CM-001 商品列表扩展 1440/1280 已完成(HF-MER-CM-001
MER-CM-002 商品编辑扩展 1440/1280 已完成(HF-MER-CM-002
MER-CW-001 云仓供货申请列表 1440/1280 已完成(HF-MER-CW-001
MER-CW-002 云仓供货申请编辑 1440/1280 已完成(HF-MER-CW-002
MER-CW-003 云仓供货记录 1440/1280 已完成(HF-MER-CW-003
MER-CW-004 云仓供货详情 1440/1280 已完成(HF-MER-CW-004
MER-CW-005 云仓履约/售后 1440/1280 已完成(HF-MER-CW-005
MER-FN-001 云仓供货货款 1440/1280 已完成(HF-MER-FN-001
MER-FN-002 云仓供货结单 1440/1280 已完成(HF-MER-FN-002

3. 用户端 29 页

页面 名称 必验视口 最终交付证据
USR-AG-001 农场专区 390/375,H5/小程序 已完成(HF-USR-AG-001
USR-AG-002 农场详情 390/375,H5/小程序 已完成(HF-USR-AG-002
USR-AG-003 农场位置与导航 390/375,正常/降级 已完成(HF-USR-AG-003
USR-LA-001 租地列表 390/375,H5/小程序 已完成(HF-USR-LA-001
USR-LA-002 租地详情 390/375,H5/小程序 已完成(HF-USR-LA-002
USR-LA-003 租地下单确认 390/375,支付差异 已完成(HF-USR-LA-003
USR-LA-004 我的土地 390/375,H5/小程序 已完成(HF-USR-LA-004
USR-LA-005 我的土地详情 390/375,H5/小程序 已完成(HF-USR-LA-005
USR-AD-001 认养列表 390/375,H5/小程序 已完成(HF-USR-AD-001
USR-AD-002 认养详情 390/375,H5/小程序 已完成(HF-USR-AD-002
USR-AD-003 认养下单确认 390/375,支付差异 已完成(HF-USR-AD-003
USR-AD-004 我的认养 390/375,H5/小程序 已完成(HF-USR-AD-004
USR-AD-005 我的认养详情 390/375,H5/小程序 已完成(HF-USR-AD-005
USR-PD-001 产出履约详情 390/375,多包裹 已完成(HF-USR-PD-001
USR-CW-001 集市云仓 390/375,场次状态 已完成(HF-USR-CW-001
USR-CW-002 云仓商品详情 390/375,长规则 已完成(HF-USR-CW-002
USR-CW-003 云仓抢购确认 390/375,支付差异 已完成(HF-USR-CW-003
USR-CW-004 云仓支付成功 390/375,六种支付结果 已完成(HF-USR-CW-004
USR-CW-005 云仓订单中心 390/375,全状态 已完成(HF-USR-CW-005
USR-CW-006 云仓去向选择 390/375,三种去向 已完成(HF-USR-CW-006
USR-CW-007 邮寄地址与补运费 390/375,支付/退款 已完成(HF-USR-CW-007
USR-CW-008 自提凭证 390/375,地图/码降级 已完成(HF-USR-CW-008
USR-CW-009 我的云仓 390/375,聚合延迟 已完成(HF-USR-CW-009
USR-CW-010 云仓持仓详情 390/375,节点/回购 已完成(HF-USR-CW-010
USR-CW-011 云仓账本 390/375,正负金额 已完成(HF-USR-CW-011
USR-CW-012 云仓账本详情 390/375,公式/冲正 已完成(HF-USR-CW-012
USR-TR-001 溯源档案 390/375,发布/撤回 已完成(HF-USR-TR-001
USR-CM-001 普通商品详情扩展 390/375,原链路回归 已完成(HF-USR-CM-001
USR-CM-002 普通订单详情扩展 390/375,原链路回归 已完成(HF-USR-CM-002

4. 服务/现场端 14 页

页面 名称 必验视口 最终交付证据
SVC-AU-001 服务人员登录 1440/1280390/360 已完成(HF-SVC-AU-001
SVC-AU-002 工作区选择 390/360/430,桌面可读 已完成(HF-SVC-AU-002
SVC-AU-003 我的与职责范围 390/360/430 已完成(HF-SVC-AU-003
SVC-CM-001 智慧农业订单查询 1440/1280 已完成(HF-SVC-CM-001
SVC-CW-001 云仓订单查询 1440/1280 已完成(HF-SVC-CW-001
SVC-CW-002 云仓异常协同 1440/1280 已完成(HF-SVC-CW-002
SVC-PD-001 我的农业任务 390/360/430 已完成(HF-SVC-PD-001
SVC-PD-002 扫码入口 390/360/430,三种降级 已完成(HF-SVC-PD-002
SVC-PD-003 新增过程记录 390/360/430,离线草稿 已完成(HF-SVC-PD-003
SVC-PD-004 采收/产出录入 390/360/430,数量方程 已完成(HF-SVC-PD-004
SVC-PD-005 仓储履约 390/360/430,四子流程 已完成(HF-SVC-PD-005
SVC-PD-006 异常上报 390/360/430,证据/幂等 已完成(HF-SVC-PD-006
SVC-PD-007 生产/产出审核 1440/1280 已完成(HF-SVC-PD-007
SVC-PD-008 本机草稿 390/360/430,存储降级 已完成(HF-SVC-PD-008

十九、逐 Flow 交付清单

15 个 Flow 画板、60 个同页高保真流程副本和 15 个唯一 Prototype 起点已完成。自动审计逐条验证:每个 Flow 4 个步骤链接均指向对应流程副本,主动作按顺序前进,最终动作返回 Flow 画板,移动页面返回动作指向上一步或画板,问题数为 0。

Flow 名称 最终必须证明
PF-CW-01 云仓活动供货 单 SKU 申请、审核预留、部分验收、发布预检和退回路径
PF-CW-02 用户抢购与支付 库存竞争、支付确认、失败/取消和继续抢购
PF-CW-03 三种去向 整条明细唯一去向、版本冲突和超时自动代销
PF-CW-04 补运费 报价变化、确认中、超时、迟到支付退款
PF-CW-05 自提 分次核销、地图降级、逾期剩余量处理
PF-CW-06 代销与三结算模式 真实销售、节点、冻结、退款和冲正
PF-CW-07 到期滞销回购 在途宽限、所有权切换、审核、原子执行和重试
PF-CW-08 商户货款 资格链、日结、正式入账、异议和调整
PF-LA-01 租地 购买、待分配、预留冲突、真实地块和生产
PF-AD-01 认养 单体/份额、待分配、并发容量和替换链
PF-PD-01 生产记录 任务、扫码、离线草稿、上传、审核和驳回
PF-PD-02 产出与履约 数量方程、验收、地址确认、多包裹和售后
PF-EX-01 异常闭环 事实、SLA、方案、审批、部分执行和重新预检
PF-TR-01 溯源发布 材料、编辑预览、审核、公开、过期和撤回
PF-AU-01 服务身份与范围 登录、上下文、工作区、范围变化和 Token 失效

二十、最终交付包与验收证据

1. Figma 交付

  • 四端结构化运行态/源码/数据库视觉参考及来源;未把结构化基线冒充浏览器原始截图。
  • 108 页高保真主状态。
  • 关键空态、错误、权限、冲突、冻结和异步状态。
  • 15 条真实 Prototype Flow。
  • 经过验证的组件、Variant、变量和文本样式。
  • 每页实现映射卡。
  • 资产清单与导出节点。
  • 设计 QA 和变更记录。

2. 研发交接

  • 页面编号与冻结 Figma 节点。
  • 页面路由、API、DTO、权限、allowed_actions 和错误状态。
  • 新建、修改、复用文件及组件复用依据。
  • 响应式、端差异和安全区行为。
  • 异步、支付、版本冲突和幂等交互。
  • 真实数据样例与测试 fixture 对应关系。

3. 验收签字

角色 验收重点 当前状态
产品 业务规则、角色任务、页面闭环 Codex 自主预审通过;人工启动会确认
设计 CRMEB 继承、组件、状态、响应式、可访问性 Codex 自主预审通过;人工启动会确认
前端 文件、组件复用、端差异和可实现性 Codex 自主预审通过;人工启动会确认
后端 API、DTO、权限、状态和异步结果 Codex 自主预审通过;人工启动会确认
测试 状态、异常、数据样例和验收证据 Codex 自主预审通过;人工启动会确认

二十一、完成结论与启动会动作

  • 3 个变量集合、61 个变量和 10 个文本样式已审计。
  • 4 个高保真组件集、45 个 Variant 和复用边界已登记。
  • 108 页高保真主状态已落图并通过结构审计。
  • 统一空、加载、无权限、冲突、错误、冻结和异步状态规范已建立。
  • H5、小程序、桌面和现场移动端差异已按端基线落图。
  • 15 条 Flow、60 个流程副本、起点、前进和返回路径已通过自动审计。
  • 页面 API、权限、文件映射已由 35/37 作为唯一主数据承接。
  • 资产文件、Figma 节点、来源、hash 和上线替换要求已登记。
  • 长文本、金额、编号、视口、缺失字体和占位文案审计已通过。
  • RC-1 机器可验证标记和 Figma 文件链接已建立。
  • 可选:补录四端登录态原始截图,用于开发阶段像素级回看;当前结构化视觉基线足以冻结设计方向。
  • 启动会:人工确认 RC-1,并在需要时保存同名 Figma 原生版本历史。
  • 启动会:产品、设计、前端、后端和测试完成签字与任务认领。

结论:设计交付物已达到 Design Ready / Codex 自主预审通过。在业务代码任务启动前,项目团队只需完成上述启动会动作;不得把尚未发生的人工签字写成已完成。

Clone this wiki locally