# abacus.base.demo

是前后端分离的基于 Spring Boot 的基础项目，作为使用 agent 应用开发前后端项目的**基础模板**。本项目自身不包含业务 Java 代码，业务能力由 abacus 框架（`abacus.config`、`abacus.commons`、`abacus.fundation`、`abacus.business.service` 等）提供，开发者/agent 在本模板上添加业务模块即可。



## 技术栈

| 项 | 说明 |
| --- | --- |
| 构建 | Maven，父工程 `abacus.framework:abacus.springcloud.pom:1.5.0` |
| 框架 | Spring Boot + abacus 系列框架（配置、通用、基础、业务服务） |
| 注册/配置中心 | Nacos（见 `bootstrap.yml`） |
| 数据库 | MySQL / SQL Server / Oracle / 达梦，Druid 连接池 + JPA |
| 定时任务 | XXL-JOB（`application-xxljob.yml`） |
| 消息队列 | Kafka |
| 接口文档 | springdoc（OpenAPI） |
| 监控 | Spring Actuator + Prometheus |

## 目录结构

```
abacus.base.demo/
├── pom.xml                        # Maven 构建配置：依赖、多环境 profile(dev/test/prod)、打包插件
├── assembly.xml                   # Maven 发布包(zip)打包规则：jar + doc + sql + html
├── .project / .classpath          # Eclipse IDE 工程配置（Java + Maven 项目）
├── .settings/                     # Eclipse 偏好配置（编码、JDK、m2e）
├── src/
│   └── main/
│       ├── java/                  # 【业务代码目录】Java 源码（当前为空，新增业务代码放这里）
│       ├── resources/
│       │   ├── config/
│       │   │   ├── dev/           # dev 环境配置（Maven profile 默认激活）
│       │   │   │   ├── application.yml          # 主配置：端口、数据源、JPA、Druid、Kafka、springdoc、abacus 扫描路径等
│       │   │   │   ├── bootstrap.yml            # 启动引导配置：应用名、Nacos 注册中心/配置中心
│       │   │   │   ├── application-xxljob.yml   # XXL-JOB 调度中心与执行器配置
│       │   │   │   ├── logback-spring.xml       # 应用日志配置
│       │   │   │   └── logback-access.xml       # 访问日志配置
│       │   │   ├── test/          # test 环境配置（与 dev 文件同名同结构）
│       │   │   └── prod/          # prod 环境配置（与 dev 文件同名同结构）
│       │   ├── doc/
│       │   │   └── 升级日志.md     # 版本升级日志，按版本记录更新说明
│       │   ├── sql/
│       │   │   ├── table/
│       │   │   │   ├── mysql.sql         # MySQL 建表 DDL（示例表 example_category）
│       │   │   │   └── sqlserver.sql     # SQL Server 建表 DDL（与 mysql.sql 对应）
│       │   │   ├── data/
│       │   │   │   └── sqlserver.sql     # 初始化数据（acas 子系统/菜单/模块注册）
│       │   │   └── upgrade.xml           # 数据库版本升级 SQL 配置（按版本号执行，支持多库语法翻译）
│       │   ├── vue/              # 【Vue 项目源码目录】存放 vue 项目，映射过来的，前后端分离（当前为空）
│       │   └── html/             # 【前端构建产物目录】存放 vue 项目编译后的 html 等静态资源（当前为空，由 assembly.xml 打入发布包）
│       └── (META-INF)            # 若存在，会按 pom.xml 配置打入发布包
└── target/                       # Maven 构建输出目录（编译产物、打包 zip，可忽略/删除）
```

## 关键配置说明（agent 开发时必须了解）

### 1. pom.xml
- 多环境 profile：`dev`（默认）/ `test` / `prod`，通过 `-P` 指定，决定加载 `src/main/resources/config/<env>/` 下的配置。
- 打包资源：仅打包 `META-INF`、当前环境 config 目录、`sql/**` 到 jar 内；`doc`、`sql`、`html` 通过 `assembly.xml` 额外打入 zip 发布包。
- 发布包：`mvn package` 生成 `${artifactId}-${version}-bin.zip`（含 jar + doc + sql + html）。

### 2. application.yml（以 dev 为例，三个环境结构一致）
- `server.port`：服务端口（示例 9003）。
- `spring.datasource`：Druid 数据源；`enableMultiSource` 可开启多数据源（`multidb0~multidb9` 预设 10 个），含 `defaultDB` 默认库、`readDB` 读库、`dynamicRelation` 业务路由配置。
- `spring.jpa`：JPA/Hibernate 配置，命名策略使用框架的 `LowercaseNamingStrategyStandardImpl`。
- `spring.kafka`：Kafka 生产/消费配置。
- `springdoc.packages-to-scan`：在线接口文档扫描的包路径。
- `abacus.controllerPackages` / `abacus.entitypackages`：**框架扫描 Controller 与实体的包路径，新增业务代码必须将包名加入此配置**（示例包前缀 `abacus.springboot.example`）。
- `abacus.responseExcludePath`：不被统一响应体包装器拦截的 URI。
- `management.endpoints.web.base-path`：Actuator 端点基础路径（`/services/actuator`）。

### 3. bootstrap.yml
- `spring.application.name`：应用名（示例 `example`），Nacos 中需唯一。
- `spring.cloud.nacos`：Nacos 服务地址、账号、命名空间；通过 `extension-configs` 引入公共配置（`abacus-discovery.yml`、`abacus-acas.yml`、`abacus-redis.yml` 等）。

### 4. sql/ 目录
- `table/`：建表 DDL，按数据库分文件（mysql.sql / sqlserver.sql），新建业务表需同步维护两个文件。
- `data/`：初始化数据（子系统、菜单、模块注册，依赖 acas 框架）。
- `upgrade.xml`：版本化升级 SQL，`<upgrade version="yyyy-MM-dd[.count]">` 按版本升序执行；`translator="true"` 时以 SQL Server 语法编写，由框架翻译到各数据库。

## 给 agent 的开发约定

1. **新增 Java 代码**：放入 `src/main/java`，包名建议以 `abacus.springboot.应用名.*` 为前缀（保持框架扫描配置一致，或同步修改 `application.yml` 中 `abacus.controllerPackages` / `springdoc.packages-to-scan` / `abacus.entitypackages`）。
2. **新增前端 Vue 项目**：Vue 源码放在 `src/main/resources/vue/`，构建（编译）产物输出到 `src/main/resources/html/`，由 `assembly.xml` 自动打入发布包。
3. **新增配置项**：优先写入 `src/main/resources/config/<env>/application.yml` 对应环境，环境间保持字段一致。
4. **数据库变更**：建表写 `sql/table/`，历史变更写 `sql/upgrade.xml`，初始化数据写 `sql/data/`。
5. **文档与日志**：功能更新记录到 `src/main/resources/doc/升级日志.md`。
6. **打包产物**：`target/` 目录为构建输出，无需维护；发布包为 `target/*-bin.zip`。
7. **多环境配置**：修改配置时需同步 `dev` / `test` / `prod` 三个目录（或按需仅改某环境）。
8. **pom.xml**：`<artifactId></artifactId>`建议以`abacus.springboot.应用名`设置