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