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

