147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
# 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. 逐步在后续开发中按需细化单篇规范，但保持入口文档结构稳定。
|