迭代 ONE-OS 多原型:统一标注壳与操作规范,租赁明细/合同/提车应收款增强,新增任务工单,同步导航与合包页面。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
2026-07-12 22:44:21 +08:00
parent 824512a224
commit 131b963e4a
317 changed files with 38569 additions and 12009 deletions

View File

@@ -53,6 +53,8 @@
|---|---|
| 正文字体 `--vm-font` | Inter, -apple-system, BlinkMacSystemFont, "SF Pro Display", "PingFang SC", "Microsoft YaHei", sans-serif |
| 等宽 `--vm-font-mono` | ui-monospace, JetBrains Mono, SFMono-Regular, Menlo, Consolas, monospace |
| 数字/金额 | 使用 `--vm-font-mono` + `tabular-nums`(全局见 `src/common/ln-numeric.css`,对齐 `.vm-expire-date` |
| 金额格式 | `src/common/format-number.js`(千分位 + 2 位小数Legacy 页可用 `window.__oneosFormatMoney` |
| 页面基础字号 | `0.875rem`14px |
| 筛选标签 | `0.75rem` / 500 |
| 表头 | `0.75rem` / 500 |
@@ -186,7 +188,7 @@ import '../vehicle-management/style.css';
| 次要 | `vm-btn vm-btn-secondary` | 带边框白底 |
| 幽灵 | `vm-btn vm-btn-ghost` | 取消、重置、工具栏次要操作 |
| 文字链 | `vm-btn vm-btn-link` | 表格内操作、行内链接 |
| 返回 | `vm-btn vm-btn-back` | 详情/编辑顶栏返回 |
| 返回 | `vm-btn vm-btn-back` | 表单/详情/编辑顶栏左上角Chevron 图标 + 白底描边hover 主色字/边框 + 浅绿底 |
**规格**:高度 36px圆角 8px字号 0.875rem / 500禁用 opacity 0.5。

View File

@@ -0,0 +1,115 @@
# 原型标注布局规范
适用于 `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` | 导航菜单同步(不再注入侧边导航树) |

View File

@@ -38,6 +38,15 @@ src/prototypes/<name>/
- 只有 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`,用于预览列表展示名:
```typescript