# 阶段二记录：后端基础工程第一批

日期：2026-07-06

## 本次目标

按照阶段二规划，先建立 V2 后端基础工程，并跑通用户端第一批 P0 接口的后端 mock 链路。

## 已完成

### 后端工程骨架

- 新建 `ai_knowledge_base_v2/apps/backend/`。
- 新增 FastAPI 应用入口。
- 新增健康检查接口：`GET /api/health`。
- 新增统一 JSON 响应结构：`code`、`message`、`data`。
- 新增统一异常处理：HTTP 异常和参数校验异常都会返回统一结构。
- 新增 `.env.example`、`requirements.txt`、后端 `.gitignore`。

### 数据库和迁移

- 新增 SQLAlchemy 数据库连接。
- 新增 Alembic 配置。
- 新增第一版初始化迁移：`0001_initial_schema.py`。
- 按字段字典建立核心表：
  - `sys_user`
  - `sys_admin`
  - `sys_role`
  - `sys_knowledge`
  - `sys_user_kb`（早期文档预留表；2026-07-07 新口径下不再作为一期主链路依赖）
  - `sys_chat_session`
  - `sys_chat_message`
  - `sys_prompt`
  - `sys_model`
  - `sys_system_config`
  - `sys_ai_request_log`
  - `sys_operation_log`

### 用户登录

- 新增 mock 短信验证码服务。
- 新增用户手机号验证码登录。
- 首次登录自动创建用户。
- 新增 JWT Token 签发。
- 新增退出登录 Token 黑名单。
- 新增当前用户接口：`GET /api/user/profile`。

### 聊天 mock 主链路

- 新增创建会话：`POST /api/chat/session`。
- 新增会话列表：`GET /api/chat/session/list`。
- 新增聊天历史：`GET /api/chat/history`。
- 新增修改标题：`PUT /api/chat/session/title`。
- 新增删除会话：`DELETE /api/chat/session/{id}`。
- 新增 mock SSE 问答：`POST /api/chat/completions`。
- 新增停止生成占位接口：`POST /api/chat/stop`。

## 当前边界

- 短信仍是 mock，默认验证码为 `123456`。
- 飞书实时检索尚未接入。
- 大模型尚未接入，`/chat/completions` 当前返回 mock SSE。
- 管理员登录接口尚未实现。
- Token 黑名单当前是内存实现，后续需要替换为 Redis。

## 已验证

- Python 编译检查通过：`python3 -m compileall -q ai_knowledge_base_v2/apps/backend/app ai_knowledge_base_v2/apps/backend/alembic`。
- 本地虚拟环境依赖安装通过：`pip install -r requirements.txt`。
- FastAPI 应用导入和 OpenAPI 生成通过，当前生成 13 条路径。

## 下一步建议

1. 补管理员登录和基础角色权限。
2. 补聊天接口的数据库级测试或最小接口测试。
3. 准备 MySQL 本地 Docker Compose，跑 Alembic 迁移验证。
4. 开始 Vue 3 H5 用户端工程，先接 mock 登录和聊天接口。
