## 2026-07-23

| # | 内容 | 理由 |
|---|------|------|
| 1 | **技术栈版本不锁定具体小版本号**。设计文档中的 Vite 8.1.2、Ant Design 6.5.0 等细化版本在 2026.7 可能不存在或不是最新，建项目时用大版本范围（如 Vite ^7.0.0）取当时最新稳定版即可 | 避免因等待特定版本号导致开发阻塞 |
| 2 | **Ollama 70B 模型需评估硬件条件**。llama3.1:70b 需要至少 48GB VRAM，如公司只有单卡 24GB 显卡需准备降级方案，同时考虑 qwen2.5:32b 或 llama3.1:8b 作为备选 | 70B 模型对 GPU 要求过高，实际硬件可能无法支撑实时推理 |
| 3 | **Spring AI 成熟度风险**。Spring AI 是较新项目（2024 年出 1.0），API 可能变化，需在代码中预留适配层抽象 | 避免 Spring AI 版本升级导致阻塞开发 |
| 4 | **Ollama / DeepSeek 双引擎输出一致性**。ChatML 格式与 DeepSeek 原生格式的 Prompt 渲染结果可能质量不一致，需两层适配：格式适配 + 必要时对两个模型分别调参 | 保证跨模型输出行为稳定可控 |
| 5 | **pgvector 1536 维 IVFFlat 索引在大数据集下召回率下降**。初期数据量小无问题，后期数据量大（>100万条）可考虑升级 pgvectorscale 或换专门向量库 | 确保向量检索长期性能 |
| 6 | **项目结构改为 backend/ + frontend/ 分离**。前后端构建方式不同（Maven vs npm），部署环境不同（JRE vs Nginx），平级放在同一 Git 仓库但各自独立 | 避免构建工具链相互干扰，部署时可独立扩缩容 |
| 7 | **AuthController 真实实现放在 ims-web 模块，其余 Controller 在 ims-api 为存根**。ims-api 只依赖 ims-common，不依赖 ims-service，无法访问 UserRepository、PasswordEncoder | 避免模块间循环依赖，同时保持架构分层清晰 |
| 8 | **JwtUtil 移除 @Component/@Value 注解，改为普通构造函数 + @Configuration 工厂方法**。ims-common 不应依赖 Spring Context，保持轻量 | 使 ims-common 成为纯 POJO 模块，不依赖 Spring 框架 |