docs: add web agents design spec

web/docs/superpowers/specs/2026-04-22-web-agents-design.md

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