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