wdh-home
1e33640629
Some checks failed
CI / init (pull_request) Has been cancelled
CI / Frontend node 18.16.0 (pull_request) Has been cancelled
CI / Backend go (1.22) (pull_request) Has been cancelled
CI / release-pr (pull_request) Has been cancelled
CI / devops-test (1.22, 18.16.0) (pull_request) Has been cancelled
CI / release-please (pull_request) Has been cancelled
CI / devops-prod (1.22, 18.x) (pull_request) Has been cancelled
CI / docker (pull_request) Has been cancelled
257 lines
7.1 KiB
Markdown
257 lines
7.1 KiB
Markdown
# admin 菜单文档生成规范
|
||
|
||
## 触发方式
|
||
|
||
当用户输入以下类似指令时，按本规范生成文档：
|
||
|
||
- `生成admin菜单文档`
|
||
- `生成后台菜单文档`
|
||
- `根据admin接口文档生成前端菜单文档`
|
||
- `给前端整理admin管理页面`
|
||
|
||
## 目标
|
||
|
||
生成一份给前端看的后台页面需求文档，用来指导 `admin` 端通用管理页面建设。
|
||
|
||
文档只回答四件事：
|
||
|
||
- 有哪些一级菜单。
|
||
- 一级菜单下有哪些一级页面。
|
||
- 每个一级页面有哪些功能跳转。
|
||
- 每个一级页面有哪些页面内功能和弹出框。
|
||
|
||
## 输入来源
|
||
|
||
默认从以下目录读取接口文档：
|
||
|
||
- `.ai-specs/doc-api/admin`
|
||
|
||
如果用户指定其他目录，以用户指定目录为准。
|
||
|
||
生成前必须先查看该目录的 diff 或文件列表：
|
||
|
||
- 优先看 `git diff -- .ai-specs/doc-api/admin`。
|
||
- 如果没有 diff，再看 staged diff、未跟踪文件和目录内现有文件。
|
||
- 只基于实际存在的 admin 接口文档推导，不凭空增加模块。
|
||
|
||
## 输出位置
|
||
|
||
默认写入：
|
||
|
||
- `.ai-skills/<业务名>-admin-frontend-pages.md`
|
||
|
||
业务名优先从接口文档的模块、资源或文件名前缀推断。
|
||
|
||
示例：
|
||
|
||
- 书籍模块：`.ai-skills/book-admin-frontend-pages.md`
|
||
|
||
## 文档语言
|
||
|
||
- 中文为主体语言。
|
||
- 技术词保留英文原文，例如 `admin`、`CRUD`、`Mermaid`。
|
||
- 面向前端，不写后端实现细节。
|
||
|
||
## 内容边界
|
||
|
||
必须写：
|
||
|
||
- 一级菜单。
|
||
- 一级页面清单。
|
||
- 每个一级页面一张独立 Mermaid 图。
|
||
- 特殊功能，例如状态调整、审核、上下架、启停、绑定、排序、选择、导入、导出等。
|
||
- 不单独成页的关联表说明。
|
||
|
||
不要写：
|
||
|
||
- 通用 CRUD 明细。
|
||
- 接口 Method、Path、API 方法名、Service 方法名。
|
||
- 字段级详细表单需求。
|
||
- 后端分层实现说明。
|
||
- 权限、审计、Casbin 等后端细节，除非用户明确要求。
|
||
|
||
## 页面命名规范
|
||
|
||
统一使用以下概念，不要混用：
|
||
|
||
- `一级菜单`：侧边栏顶层业务菜单。
|
||
- `一级页面`：菜单下可直接进入的管理列表页。
|
||
- `功能跳转`：从一级页面进入的详情页、编辑页、配置页等。
|
||
- `页面内功能`：当前页面内完成的功能，不代表新页面。
|
||
- `弹出框`：选择、确认、绑定、排序、状态调整等弹窗。
|
||
- `不独立成页`：纯关联表、日志表、明细表等不应成为独立管理页的资源。
|
||
|
||
不要使用：
|
||
|
||
- `N级区域`
|
||
- `二级页面`，除非用户明确要求该词
|
||
- `模块页面` 这类不清晰命名
|
||
|
||
## 关联表处理规则
|
||
|
||
纯关联表默认不做独立一级页面。
|
||
|
||
判断依据：
|
||
|
||
- 文件名或资源名包含 `relation`、`binding`、`mapping`、`link`。
|
||
- 表意是两个主体资源之间的绑定关系。
|
||
- 没有独立业务生命周期，只依附主体资源维护。
|
||
|
||
处理方式：
|
||
|
||
- 放到主体表的编辑页或详情页中。
|
||
- 用 `页面内功能：绑定xxx`、`页面内功能：排序xxx` 表达。
|
||
- 如需选择对象，用 `弹出框：选择xxx` 表达。
|
||
- 在文档末尾 `不单独成页` 中说明原因。
|
||
|
||
示例：
|
||
|
||
- `书籍作者关系` 不做独立页面；放在 `书籍管理` 的作者绑定和作者排序功能中。
|
||
|
||
## 记录表处理规则
|
||
|
||
记录表可作为一级页面，但通常只提供查看和必要维护。
|
||
|
||
判断依据：
|
||
|
||
- 文件名或资源名包含 `record`、`log`、`history`。
|
||
- 表意是用户行为、操作痕迹、统计明细。
|
||
|
||
处理方式：
|
||
|
||
- 可生成 `xxx记录管理` 一级页面。
|
||
- 通常只生成 `功能跳转：xxx记录详情页`。
|
||
- 页面内功能重点写查看关系、查看用户、查看主体对象、查看时间/进度等。
|
||
- 不要主动设计复杂状态流转。
|
||
|
||
## 状态类功能处理规则
|
||
|
||
如果接口文档、SQL 文档或字典文档中出现状态字段，应在页面内功能中体现。
|
||
|
||
常见表达：
|
||
|
||
- `页面内功能：上下架状态调整`
|
||
- `页面内功能：完结状态调整`
|
||
- `页面内功能：作者状态调整`
|
||
- `页面内功能：系列启停/展示状态调整`
|
||
- `页面内功能：评论状态处理`
|
||
- `弹出框：状态调整确认`
|
||
- `弹出框：状态处理确认`
|
||
|
||
如果 admin 接口文档没有独立状态流转接口，只能写成页面需求，不要暗示后端已经有专用接口。
|
||
|
||
## Mermaid 图规范
|
||
|
||
每个一级页面单独一张图。
|
||
|
||
图必须使用 `flowchart TD`。
|
||
|
||
节点命名格式：
|
||
|
||
```text
|
||
一级页面：xxx管理
|
||
功能跳转：xxx详情页
|
||
功能跳转：xxx编辑页
|
||
页面内功能：xxx
|
||
弹出框：xxx
|
||
不独立成页：xxx
|
||
```
|
||
|
||
推荐结构：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["一级页面：xxx管理"]
|
||
|
||
A --> B1["功能跳转：xxx详情页"]
|
||
A --> B2["功能跳转：xxx编辑页"]
|
||
|
||
B1 --> C1["页面内功能：查看xxx"]
|
||
B2 --> C2["页面内功能：维护xxx"]
|
||
|
||
C2 --> D1["弹出框：选择xxx"]
|
||
A --> C3["页面内功能：xxx状态调整"]
|
||
C3 --> D2["弹出框：状态调整确认"]
|
||
```
|
||
|
||
关联表不独立成页示例：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["一级页面：主体管理"]
|
||
A --> B1["功能跳转：主体编辑页"]
|
||
B1 --> C1["页面内功能：维护关联对象绑定"]
|
||
B1 --> C2["页面内功能：维护关联对象排序"]
|
||
C1 --> D1["弹出框：选择关联对象"]
|
||
|
||
X["不独立成页：主体关联关系"] -.-> C1
|
||
X -.-> C2
|
||
```
|
||
|
||
## 文档结构模板
|
||
|
||
生成文档时使用以下结构：
|
||
|
||
```markdown
|
||
# <业务名>后台管理页面需求
|
||
|
||
## 说明
|
||
|
||
- 本文档面向前端 `admin` 后台页面实现。
|
||
- 只描述菜单、页面跳转、页面内功能和弹出框关系。
|
||
- 通用 CRUD 能力不重复描述，按后台管理通用列表页、详情页、编辑页能力实现。
|
||
- 纯关联表不单独做管理菜单；在主体资源详情/编辑中维护。
|
||
|
||
## 一级菜单
|
||
|
||
- <一级菜单名>
|
||
|
||
## 一级页面清单
|
||
|
||
- <一级页面1>
|
||
- <一级页面2>
|
||
|
||
## <一级页面1>
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["一级页面：<一级页面1>"]
|
||
```
|
||
|
||
## <一级页面2>
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["一级页面：<一级页面2>"]
|
||
```
|
||
|
||
## 不单独成页
|
||
|
||
- <关联表资源>：不做独立管理菜单，不做独立一级页面；在 `<主体页面>` 中作为 `<页面内功能>` 维护。
|
||
```
|
||
|
||
## 生成步骤
|
||
|
||
1. 读取 `.ai-specs/doc-api/admin` 的 diff、staged diff、未跟踪文件和文件列表。
|
||
2. 从文件名和文档标题提取资源清单。
|
||
3. 合并同一业务域为一级菜单。
|
||
4. 把主体资源、记录资源生成一级页面。
|
||
5. 把纯关联资源挂到主体资源页面内功能。
|
||
6. 为每个一级页面生成一张 Mermaid 图。
|
||
7. 删除所有通用 CRUD、接口路径、后端方法名。
|
||
8. 写入 `.ai-skills/<业务名>-admin-frontend-pages.md`。
|
||
9. 用 UTF-8 读取文件做一次快速确认。
|
||
|
||
## 质量检查
|
||
|
||
生成后逐项检查：
|
||
|
||
- 是否每个一级页面都有独立 Mermaid 图。
|
||
- 是否没有使用 `N级区域`。
|
||
- 是否没有把纯关联表做成独立页面。
|
||
- 是否没有展开通用 CRUD。
|
||
- 是否没有写接口 Method、Path、API 方法名、Service 方法名。
|
||
- 是否特殊功能都体现为 `页面内功能` 或 `弹出框`。
|
||
- 是否文档能在没有对话上下文时独立理解。
|
||
|