迭代 ONE-OS 多原型:统一标注壳与操作规范,租赁明细/合同/提车应收款增强,新增任务工单,同步导航与合包页面。
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -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。
|
||||
|
||||
|
||||
115
rules/prototype-annotation-layout-guide.md
Normal file
115
rules/prototype-annotation-layout-guide.md
Normal 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` | 导航菜单同步(不再注入侧边导航树) |
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user