迭代 ONE-OS 多原型：加氢记录/订单同源对账、租赁明细校验与月度损益、车辆与台账增强；新增客户回款与加氢站统计；补齐业务逻辑与对象存储发布规范，同步原型导航。
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
135
rules/business-logic-documentation-guide.md
Normal file
135
rules/business-logic-documentation-guide.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# 业务逻辑文档化指南（全局）
|
||||
|
||||
凡原型或页面实现**复杂判断逻辑、跨模块校验、状态/公式推导、导入导出规则**时，除代码外**必须**同步写入 Markdown 与 PRD，供评审、标注目录与后续 Agent 读取。
|
||||
|
||||
参考范例：`src/prototypes/lease-business-detail/.spec/field-checks.md` + `requirements-prd.md` §5 单元格系统校验。
|
||||
|
||||
---
|
||||
|
||||
## 何时必须文档化
|
||||
|
||||
满足以下**任一**条件，即视为「复杂业务逻辑」，不得只留在代码或口头说明：
|
||||
|
||||
| 类型 | 示例 |
|
||||
|------|------|
|
||||
| 多步判定 / 优先级链 | 客户名称 5 步校验、收款状态三态 |
|
||||
| 跨模块对照 | 对照客户管理、车辆管理、合同台账 |
|
||||
| 公式 / 聚合口径 | KPI、表尾 SUBTOTAL、应收租金 = 租金 × 月数 |
|
||||
| 状态机 | 未收款 → 部分收款 → 已结清 |
|
||||
| 导入 / 保存拦截 | 重复键策略、实收 ≤ 应收 |
|
||||
| 权限 / 角色分支 | 主管可改、数据范围（若实现） |
|
||||
| 一键修复 / 建议值 | 校验警告 + 替换动作 |
|
||||
|
||||
纯样式、文案、布局微调**不**触发本指南；但若改动会改变上述判定结果，必须更新文档。
|
||||
|
||||
---
|
||||
|
||||
## 文档落点（三层）
|
||||
|
||||
```text
|
||||
src/prototypes/<name>/
|
||||
├── .spec/requirements-prd.md # ① PRD：摘要 + 验收项（产品可读）
|
||||
├── .spec/<logic-topic>.md # ② 规格：完整判定顺序、数据源、边界（开发/评审）
|
||||
├── annotation-source.json # ③ 标注：目录节点 + 页面/字段标注（经同步脚本）
|
||||
└── columnHeaderTips.ts 等 # 可选：表头/字段级一句话提示
|
||||
```
|
||||
|
||||
### ① PRD（`requirements-prd.md`）
|
||||
|
||||
在对应功能章节增加**摘要**，至少包含：
|
||||
|
||||
- 业务目的（一句话）
|
||||
- 判定顺序或状态表（表格优先）
|
||||
- 数据源 / 对照模块
|
||||
- 用户可见结果（图标、文案、是否可一键修复）
|
||||
- 链接到 `.spec/<logic-topic>.md` 全文
|
||||
|
||||
在 **§验收重点** 增加可勾选项。
|
||||
|
||||
### ② 规格 Markdown（`.spec/<logic-topic>.md`）
|
||||
|
||||
完整规则文档，建议结构：
|
||||
|
||||
```markdown
|
||||
# <模块> · <逻辑名称>
|
||||
|
||||
> 实现：`utils/xxx.ts`；UI：`components/xxx.tsx`
|
||||
|
||||
## 对照数据源
|
||||
## 交互与状态（ok / warn / none）
|
||||
## <字段或场景 A> 判定顺序（表格）
|
||||
## <字段或场景 B> …
|
||||
## 启用范围 / 与代码映射
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
- **判定顺序**写清优先级（命中即返回）
|
||||
- **前置条件**写清何时不校验
|
||||
- **弱校验 / 强校验**区分标注
|
||||
- 标明原型种子 vs 真实 API（若未接后端）
|
||||
|
||||
### ③ 标注目录（`annotation-source.json`）
|
||||
|
||||
通过 `scripts/sync-annotation-directory.mjs`（或等价脚本）同步：
|
||||
|
||||
| 同步目标 | 内容 |
|
||||
|----------|------|
|
||||
| `directory` → 规格说明 | 全文或 `markdownPath` 指向 `.spec/*.md` |
|
||||
| 页面标注节点 | 功能区摘要（如列表工具栏、明细表） |
|
||||
| 字段标注节点 | 单字段判定摘要（如客户名称） |
|
||||
| `markdownMap` | 与节点 `annotationText` 一致 |
|
||||
|
||||
**禁止**：代码已改、PRD/标注仍写旧逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 实施顺序（与开发绑定）
|
||||
|
||||
```text
|
||||
实现 / 修改业务逻辑代码
|
||||
↓
|
||||
编写或更新 .spec/<logic-topic>.md
|
||||
↓
|
||||
更新 requirements-prd.md 摘要 + 验收项
|
||||
↓
|
||||
更新表头提示 / 字段标注文案（如有）
|
||||
↓
|
||||
运行 sync-annotation-directory.mjs
|
||||
↓
|
||||
验收：目录与 PRD 可读、与页面行为一致
|
||||
```
|
||||
|
||||
逻辑变更与文档变更**同一轮交付**；不得「先合代码、后补文档」作为默认流程。
|
||||
|
||||
---
|
||||
|
||||
## 最小检查清单
|
||||
|
||||
- [ ] 复杂逻辑有独立 `.spec/*.md` 或 PRD 内等价完整章节
|
||||
- [ ] PRD 摘要含判定顺序表 / 状态表
|
||||
- [ ] PRD §验收 含可验证条目
|
||||
- [ ] `annotation-source.json` 目录已同步
|
||||
- [ ] 关键字段在「字段标注」或表头提示有一句业务说明
|
||||
- [ ] 文档标明数据来源（种子 / API / 手工列）
|
||||
- [ ] 代码路径在 PRD §源码入口 或规格文首注明
|
||||
|
||||
---
|
||||
|
||||
## 反例
|
||||
|
||||
| ❌ 不做 | ✅ 应做 |
|
||||
|--------|--------|
|
||||
| 只在 `utils/field-checks.ts` 里写 5 层 if | 同步 `field-checks.md` + PRD §5 摘要 |
|
||||
| 评审时口头解释客户名校验 | 目录「单元格系统校验」可点开全文 |
|
||||
| 改判定顺序不更新 PRD | 同 PR 更新 `.spec` + 跑 sync 脚本 |
|
||||
| 表头提示与真实逻辑矛盾 | 以 `.spec` 为单一真相，提示引用摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 关联规则
|
||||
|
||||
- 产品需求对齐：`rules/requirements-alignment-guide.md`
|
||||
- 原型开发验收：`rules/prototype-development-guide.md`
|
||||
- 标注布局：`rules/prototype-annotation-layout-guide.md`
|
||||
- Agent 门禁：根目录 `AGENTS.md`
|
||||
86
rules/cloud-publish-url-guide.md
Normal file
86
rules/cloud-publish-url-guide.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# 对象存储发布 URL 规范（全局）
|
||||
|
||||
Make 客户端「发布到对象存储」与脚本/Agent 批量发布**必须使用同一套公网路径**，避免维护两套链接。
|
||||
|
||||
配置来源：`.axhub/make/axhub.config.json` → `cloudPublishing.s3`
|
||||
|
||||
---
|
||||
|
||||
## 标准 URL 形态
|
||||
|
||||
```text
|
||||
{baseUrl}/{objectPrefix}/index.html
|
||||
```
|
||||
|
||||
| 项 | 默认值 | 示例 |
|
||||
|---|---|---|
|
||||
| `baseUrl` | `https://prototype.lnoneos.com` | — |
|
||||
| 原型页 `objectPrefix` | `{prototype-id}` | `lease-business-detail` |
|
||||
| 主题页 `objectPrefix` | `themes/{theme-id}` | `themes/claude` |
|
||||
| 入口文件名 | **固定** `index.html` | 不得改为 `/`、`.html` 省略或 `index.htm` |
|
||||
|
||||
**租赁业务明细（范例）**
|
||||
|
||||
```text
|
||||
https://prototype.lnoneos.com/lease-business-detail/index.html
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 禁止的改写
|
||||
|
||||
| ❌ 禁止 | 说明 |
|
||||
|--------|------|
|
||||
| 加 `prototypes/` 前缀 | 不得发布为 `/prototypes/lease-business-detail/index.html` |
|
||||
| 去掉 `index.html` | 不得改为目录根 `/lease-business-detail/` |
|
||||
| 改 `baseUrl` 域名 | 以 `axhub.config.json` 的 `s3.baseUrl` 为准 |
|
||||
| 自造路径别名 | 仅 `pathAliases` 中已声明的 id 可例外 |
|
||||
|
||||
---
|
||||
|
||||
## pathAliases（例外）
|
||||
|
||||
仅在 `axhub.config.json` → `cloudPublishing.s3.pathAliases` 中显式配置时覆盖默认前缀，例如：
|
||||
|
||||
```json
|
||||
"pathAliases": {
|
||||
"oneos-prototype-nav": "oneos-prototype-nav"
|
||||
}
|
||||
```
|
||||
|
||||
新增别名须**同时**更新：
|
||||
|
||||
1. `axhub.config.json` → `pathAliases`
|
||||
2. `src/prototypes/oneos-prototype-nav/nav-data.ts` → `CLOUD_PUBLISH_PATH_ALIASES`
|
||||
3. `prototype-registry.json` 变更说明（如有）
|
||||
|
||||
---
|
||||
|
||||
## 实现对照
|
||||
|
||||
| 场景 | 路径解析 |
|
||||
|------|----------|
|
||||
| Make 客户端发布 | `/{prototype-id}/index.html` |
|
||||
| `scripts/publish-all-to-s3.mjs` | `resolveObjectPrefix()` → 同上 |
|
||||
| 导航页 `resolvePrototypeHref()` | 云主机上 `/{segment}/index.html` |
|
||||
| 本地开发 | `/prototypes/{prototype-id}`（仅 dev，不是发布 URL） |
|
||||
|
||||
---
|
||||
|
||||
## Agent / AI 发布检查清单
|
||||
|
||||
发布或向用户回报链接前：
|
||||
|
||||
- [ ] 使用 `axhub.config.json` 中的 `baseUrl`
|
||||
- [ ] 原型链接以 `/index.html` 结尾
|
||||
- [ ] 未擅自添加 `prototypes/` 前缀
|
||||
- [ ] 与 Make 工具弹窗中的 URL 逐字一致
|
||||
- [ ] 未将 dev 路径（`/prototypes/...`）当作对象存储链接写入 PRD/导航
|
||||
|
||||
---
|
||||
|
||||
## 关联文件
|
||||
|
||||
- `scripts/publish-all-to-s3.mjs` — `resolveObjectPrefix`、`resolvePublicUrl`
|
||||
- `src/prototypes/oneos-prototype-nav/nav-data.ts` — 静态站跳转
|
||||
- `.cursor/rules/cloud-publish-url.mdc` — Agent 强制规则
|
||||
@@ -1,5 +1,7 @@
|
||||
# ONE-OS 全局设计规范（开发版）
|
||||
|
||||
> **对外分享请使用**：[`src/resources/design-system/`](../src/resources/design-system/README.md)（含 `DESIGN.md`、`tokens.json`、AI 提示模板）。本文件为项目内 Agent 规则副本。
|
||||
|
||||
| 项 | 说明 |
|
||||
|---|---|
|
||||
| 文档版本 | v1.0 |
|
||||
@@ -160,6 +162,8 @@ import '../vehicle-management/style.css';
|
||||
**折叠筛选**
|
||||
|
||||
- 超过 4 项时其余放入 `vm-filter-expand`（见 `src/common/vm-filter-panel.ts`）。
|
||||
- 筛选项数组经 `splitFilterFields()` 拆为首行 + 展开区；首行固定最多 4 项，**禁止**首行放 5 项导致第二行孤零零 1 项。
|
||||
- 展开区项数不得为 4n+1（避免展开后末行仅 1 项）；由 `splitFilterFields` 自动从首行借调平衡。
|
||||
- 切换按钮：`vm-filter-toggle` + 角标 `vm-filter-toggle-badge`。
|
||||
|
||||
### 4.2 输入框 `.vm-input`
|
||||
|
||||
@@ -105,6 +105,18 @@ export default function MyApp() {
|
||||
|
||||
参考：`vehicle-management/index.tsx`、`lease-business-ledger/index.tsx`。
|
||||
|
||||
## 业务逻辑文档化（强制）
|
||||
|
||||
实现**复杂判断逻辑**（多步判定、跨模块校验、状态/公式推导、导入保存规则等）时，必须与代码**同一轮**更新文档。详见 `rules/business-logic-documentation-guide.md`。
|
||||
|
||||
```text
|
||||
.spec/<logic-topic>.md # 完整规则（判定顺序、数据源、代码路径）
|
||||
.spec/requirements-prd.md # 摘要 + 验收项
|
||||
annotation-source.json # sync-annotation-directory.mjs 同步目录/字段标注
|
||||
```
|
||||
|
||||
范例：`lease-business-detail/.spec/field-checks.md`。
|
||||
|
||||
## 验收流程
|
||||
|
||||
运行原型验收脚本：
|
||||
@@ -132,3 +144,4 @@ node scripts/check-app-ready.mjs /prototypes/[原型目录]
|
||||
- [ ] 占位原型已更新为有意义的目录名和显示名。
|
||||
- [ ] 新增依赖已写入 `package.json`。
|
||||
- [ ] `check-app-ready.mjs` 原型验收通过。
|
||||
- [ ] 若含复杂业务逻辑：`.spec` 规格文 + PRD 摘要 + 标注目录已同步（见 `business-logic-documentation-guide.md`）。
|
||||
|
||||
@@ -46,6 +46,7 @@
|
||||
- 本次范围、功能清单和不做什么。
|
||||
- 页面或资源的核心内容、数据来源和素材来源。
|
||||
- 关键状态、核心路径和必要交互。
|
||||
- **复杂判定逻辑**（校验链、状态机、公式口径、导入规则）：在 PRD 中写摘要，并规划 `.spec/<topic>.md` 全文（见 `rules/business-logic-documentation-guide.md`）。
|
||||
- 用户最终如何判断结果可用。
|
||||
|
||||
只问会影响范围、成本或验收的问题。能从上下文推断的内容直接记为假设继续；如果缺失信息会导致不同功能范围、不同页面结构或不同验收标准，必须先问。
|
||||
|
||||
Reference in New Issue
Block a user