spring-data-jdbc

检测防护

应用此技能中的任何规则之前，请确认目标文件导入了 org.springframework.data.relational.core.mapping / org.springframework.data.annotation。如果看到 jakarta.persistence.* 导入，请停止并切换到 spring-data-jpa 技能——这两个技术栈不能互换，JPA 中的模式（HibernateProxy、@ManyToOne、@OneToMany、@JoinColumn、FetchType）不适用于此处。

Harness 兼容性

此技能旨在适用于多种 Agent 运行时（Claude Code、Codex、OpenCode）。技能中提到了两种特定于 Harness 的原语；请将它们视为优先但非必需的功能，并在不可用时妥善降级：

• AskUserQuestion（Claude Code 的结构化提示，提供多项选择）。运行时支持时，请在每个约定文件的第 1.4 步使用它——这些文件中的 JSON 示例与该工具所需的参数格式对应。运行时不支持时（Codex、OpenCode、普通命令行），请在对话中以内联方式询问完全相同的问题：将每个问题呈现为一段简短文字，后接编号或项目符号选项列表，在推荐选项后标注 (Recommended)，并接受用户回复中的选项标签或编号。决策树保持不变；只有呈现方式不同。
• “Memory”——Claude Code 基于持久文件的自动记忆。类似“检查记忆中先前保存的约定”的引用表示：如果你可以访问 Claude Code 的自动记忆，请先查看。对于 Codex/OpenCode（以及任何没有持久记忆的运行时），改为“扫描本次对话较早的轮次”——如果本会话已确定约定，请复用；如果是全新会话，则从头执行第 1 步。

不要仅因缺少其中一种原语就拒绝任务。请使用内联等效方式替代，并在任务开始时说明一次替代情况（“此运行时不支持 AskUserQuestion——改为以内联方式提问” / “此运行时没有持久记忆——从头检测约定”）。

---

预检：Spring MCP

此技能属于 Spring Agent Toolkit，旨在与 Spring MCP 服务（由 Amplicode IntelliJ 插件提供）配合使用。开始任何操作前，请检查工具列表中是否有 Spring MCP 工具——这些工具通过 amplicode MCP 服务公开（例如 get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories）；将 MCP 工具扁平化到工具列表中的 Harness 会对相同名称使用 mcp__amplicode__ 前缀。

• 如果至少有一个 Amplicode 工具可用——表示 MCP 已连接。继续使用下方的技能。
• 如果没有可用工具——停止并调用 amplicode-install 技能（与 Spring Agent Toolkit 捆绑）。该技能会安装 Amplicode 插件，并引导用户点击欢迎屏幕上的 «Настроить Spring Agent» 按钮，然后重启 MCP 客户端。完成后，MCP 工具便可用——继续使用此技能。
• 如果技能列表中未注册 amplicode-install，或用户拒绝安装（例如，他们使用的是不支持 MCP 的 Harness，如 CI 沙盒），请继续使用下一节所述的文件读取备用方案，以免任务受阻。

---

MCP 可用性与回退方案

本技能优先使用 Spring MCP 工具（get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories），因为它们可以通过一次调用返回已解析的项目级答案。如果 Spring MCP 服务无法访问（连接错误、工具未注册、运行环境不支持 MCP），且用户已选择不通过上面的 Preflight 安装插件，则不要拒绝任务——改用直接读取文件／grep 作为回退方案：

本项目以 Kotlin 为主（主要使用 Kotlin 2.2.20，部分模块使用 Java）——每次回退 grep 都必须同时匹配 *.kt 和 *.java。不要向 rg 传递 -t java；要么省略类型筛选，要么使用 -t kotlin -t java。

• 要替代 list_all_domain_entities——在项目中 grep org.springframework.data.relational.core.mapping.Table 导入（或导入解析到该位置的 @Table 注解），以枚举 JDBC 实体。对 .java 和 .kt 文件均适用。
• 要替代 list_entity_repositories——grep 仓库声明关键字（Java 中是 extends，Kotlin 中是 :；Kotlin 中冒号前可能没有空格，因此要使用 \s*）。明确写出每个基接口，而不要依赖可选前缀——(List)?(...|...) 对人类读者来说有歧义：

  (extends|:)\s*(ListCrudRepository|CrudRepository|ListPagingAndSortingRepository|PagingAndSortingRepository)\b
  

• 要替代 get_jdbc_entity_details——参见 references/aggregate-rules-impl.md 中的“Without get_jdbc_entity_details”小节。该小节中的手动步骤通过读取源文件（包括 Java 和 Kotlin）可得出相同的 idField.type / aggregateRootFqn / aggregates / referencedBy 信息。

在任务开始时说明一次，你正在使用回退模式及其原因（例如：“Spring MCP 无法访问——使用文件读取回退方案”）。不要悄悄切换。

处理 JDBC 实体

当任务涉及创建或修改 Spring Data JDBC 实体时：

1. 如果本次对话中尚未检测实体约定——先检查记忆中是否保存了之前的约定（或在不支持持久化记忆的运行环境中查看之前的对话轮次——参见“Harness compatibility”）。如果找到，则沿用。否则，阅读 references/entity-conventions.md 并遵循其中的所有子步骤来检测项目约定。
2. 阅读 references/entity-rules-impl.md，并在编写或修改实体时遵循其中的规则。
3. 如果实体之间或实体与现有实体之间存在任何关系——集合字段、引用字段、FK 列，或用户请求中描述的关系（“X 属于 Y”“Y 有多个 X”）——还必须在决定任何链接的形态之前阅读 references/aggregate-rules-impl.md。实体规则涵盖字段语法；聚合规则决定哪些关系形态合法，以及链接可以持有在哪一侧。跳过此步骤就会生成非法形态（指向其他聚合成员的原始 FK、引用非根实体）。

工具与源码的使用原则——准备编辑实体时，直接读取源文件。get_jdbc_entity_details 被明确说明为只读分析工具，并明确指出“如果计划随后修改实体类——请直接读取文件”。仅在需要获取单个文件中看不到的跨聚合上下文时使用 MCP 工具：

• 目标实体在其聚合中的角色（aggregateRootFqn）。
• 指向该实体的其他聚合（referencedBy）。
• 需要通过 AggregateReference<Other, IdType> 链接到的其他聚合的 ID 类型（如果读取 Other 的源文件过于繁琐）。

对于要编辑文件中的所有内容——ID 类型、当前字段、当前 @MappedCollection / @Embedded 声明——都要读取该文件。

审查 JDBC 模式

当用户要求审查项目中的 JDBC 模式、约定或代码质量时：

1. 按照 references/entity-conventions.md（步骤 1.1–1.5）检测当前约定。
2. 将检测到的约定与 references/entity-rules-impl.md 中定义的最佳实践进行比较。对于每一处偏差，按以下格式给出建议：

### JDBC Review

**[Convention or pattern name]**
- Current: <what the project does>
- Recommended: <what the best practice says>
- Reason: <why this matters>

如果没有发现偏差，则说明项目遵循最佳实践。

---

使用 JDBC 仓库

当任务涉及添加或修改 Spring Data JDBC 仓库时：

1. 如果尚未在本次对话中检测仓库约定，则先检查记忆（或较早的对话轮次——参见“Harness 兼容性”）。否则，阅读 references/repository-conventions.md 并遵循其中所有子步骤。
2. 阅读 references/repository-rules-impl.md 并遵循其中的规则。

创建新仓库前，调用 list_entity_repositories，并设置 entityFqn = <target>，以确认该实体尚无仓库；同时调用 get_jdbc_entity_details 查询目标实体——只有聚合根（aggregateRootFqn == null）才能创建仓库。请注意，list_entity_repositories 不支持 JDBC 筛选；如果调用时未设置 entityFqn，请手动筛选结果。

---

使用聚合

当任务涉及聚合边界时——添加 AggregateReference 字段、将自有的 @MappedCollection 转换为跨聚合链接、拆分聚合、创建实体间的任何关系（包括一对多、多对多），或回答“谁引用了 X？”／“聚合 Y 中包含什么？”时：

1. **必须：**首先阅读 references/aggregate-rules-impl.md，并检查其中适用于具体关系类型的规则。确认适用规则之前，不得修改实体。
2. 如果尚未在本次对话中检测聚合约定，则先检查记忆（或较早的对话轮次——参见“Harness 兼容性”）。否则，阅读 references/aggregate-conventions.md 并遵循其中所有子步骤。
3. 只有在阅读完这两个参考文件后，才能修改实体。严格遵循其中的规则。

MCP 工具 get_jdbc_entity_details 是聚合成员关系的事实来源。其响应包含 aggregateRootFqn（如果该实体本身是根，则为 null）、aggregates（自有子级，递归；仅根实体会填充此项）和 referencedBy（通过 AggregateReference 链接到此处的其他聚合）。在决定任何聚合边界之前，请先阅读这些信息。

---

重要：一对多和多对多关系

**不同聚合之间的任何一对多或多对多关系都必须使用链接实体。**这一要求不可协商。实现此类关系前：

1. 通过 get_jdbc_entity_details（或阅读实体）确认双方都是聚合根，或检查它们的聚合成员关系。
2. 如果它们属于不同的聚合，则必须创建中间链接实体——不得使用直接指向另一个根的 @MappedCollection。
3. 阅读 references/aggregate-rules-impl.md 中的具体规则——“Rule: One-to-many between two aggregates goes through a link entity”或“Rule: Many-to-many between two aggregates goes through a link entity”部分。
4. 严格遵循文档中的链接实体模式：持有方通过 @MappedCollection 拥有链接集合；每个链接实体都包含指向目标根的 AggregateReference<Target, IdType>。