kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
8611d6b47f
datai/docs/skill/phase5-prompt-engineering.md
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

21 KiB
Raw Blame History

阶段 5：提示词生成技能书

A. 元数据 (Metadata)

name: phase5-prompt-engineering

description: 在 Datai 项目中，基于已创建的需求文档和设计文档，生成针对当前需求的提示词，引用真源，定义输出格式，并更新索引和会话记录。此技能确保 AI 生成的代码符合项目规范和需求。

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

触发关键词

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

  • "提示词"、"Prompt"、"提示词生成"
  • "工程化提示词"、"执行提示词"
  • "进入阶段 5"、"下一阶段"
  • "Prompt 设计"、"提示词设计"

触发场景

  • 用户确认阶段 4 完成，要求进入阶段 5
  • 用户要求生成提示词
  • 用户询问如何设计提示词
  • 用户提到"按照项目规则"或"SSOT 流程"进行提示词设计

操作路径

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

  • 读取: docs/requirements/YYYY-MM-DD-00X-需求名.md (阶段 1 创建的需求文档)
  • 读取: docs/design/YYYY-MM-DD-00X-设计名.md (阶段 2 创建的设计文档)
  • 创建: docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md
  • 更新: docs/index.md
  • 更新: docs/requirements/YYYY-MM-DD-00X-需求名.md (添加提示词引用)
  • 更新: docs/sessions/YYYY-MM-DD-00X-session.md
  • 读取: .trae/rules/project_rules.md (项目规则)
  • 读取: docs/Prompt/0004-单一真源文档驱动架构师.md (SSOT 架构师提示词)
  • 读取: docs/Prompt/0000-template.md (提示词模板)

SSOT 依赖

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

C. 核心指令集 (Instructions)

架构约束

1. 提示词命名规范（强制）

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

2. 提示词内容约束（强制）

提示词必须包含以下内容：

  • 引用真源（需求文档和设计文档的链接）
  • 需求描述
  • 设计方案
  • 输出格式要求
  • 代码规范要求
  • 测试要求

3. 引用真源约束（强制）

  • 提示词开头必须引用 docs/requirements/ 和 docs/design/ 的文件链接
  • 引用格式：[需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)
  • 引用格式：[设计文档](../design/YYYY-MM-DD-00X-设计名.md)

4. 输出格式约束（强制）

  • 必须定义输出格式，如：必须包含单元测试，必须符合某设计模式
  • 必须定义代码结构，如：Controller、Service、Mapper、Entity 分层
  • 必须定义命名规范，如：类名、方法名、变量名的命名规则
  • 必须定义注释规范，如：类注释、方法注释、字段注释

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

  • 必须在生成提示词后立即更新 docs/index.md
  • 必须更新需求文档，添加提示词引用
  • 采用增量更新策略，严禁删除现有内容
  • 索引链接格式：[文档名](./相对路径/文件名.md)
  • 必须在 docs/index.md 中添加到"提示词"部分

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

  • 必须更新 docs/sessions/YYYY-MM-DD-00X-session.md
  • 必须更新当前阶段为"阶段 5：提示词生成"
  • 必须记录提示词内容摘要
  • 必须记录提示词链接

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

步骤 1：提示词分析（Let's think step by step）

在生成提示词前，必须执行以下分析：

  1. 分析需求的核心任务

    • 读取阶段 1 创建的需求文档
    • 识别需求的核心功能和非功能需求
    • 确定需要生成的代码类型（Controller、Service、Mapper、Entity 等）

  2. 确定需要生成的提示词类型

    • 根据需求类型确定提示词类型：
      • 功能开发提示词
      • Bug 修复提示词
      • 性能优化提示词
      • 重构提示词
    • 根据技术栈确定提示词类型：
      • Spring Boot 提示词
      • MyBatis Plus 提示词
      • 若依框架提示词
      • Salesforce API 提示词

  3. 设计提示词的结构和内容

    • 引用真源（需求文档和设计文档）
    • 需求描述
    • 设计方案
    • 输出格式要求
    • 代码规范要求
    • 测试要求

步骤 2：生成提示词

  1. 确定文档路径

    • 路径：docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md
    • 使用 Write 工具创建文件
    • 确保目录存在（使用 LS 工具检查）

  2. 填充提示词内容

    • 引用真源： 
      # 提示词：用户登录功能

## 引用真源
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
    • 需求描述： 
      ## 需求描述
根据需求文档，实现用户登录功能，包括：
1. 用户名和密码验证
2. 记住密码功能
3. 自动登录功能
4. 登录失败提示
5. 登录成功后跳转到首页
    • 设计方案： 
      ## 设计方案
根据设计文档，采用以下技术方案：
1. 认证框架：Spring Security 6.x
2. Token 生成：JWT
3. 密码加密：BCrypt
4. 会话管理：Redis 存储 Token
5. 权限框架：若依权限系统
    • 输出格式要求： 
      ## 输出格式要求
1. 必须包含以下文件：
   - Controller：`SysLoginController.java`
   - Service：`SysLoginService.java`
   - Mapper：`SysUserMapper.java`
   - Entity：`SysUser.java`
   - 配置类：`SecurityConfig.java`
2. 必须包含单元测试：
   - `SysLoginServiceTest.java`
3. 必须符合 Spring Boot 最佳实践
4. 必须遵循若依框架规范
    • 代码规范要求： 
      ## 代码规范要求
1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
2. 方法命名：首字母小写，驼峰命名，如 `login`
3. 变量命名：首字母小写，驼峰命名，如 `userName`
4. 注释规范：
   - 类注释：使用 `/** */`，包含类功能描述
   - 方法注释：使用 `/** */`，包含方法功能、参数、返回值描述
   - 字段注释：使用 `/** */`，包含字段功能描述
    • 测试要求： 
      ## 测试要求
1. 单元测试覆盖率不低于 80%
2. 测试用例包含正常场景和异常场景
3. 使用 JUnit 5 和 Mockito 进行测试
4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`

  3. 提示词质量检查

    • 使用 Read 工具读取刚创建的提示词
    • 检查是否符合提示词内容约束
    • 检查是否引用了真源
    • 检查输出格式要求是否明确
    • 检查代码规范要求是否明确
    • 检查测试要求是否明确

步骤 3：更新索引和需求文档

  1. 读取现有索引

    • 使用 Read 工具读取 docs/index.md
    • 找到"提示词"部分
    • 如果不存在，则创建该部分

  2. 添加新提示词链接

    • 在"提示词"部分追加新提示词
    • 格式：- [提示词名](./prompts/YYYY-MM-DD-00X-prompt-提示词名.md) - [描述]
    • 示例：- [用户登录功能提示词](./prompts/2026-01-21-001-prompt-用户登录功能.md) - 用户登录功能的执行提示词

  3. 更新需求文档

    • 使用 Read 工具读取需求文档
    • 在"相关文档"部分添加提示词引用
    • 格式：- [提示词文档](../prompts/YYYY-MM-DD-00X-prompt-提示词名.md)
    • 使用 Write 工具更新需求文档

  4. 保存索引

    • 使用 Write 工具更新 docs/index.md
    • 严禁删除现有内容，只追加新内容

步骤 4：更新会话记录

  1. 读取现有会话记录

    • 使用 Read 工具读取 docs/sessions/YYYY-MM-DD-00X-session.md

  2. 更新阶段 5 信息

    • 更新"当前阶段"为"阶段 5：提示词生成"
    • 更新"阶段 5：提示词生成"的状态为"已完成"
    • 添加生成的提示词链接
    • 记录提示词内容摘要

  3. 保存会话记录

    • 使用 Write 工具更新会话记录

步骤 5：确认与询问

  1. 向用户确认

    • 显示提示词的链接
    • 询问："提示词是否合适？"
    • 询问："是否进入下一阶段（执行代码生成）？"

  2. 等待用户反馈

    • 如果用户不满意，询问具体需要修改的地方
    • 如果用户要求回退，执行回退机制（见错误陷阱部分）
    • 如果用户确认，标记阶段 5 为已完成，准备进入阶段 6

工具调用

必须使用的工具

  1. Read 工具：读取现有文件

    • 使用场景：读取需求文档、设计文档、索引、会话记录、提示词模板
    • 命令：Read(file_path="d:\\idea_demo\\datai\\docs\\requirements\\2026-01-21-001-用户登录功能.md")

  2. Write 工具：创建或更新文件

    • 使用场景：生成提示词、更新索引、更新需求文档、更新会话记录
    • 命令：Write(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md", content="...")

  3. LS 工具：检查目录是否存在

    • 使用场景：创建提示词前检查 docs/prompts/ 目录
    • 命令：LS(path="d:\\idea_demo\\datai\\docs")

  4. SearchCodebase 工具：搜索现有提示词

    • 使用场景：查找现有提示词作为参考
    • 命令：SearchCodebase(information_request="查找 docs/prompts 目录下的所有提示词")

可选使用的工具

  1. Glob 工具：查找文件

    • 使用场景：查找所有提示词
    • 命令：Glob(pattern="docs/prompts/*.md")

  2. TodoWrite 工具：管理任务

    • 使用场景：跟踪阶段执行进度
    • 命令：TodoWrite(todos=[...])

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

常见错误（Anti-Patterns）

错误 1：不引用真源

错误示例：

# 提示词：用户登录功能

## 需求描述
实现用户登录功能...

问题：

  • 没有引用真源（需求文档和设计文档）
  • 违反了 SSOT 原则

正确示例：

# 提示词：用户登录功能

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

## 需求描述
实现用户登录功能...

错误 2：输出格式要求不明确

错误示例：

## 输出格式要求
请生成用户登录功能的代码。

问题：

  • 输出格式要求不明确
  • 没有指定需要生成的文件
  • 没有指定代码规范
  • 没有指定测试要求

正确示例：

## 输出格式要求
1. 必须包含以下文件：
   - Controller：`SysLoginController.java`
   - Service：`SysLoginService.java`
   - Mapper：`SysUserMapper.java`
   - Entity：`SysUser.java`
   - 配置类：`SecurityConfig.java`
2. 必须包含单元测试：
   - `SysLoginServiceTest.java`
3. 必须符合 Spring Boot 最佳实践
4. 必须遵循若依框架规范

错误 3：代码规范要求不明确

错误示例：

## 代码规范要求
请遵循项目代码规范。

问题：

  • 代码规范要求不明确
  • 没有指定具体的命名规范
  • 没有指定具体的注释规范

正确示例：

## 代码规范要求
1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
2. 方法命名：首字母小写，驼峰命名，如 `login`
3. 变量命名：首字母小写，驼峰命名，如 `userName`
4. 注释规范：
   - 类注释：使用 `/** */`，包含类功能描述
   - 方法注释：使用 `/** */`，包含方法功能、参数、返回值描述
   - 字段注释：使用 `/** */`，包含字段功能描述

错误 4：测试要求不明确

错误示例：

## 测试要求
请添加单元测试。

问题：

  • 测试要求不明确
  • 没有指定测试覆盖率
  • 没有指定测试框架
  • 没有指定测试用例规范

正确示例：

## 测试要求
1. 单元测试覆盖率不低于 80%
2. 测试用例包含正常场景和异常场景
3. 使用 JUnit 5 和 Mockito 进行测试
4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`

错误 5：不更新需求文档的提示词引用

错误示例：

AI：生成提示词
AI：更新 docs/index.md
AI：完成（忘记更新需求文档）

正确示例：

AI：生成提示词
AI：更新 docs/index.md
AI：更新需求文档，添加提示词引用
AI：完成

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

错误示例：

AI：生成提示词
AI：进入阶段 6：执行代码生成（未询问用户）

正确示例：

AI：生成提示词
AI：提示词已生成：[链接]
AI：提示词是否合适？
AI：是否进入下一阶段（执行代码生成）？

验收清单（Checklist）

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

提示词完整性检查

  • 提示词已创建在 docs/prompts/ 目录下
  • 提示词命名符合 YYYY-MM-DD-00X-prompt-提示词名.md 格式
  • 提示词包含引用真源（需求文档和设计文档的链接）
  • 提示词包含需求描述
  • 提示词包含设计方案
  • 提示词包含输出格式要求
  • 提示词包含代码规范要求
  • 提示词包含测试要求

提示词质量检查

  • 引用真源格式正确
  • 需求描述清晰、准确
  • 设计方案完整、准确
  • 输出格式要求明确、具体
  • 代码规范要求明确、具体
  • 测试要求明确、具体

索引更新检查

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

需求文档更新检查

  • 需求文档已更新
  • 需求文档的"相关文档"部分已添加提示词引用
  • 提示词引用格式正确：[提示词文档](../prompts/YYYY-MM-DD-00X-prompt-提示词名.md)

会话记录更新检查

  • 会话记录已更新
  • 会话记录的"当前阶段"已更新为"阶段 5：提示词生成"
  • 会话记录的"阶段 5：提示词生成"状态已更新为"已完成"
  • 会话记录包含提示词链接
  • 会话记录包含提示词内容摘要

用户确认检查

  • 已向用户显示提示词链接
  • 已询问用户"提示词是否合适？"
  • 已询问用户"是否进入下一阶段？"
  • 已等待用户反馈

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

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

Correct vs Incorrect 代码对比

Incorrect（错误示例）

# 提示词：用户登录功能

## 需求描述
实现用户登录功能，包括用户名和密码验证、记住密码、自动登录等。

## 设计方案
使用 Spring Security 和 JWT。

## 输出格式要求
请生成代码。

Correct（正确示例）

# 提示词：用户登录功能

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

## 需求描述
根据需求文档，实现用户登录功能，包括：
1. 用户名和密码验证
2. 记住密码功能
3. 自动登录功能
4. 登录失败提示
5. 登录成功后跳转到首页

## 设计方案
根据设计文档，采用以下技术方案：
1. 认证框架：Spring Security 6.x
2. Token 生成：JWT
3. 密码加密：BCrypt
4. 会话管理：Redis 存储 Token
5. 权限框架：若依权限系统

## 输出格式要求
1. 必须包含以下文件：
   - Controller：`SysLoginController.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/controller/SysLoginController.java`）
   - Service：`SysLoginService.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/service/SysLoginService.java`）
   - Mapper：`SysUserMapper.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/mapper/SysUserMapper.java`）
   - Entity：`SysUser.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/domain/SysUser.java`）
   - 配置类：`SecurityConfig.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/config/SecurityConfig.java`）
2. 必须包含单元测试：
   - `SysLoginServiceTest.java`（路径：`datai-modules-system/src/test/java/com/datai/modules/system/service/SysLoginServiceTest.java`）
3. 必须符合 Spring Boot 最佳实践
4. 必须遵循若依框架规范
5. 必须使用 MyBatis Plus 进行数据库操作

## 代码规范要求
1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
2. 方法命名：首字母小写，驼峰命名，如 `login`
3. 变量命名：首字母小写，驼峰命名，如 `userName`
4. 注释规范：
   - 类注释：使用 `/** */`，包含类功能描述、作者、创建时间
   - 方法注释：使用 `/** */`，包含方法功能、参数、返回值、异常描述
   - 字段注释：使用 `/** */`，包含字段功能描述
5. 代码格式：使用 4 个空格缩进，行宽不超过 120 字符
6. 导入规范：使用 import 静态导入，避免通配符导入

## 测试要求
1. 单元测试覆盖率不低于 80%
2. 测试用例包含以下场景：
   - 正常登录成功
   - 用户名不存在
   - 密码错误
   - 用户已停用
   - 验证码错误
3. 使用 JUnit 5 和 Mockito 进行测试
4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`
5. 测试数据使用 Mockito 模拟

## 注意事项
1. 必须处理 Salesforce API 的空值情况
2. 必须使用若依的 `@DataScope` 注解进行数据权限控制
3. 必须使用若依的 `@Log` 注解记录操作日志
4. 必须使用若依的 `GlobalExceptionHandler` 处理异常

附录：快速参考

文件路径速查

  • 需求文档：docs/requirements/YYYY-MM-DD-00X-需求名.md
  • 设计文档：docs/design/YYYY-MM-DD-00X-设计名.md
  • 提示词：docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md
  • 主索引：docs/index.md
  • 会话记录：docs/sessions/YYYY-MM-DD-00X-session.md
  • 项目规则：.trae/rules/project_rules.md
  • SSOT 架构师提示词：docs/Prompt/0004-单一真源文档驱动架构师.md
  • 提示词模板：docs/Prompt/0000-template.md

工具命令速查

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

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

# 生成提示词
Write(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md", content="...")

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

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

# 搜索现有提示词
SearchCodebase(information_request="查找 docs/prompts 目录下的所有提示词")

# 查找所有提示词
Glob(pattern="docs/prompts/*.md")

阶段 5 输出清单

  • 提示词文档：docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md
  • 更新的索引：docs/index.md
  • 更新的需求文档：docs/requirements/YYYY-MM-DD-00X-需求名.md
  • 更新的会话记录：docs/sessions/YYYY-MM-DD-00X-session.md

下一阶段提示

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

  • project_rules.md 的"阶段 6：执行代码生成"
  • 准备分析需求和设计文档
  • 准备确定需要生成的代码文件
  • 准备加载阶段 5 生成的提示词
  • 准备生成代码