# 旧代码复用评估报告

日期：2026-07-06

## 结论

现有项目可以提供一些工程实现参考，但不建议直接在旧代码上硬改成新系统。

旧项目是 **大本营答疑资产后台系统 MVP**，核心流程是：

`飞书场次/转写稿 -> AI 清洗 -> 原始问答 -> 人工审核 -> 标准问答 -> 人工标记可调用`

新项目是 **AI 企业知识库问答系统**，核心流程是：

`用户登录 -> 获取授权知识库 -> 实时检索飞书知识库 -> 组装 Prompt -> 大模型流式回答 -> 保存聊天、引用和日志`

两个系统都涉及“问答”和“飞书”，但领域模型、权限逻辑、接口、数据库表和用户流程都不一样。为了后期维护和交接，V2 应该重新建立自己的领域模型，只选择性复用旧项目里的工程模式、小工具或局部服务代码。

## 新需求概要

根据这次上传的需求资料，V2 的目标包括：

- 飞书知识库是一阶段唯一知识来源。
- 一期不建立独立本地知识库，不做人工同步，不做向量数据库同步。
- 用户端使用手机号 + 短信验证码登录。
- 管理后台使用用户名 + 密码登录。
- AI 聊天支持多会话、历史聊天、流式输出、停止生成、Markdown 渲染、自动标题和每日聊天额度。
- AI 只能基于用户有权限访问的知识库和检索片段回答。
- 没有命中知识时，统一回答：`当前知识库中未检索到相关内容，请联系管理员补充相关知识。`
- 飞书或模型异常时，需要统一提示并记录日志。
- 后台包含首页统计、用户管理、管理员管理、知识库管理、Prompt 管理、模型管理、聊天记录、系统配置和操作日志。
- 核心表包括 `sys_user`、`sys_admin`、`sys_role`、`sys_knowledge`、`sys_user_kb`、`sys_chat_session`、`sys_chat_message`、`sys_prompt`、`sys_model`、`sys_system_config`、`sys_ai_request_log`、`sys_operation_log`。

## 旧项目现状

旧项目当前技术栈：

- 后端：FastAPI、SQLAlchemy、Pydantic、APScheduler、HTTPX。
- 前端：Next.js、React、TypeScript、TailwindCSS。
- 数据库：优先 PostgreSQL，未配置时使用 SQLite。
- AI：OpenAI 兼容 Chat Completions，支持 mock。
- 飞书：已有多维表格和文档读取适配器，支持 mock。
- H5：已有手机优先的聊天界面，但目前连接的是 `/api/standard-qa/callable`。

旧项目核心数据模型：

- `users`
- `feishu_sessions`
- `raw_qa_items`
- `standard_qa_items`
- `task_runs`
- `audit_logs`
- `system_settings`

## 可复用性评估

| 模块 | 复用等级 | 建议 |
| --- | --- | --- |
| FastAPI 应用骨架 | 高 | 可参考路由拆分、配置读取、CORS、依赖注入和 service 分层方式。 |
| SQLAlchemy / Pydantic 写法 | 中 | 可参考编码风格，但模型需要按 V2 的 `sys_*` 表重建。 |
| Next.js / Tailwind 前端工程 | 中 | 可参考工程搭建方式和页面实现经验，但页面要按 V2 用户端和后台流程重建。 |
| H5 聊天交互 | 中 | 可复用手机优先、聊天气泡、输入框、加载状态等交互思路；需要替换为真实会话接口和 SSE 流式问答。 |
| 飞书服务适配 | 中 | 可参考 token 获取、HTTP 封装、文档文本提取和 mock 模式；V2 仍需新增基于 SpaceID/NodeID 的实时知识库检索服务。 |
| AI 调用封装 | 中 | 可参考 OpenAI 兼容请求方式；V2 需要新增流式输出、停止生成、Prompt 组装、Token 记录和从数据库读取模型配置。 |
| 日志/审计思路 | 低到中 | 可参考日志意识；V2 需要实现 `sys_operation_log` 和 `sys_ai_request_log`，不能直接沿用旧审核日志语义。 |
| 定时任务 | 低 | V2 一期不做同步任务和向量库同步，定时任务不是核心。后续如有维护任务再引入。 |
| 旧问答审核领域 | 低 | 不建议作为 V2 核心。原始问答、标准问答、风险、脱敏、可调用状态属于旧系统领域。 |
| `/standard-qa/callable` 接口 | 低 | V2 应替换为聊天、会话、历史和 SSE 接口。这个接口可以作为旧系统能力保留，但不应驱动 V2。 |
| Docker Compose | 中 | 可复用容器化思路，但 V2 文档指定 MySQL 8.x。如果继续用 PostgreSQL，需要单独记录偏离原因。 |

## 缺口分析

V2 必须新建或重构的能力：

- 用户短信登录、Token、退出失效、账号有效期和每日额度。
- 管理员用户名密码登录、角色和权限控制。
- 知识库管理，字段包括知识库名称、SpaceID、NodeID、状态和备注。
- 用户知识库授权关系，支持生效时间和到期时间。
- 聊天会话和聊天消息持久化。
- SSE 流式接口 `POST /chat/completions`。
- 停止生成接口 `POST /chat/stop`。
- Prompt 管理和当前 Prompt 加载。
- 模型管理，包括 API URL、API Key、模型名称、温度、最大 Token 和超时。
- 系统配置，包括登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源、是否允许联网。
- 按权限过滤后的飞书实时检索。
- AI 请求日志，记录 Prompt、检索知识库、Token、耗时、状态和错误信息。
- 后台聊天记录查询、详情和导出。
- 围绕权限隔离、无命中兜底、不编造答案的测试和验收。

## 推荐技术方向

1. 继续把 `ai_knowledge_base_v2/` 作为新需求上下文和规划工作区。
2. 架构确认后，新建 V2 应用目录，而不是直接大面积修改旧 V1 文件。
3. 后端从第一天开始按模块拆分：
   - `auth`
   - `users`
   - `admins`
   - `knowledge`
   - `chat`
   - `rag`
   - `prompts`
   - `models`
   - `config`
   - `logs`
4. service 层保持边界清楚：
   - `SmsCodeService`
   - `TokenService`
   - `FeishuKnowledgeService`
   - `RagService`
   - `ModelClient`
   - `ChatService`
   - `AuditLogService`
5. 本地开发阶段需要明确 mock provider：
   - mock 短信验证码
   - mock 大模型回答
   - mock 飞书知识库检索
6. 生产环境的模型 API Key 不建议明文存储。需要优先考虑环境变量引用、密文存储或其他安全方案，并形成决策记录。

## 风险提示

- 新文档指定 MySQL 8.x，而旧项目使用 PostgreSQL/SQLite。这不是一个小改动，需要作为架构和部署决策处理。
- 文档要求“飞书更新后立即生效”和“每次提问实时检索”，这强依赖飞书实际 API 能力和租户权限，必须尽早做技术验证。
- 流式输出和停止生成会影响后端请求生命周期、前端渲染和消息落库语义，应作为核心能力设计。
- 权限是产品底线。每一次聊天检索都必须先过滤用户知识库权限，并记录实际使用的知识库和片段。

## 下一步建议

1. 确认 V2 是放在当前仓库的新应用目录，还是后续拆成独立仓库。
2. 先写 V2 架构和开发流程计划。
3. 搭建 V2 后端基础工程和 `sys_*` 领域模型。
4. 搭建 V2 用户端 H5，先跑通登录 mock、会话、SSE mock 问答。
5. 搭建后台基础框架和用户/知识库/Prompt/模型管理页面。
6. 尽早验证飞书实时检索和模型流式调用，避免后期被关键外部接口卡住。