11

.cursor/rules/aiclient-overview.mdc

@@ -32,6 +32,62 @@ src-tauri/           # Tauri Rust 与配置
 - `npm run tauri dev` — 桌面开发
 - `npm run build` / `npm run tauri build` — 构建（前端无 `tsc` 步骤）
 
+## 后端 API 约定（pythonbackend）
+
+前端通过 HTTP 对接 `f:\projects\pythonbackend`（FastAPI，默认 `http://127.0.0.1:8001`）。业务接口前缀 `/api/v1`。
+
+### 统一响应 `ApiResponse<T>`
+
+所有 JSON 响应使用同一信封（与 `app/schemas/common.py` 一致）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | `boolean` | `true` 表示业务成功，`false` 表示失败（如校验、鉴权、业务错误） |
+| `message` | `string` | 提示文案，默认可为空；失败时展示给用户 |
+| `data` | `T \| null` | 成功时的载荷；失败时通常为 `null` 或省略 |
+
+前端处理模式：
+
+```js
+const body = await res.json();
+if (!body.ok) {
+  // 用 body.message 提示用户
+  return { ok: false, message: body.message };
+}
+// 使用 body.data
+```
+
+- 业务失败（如用户名已存在）仍返回 **HTTP 200**，以 `ok: false` 区分，勿仅依赖状态码。
+- 未认证访问受保护接口返回 **HTTP 401**（FastAPI 标准错误体，非 `ApiResponse` 信封）。
+
+### 认证
+
+- 登录/注册成功后，`data` 为 `TokenResponse`：
+  - `access_token`：JWT，前端持久化（如 localStorage `aiclient_token`）
+  - `token_type`：固定 `"bearer"`
+  - `user`：`{ id, username }`
+- 需登录的请求请求头：`Authorization: Bearer <access_token>`
+- 登出：`POST /api/v1/auth/logout`，带同上 Authorization；成功 `ok: true`，`message`: `"已退出登录"`
+
+### 认证相关端点
+
+| 方法 | 路径 | 请求体 | `data`（成功时） |
+|------|------|--------|------------------|
+| POST | `/api/v1/auth/register` | `{ username, password, confirmPassword }` | `TokenResponse` |
+| POST | `/api/v1/auth/login` | `{ username, password }` | `TokenResponse` |
+| POST | `/api/v1/auth/logout` | 无 | `null` |
+| GET | `/api/v1/auth/me` | 无 | `{ id, username }` |
+
+- 注册请求体字段名与前端表单一致：`confirmPassword`（camelCase）；其余 API JSON 字段为 **snake_case**（如 `access_token`）。
+- 密码规则与本地逻辑对齐：至少 6 位；用户名 trim 后非空。
+
+
+### 前端对接注意
+
+- Pinia `auth` store 的 `login` / `register` 可逐步改为调用上述 API，保留 `{ ok, message }` 与视图层一致。
+- 开发时后端需配置 CORS 包含 `http://localhost:1420`（见 pythonbackend `.env` 的 `CORS_ORIGINS`）。
+- 开发时 Vite 将 `/api` 代理到 `http://127.0.0.1:8001`（见 `vite.config.js`）；API 基址默认 `/api/v1`，生产可设 `VITE_API_BASE_URL`。
+
 ## 通用原则
 
 - 用户界面文案默认使用简体中文