系统架构
Java 后端采用模块化单体：一个 Spring Boot 应用、一个业务数据库，业务按域分包。art-admin 组合应用，art-system 承载业务，art-common-* 提供可复用技术能力。
依赖与请求方向
模块依赖：art-admin → art-system → art-common-*
art-admin → art-common-*
请求处理：Controller → Service → Mapper / XML → MySQL
跨域协作：业务域 A → 业务域 B 的 api / spi公共模块不反向依赖业务模块。art-common-test 不进入生产依赖。包隔离用于控制修改范围，不意味着可以单独启动每个业务包。
用一个查询理解分层
以查询系统参数为例：浏览器把 current/size/keyword 发送到 Controller，SystemParamQuery 校验请求；Service 根据当前用户解析数据范围，并转换为 SystemParamFilter；Mapper/XML 使用筛选模型查询数据库，Service 组装 VO，Controller 最后包装 R。
这样 HTTP 参数变化主要在 DTO/Controller 处理，SQL 仍只依赖业务筛选条件。新增筛选时应同步核对 DTO → Service 转换 → Filter → Mapper/XML，而不是把 DTO 直接传入 Mapper。
域内分层
| 位置 | 责任 | 避免的做法 |
|---|---|---|
| Controller | HTTP 绑定、登录/权限、请求校验、响应包装 | 直接写 SQL、编排复杂事务 |
| Service | 用例、事务、业务规则、模型转换 | 返回 R，把事务藏进无边界工具类 |
| Mapper / XML | 数据读取和所属表写入 | 引用 HTTP DTO/VO，拼接用户输入的 SQL |
| DTO / VO | 请求与响应模型 | 直接暴露数据库实体 |
| domain/entity | 表映射 | 用于所有层的数据传递 |
| domain/model | 查询投影、筛选与写入命令 | 混入 Servlet 或 HTTP 响应 |
普通 CRUD 可使用一个 Service；存在独立规则、外部适配或事务职责时再拆分。不要求每个 Service 都创建接口，也不为简单功能预建一套空目录。
跨域协作
跨域只依赖对方 api / spi，不引用对方的内部 Service、Mapper、Entity 或 HTTP DTO/VO。状态由所属域写入。
- 账号域
access持有账号与角色关系，auth负责认证和会话。 - 站点配置表归
settings，商城通过公开端口读取售后须知等设置。 - 文件资产归
files，审批域决定实例及字段范围内的附件访问。 - 用户删除等扩展通过 SPI 协作，让各参与域处理自己的数据。
- 跨域装配位于
art-admin的admin/config。
事务与外部服务
数据库内多表业务由 Service 定义事务。Flowable 与业务数据源、事务管理器共用，因此审批写入与引擎命令可在同一事务中提交。
对象存储、AI 与支付渠道不参与 MySQL 本地事务。文件使用持久化恢复状态，支付使用查询/回调与幂等完成服务处理不确定结果，不能通过加一个 @Transactional 假设外部动作会随数据库回滚。
缓存与授权
业务缓存使用 Redis 命名空间与提交后失效机制。敏感接口仍按当前有效角色实时鉴权；前端权限快照与缓存不替代安全检查。详见 权限 和 缓存。
修改时保留的契约
保持路径、HTTP 方法、字段、默认值、集合顺序、错误、PATCH 空值、日期与金额语义。重构不能顺带改变查询/写入顺序、锁顺序、事务传播或外部调用时机。
已有兼容入口集中在各域 compat 中，有明确保留原因。新功能不继续依赖兼容实现；删除前核对真实调用方与测试。
架构约束见仓库 AGENTS.md，验证入口包含 FeatureArchitectureTest、MapperLayoutTest、CommonModuleBoundaryTest、BusinessWriteOwnershipTest 与 IdentityWebMvcConfigTest。不要通过放宽白名单绕过约束。