kris/datai

Kris b7163d555b feat: 实现动态数据源延迟加载功能 (2026-01-21-001)

## 功能概述
- 实现动态数据源的延迟加载机制，支持应用启动时只加载主库，从库按需动态加载和切换
- 从库配置存储在主库中，支持运行时灵活切换从库库名
- 使用现有的 @DataSource 注解进行数据源切换，业务代码无需修改

## 新增功能
- 动态数据源管理接口 IDynamicDataSourceManager
- 动态数据源服务接口 IDynamicDataSourceService
- 动态数据源服务实现 DynamicDataSourceServiceImpl
- 数据源管理控制器 DatasourceController
- 数据源配置表 sys_datasource_config

## 新增文档
- 需求文档: docs/requirements/2026-01-21-001-动态数据源延迟加载.md
- 设计文档: docs/design/2026-01-21-001-动态数据源延迟加载设计.md
- 决策记录: docs/decisions/2026-01-21-001-ADR-动态数据源延迟加载.md
- SQL 脚本: docs/sql/2026-01-21-001-sys_datasource_config.sql
- 提示词: docs/prompts/2026-01-21-001-动态数据源延迟加载代码生成提示词.md
- 会话记录: docs/sessions/2026-01-21-001-session.md
- 变更日志: docs/changelog/2026-01-21-001-changelog.md
- 复盘文档: docs/retros/2026-01-21-001-retro.md
- API 文档: docs/api-docs/2026-01-21-001-api.md
- 根目录变更日志: CHANGELOG.md

## 修改功能
- 扩展 DataSourceManager 类，添加动态数据源管理方法
- 扩展 SysDatasourceConfigMapper 接口，添加 selectSysDatasourceConfigByDsName 方法
- 更新项目索引和 Authentication.canvas

## 修复问题
- 修复循环依赖问题：创建 IDynamicDataSourceManager 接口解决 datai-system 和 datai-framework 互相依赖
- 修复导入错误：删除 DynamicDataSourceServiceImpl 中未使用的导入
- 修复异常处理：将 setFilters() 调用移到 try-catch 块内

## API 接口
- POST /system/datasource/loadSlave - 加载从库数据源
- POST /system/datasource/switchSlave/{dbName} - 切换从库库名
- GET /system/datasource/getSlaveConfig - 获取从库配置
- POST /system/datasource/switch/{dsName} - 切换数据源
- DELETE /system/datasource/{dsName} - 移除数据源

2026-01-21 18:24:24 +08:00

17 KiB

Raw Permalink Blame History

阶段 3：方案决策技能书

A. 元数据 (Metadata)

name: phase3-decision

description: 在 Datai 项目中，基于已创建的设计文档，分析至少两种技术方案，进行架构决策，生成标准化的决策记录（ADR），并更新索引和会话记录。此技能确保技术决策的可追溯性和合理性。

B. 触发与定位 (Triggers & Scope)

触发关键词

当用户输入包含以下关键词时，必须觉醒此技能：

"架构决策"、"ADR"、"决策记录"
"技术方案对比"、"方案分析"
"进入阶段 3"、"下一阶段"
"决策"、"选择方案"、"方案评估"

触发场景

用户确认阶段 2 完成，要求进入阶段 3
用户要求创建决策记录（ADR）
用户询问如何进行技术方案决策
用户提到"按照项目规则"或"SSOT 流程"进行决策

操作路径

此技能涉及以下文件和目录的操作：

读取: docs/design/YYYY-MM-DD-00X-设计名.md (阶段 2 创建的设计文档)
创建: docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md
更新: docs/index.md
更新: docs/design/YYYY-MM-DD-00X-设计名.md (添加决策记录引用)
更新: docs/sessions/YYYY-MM-DD-00X-session.md
读取: .trae/rules/project_rules.md (项目规则)
读取: docs/Prompt/0004-单一真源文档驱动架构师.md (SSOT 架构师提示词)

SSOT 依赖

必须参考以下"唯一真源"：

设计文档 - 阶段 2 创建的设计文档
project_rules.md - 项目规则和阶段定义
0004-单一真源文档驱动架构师.md - SSOT 架构师提示词
docs/decisions/ 目录下的现有决策记录（作为格式参考）
docs/decisions/adr/0000-template.md (ADR 模板)

C. 核心指令集 (Instructions)

架构约束

1. 文档命名规范（强制）

必须使用格式：YYYY-MM-DD-00X-ADR-决策名.md
YYYY-MM-DD：当前日期（如 2026-01-21）
00X：需求编号（与阶段 1、2 保持一致）
决策名：简洁描述，使用中文，如"用户登录功能-技术选型"
严禁使用英文、拼音或无意义的文件名

2. 文档结构约束（强制）

决策记录必须包含以下章节，顺序不能改变：

# ADR-001: 决策标题

## 状态
已接受/已废弃/已替代

## 日期
YYYY-MM-DD

## 背景
[决策背景]

## 决策
[决策内容]

## 后果
### 正面影响
- [正面影响1]
- [正面影响2]

### 负面影响
- [负面影响1]
- [负面影响2]

## 替代方案
- [替代方案1]
- [替代方案2]

## 相关文档
- [需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
- [设计文档](../design/YYYY-MM-DD-00X-设计名.md)

3. 决策约束（强制）

必须分析至少两种技术方案的优缺点
必须有明确的决策理由
必须考虑与已有 ADR 记录的冲突
必须记录决策的正面影响和负面影响
必须记录替代方案

4. 强制校验（强制）

必须检查方案是否冲突于已有的 ADR 记录
必须使用 SearchCodebase 工具搜索已有的 ADR 记录
如果发现冲突，必须重新评估方案或更新已有 ADR 记录

5. 索引更新约束（强制）

必须在创建决策记录后立即更新 docs/index.md
必须更新设计文档，添加决策记录引用
采用增量更新策略，严禁删除现有内容
索引链接格式：[文档名](./相对路径/文件名.md)
必须在 docs/index.md 中添加到"决策记录"部分

6. 会话记录约束（强制）

必须更新 docs/sessions/YYYY-MM-DD-00X-session.md
必须更新当前阶段为"阶段 3：方案决策"
必须记录关键决策内容
必须记录决策记录链接

业务逻辑 SOP（标准操作流程）

步骤 1：决策分析（Let's think step by step）

在创建决策记录前，必须执行以下分析：

识别关键决策点
- 读取阶段 2 创建的设计文档
- 识别设计文档中的技术选型、架构设计、集成方案等关键决策点
- 确定需要进行 ADR 记录的决策点
分析至少两种技术方案的优缺点
- 方案 1：
  - 技术选型
  - 优点
  - 缺点
  - 适用场景
- 方案 2：
  - 技术选型
  - 优点
  - 缺点
  - 适用场景
- （可选）方案 3：
  - 技术选型
  - 优点
  - 缺点
  - 适用场景
确定最终决策和理由
- 基于方案优缺点对比，确定最终选择的方案
- 说明选择该方案的理由
- 说明放弃其他方案的理由
- 考虑方案的可行性、成本、风险、可维护性等因素

步骤 2：强制校验

搜索已有 ADR 记录
- 使用 SearchCodebase 工具搜索 docs/decisions/ 目录下的所有 ADR 记录
- 检查是否有与当前决策冲突的记录
- 如果发现冲突，重新评估方案或更新已有 ADR 记录
确认决策的一致性
- 确认决策与项目规则一致
- 确认决策与 SSOT 架构师提示词一致
- 确认决策与需求文档一致

步骤 3：创建决策记录

确定文档路径
- 路径：docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md
- 使用 Write 工具创建文件
- 确保目录存在（使用 LS 工具检查）
填充文档内容
- 标题：ADR-00X: 决策标题
- 状态：已接受/已废弃/已替代
- 日期：当前日期
- 背景：决策的背景和上下文
- 决策：最终选择的方案和理由
- 后果：
  - 正面影响
  - 负面影响
- 替代方案：列出所有考虑过的方案
- 相关文档：添加需求文档和设计文档链接
文档质量检查
- 使用 Read 工具读取刚创建的文档
- 检查是否符合文档结构约束
- 检查是否有遗漏的章节
- 检查决策理由是否充分

步骤 4：更新索引和设计文档

读取现有索引
- 使用 Read 工具读取 docs/index.md
- 找到"决策记录"部分
- 如果不存在，则创建该部分
添加新决策链接
- 在"决策记录"部分追加新决策
- 格式：- [决策名](./decisions/YYYY-MM-DD-00X-ADR-决策名.md) - [状态]
- 示例：- [用户登录功能-技术选型](./decisions/2026-01-21-001-ADR-用户登录功能-技术选型.md) - 已接受
更新设计文档
- 使用 Read 工具读取设计文档
- 在"相关文档"部分添加决策记录链接
- 格式：- [决策记录](../decisions/YYYY-MM-DD-00X-ADR-决策名.md)
- 使用 Write 工具更新设计文档
保存索引
- 使用 Write 工具更新 docs/index.md
- 严禁删除现有内容，只追加新内容

步骤 5：更新会话记录

读取现有会话记录
- 使用 Read 工具读取 docs/sessions/YYYY-MM-DD-00X-session.md
更新阶段 3 信息
- 更新"当前阶段"为"阶段 3：方案决策"
- 更新"阶段 3：方案决策"的状态为"已完成"
- 添加生成文档链接
- 添加关键决策内容
保存会话记录
- 使用 Write 工具更新会话记录

步骤 6：确认与询问

向用户确认
- 显示决策记录的链接
- 询问："决策是否合理？"
- 询问："是否进入下一阶段（数据库结构生成）？"
等待用户反馈
- 如果用户不满意，询问具体需要修改的地方
- 如果用户要求回退，执行回退机制（见错误陷阱部分）
- 如果用户确认，标记阶段 3 为已完成，准备进入阶段 4

工具调用

必须使用的工具

Read 工具：读取现有文件
- 使用场景：读取设计文档、读取索引、读取会话记录、读取已有 ADR 记录
- 命令：Read(file_path="d:\\idea_demo\\datai\\docs\\design\\2026-01-21-001-用户登录功能-设计.md")
Write 工具：创建或更新文件
- 使用场景：创建决策记录、更新索引、更新设计文档、更新会话记录
- 命令：Write(file_path="d:\\idea_demo\\datai\\docs\\decisions\\2026-01-21-001-ADR-用户登录功能-技术选型.md", content="...")
LS 工具：检查目录是否存在
- 使用场景：创建文档前检查 docs/decisions/ 目录
- 命令：LS(path="d:\\idea_demo\\datai\\docs")
SearchCodebase 工具：搜索已有 ADR 记录
- 使用场景：检查方案是否冲突于已有的 ADR 记录
- 命令：SearchCodebase(information_request="查找 docs/decisions 目录下的所有 ADR 记录")

可选使用的工具

Glob 工具：查找文件
- 使用场景：查找所有决策记录
- 命令：Glob(pattern="docs/decisions/*.md")
TodoWrite 工具：管理任务
- 使用场景：跟踪阶段执行进度
- 命令：TodoWrite(todos=[...])

D. 错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误（Anti-Patterns）

错误 1：不分析多种方案直接决策

错误示例：

用户：进入阶段 3
AI：直接创建决策记录，只分析一种方案

正确示例：

用户：进入阶段 3
AI：让我先分析至少两种技术方案...
AI：方案 1：使用 Spring Security + JWT
AI：方案 2：使用 Shiro + Redis
AI：分析两种方案的优缺点...
AI：基于分析，选择方案 1...

错误 2：决策理由不充分

错误示例：

## 决策
选择方案 1，因为它更好。

问题：

决策理由过于简单
没有说明为什么选择方案 1
没有说明放弃其他方案的理由

正确示例：

## 决策
选择方案 1（Spring Security + JWT），理由如下：
1. 与项目现有技术栈（Spring Boot）集成更好
2. 社区活跃度高，文档丰富
3. 安全性更高，支持更多认证方式
4. 已在公司其他项目中广泛使用，开发人员熟悉

放弃方案 2（Shiro + Redis）的理由：
1. 与 Spring Boot 集成不如 Spring Security 紧密
2. 社区活跃度相对较低
3. 安全性功能不如 Spring Security 全面

错误 3：不检查已有 ADR 记录

错误示例：

AI：创建决策记录，不检查已有 ADR 记录
AI：发现决策与已有 ADR 记录冲突

正确示例：

AI：使用 SearchCodebase 工具搜索已有 ADR 记录
AI：检查是否有与当前决策冲突的记录
AI：如果没有冲突，继续创建决策记录
AI：如果有冲突，重新评估方案或更新已有 ADR 记录

错误 4：不更新设计文档的决策记录引用

错误示例：

AI：创建决策记录
AI：更新 docs/index.md
AI：完成（忘记更新设计文档）

正确示例：

AI：创建决策记录
AI：更新 docs/index.md
AI：更新设计文档，添加决策记录引用
AI：完成

错误 5：不询问用户确认就进入下一阶段

错误示例：

AI：创建决策记录
AI：进入阶段 4：数据库结构生成（未询问用户）

正确示例：

AI：创建决策记录
AI：决策记录已创建：[链接]
AI：决策是否合理？
AI：是否进入下一阶段（数据库结构生成）？

验收清单（Checklist）

在完成阶段 3 前，必须检查以下项目：

文档完整性检查

决策记录已创建在 docs/decisions/ 目录下
文档命名符合 YYYY-MM-DD-00X-ADR-决策名.md 格式
文档包含所有必需章节（标题、状态、日期、背景、决策、后果、替代方案、相关文档）
状态已正确填写（已接受/已废弃/已替代）
日期已正确填写
背景清晰、无歧义
决策理由充分
后果包含正面影响和负面影响
替代方案至少包含两种
相关文档链接正确

决策合理性检查

分析了至少两种技术方案
每种方案都有明确的优缺点
决策理由充分且合理
考虑了方案的可行性、成本、风险、可维护性等因素

强制校验检查

使用 SearchCodebase 工具搜索了已有 ADR 记录
检查了方案是否冲突于已有的 ADR 记录
如果有冲突，已解决冲突

索引更新检查

docs/index.md 已更新
新决策链接已添加到"决策记录"部分
索引链接格式正确：[文档名](./相对路径/文件名.md)
索引更新采用增量策略，未删除现有内容

设计文档更新检查

设计文档已更新
设计文档的"相关文档"部分已添加决策记录引用
决策记录链接格式正确：[决策记录](../decisions/YYYY-MM-DD-00X-ADR-决策名.md)

会话记录更新检查

会话记录已更新
会话记录的"当前阶段"已更新为"阶段 3：方案决策"
会话记录的"阶段 3：方案决策"状态已更新为"已完成"
会话记录包含决策记录链接
会话记录包含关键决策内容

用户确认检查

已向用户显示决策记录链接
已询问用户"决策是否合理？"
已询问用户"是否进入下一阶段？"
已等待用户反馈

回退机制检查（如果需要）

如果用户不满意，已询问具体需要修改的地方
如果用户要求回退，已删除相关文档
如果用户要求回退，已撤销索引更新
如果用户要求回退，已撤销设计文档更新
如果用户要求回退，已更新会话记录

Correct vs Incorrect 代码对比

Incorrect（错误示例）

# ADR-001: 用户登录功能技术选型

## 状态
已接受

## 日期
2026-01-21

## 背景
用户登录功能需要选择认证方案。

## 决策
选择 Spring Security + JWT。

## 后果
### 正面影响
- 好

### 负面影响
- 不好

## 替代方案
- 其他方案

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)

Correct（正确示例）

# ADR-001: 用户登录功能技术选型

## 状态
已接受

## 日期
2026-01-21

## 背景
用户登录功能需要选择一个可靠的认证方案，满足以下要求：
1. 与 Spring Boot 集成良好
2. 支持 JWT Token 认证
3. 支持密码加密
4. 支持权限控制
5. 社区活跃度高，文档丰富

## 决策
选择方案 1：Spring Security + JWT，理由如下：
1. 与项目现有技术栈（Spring Boot）集成更好
2. 社区活跃度高，文档丰富
3. 安全性更高，支持更多认证方式（OAuth2、OpenID Connect 等）
4. 已在公司其他项目中广泛使用，开发人员熟悉
5. 支持密码加密（BCrypt）和权限控制

## 后果
### 正面影响
1. 开发效率高，与现有技术栈集成良好
2. 安全性高，支持多种认证方式
3. 维护成本低，社区活跃度高
4. 开发人员熟悉，学习成本低

### 负面影响
1. 配置相对复杂
2. 入门门槛较高

## 替代方案

### 方案 2：Shiro + Redis
- **优点**：配置简单，入门门槛低
- **缺点**：与 Spring Boot 集成不如 Spring Security 紧密，安全性功能不如 Spring Security 全面
- **适用场景**：小型项目，对安全性要求不高的项目

### 方案 3：自定义认证方案
- **优点**：完全定制化，符合项目特定需求
- **缺点**：开发成本高，安全性难以保证，维护成本高
- **适用场景**：对认证方案有特殊要求的项目

## 相关文档
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)

附录：快速参考

文件路径速查

设计文档：docs/design/YYYY-MM-DD-00X-设计名.md
决策记录：docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md
主索引：docs/index.md
会话记录：docs/sessions/YYYY-MM-DD-00X-session.md
项目规则：.trae/rules/project_rules.md
SSOT 架构师提示词：docs/Prompt/0004-单一真源文档驱动架构师.md

工具命令速查

# 读取设计文档
Read(file_path="d:\\idea_demo\\datai\\docs\\design\\2026-01-21-001-用户登录功能-设计.md")

# 创建决策记录
Write(file_path="d:\\idea_demo\\datai\\docs\\decisions\\2026-01-21-001-ADR-用户登录功能-技术选型.md", content="...")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

# 搜索已有 ADR 记录
SearchCodebase(information_request="查找 docs/decisions 目录下的所有 ADR 记录")

# 查找所有决策记录
Glob(pattern="docs/decisions/*.md")

阶段 3 输出清单

决策记录：docs/decisions/YYYY-MM-DD-00X-ADR-决策名.md
更新的索引：docs/index.md
更新的设计文档：docs/design/YYYY-MM-DD-00X-设计名.md
更新的会话记录：docs/sessions/YYYY-MM-DD-00X-session.md

下一阶段提示

如果用户确认进入下一阶段，请参考：

project_rules.md 的"阶段 4：数据库结构生成"
准备分析需求是否涉及数据库变更
准备生成 SQL 脚本
准备更新索引和会话记录

17 KiB Raw Permalink Blame History Unescape Escape

阶段 3：方案决策技能书

A. 元数据 (Metadata)

B. 触发与定位 (Triggers & Scope)

触发关键词

触发场景

操作路径

SSOT 依赖

C. 核心指令集 (Instructions)

架构约束

1. 文档命名规范（强制）

2. 文档结构约束（强制）

3. 决策约束（强制）

4. 强制校验（强制）

5. 索引更新约束（强制）

6. 会话记录约束（强制）

业务逻辑 SOP（标准操作流程）

步骤 1：决策分析（Let's think step by step）

步骤 2：强制校验

步骤 3：创建决策记录

步骤 4：更新索引和设计文档

步骤 5：更新会话记录

步骤 6：确认与询问

工具调用

必须使用的工具

可选使用的工具

D. 错误陷阱与验证 (Anti-Patterns & Checklist)

常见错误（Anti-Patterns）

错误 1：不分析多种方案直接决策

错误 2：决策理由不充分

错误 3：不检查已有 ADR 记录

错误 4：不更新设计文档的决策记录引用

错误 5：不询问用户确认就进入下一阶段

验收清单（Checklist）

文档完整性检查

决策合理性检查

强制校验检查

索引更新检查

设计文档更新检查

会话记录更新检查

用户确认检查

回退机制检查（如果需要）

Correct vs Incorrect 代码对比

Incorrect（错误示例）

Correct（正确示例）

附录：快速参考

文件路径速查

工具命令速查

阶段 3 输出清单

下一阶段提示

17 KiB

Raw Permalink Blame History