# V2 开发决策登记表

日期：2026-07-06

## 目的

这份文档专门记录 V2 开发过程中的关键决策，包括用户明确拍板的决策、我在开发中默认采用的工程决策、以及仍需确认的决策。

后续如果决策发生变化，不直接覆盖历史结论，应新增记录说明变更原因、影响范围和执行动作。

## 用户明确决策

| 编号 | 决策 | 状态 | 影响 |
| --- | --- | --- | --- |
| U-001 | 给用户、团队、交接和评审看的项目文档必须使用中文。 | 已确认 | 评估报告、开发计划、决策记录、验收记录等都用中文；机器抽取或开发检索用中间文档可保留源语言。 |
| U-002 | 用户端直接使用 Vue 3，不使用 uni-app。 | 已确认 | V2 用户端按 Vue 3 H5 开发；后续小程序转换单独评估，不作为一期技术栈前置约束。 |
| U-003 | V2 新需求不要继续混在旧项目文档里，要建立新目录和新开发记录。 | 已确认 | V2 文档和后续代码集中放在 `ai_knowledge_base_v2/` 下。 |
| U-004 | 每次代码改动和内容改动都要提交并推送到 Git。 | 已确认 | 文档、代码、配置变更都必须 commit + push。 |
| U-005 | 修改需求时必须先修改相关文档，再修改代码。 | 已确认 | 后续需求变更需要先落中文开发记录和范围/接口/决策文档，再进入实现。 |
| U-006 | 用户端登录改为学员名单准入。 | 已确认 | 不再自动创建普通用户；后台手动添加或批量导入的手机号才可以登录。 |

## 当前默认工程决策

| 编号 | 决策 | 状态 | 说明 |
| --- | --- | --- | --- |
| D-001 | V2 暂时继续在当前仓库推进，目录为 `ai_knowledge_base_v2/`。 | 默认采用 | 避免拆仓库导致前期沟通和推送成本增加；后续可迁移。 |
| D-002 | V2 后端使用 FastAPI + SQLAlchemy + Alembic。 | 默认采用 | 复用旧项目工程经验，同时保留清晰迁移能力。 |
| D-003 | V2 数据库按文档使用 MySQL 8.x。 | 默认采用 | 数据库设计文档明确指定 MySQL 8.x。 |
| D-004 | 用户端使用 Vue 3 + Vite + TypeScript。 | 默认采用 | 对齐用户“直接用 Vue 3”的要求。 |
| D-005 | 管理后台优先使用 Vue 3 + Vite + Element Plus。 | 默认采用 | 与用户端 Vue 体系一致，后台表格/表单效率高。 |
| D-006 | 短信、飞书、大模型都先做 mock provider，再接真实服务。 | 默认采用 | 保证本地开发和测试不被外部账号、权限、费用阻塞。 |
| D-007 | RAG 一期作为后端内部 service，不单独拆微服务。 | 默认采用 | 降低一期部署和调试复杂度。 |
| D-008 | 生产密钥不明文展示，不写入日志。 | 默认采用 | 降低模型 Key、飞书密钥、短信密钥泄露风险。 |
| D-009 | 用户端 Markdown 渲染使用 `markdown-it`，不手写 Markdown 解析器。 | 默认采用 | 减少列表、代码块、表格等格式兼容问题，降低后续维护成本。 |
| D-010 | 用户端停止生成先使用浏览器 `AbortController` 中断 SSE 读取，后端真实中断等接入真实模型时实现。 | 默认采用 | 当前后端仍是 mock 模型，前端先保证用户操作反馈真实有效。 |
| D-011 | 阶段四外部服务默认保持 mock 开启，通过配置关闭 mock 后再走真实 provider。 | 默认采用 | 当前缺少真实飞书检索地址和模型凭证，默认 mock 可以保证开发、演示和测试连续。 |
| D-012 | 大模型真实调用先按 OpenAI 兼容 `chat/completions` 非流式响应接入。 | 默认采用 | 先打通配置化真实模型调用和失败日志，后续再升级为模型原生流式透传。 |
| D-013 | 管理后台开发阶段支持首次登录自动创建默认管理员。 | 默认采用 | 降低本地初始化成本；生产环境必须修改默认账号密码。 |
| D-014 | 管理后台 Element Plus 先整体引入，后续再做按需导入优化。 | 已调整 | 阶段五优先保证后台功能闭环和交付速度；已在 D-019 调整为按需注册。 |
| D-015 | 模型管理按“快速厂商 + 协议通用配置”补全。 | 已调整 | DeepSeek 和 MiniMax 提供快速添加；其他供应商按 OpenAI 兼容协议或 Anthropic Messages 协议添加。 |
| D-016 | 模型配置支持 `baseUrl` 自动拼接接口，同时保留 `apiUrl` 覆盖能力。 | 默认采用 | 降低普通配置成本，同时给特殊代理网关、私有化模型和供应商非标准路径保留出口。 |
| D-017 | 编辑模型时 API Key 留空表示保留旧密钥。 | 默认采用 | 减少密钥重复暴露，避免后台人员只改参数时误覆盖密钥。 |
| D-018 | 模型高级参数用 JSON 对象透传。 | 默认采用 | 用较低成本兼容供应商差异，避免数据库字段无限膨胀。 |
| D-019 | 管理后台 Element Plus 改为按需注册，并拆分表格和基础 vendor chunk。 | 默认采用 | 解决后台构建单 chunk 过大的提示，降低首屏主入口体积，同时不引入额外构建插件。 |
| D-020 | MiniMax 快速添加默认使用 Anthropic Messages 兼容协议。 | 默认采用 | MiniMax 文本生成指南推荐 Anthropic-compatible 路径；后端按 `auth_type` 兼容 Bearer 和 x-api-key 两种鉴权。 |
| D-021 | 模型管理只负责 LLM 接入，Agent 管理负责提示词、知识库、模型选择和推理参数调试。 | 默认采用 | 避免模型连接配置与 Agent 运行策略混在一起，方便后续做 Agent 版本、调试和发布流程。 |
| D-022 | 用户-知识库授权先放在用户管理中维护。 | 已废弃 | 2026-07-07 需求调整后，一期不再按人分配知识库，已开放知识库默认所有用户可见。 |
| D-023 | Agent 调试预览采用接近用户端聊天页的交互形态。 | 默认采用 | 测试问题从配置区移到预览窗口底部，减少调试和真实用户问答体验之间的差异。 |
| D-024 | 知识库访问范围改为“开放即全员可见”。 | 用户确认 | 知识库不再精确到用户授权；用户端问答只使用已开放、未禁用知识库，用户管理不再承担知识库授权职责。 |
| D-025 | 学员批量导入一期先支持 CSV 文本粘贴。 | 已废弃 | 2026-07-07 需求调整为 Excel 模板导入，CSV 文本粘贴不再作为正式后台入口。 |
| D-026 | 学员批量导入正式入口改为 Excel 模板上传。 | 用户确认 | 后台提供模板下载和 Excel 上传导入；导入结果展示新增、更新、失败及失败原因。 |
| D-027 | Agent 调试预览采用接近 DeepSeek 等聊天产品的显示方式。 | 用户确认 | 预览窗口以真实聊天体验为目标，支持连续对话、底部输入和生成中状态。 |
| D-028 | 系统配置页面从占位 Key/Value 调整为中文分组配置表单。 | 用户确认 | 配置保存到 `sys_system_config`，默认每日额度接入学员新增和导入逻辑；其他配置作为后续运行时读取的统一入口。 |
| D-029 | 系统配置页不保留高级配置入口。 | 用户确认 | 所有允许后台配置的项目必须显式列在配置页中，不允许管理员通过自由 Key/Value 临时增加配置项。 |
| D-030 | 知识库检索不再使用 mock。 | 用户确认 | Agent 查找知识库内容时，要么调用真实搜索接口，要么飞书直读。 |
| D-031 | 搜索接口必须限定在已开放知识库节点范围内。 | 用户确认 | 后端调用搜索接口时传入已开放知识库的 `spaceId/nodeId`，禁止搜索服务全局检索。 |

## 待确认决策

| 编号 | 问题 | 当前默认 | 需要确认的时间点 |
| --- | --- | --- | --- |
| Q-001 | 管理后台是否最终采用 Vue 3 + Element Plus？ | 默认采用 | 开始后台工程前。 |
| Q-002 | 真实短信供应商是谁？ | 先 mock | 接入真实登录前。 |
| Q-003 | 大模型供应商、API URL、模型名和鉴权方式是什么？ | 后台模型管理已支持多供应商配置，真实生产供应商仍待确认。 | 接入真实模型前。 |
| Q-004 | 飞书知识库实时检索 API 是否满足 SpaceID/NodeID 检索要求？ | 先做 mock + 技术验证 | 阶段二后端基础工程完成后尽快验证。 |
| Q-005 | 模型 API Key 生产环境如何保存？ | 优先环境变量引用或加密存储 | 做模型管理功能前。 |
| Q-006 | 飞书检索是否直接调飞书原生 API，还是先由独立适配服务封装？ | 当前先预留 `FEISHU_SEARCH_URL` 适配服务入口 | 飞书账号、权限和 API 返回结构确认后。 |

## 当前可进入阶段二的判断

可以进入阶段二。

理由：

1. 一期范围已经锁定。
2. 用户端技术栈已经明确为 Vue 3 H5。
3. 后端、数据库、模块边界和接口优先级已有阶段一文档支撑。
4. 阶段二可以先从后端基础工程、数据模型和 mock 登录开始，不依赖真实短信、飞书或大模型。
