energy-manage-healthcheck/MIGRATION.md

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

将原 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 等。

五、构建

# 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 运行

# 平台服务
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 侧数据，本机无法在超时内完成， 属该测试接口的运行前提问题，与服务装配无关。