Record Vue 3 client decision

ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md

@@ -23,7 +23,7 @@ ai_knowledge_base_v2/
   reports/                   # 评估和调研报告
   apps/
     backend/                 # V2 后端服务
-    user-client/             # 用户端 H5，后续可按小程序方向演进
+    user-client/             # 用户端 H5
     admin-web/               # 管理后台
   packages/
     shared-types/            # 前后端共享类型，可后续再建
@@ -50,25 +50,26 @@ ai_knowledge_base_v2/
 
 ### 用户端
 
-建议：优先评估 `uni-app + Vue 3` 作为用户端技术路线。
+已确认：用户端直接使用 `Vue 3 + Vite + TypeScript` 开发 H5。
 
 原因：
 
 - 用户端主要场景是手机端。
-- 后续可能转微信小程序，uni-app 比 Next.js H5 更适合这一目标。
+- 当前一期目标是先把 H5 用户端功能做扎实。
-- 交互和接口要按 H5/小程序都能承载的方式设计，避免依赖纯 Web 特性。
+- 用户明确要求用户端直接使用 Vue 3，不采用 uni-app。
+- Vue 3 + Vite 足够支撑 H5 主链路，工程结构清晰，团队后续维护成本低。
 
-阶段一先记录为“建议”，代码开工前需要最终确认。若为了复用旧 H5 代码选择 Next.js，也必须接受后续小程序迁移成本更高这一代价。
+说明：后续如果要转微信小程序，可以再评估独立小程序工程或迁移方案，但这不作为一期技术栈前置条件。
 
 ### 管理后台
 
-建议：`Vue 3 + Vite + Element Plus` 或沿用当前 Next.js 后台经验二选一。
+建议：`Vue 3 + Vite + Element Plus`。
 
 优先建议 Vue 3 的原因：
 
 - 后台是典型表单、表格、筛选、弹窗、权限菜单场景。
 - Element Plus 生态适合快速搭后台。
-- 与用户端 uni-app/Vue 体系更接近，团队后续维护成本更低。
+- 与用户端 Vue 3 技术体系一致，团队后续维护成本更低。
 
 ### AI/RAG
 
@@ -138,7 +139,7 @@ ai_knowledge_base_v2/
 | 风险 | 控制措施 |
 | --- | --- |
 | 飞书实时检索 API 能力不确定 | 阶段二开始前做技术验证脚本，确认 SpaceID/NodeID、权限和返回结构。 |
-| H5 后续转小程序成本高 | 用户端优先采用适合小程序路线的技术栈，交互不依赖复杂 Web API。 |
+| H5 后续转小程序成本高 | 一期先按 Vue 3 H5 做稳定主链路；后续小程序单独评估迁移或新建工程。 |
 | 权限后补导致越权 | RAG 链路第一步就是权限过滤，接口测试必须覆盖越权场景。 |
 | 模型回答编造 | 无命中固定兜底，Prompt 明确限制，日志记录检索片段和 Prompt。 |
 | API Key 明文风险 | 开发前明确密钥存储策略，生产不在日志中输出密钥。 |
@@ -148,5 +149,5 @@ ai_knowledge_base_v2/
 
 1. V2 先在当前仓库 `ai_knowledge_base_v2/` 下继续推进。
 2. 后端优先使用 FastAPI，数据库对齐文档使用 MySQL 8.x。
-3. 用户端优先评估 uni-app + Vue 3，管理后台优先评估 Vue 3 + Element Plus。
+3. 用户端已确认使用 Vue 3 + Vite + TypeScript，管理后台优先使用 Vue 3 + Element Plus。
 4. 第一条代码主线从后端基础工程和用户端 mock 主链路开始，不先做完整后台。

ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md

@@ -0,0 +1,52 @@
+# 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。 |
+
+## 当前默认工程决策
+
+| 编号 | 决策 | 状态 | 说明 |
+| --- | --- | --- | --- |
+| 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、飞书密钥、短信密钥泄露风险。 |
+
+## 待确认决策
+
+| 编号 | 问题 | 当前默认 | 需要确认的时间点 |
+| --- | --- | --- | --- |
+| Q-001 | 管理后台是否最终采用 Vue 3 + Element Plus？ | 默认采用 | 开始后台工程前。 |
+| Q-002 | 真实短信供应商是谁？ | 先 mock | 接入真实登录前。 |
+| Q-003 | 大模型供应商、API URL、模型名和鉴权方式是什么？ | 先按 OpenAI 兼容接口 | 接入真实模型前。 |
+| Q-004 | 飞书知识库实时检索 API 是否满足 SpaceID/NodeID 检索要求？ | 先做 mock + 技术验证 | 阶段二后端基础工程完成后尽快验证。 |
+| Q-005 | 模型 API Key 生产环境如何保存？ | 优先环境变量引用或加密存储 | 做模型管理功能前。 |
+
+## 当前可进入阶段二的判断
+
+可以进入阶段二。
+
+理由：
+
+1. 一期范围已经锁定。
+2. 用户端技术栈已经明确为 Vue 3 H5。
+3. 后端、数据库、模块边界和接口优先级已有阶段一文档支撑。
+4. 阶段二可以先从后端基础工程、数据模型和 mock 登录开始，不依赖真实短信、飞书或大模型。

ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md

@@ -12,11 +12,16 @@
 | --- | --- | --- | --- |
 | Q-001 | V2 是否长期放在当前仓库，还是后续拆独立仓库？ | 影响目录结构、CI/CD 和部署方式。 | 当前先在 `ai_knowledge_base_v2/` 下推进，后续如拆仓库再迁移。 |
 | Q-002 | 数据库是否严格使用 MySQL 8.x？ | 影响 ORM、迁移、Docker 和部署。 | 建议按文档使用 MySQL 8.x。 |
-| Q-003 | 用户端技术栈是否采用 uni-app + Vue 3？ | 影响 H5 和微信小程序迁移成本。 | 建议优先采用 uni-app；如选择 Next.js，需要接受后续小程序迁移成本。 |
 | Q-004 | 短信验证码供应商是谁？ | 影响登录真实接入、费用和安全策略。 | 开发阶段先 mock，生产前确认供应商。 |
 | Q-005 | 大模型供应商、API URL、模型名和鉴权方式是什么？ | 影响模型配置和流式输出兼容性。 | 先按 OpenAI 兼容接口设计，真实供应商确认后适配。 |
 | Q-006 | 飞书知识库实时检索 API 是否满足需求？ | 是 RAG 主链路最大外部风险。 | 阶段二前做技术验证脚本。 |
 
+## 已关闭问题
+
+| 编号 | 问题 | 结论 |
+| --- | --- | --- |
+| Q-003 | 用户端技术栈是否采用 uni-app + Vue 3？ | 已确认：不用 uni-app，用户端直接使用 Vue 3 H5。 |
+
 ## 需要产品确认
 
 | 编号 | 问题 | 影响 | 建议处理 |
@@ -42,5 +47,5 @@
 1. V2 暂时继续放在当前仓库的 `ai_knowledge_base_v2/` 下。
 2. 后端使用 FastAPI，数据库按文档使用 MySQL 8.x。
 3. 短信、飞书和大模型先做 mock provider。
-4. 用户端优先按手机端和小程序迁移友好的方式设计。
+4. 用户端直接使用 Vue 3 H5，手机端体验优先；后续小程序转换单独评估。
 5. 后台管理端优先保证功能完整和可维护，不追求复杂视觉效果。

ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md

@@ -27,7 +27,7 @@
 1. V2 先在当前仓库的 `ai_knowledge_base_v2/` 下独立推进。
 2. V2 后端建议使用 FastAPI + SQLAlchemy + Alembic。
 3. V2 数据库建议严格对齐文档，使用 MySQL 8.x。
-4. 用户端建议优先评估 uni-app + Vue 3，降低后续微信小程序迁移成本。
+4. 用户端已确认直接使用 Vue 3 H5，不采用 uni-app。
 5. 管理后台建议优先评估 Vue 3 + Element Plus。
 6. 短信、飞书、大模型先做 mock provider，再逐步替换真实服务。
 7. 开发顺序先跑通用户端主链路，再补后台完整管理能力。
@@ -38,10 +38,9 @@
 
 1. 是否接受 V2 继续放在当前仓库的 `ai_knowledge_base_v2/` 下。
 2. 是否确认 V2 使用 MySQL 8.x。
-3. 用户端是否采用 uni-app + Vue 3。
+3. 后台是否采用 Vue 3 + Element Plus。
-4. 后台是否采用 Vue 3 + Element Plus。
+4. 飞书知识库实时检索 API 是否能满足需求，需要做技术验证。
-5. 飞书知识库实时检索 API 是否能满足需求，需要做技术验证。
+5. 生产短信和大模型供应商待定，当前先按 mock + OpenAI 兼容接口推进。
-6. 生产短信和大模型供应商待定，当前先按 mock + OpenAI 兼容接口推进。
 
 ## 建议下一步
 

ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md

@@ -46,22 +46,22 @@
 - FastAPI 适合快速实现 REST、SSE 和 OpenAI 兼容模型调用。
 - SQLAlchemy 可以兼容 MySQL，Alembic 能提供可追踪迁移。
 
-## D-004：用户端优先评估 uni-app + Vue 3
+## D-004：用户端直接使用 Vue 3 H5
 
-状态：待确认
+状态：已确认
 
-决策：用户端建议优先使用 uni-app + Vue 3，而不是直接沿用旧 Next.js H5。
+决策：用户端直接使用 `Vue 3 + Vite + TypeScript` 开发 H5，不采用 uni-app。
 
 原因：
 
-- 主要使用场景是手机端。
+- 用户明确拍板：用户端直接用 Vue 3，不用 uni-app。
-- 用户之前提出后续可能封装成微信小程序。
+- 一期重点是把 H5 用户端功能能力做好。
-- uni-app 更适合 H5 与小程序双端路线。
+- Vue 3 + Vite 工程清晰，适合后续长期维护。
 
-代价：
+影响：
 
-- 旧 Next.js H5 代码只能复用交互经验，不能大面积复制。
+- 后续如果要做微信小程序，需要单独评估迁移方案或新建小程序工程。
-- 团队需要接受 Vue/uni-app 工程结构。
+- 旧 Next.js H5 代码主要复用交互经验，不作为 V2 用户端代码基础。
 
 ## D-005：管理后台优先评估 Vue 3 + Element Plus
 
@@ -73,7 +73,7 @@
 
 - 后台是典型表格、表单、筛选、弹窗和权限菜单场景。
 - Element Plus 可以快速搭建可维护后台。
-- 与用户端 Vue 体系更一致。
+- 与用户端 Vue 3 技术体系更一致。
 
 备选：
 

ai_knowledge_base_v2/development_records/README.md

@@ -24,3 +24,4 @@
 | `2026-07-06-api-priority.md` | 接口优先级规划。 |
 | `2026-07-06-open-questions.md` | 待确认问题清单。 |
 | `2026-07-06-tech-decisions.md` | 技术决策记录。 |
+| `2026-07-06-decision-register.md` | 开发决策登记表，集中记录用户明确决策和默认工程决策。 |