docs: add web frontend engineering guide

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