94 lines
3.5 KiB
Plaintext
94 lines
3.5 KiB
Plaintext
---
|
||
description: aiclient 项目总览与通用约定
|
||
alwaysApply: true
|
||
---
|
||
|
||
# aiclient 项目约定
|
||
|
||
## 技术栈
|
||
|
||
- **桌面壳**：Tauri 2（Rust），单例、无边框、可拖动标题栏
|
||
- **前端**：Vue 3 + Vite 6，**纯 JavaScript**（不使用 TypeScript）
|
||
- **UI**：Tailwind CSS v4（`@tailwindcss/vite`）+ PrimeVue 4（Aura 深色预设）
|
||
- **状态/路由**：Pinia + Vue Router
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/ # Vue 前端
|
||
main.js # 入口：插件与全局组件注册
|
||
App.vue # 布局：标题栏 + router-view
|
||
styles/main.css # Tailwind + 科技感主题令牌
|
||
router/ # 路由与守卫
|
||
stores/ # Pinia（auth 等）
|
||
views/ # 页面
|
||
components/ # 可复用组件
|
||
src-tauri/ # Tauri Rust 与配置
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
- `npm run dev` — 仅前端（端口 1420）
|
||
- `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`。
|
||
|
||
## 通用原则
|
||
|
||
- 用户界面文案默认使用简体中文
|