---
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` — 构建桌面端（仅生成 zip 便携包，不生成 MSI/NSIS 安装包；前端无 `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`。

## 通用原则

- 用户界面文案默认使用简体中文