AGENTS.md

本文件为 AI 编码代理在 open-cdm 仓库内工作时的规则说明，内容按 open-cdm 的实际工程组织和本地团队规则调整。

作用范围

• 本文件适用于当前目录为根的整个 open-cdm 仓库。
• 如果某个子目录下存在更深层的 AGENTS.md，则该子目录及其后代目录以内层文件为准。
• 本文件约束源码、文档、配置、脚本和测试变更；默认不要修改生成产物、依赖目录和构建输出，例如 backend/**/build/、 frontend/node_modules/、frontend/dist/、package/build/。

项目定位

• open-cdm 是 CloudDM 的开源工程，面向团队数据库管理。
• 核心能力包括数据源管理、数据查询、权限控制、数据脱敏、SQL 审核、数据库 CI/CD、工单协作和多部署形态。
• 主要技术栈：
  • 后端：Java、JDK 17+、Gradle 9.5.0+、Spring / Spring Boot、MyBatis。
  • 前端：Vue 3、Vue CLI、JavaScript / TypeScript、Node.js 22.22.1。
  • 运行数据库：MySQL 8.0+。

项目结构

• backend/：后端 Gradle 根工程，包含启动模块、平台模块、插件模块、工具模块和测试模块。
• backend/settings.gradle：后端模块注册入口；新增插件或数据源模块时必须同步注册。
• backend/clouddm-boot/：启动与初始化模块，包括 boot-alone、boot-console、boot-sidecar、boot-initialization。
• backend/clouddm-platform/：平台核心模块，包括 API、DAO、Console、Sidecar、插件 SDK 和共享库。
• backend/clouddm-plugins/：数据源、认证 Provider、特性插件和内置插件。
• backend/clouddm-utils/：通用工具、驱动、RPC、schema、SQL / DSL 解析等基础能力。
• backend/clouddm-platform/cgdm-dao/src/main/resources/mybatis/mapper/：MyBatis XML mapper 目录。
• backend/clouddm-boot/boot-initialization/src/main/java/com/clougence/clouddm/init/component/scripts/：Flyway Java 初始化和升级脚本目录。
• frontend/：CloudDM Web 前端工程，也是后端 Gradle 中的 cgdm-web 模块。
• frontend/src/locales/：前端国际化文案目录。
• package/：统一构建、tgz 打包、Docker 镜像和部署清单生成入口。
• docs/：中英文文档与图片资源。
• backend/gradle.properties：主版本号 cg.clouddm.main.version 所在文件。

工作方式

• 以最小且正确的改动解决问题。
• 优先选择直接、清晰、可读的实现，不追求花哨抽象。
• 当多条规则冲突时，优先保证行为正确、状态一致、契约清晰。
• 不乱猜业务语义；拿不到明确数据时，不要擅自补业务对象、状态、内容或其他业务含义。
• 不胡乱兼容旧逻辑；已经明确删除的字段、分支、路径要清干净。
• 先阅读相关模块的现有实现，再决定改法；优先沿用本仓库已有模式、命名、工具类和基础设施。
• 工作区可能存在用户未提交改动；不要回滚、覆盖或重排与当前任务无关的改动。

构建与验证命令

环境要求

• JDK 17+
• Gradle 9.5.0+
• Node.js 22.22.1
• MySQL 8.0+
• Docker 仅在构建镜像或部署清单时需要

全量构建与打包

# Full build, including frontend assets.
cd package && ./all_build.sh

# Frontend web resources only.
cd package && ./all_build.sh web

# Rebuild one plugin package. Replace the module name as needed.
cd package && ./all_build.sh plugin plus-provider-ldap

# Compile and generate tgz install packages.
cd package && ./package.sh --build

# Compile, package, and build Docker images plus deployment manifests.
cd package && ./package.sh --build --docker

# Build Docker images for one architecture.
cd package && ./package.sh --build --docker arm64
cd package && ./package.sh --build --docker x86_64

后端

# Build from the backend Gradle root.
cd backend && ./gradlew -Pprofile=dev -Ptarget=none -PbuildFrontend=true buildx local -x test --parallel --max-workers=16

# Run all tests when the scope requires it.
cd backend && ./gradlew test

# Run one module's tests.
cd backend && ./gradlew :<module>:test

# Build one module.
cd backend && ./gradlew :<module>:build

• 本地调试通常打开 backend/ 作为 Gradle 工程。
• 单机模式入口：backend/clouddm-boot/boot-alone/src/main/java/com/clougence/clouddm/boot/DmAloneLauncher.java。
• 启动后访问 http://localhost:8222；首次启动会进入初始化流程。

前端

cd frontend && npm install
cd frontend && npm run serve:dm
cd frontend && npm run build:dm
cd frontend && npm run lint
cd frontend && npm run lint-fix
cd frontend && npm run test:unit
cd frontend && npm run check-i18n

• 前端使用 package-lock.json，默认使用 npm，不要擅自切换到其他包管理器。
• 修改任何前端源码后，必须从仓库根目录执行 cd package && ./all_build.sh web，且命令必须成功（退出码为 0）；若构建失败，必须修复所有阻塞错误后才能认定任务完成，不得以“既有问题”或“与本次改动无关”为由跳过。
• 修改用户可见文案时，同步维护 frontend/src/locales/。

编码规则

• 不过度防御，不为了极低概率场景写复杂兜底逻辑。
• 允许基于模块边界、配置约束和框架契约建立合理信任；不要不看上下文就把所有值都当成任意脏输入。
• 不要为实际不可能出现的 null、空值或非法状态写复杂防御分支；防御逻辑只放在真实边界和不可信输入处。
• 避免长条件和层层 if 堆叠导致代码难读；如果必须校验，优先让边界、契约和数据结构保持清晰。
• 代码要干净直接，好读优先，不要为了抽象而抽象。
• 组装多个对象时，按对象集中排列字段赋值（包括 setter、直接赋值和 Map 的 put），同一对象的业务字段、审计字段和时间字段放在一起，避免无依赖的交叉赋值；对象之间用空行分隔。
• 嵌套对象优先先组装子对象，再集中组装父对象。涉及权限判断、状态更新、数据库回填 ID 等依赖时，保留必要的执行顺序，不为集中排列新增无意义的分支、方法或封装。
• 尽量不写三元表达式，能用 if 表达清楚的逻辑，优先使用 if。
  • 连续条件判断的三元表达式只有在完整表达式能控制在 100 个字符以内时才允许使用；超过后必须退化为显式 if ，避免嵌套三元和换行三元影响阅读。
• 写代码时不要过分抽方法；没有明显复用、没有降低理解成本的短逻辑，正常内联写在调用处即可。
• 不写没必要的小 helper，只有复用明显且能降低理解成本时才抽。拆小方法的规则是：
  • 23 行的代码在 35 处以上重复出现，那么适合拆小方法，但是优先考虑使用 JDK 自带工具及 utils 包的工具方法。
  • 一个独立的业务逻辑具有 20行以上的代码量那么适合拆小方法。否则优先 在代码中使用注释分段执行并标记注释。
  • 一个方法超过 40 行就适合评估拆方法。
  • 大段 if/else 分支承载独立业务流程时，即使只有一个调用点，也可以抽成有业务含义的小方法。
• 不为了测试扩大生产代码的 public API。
• 不要增加只为测试存在的生产方法。
• 没用到的字段、方法、分支、返回值要删掉。
• 方法、字段可见性要明确，能 private 就不要保留为默认或 public。
• 不要写内部类；类和枚举都必须定义在独立的 Java 源文件中。
• 使用 Jakarta Bean Validation 注解时，不要设置 message 属性，直接使用注解的默认校验消息。
• 不要使用 @SneakyThrows；需要 try/catch 异常时，用简短 msg 描述错误，并通过 log.error(msg, e) 打印异常。
• Java 中能用 Lombok 解决 getter / setter 模板代码的地方，优先使用 Lombok。
• Lombok 注解按实际用途添加，不默认叠加 @EqualsAndHashCode、@ToString 等；值比较、集合键或日志输出等真实使用场景需要时才保留。
• 同时需要 getter 和 setter，且需要三个及以上 Lombok 注解时，使用 @Data 合并其覆盖的注解；@Data 不覆盖的构造器、日志等注解按需保留。不要为了使用 @Data 给只读对象增加 setter。
• 重复胶水代码要适度收敛，但收敛方式不能比原逻辑更难懂。
• 注释只解释不明显的业务约束、协议边界或复杂流程，不写重复代码字面含义的注释。
• 前端调用后端时，使用的接口名称要求格式为驼峰命名法。

Java 后端规则

• 修改任何 Java 文件后，必须在仓库根目录运行 ./scripts/format_java.sh，统一完成 imports 优化和 codeformat.xml（cdm-format）格式化，且命令必须成功（退出码为 0）。
• 运行前确保 IDEA 已打开对应项目、索引完成且文件已保存；同时运行多个 IDEA 版本时，通过 IDEA_BIN 指定。
• imports 优化沿用 IDEA 实际选用的优化器，包括 Eclipse Formatter 等插件的覆盖实现，不绕过插件调用默认优化器。
• imports 以项目实际生效的 IDEA Java Code Style 配置为准，包括适用的 .editorconfig 和项目 Code Style； 未覆盖的设置使用 IDEA 当前选用的方案。分组、排序、空行及静态导入位置遵循 Import Layout，不另行硬编码分组顺序。
• Optimize Imports 应清理未使用、重复和冗余导入，并遵循普通／静态导入的通配符阈值、强制通配符包列表及内部类导入设置。 IDEA 默认阈值通常为同包 5 个类、同类 3 个静态成员，实际值以生效配置为准；合并时必须处理名称冲突， 不得强制展开所有 *，也不得仅按数量机械合并。
• 不得用手工整理、其他格式化工具或 --format-only、--check、--dry-run 代替完整执行； 脚本失败时应修复后重试，无法解决时明确报告阻塞原因，不得认定任务完成。
• 脚本自动处理 Git 中已暂存、未暂存和未跟踪的 Java 文件；执行前后检查 diff，保留用户已有改动，并运行相关编译验证。
• 遵循现有包结构和模块边界，避免跨层直接调用导致平台、插件、启动模块相互缠绕。
• 优先使用项目已有基础设施，例如 com.clougence.utils、插件 SDK、DAO、服务层、统一异常和日志机制。
• 数据库实体沿用 DO 后缀，表单对象沿用 FO，请求 / 响应对象沿用 VO。
• 新增数据源能力时，优先参考 backend/clouddm-plugins/clouddm-ds/ 下相近实现，并在 backend/settings.gradle 注册模块。
• 新增认证或第三方集成时，优先参考 backend/clouddm-plugins/clouddm-provider/ 下相近实现。
• 新增平台 API 时，同时检查 cgdm-api、cgdm-console、cgdm-dao、前端调用和测试是否需要同步调整。
• 日志使用 Lombok @Slf4j；错误日志要带上下文和异常栈，不要吞异常。
• 异常信息要简短、明确，避免只抛空泛的 RuntimeException。
• 在插件执行过程中中抛出的异常使用 ThirdPartyApiException 类型抛出。
• 业务异常抛出时要使用 ErrorMessageException 类型并配备国际化。
• 初始化/升级脚本这一块，永远不能改历史 migration

数据源 SQL 函数与权限资源模板

• 新增或补齐数据源函数时，统一参考 PostgreSQL 的现有实现，保持最小改动：
  • postgres-built-in-functions.json：登记内置函数名称及适用版本。
  • postgres-analysis-resources.json：登记元数据函数、特权函数、语句分类和行为分类。
  • PgResourceRegistry 和 PgSysObjectRegistrySpi：资源注册、查询及权限判断的职责划分。
• 各数据源使用对应的 <datasource>-built-in-functions.json 和 <datasource>-analysis-resources.json。 沿用上述 JSON 的字段结构、空格、缩进和紧凑条目排版，短数组保持单行，不机械地把每个数组元素拆成一行。
• 内置目录中的 entries 使用 versions、type、name；分析资源沿用 metadataFunctions、privilegedFunctions、 functionStatementTypes、functionBehaviors 等分类，以及 action、targetType、targetAction、unsafe 等行为字段。 按数据源实际能力登记，不复制不适用的 PostgreSQL 对象或行为。
• 版本信息必须依据官方对应版本资料，保留来源；只登记必要的大版本，不能把某一版本的目录视为所有版本通用，也不能编造版本范围。 产品版本与兼容内核版本分别处理，产品专属函数不能使用兼容内核版本判断。
• 版本解析沿用 SqlServerVersion 一类的版本枚举、LATEST 和 parse() 写法。 未知版本沿用现有枚举解析约定，不另加正则门禁、第二套解析或自造版本编号。云服务按实际可识别的版本或兼容模式处理； 无可识别版本时，明确区分无版本的行为分类与函数可用性，不能用固定版本号伪装版本信息或据此默认放行。
• 各数据源在自己的 analysis/reference/*ResourceRegistry 中统一维护资源，采用 INSTANCE、instance() 和私有构造器， 在构造器中加载资源，提供内置函数、普通函数及分类查询。已有注册器直接补齐，不另加重复封装或兼容转发层。
• SysObjectRegistrySpi 只负责权限判断，通过对应 ResourceRegistry 查询；不得在 static {}、SQL 引擎类或权限注册器中加载函数资源， 不得使用 loadNames() 丢弃版本信息，也不得通过 ignored -> 1 等写法忽略真实版本。
• 拆句、行为分析和权限判断共用同一个资源注册器。Visitor 仅在接入分类、补齐函数行为或保留限定名和引号等必要信息时修改； 入口迁移只调整 import 和调用点，不顺便重写解析逻辑，也不能提前跳过目录中的函数而遗漏权限行为。
• 普通内置函数的 CALL 通过现有权限豁免入口处理；被访问表的查询权限仍正常校验。 自定义函数、限定名、带引号名称按各数据源真实语义判断；特权或不安全行为，以及函数实际访问的配置项、文件等资源仍须独立鉴权。
• 不得只补 JSON：相关语句分类、行为分析和权限判断必须接通，并在现有回归中覆盖版本边界、未知版本、普通内置函数、 自定义函数、限定名、带引号名称和管理函数。整理变更时，按数据源将代码、JSON 和对应测试放在同组，公共实现与跨数据源测试单独归组。

前端规则

• 前端以 Vue 3 和 Vue CLI 为主，优先沿用 frontend/src/components/、frontend/src/services/、frontend/src/store/、 frontend/src/router/、frontend/src/views/ 的既有模式。
• 用户可见文案必须维护在 frontend/src/locales/，不要在组件、服务或 store 中直接硬编码展示文案。
• 修改接口字段、枚举、状态或错误码时，要同步检查后端 VO / API、前端 service、页面逻辑和测试。
• 后端已经删除的字段，前端不要继续保留 fallback 行为。
• 不要擅自引入新的 UI 框架、状态管理库或构建工具。
• 复用现有组件和样式规范；只有现有组件无法表达真实交互或可访问性需求时，才新增组件。
• 修改样式时要检查移动端和常见桌面宽度，避免文案溢出、控件遮挡和布局跳动。

数据库变更

• 不要修改已经发布或已用于升级路径的历史 Flyway Java migration。
• 新增结构或数据变更时，在 backend/clouddm-boot/boot-initialization/src/main/java/com/clougence/clouddm/init/component/scripts/ 下新增 migration，并沿用现有命名和执行模式。
• SQL 只负责必要的数据查询、过滤和排序；不要把复杂业务计算写进 SQL。
• 跨日期统计、多口径聚合等复杂计算优先放在 Java 内存里做，数据库侧只拉取必要字段。
• MyBatis XML 中 SQL 比较符统一使用 <![CDATA[ ... ]]>，不要写 <、> 这类 XML 转义符。
• MyBatis XML 中的 SQL 关键字统一大写；SELECT、FROM、WHERE、ORDER BY、UPDATE、SET、INSERT、 VALUES、DELETE 等主要子句分行，表名或列清单缩进一层；同一条件块或赋值块的比较、赋值运算符纵向对齐， 多个条件每行一个，AND、OR 独立占一行并与条件字段保持同级缩进。<sql> 公共列片段保持现有紧凑格式， 不做机械展开。
• 修改表结构、字段语义或默认数据时，同步检查 DAO、DO、mapper、初始化脚本、升级脚本、前端展示和测试。

Flyway 数据订正

• collectScript() 只放 DDL 结构变更；历史数据回填、状态转换、缓存去重等 INSERT、UPDATE、DELETE 数据订正放到 beforeMigrate(Connection) 或 afterMigrate(Connection)，不要混入 collectScript()。
• 执行顺序为 beforeMigrate() → collectScript() → afterMigrate()。依赖旧字段或必须在结构变更前完成的订正放到 beforeMigrate()；依赖新增字段、表或新结构的订正放到 afterMigrate()。
• 唯一索引、非空约束等依赖数据订正结果时，必须先订正数据，再在对应钩子中执行依赖的 DDL，并注释说明顺序依赖； 不要在 collectScript() 中提前建立这些约束。
• 简单订正沿用 safeExecute(connection, sql)；需要参数绑定或逐条处理时，使用 PreparedStatement，通过 try-with-resources 释放语句和结果集，复杂业务转换放在 Java 中完成。
• 订正必须限定正确的账号归属、业务类型、来源及待订正状态，并保证重复执行幂等。缓存去重须明确保留规则， 不得误删自定义业务定义、在途实例或历史记录。
• 参考现有 V202607270001__sql_audit_ack 的参数化订正和 V202607290003__consolidated_upgrade 的 “先回填、再加约束”写法。验证时使用隔离测试库，覆盖存量数据、重复执行、订正范围及约束生效，不直接重跑共享开发库迁移。

MyBatis Mapper XML 可读性规则

• 新增或修改 MyBatis Mapper XML 时，以 backend/clouddm-platform/cgdm-dao/src/main/resources/mybatis/mapper/DmApprovalProcessMapper.xml 为排版参考。
• XML 使用 4 个空格缩进，每深入一层增加 4 个空格，禁止使用 Tab；自闭合标签写成 <result .../>，/> 前不加空格。
• DOCTYPE 的公共标识和 URL 分成两行，第二行缩进 8 个空格。<resultMap>、<sql> 和每条 CRUD 语句等顶层代码块之间 只保留一个空行；同类 CRUD 语句也不能连续挤在一起或使用多个空行。
• resultMap 每个字段映射独占一行。单行过长时，从 javaType、typeHandler 等扩展属性处换行，后续属性缩进 16 个空格。
• SQL 关键字和标准函数名统一大写，例如 SELECT、FROM、WHERE、AND、ORDER BY、NOW()、COUNT()； MyBatis 标签、参数名、列名、表名和字符串常量保持原有大小写。
• SELECT、FROM、WHERE、UPDATE、SET、INSERT INTO、VALUES、DELETE FROM 等主要子句独占一行， 表名、字段、值和条件相对其子句再缩进一层。短小的 ORDER BY id、GROUP BY type 可以保持一行，多字段时按字段换行。
• WHERE 中每个条件独占一行，第二个及后续条件的 AND、OR 独占一行；SET 中每个赋值独占一行。 只在同一个连续条件块或赋值块内用空格纵向对齐运算符，不跨 MyBatis 动态标签强行对齐。
• 逗号放在当前字段、值或赋值行的行尾。SELECT 字段较多时优先使用 <sql> 和 <include> 复用，不写超长横向字段列表。
• <if>、<choose>、<when>、<otherwise>、<foreach>、<where>、<set>、<trim> 等动态标签按 XML 层级缩进， 内部 SQL 在标签基础上再缩进一层；禁止把动态标签及其 SQL 内容压缩在同一行。
• SQL 比较符包含 <、>、<= 或 >= 时，统一写成 <![CDATA[ ... ]]>，并在 CDATA 内侧保留一个空格； 不使用 <、> 等 XML 实体代替。

前后端契约

• 前后端契约必须保持一致。
• 字段删除时，要同时删除后端、前端和测试中的对应逻辑。
• 前端不要为后端已删除字段继续保留 fallback 行为。
• 在增加兼容逻辑前，先确认后端真实协议。
• 接口响应、状态机、权限判断、国际化 key 和错误码要以当前真实实现为准，不要凭命名猜业务含义。

并发、连接与流式

• 异步、线程池、队列、锁、连接和流式处理相关代码必须特别谨慎。
• 不要把慢连接或阻塞 I/O 带回生产工作线程。
• 重点关注终态、重试、重复执行、重连、资源释放、不可恢复失败等路径。
• 涉及数据库连接、查询执行、结果导出、WebSocket、任务调度、插件加载和 worker 心跳时，要明确资源释放和失败恢复路径。

测试要求

• 测试相关文档统一放在主工程 tests/ 的现有分类目录中，例如 tests/frontend/、tests/datasource/；不得放到 docs/、仓库根目录，或随意新建 testing/ 等平行目录，也不要在 tests/ 根目录堆放报告。
• 优先更新已有的长期测试流程和测试矩阵，不按任务、日期或执行次数重复创建验收文档。一次性执行记录、临时日志和过程报告不入库，验证结果直接在回复中说明。
• 没有合适归属或长期维护价值时，不新增测试文档，不为存放报告另造目录；不要擅自迁移或删除与当前任务无关的已有文档。
• 用户没有主动明确要求新增测试类时，不要新增任何测试类。
• 测试要覆盖真实风险路径，不要只覆盖表面分支。
• 重点覆盖网络断开、重连、终态、不可恢复、重复执行、慢连接、资源释放等场景。
• 后端改动优先运行相关模块测试；影响公共模块、DAO、初始化、权限、SQL 执行或插件协议时扩大验证范围。
• 前端改动优先运行 npm run lint、npm run check-i18n 和相关单测；用户可见流程变更要做浏览器级检查。
• 可重复执行的前端浏览器测试流程统一维护在 tests/frontend/；一个用户流程只维护一份长期有效的流程文档，不按执行日期生成测试报告。
• 前端用户可见行为、交互、布局、路由、权限、表单、状态流或接口契约发生变化时，必须使用 @Browser 内置浏览器复测。测试前读取相关流程文档，测试后按当前真实实现创建或更新文档；具体格式和 @Browser 复测规则遵循 frontend/AGENTS.md 的“可复用的前端复测流程”章节。

Review 规则

• Review 只提真实 bug 和明确 concern。
• 不要堆风格噪音，除非它确实影响正确性、可维护性或契约清晰度。
• 优先关注状态一致性、协议破坏、权限绕过、升级兼容、资源泄漏、重复执行和前后端字段不一致。

PR 与提交

• PR 说明要清楚描述改了什么、为什么改、如何验证。
• 提交信息使用 Conventional Commits，例如 feat(mysql): support prepared statement 或 fix(auth): avoid stale role cache。
• 提交前确认没有把本地构建产物、依赖目录、日志、临时文件或无关格式化改动带入 diff。

@AGENTS.local.md