tangweijie/fujian_water_biz_doc
1
0
Fork 0
Code Issues Pull Requests 12 Actions Packages Projects Releases 1 Wiki Activity
fujian_water_biz_doc/docs/guides/BACKEND_CURRENT_STATUS.md

12 KiB
Raw Blame History

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