# V2 架构设计草案

日期：2026-07-06

## 架构目标

V2 架构要解决四件事：

1. 支持手机端优先的 AI 问答体验，并为后续微信小程序留出空间。
2. 后端必须把权限、聊天、RAG、模型、日志拆清楚，避免后期维护困难。
3. 外部依赖先 mock 后真实接入，保证本地可开发、可测试、可演示。
4. 关键能力可追溯：用户问题、检索知识库、Prompt、模型、Token、耗时和错误都要记录。

## 推荐仓库结构

建议继续在当前仓库中推进 V2，但所有 V2 代码放在 `ai_knowledge_base_v2/` 下，和旧系统隔离。

```text
ai_knowledge_base_v2/
  source_documents/          # 原始需求资料
  extracted/                 # 机器抽取文档
  development_records/       # 开发过程和决策记录
  reports/                   # 评估和调研报告
  apps/
    backend/                 # V2 后端服务
    user-client/             # 用户端 H5
    admin-web/               # 管理后台
  packages/
    shared-types/            # 前后端共享类型，可后续再建
```

说明：

- 先不删除旧系统，避免把两套不同领域模型混在一起。
- V2 代码目录后续新增时，也要同步记录到 `development_records/`。
- 如果未来决定拆独立仓库，再以当前目录为迁移源。

## 技术选型建议

### 后端

建议：`FastAPI + SQLAlchemy + Alembic + MySQL 8.x + Redis`

原因：

- 旧项目已经使用 FastAPI、SQLAlchemy、Pydantic，有可复用经验。
- 新数据库文档明确指定 MySQL 8.x，V2 应优先对齐。
- Alembic 用于数据库迁移，避免手工建表不可追踪。
- Redis 用于验证码、Token 黑名单、限流和可选的生成状态控制。

### 用户端

已确认：用户端直接使用 `Vue 3 + Vite + TypeScript` 开发 H5。

原因：

- 用户端主要场景是手机端。
- 当前一期目标是先把 H5 用户端功能做扎实。
- 用户明确要求用户端直接使用 Vue 3，不采用 uni-app。
- Vue 3 + Vite 足够支撑 H5 主链路，工程结构清晰，团队后续维护成本低。

说明：后续如果要转微信小程序，可以再评估独立小程序工程或迁移方案，但这不作为一期技术栈前置条件。

### 管理后台

建议：`Vue 3 + Vite + Element Plus`。

优先建议 Vue 3 的原因：

- 后台是典型表单、表格、筛选、弹窗、权限菜单场景。
- Element Plus 生态适合快速搭后台。
- 与用户端 Vue 3 技术体系一致，团队后续维护成本更低。

### AI/RAG

建议独立成后端 service，不单独拆微服务：

- `FeishuKnowledgeService`
- `RagService`
- `PromptService`
- `ModelClient`
- `AiRequestLogService`

一期先在单体后端内实现，后续并发或成本压力变大时再拆独立 AI 服务。

## 后端模块边界

| 模块 | 职责 |
| --- | --- |
| `auth` | 用户短信登录、管理员登录、Token 签发、退出失效。 |
| `users` | 普通用户资料、状态、额度、有效期。 |
| `admins` | 管理员账号、角色、后台权限。 |
| `knowledge` | 飞书知识库配置、开放状态、启用禁用和删除。 |
| `chat` | 会话、消息、标题、历史、停止生成。 |
| `rag` | 开放知识库过滤、飞书检索、Prompt 组装、冲突处理。 |
| `models` | 模型配置、启用模型、模型调用客户端。 |
| `prompts` | 系统 Prompt 查看、保存、恢复默认。 |
| `config` | 系统配置读写和运行时配置加载。 |
| `logs` | 操作日志、AI 请求日志、导出。 |
| `dashboard` | 首页统计和知识库排行榜。 |

## 核心调用链路

```text
用户发送问题
  -> Token 校验
  -> 账号状态/有效期校验
  -> 每日额度校验
  -> 获取全部已开放知识库
  -> 过滤禁用或未开放知识库
  -> 实时检索飞书知识库
  -> 无命中则返回固定兜底
  -> 组装 Prompt
  -> 调用启用模型
  -> SSE 流式输出
  -> 保存用户消息、AI 消息、检索片段、AI 请求日志
```

## 数据库原则

- 使用 MySQL 8.x、utf8mb4、InnoDB。
- 表名按需求文档使用 `sys_*`。
- 主键统一 `BIGINT AUTO_INCREMENT`。
- 常规删除使用 `is_deleted` 逻辑删除。
- 知识库删除按文档允许物理删除，但删除前必须二次确认并写操作日志。
- 生产环境密钥不建议明文保存；模型 API Key 需要在实现前做安全决策。

## 外部服务接入策略

| 外部服务 | 开发阶段 | 生产阶段 |
| --- | --- | --- |
| 短信验证码 | mock 固定验证码/控制台输出 | 接真实短信供应商 |
| 飞书知识库 | mock 检索数据 + 技术验证脚本 | 实时检索 SpaceID/NodeID |
| 大模型 | mock SSE + OpenAI 兼容流式调用 | 从后台启用模型配置读取 |
| Redis | 可选本地容器 | 验证码、Token 黑名单、限流、停止生成状态 |

## 风险和控制措施

| 风险 | 控制措施 |
| --- | --- |
| 飞书实时检索 API 能力不确定 | 阶段二开始前做技术验证脚本，确认 SpaceID/NodeID、权限和返回结构。 |
| H5 后续转小程序成本高 | 一期先按 Vue 3 H5 做稳定主链路；后续小程序单独评估迁移或新建工程。 |
| 知识库开放范围后补导致误检索 | RAG 链路第一步就是开放知识库过滤，接口测试必须覆盖禁用知识库不可检索场景。 |
| 模型回答编造 | 无命中固定兜底，Prompt 明确限制，日志记录检索片段和 Prompt。 |
| API Key 明文风险 | 开发前明确密钥存储策略，生产不在日志中输出密钥。 |
| 单文件膨胀 | 按模块和 service 拆分，控制单文件职责。 |

## 第一阶段暂定结论

1. V2 先在当前仓库 `ai_knowledge_base_v2/` 下继续推进。
2. 后端优先使用 FastAPI，数据库对齐文档使用 MySQL 8.x。
3. 用户端已确认使用 Vue 3 + Vite + TypeScript，管理后台优先使用 Vue 3 + Element Plus。
4. 第一条代码主线从后端基础工程和用户端 mock 主链路开始，不先做完整后台。
