Compare commits
3 Commits
8164eec650
...
65a5aac833
| Author | SHA1 | Date | |
|---|---|---|---|
| 65a5aac833 | |||
| a3b97cda1e | |||
| d8acafcdc5 |
11
server/.ai-specs/doc-dict/book_process_status.md
Normal file
11
server/.ai-specs/doc-dict/book_process_status.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# 书籍处理状态
|
||||
|
||||
- 模块：book
|
||||
- 字典编码：`book_process_status`
|
||||
|
||||
| Label | Value | Sort | Status | Desc |
|
||||
|:---|:---|:---|:---|:---|
|
||||
| 文件准备 | `file_ready` | 10 | true | 原始整本书文件已准备好，可进入拆分流程 |
|
||||
| 拆分章节 | `chapter_splitting` | 20 | true | 系统正在把整本书拆分成多个章节文件 |
|
||||
| 验证章节 | `chapter_verifying` | 30 | true | 系统正在校验章节拆分结果与内容完整性 |
|
||||
| 完成 | `process_completed` | 40 | true | 章节文件已生成并通过校验，可对外提供阅读 |
|
||||
@@ -1,25 +1,37 @@
|
||||
书名:
|
||||
子标题
|
||||
书籍类型:字典
|
||||
书籍标签 : 字典 ,标签是多个 要考虑用标签搜索书籍的性能问题
|
||||
书有系列:第一部 第二部, 上部 下部 , 所以有排序功能
|
||||
章节名: 章节是否能观看
|
||||
文件路径:oss url
|
||||
封面图片: url
|
||||
作者名(非id): 多个名字用,隔开
|
||||
出版社:
|
||||
出版时间:
|
||||
简介:
|
||||
热度:
|
||||
评分: 0-10分
|
||||
点评数:
|
||||
字数:
|
||||
书籍完结状态: 字典, 完结/连载
|
||||
# 书籍信息表
|
||||
- 书名:
|
||||
- 子标题
|
||||
- 书籍类型:字典
|
||||
- 书籍标签 : 字典 ,标签是多个 要考虑用标签搜索书籍的性能问题
|
||||
- 书有系列:第一部 第二部, 上部 下部 , 所以有排序功能
|
||||
- 封面图片: url
|
||||
- 出版社:
|
||||
- 出版时间:
|
||||
- 简介:
|
||||
- 热度:
|
||||
- 评分: 0-10分
|
||||
- 点评数:
|
||||
- 字数:
|
||||
- 书籍完结状态: 字典, 完结/连载
|
||||
- 书籍处理状态: 字典, 文件准备 / 拆分章节 / 验证章节 / 完成
|
||||
- 书籍系列Id
|
||||
- 系列内排序: 用于同系列书籍排序
|
||||
- 作者: 通过书籍作者关联表维护, 支持多个作者和排序
|
||||
- 原始书籍文件: 保存整本书文件存储地址
|
||||
- 内容存储: 原始整本书文件保存后, 系统再拆分成多个章节文件保存
|
||||
|
||||
# 书籍系列表
|
||||
- 名字
|
||||
- 封面图片
|
||||
- 书籍通过 系列Id + 系列内排序 挂到系列下
|
||||
|
||||
# 书籍章节表
|
||||
- 书籍Id
|
||||
- 章节标题
|
||||
- 章节排序
|
||||
- 是否可观看
|
||||
- 章节文件存储地址
|
||||
- 阅读历史和评论都通过 章节Id + 行号 定位
|
||||
|
||||
# 书籍作者表
|
||||
- 名字
|
||||
@@ -27,21 +39,51 @@
|
||||
- 简介
|
||||
- 封面图片： url
|
||||
|
||||
# 书籍作者关联表
|
||||
- 书籍Id
|
||||
- 作者Id
|
||||
- 作者排序
|
||||
- 一本书可关联多个作者, 一个作者可关联多本书
|
||||
|
||||
# 用户观看书籍历史表
|
||||
- 会员用户Id
|
||||
- 书籍Id
|
||||
- 观看书籍进度 : 前端显示 50%
|
||||
- 观看章节Id
|
||||
- 观看章节行数
|
||||
- 主定位以 章节Id + 行号 为准
|
||||
|
||||
|
||||
# 用户收藏书籍历
|
||||
# 用户收藏书籍历史表
|
||||
- 会员用户Id
|
||||
- 书籍Id
|
||||
|
||||
# 书籍评论表
|
||||
- 评论书籍id
|
||||
- 评论章节id
|
||||
- 评论用户Id
|
||||
- 评论书籍Id
|
||||
- 评论章节Id
|
||||
- 评论章节行数 ： 比如第二章第5行
|
||||
- 评论内容
|
||||
- 评论点赞数
|
||||
- 作者是否点赞
|
||||
- 主定位以 章节Id + 行号 为准
|
||||
|
||||
# 关系图
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Book["书籍"] --> Series["书籍系列"]
|
||||
Book --> SourceFile["整本原始文件"]
|
||||
Book --> Chapter["书籍章节"]
|
||||
Book --> BookAuthorRel["书籍作者关联"]
|
||||
BookAuthorRel --> Author["书籍作者"]
|
||||
SourceFile -.拆分生成.-> Chapter
|
||||
|
||||
User["用户"] --> History["观看书籍历史"]
|
||||
User --> Favorite["收藏书籍历史"]
|
||||
User --> Comment["书籍评论"]
|
||||
|
||||
History --> Book
|
||||
History --> Chapter
|
||||
Favorite --> Book
|
||||
Comment --> Book
|
||||
Comment --> Chapter
|
||||
```
|
||||
|
||||
@@ -133,6 +133,7 @@ flowchart LR
|
||||
|:---|:---|:---|
|
||||
| `.ai-specs\doc-dict\book_author_status.md` | 定义作者状态的标准值域 | 涉及作者状态的存储、校验、展示和接口出入参时必读 |
|
||||
| `.ai-specs\doc-dict\book_completion_status.md` | 定义书籍完结状态的标准值域 | 涉及书籍完结状态的存储、校验、展示和接口出入参时必读 |
|
||||
| `.ai-specs\doc-dict\book_process_status.md` | 定义书籍文件处理状态的标准值域 | 涉及原始文件准备、章节拆分、章节校验、处理完成等流程状态时必读 |
|
||||
|
||||
|
||||
## 可复用代码/组件
|
||||
|
||||
25
web/.ai-specs/coding-specs/api-request-flow.md
Normal file
25
web/.ai-specs/coding-specs/api-request-flow.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# api-request-flow
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增接口文件、修改请求封装、上传下载、统一错误处理时必读。
|
||||
|
||||
## 分层规则
|
||||
|
||||
- `src/api` 只负责请求函数和参数组织，统一调用 `@/utils/request`。
|
||||
- `src/utils/request.js` 负责 token、loading、统一错误处理、401 跳转和基础 headers。
|
||||
- 页面和 store 负责业务语义层的提示、页面状态更新和调用顺序。
|
||||
- 插件接口优先放在 `src/plugin/<plugin>/api`，但仍必须复用全局 `request.js`。
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 禁止在 `src/api` 里重复实现 token 注入、401 处理和全局 loading。
|
||||
- 禁止在 `src/api` 里写页面展示逻辑，例如直接操作页面组件状态。
|
||||
- 改接口返回结构时，必须同步回查调用页面、store 和错误提示。
|
||||
- 使用特殊请求选项时，优先复用 `donNotShowLoading` 和 `loadingOption` 约定。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 在页面里直接拼接 axios 请求，绕过 `src/api` 和 `request.js`。
|
||||
- 在 API 层直接弹 `ElMessage`，把展示逻辑和请求层耦合。
|
||||
- 修改 `request.js` 后没有检查上传、下载、插件接口的兼容性。
|
||||
25
web/.ai-specs/coding-specs/page-view-component-split.md
Normal file
25
web/.ai-specs/coding-specs/page-view-component-split.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# page-view-component-split
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增页面、抽公共组件、抽 hooks 时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/view` 负责页面级编排、页面级异步请求、页面生命周期和页面局部状态。
|
||||
- `src/components` 只放跨页面复用组件，不直接承载具体页面路由语义。
|
||||
- `src/hooks` 只放可复用行为逻辑，不承载模板和页面路由跳转。
|
||||
- 页面私有子组件优先放在页面目录内部，而不是直接放进 `src/components`。
|
||||
|
||||
## 新增代码默认落点
|
||||
|
||||
- 新页面：`src/view/<module>/index.vue` 或页面目录内对应 `.vue`
|
||||
- 页面局部子组件：`src/view/<module>/components/*`
|
||||
- 跨页面复用组件：`src/components/<component-name>/*`
|
||||
- 跨页面复用逻辑：`src/hooks/useXxx.js`
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只在一个页面使用的弹窗、表格、筛选器被塞进 `src/components`。
|
||||
- 页面内的大段逻辑直接复制到第二个页面，没有先评估是否抽 hooks。
|
||||
- hooks 内直接操作页面模板细节，导致复用边界失效。
|
||||
24
web/.ai-specs/coding-specs/pinia-store-boundary.md
Normal file
24
web/.ai-specs/coding-specs/pinia-store-boundary.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# pinia-store-boundary
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增 store、修改共享状态、决定状态是否全局化时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/pinia/modules` 只承载跨页面共享状态，不承载单页面临时表单态和局部弹窗态。
|
||||
- store 可以协调 API 调用、登录态恢复、路由初始化和全局字典，但不要承载组件展示逻辑。
|
||||
- 页面私有状态优先留在页面；仅在多个页面或守卫链路复用时再进入 store。
|
||||
- 插件若只有单页临时状态，优先使用页面局部状态或 plugin 内部 composable。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改 `user` store：同步检查 token、用户信息、401 清理和登录跳转。
|
||||
- 改 `router` store：同步检查动态路由注册、默认首页、keep-alive 和菜单进入。
|
||||
- 改 `dictionary` store：同步检查依赖字典的页面和表单。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 把列表筛选条件、弹窗开关、局部 loading 全部塞进全局 store。
|
||||
- 新增 store 字段时没有同步补齐初始化、清理和持久化行为。
|
||||
- store 内直接依赖页面组件实例或 DOM。
|
||||
26
web/.ai-specs/coding-specs/plugin-module-structure.md
Normal file
26
web/.ai-specs/coding-specs/plugin-module-structure.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# plugin-module-structure
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增插件、修改 `src/plugin/*` 结构、决定插件代码是否上提公共层时必读。
|
||||
|
||||
## 标准结构
|
||||
|
||||
- 插件目录默认落点：`src/plugin/<plugin>`
|
||||
- 插件内部优先自洽，常见子目录包括：
|
||||
- `api`
|
||||
- `view`
|
||||
- `form`
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 插件自己的页面、表单、接口优先放在插件目录内部，不要一开始就散落到主应用公共目录。
|
||||
- 插件必须复用主应用的 `@/utils/request`、`@/pinia`、`@/style`、`@/components` 能力，禁止复制全局基础设施。
|
||||
- 只有被多个插件或主应用反复复用的能力，才允许从插件目录上提到公共目录。
|
||||
- 插件若接入主应用菜单、权限、路由，必须回查主应用 `router / permission / pinia` 链路。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 为插件单独复制一份 request、bus、style 覆盖逻辑。
|
||||
- 插件里的组件刚出现一次就提升为全局组件。
|
||||
- 插件 API 改了，但没有同步检查插件页面和主应用集成点。
|
||||
24
web/.ai-specs/coding-specs/router-permission-route.md
Normal file
24
web/.ai-specs/coding-specs/router-permission-route.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# router-permission-route
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增页面路由、动态路由、白名单、登录跳转或菜单进入逻辑时必读。
|
||||
|
||||
## 当前入口
|
||||
|
||||
- 静态路由入口：`src/router/index.js`
|
||||
- 全局守卫入口：`src/permission.js`
|
||||
- 动态路由状态：`src/pinia/modules/router.js`
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新受保护页面不能绕开 `src/permission.js` 的登录态和动态路由流程。
|
||||
- 修改路由 `name`、`path`、`redirect` 时，必须同步检查菜单、默认首页、keep-alive 和页面标题。
|
||||
- 白名单只用于登录页、初始化页和明确公开页；不要随意放宽。
|
||||
- 插件页面若接入主应用菜单和权限，也必须服从现有动态路由注册机制。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只改 `src/router/index.js`，没有回查 `src/permission.js` 中的白名单和跳转逻辑。
|
||||
- 改页面路由名后，没有检查 `defaultRouter` 和缓存逻辑。
|
||||
- 单独为插件再造一个路由守卫入口，导致权限链路分叉。
|
||||
24
web/.ai-specs/coding-specs/style-asset-spec.md
Normal file
24
web/.ai-specs/coding-specs/style-asset-spec.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# style-asset-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及全局样式、Element Plus 样式覆盖、资源文件和主题变量时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/style` 只放全局样式、重置样式、主题覆盖和 Element Plus 覆盖。
|
||||
- 页面局部样式优先写在对应 `.vue` 文件内，不要随手上提到全局。
|
||||
- `src/assets` 放构建期静态资源；只有明确需要原样暴露的资源才考虑放 `public`。
|
||||
- Element Plus 的全局覆盖优先集中到 `src/style/element*` 相关文件。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改全局样式：同步检查登录页、主布局页、错误页和插件页。
|
||||
- 改主题变量或图标资源：同步检查使用这些资源的组件和页面。
|
||||
- 改资源引用路径：同步检查 Vite 构建、打包后路径和生产环境资源可达性。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 为了修某一个页面，把选择器直接写到全局样式里误伤其他页面。
|
||||
- 把只在一个页面使用的图片或样式工具放到全局目录。
|
||||
- 改 Element Plus 覆盖后没有检查常用表单、表格、弹窗。
|
||||
31
web/.ai-specs/sys-specs/env-build-spec.md
Normal file
31
web/.ai-specs/sys-specs/env-build-spec.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# env-build-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及 `.env.*`、`vite.config.js`、`package.json` scripts、构建参数和部署相关配置时必读。
|
||||
|
||||
## 当前构建链路
|
||||
|
||||
- 开发命令以 `package.json` 中的 `dev` / `serve` 为入口。
|
||||
- 构建命令以 `package.json` 中的 `build` 为入口。
|
||||
- Vite 主配置文件为 `vite.config.js`。
|
||||
- 运行时接口基地址由 `import.meta.env.VITE_BASE_API` 提供，消费点在 `src/utils/request.js`。
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新增前端环境变量时，变量名必须使用 `VITE_` 前缀。
|
||||
- 变更环境变量时，必须同步检查 `.env.development`、`.env.production` 和实际消费点。
|
||||
- 变更构建配置时，必须同步检查 `vite.config.js`、`package.json` scripts、`Dockerfile` 和部署路径假设。
|
||||
- 禁止把业务常量长期堆进 `.env.*`；只有部署环境相关变量才放环境文件。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改 `VITE_BASE_API` 或其消费方式：同步检查 `src/utils/request.js` 和所有上传/下载接口。
|
||||
- 改 Vite alias、静态资源策略或 publicPath：同步检查路由、静态资源引用和部署环境。
|
||||
- 改 scripts：同步检查 README、Docker 构建命令和团队既有运行方式。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只改一个环境文件，导致开发和生产行为不一致。
|
||||
- 在页面或 API 文件里硬编码后端域名，绕过 `VITE_BASE_API`。
|
||||
- 修改构建配置后没有验证登录页、主布局页和插件页是否还能正确加载资源。
|
||||
35
web/.ai-specs/sys-specs/frontend-directory-spec.md
Normal file
35
web/.ai-specs/sys-specs/frontend-directory-spec.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# frontend-directory-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增目录、移动文件、决定代码落点时必读。
|
||||
- 本文档只定义前端工程目录边界，不定义具体业务规则。
|
||||
|
||||
## 当前主目录职责
|
||||
|
||||
| 目录 | 职责 | 默认落点 |
|
||||
|:---|:---|:---|
|
||||
| `src/view` | 页面级目录，负责页面编排、页面级状态、页面生命周期 | 新页面、新页面内局部子组件 |
|
||||
| `src/components` | 跨页面复用组件 | 被多个页面或多个模块复用的 UI 片段 |
|
||||
| `src/hooks` | 可复用组合逻辑 | 多页面共享的行为逻辑 |
|
||||
| `src/api` | 主应用接口函数 | 主应用页面直接调用的请求封装 |
|
||||
| `src/pinia/modules` | 跨页面共享状态 | 登录态、路由态、全局字典、全局配置 |
|
||||
| `src/router` | 路由入口 | 静态路由定义 |
|
||||
| `src/plugin` | 插件化业务目录 | 插件自己的 `api / view / form` |
|
||||
| `src/utils` | 通用工具 | 与页面、组件解耦的工具逻辑 |
|
||||
| `src/style` | 全局样式与覆盖 | 全局样式、Element Plus 覆盖 |
|
||||
| `src/assets` | 构建期静态资源 | 图片、图标、背景资源 |
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新页面默认放在 `src/view/<module>`，不要直接放到 `src/components`。
|
||||
- 只有跨页面复用的 UI 才进入 `src/components`；只在单页内使用的组件优先放在页面目录内。
|
||||
- 共享行为逻辑优先放在 `src/hooks`；不要把纯逻辑长期堆在页面或组件里。
|
||||
- 插件相关代码优先留在 `src/plugin/<plugin>` 内部自洽，只有真正公共的能力才上提。
|
||||
- 不允许随意新增新的 `src/*` 顶层目录；必须先评估现有目录是否可以承载。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 把单页面局部组件放进 `src/components`，导致公共目录堆积业务代码。
|
||||
- 把页面状态塞进 `pinia`，导致全局状态污染。
|
||||
- 为插件单独复制一套请求层、路由层或全局样式层。
|
||||
27
web/.ai-specs/sys-specs/naming-import-path-spec.md
Normal file
27
web/.ai-specs/sys-specs/naming-import-path-spec.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# naming-import-path-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增目录、文件命名、导入路径和导出命名时必读。
|
||||
|
||||
## 命名规则
|
||||
|
||||
- 目录命名优先跟随现有项目风格；当前项目以 `lowerCamelCase` 目录较多，例如 `superAdmin`、`systemTools`。
|
||||
- 页面目录默认使用业务语义命名，页面入口文件优先使用 `index.vue`。
|
||||
- `pinia/modules` 中的文件名使用模块名，例如 `user.js`、`router.js`、`dictionary.js`。
|
||||
- store 导出统一使用 `useXxxStore`。
|
||||
- 新增 hooks 优先使用 `useXxx.js`；若扩展现有文件族，跟随邻近文件风格。
|
||||
- API 函数命名使用动词开头，优先使用 `get`、`list`、`create`、`update`、`delete`、`set`。
|
||||
|
||||
## 导入路径规则
|
||||
|
||||
- `src` 下的跨目录导入优先使用 `@/` 别名。
|
||||
- 同目录或紧邻目录的小范围导入可以使用相对路径。
|
||||
- 禁止新增深层级 `../../../` 风格导入来绕过别名。
|
||||
- 插件目录内引用主应用公共能力时，优先使用 `@/components`、`@/utils`、`@/style`、`@/pinia`。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 同一种概念在不同文件中使用不同命名，例如 `getUserList` 和 `fetchUsers` 混用。
|
||||
- 新增 hooks 没有 `use` 前缀，导致和普通工具函数混淆。
|
||||
- 同一功能有的用相对路径，有的用 `@/`，导致导入风格失控。
|
||||
168
web/AGENTS.md
168
web/AGENTS.md
@@ -1,73 +1,131 @@
|
||||
# AI 开发入口 [!IMPORTANT]
|
||||
|
||||
- 本文档为项目级别规范和重要导航,必须严格参考
|
||||
- 对我的回复/文档编写 ,必须是 中文为主体语言，技术术语保留英文原文
|
||||
- 强制工作流：按下方索引表定位需要的文档 → 读取匹配文档 → 进入源码
|
||||
- 禁止跳过文档检查直接写复杂业务；禁止已有对应文档却不读
|
||||
- 索引表无匹配时，按本文件通用规则和现有同层代码风格实现
|
||||
- 业务流程需要遵循 `主流做法` `工业级正规`
|
||||
- 规范型文档是给 AI 的顶层入口文档，不是“解释得更全”就更好，而是要 更短、更硬、更可判定
|
||||
- 本文档只允许在已有的结构上CURD,不允许增加其他标题区
|
||||
|
||||
- **本文档要求**：本文档为项目级别规范和重要导航，必须严格参考
|
||||
- **本文档要求**：本文档只允许在已有的结构上 CRUD，不允许增加其他标题区
|
||||
- **本文档要求**：`.ai-specs` 目录下新增/删除任何文档的时候都应该在本文档中修改 `## 项目文档`
|
||||
- **文档要求**：规范型文档是给 AI 的顶层入口文档，不是“解释得更全”就更好，而是要更短、更硬、更可判定
|
||||
- **代码优化**：先复用再新增，允许抽公共逻辑，但公共逻辑必须保证边界仍清晰
|
||||
- **代码优化**：优化代码时必须同时考虑冗余、孤岛代码、代码清晰度、复杂度、边界条件和兼容性，不能只追求功能跑通；不要修改 UI/UX 视觉效果，除非明确要求
|
||||
- **代码默认遵循**：业务流程需要遵循 `主流做法` `工业级正规`
|
||||
- **代码默认遵循**：强制工作流：按 `## 项目文档` 定位需要的文档 → 读取匹配文档 → 进入源码
|
||||
|
||||
## 工具使用规则
|
||||
|
||||
- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `.gitignore` 忽略的目录，以避免性能卡顿。
|
||||
- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `.gitignore` 忽略的目录，以避免性能卡顿
|
||||
- **读写**：所有文件读取/写入统一使用 UTF-8（建议无 BOM）
|
||||
- **读写**：PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`
|
||||
|
||||
## 当前项目代码要求
|
||||
|
||||
### 通用要求
|
||||
|
||||
- 优化代码时必须同时考虑冗余、孤岛代码、代码清晰度、复杂度、边界条件和兼容性，不能只追求功能跑通。
|
||||
- 优化代码时不要修改ui/ux 视觉效果,除非明确要求。
|
||||
- 先复用再新增
|
||||
- 允许抽公共逻辑，但公共逻辑必须放在根级共享目录，并保证边界仍清晰。
|
||||
|
||||
### 项目偏好
|
||||
-
|
||||
|
||||
## 文档体系
|
||||
|
||||
开始写代码前，根据下表判断当前任务涉及哪些文档，有对应文档必须先读。
|
||||
- .ai-specs 为规范根目录
|
||||
- .ai-specs\coding-specs
|
||||
- .ai-specs\logic-specs
|
||||
|
||||
### 目录索引表
|
||||
|
||||
| 类型 | 路径 | 用途 | 说明 |
|
||||
|:---|:---|:---|:---|
|
||||
- **画图**：优先使用 `mermaid flowchart`
|
||||
- **对话/文档编写**：必须是中文为主体语言，技术术语保留英文原文
|
||||
|
||||
## 项目架构
|
||||
|
||||
### 模块说明
|
||||
- **技术栈**：本项目为 `Vue 3 + Vite` 前端工程，基于 `gin-vue-admin` web 体系；路由使用 `Vue Router 4`，状态管理使用 `Pinia`，HTTP 请求使用 `Axios`，UI 组件库使用 `Element Plus`，构建与环境变量由 `Vite` 管理，样式体系包含 `SCSS` 与 `UnoCSS`
|
||||
- **代码链路**：本项目采用 `Router / Permission → View → Components / Hooks → API → Request → Backend` 主链路
|
||||
- `Pinia` 作为跨页面共享状态层，贯穿 `Permission`、`View`、`API`；`Plugin` 作为插件化业务子目录，内部可有自己的 `api / view / form`，但仍受主应用工程规则约束
|
||||
|
||||
├── web
|
||||
├── public (静态公开资源)
|
||||
├── src
|
||||
│ ├── api (主应用接口层)
|
||||
│ ├── assets (构建期静态资源)
|
||||
│ ├── components (跨页面复用组件)
|
||||
│ ├── core (项目基础配置与初始化)
|
||||
│ ├── directive (全局指令)
|
||||
│ ├── hooks (复用组合逻辑)
|
||||
│ ├── pinia (全局状态)
|
||||
│ │ └── modules (状态模块)
|
||||
│ ├── plugin (插件化业务目录)
|
||||
│ ├── router (静态路由入口)
|
||||
│ ├── style (全局样式与覆盖)
|
||||
│ ├── utils (通用工具与请求基座)
|
||||
│ ├── view (页面级目录)
|
||||
│ ├── App.vue (根组件)
|
||||
│ ├── main.js (应用入口)
|
||||
│ └── permission.js (全局路由守卫)
|
||||
├── .env.development (开发环境变量)
|
||||
├── .env.production (生产环境变量)
|
||||
├── package.json (脚本与依赖)
|
||||
└── vite.config.js (Vite 配置)
|
||||
|
||||
### 业务流转
|
||||
|
||||
#### 1. xxx
|
||||
|
||||
-
|
||||
|
||||
## 命名规范
|
||||
|
||||
-
|
||||
|
||||
|
||||
### 模块词汇
|
||||
|
||||
| 中文 | 英文 | 说明 |
|
||||
| 层级 | 职责 | 命名规范 |
|
||||
|:---|:---|:---|
|
||||
| 设备 | device | 设备管理模块 |
|
||||
| Router / Permission | 定义静态路由、接管全局守卫、处理登录态、动态路由注册和页面进入规则；禁止承载页面展示逻辑 | 路由入口固定 `src/router/index.js`；守卫入口固定 `src/permission.js` |
|
||||
| View | 承载页面编排、页面生命周期、页面局部状态和页面级接口调用；禁止把复用逻辑长期堆在页面中 | 页面目录固定 `src/view/<module>`；页面入口优先 `index.vue` |
|
||||
| Components | 承载跨页面复用 UI 组件和局部交互能力；禁止直接绑定具体页面路由语义 | 目录固定 `src/components/<component>`；组件入口优先 `index.vue` 或具名 `.vue` |
|
||||
| Hooks | 承载跨页面复用行为逻辑；禁止承载模板和页面路由配置 | 目录固定 `src/hooks`；新 hooks 优先使用 `useXxx.js` |
|
||||
| API | 承载接口函数和参数组织；禁止重复实现 token、401、loading 等全局请求逻辑 | 主应用目录固定 `src/api/<module>.js`；插件接口固定 `src/plugin/<plugin>/api/<module>.js` |
|
||||
| Request | 承载 Axios 实例、token 注入、全局 loading、统一错误处理和 401 跳转 | 请求基座固定 `src/utils/request.js` |
|
||||
| Pinia | 承载跨页面共享状态；禁止把单页面临时状态全部塞进全局 store | 模块目录固定 `src/pinia/modules/<module>.js`；store 导出使用 `useXxxStore` |
|
||||
| Style | 承载全局样式、重置样式和 Element Plus 覆盖；禁止把页面局部样式长期上提到全局 | 样式目录固定 `src/style`；Element Plus 覆盖优先放在 `src/style/element*` |
|
||||
| Plugin | 承载插件化业务代码，优先在插件目录内部自洽；禁止复制主应用基础设施 | 目录固定 `src/plugin/<plugin>`；常见子目录为 `api`、`view`、`form` |
|
||||
|
||||
- 新增页面时，主落点一律放在 `src/view/<module>`。
|
||||
- 新增接口时，主应用放在 `src/api`，插件接口放在 `src/plugin/<plugin>/api`。
|
||||
- 新增跨页面复用组件时，统一放在 `src/components`。
|
||||
- 新增跨页面共享行为逻辑时，统一放在 `src/hooks`。
|
||||
- 新增全局共享状态时，统一放在 `src/pinia/modules`。
|
||||
- 新增插件功能时，优先在 `src/plugin/<plugin>` 目录内闭环实现。
|
||||
|
||||
## 可复用组件
|
||||
### 架构关系
|
||||
|
||||
-
|
||||
- 关系总线：`sys-specs / coding-specs → Router / Permission → View → Components / Hooks / API → Request`，其中 `Pinia` 贯穿登录态、动态路由和跨页面共享状态；`Plugin` 沿用主应用同一套请求、路由、状态和样式基础设施
|
||||
|
||||
## 技术栈专项规范
|
||||
```mermaid
|
||||
flowchart LR
|
||||
SPEC["sys-specs / coding-specs"] --> Router
|
||||
Router["Router / Permission"] --> View
|
||||
View --> Components["Components / Hooks"]
|
||||
View --> API
|
||||
API --> Request["utils/request.js"]
|
||||
Pinia --> Router
|
||||
Pinia --> View
|
||||
Pinia --> API
|
||||
Plugin["plugin/*"] --> View
|
||||
Plugin --> API
|
||||
Request --> Backend["Backend"]
|
||||
```
|
||||
|
||||
### xxx
|
||||
-
|
||||
- 改 `view`：必须同步检查对应 `api`、`pinia`、路由入口、页面标题、keep-alive、权限显示是否仍一致
|
||||
- 改 `components`：必须同步检查调用页面、props、events、slots 和样式兼容性
|
||||
- 改 `hooks`：必须同步检查调用方是否仍满足生命周期和响应式前提
|
||||
- 改 `api`：必须同步检查 `src/utils/request.js` 契约、调用页面、store、错误提示和返回值结构
|
||||
- 改 `src/utils/request.js`：必须同步检查 token 注入、loading、401 跳转、上传下载和插件接口兼容性
|
||||
- 改 `pinia`：必须同步检查页面初始化、动态路由依赖、缓存和持久化字段
|
||||
- 改 `router` / `permission.js`：必须同步检查白名单、动态路由注入、默认首页、菜单跳转和未登录跳转
|
||||
- 改 `style`：必须同步检查全局覆盖范围，避免误伤登录页、主布局页和插件页
|
||||
- 改 `plugin/*`：必须同步检查插件内部 `api / view / form` 是否自洽，以及是否错误侵入主应用公共层
|
||||
|
||||
## 项目文档
|
||||
|
||||
- **根目录**：`.ai-specs`
|
||||
- **要求**：开始写代码前，根据任务类型先定位目录，再读取对应文档；有对应文档必须先读
|
||||
- **兜底**：索引表无匹配时，按本文件通用规则和现有同层代码风格实现
|
||||
|
||||
### coding-specs 存放对前端功能代码的说明/限制/要求
|
||||
|
||||
| 路径 | 用途 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| `.ai-specs\coding-specs\page-view-component-split.md` | 规定 `view / components / hooks` 的边界与默认落点 | 涉及新增页面、抽公共组件、抽 hooks 时必读 |
|
||||
| `.ai-specs\coding-specs\api-request-flow.md` | 规定 `api` 与 `request.js` 的分层、错误处理和请求链路 | 涉及新增接口、修改请求封装、上传下载、统一错误处理时必读 |
|
||||
| `.ai-specs\coding-specs\router-permission-route.md` | 规定静态路由、动态路由、白名单和权限链路 | 涉及新增页面路由、登录跳转、菜单进入、默认首页时必读 |
|
||||
| `.ai-specs\coding-specs\pinia-store-boundary.md` | 规定共享状态和页面状态的分层边界 | 涉及新增 store、共享状态、状态持久化时必读 |
|
||||
| `.ai-specs\coding-specs\plugin-module-structure.md` | 规定 `plugin/*` 的目录结构和与主应用公共层的关系 | 涉及新增插件、修改插件目录、决定代码是否上提时必读 |
|
||||
| `.ai-specs\coding-specs\style-asset-spec.md` | 规定全局样式、静态资源和主题覆盖的修改边界 | 涉及全局样式、Element Plus 覆盖、资源路径时必读 |
|
||||
|
||||
### sys-specs 存放前端系统级文档
|
||||
|
||||
| 路径 | 用途 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| `.ai-specs\sys-specs\frontend-directory-spec.md` | 规定前端工程目录总体结构和新增代码的默认落点 | 涉及新增目录、移动文件、决定代码放置位置时必读 |
|
||||
| `.ai-specs\sys-specs\naming-import-path-spec.md` | 规定命名、导入路径、别名和导出风格 | 涉及新增文件、目录命名、导入路径调整时必读 |
|
||||
| `.ai-specs\sys-specs\env-build-spec.md` | 规定环境变量、Vite 构建配置和 scripts 修改边界 | 涉及 `.env.*`、`vite.config.js`、`package.json` scripts 时必读 |
|
||||
|
||||
## 可复用代码/组件
|
||||
|
||||
| 中文 | 代码文件名 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| 请求基座 | `src/utils/request.js` | 统一 Axios 实例、token、loading、错误处理、401 跳转 |
|
||||
| 路由守卫 | `src/permission.js` | 统一登录态校验、动态路由注册、页面进入和跳转规则 |
|
||||
| 路由状态 | `src/pinia/modules/router.js` | 统一异步路由、keep-alive 和默认首页相关状态 |
|
||||
| 用户状态 | `src/pinia/modules/user.js` | 统一 token、用户信息和登录态清理 |
|
||||
| 事件总线 | `src/utils/bus.js` | 提供跨组件的全局 mitt 事件能力 |
|
||||
|
||||
@@ -0,0 +1,676 @@
|
||||
# Web AGENTS Frontend Spec Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build a frontend-engineering `web/AGENTS.md` plus `.ai-specs` document skeleton that matches the current `web` project structure and excludes business rules.
|
||||
|
||||
**Architecture:** Put project-wide entry rules, directory boundaries, and cross-check requirements in `web/AGENTS.md`. Put focused frontend engineering norms into `.ai-specs/sys-specs` and `.ai-specs/coding-specs`, keeping each file short, strict, and cross-referenced from `AGENTS.md`.
|
||||
|
||||
**Tech Stack:** Markdown, PowerShell, Git, Vue 3, Vite, Vue Router 4, Pinia, Axios, Element Plus
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
- Modify: `web/AGENTS.md`
|
||||
- Create: `web/.ai-specs/sys-specs/frontend-directory-spec.md`
|
||||
- Create: `web/.ai-specs/sys-specs/naming-import-path-spec.md`
|
||||
- Create: `web/.ai-specs/sys-specs/env-build-spec.md`
|
||||
- Create: `web/.ai-specs/coding-specs/page-view-component-split.md`
|
||||
- Create: `web/.ai-specs/coding-specs/api-request-flow.md`
|
||||
- Create: `web/.ai-specs/coding-specs/router-permission-route.md`
|
||||
- Create: `web/.ai-specs/coding-specs/pinia-store-boundary.md`
|
||||
- Create: `web/.ai-specs/coding-specs/plugin-module-structure.md`
|
||||
- Create: `web/.ai-specs/coding-specs/style-asset-spec.md`
|
||||
- Verify: `web/docs/superpowers/specs/2026-04-22-web-agents-design.md`
|
||||
|
||||
Each file has one clear responsibility:
|
||||
|
||||
- `web/AGENTS.md`: top-level entry for AI and developers before touching source code.
|
||||
- `sys-specs/*`: system-wide frontend engineering rules that affect many directories.
|
||||
- `coding-specs/*`: concrete coding boundaries for common frontend change types.
|
||||
|
||||
### Task 1: Create System-Level Spec Files
|
||||
|
||||
**Files:**
|
||||
- Create: `web/.ai-specs/sys-specs/frontend-directory-spec.md`
|
||||
- Create: `web/.ai-specs/sys-specs/naming-import-path-spec.md`
|
||||
- Create: `web/.ai-specs/sys-specs/env-build-spec.md`
|
||||
|
||||
- [ ] **Step 1: Create the `.ai-specs` directory tree**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Directory -Force D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs | Out-Null
|
||||
New-Item -ItemType Directory -Force D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs | Out-Null
|
||||
```
|
||||
|
||||
Expected: both directories exist and `Get-ChildItem D:\Code3\wdp\xuanzhi-service\web\.ai-specs` shows `coding-specs` and `sys-specs`.
|
||||
|
||||
- [ ] **Step 2: Write `frontend-directory-spec.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\frontend-directory-spec.md` with:
|
||||
|
||||
```markdown
|
||||
# frontend-directory-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增目录、移动文件、决定代码落点时必读。
|
||||
- 本文档只定义前端工程目录边界，不定义具体业务规则。
|
||||
|
||||
## 当前主目录职责
|
||||
|
||||
| 目录 | 职责 | 默认落点 |
|
||||
|:---|:---|:---|
|
||||
| `src/view` | 页面级目录，负责页面编排、页面级状态、页面生命周期 | 新页面、新页面内局部子组件 |
|
||||
| `src/components` | 跨页面复用组件 | 被多个页面或多个模块复用的 UI 片段 |
|
||||
| `src/hooks` | 可复用组合逻辑 | 多页面共享的行为逻辑 |
|
||||
| `src/api` | 主应用接口函数 | 主应用页面直接调用的请求封装 |
|
||||
| `src/pinia/modules` | 跨页面共享状态 | 登录态、路由态、全局字典、全局配置 |
|
||||
| `src/router` | 路由入口 | 静态路由定义 |
|
||||
| `src/plugin` | 插件化业务目录 | 插件自己的 `api / view / form` |
|
||||
| `src/utils` | 通用工具 | 与页面、组件解耦的工具逻辑 |
|
||||
| `src/style` | 全局样式与覆盖 | 全局样式、Element Plus 覆盖 |
|
||||
| `src/assets` | 构建期静态资源 | 图片、图标、背景资源 |
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新页面默认放在 `src/view/<module>`，不要直接放到 `src/components`。
|
||||
- 只有跨页面复用的 UI 才进入 `src/components`；只在单页内使用的组件优先放在页面目录内。
|
||||
- 共享行为逻辑优先放在 `src/hooks`；不要把纯逻辑长期堆在页面或组件里。
|
||||
- 插件相关代码优先留在 `src/plugin/<plugin>` 内部自洽，只有真正公共的能力才上提。
|
||||
- 不允许随意新增新的 `src/*` 顶层目录；必须先评估现有目录是否可以承载。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 把单页面局部组件放进 `src/components`，导致公共目录堆积业务代码。
|
||||
- 把页面状态塞进 `pinia`，导致全局状态污染。
|
||||
- 为插件单独复制一套请求层、路由层或全局样式层。
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Write `naming-import-path-spec.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\naming-import-path-spec.md` with:
|
||||
|
||||
```markdown
|
||||
# naming-import-path-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增目录、文件命名、导入路径和导出命名时必读。
|
||||
|
||||
## 命名规则
|
||||
|
||||
- 目录命名优先跟随现有项目风格；当前项目以 `lowerCamelCase` 目录较多，例如 `superAdmin`、`systemTools`。
|
||||
- 页面目录默认使用业务语义命名，页面入口文件优先使用 `index.vue`。
|
||||
- `pinia/modules` 中的文件名使用模块名，例如 `user.js`、`router.js`、`dictionary.js`。
|
||||
- store 导出统一使用 `useXxxStore`。
|
||||
- 新增 hooks 优先使用 `useXxx.js`；若扩展现有文件族，跟随邻近文件风格。
|
||||
- API 函数命名使用动词开头，优先使用 `get`、`list`、`create`、`update`、`delete`、`set`。
|
||||
|
||||
## 导入路径规则
|
||||
|
||||
- `src` 下的跨目录导入优先使用 `@/` 别名。
|
||||
- 同目录或紧邻目录的小范围导入可以使用相对路径。
|
||||
- 禁止新增深层级 `../../../` 风格导入来绕过别名。
|
||||
- 插件目录内引用主应用公共能力时，优先使用 `@/components`、`@/utils`、`@/style`、`@/pinia`。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 同一种概念在不同文件中使用不同命名，例如 `getUserList` 和 `fetchUsers` 混用。
|
||||
- 新增 hooks 没有 `use` 前缀，导致和普通工具函数混淆。
|
||||
- 同一功能有的用相对路径，有的用 `@/`，导致导入风格失控。
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Write `env-build-spec.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\env-build-spec.md` with:
|
||||
|
||||
```markdown
|
||||
# env-build-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及 `.env.*`、`vite.config.js`、`package.json` scripts、构建参数和部署相关配置时必读。
|
||||
|
||||
## 当前构建链路
|
||||
|
||||
- 开发命令以 `package.json` 中的 `dev` / `serve` 为入口。
|
||||
- 构建命令以 `package.json` 中的 `build` 为入口。
|
||||
- Vite 主配置文件为 `vite.config.js`。
|
||||
- 运行时接口基地址由 `import.meta.env.VITE_BASE_API` 提供，消费点在 `src/utils/request.js`。
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新增前端环境变量时，变量名必须使用 `VITE_` 前缀。
|
||||
- 变更环境变量时，必须同步检查 `.env.development`、`.env.production` 和实际消费点。
|
||||
- 变更构建配置时，必须同步检查 `vite.config.js`、`package.json` scripts、`Dockerfile` 和部署路径假设。
|
||||
- 禁止把业务常量长期堆进 `.env.*`；只有部署环境相关变量才放环境文件。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改 `VITE_BASE_API` 或其消费方式：同步检查 `src/utils/request.js` 和所有上传/下载接口。
|
||||
- 改 Vite alias、静态资源策略或 publicPath：同步检查路由、静态资源引用和部署环境。
|
||||
- 改 scripts：同步检查 README、Docker 构建命令和团队既有运行方式。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只改一个环境文件，导致开发和生产行为不一致。
|
||||
- 在页面或 API 文件里硬编码后端域名，绕过 `VITE_BASE_API`。
|
||||
- 修改构建配置后没有验证登录页、主布局页和插件页是否还能正确加载资源。
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Verify the three system spec files**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\frontend-directory-spec.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\naming-import-path-spec.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\env-build-spec.md
|
||||
```
|
||||
|
||||
Expected: all three files open as readable UTF-8 Chinese markdown and contain no placeholder text.
|
||||
|
||||
- [ ] **Step 6: Commit system-level specs**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git -C D:\Code3\wdp\xuanzhi-service add -- `
|
||||
web/.ai-specs/sys-specs/frontend-directory-spec.md `
|
||||
web/.ai-specs/sys-specs/naming-import-path-spec.md `
|
||||
web/.ai-specs/sys-specs/env-build-spec.md
|
||||
git -C D:\Code3\wdp\xuanzhi-service commit -m "docs: add web frontend system specs"
|
||||
```
|
||||
|
||||
Expected: a commit containing only the three `sys-specs` files.
|
||||
|
||||
### Task 2: Create Coding-Level Spec Files
|
||||
|
||||
**Files:**
|
||||
- Create: `web/.ai-specs/coding-specs/page-view-component-split.md`
|
||||
- Create: `web/.ai-specs/coding-specs/api-request-flow.md`
|
||||
- Create: `web/.ai-specs/coding-specs/router-permission-route.md`
|
||||
- Create: `web/.ai-specs/coding-specs/pinia-store-boundary.md`
|
||||
- Create: `web/.ai-specs/coding-specs/plugin-module-structure.md`
|
||||
- Create: `web/.ai-specs/coding-specs/style-asset-spec.md`
|
||||
|
||||
- [ ] **Step 1: Write `page-view-component-split.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\page-view-component-split.md` with:
|
||||
|
||||
```markdown
|
||||
# page-view-component-split
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增页面、抽公共组件、抽 hooks 时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/view` 负责页面级编排、页面级异步请求、页面生命周期和页面局部状态。
|
||||
- `src/components` 只放跨页面复用组件，不直接承载具体页面路由语义。
|
||||
- `src/hooks` 只放可复用行为逻辑，不承载模板和页面路由跳转。
|
||||
- 页面私有子组件优先放在页面目录内部，而不是直接放进 `src/components`。
|
||||
|
||||
## 新增代码默认落点
|
||||
|
||||
- 新页面：`src/view/<module>/index.vue` 或页面目录内对应 `.vue`
|
||||
- 页面局部子组件：`src/view/<module>/components/*`
|
||||
- 跨页面复用组件：`src/components/<component-name>/*`
|
||||
- 跨页面复用逻辑：`src/hooks/useXxx.js`
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只在一个页面使用的弹窗、表格、筛选器被塞进 `src/components`。
|
||||
- 页面内的大段逻辑直接复制到第二个页面，没有先评估是否抽 hooks。
|
||||
- hooks 内直接操作页面模板细节，导致复用边界失效。
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Write `api-request-flow.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\api-request-flow.md` with:
|
||||
|
||||
```markdown
|
||||
# api-request-flow
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增接口文件、修改请求封装、上传下载、统一错误处理时必读。
|
||||
|
||||
## 分层规则
|
||||
|
||||
- `src/api` 只负责请求函数和参数组织，统一调用 `@/utils/request`。
|
||||
- `src/utils/request.js` 负责 token、loading、统一错误处理、401 跳转和基础 headers。
|
||||
- 页面和 store 负责业务语义层的提示、页面状态更新和调用顺序。
|
||||
- 插件接口优先放在 `src/plugin/<plugin>/api`，但仍必须复用全局 `request.js`。
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 禁止在 `src/api` 里重复实现 token 注入、401 处理和全局 loading。
|
||||
- 禁止在 `src/api` 里写页面展示逻辑，例如直接操作页面组件状态。
|
||||
- 改接口返回结构时，必须同步回查调用页面、store 和错误提示。
|
||||
- 使用特殊请求选项时，优先复用 `donNotShowLoading` 和 `loadingOption` 约定。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 在页面里直接拼接 axios 请求，绕过 `src/api` 和 `request.js`。
|
||||
- 在 API 层直接弹 `ElMessage`，把展示逻辑和请求层耦合。
|
||||
- 修改 `request.js` 后没有检查上传、下载、插件接口的兼容性。
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Write `router-permission-route.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\router-permission-route.md` with:
|
||||
|
||||
```markdown
|
||||
# router-permission-route
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增页面路由、动态路由、白名单、登录跳转或菜单进入逻辑时必读。
|
||||
|
||||
## 当前入口
|
||||
|
||||
- 静态路由入口：`src/router/index.js`
|
||||
- 全局守卫入口：`src/permission.js`
|
||||
- 动态路由状态：`src/pinia/modules/router.js`
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 新受保护页面不能绕开 `src/permission.js` 的登录态和动态路由流程。
|
||||
- 修改路由 `name`、`path`、`redirect` 时，必须同步检查菜单、默认首页、keep-alive 和页面标题。
|
||||
- 白名单只用于登录页、初始化页和明确公开页；不要随意放宽。
|
||||
- 插件页面若接入主应用菜单和权限，也必须服从现有动态路由注册机制。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 只改 `src/router/index.js`，没有回查 `src/permission.js` 中的白名单和跳转逻辑。
|
||||
- 改页面路由名后，没有检查 `defaultRouter` 和缓存逻辑。
|
||||
- 单独为插件再造一个路由守卫入口，导致权限链路分叉。
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Write `pinia-store-boundary.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\pinia-store-boundary.md` with:
|
||||
|
||||
```markdown
|
||||
# pinia-store-boundary
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增 store、修改共享状态、决定状态是否全局化时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/pinia/modules` 只承载跨页面共享状态，不承载单页面临时表单态和局部弹窗态。
|
||||
- store 可以协调 API 调用、登录态恢复、路由初始化和全局字典，但不要承载组件展示逻辑。
|
||||
- 页面私有状态优先留在页面；仅在多个页面或守卫链路复用时再进入 store。
|
||||
- 插件若只有单页临时状态，优先使用页面局部状态或 plugin 内部 composable。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改 `user` store：同步检查 token、用户信息、401 清理和登录跳转。
|
||||
- 改 `router` store：同步检查动态路由注册、默认首页、keep-alive 和菜单进入。
|
||||
- 改 `dictionary` store：同步检查依赖字典的页面和表单。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 把列表筛选条件、弹窗开关、局部 loading 全部塞进全局 store。
|
||||
- 新增 store 字段时没有同步补齐初始化、清理和持久化行为。
|
||||
- store 内直接依赖页面组件实例或 DOM。
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Write `plugin-module-structure.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\plugin-module-structure.md` with:
|
||||
|
||||
```markdown
|
||||
# plugin-module-structure
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及新增插件、修改 `src/plugin/*` 结构、决定插件代码是否上提公共层时必读。
|
||||
|
||||
## 标准结构
|
||||
|
||||
- 插件目录默认落点：`src/plugin/<plugin>`
|
||||
- 插件内部优先自洽，常见子目录包括：
|
||||
- `api`
|
||||
- `view`
|
||||
- `form`
|
||||
|
||||
## 强制规则
|
||||
|
||||
- 插件自己的页面、表单、接口优先放在插件目录内部，不要一开始就散落到主应用公共目录。
|
||||
- 插件必须复用主应用的 `@/utils/request`、`@/pinia`、`@/style`、`@/components` 能力，禁止复制全局基础设施。
|
||||
- 只有被多个插件或主应用反复复用的能力，才允许从插件目录上提到公共目录。
|
||||
- 插件若接入主应用菜单、权限、路由，必须回查主应用 `router / permission / pinia` 链路。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 为插件单独复制一份 request、bus、style 覆盖逻辑。
|
||||
- 插件里的组件刚出现一次就提升为全局组件。
|
||||
- 插件 API 改了，但没有同步检查插件页面和主应用集成点。
|
||||
```
|
||||
|
||||
- [ ] **Step 6: Write `style-asset-spec.md`**
|
||||
|
||||
Create `D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\style-asset-spec.md` with:
|
||||
|
||||
```markdown
|
||||
# style-asset-spec
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 涉及全局样式、Element Plus 样式覆盖、资源文件和主题变量时必读。
|
||||
|
||||
## 边界规则
|
||||
|
||||
- `src/style` 只放全局样式、重置样式、主题覆盖和 Element Plus 覆盖。
|
||||
- 页面局部样式优先写在对应 `.vue` 文件内，不要随手上提到全局。
|
||||
- `src/assets` 放构建期静态资源；只有明确需要原样暴露的资源才考虑放 `public`。
|
||||
- Element Plus 的全局覆盖优先集中到 `src/style/element*` 相关文件。
|
||||
|
||||
## 联动检查
|
||||
|
||||
- 改全局样式：同步检查登录页、主布局页、错误页和插件页。
|
||||
- 改主题变量或图标资源：同步检查使用这些资源的组件和页面。
|
||||
- 改资源引用路径：同步检查 Vite 构建、打包后路径和生产环境资源可达性。
|
||||
|
||||
## 常见错误
|
||||
|
||||
- 为了修某一个页面，把选择器直接写到全局样式里误伤其他页面。
|
||||
- 把只在一个页面使用的图片或样式工具放到全局目录。
|
||||
- 改 Element Plus 覆盖后没有检查常用表单、表格、弹窗。
|
||||
```
|
||||
|
||||
- [ ] **Step 7: Verify the six coding spec files**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
Get-ChildItem D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\page-view-component-split.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\api-request-flow.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\router-permission-route.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\pinia-store-boundary.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\plugin-module-structure.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\style-asset-spec.md
|
||||
```
|
||||
|
||||
Expected: six files exist, are UTF-8 readable, and remain focused on frontend engineering rather than business rules.
|
||||
|
||||
- [ ] **Step 8: Commit coding-level specs**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git -C D:\Code3\wdp\xuanzhi-service add -- `
|
||||
web/.ai-specs/coding-specs/page-view-component-split.md `
|
||||
web/.ai-specs/coding-specs/api-request-flow.md `
|
||||
web/.ai-specs/coding-specs/router-permission-route.md `
|
||||
web/.ai-specs/coding-specs/pinia-store-boundary.md `
|
||||
web/.ai-specs/coding-specs/plugin-module-structure.md `
|
||||
web/.ai-specs/coding-specs/style-asset-spec.md
|
||||
git -C D:\Code3\wdp\xuanzhi-service commit -m "docs: add web frontend coding specs"
|
||||
```
|
||||
|
||||
Expected: a commit containing only the six `coding-specs` files.
|
||||
|
||||
### Task 3: Rewrite `web/AGENTS.md`
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/AGENTS.md`
|
||||
- Read: `web/.ai-specs/sys-specs/*`
|
||||
- Read: `web/.ai-specs/coding-specs/*`
|
||||
|
||||
- [ ] **Step 1: Replace `web/AGENTS.md` with the new frontend entry document**
|
||||
|
||||
Update `D:\Code3\wdp\xuanzhi-service\web\AGENTS.md` to:
|
||||
|
||||
```markdown
|
||||
# AI 开发入口 [!IMPORTANT]
|
||||
|
||||
- **本文档要求**：本文档为项目级别规范和重要导航，必须严格参考
|
||||
- **本文档要求**：本文档只允许在已有的结构上 CRUD，不允许增加其他标题区
|
||||
- **本文档要求**：`.ai-specs` 目录下新增/删除任何文档的时候都应该在本文档中修改 `## 项目文档`
|
||||
- **文档要求**：规范型文档是给 AI 的顶层入口文档，不是“解释得更全”就更好，而是要更短、更硬、更可判定
|
||||
- **代码优化**：先复用再新增，允许抽公共逻辑，但公共逻辑必须保证边界仍清晰
|
||||
- **代码优化**：优化代码时必须同时考虑冗余、孤岛代码、代码清晰度、复杂度、边界条件和兼容性，不能只追求功能跑通；不要修改 UI/UX 视觉效果，除非明确要求
|
||||
- **代码默认遵循**：业务流程需要遵循 `主流做法` `工业级正规`
|
||||
- **代码默认遵循**：强制工作流：按 `## 项目文档` 定位需要的文档 → 读取匹配文档 → 进入源码
|
||||
|
||||
## 工具使用规则
|
||||
|
||||
- **搜索范围限制**：Grep/Glob 严禁全盘搜索，绝对禁止扫描 `.gitignore` 忽略的目录，以避免性能卡顿
|
||||
- **读写**：所有文件读取/写入统一使用 UTF-8（建议无 BOM）
|
||||
- **读写**：PowerShell/脚本读取项目文件必须显式指定 `-Encoding utf8`
|
||||
- **画图**：优先使用 `mermaid flowchart`
|
||||
- **对话/文档编写**：必须是中文为主体语言，技术术语保留英文原文
|
||||
|
||||
## 项目架构
|
||||
|
||||
- **技术栈**：本项目为 `Vue 3 + Vite` 前端工程，基于 `gin-vue-admin` web 体系；路由使用 `Vue Router 4`，状态管理使用 `Pinia`，HTTP 请求使用 `Axios`，UI 组件库使用 `Element Plus`，构建与环境变量由 `Vite` 管理，样式体系包含 `SCSS` 与 `UnoCSS`
|
||||
- **代码链路**：本项目采用 `Router / Permission → View → Components / Hooks → API → Request → Backend` 主链路
|
||||
- `Pinia` 作为跨页面共享状态层，贯穿 `Permission`、`View`、`API`；`Plugin` 作为插件化业务子目录，内部可有自己的 `api / view / form`，但仍受主应用工程规则约束
|
||||
|
||||
├── web
|
||||
├── public (静态公开资源)
|
||||
├── src
|
||||
│ ├── api (主应用接口层)
|
||||
│ ├── assets (构建期静态资源)
|
||||
│ ├── components (跨页面复用组件)
|
||||
│ ├── core (项目基础配置与初始化)
|
||||
│ ├── directive (全局指令)
|
||||
│ ├── hooks (复用组合逻辑)
|
||||
│ ├── pinia (全局状态)
|
||||
│ │ └── modules (状态模块)
|
||||
│ ├── plugin (插件化业务目录)
|
||||
│ ├── router (静态路由入口)
|
||||
│ ├── style (全局样式与覆盖)
|
||||
│ ├── utils (通用工具与请求基座)
|
||||
│ ├── view (页面级目录)
|
||||
│ ├── App.vue (根组件)
|
||||
│ ├── main.js (应用入口)
|
||||
│ └── permission.js (全局路由守卫)
|
||||
├── .env.development (开发环境变量)
|
||||
├── .env.production (生产环境变量)
|
||||
├── package.json (脚本与依赖)
|
||||
└── vite.config.js (Vite 配置)
|
||||
|
||||
| 层级 | 职责 | 命名规范 |
|
||||
|:---|:---|:---|
|
||||
| Router / Permission | 定义静态路由、接管全局守卫、处理登录态、动态路由注册和页面进入规则；禁止承载页面展示逻辑 | 路由入口固定 `src/router/index.js`；守卫入口固定 `src/permission.js` |
|
||||
| View | 承载页面编排、页面生命周期、页面局部状态和页面级接口调用；禁止把复用逻辑长期堆在页面中 | 页面目录固定 `src/view/<module>`；页面入口优先 `index.vue` |
|
||||
| Components | 承载跨页面复用 UI 组件和局部交互能力；禁止直接绑定具体页面路由语义 | 目录固定 `src/components/<component>`；组件入口优先 `index.vue` 或具名 `.vue` |
|
||||
| Hooks | 承载跨页面复用行为逻辑；禁止承载模板和页面路由配置 | 目录固定 `src/hooks`；新 hooks 优先使用 `useXxx.js` |
|
||||
| API | 承载接口函数和参数组织；禁止重复实现 token、401、loading 等全局请求逻辑 | 主应用目录固定 `src/api/<module>.js`；插件接口固定 `src/plugin/<plugin>/api/<module>.js` |
|
||||
| Request | 承载 Axios 实例、token 注入、全局 loading、统一错误处理和 401 跳转 | 请求基座固定 `src/utils/request.js` |
|
||||
| Pinia | 承载跨页面共享状态；禁止把单页面临时状态全部塞进全局 store | 模块目录固定 `src/pinia/modules/<module>.js`；store 导出使用 `useXxxStore` |
|
||||
| Style | 承载全局样式、重置样式和 Element Plus 覆盖；禁止把页面局部样式长期上提到全局 | 样式目录固定 `src/style`；Element Plus 覆盖优先放在 `src/style/element*` |
|
||||
| Plugin | 承载插件化业务代码，优先在插件目录内部自洽；禁止复制主应用基础设施 | 目录固定 `src/plugin/<plugin>`；常见子目录为 `api`、`view`、`form` |
|
||||
|
||||
- 新增页面时，主落点一律放在 `src/view/<module>`。
|
||||
- 新增接口时，主应用放在 `src/api`，插件接口放在 `src/plugin/<plugin>/api`。
|
||||
- 新增跨页面复用组件时，统一放在 `src/components`。
|
||||
- 新增跨页面共享行为逻辑时，统一放在 `src/hooks`。
|
||||
- 新增全局共享状态时，统一放在 `src/pinia/modules`。
|
||||
- 新增插件功能时，优先在 `src/plugin/<plugin>` 目录内闭环实现。
|
||||
|
||||
### 架构关系
|
||||
|
||||
- 关系总线：`sys-specs / coding-specs → Router / Permission → View → Components / Hooks / API → Request`，其中 `Pinia` 贯穿登录态、动态路由和跨页面共享状态；`Plugin` 沿用主应用同一套请求、路由、状态和样式基础设施
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
SPEC["sys-specs / coding-specs"] --> Router
|
||||
Router["Router / Permission"] --> View
|
||||
View --> Components["Components / Hooks"]
|
||||
View --> API
|
||||
API --> Request["utils/request.js"]
|
||||
Pinia --> Router
|
||||
Pinia --> View
|
||||
Pinia --> API
|
||||
Plugin["plugin/*"] --> View
|
||||
Plugin --> API
|
||||
Request --> Backend["Backend"]
|
||||
```
|
||||
|
||||
- 改 `view`：必须同步检查对应 `api`、`pinia`、路由入口、页面标题、keep-alive、权限显示是否仍一致
|
||||
- 改 `components`：必须同步检查调用页面、props、events、slots 和样式兼容性
|
||||
- 改 `hooks`：必须同步检查调用方是否仍满足生命周期和响应式前提
|
||||
- 改 `api`：必须同步检查 `src/utils/request.js` 契约、调用页面、store、错误提示和返回值结构
|
||||
- 改 `src/utils/request.js`：必须同步检查 token 注入、loading、401 跳转、上传下载和插件接口兼容性
|
||||
- 改 `pinia`：必须同步检查页面初始化、动态路由依赖、缓存和持久化字段
|
||||
- 改 `router` / `permission.js`：必须同步检查白名单、动态路由注入、默认首页、菜单跳转和未登录跳转
|
||||
- 改 `style`：必须同步检查全局覆盖范围，避免误伤登录页、主布局页和插件页
|
||||
- 改 `plugin/*`：必须同步检查插件内部 `api / view / form` 是否自洽，以及是否错误侵入主应用公共层
|
||||
|
||||
## 项目文档
|
||||
|
||||
- **根目录**：`.ai-specs`
|
||||
- **要求**：开始写代码前，根据任务类型先定位目录，再读取对应文档；有对应文档必须先读
|
||||
- **兜底**：索引表无匹配时，按本文件通用规则和现有同层代码风格实现
|
||||
|
||||
### coding-specs 存放对前端功能代码的说明/限制/要求
|
||||
|
||||
| 路径 | 用途 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| `.ai-specs\coding-specs\page-view-component-split.md` | 规定 `view / components / hooks` 的边界与默认落点 | 涉及新增页面、抽公共组件、抽 hooks 时必读 |
|
||||
| `.ai-specs\coding-specs\api-request-flow.md` | 规定 `api` 与 `request.js` 的分层、错误处理和请求链路 | 涉及新增接口、修改请求封装、上传下载、统一错误处理时必读 |
|
||||
| `.ai-specs\coding-specs\router-permission-route.md` | 规定静态路由、动态路由、白名单和权限链路 | 涉及新增页面路由、登录跳转、菜单进入、默认首页时必读 |
|
||||
| `.ai-specs\coding-specs\pinia-store-boundary.md` | 规定共享状态和页面状态的分层边界 | 涉及新增 store、共享状态、状态持久化时必读 |
|
||||
| `.ai-specs\coding-specs\plugin-module-structure.md` | 规定 `plugin/*` 的目录结构和与主应用公共层的关系 | 涉及新增插件、修改插件目录、决定代码是否上提时必读 |
|
||||
| `.ai-specs\coding-specs\style-asset-spec.md` | 规定全局样式、静态资源和主题覆盖的修改边界 | 涉及全局样式、Element Plus 覆盖、资源路径时必读 |
|
||||
|
||||
### sys-specs 存放前端系统级文档
|
||||
|
||||
| 路径 | 用途 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| `.ai-specs\sys-specs\frontend-directory-spec.md` | 规定前端工程目录总体结构和新增代码的默认落点 | 涉及新增目录、移动文件、决定代码放置位置时必读 |
|
||||
| `.ai-specs\sys-specs\naming-import-path-spec.md` | 规定命名、导入路径、别名和导出风格 | 涉及新增文件、目录命名、导入路径调整时必读 |
|
||||
| `.ai-specs\sys-specs\env-build-spec.md` | 规定环境变量、Vite 构建配置和 scripts 修改边界 | 涉及 `.env.*`、`vite.config.js`、`package.json` scripts 时必读 |
|
||||
|
||||
## 可复用代码/组件
|
||||
|
||||
| 中文 | 代码文件名 | 说明 |
|
||||
|:---|:---|:---|
|
||||
| 请求基座 | `src/utils/request.js` | 统一 Axios 实例、token、loading、错误处理、401 跳转 |
|
||||
| 路由守卫 | `src/permission.js` | 统一登录态校验、动态路由注册、页面进入和跳转规则 |
|
||||
| 路由状态 | `src/pinia/modules/router.js` | 统一异步路由、keep-alive 和默认首页相关状态 |
|
||||
| 用户状态 | `src/pinia/modules/user.js` | 统一 token、用户信息和登录态清理 |
|
||||
| 事件总线 | `src/utils/bus.js` | 提供跨组件的全局 mitt 事件能力 |
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify `AGENTS.md` and the `.ai-specs` index are consistent**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\AGENTS.md
|
||||
Get-ChildItem D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs
|
||||
Get-ChildItem D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs
|
||||
```
|
||||
|
||||
Expected: every file listed under `## 项目文档` exists on disk and no extra `.ai-specs` file is missing from the index.
|
||||
|
||||
- [ ] **Step 3: Commit `AGENTS.md`**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git -C D:\Code3\wdp\xuanzhi-service add -- web/AGENTS.md
|
||||
git -C D:\Code3\wdp\xuanzhi-service commit -m "docs: add web agents entry"
|
||||
```
|
||||
|
||||
Expected: a commit containing only `web/AGENTS.md`.
|
||||
|
||||
### Task 4: Validate the Full Documentation Set
|
||||
|
||||
**Files:**
|
||||
- Verify: `web/AGENTS.md`
|
||||
- Verify: `web/.ai-specs/sys-specs/*.md`
|
||||
- Verify: `web/.ai-specs/coding-specs/*.md`
|
||||
- Read: `web/docs/superpowers/specs/2026-04-22-web-agents-design.md`
|
||||
|
||||
- [ ] **Step 1: Run placeholder and encoding checks**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
$p1 = 'TB' + 'D'
|
||||
$p2 = 'TO' + 'DO'
|
||||
$p3 = [char]24453 + [char]23450
|
||||
$p4 = [char]21344 + [char]20301
|
||||
$pattern = ($p1, $p2, $p3, $p4) -join '|'
|
||||
Select-String -Path D:\Code3\wdp\xuanzhi-service\web\AGENTS.md -Pattern $pattern -Encoding utf8
|
||||
Select-String -Path D:\Code3\wdp\xuanzhi-service\web\.ai-specs\sys-specs\*.md -Pattern $pattern -Encoding utf8
|
||||
Select-String -Path D:\Code3\wdp\xuanzhi-service\web\.ai-specs\coding-specs\*.md -Pattern $pattern -Encoding utf8
|
||||
```
|
||||
|
||||
Expected: no output.
|
||||
|
||||
- [ ] **Step 2: Run whitespace and patch integrity checks**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git -C D:\Code3\wdp\xuanzhi-service diff --check
|
||||
git -C D:\Code3\wdp\xuanzhi-service status --short
|
||||
```
|
||||
|
||||
Expected: no trailing-whitespace or conflict markers; `status --short` only shows the intended `web` documentation files if commits have not yet been made.
|
||||
|
||||
- [ ] **Step 3: Cross-check against the approved design spec**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\docs\superpowers\specs\2026-04-22-web-agents-design.md
|
||||
Get-Content -Raw -Encoding utf8 D:\Code3\wdp\xuanzhi-service\web\AGENTS.md
|
||||
```
|
||||
|
||||
Expected: `AGENTS.md` contains the four approved design areas: project hard rules, frontend architecture, linkage rules, and `.ai-specs` index; `.ai-specs` contains exactly the planned `sys-specs` and `coding-specs` files.
|
||||
|
||||
- [ ] **Step 4: Final documentation commit**
|
||||
|
||||
Run:
|
||||
|
||||
```powershell
|
||||
git -C D:\Code3\wdp\xuanzhi-service add -- web/AGENTS.md web/.ai-specs
|
||||
git -C D:\Code3\wdp\xuanzhi-service commit -m "docs: add web frontend engineering guide"
|
||||
```
|
||||
|
||||
Expected: a final commit that captures any remaining documentation fixes not already committed in earlier tasks.
|
||||
|
||||
## Self-Review
|
||||
|
||||
### Spec coverage
|
||||
|
||||
- `AGENTS.md` entry positioning: covered by Task 3.
|
||||
- Frontend-only engineering scope: covered by Tasks 1-3 content and Task 4 verification.
|
||||
- `.ai-specs` skeleton with `coding-specs` and `sys-specs`: covered by Tasks 1-2.
|
||||
- `plugin/*` inclusion: covered by Task 2 `plugin-module-structure.md` and Task 3 architecture section.
|
||||
- Linkage rules and directory responsibilities: covered by Task 3 plus the individual spec files.
|
||||
|
||||
### Placeholder scan
|
||||
|
||||
- The plan contains no placeholder markers or deferred-work wording.
|
||||
- Every file to create or modify has explicit target content.
|
||||
|
||||
### Type consistency
|
||||
|
||||
- All referenced file paths use the same final naming:
|
||||
- `frontend-directory-spec.md`
|
||||
- `naming-import-path-spec.md`
|
||||
- `env-build-spec.md`
|
||||
- `page-view-component-split.md`
|
||||
- `api-request-flow.md`
|
||||
- `router-permission-route.md`
|
||||
- `pinia-store-boundary.md`
|
||||
- `plugin-module-structure.md`
|
||||
- `style-asset-spec.md`
|
||||
146
web/docs/superpowers/specs/2026-04-22-web-agents-design.md
Normal file
146
web/docs/superpowers/specs/2026-04-22-web-agents-design.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# Web AGENTS 入口设计
|
||||
|
||||
## 背景
|
||||
|
||||
`D:\Code3\wdp\xuanzhi-service\server\AGENTS.md` 已经形成了一套清晰的 AI 开发入口模式：用一个顶层文档约束工程规则、架构边界和文档索引，再用 `.ai-specs` 承载更细的规范文档。
|
||||
|
||||
当前 `D:\Code3\wdp\xuanzhi-service\web\AGENTS.md` 只有标题，尚未形成前端工程入口。`web` 项目本身已经具备稳定目录结构，包括 `src/view`、`src/components`、`src/api`、`src/pinia`、`src/router`、`src/utils`、`src/style` 以及 `src/plugin/*`，因此适合补齐一套与服务端风格一致、但内容面向前端工程的入口文档体系。
|
||||
|
||||
## 目标
|
||||
|
||||
1. 为 `web` 项目建立一份前端工程级 `AGENTS.md`，作为 AI 和开发者进入源码前的第一入口。
|
||||
2. 建立 `web/.ai-specs` 文档骨架，用索引方式承载前端工程规范。
|
||||
3. 明确当前前端项目的目录职责、联动修改规则和新增代码落点。
|
||||
4. 将 `src/plugin/*` 纳入统一工程规范，而不是作为游离目录处理。
|
||||
|
||||
## 非目标
|
||||
|
||||
1. 不设计具体业务模块规范。
|
||||
2. 不定义列表页、表单页、详情页等业务交互模板。
|
||||
3. 不修改现有 UI/UX 风格，不重构现有目录。
|
||||
4. 不引入后端式的 `Router -> API -> Service -> Model` 结构到前端。
|
||||
|
||||
## 设计结论
|
||||
|
||||
### 1. 文档定位
|
||||
|
||||
`web/AGENTS.md` 采用与 `server/AGENTS.md` 同类的入口定位，但只覆盖前端工程规范。文档承担四类职责：
|
||||
|
||||
1. 项目级硬规则。
|
||||
2. 前端架构和目录职责说明。
|
||||
3. 改动联动检查规则。
|
||||
4. `.ai-specs` 文档索引。
|
||||
|
||||
文档风格保持“短、硬、可判定”，不写成教程，不堆叠背景描述。
|
||||
|
||||
### 2. 前端主链路
|
||||
|
||||
`web` 项目的主链路定义为：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Router["router / permission"] --> View
|
||||
View --> Components["components / hooks"]
|
||||
View --> API
|
||||
API --> Request["utils/request.js"]
|
||||
Request --> Backend["backend service"]
|
||||
Pinia["pinia"] --> View
|
||||
Pinia --> Router
|
||||
Pinia --> API
|
||||
Plugin["plugin/*"] --> View
|
||||
Plugin --> API
|
||||
Plugin --> Style["style"]
|
||||
```
|
||||
|
||||
核心边界如下：
|
||||
|
||||
- `src/view`：页面级编排与页面状态。
|
||||
- `src/components`：跨页面复用组件。
|
||||
- `src/hooks`：跨页面复用组合逻辑。
|
||||
- `src/api`：接口函数封装。
|
||||
- `src/utils/request.js`：请求基座，统一 token、loading、错误处理、401 跳转。
|
||||
- `src/pinia/modules`：跨页面共享状态。
|
||||
- `src/router` 与 `src/permission.js`：路由入口、动态路由注册、登录态和菜单进入逻辑。
|
||||
- `src/style`：全局样式和 Element Plus 覆盖。
|
||||
- `src/plugin/*`：插件化业务子目录，内部可有自己的 `api / view / form`，但仍服从主应用工程边界。
|
||||
|
||||
### 3. `AGENTS.md` 建议章节
|
||||
|
||||
建议保留与服务端相近的顶层结构：
|
||||
|
||||
1. `# AI 开发入口 [!IMPORTANT]`
|
||||
2. 项目级要求
|
||||
3. 工具使用规则
|
||||
4. 项目架构
|
||||
5. 架构关系
|
||||
6. 项目文档
|
||||
7. 可复用代码/组件
|
||||
|
||||
其中：
|
||||
|
||||
- “项目级要求”强调 UTF-8、中文为主、先查 `.ai-specs` 再写代码、禁止全盘搜索、优先复用。
|
||||
- “项目架构”写清前端主链路与目录职责。
|
||||
- “架构关系”写清改动时的联动检查。
|
||||
- “项目文档”只列 `.ai-specs` 索引，不夹带业务说明。
|
||||
|
||||
### 4. `.ai-specs` 目录设计
|
||||
|
||||
本次只建立前端工程文档，不建立业务文档。建议目录如下：
|
||||
|
||||
| 路径 | 职责 |
|
||||
|:---|:---|
|
||||
| `.ai-specs/coding-specs` | 面向日常编码的实现规则 |
|
||||
| `.ai-specs/sys-specs` | 面向整体工程的系统级规则 |
|
||||
|
||||
建议首批文档如下：
|
||||
|
||||
| 路径 | 用途 |
|
||||
|:---|:---|
|
||||
| `.ai-specs/coding-specs/page-view-component-split.md` | 规定 `view / components / hooks` 的边界与新增代码落点 |
|
||||
| `.ai-specs/coding-specs/api-request-flow.md` | 规定 `api` 与 `request.js` 的分层、错误处理和调用约束 |
|
||||
| `.ai-specs/coding-specs/router-permission-route.md` | 规定静态路由、动态路由、白名单和权限链路 |
|
||||
| `.ai-specs/coding-specs/pinia-store-boundary.md` | 规定 store 的职责边界与页面状态分层 |
|
||||
| `.ai-specs/coding-specs/plugin-module-structure.md` | 规定 `plugin/*` 的标准结构与和主应用的关系 |
|
||||
| `.ai-specs/coding-specs/style-asset-spec.md` | 规定 `style`、静态资源、主题覆盖的边界 |
|
||||
| `.ai-specs/sys-specs/frontend-directory-spec.md` | 规定前端工程目录总体结构和推荐新增落点 |
|
||||
| `.ai-specs/sys-specs/naming-import-path-spec.md` | 规定命名、导入别名、组件和 API 命名方式 |
|
||||
| `.ai-specs/sys-specs/env-build-spec.md` | 规定环境变量、Vite 构建配置和脚本修改边界 |
|
||||
|
||||
### 5. 联动修改规则
|
||||
|
||||
`web/AGENTS.md` 里应明确“改哪里，就必须回查哪里”，至少覆盖以下规则：
|
||||
|
||||
- 改 `view`：同步检查对应 `api`、`pinia`、路由入口、页面标题、keep-alive、权限显示。
|
||||
- 改 `components`：同步检查调用页面、props、events、slots 和样式兼容性。
|
||||
- 改 `hooks`：同步检查调用方是否仍满足生命周期与响应式前提。
|
||||
- 改 `api`：同步检查 `request.js` 契约、调用页面、store、错误提示和返回值结构。
|
||||
- 改 `request.js`：同步检查 token 注入、loading、401 跳转、上传下载、插件接口兼容性。
|
||||
- 改 `pinia`：同步检查页面初始化、异步路由依赖、缓存和持久化字段。
|
||||
- 改 `router` 或 `permission.js`：同步检查白名单、动态路由注入、默认首页、菜单跳转和未登录跳转。
|
||||
- 改 `style`：同步检查全局覆盖范围，避免误伤插件页面和其他公共页面。
|
||||
- 改 `plugin/*`：同步检查插件内部 `api / view / form` 是否自洽，以及是否错误侵入主应用公共层。
|
||||
|
||||
### 6. 落地粒度
|
||||
|
||||
本次落地只生成：
|
||||
|
||||
1. `web/AGENTS.md`
|
||||
2. `web/.ai-specs/coding-specs/*`
|
||||
3. `web/.ai-specs/sys-specs/*`
|
||||
|
||||
不生成业务文档，不补充页面交互规范，不额外引入新的工程目录。
|
||||
|
||||
## 验收标准
|
||||
|
||||
完成后应满足以下标准：
|
||||
|
||||
1. `web/AGENTS.md` 能独立说明前端工程规则、目录职责和文档入口。
|
||||
2. `.ai-specs` 中存在足够覆盖当前项目前端工程问题的首批骨架文档。
|
||||
3. 任意新增页面、组件、接口、store、plugin 模块时，都能先在 `AGENTS.md` 和 `.ai-specs` 中定位规则。
|
||||
4. 文档内容不越界到业务设计，不与 `server/AGENTS.md` 的定位冲突。
|
||||
|
||||
## 实施顺序
|
||||
|
||||
1. 新建 `web/.ai-specs` 目录与首批规范文档。
|
||||
2. 改写 `web/AGENTS.md`，引用并索引这些文档。
|
||||
3. 逐步在后续开发中按需细化单篇规范，但保持入口文档结构稳定。
|
||||
Reference in New Issue
Block a user