docs: add web frontend engineering guide

web/.ai-specs/coding-specs/api-request-flow.md

@@ -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` 后没有检查上传、下载、插件接口的兼容性。

web/.ai-specs/coding-specs/page-view-component-split.md

@@ -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 内直接操作页面模板细节，导致复用边界失效。

web/.ai-specs/coding-specs/pinia-store-boundary.md

@@ -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。

web/.ai-specs/coding-specs/plugin-module-structure.md

@@ -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 改了，但没有同步检查插件页面和主应用集成点。

web/.ai-specs/coding-specs/router-permission-route.md

@@ -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` 和缓存逻辑。
+- 单独为插件再造一个路由守卫入口，导致权限链路分叉。

web/.ai-specs/coding-specs/style-asset-spec.md

@@ -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 覆盖后没有检查常用表单、表格、弹窗。

web/.ai-specs/sys-specs/env-build-spec.md

@@ -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`。
+- 修改构建配置后没有验证登录页、主布局页和插件页是否还能正确加载资源。

web/.ai-specs/sys-specs/frontend-directory-spec.md

@@ -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`，导致全局状态污染。
+- 为插件单独复制一套请求层、路由层或全局样式层。

web/.ai-specs/sys-specs/naming-import-path-spec.md

@@ -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` 前缀，导致和普通工具函数混淆。
+- 同一功能有的用相对路径，有的用 `@/`，导致导入风格失控。