# 原型标注布局规范

适用于 `src/prototypes/` 下所有接入 `@axhub/annotation` 的原型页面。

## 核心原则

1. **禁止在右侧「原型目录」中展示跨原型导航**
   - 不得在 `annotation-source.json` 的 `directory.nodes` 中维护 `id: oneos-project-nav` 的「ONE-OS 原型导航」文件夹
   - 跨原型跳转统一由 **`/prototypes/oneos-prototype-nav`（原型导航页）** 承担

2. **PRD 说明展示在右侧「原型标注」目录面板**
   - 产品需求、模块说明、分章节 PRD 等内容，通过 `directory` 的 `markdown` 节点写入
   - 用户在右侧工具栏打开「原型标注 / 原型目录」，按章节阅读 Markdown 正文
   - **不在**页面正文下方内联展示 PRD 大段内容

3. **去除目录内页面跳转**
   - `type: link` 跨原型/跨模块链接不在目录树中展示
   - `type: route` 页面内跳转节点不在目录树中展示（`route` 仅用于声明 `pageId` 绑定，供按当前页过滤章节）
   - 页面切换由原型自身导航（按钮、Tab、Hash 等）完成

4. **标注工具栏保留**
   - 页面元素批注、主题切换、颜色筛选等 `@axhub/annotation` 能力继续可用

## 标准接入方式

所有新原型与存量改造，**必须**使用公共壳组件：

```tsx
import {
  type AnnotationSourceDocument,
  type AnnotationViewerOptions,
} from '@axhub/annotation';
import { PrototypeAnnotationHost } from '../../common/prototype-annotation-host';
import annotationSourceDocument from './annotation-source.json';

export default function MyPrototypePage() {
  const annotationOptions = useMemo<AnnotationViewerOptions>(() => ({
    showToolbar: true,
    showThemeToggle: true,
    showColorFilter: true,
    emptyWhenNoData: false,
    toolbarEdge: 'right',
    currentPageId: 'list', // 多页面原型按当前页传入
  }), []);

  return (
    <>
      <MyApp />
      <PrototypeAnnotationHost
        source={annotationSourceDocument as AnnotationSourceDocument}
        options={annotationOptions}
      />
    </>
  );
}
```

### 多页面原型

- `options.currentPageId` 与页面路由保持一致
- `annotation-source.json` 中带 `route` 子节点的文件夹，仅在其 `payload.pageId` 匹配当前页时，才在右侧目录中展示对应 PRD 章节
- 无 `route` 绑定的 PRD 文件夹（如「PRD 全文」「模块总览」）在所有子页面均展示
- 一般**不需要**再实现 `onDirectoryRoute`（目录内已无 `route` 可点击节点）

## annotation-source.json 目录约定

`directory.nodes` 中只允许保留 **本产品说明**，结构建议：

```text
directory.nodes
├── folder · 模块说明 / PRD 全文 / 列表页模块 / 新增页模块 …
│   ├── markdown · 章节正文（内联 markdown 或 markdownMap）
│   └── route · 仅用于声明 pageId 绑定（不在 UI 展示）
```

**禁止写入：**

- `id: oneos-project-nav` 导航文件夹
- 依赖 `type: link` 的跨原型跳转（改放原型导航页）

**不在目录 UI 展示（但可保留在 JSON 中供过滤）：**

- `type: link` 节点
- `type: route` 节点（仅作 pageId 绑定元数据）

## 脚本与同步

| 命令 | 作用 |
|------|------|
| `npm run project-nav:sync` | 更新原型导航页 `nav-menu.json`，并清理各原型目录中的导航节点 |
| `node scripts/strip-prototype-nav-from-directory.mjs` | 批量移除 `oneos-project-nav` |
| `node scripts/migrate-prototype-annotation-host.mjs` | 将 `AnnotationViewer` 迁移为 `PrototypeAnnotationHost` |

修改 sidebar 菜单或批量整理标注目录后，执行 `npm run project-nav:sync`。

## Agent 开发检查清单

新建或改造带标注的原型时：

- [ ] `index.tsx` 使用 `PrototypeAnnotationHost`，不直接挂载裸 `AnnotationViewer`
- [ ] `annotation-source.json` 无 `oneos-project-nav` 节点
- [ ] PRD / 模块说明以 `markdown` 节点写入 `directory`，能在右侧「原型目录」分章节阅读
- [ ] 页面正文下方**无**大块 PRD 内联区域
- [ ] 右侧目录**无**跨原型 link、**无**可点击的 route 页面跳转
- [ ] 跨原型入口统一引导用户打开「原型导航」页
- [ ] 多页面原型正确传入 `currentPageId`，右侧 PRD 章节与当前页匹配

## 相关文件

| 文件 | 说明 |
|------|------|
| `src/common/prototype-annotation-host.tsx` | 标注壳：过滤目录 + 批注工具栏 |
| `src/common/prototype-annotation-utils.ts` | PRD 目录过滤与导航节点清理 |
| `src/prototypes/oneos-prototype-nav/` | 全局原型导航页 |
| `scripts/sync-project-prototype-directory.mjs` | 导航菜单同步（不再注入侧边导航树） |