# view/app 架构约定（Atomic Design / Core-3）

本应用是 GitDataAI 工作台前端。分层只回答“放哪里、能不能依赖”，
业务契约写在 TypeScript props 里。

## 分层

| 层 | 目录 | 允许做 | 禁止做 |
|---|---|---|---|
| 基础控件 | `src/ui` | 渲染原生控件、暴露 variant/size/disabled/ref、焦点与键盘 | 读路由、读会话、发请求、做业务校验 |
| 展示组合 | `src/components` | 组合 `ui`，接收 label/error/slots/回调 | 发请求、判断权限、读全局 store |
| 页面区块 | `src/blocks` | 页面级布局（AppShell/顶栏），内容全部由 props 注入 | 自己取数据 |
| 业务域 | `src/domains/*` | 请求、缓存、校验、权限、域内组件 | 被 `ui/components/blocks` 反向依赖 |
| 页面 | `src/pages/*` | 路由页面装配 | 沉淀可复用组件 |
| 基础设施 | `src/services/*` | API 客户端与适配、实时、语音、存储 | 渲染 UI |

依赖方向固定为 `ui → components → blocks` 逐级组合，`domains`/`pages` 消费系统层；
系统层不得 import `domains`、`pages`、`services`、`routing`。

## 判定顺序

1. 内部包含其他系统组件？是 → 不是 `ui`。
2. 承载业务动作、数据请求、校验或权限？是 → 放 `domains`。
3. 只服务单个页面？是 → 与该页面同域，不进系统层。
4. 纯展示但被多处复用？→ `components` 或 `blocks`。

## API 边界

- 生成客户端位于 `packages/apiclient`，由 `pnpm exec orval` 从仓库根 `openapi.json` 生成，不要手改。
- 统一经 `src/services/api` 调用；响应信封为 `{ code, message, data, error, error_code, request_id }`，
  `data: null` 表示成功但无内容，不是失败。
- 列表响应统一为 `{ items, total, limit, offset }`；请求 `limit` 不得超过服务端上限（空间域 100）。
- 会话走同源 Cookie；401 跳 `/auth/login?callback_url=<当前地址>`，不做令牌刷新重放。

## 资源

- `src/vendor/livekit` 为第三方 vendored 代码（含 styles/dist 与许可证），保持原样，不参与格式化与 lint。