OneOS1.2/rules/prototype-development-guide.md

原型开发与验收指南

用于 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 文件。

每个原型的 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。

验收流程

运行原型验收脚本：

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 原型验收通过。