# 风电机组健康体检平台 —— 服务拆分说明

将原 `energy-manage-service` 单服务按业务边界拆分为两个 Maven 工程：

| 工程 | 职责 | 构建产物 |
|---|---|---|
| `energy-manage-platform/energy-manage-service` | 风电场主数据与平台管理能力 | `energy-manage-service.jar`（Spring Boot 可执行包） |
| `energy-manage-healthcheck` | 风电机组健康体检（分析）能力 | `energy-manage-healthcheck.jar`（Spring Boot 可执行包） |
| `energy-manage-platform/energy-manage-common` | 两个服务共享的 PO / 基础能力 | `energy-manage-common-1.0.0-SNAPSHOT.jar` |

---

## 一、保留在 energy-manage-service 的内容

按 mybatis 目录口径保留的 10 个业务模块，及其对应的实体（PO）、controller、mappers、service：

`anemometertower`、`area`、`company`、`dict`、`system`、`units`、
`windenginegroup`、`windenginemill`、`windfield`、`windrelation`

同时保留这些模块被引用到的**周边代码**（否则无法编译运行）：

- `controller/powerwordcontract`、`controller/powerwordcriterion`、`service/powerword*`、
  `mappers/powerword*`：`WindFieldContractServiceImpl` 反向依赖合同管理，且合同/准则属于平台侧主数据。
- `service/kafka/producer`、`mappers/windexceptioncount`、`resources/mybatis/windexceptioncount`：
  `SysRolePermissionController` 需要 Kafka 发送能力；`WindEngineGroupServiceImpl` 需要按批次查询异常机组。

**调整点（1 处）**：`WindEngineGroupServiceImpl` 原来通过 `AnalysisErrService.AnalysisErrorCodeQuery(batchCode)`
获取异常机组，拆分后分析侧已不属于本工程，改为直接调用本工程内的 `WindExceptionCountMapper.selectExceptionCountBybatchCode(batchCode)`
（同一条 SQL，语义不变）。

## 二、迁移到 energy-manage-healthcheck 的内容

- **controller**：`analysis`、`analysiscomment`、`analysispriority`、`analysisresultreport`、`chartsdata`、
  `datatransfer`、`datatransfertype`、`homepage`、`wavedatatransfer`、`wavedic`、`windfieldbatch`（批次导入/查询属分析场景）、
  `base`(共享基类)、`UploadController`、`SysTestController`
- **service**：`analysis`、`analysiscomment`、`analysispriority`、`autoanalysisconfig`、`chartsdata`、
  `datatransfer`、`datatransfertype`、`homepage`、`wavedatatransfer`、`wavedic`、`windfieldbatch`、
  `vibration`(SKF 振动数据)、`kafka`（消费者 + 生产者）
- **mappers + mybatis XML**：`analysis`、`analysisdatarelationrecords`、`analysispriorityrecords`、
  `autoanalysisconfigdetail(optionrecords/relations)`、`chartsdata`、`datatransfer(history/type)`、
  `detectionpointdic`、`wavedatatransfer(history)`、`windexceptioncount`
- **task**：`AnalysisTask`、`AutoAnalysisTask`、`SkfVibrationDataTask`（xxl-job 定时任务）
- **domain**：完整的 `domain/dto`、`domain/vo`、`domain/client`（分析算法、报表、波形、SKF 等全部 DTO/VO）

## 三、为支撑拆分而共享到 energy-manage-common 的内容

这些类被两个服务同时使用，放在 common 中避免重复实现：

| 类 | 原位置 | 新位置 |
|---|---|---|
| `CacheService` / `CacheServiceImpl` | `service.service.cache` | `common.service.cache` |
| `AlgorithmProperties` | `service.property.analysis` | `common.property.analysis` |
| `AnalysisTypeConfig` | `service.config` | `common.config` |
| `AnalysisConstants` / `AnalysisStatusConstants` | `service.constant.analysis` | `common.constant.analysis` |

两个服务的 Mapper 继续复用 `common` 中的全部 PO（`com.energy.manage.common.po`），
`mybatis.type-aliases-package` 保持指向 `com.energy.manage.common.po` 不变。

## 四、healthcheck 的 Spring Boot / Swagger 配置

- 启动类：`com.energy.manage.service.HealthCheckApplication`
  - `@SpringBootApplication`、`@MapperScan("com.energy.manage.service.mappers")`
  - `@ComponentScan({"com.energy.manage.service", "com.energy.manage.common"})`（后者用于装配迁移到 common 的 `CacheServiceImpl` 等）
  - `@ForestScan("com.energy.manage.service.client")`、`@EnableKafka`、`@EnableAsync`、`@EnableTransactionManagement`
- 接口文档：沿用工程原有的 **springfox 3.0.0 + knife4j 3.0.1**（含 `Knife4jConfiguration`、`SwaggerDoc`）
  - Swagger：`http://<host>:16201/energy-manage-healthcheck/swagger-ui/index.html`
  - Knife4j：`http://<host>:16201/energy-manage-healthcheck/doc.html`
- 端口/上下文：`server.port=16201`，`server.servlet.context-path=/energy-manage-healthcheck/`
- 拦截器：`LoginVerifyInterceptor` 已去掉对 `service.system`（`SysUserRoleMapper`/`SysUserRoleService`）的未使用导入，
  仅保留 JWT + Redis 校验，逻辑不变。
- 配置中心：`bootstrap.properties` 仍指向原 Nacos（同一 namespace），
  并新增 `spring.cloud.nacos.config.fail-fast=false`，Nacos 不可用时允许降级启动。
- 依赖：在 common 之外补充了 split 后暴露的 `minio 8.0.3`、`pinyin4j 2.5.1`、`spring-kafka`、`xxl-job-core 2.3.0`、
  `forest 1.5.30`、`springfox-boot-starter 3.0.0`、`knife4j-spring-boot-starter 3.0.1` 等。

## 五、构建

```powershell
# 1) 先安装公共模块到本地仓库（两个服务都依赖它）
cd E:\WorkSpace\SourceCode\backend_service_java\energy-manage\energy-manage-platform
mvn clean install -DskipTests

# 2) 健康体检服务
cd E:\WorkSpace\SourceCode\backend_service_java\energy-manage\energy-manage-healthcheck
mvn clean package -DskipTests
```

## 六、环境与运行

### 6.1 已接入的 Nacos 环境

两个服务的 `bootstrap.properties` 均指向 `106.120.102.238:28488`，namespace `79c42a7a-2c7d-4dcf-8a2c-b334271e2191`；
配置分组由 **pom 的 `profiles.active`** 决定。两个 pom 的默认 profile 均为 `datang`，
即从 Nacos 的 `datang` 组读取 `application.properties`（该组已在 Nacos 中配置，含 TiDB / Redis / MinIO / xxl-job）：

| 依赖 | 地址 |
|---|---|
| Nacos | `106.120.102.238:28488`，组 `datang` |
| MySQL(TiDB) | `106.120.102.238:16306`，库 `energy_dt` |
| Redis | `106.120.102.238:16379` |
| MinIO | `106.120.102.238:26900` |
| xxl-job admin | `106.120.102.238:21680/xxl-job-admin` |

切换环境只需换 profile，例如 `mvn -Pdev clean package` 会读 Nacos 的 `dev` 组。

### 6.2 运行

```powershell
# 平台服务
java -jar energy-manage-platform\energy-manage-service\target\energy-manage-service.jar

# 健康体检服务
java -jar energy-manage-healthcheck\target\energy-manage-healthcheck.jar
```

### 6.3 端口（同机部署已解决）

Nacos `datang` 组的 `application.properties` 中原本写有 `server.port = 16200`，**两个服务都会读到它**
且优先级高于命令行 `--server.port`（`-D`、环境变量同样无效），导致同机部署端口冲突。

处理方式（已完成）：把 `server.port` 从 Nacos 共享配置中**移除**，让端口回归各服务的本地配置：

| 服务 | 本地配置 | 端口 | 上下文 |
|---|---|---|---|
| energy-manage-service | `application.properties` 增加 `server.port = 16200` | 16200 | `/energy-manage-service/` |
| energy-manage-healthcheck | `application.properties` 已有 `server.port = 16201` | 16201 | `/energy-manage-healthcheck/` |

> Nacos 共享配置改动记录：仅删除了 `server.port = 16200` 一行，其余 41 个键（数据源 / Redis / MinIO /
> xxl-job / 分析算法参数等）逐键核对无变化。原文件已备份到
> `F:\workspace_aiagent\harness_deepseeek\migration\nacos-datang-application.properties.backup`。
> 唯一副作用是行尾符由 LF 变为 CRLF（属性文件语义等价，Java `Properties.load` 两者都支持）。
> 后续若要让健康体检服务换端口，直接改它自己的 `application.properties` 即可，Nacos 无需再动。

访问地址：

- 健康体检服务接口文档：`http://<host>:16201/energy-manage-healthcheck/doc.html`
- 平台服务接口文档：`http://<host>:16200/energy-manage-service/doc.html`

## 七、本次验证结论

| 验证项 | 结果 |
|---|---|
| `energy-manage-common` clean install | BUILD SUCCESS（106 个源文件） |
| `energy-manage-service` clean install | BUILD SUCCESS（338 个 java、18 个 mapper xml） |
| `energy-manage-healthcheck` clean package | BUILD SUCCESS（333 个 java、31 个 mapper xml） |
| 两个可执行 jar 的 `Start-Class` | `ManageAppApplication` / `HealthCheckApplication` |
| 每个 mybatis 映射文件解析（namespace、resultType/parameterType） | 全部通过：service 18 份 + healthcheck 31 份，222 处类型引用全部可解析，0 失败 |
| mapper xml 与 mapper 接口一一对应（无孤儿 XML） | 通过（原 `mybatis\windenginebatch\WindFieldBatchMapper.xml` 已归位到 healthcheck） |
| 包声明与目录一致 | 通过 |
| 迁移文件与 Git 原始版本逐字节比对 | 通过（仅保留预期的 import 调整） |
| **energy-manage-service 真实启动** | **成功**：`Started ManageAppApplication`，Tomcat 16200，doc.html 200 |
| **energy-manage-healthcheck 真实启动** | **成功**：`Started HealthCheckApplication`，读取 Nacos datang 组配置，Tomcat 16201 |
| **两个服务同机同时运行** | **成功**：16200 与 16201 同时监听，两侧 `doc.html`/`swagger-resources` 均 200 |
| 健康体检服务真实业务调用 | `POST /api/check/uploadMaterial` 返回 `{"code":200,"msg":"成功","data":["..."]}`，文件已落 MinIO |
| 登录拦截器 | 生效：无 token 访问 `v3/api-docs` 返回 `{"code":113,"msg":"请重新登陆用户"}` |
| xxl-job 任务注册 | 成功注册 `analysisTaskExecute`、`autoAnalysis`、`skfVibrationData` |

### 启动过程中发现并修复的问题

1. **`ManageAppApplication` 缺少 common 包扫描**：`CacheServiceImpl` 迁到
   `com.energy.manage.common.service.cache` 后，平台服务只扫描 `com.energy.manage.service`，
   启动报 `No qualifying bean of type '...CacheService'`。已补
   `@ComponentScan({"com.energy.manage.service", "com.energy.manage.common"})`。
   该问题只在真实启动时才会暴露，编译期发现不了。
2. **`AnalysisTypeConfig` 的 package 声明未随文件搬迁更新**：已改为
   `com.energy.manage.common.config`。
3. **平台服务 pom 增加 `datang` profile 并设为默认**，使 `profiles.active` 指向 Nacos 的 `datang` 配置分组。
4. **Nacos `datang` 组 `application.properties` 移除 `server.port = 16200`**，
   并在平台服务本地 `application.properties` 中显式声明 `server.port = 16200`，解决同机端口冲突。

> `GET /SysTestController/vibrationData`（免登录的自测接口）会去调用外部 SKF/MinIO 侧数据，本机无法在超时内完成，
> 属该测试接口的运行前提问题，与服务装配无关。