扩展开发

新增功能的目标是让客户业务沿用现有认证、接口、菜单、事务与部署方式。先确定完整用例和状态归属，再创建目录，不从一个通用 CRUD 模板机械复制所有层。

1. 明确业务与变更范围

写清用户操作、请求/响应、状态变化、角色及数据范围、失败场景。先判断属于已有业务域，还是有独立构建/交付需求的新模块。

已有域内扩展通常放入 art-system 的对应包。只有实际需要独立依赖、构建或交付时才新建 art-modules/art-xxx，同时维护聚合 POM、依赖管理和应用装配。

2. 以当前真实用例作为参考

例如新增系统设置类资源，可从以下链路理解当前风格：

text

settings/controller/SystemParamController.java
  → settings/service/SystemParamService.java
  → settings/mapper/ 与 mapper/settings/
  → settings/dto/、vo/、domain/

同时读取权限常量、缓存失效、对应迁移和测试。参考的业务语义不一定可直接复制，例如普通配置与支付凭据对 PATCH 的处理不同。

跟读一次已有的列表查询

先不新建模块，用当前系统参数列表熟悉一次完整流程：

在接口文档找到 GET /api/v1/system-params，查看 current、size、keyword 等参数。
在 SystemParamController.list 观察 @Valid、@RequireApiPermission 和当前用户 ID 的传递。
在 SystemParamService.listInScope 观察数据范围、分页和 VO 组装。
在 filter(...) 与 SystemParamFilter 中确认 HTTP 参数怎样转换为数据访问条件。
打开 mapper/settings/SystemParamMapper.xml，核对筛选、参数绑定和数据范围。

例如未来新增一个筛选字段，需要同时修改请求 DTO、筛选模型、Service 转换与 SQL，并增加有该值、无该值和越权数据的验证。前端再同步类型与查询参数。

3. 定义数据与接口模型

用新 Flyway 迁移新增表、索引和必要默认数据，不修改已发布基线。
DTO 用于 HTTP 校验，VO 用于响应，Entity 用于表映射。
查询条件与写入命令放在域内模型中，Mapper 不接收 HTTP DTO/VO。
保持 R、分页、日期、金额与 PATCH 契约。

新业务包按需要组织：

text

com.artd.system.<feature>/
├── controller/
├── dto/
├── vo/
├── domain/entity/
├── domain/model/
├── mapper/
└── service/

XML 放在 art-system/src/main/resources/mapper/<feature>/，共享 SQL 片段放 fragments/*Sql.xml，只声明 sql 片段。无需预建没有实际职责的 api、spi 或配置类。

4. 完成用例与事务

Controller 处理 HTTP、校验、权限和 R.ok 包装；Service 实现完整业务流程和事务；Mapper/XML 处理 SQL。

涉及多表写入，明确原子边界、锁顺序和重复提交。调用外部支付、存储等服务时区分本地事务与外部动作，设计恢复路径。避免事务方法提取后变为自调用而使代理失效。

跨域使用公开 api/spi，不直接写对方表或调用内部 Mapper。缓存写入后复用提交后失效机制。

5. 补齐权限和前端

新增 Controller 权限声明、接口目录、菜单按钮、目标角色及超级管理员授权。需要数据范围时在对应查询和写操作中落实，不能只给列表加过滤。

在共享前端同步接口类型、请求封装、页面、菜单组件路径与按钮声明。接口版本号按本业务定义，不批量改造既有路径。

6. 选择验证

普通规则覆盖成功、关键边界和拒绝场景。涉及 SQL、数据库锁、迁移、完整登录或存储时，使用隔离集成验证。

bash

./mvnw -pl art-modules/art-system -am test
./mvnw spotless:check checkstyle:check pmd:check
node scripts/integration.mjs clean

不必每次盲目执行全部测试，按影响选择；具体命令与环境见 AI 协作开发。集成脚本创建一次性依赖，不指向客户库。

交付前核对

接口、模型、Mapper/XML、迁移、菜单权限与前端调用保持一致；文档说明新增能力的配置和使用步骤。使用普通账号验证权限边界，保留客户配置和历史数据。

给 AI 的任务应附上上述参考链路、目标范围与验收条件，而非仅写“照现有项目生成一套代码”。

扩展开发 ​

1. 明确业务与变更范围 ​

2. 以当前真实用例作为参考 ​

跟读一次已有的列表查询 ​

3. 定义数据与接口模型 ​

4. 完成用例与事务 ​

5. 补齐权限和前端 ​

6. 选择验证 ​

交付前核对 ​