基础项目

web/AGENTS.md

@@ -66,10 +66,38 @@
 - 新增全局共享状态时，统一放在 `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
@@ -85,34 +113,32 @@ flowchart LR
     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`
+### 外部文档路径
+| 路径 | 用途 | 说明 |
+|:---|:---|:---|
+| `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    存放对前端功能代码的说明/限制/要求
+#### 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       存放前端系统级文档
+#### sys-specs       存放前端系统级文档
 
 | 路径 | 用途 | 说明 |
 |:---|:---|:---|