xuanzhi-service/web/AGENTS.md

# 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` 沿用主应用同一套请求、路由、状态和样式基础设施

#### 新增链路规范

- 新增业务页面必须先判定：是否登录后访问、是否进入菜单、是否需要角色授权、是否需要按钮权限、是否需要 keep-alive、是否可能成为默认首页。
- 新增业务页面源码默认落在 `src/view/<module>/index.vue`；单页私有组件落在 `src/view/<module>/components`；跨页面复用组件才允许上提到 `src/components`。
- 新增页面接口默认新增或复用 `src/api/<module>.js`；接口函数只组织参数并调用 `@/utils/request`，页面不得直接写 axios、token、401、loading 等请求基础逻辑。
- 新增页面路由必须二选一：公开页、登录页、初始化页、独立工具页走 `src/router/index.js` 本地路由；登录后业务页、菜单页、权限页、缓存页、默认首页候选页走后台菜单远程路由。
- 新增远程菜单必须同步确认 `path`、`name`、`component`、`meta.title`、`meta.keepAlive`、`meta.closeTab`、`meta.defaultMenu`、角色授权和按钮权限；`component` 只写 `view/...` 或 `plugin/...` 正斜杠路径。
- 新增页面若依赖跨页面共享状态，才允许新增或修改 `src/pinia/modules/<module>.js`；单页面查询条件、弹窗状态、表单状态默认留在页面内。
- 新增页面若存在跨页面复用行为，才允许新增 `src/hooks/useXxx.js`；只被当前页面使用的组合逻辑优先留在页面目录内。
- 新增页面若涉及插件业务，优先在 `src/plugin/<plugin>/view` 与 `src/plugin/<plugin>/api` 内闭环实现，不得复制主应用请求层、路由层、store 基础设施。
- 新增页面若需要静态资源，构建期资源放 `src/assets`，公开直出资源放 `public`；页面局部样式留在页面内，只有全局覆盖或主题调整才修改 `src/style`。
- 新增页面完成后必须回查链路：`页面文件存在 → API 可调用 → 路由/菜单可进入 → 权限可见 → keep-alive/defaultRouter 符合预期 → 刷新和未登录跳转正常`。

#### 代码联动
- 改 `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` 是否自洽，以及是否错误侵入主应用公共层

#### 关系图

```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"]
```

## 项目文档

### 外部文档路径
| 路径 | 用途 | 说明 |
|:---|:---|:---|
| `D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-api\admin` | 后台API文档路径 | 涉及 API / 参数 时必读,不允许凭空捏造API参数|
| `D:\Code3\wdp\xuanzhi-service\.worktrees\feat-xuanzhi-service\server\.ai-specs\doc-dict` | 后台字典文档路径 | 涉及 字典 时必读,不允许凭空捏造字典数据 ,不允许使用硬编码字典数据 |

### .ai-specs 

- **要求**：开始写代码前，根据任务类型先定位目录，再读取对应文档；有对应文档必须先读
- **兜底**：索引表无匹配时，按本文件通用规则和现有同层代码风格实现

#### coding-specs    存放对前端功能代码的说明/限制/要求

| 路径 | 用途 | 说明 |
|:---|:---|:---|
| `.ai-specs\coding-specs\page-view-component-split.md` | 规定 `view / components / hooks` 的边界与默认落点 | 涉及新增页面、抽公共组件、抽 hooks 时必读 |
| `.ai-specs\coding-specs\common-page-create-spec.md` | 规定通用页面创建链路、本地路由/远程路由选择和联调要求 | 涉及新增通用页面、菜单接入、页面联调时必读 |
| `.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 事件能力 |