# V2 技术决策记录

日期：2026-07-06

## 记录方式

状态说明：

- `建议采纳`：当前建议按此执行，后续如修改需要新增决策记录。
- `待确认`：先作为默认假设推进，但需要用户或技术验证确认。
- `已确认`：已经明确执行。

## D-001：V2 代码与文档放在独立目录

状态：建议采纳

决策：V2 继续在当前仓库推进，但所有 V2 文档和后续代码都放在 `ai_knowledge_base_v2/` 下。

原因：

- 避免和旧“答疑资产后台系统”混在一起。
- 当前远端仓库已经打通提交和推送，便于持续追踪。
- 后续如果需要拆仓库，可以从这个目录迁移。

## D-002：数据库优先使用 MySQL 8.x

状态：建议采纳

决策：V2 数据库按需求文档使用 MySQL 8.x、utf8mb4、InnoDB。

原因：

- 数据库设计文档明确指定 MySQL 8.x。
- 字段字典、表命名和部署文档都围绕该方向。
- 旧项目的 PostgreSQL/SQLite 只能作为旧系统实现参考，不作为 V2 默认数据库。

## D-003：后端优先使用 FastAPI

状态：建议采纳

决策：V2 后端优先使用 FastAPI + SQLAlchemy + Alembic。

原因：

- 旧项目已有 FastAPI 经验，可以复用工程实践。
- FastAPI 适合快速实现 REST、SSE 和 OpenAI 兼容模型调用。
- SQLAlchemy 可以兼容 MySQL，Alembic 能提供可追踪迁移。

## D-004：用户端直接使用 Vue 3 H5

状态：已确认

决策：用户端直接使用 `Vue 3 + Vite + TypeScript` 开发 H5，不采用 uni-app。

原因：

- 用户明确拍板：用户端直接用 Vue 3，不用 uni-app。
- 一期重点是把 H5 用户端功能能力做好。
- Vue 3 + Vite 工程清晰，适合后续长期维护。

影响：

- 后续如果要做微信小程序，需要单独评估迁移方案或新建小程序工程。
- 旧 Next.js H5 代码主要复用交互经验，不作为 V2 用户端代码基础。

## D-005：管理后台优先评估 Vue 3 + Element Plus

状态：待确认

决策：管理后台建议优先使用 Vue 3 + Vite + Element Plus。

原因：

- 后台是典型表格、表单、筛选、弹窗和权限菜单场景。
- Element Plus 可以快速搭建可维护后台。
- 与用户端 Vue 3 技术体系更一致。

备选：

- 如果团队强希望复用旧 Next.js 后台经验，可以继续用 Next.js，但要记录技术栈不统一的维护成本。

## D-006：短信、飞书、大模型先 mock 后真实接入

状态：建议采纳

决策：外部服务必须先有 mock provider，保证本地开发和测试不被外部账号、权限、费用阻塞。

原因：

- 短信供应商未确认。
- 飞书实时检索 API 需要技术验证。
- 大模型供应商和模型参数未最终确认。

## D-007：RAG 不单独拆微服务

状态：建议采纳

决策：一期 RAG 能力先作为后端内部 service 实现，不单独拆微服务。

原因：

- 一期重点是跑通业务闭环。
- 单体更容易部署、调试和回滚。
- 后续并发、成本、队列和模型调用压力变大后，再评估拆分。

## D-008：生产密钥不直接明文展示

状态：建议采纳

决策：模型 API Key、飞书密钥、短信密钥等敏感信息不应在前端明文展示，也不应进入日志。

建议实现：

- 开发阶段可以用 `.env`。
- 生产阶段优先使用环境变量引用或加密存储。
- 后台模型配置页展示脱敏后的 Key。
# 补充决策：不使用向量数据库

当前知识库检索采用“开放知识库范围约束 + 飞书搜索/节点直读 + 关键词片段排序”，不引入 embedding 或向量数据库。具体边界和重新评估条件见 `2026-07-10-production-readiness-phase2.md`。
