From 44689a34eee13dc6a1560594de8469e2334ab309 Mon Sep 17 00:00:00 2001 From: wdh-home <243823965@qq.com> Date: Sat, 2 May 2026 16:16:47 +0800 Subject: [PATCH] 1 --- server/.ai-skills/admin-menu-doc-spec.md | 256 ------------------ .../prd-draft/book.md | 0 server/AGENTS.md | 6 - 3 files changed, 262 deletions(-) delete mode 100644 server/.ai-skills/admin-menu-doc-spec.md rename server/{.ai-specs => .ai-transition}/prd-draft/book.md (100%) diff --git a/server/.ai-skills/admin-menu-doc-spec.md b/server/.ai-skills/admin-menu-doc-spec.md deleted file mode 100644 index f25080c..0000000 --- a/server/.ai-skills/admin-menu-doc-spec.md +++ /dev/null @@ -1,256 +0,0 @@ -# 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 方法名。 -- 是否特殊功能都体现为 `页面内功能` 或 `弹出框`。 -- 是否文档能在没有对话上下文时独立理解。 - diff --git a/server/.ai-specs/prd-draft/book.md b/server/.ai-transition/prd-draft/book.md similarity index 100% rename from server/.ai-specs/prd-draft/book.md rename to server/.ai-transition/prd-draft/book.md diff --git a/server/AGENTS.md b/server/AGENTS.md index eee292f..c366a60 100644 --- a/server/AGENTS.md +++ b/server/AGENTS.md @@ -121,12 +121,6 @@ flowchart LR | `.ai-specs\coding-specs\sys-params.md` | 规定 `sys_params` 的读写方式与单参数独立 API 的封装方式 | 涉及系统参数读写、基于 `sys_params` 封装业务配置接口时必读 | | `.ai-specs\coding-specs\vo-model-request-response.md` | 规定项目中实体、API 入参、API 出参与通用结构在 `model` 体系内的落点与复用边界 | 涉及 `vo` 放置方式、是否复用实体、何时新增 `request/response` 结构时必读 | -### prd-draft 存放需求草案文档 - -| 路径 | 用途 | 说明 | -|:---|:---|:---| -| `.ai-specs\prd-draft\book.md` | 记录书籍需求草案，先列相关表和字段，再列业务需求描述 | 涉及书籍、书籍系列、书籍作者、书籍评论等业务设计时先读 | - ### sys-specs 存放系统级文档 | 路径 | 用途 | 说明 |