# Backend 现状梳理

## 1. 文档目的

本文档用于帮助项目成员快速理解当前引入的后端子模块 `backend/` 的整体技术现状、模块结构、与本项目业务设计的对应关系，以及当前可确认的边界与待进一步核实的事项。

## 2. 当前后端来源与状态

- 子模块路径：`backend/`
- 仓库地址：`ssh://git@gitea.devops.1msoft.cn:12224/emsoft-IF/sw-system-cloud.git`
- 当前分支：`develop`
- 当前提交：`be71df0a1efc1d778fdfb337032993259943c1f7`

说明：
- 当前已作为 Git submodule 正常加入本仓库。
- 该后端仓库存在一个上游遗留的嵌套 submodule 异常路径：`infra/converter/markdown-converter-service-standalone`。
- 该异常目前不影响代码浏览和结构分析，但可能影响部分递归 submodule 命令。

## 3. 总体技术架构判断

根据 `backend/pom.xml` 与 `backend/README.md`，当前后端是一个基于 **Spring Cloud Alibaba** 的 Maven 多模块微服务系统，而非单体应用。

### 3.1 核心技术栈

- Java 17
- Spring Boot 3.4.5
- Spring Cloud Alibaba 2023.0.1
- Nacos（注册中心、配置中心）
- Spring Cloud Gateway
- MyBatis Plus
- Redis + Redisson
- Spring Security
- XXL-Job
- RocketMQ / Kafka / RabbitMQ（按模块选配）
- Flowable（工作流）
- PF4J（IoT 插件机制）

### 3.2 总体结构特征

该后端更像“**微服务底座 + 通用平台模块 + 行业业务模块**”的组合：

- 底座层负责依赖、框架、网关、启动装配。
- 通用模块负责系统管理、基础设施、流程、支付、报表、AI、IoT 等能力。
- 行业业务模块负责水务营收与银行代收等业务。

## 4. 顶层模块结构

根据 `backend/pom.xml`，当前顶层聚合模块包括：

1. `sw-dependencies`
2. `sw-gateway`
3. `sw-framework`
4. `sw-server`
5. `sw-module-system`
6. `sw-module-infra`
7. `sw-module-bpm`
8. `sw-module-pay`
9. `sw-module-report`
10. `sw-module-ai`
11. `sw-module-iot`
12. `sw-business`
13. `sw-business-bank`

## 5. 顶层模块职责简述

### 5.1 基础底座层

#### `sw-dependencies`
- Maven 依赖版本管理中心（BOM）。
- 统一管理各模块依赖版本。

#### `sw-framework`
- 框架公共能力层。
- 预计封装 Web、安全、租户、数据权限、MyBatis、Redis、RPC 等基础能力。

#### `sw-gateway`
- 微服务统一入口。
- 负责网关路由、鉴权、过滤等能力。

#### `sw-server`
- 服务启动与装配层。
- README 中定义为“管理后台 + 用户 APP 的服务端”。

### 5.2 平台通用能力层

#### `sw-module-system`
- 系统功能模块。
- 包括用户、角色、菜单、部门、岗位、租户、字典、通知、日志等。

#### `sw-module-infra`
- 基础设施模块。
- 包括代码生成、接口文档、数据库文档、配置管理、文件服务、定时任务、API 日志、监控等。

#### `sw-module-bpm`
- 工作流模块。
- 基于 Flowable，承接审批流、表单、任务、抄送、驳回、会签等能力。

#### `sw-module-pay`
- 支付模块。
- 包括支付订单、退款订单、回调通知、支付接入等能力。

#### `sw-module-report`
- 报表与大屏模块。
- 包括报表设计器、大屏设计器。

#### `sw-module-ai`
- AI 模块。
- 当前与营收主流程关联度相对较低。

#### `sw-module-iot`
- 物联网模块。
- 与远传水表、厂家协议、设备接入、集抄平台等方向高度相关。

### 5.3 行业业务层

#### `sw-business`
- 水务业务模块。
- 是当前最值得重点分析的行业核心模块。

#### `sw-business-bank`
- 多银行代收模块。
- 与银行代扣、托收、送盘、银行报文处理相关。

## 6. 重点模块下钻结果

## 6.1 `sw-business` 结构

`sw-business` 包含两个子模块：

- `sw-business-api`
- `sw-business-server`

### `sw-business-api`
定位：业务 API / DTO / Feign 契约层。

主要特征：
- 依赖 `sw-common`
- 支持参数校验
- 支持 OpenFeign
- 提供 OpenAPI 文档模型支持

判断：
- 主要承载对外接口定义、DTO/VO、服务间调用契约。
- 不直接作为运行服务。

### `sw-business-server`
定位：水务业务服务实现层。

主要依赖：
- `sw-module-system-api`
- `sw-module-infra-api`
- `sw-business-api`
- `sw-business-bank-api`（provided）
- `sw-module-bpm-api`

技术能力：
- Web
- Security
- MyBatis
- Redis
- RPC
- Nacos 注册/配置
- Job
- MQ
- Monitor

判断：
- 这是当前水务营收业务的核心服务实现模块。
- 大概率承载客户、表务、抄表、账务、工单等业务逻辑。
- 与银行代收和流程模块均存在集成关系。

## 6.2 `sw-business-bank` 结构

`sw-business-bank` 包含两个子模块：

- `sw-business-bank-api`
- `sw-business-bank-server`

### `sw-business-bank-api`
定位：银行业务 API 契约层。

主要特征：
- 依赖 `sw-common`
- 支持参数校验
- 支持 OpenFeign
- 支持 OpenAPI 文档模型

判断：
- 主要用于银行代收、托收等服务间调用契约。

### `sw-business-bank-server`
定位：多银行代收服务实现层。

主要依赖：
- `sw-module-system-api`
- `sw-module-infra-api`
- `sw-business-bank-api`
- `sw-business-api`

技术能力：
- Web
- Security
- MyBatis
- Redis
- RPC
- Nacos
- Job
- MQ
- Monitor
- 国密算法支持（SM2/SM4）

判断：
- 这是一个独立的银行业务服务。
- 很可能承载托收、代扣、送盘、回盘、银行接口报文处理。
- 与 `sw-business` 存在双向协同关系。

## 6.3 `sw-module-iot` 结构

`sw-module-iot` 包含三个子模块：

- `sw-module-iot-api`
- `sw-module-iot-biz`
- `sw-module-iot-plugins`

### `sw-module-iot-api`
定位：IoT API 与插件扩展接口层。

主要特征：
- 依赖 `sw-common`
- 引入 `pf4j-spring`
- 提供 IoT 插件机制的接口抽象

判断：
- 不只是普通 API 层，还承担插件扩展点定义职责。

### `sw-module-iot-biz`
定位：IoT 业务主服务层。

POM 描述明确提到：
- 产品管理
- 设备管理
- 协议管理

主要技术能力：
- Web / Security
- MyBatis / Redis
- RPC
- Nacos
- Job
- MQ
- Quartz
- PF4J
- Groovy / GraalVM JS ScriptEngine
- 可选 RocketMQ / Kafka / RabbitMQ
- 额外依赖 `taos-jdbcdriver`

判断：
- 这是一个较重的 IoT 业务中台模块。
- 不只是设备台账，还可能包含协议接入、规则执行、消息桥接、动态脚本处理等能力。
- 对“远传水表、集抄平台、厂家协议、水表数据交互”场景具有直接参考价值。

### `sw-module-iot-plugins`
定位：IoT 插件聚合层。

包含四个插件子模块：
- `sw-module-iot-plugin-common`
- `sw-module-iot-plugin-http`
- `sw-module-iot-plugin-mqtt`
- `sw-module-iot-plugin-emqx`

#### `sw-module-iot-plugin-common`
- 插件公共能力层。
- 提供 Web、Vertx、校验等共通依赖。

#### `sw-module-iot-plugin-http`
- HTTP 协议插件。
- 插件主类：`IotHttpVertxPlugin`
- 支持插件包与 standalone 打包。

#### `sw-module-iot-plugin-mqtt`
- MQTT 协议插件。
- 插件主类：`MqttPlugin`
- 依赖 `vertx-mqtt`。

#### `sw-module-iot-plugin-emqx`
- EMQX 专用插件。
- 插件主类：`IotEmqxPlugin`
- 说明系统不仅支持通用 MQTT，也对 EMQX 做了专门适配。

判断：
- `sw-module-iot` 采用了明显的可插拔协议接入架构。
- 适合对接多厂家、多协议、多接入方式的物联网设备场景。

## 7. 与当前福建水务营收文档的映射关系

结合本项目已有文档结构，可以先建立如下对应关系：

### 7.1 营收主业务
优先对应模块：
- `sw-business-server`
- `sw-business-api`

可能映射章节：
- 客户资料管理
- 抄表开账
- 营业收费
- 账务处理
- 工单办理
- 部分表务相关业务

### 7.2 银行代收与托收业务
优先对应模块：
- `sw-business-bank-server`
- `sw-business-bank-api`

可能映射章节：
- 代收业务
- 银行接口
- 托收代扣
- 送盘/回盘

### 7.3 远传表 / 物联网 / 集抄接入
优先对应模块：
- `sw-module-iot-biz`
- `sw-module-iot-api`
- `sw-module-iot-plugin-http`
- `sw-module-iot-plugin-mqtt`
- `sw-module-iot-plugin-emqx`

可能映射章节：
- 物联网平台
- 集抄平台
- 厂家设备信息管理
- 水表数据交互接口
- 水表用户同步接口

### 7.4 支付与退款
优先对应模块：
- `sw-module-pay`

可能映射章节：
- 在线缴费
- 柜面扫码支付
- 支付订单与退款

### 7.5 流程审批与工单流转
优先对应模块：
- `sw-module-bpm`

可能映射章节：
- 业务工单
- 报装流程
- 审批流相关能力

## 8. 当前能确认的现状结论

### 8.1 已确认

1. 当前后端是微服务多模块架构，不是单体应用。
2. 已具备较完整的通用平台底座能力：系统、基础设施、流程、支付、报表。
3. 已存在明确的水务业务模块：`sw-business`。
4. 已存在明确的银行业务模块：`sw-business-bank`。
5. 已存在明确的 IoT 模块，并且采用插件化协议接入架构。
6. IoT 模块对远传水表、集抄平台、厂家协议接入场景具备较高相关性。

### 8.2 尚未完全确认

以下内容目前还只是根据模块命名、POM 依赖与 README 做出的结构判断，尚未下钻到具体 Java 包、Controller、Service、Mapper 层：

1. `sw-business-server` 内是否已经完整实现：
   - 客户资料
   - 抄表开账
   - 营业收费
   - 账务处理
   - 发票管理
   - 催缴管理
   - 工单办理

2. `sw-business-bank-server` 内是否已经完整实现：
   - 银行托收
   - 银行代扣
   - 送盘/回盘
   - 对账
   - 国密报文交互

3. `sw-module-iot-biz` 内是否已经完整实现：
   - 产品管理
   - 设备台账
   - 协议管理
   - 厂家适配
   - 数据桥接与规则执行

## 9. 当前后端分析的限制

1. 当前仅完成了模块级与 POM 级分析，尚未做代码包级逐层拆解。
2. 当前未完成运行验证，尚未确认各服务启动配置与部署方式。
3. 当前未完成数据库脚本与后端实体/Mapper 的逐项映射。
4. 当前未完成接口清单与文档章节的逐条绑定。

## 10. 建议的下一步分析顺序

为了更高效支撑本项目设计文档，建议后续按以下顺序继续下钻：

### 第一阶段：业务代码结构分析

优先分析：
1. `sw-business-server`
2. `sw-business-bank-server`
3. `sw-module-iot-biz`

目标：
- 找到 Controller / Service / Mapper / DO / VO 的实际结构
- 确认是否已有“客户、抄表、账单、收费、工单、托收、设备”对应实现

### 第二阶段：数据库与代码映射

目标：
- 对照 `sql/lhc_数据库设计.md`
- 对照 `docs/design/04_Appendix/Archive/05_Data_Dictionary/营收数据字典.md`
- 找出已实现表、未实现表、后端已有但文档未覆盖的对象

### 第三阶段：接口与文档映射

目标：
- 对照接口设计文档
- 对照物联网接口规范附件
- 确认后端已有接口、待补接口、历史遗留接口

## 11. 当前建议的阅读重点

如果只想快速建立对后端系统的认识，建议优先关注：

1. `backend/pom.xml`
2. `backend/sw-business/sw-business-server`
3. `backend/sw-business-bank/sw-business-bank-server`
4. `backend/sw-module-iot/sw-module-iot-biz`
5. `backend/sw-module-iot/sw-module-iot-plugins`

## 12. 一句话结论

当前 `backend` 后端系统的现状可以概括为：

> 它已经具备较完整的微服务底座与通用平台能力，并且明确拆分出了水务业务、银行代收、IoT 设备接入三条与本项目高度相关的业务线；但目前我们对其理解仍停留在模块结构层，尚需进一步下钻代码包结构、数据库映射和接口实现，才能形成可直接落地到本项目设计文档的精确结论。

## 13. 相关延伸文档

- 真实表清单与数据字典映射：`docs/guides/BACKEND_TABLE_MAPPING.md`