6.5 KiB
6.5 KiB
原型开发与验收指南
用于 src/prototypes/<name>/ 下的原型实现、局部修改、多页面组织和预览验收。主题创建、派生和主题页验收优先看 rules/theme-guide.md。
开发流程：
读取已确认需求和设计决策 -> 修改原型目录内代码 -> 运行验收脚本 -> 按错误信息修复 -> 重新验收
实现边界
- 一个原型目录就是主要隔离边界，页面组件、样式和素材优先留在对应原型目录内。
- 不为单个原型随意修改
src/common/、全局主题或共享工具。 - 多步骤或高风险修改先拆成短任务，逐项处理并维护当前状态。
- 一次只处理一个明确问题；遇到构建、运行或验收失败，先定位原因再继续。
- 完成后必须通过预览验收；纯视觉、文案、布局和素材调整不要求测试驱动。
文件结构与命名
src/prototypes/<name>/
├── index.tsx # 必需
├── style.css # 可选
├── components/ # 可选：原型内部共享组件
├── pages/ # 可选：多页面原型页面组件
├── docs/ # 可选：目录 Markdown 文档
└── assets/ # 可选：原型专属素材
- 原型入口文件必须是
index.tsx。 - 原型目录名使用小写字母、数字、连字符，如
order-review。 - 当目录名为
untitled、untitled-*或显示名为「未命名」时，开始生成实际内容前应更新为有意义的目录名和@name。 - 本项目当前不产出独立
components资源；原型内部组件放在对应原型目录下的components/。 - 原型目录文档放在当前原型的
docs/下，例如src/prototypes/order-review/docs/prd-03-status.md。 annotation-source.json的目录文档节点优先使用相对当前原型目录的markdownPath，例如"markdownPath": "docs/prd-03-status.md"；不要写绝对路径、..或跨原型引用。- 普通预览和
@axhub/annotation阅读页不显示目录文档编辑入口；编辑 URL 由 Make 批注宿主回调生成，不写进 annotation 包或目录节点数据。 - 只有 Make 批注/编辑工具启用、且当前选中的是带安全本地
markdownPath的目录 Markdown 正文子节点时，批注气泡卡片才显示“文档编辑”按钮。 - 导出/发布时会构建期内联
markdownPath正文，不依赖运行时请求.md文件。
原型标注与 PRD 布局（强制）
跨原型跳转与 PRD 阅读方式已全局统一，详见 rules/prototype-annotation-layout-guide.md：
- 禁止 在
annotation-source.json的directory中维护oneos-project-nav（ONE-OS 原型导航）；跨原型入口统一使用/prototypes/oneos-prototype-nav - 必须 通过
PrototypeAnnotationHost（src/common/prototype-annotation-host.tsx）挂载标注，不在各原型直接使用裸AnnotationViewer - PRD / 模块说明写在
directory的markdown节点中，由右侧「原型标注」目录分章节展示；不在页面正文下方内联 PRD - 目录内不展示
link/route跳转节点；多页面原型通过options.currentPageId控制右侧 PRD 章节与当前页匹配
每个原型的 index.tsx 顶部建议包含面向用户的中文 @name，用于预览列表展示名：
/**
* @name 评审工作台
*/
多页面原型
单个原型可以包含多个页面，通过 URL hash 参数 #page=<pageId> 定位：
/prototypes/express-app/#page=home
/prototypes/express-app/#page=detail
多页面仍属于同一个原型目录；页面组件放在原型内部的 pages/，跨页面共享组件放在原型内部的 components/。
使用公共 hook src/common/useHashPage.ts：
import { useHashPage } from '../../common/useHashPage';
export default function MyApp() {
const { page, setPage } = useHashPage('home');
// page === 'home' | 'detail' | ...
}
pageId命名使用小写字母、数字、连字符。- 不带
#page=时自动使用defaultPage。 - 此路由完全在原型内部，不影响构建。
参考实现：src/prototypes/ref-app-home/index.tsx。
依赖与样式
- React 与 Hooks 直接从
react导入。 - 第三方库按需导入，新增依赖必须同步更新
package.json。 - 使用 Tailwind CSS V4 时，入口样式文件需包含：
@import "tailwindcss";
- 使用主题 CSS Variables 时，按所选
DESIGN.md和主题规则引入，不复制另一套 token。
列表分页（vm-page 强制）
凡 vm-page 下的数据列表页，表格底部 必须 使用全局分页组件与样式，规范见 src/prototypes/vm-shared/DESIGN.md：
- 组件：
import { TablePagination, DEFAULT_PAGE_SIZE } from '../../common/TablePagination' - 样式：引入
vehicle-management/style.css（已包含src/common/vm-pagination.css） - 禁止：下拉加载更多、自建分页 UI、与
vm-pagination*不一致的第三方分页
参考：vehicle-management/index.tsx、lease-business-ledger/index.tsx。
业务逻辑文档化（强制）
实现复杂判断逻辑（多步判定、跨模块校验、状态/公式推导、导入保存规则等）时，必须与代码同一轮更新文档。详见 rules/business-logic-documentation-guide.md。
.spec/<logic-topic>.md # 完整规则（判定顺序、数据源、代码路径）
.spec/requirements-prd.md # 摘要 + 验收项
annotation-source.json # sync-annotation-directory.mjs 同步目录/字段标注
范例：lease-business-detail/.spec/field-checks.md。
验收流程
运行原型验收脚本：
node scripts/check-app-ready.mjs /prototypes/[原型目录]
关键返回字段：
status:READY/ERROR/TIMEOUT。targetUrl: 本次验收目标地址。errors: 构建、运行时或页面加载错误列表。
错误处理：
ERROR：按errors修复后重新执行验收脚本，直到通过。TIMEOUT：优先排查 dev server 启动、端口、长任务和运行时阻塞。- 修复时先处理构建、启动和运行时报错，再处理交互与视觉问题；一次只修一个明确问题，修完重新验收。
最小清单
index.tsx完整存在。index.tsx顶部有清晰的@name。- 占位原型已更新为有意义的目录名和显示名。
- 新增依赖已写入
package.json。 check-app-ready.mjs原型验收通过。- 若含复杂业务逻辑：
.spec规格文 + PRD 摘要 + 标注目录已同步（见business-logic-documentation-guide.md）。