# 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 方法名。 - 是否特殊功能都体现为 `页面内功能` 或 `弹出框`。 - 是否文档能在没有对话上下文时独立理解。