docs: add RESTful API refactor design and plan

docs/plans/2026-02-26-restful-api-refactor-design.md

@@ -0,0 +1,190 @@
+# RESTful API 全面重构设计
+
+**日期**: 2026-02-26
+**状态**: 待实现
+
+## 目标
+
+将后端 HTTP API 改造为完全符合 RESTful 规范，并同步更新前端适配代码。
+
+## 设计原则
+
+1. **资源导向 URL**：使用名词而非动词
+2. **HTTP 语义化**：状态通过状态码表达，响应体只包含必要数据
+3. **响应格式统一**：成功响应无冗余字段，错误响应使用 RFC 7807
+4. **文档同步**：路由变更必须同步更新文档
+
+## URL 重构
+
+### Auth 相关
+
+| 功能 | 当前 URL | 新 URL | HTTP 方法 |
+|------|----------|--------|-----------|
+| 注册发起 | `/signup/start` | `/verifications` | POST |
+| 重发验证码 | `/signup/resend` | `/verifications/resend` | POST |
+| 验证码校验 | `/signup/verify` | `/verifications/verify` | POST |
+| 登录 | `/login` | `/sessions` | POST |
+| 刷新 Token | `/refresh` | `/sessions/refresh` | POST |
+| 登出 | `/logout` | `/sessions` | DELETE |
+| 按邮箱查用户 | `/users/by-email` | `/users?email=xxx` | GET |
+
+### Profile → Users 统一
+
+| 功能 | 当前 URL | 新 URL | HTTP 方法 |
+|------|----------|--------|-----------|
+| 获取个人信息 | `/profile/me` | `/users/me` | GET |
+| 更新个人信息 | `/profile/me` | `/users/me` | PATCH |
+| 按用户名查用户 | `/profile/{username}` | `/users/{username}` | GET |
+
+### Agent Chat
+
+| 功能 | 当前 URL | 新 URL | HTTP 方法 |
+|------|----------|--------|-----------|
+| 运行对话 | `/agent-chat/run` | `/agent-chats` | POST |
+
+## 响应格式
+
+### 成功响应
+
+| 端点 | 状态码 | 响应体 |
+|------|--------|--------|
+| `POST /verifications` | 202 | `{email: string}` |
+| `POST /verifications/resend` | 204 | 无 |
+| `POST /verifications/verify` | 200 | `{access_token, refresh_token, expires_in, token_type, user}` |
+| `POST /sessions` | 200 | 同上 |
+| `POST /sessions/refresh` | 200 | 同上 |
+| `DELETE /sessions` | 204 | 无 |
+| `GET /users?email=xxx` | 200 | `{id, email, created_at, email_confirmed_at?}` |
+| `GET /users/me` | 200 | `{id, username, avatar_url?, bio?}` |
+| `PATCH /users/me` | 200 | 同上 |
+| `GET /users/{username}` | 200 | 同上 |
+| `POST /agent-chats` | 200 | `{session_id, output, events[]}` |
+
+### 错误响应
+
+保持 RFC 7807 格式（已实现）：
+
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Invalid verification code",
+  "instance": "/api/v1/verifications/verify"
+}
+```
+
+前端解析优先级：`detail` → `message` → `error` → "请求失败"
+
+## Schema 定义
+
+### 请求 Schema
+
+```python
+# verifications
+class VerificationCreateRequest(BaseModel):
+    username: str = Field(min_length=3, max_length=30)
+    email: EmailStr
+    password: str = Field(min_length=6)
+    redirect_to: str | None = None
+
+class VerificationResendRequest(BaseModel):
+    email: EmailStr
+
+class VerificationVerifyRequest(BaseModel):
+    email: EmailStr
+    token: str = Field(pattern=r"^\d{6}$")
+
+# sessions
+class SessionCreateRequest(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=6)
+
+class SessionRefreshRequest(BaseModel):
+    refresh_token: str = Field(min_length=1)
+
+class SessionDeleteRequest(BaseModel):
+    refresh_token: str = Field(min_length=1)
+
+# users
+class UserUpdateRequest(BaseModel):
+    username: str | None = Field(default=None, min_length=3, max_length=30)
+    avatar_url: str | None = None
+    bio: str | None = Field(default=None, max_length=200)
+```
+
+### 响应 Schema
+
+```python
+class VerificationCreateResponse(BaseModel):
+    email: EmailStr
+
+class SessionResponse(BaseModel):
+    access_token: str
+    refresh_token: str
+    expires_in: int
+    token_type: str
+    user: AuthUser
+
+class UserResponse(BaseModel):
+    id: str
+    username: str
+    avatar_url: str | None = None
+    bio: str | None = None
+
+class UserByEmailResponse(BaseModel):
+    id: str
+    email: EmailStr
+    created_at: str
+    email_confirmed_at: str | None = None
+```
+
+## 文件改动清单
+
+### 后端
+
+| 文件 | 改动 |
+|------|------|
+| `v1/auth/router.py` | URL 重命名，简化响应 |
+| `v1/auth/schemas.py` | 重命名/简化模型 |
+| `v1/auth/gateway.py` | 适配新 schema |
+| `v1/auth/service.py` | 适配新 schema |
+| `v1/profile/` → `v1/users/` | 目录重命名 |
+| `v1/users/router.py` | URL 更新 |
+| `v1/users/schemas.py` | 重命名模型 |
+| `v1/agent_chat/router.py` | URL 更新 |
+| `v1/router.py` | 更新路由注册 |
+| 测试文件 | 同步更新 |
+
+### 前端
+
+| 文件 | 改动 |
+|------|------|
+| `auth/data/auth_api.dart` | URL 更新 |
+| `auth/data/models/auth_response.dart` | 简化 SignupStartResponse，删除 SignupResendResponse |
+| `profile/data/profile_api.dart` | 改为 `users/data/users_api.dart` |
+| `profile/data/models/profile_response.dart` | 重命名 |
+| 相关 cubit/screen | 适配新 API |
+
+### 文档
+
+| 文件 | 改动 |
+|------|------|
+| `docs/runtime/runtime-route.md` | 新增，记录所有路由 |
+| `AGENTS.md` | 添加路由文档同步规则 |
+
+## 风险与缓解
+
+| 风险 | 缓解措施 |
+|------|----------|
+| 前后端不同步导致功能失效 | 同时修改，一次性提交 |
+| 测试覆盖不足 | 先更新测试，确保通过后再改实现 |
+| 遗漏某个调用点 | 全局搜索旧 URL 字符串 |
+
+## 验收标准
+
+- [ ] 所有后端测试通过
+- [ ] 所有前端测试通过
+- [ ] 手动验证注册/登录/登出流程
+- [ ] `runtime-route.md` 包含所有端点文档
+- [ ] `AGENTS.md` 包含路由同步规则