docs(web/app): document the workspace layering and API boundary
Record the Core-3 rules, the decision order for placing a component and the response/pagination conventions callers must follow.
ZhenYi committed
Added view/app/AGENTS.md view/app/AGENTS.md +37 −0 View view/app/AGENTS.md
@@ -0,0 +1,37 @@
1# view/app 架构约定（Atomic Design / Core-3）
2
3本应用是 GitDataAI 工作台前端。分层只回答“放哪里、能不能依赖”，
4业务契约写在 TypeScript props 里。
5
6## 分层
7
8| 层 | 目录 | 允许做 | 禁止做 |
9|---|---|---|---|
10| 基础控件 | `src/ui` | 渲染原生控件、暴露 variant/size/disabled/ref、焦点与键盘 | 读路由、读会话、发请求、做业务校验 |
11| 展示组合 | `src/components` | 组合 `ui`，接收 label/error/slots/回调 | 发请求、判断权限、读全局 store |
12| 页面区块 | `src/blocks` | 页面级布局（AppShell/顶栏），内容全部由 props 注入 | 自己取数据 |
13| 业务域 | `src/domains/*` | 请求、缓存、校验、权限、域内组件 | 被 `ui/components/blocks` 反向依赖 |
14| 页面 | `src/pages/*` | 路由页面装配 | 沉淀可复用组件 |
15| 基础设施 | `src/services/*` | API 客户端与适配、实时、语音、存储 | 渲染 UI |
16
17依赖方向固定为 `ui → components → blocks` 逐级组合，`domains`/`pages` 消费系统层；
18系统层不得 import `domains`、`pages`、`services`、`routing`。
19
20## 判定顺序
21
221. 内部包含其他系统组件？是 → 不是 `ui`。
232. 承载业务动作、数据请求、校验或权限？是 → 放 `domains`。
243. 只服务单个页面？是 → 与该页面同域，不进系统层。
254. 纯展示但被多处复用？→ `components` 或 `blocks`。
26
27## API 边界
28
29- 生成客户端位于 `packages/apiclient`，由 `pnpm exec orval` 从仓库根 `openapi.json` 生成，不要手改。
30- 统一经 `src/services/api` 调用；响应信封为 `{ code, message, data, error, error_code, request_id }`，
31 `data: null` 表示成功但无内容，不是失败。
32- 列表响应统一为 `{ items, total, limit, offset }`；请求 `limit` 不得超过服务端上限（空间域 100）。
33- 会话走同源 Cookie；401 跳 `/auth/login?callback_url=<当前地址>`，不做令牌刷新重放。
34
35## 资源
36
37- `src/vendor/livekit` 为第三方 vendored 代码（含 styles/dist 与许可证），保持原样，不参与格式化与 lint。