项目结构
Art Design Pro X Java 采用 Maven 多模块组织工程：art-admin 启动应用，art-common 提供公共技术能力，art-system 按业务域组织功能。下面保留主要目录和少量关键文件，便于快速建立工程全貌。
第一次阅读先看这几处
- 只想启动：看根目录
README.md、config/和scripts/dev.mjs。 - 想理解入口：看
art-admin的ArtDesignApplication.java。 - 想修改业务：在
art-system找到对应域的 Controller，再追踪 Service 和 Mapper。 - 想改表或默认权限：看
art-admin/src/main/resources/db/migration/，新增迁移。
不需要按目录从头读完。下文目录树用于查位置，实际开发从一个具体请求开始更容易理解。
整体工程结构
从 art-design-pro-x-java 根目录打开项目并导入 pom.xml。配套前端独立位于 art-design-pro-x-ui。
art-design-pro-x-java/
├── art-admin/ # 应用入口与装配
├── art-common/ # 公共技术模块
│ ├── art-common-core/ # 响应、分页、异常与基础工具
│ ├── art-common-web/ # Web 配置与统一异常处理
│ ├── art-common-mybatis/ # MyBatis-Plus 与分页适配
│ ├── art-common-redis/ # Redis、缓存与环境隔离
│ ├── art-common-oss/ # 本地、MinIO、阿里云 OSS
│ ├── art-common-doc/ # OpenAPI 配置
│ └── art-common-test/ # 公共测试工具
├── art-modules/ # 业务模块目录
│ └── art-system/ # 系统与业务功能
├── config/ # 客户外置应用 YAML
├── deploy/ # 客户 Docker 配置
├── scripts/ # 启动、部署与验证脚本
├── docs/guides/ # 随源码交付的专题说明
├── skills/ # Java 开发与 AI 协作技能
├── .vscode/ # 调试与编辑器配置
├── .mvn/wrapper/ # Maven Wrapper
├── docker-compose.yml # 生产公共 Compose 定义
├── docker-compose.dev.yml # 开发数据服务定义
├── Dockerfile # 应用镜像构建
├── pom.xml # 模块、依赖版本与构建插件
├── mvnw # Linux / macOS Maven 入口
├── mvnw.cmd # Windows Maven 入口
├── checkstyle.xml # 代码规范检查
├── pmd-ruleset.xml # 静态检查规则
├── AGENTS.md # 开发约定
├── PRODUCT.md # 能力与交付边界
└── README.md # 启动与部署说明最终由 art-admin 组合应用并产出可执行 JAR。当前业务位于一个 Maven 模块 art-system，内部按领域分包，业务包不分别部署。
启动与配置：art-admin
负责应用启动、Spring 装配、安全拦截器和安装配置工具。日常业务规则放在所属业务域。
art-admin/
├── src/main/
│ ├── java/com/artd/
│ │ ├── ArtDesignApplication.java # Spring Boot 启动入口
│ │ └── admin/
│ │ ├── config/ # 安全、调度与运行环境装配
│ │ └── deployment/ # 配置初始化、检查与 Compose 生成
│ └── resources/
│ ├── application.yml # 公共默认配置
│ ├── application-dev.yml # 开发环境默认值
│ ├── application-prod.yml # 生产环境默认值
│ ├── META-INF/ # 环境处理器与配置元数据
│ └── db/migration/ # Flyway 初始化与升级
├── src/test/ # 配置、架构与整应用集成测试
└── pom.xml # 可执行应用依赖包内配置随产品发布；客户连接信息与密钥填写根目录 config/application-dev.yml 或 config/application-prod.yml。实际 YAML 不进入 JAR 和镜像，具体加载方式见 应用配置。
公共能力：art-common
公共模块供各业务域复用，不反向依赖业务实现。art-common-test 仅用于测试依赖。
| 模块 | 常用内容 |
|---|---|
art-common-core | R 统一响应、PageResult 分页、业务异常、日志注解、日期与 ID 工具 |
art-common-web | CORS、全局异常处理、客户端地址解析 |
art-common-mybatis | ORM 配置、BaseEntity、公共字段填充、分页结果转换 |
art-common-redis | Redis 序列化、键空间、命名空间缓存与失效 |
art-common-oss | FileStorage 契约及本地、MinIO、阿里云适配 |
art-common-doc | SpringDoc / OpenAPI 配置 |
art-common-test | 接口契约提取、Mapper XML 测试辅助 |
需要修改公共能力时，先确认是否影响多个业务域。响应、日期、分页等约定见 接口设计，依赖边界见 系统架构。
业务目录：art-system
业务 Java 路径为 art-modules/art-system/src/main/java/com/artd/system/。
com/artd/system/
├── access/ # 用户、角色、部门、岗位与授权
├── auth/ # 登录、注册、验证码与刷新会话
├── menu/ # 菜单、按钮与前端路由
├── settings/ # 字典、参数与站点配置
├── files/ # 文件、目录、授权与回收恢复
├── notifications/ # 通知、收件箱与实时推送
├── content/ # 内容、分类、标签与回收站
├── feedback/ # 反馈提交与处理
├── audit/ # 操作日志、登录日志与安全事件
├── monitor/ # 服务器、在线用户与缓存监控
├── tasks/ # 任务定义、调度、执行与日志
├── workflow/ # Flowable 审批、表单、版本与附件
├── mall/ # 商品、库存、订单、支付与售后
├── aiassistant/ # 模型代理与 AI 流式回复
├── crypto/ # 密码加密、公钥与安全配置
└── cache/ # 业务缓存命名与可管理空间业务包内部如何组织
以 settings 为例，其他业务域按实际需要保留相应目录：
settings/
├── controller/ # HTTP 入口、校验与响应包装
├── dto/ # 请求参数与校验规则
├── vo/ # 接口响应模型
├── domain/ # 查询投影与写入模型
├── service/ # 业务用例、事务与模型转换
├── mapper/ # 数据访问接口
├── security/ # 域内权限常量
├── api/ # 供其他业务域调用的公开端口
└── compat/ # 兼容适配域内调用沿 Controller → Service → Mapper/XML 展开。跨域协作通过 api / spi；有后台任务或框架集成的业务域还会包含 task、config 等目录。普通 CRUD 可使用一个 Service，复杂用例按实际职责拆分。
各域的重点入口和业务边界见 业务模块地图，新增功能步骤见 扩展开发。
数据资源与测试
Mapper XML 与接口按业务域对应，数据库结构与默认数据统一由 Flyway 管理。
art-modules/art-system/src/main/resources/
└── mapper/ # 按业务域组织 SQL
├── access/ # 账号、组织与授权
│ └── fragments/ # 共享数据范围 SQL 片段
├── settings/ # 字典、参数与站点配置
├── files/ # 文件资产与业务引用
├── workflow/ # 流程、版本、实例与任务
├── mall/ # 商品、库存、订单与支付
└── ... # 其他业务域的 Mapper XML
art-admin/src/main/resources/db/migration/
├── V1__init_schema.sql # 系统底座表结构
├── V2__init_data.sql # 初始账号、配置与授权
├── V3__init_workflow.sql # 审批与 Flowable 引擎
├── V4__init_mall.sql # 商城与交易能力
└── README.md # 初始化、升级与裁剪约定不是每个 Mapper 都需要 XML，具体实现也可使用 MyBatis-Plus 或注解 SQL。已发布迁移保持不变，新变更增加更高版本脚本，详见 数据库初始化与升级。
| 测试位置 | 验证内容 |
|---|---|
art-common/*/src/test | 公共技术能力 |
art-system/src/test/java（业务模块内） | 业务规则、接口、权限与引擎行为 |
art-system/src/test/resources（业务模块内） | 商城、审批接口目录与审计契约 |
art-admin/src/test/java/com/artd/admin | 架构边界、装配、配置与部署工具 |
art-admin/src/test/java/com/artd/integration | 真实依赖与完整 HTTP 链路 |
art-admin/src/test/resources/contracts | 权限目录、数据范围与角色快照 |
启动、部署与验证脚本
以下脚本位于后端根目录 scripts/：
scripts/
├── dev.mjs # 构建模块并启动本地 Java
├── deploy.sh # 数据服务、生产初始化与更新
├── integration.mjs # 隔离依赖与 HTTP 集成验证
├── deploy.integration.mjs # 生产部署方案验收
├── deploy.dev.integration.mjs # 开发启动方案验收
├── check-identity.mjs # 账号与认证契约核对
├── check-file.mjs # 文件契约核对
├── check-workflow.mjs # 审批契约核对
└── check-mall.mjs # 商城契约核对契约核对脚本需要相应参考仓库和 Node 依赖，不属于客户启动 Java 的必要步骤。命令和验证选择见 AI 协作开发。
常见需求对应入口
| 需求 | 优先查看 |
|---|---|
| 登录、刷新、验证码异常 | auth、crypto 与会话校验 |
| 菜单或按钮不显示 | menu、access 与前端组件映射 |
| 修改站点、字典和参数 | settings |
| 文件访问或存储问题 | files 与 art-common-oss |
| 修改审批规则 | workflow 的校验、编译与任务用例 |
| 修改库存、订单或支付 | mall 对应业务 Service、Mapper 与任务 |
| 新增后台处理任务 | tasks/spi 与所属业务域 task |
| 配置模型或排查流式回复 | aiassistant 与网关配置 |
| 连接、端口或部署配置 | 根目录 config、deploy 与 art-admin |
阅读一个接口时，从 Controller 和 DTO/VO 开始，再追踪 Service、Mapper/XML 和测试。交给 AI 修改前，先读取 AGENTS.md、PRODUCT.md 与对应主题，明确范围和验收要求。