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
7.1 KiB
7.1 KiB
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。
节点命名格式：
一级页面：xxx管理
功能跳转：xxx详情页
功能跳转：xxx编辑页
页面内功能：xxx
弹出框：xxx
不独立成页：xxx
推荐结构：
flowchart TD
A["一级页面：xxx管理"]
A --> B1["功能跳转：xxx详情页"]
A --> B2["功能跳转：xxx编辑页"]
B1 --> C1["页面内功能：查看xxx"]
B2 --> C2["页面内功能：维护xxx"]
C2 --> D1["弹出框：选择xxx"]
A --> C3["页面内功能：xxx状态调整"]
C3 --> D2["弹出框：状态调整确认"]
关联表不独立成页示例：
flowchart TD
A["一级页面：主体管理"]
A --> B1["功能跳转：主体编辑页"]
B1 --> C1["页面内功能：维护关联对象绑定"]
B1 --> C2["页面内功能：维护关联对象排序"]
C1 --> D1["弹出框：选择关联对象"]
X["不独立成页：主体关联关系"] -.-> C1
X -.-> C2
文档结构模板
生成文档时使用以下结构：
# <业务名>后台管理页面需求
## 说明
- 本文档面向前端 `admin` 后台页面实现。
- 只描述菜单、页面跳转、页面内功能和弹出框关系。
- 通用 CRUD 能力不重复描述，按后台管理通用列表页、详情页、编辑页能力实现。
- 纯关联表不单独做管理菜单；在主体资源详情/编辑中维护。
## 一级菜单
- <一级菜单名>
## 一级页面清单
- <一级页面1>
- <一级页面2>
## <一级页面1>
```mermaid
flowchart TD
A["一级页面：<一级页面1>"]
<一级页面2>
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 方法名。
- 是否特殊功能都体现为 `页面内功能` 或 `弹出框`。
- 是否文档能在没有对话上下文时独立理解。