diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md b/ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md index df242a3..b3e0f3c 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md +++ b/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/小程序都能承载的方式设计，避免依赖纯 Web 特性。 +- 当前一期目标是先把 H5 用户端功能做扎实。 +- 用户明确要求用户端直接使用 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 主链路开始，不先做完整后台。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md b/ai_knowledge_base_v2/development_records/2026-07-06-decision-register.md new file mode 100644 index 0000000..af79b4c --- /dev/null +++ b/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 登录开始，不依赖真实短信、飞书或大模型。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md b/ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md index e6b5a6b..5c72c1b 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md +++ b/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. 后台管理端优先保证功能完整和可维护，不追求复杂视觉效果。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md b/ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md index 74a13bb..9a5814f 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md +++ b/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。 -4. 后台是否采用 Vue 3 + Element Plus。 -5. 飞书知识库实时检索 API 是否能满足需求，需要做技术验证。 -6. 生产短信和大模型供应商待定，当前先按 mock + OpenAI 兼容接口推进。 +3. 后台是否采用 Vue 3 + Element Plus。 +4. 飞书知识库实时检索 API 是否能满足需求，需要做技术验证。 +5. 生产短信和大模型供应商待定，当前先按 mock + OpenAI 兼容接口推进。 ## 建议下一步 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md b/ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md index ddf5c5b..45a2d3a 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md +++ b/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。 原因： -- 主要使用场景是手机端。 -- 用户之前提出后续可能封装成微信小程序。 -- uni-app 更适合 H5 与小程序双端路线。 +- 用户明确拍板：用户端直接用 Vue 3，不用 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 技术体系更一致。 备选： diff --git a/ai_knowledge_base_v2/development_records/README.md b/ai_knowledge_base_v2/development_records/README.md index a0fb03c..1e93f1e 100644 --- a/ai_knowledge_base_v2/development_records/README.md +++ b/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` | 开发决策登记表，集中记录用户明确决策和默认工程决策。 |