1377 lines
42 KiB
Markdown
1377 lines
42 KiB
Markdown
# FastBee IoT 设备监测报告引擎开发 Skill
|
||
|
||
> **领域背景**：公司主营业务为桥梁、建筑、边坡、隧道等结构老化与安全监测。核心监测对象为裂缝、深部位移、轴力/应力、沉降、倾角、应变、振动等工程物理量。报告引擎的目标是：基于已落库的 IoT 物模型监测数据，为单个监测设备生成专业分析报告，并支持**日报 / 周报 / 半月报 / 月报**四种周期，最终通过 Word 模板导出 `.docx`。
|
||
>
|
||
> **第一阶段范围**：根据所选设备 + 报告周期（或自定义时间范围）生成单设备分析报告。
|
||
>
|
||
> **不在第一阶段实现**：项目综合报告、多设备联合分析、AI 自动工程安全判定、在线 Word 模板编辑器。
|
||
|
||
---
|
||
|
||
# 0. 现状盘点（先读后写，禁止重复造轮子）
|
||
|
||
执行本 Skill 前，必须先认清 FastBee 当前已有什么、缺什么。下列结论已通过代码调研确认。
|
||
|
||
## 0.1 已有可复用基础设施
|
||
|
||
| 能力 | 位置 | 复用方式 |
|
||
|:---|:---|:---|
|
||
| 设备实体 | `iot_device` / `Device.java` | `Device` 含 `deviceId, serialNumber, productName, projectId, thingsModelValue` |
|
||
| 产品实体 | `iot_product` / `Product.java` | `Product` 含 `categoryId, protocolCode, thingsModelsJson` |
|
||
| 物模型 | `iot_things_model` / `ThingsModel.java` | 字段：`identifier, unit, datatype, type(1属性/2功能/3事件), isMonitor, isHistory, isChart, isCalculated(0上报/1横向计算/2纵向计算), formula, specs` |
|
||
| 项目实体 | `iot_project` / `Project.java` | `projectId, projectCode, projectName, address, startTime, endTime, projectStatus` |
|
||
| 设备日志（时序数据） | `iot_device_log` / `DeviceLog.java` | 字段：`ts, logType(1属性上报/7运算数据), logValue, deviceId, serialNumber, identity, isMonitor, mode` |
|
||
| 日志查询（MySQL） | `DeviceLogMapper.java` | `listHistory(DeviceLog)` / `selectHistoryList` / `selectMonitorList` / `selectLastReport` |
|
||
| 日志查询（TDengine） | `TDDeviceLogMapper.java` | TDengine 启用时走此 Mapper |
|
||
| 告警定义 | `iot_alert` / `Alert.java` | `alertLevel(1提醒/2轻微/3严重), status`，阈值规则在 `iot_scene`（LiteFlow） |
|
||
| OSS 上传 | `fastbee-plugs/oss` / `OssFactory.java` | `OssFactory.instance(redis).upload(byte[], path, contentType)` → `UploadResult{url, filename}` |
|
||
| Word/POI | `fastbee-common/pom.xml` | 已含 `poi-ooxml 4.1.2`；**未含** poi-tl / docx4j |
|
||
| Excel | `easyexcel-core 3.3.1` | 已含 |
|
||
| MQ | `fastbee-mq` | RocketMQ，未来异步报告任务复用 |
|
||
| Maven 父 POM | `pom.xml` | `revision=3.8.5`, Java 1.8, Spring Boot 2.5.14, `poi.version=4.1.2` |
|
||
|
||
## 0.2 关键缺失（本 Skill 要补齐的）
|
||
|
||
1. **设备分类（最重要）**：`iot_device.device_type` / `DeviceType.java` 枚举 = 连接拓扑 `{UNKNOWN, DIRECT_DEVICE, GATEWAY, CAMERA, SUB_GATEWAY}`，**不区分裂缝计/深部位移/轴力计/静力水准/振弦**。`iot_category` 是租户私有的产品分类树，只有 `categoryName` 文本、无稳定机器码，不能作为 Analyzer 路由键。
|
||
2. **报告周期**：当前无日报/周报/半月报/月报概念。
|
||
3. **报告引擎**：无 `fastbee-report` 模块、无 `ReportEngine`、无 `ReportAnalyzer`、无 `ReportRecord` 表。
|
||
4. **监测点阈值**：`iot_alert` 无阈值数值列，阈值藏在 LiteFlow `iot_scene` 规则里，报告难以直接读取结构化阈值。
|
||
5. **Java 端图表**：仅前端有 echarts；后端无 JFreeChart/XChart，无法生成 PNG 嵌入 Word。
|
||
6. **Word 模板引擎**：仅有裸 POI，无 `{{var}}` 占位符语法支持（需引入 poi-tl）。
|
||
|
||
---
|
||
|
||
# 1. Skill 目标
|
||
|
||
补齐报告能力链路：
|
||
|
||
```text
|
||
IoT 数据
|
||
↓
|
||
ReportRequest（设备 + 周期/时间范围 + 模板）
|
||
↓
|
||
ReportContext（设备/产品/物模型/监测数据/阈值）
|
||
↓
|
||
ReportAnalyzer（按 MonitorCategory 路由）
|
||
↓
|
||
AnalysisResult（统计/趋势/质量/预警/结论）
|
||
↓
|
||
ReportModel
|
||
↓
|
||
WordRenderer（poi-tl + JFreeChart）
|
||
↓
|
||
DOCX → OSS → ReportRecord
|
||
```
|
||
|
||
最终形成：
|
||
|
||
```text
|
||
IoT 数据 → Report Engine → 专业监测分析报告 (.docx)
|
||
```
|
||
|
||
---
|
||
|
||
# 2. 核心设计原则
|
||
|
||
## 2.1 Report Engine 不直接理解数据库
|
||
|
||
禁止 `ReportEngine → 直接操作 Mapper → 查询数据库 → 分析 → Word`。
|
||
|
||
推荐：
|
||
|
||
```text
|
||
数据访问层（DeviceLogMapper / ThingsModelMapper / OssFactory）
|
||
↓
|
||
ReportContext（已装配好的上下文）
|
||
↓
|
||
Analyzer（纯计算）
|
||
↓
|
||
AnalysisResult
|
||
↓
|
||
ReportModel
|
||
↓
|
||
WordRenderer
|
||
```
|
||
|
||
Report Engine 只负责报告流程编排，Analyzer 不允许自己 `@Autowired DeviceService/ProjectService` 到处查询。
|
||
|
||
## 2.2 复用优先
|
||
|
||
- OSS → 复用 `OssFactory`，禁止新写 `MinIOService/S3Service`
|
||
- 数据查询 → 复用 `DeviceLogMapper.listHistory`，禁止报告模块自己写 TDengine SQL
|
||
- Word → 基于 `poi-ooxml`（已含）+ 引入 `poi-tl`，禁止再引入 docx4j
|
||
- 图表 → 引入 `JFreeChart`（成熟、纯 Java、生成 PNG）
|
||
- 物模型/设备/产品领域对象 → 复用 `fastbee-iot-service` 现有实体，禁止新建 `ReportDevice/ReportThingsModel` 重复 DTO（除非报告场景确实需要独立 DTO）
|
||
|
||
## 2.3 单一职责与可扩展
|
||
|
||
新增设备分类只新增一个 Analyzer，不修改 `ReportEngine`、不写 `if(category==xxx)` 巨型判断。
|
||
|
||
---
|
||
|
||
# 3. 设备分类深度设计（MonitorCategory）
|
||
|
||
> 这是本 Skill 最核心的设计。**公司做桥梁/建筑老化检测，设备分类是报告分析的入口**——不同传感器（裂缝计 vs 深部位移 vs 静力水准）的分析维度、图表、结论模板完全不同，必须有稳定、机器可读的分类路由键。
|
||
|
||
## 3.1 为什么不能复用现有分类
|
||
|
||
| 现有分类 | 为什么不行 |
|
||
|:---|:---|
|
||
| `iot_device.device_type`（DeviceType 枚举） | 是连接拓扑（直连/网关/摄像头/子设备），与传感器物理量无关 |
|
||
| `iot_product.category_id` → `iot_category` | 租户私有的产品目录树，仅 `categoryName` 文本；同一类传感器在不同租户下分类名/层级可能不同；无稳定 code，不能做路由键 |
|
||
| ThingsModel `identifier` 启发式推断 | 命名不规范时误判，专业工程报告不能依赖猜测 |
|
||
|
||
## 3.2 方案：iot_product 加列 + MonitorCategoryEnum
|
||
|
||
### 3.2.1 数据库改动
|
||
|
||
```sql
|
||
-- iot_product 新增监测分类编码列（可空，兼容存量数据）
|
||
ALTER TABLE iot_product
|
||
ADD COLUMN monitor_category_code VARCHAR(64) NULL COMMENT '监测分类编码（报告引擎路由键，如 CRACK_METER）'
|
||
AFTER category_id;
|
||
|
||
-- 存量产品由后台运维或 SQL 一次性回填
|
||
-- 例：UPDATE iot_product SET monitor_category_code='CRACK_METER' WHERE product_name LIKE '%裂缝%';
|
||
```
|
||
|
||
> 不在 `iot_device` 落库：设备分类随产品走，避免冗余与不一致。设备查询时 JOIN `iot_product` 取 `monitor_category_code` 即可（DeviceMapper 已有产品关联）。
|
||
|
||
### 3.2.2 MonitorCategoryEnum
|
||
|
||
位置：`fastbee-common/src/main/java/com/fastbee/common/enums/MonitorCategory.java`
|
||
|
||
```java
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum MonitorCategory {
|
||
|
||
CRACK_METER("CRACK_METER", "裂缝计"),
|
||
DEEP_DISPLACEMENT("DEEP_DISPLACEMENT", "深部位移"),
|
||
AXIAL_FORCE("AXIAL_FORCE", "轴力/压力计"),
|
||
STATIC_LEVEL("STATIC_LEVEL", "静力水准仪"),
|
||
VIBRATING_WIRE("VIBRATING_WIRE", "振弦式采集仪"),
|
||
TILT_METER("TILT_METER", "倾角仪"),
|
||
STRAIN_GAUGE("STRAIN_GAUGE", "应变计"),
|
||
TEMPERATURE_HUMIDITY("TEMPERATURE_HUMIDITY", "温湿度"),
|
||
VIBRATION("VIBRATION", "振动/加速度"),
|
||
CUSTOM("CUSTOM", "自定义"),
|
||
UNKNOWN("UNKNOWN", "未知");
|
||
|
||
private final String code;
|
||
private final String desc;
|
||
|
||
public static MonitorCategory of(String code) {
|
||
for (MonitorCategory v : values()) {
|
||
if (v.code.equalsIgnoreCase(code)) return v;
|
||
}
|
||
return MonitorCategory.UNKNOWN;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2.3 Product 实体加字段
|
||
|
||
`Product.java` 增加：
|
||
|
||
```java
|
||
@ApiModelProperty("监测分类编码（报告引擎路由键）")
|
||
private String monitorCategoryCode;
|
||
```
|
||
|
||
### 3.2.4 MonitorCategoryResolver
|
||
|
||
位置：`fastbee-report/src/main/java/com/fastbee/report/category/MonitorCategoryResolver.java`
|
||
|
||
```java
|
||
public interface MonitorCategoryResolver {
|
||
MonitorCategory resolve(Long productId);
|
||
MonitorCategory resolveByDeviceId(Long deviceId);
|
||
}
|
||
```
|
||
|
||
实现：先查 `iot_product.monitor_category_code`；为空时返回 `UNKNOWN`（第一阶段不实现启发式回退，避免误判；后台需维护分类）。
|
||
|
||
### 3.2.5 AnalyzerFactory 按 MonitorCategory 路由
|
||
|
||
```java
|
||
public interface ReportAnalyzerFactory {
|
||
ReportAnalyzer get(MonitorCategory category);
|
||
}
|
||
```
|
||
|
||
```java
|
||
@Component
|
||
public class DefaultReportAnalyzerFactory implements ReportAnalyzerFactory {
|
||
private final List<ReportAnalyzer> analyzers;
|
||
|
||
@Override
|
||
public ReportAnalyzer get(MonitorCategory category) {
|
||
return analyzers.stream()
|
||
.filter(a -> a.supports(category))
|
||
.findFirst()
|
||
.orElseThrow(() -> new ReportException("不支持的监测分类: " + category));
|
||
}
|
||
}
|
||
```
|
||
|
||
## 3.3 与现有 iot_category 的关系
|
||
|
||
两者**正交**，互不替代：
|
||
|
||
```text
|
||
iot_category → 产品商务分类（客户买什么、目录树展示）
|
||
iot_product.monitor_category_code → 监测语义分类（如何分析数据、走哪个 Analyzer）
|
||
```
|
||
|
||
同一个产品可以：`category_id` = "桥梁监测传感器/裂缝计"（商务树）+ `monitor_category_code` = `CRACK_METER`（分析路由键）。
|
||
|
||
## 3.4 命名冲突说明
|
||
|
||
**不要**复用 `DeviceType` 这个类名——项目中已存在 `com.fastbee.iot.enums.DeviceType`（连接拓扑）。本 Skill 的分类统一叫 `MonitorCategory`，避免歧义。
|
||
|
||
---
|
||
|
||
# 4. 报告周期设计（ReportPeriod）
|
||
|
||
支持：**日报 / 周报 / 半月报 / 月报**，统一使用**自然日历窗口**（符合工程监测报告习惯）。
|
||
|
||
## 4.1 ReportPeriod 枚举
|
||
|
||
位置：`fastbee-common/src/main/java/com/fastbee/common/enums/ReportPeriod.java`
|
||
|
||
```java
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum ReportPeriod {
|
||
|
||
DAY("DAY", "日报"),
|
||
WEEK("WEEK", "周报"),
|
||
HALF_MONTH("HALF_MONTH", "半月报"),
|
||
MONTH("MONTH", "月报"),
|
||
CUSTOM("CUSTOM", "自定义");
|
||
|
||
private final String code;
|
||
private final String desc;
|
||
}
|
||
```
|
||
|
||
## 4.2 自然日历窗口规则
|
||
|
||
锚点日期 = `anchorDate`（默认为报告生成当天）。
|
||
|
||
| 周期 | startTime | endTime |
|
||
|:---|:---|:---|
|
||
| 日报 | anchorDate 00:00:00 | anchorDate 23:59:59 |
|
||
| 周报 | anchorDate 所在周的周一 00:00:00 | 周日 23:59:59（按周一为一周起点） |
|
||
| 半月报 | anchorDate 日期 ≤15 → 当月1日 00:00:00 ~ 当月15日 23:59:59；否则 16日 00:00:00 ~ 当月最后一天 23:59:59 |
|
||
| 月报 | anchorDate 所在月 1日 00:00:00 ~ 当月最后一天 23:59:59 |
|
||
| 自定义 | request.startTime | request.endTime |
|
||
|
||
## 4.3 ReportPeriodResolver
|
||
|
||
```java
|
||
public interface ReportPeriodResolver {
|
||
/** 根据周期与锚点日期，计算 [startTime, endTime] */
|
||
TimeWindow resolve(ReportPeriod period, LocalDate anchorDate);
|
||
}
|
||
```
|
||
|
||
```java
|
||
public class TimeWindow {
|
||
private LocalDateTime startTime;
|
||
private LocalDateTime endTime;
|
||
}
|
||
```
|
||
|
||
实现要点：
|
||
- 周一为一周起点（`DayOfWeek.MONDAY`）
|
||
- 月末用 `YearMonth.atEndOfMonth()`
|
||
- 半月报以 15 日为界
|
||
- 时区固定 `GMT+8`（与 `DeviceLog.ts` 的 `@JsonFormat timezone=GMT+8` 一致）
|
||
|
||
## 4.4 ReportRequest 同时支持周期与自定义
|
||
|
||
```java
|
||
public class ReportRequest {
|
||
private Long deviceId;
|
||
/** 报告周期；为 CUSTOM 时使用 startTime/endTime */
|
||
private ReportPeriod period;
|
||
/** 锚点日期（period != CUSTOM 时生效，默认今天） */
|
||
private LocalDate anchorDate;
|
||
/** 自定义开始时间（period == CUSTOM 时生效） */
|
||
private LocalDateTime startTime;
|
||
/** 自定义结束时间（period == CUSTOM 时生效） */
|
||
private LocalDateTime endTime;
|
||
private String templateCode;
|
||
private ReportFormat format;
|
||
}
|
||
```
|
||
|
||
校验规则：
|
||
- `period == null` 且 `startTime/endTime` 都给 → 按 CUSTOM 处理
|
||
- `period != CUSTOM` 时忽略 `startTime/endTime`，由 `ReportPeriodResolver` 计算
|
||
- `endTime` 必须 > `startTime`
|
||
|
||
---
|
||
|
||
# 5. 阈值来源设计（WarningAnalyzer 现实方案）
|
||
|
||
## 5.1 现状
|
||
|
||
`iot_alert` 表无阈值数值列，阈值规则藏在 LiteFlow `iot_scene` 规则链里（脚本化、动态、非结构化）。报告引擎直接解析 LiteFlow 脚本取阈值成本高、易错。
|
||
|
||
## 5.2 V1 方案：iot_report_threshold（报告专用阈值表）
|
||
|
||
报告场景需要**结构化、可读、可回溯**的阈值，与告警规则解耦：
|
||
|
||
```sql
|
||
CREATE TABLE iot_report_threshold (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
product_id BIGINT NOT NULL COMMENT '产品ID（0=全局默认）',
|
||
device_id BIGINT NOT NULL DEFAULT 0 COMMENT '设备ID（0=产品级）',
|
||
monitor_category_code VARCHAR(64) NOT NULL COMMENT '监测分类编码',
|
||
metric_identifier VARCHAR(128) NOT NULL COMMENT '物模型标识符',
|
||
warning_value DECIMAL(18,6) COMMENT '预警阈值',
|
||
alarm_value DECIMAL(18,6) COMMENT '报警阈值',
|
||
control_value DECIMAL(18,6) COMMENT '控制值（设计值，可选）',
|
||
unit VARCHAR(32) COMMENT '单位',
|
||
tenant_id BIGINT,
|
||
del_flag CHAR(1) DEFAULT '0',
|
||
create_by VARCHAR(64),
|
||
create_time DATETIME,
|
||
update_by VARCHAR(64),
|
||
update_time DATETIME,
|
||
KEY idx_device_metric (device_id, metric_identifier),
|
||
KEY idx_product_category (product_id, monitor_category_code)
|
||
) COMMENT '报告预警阈值配置';
|
||
```
|
||
|
||
查询优先级：`device_id > product_id > 全局默认(product_id=0)`。
|
||
|
||
## 5.3 WarningAnalyzer 只读结构化阈值
|
||
|
||
禁止 Analyzer 硬编码 `if(value>2)`。必须通过 `ReportThresholdProvider` 查询：
|
||
|
||
```java
|
||
public interface ReportThresholdProvider {
|
||
ReportThreshold get(MonitorCategory category, Long productId, Long deviceId, String metricIdentifier);
|
||
}
|
||
```
|
||
|
||
`ReportContext` 构建时一次性装入该设备所有相关阈值，Analyzer 直接读 Context。
|
||
|
||
## 5.4 与 iot_alert 的关系
|
||
|
||
- `iot_alert` + `iot_scene` → 实时告警推送（保持现状，不改）
|
||
- `iot_report_threshold` → 报告分析时的预警状态判定（新增）
|
||
|
||
两者独立，避免报告引擎侵入告警规则引擎。未来可考虑用 `iot_alert` 反推阈值，但 V1 不做。
|
||
|
||
---
|
||
|
||
# 6. 物模型与监测数据复用
|
||
|
||
## 6.1 监测指标筛选
|
||
|
||
`ThingsModel` 字段复用约定：
|
||
|
||
| 字段 | 报告用途 |
|
||
|:---|:---|
|
||
| `isMonitor=1` | 纳入监测分析的主指标（裂缝宽度、位移、轴力等） |
|
||
| `isHistory=1` | 查询历史时序数据（DeviceLogMapper.listHistory） |
|
||
| `isChart=1` | 生成趋势图 |
|
||
| `isCalculated=2` | **纵向计算（累积值）**，直接取缓存值作为"累计变化量"，报告不重新计算 |
|
||
| `isCalculated=1` | 横向计算（公式含 `{}`），按 formula 计算 |
|
||
| `isCalculated=0` | 设备原始上报值 |
|
||
| `unit` | 报告数值单位 |
|
||
| `datatype` | integer/decimal/string/bool/array/enum |
|
||
| `formula` | 计算公式（`%s` 占位符） |
|
||
|
||
> **重要**：`isCalculated=2` 的累积值由现有缓存机制维护（见项目既有约定：isCalculated=2 从缓存模型值累积，无新状态表）。报告 Analyzer 直接读取该物模型的时序值作为"累计变化量"，**不要**在报告里再实现一套累积逻辑。
|
||
|
||
## 6.2 数据查询入口
|
||
|
||
报告模块通过 `ReportDataProvider` 抽象调用现有 `DeviceLogMapper`：
|
||
|
||
```java
|
||
public interface ReportDataProvider {
|
||
/** 查询设备某标识符在时间窗口内的时序数据 */
|
||
List<MetricData> queryMetricData(Long deviceId, String identity,
|
||
LocalDateTime start, LocalDateTime end);
|
||
/** 查询设备最后一条上报值 */
|
||
MetricData queryLast(Long deviceId, String identity);
|
||
}
|
||
```
|
||
|
||
实现：内部委托 `DeviceLogMapper.listHistory`（MySQL）或 `TDDeviceLogMapper`（TDengine），按 `iot_device_log.identity` + `ts` 范围 + `logType IN (1,7)` 过滤。
|
||
|
||
## 6.3 MetricData（报告内部数据模型）
|
||
|
||
```java
|
||
public class MetricData {
|
||
private LocalDateTime timestamp;
|
||
private String identity;
|
||
private BigDecimal value;
|
||
private String unit;
|
||
private Integer isCalculated; // 0上报/1横向/2纵向
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 7. 当前架构中的模块职责
|
||
|
||
报告能力必须遵守现有模块边界：
|
||
|
||
```text
|
||
fastbee-admin ← REST 入口
|
||
fastbee-open-api ← 报告 Controller 放这里
|
||
fastbee-report ← 新增模块，报告引擎核心
|
||
fastbee-iot-service ← 设备/产品/物模型/日志领域（被复用）
|
||
fastbee-iot-data ← 时序数据访问（被复用）
|
||
fastbee-plugs/oss ← OSS 上传（被复用）
|
||
fastbee-common ← MonitorCategory / ReportPeriod 枚举
|
||
```
|
||
|
||
禁止：
|
||
- 把报告逻辑全塞进 `fastbee-admin`
|
||
- 把 Word 代码塞进 `fastbee-iot-service`
|
||
- 让 `fastbee-iot-service` 反向依赖 `fastbee-report`
|
||
|
||
---
|
||
|
||
# 8. 推荐新增模块：fastbee-report
|
||
|
||
```text
|
||
fastbee-report/
|
||
├── pom.xml
|
||
└── src/main/java/com/fastbee/report/
|
||
├── api/
|
||
│ ├── ReportEngine.java
|
||
│ ├── ReportRequest.java
|
||
│ └── ReportResult.java
|
||
├── core/
|
||
│ ├── DefaultReportEngine.java
|
||
│ ├── ReportContext.java
|
||
│ ├── ReportContextBuilder.java
|
||
│ └── ReportAssembler.java
|
||
├── category/
|
||
│ ├── MonitorCategoryResolver.java
|
||
│ └── DefaultMonitorCategoryResolver.java
|
||
├── period/
|
||
│ ├── ReportPeriodResolver.java
|
||
│ └── DefaultReportPeriodResolver.java
|
||
├── analyzer/
|
||
│ ├── ReportAnalyzer.java
|
||
│ ├── ReportAnalyzerFactory.java
|
||
│ └── DefaultReportAnalyzerFactory.java
|
||
├── analyzer/crack/
|
||
│ └── CrackMeterAnalyzer.java
|
||
├── analyzer/displacement/
|
||
│ └── DeepDisplacementAnalyzer.java
|
||
├── analyzer/axialforce/
|
||
│ └── AxialForceAnalyzer.java
|
||
├── analyzer/staticlevel/
|
||
│ └── StaticLevelAnalyzer.java
|
||
├── analyzer/vibratingwire/
|
||
│ └── VibratingWireAnalyzer.java
|
||
├── analysis/
|
||
│ ├── StatisticsCalculator.java
|
||
│ ├── TrendAnalyzer.java
|
||
│ ├── RateCalculator.java
|
||
│ ├── QualityAnalyzer.java
|
||
│ └── WarningAnalyzer.java
|
||
├── threshold/
|
||
│ ├── ReportThresholdProvider.java
|
||
│ ├── ReportThreshold.java
|
||
│ └── DbReportThresholdProvider.java
|
||
├── data/
|
||
│ ├── ReportDataProvider.java
|
||
│ ├── MetricData.java
|
||
│ └── DeviceDataSnapshot.java
|
||
├── model/
|
||
│ ├── ReportModel.java
|
||
│ ├── AnalysisResult.java
|
||
│ ├── Statistics.java
|
||
│ ├── TrendAnalysis.java
|
||
│ ├── QualityAnalysis.java
|
||
│ ├── WarningAnalysis.java
|
||
│ ├── AnalysisConclusion.java
|
||
│ └── ChartData.java
|
||
├── chart/
|
||
│ ├── ChartGenerator.java
|
||
│ ├── LineChartGenerator.java // JFreeChart
|
||
│ └── ProfileChartGenerator.java // 位移-深度剖面
|
||
├── renderer/
|
||
│ ├── ReportRenderer.java
|
||
│ ├── WordRenderer.java // poi-tl
|
||
│ └── WordTemplateResolver.java
|
||
├── record/
|
||
│ ├── ReportRecord.java
|
||
│ ├── ReportRecordMapper.java
|
||
│ └── ReportRecordService.java
|
||
└── exception/
|
||
└── ReportException.java
|
||
```
|
||
|
||
---
|
||
|
||
# 9. Maven 模块依赖方向
|
||
|
||
```text
|
||
fastbee-admin
|
||
↓
|
||
fastbee-open-api
|
||
↓
|
||
fastbee-report
|
||
↓
|
||
fastbee-iot-service + fastbee-iot-data + fastbee-oss
|
||
↓
|
||
MySQL / TDengine / Object Storage
|
||
```
|
||
|
||
**禁止** `fastbee-iot-service → fastbee-report` 反向依赖。报告是上层业务能力。
|
||
|
||
---
|
||
|
||
# 10. 新增 Maven 依赖
|
||
|
||
在 `fastbee-report/pom.xml` 引入（项目根 pom.xml 的 `dependencyManagement` 同步声明版本）：
|
||
|
||
```xml
|
||
<!-- Word 模板引擎，基于 poi-ooxml，支持 {{var}} 占位符/循环表格/图片 -->
|
||
<dependency>
|
||
<groupId>com.deepoove</groupId>
|
||
<artifactId>poi-tl</artifactId>
|
||
<version>1.10.4</version>
|
||
</dependency>
|
||
|
||
<!-- Java 端图表生成（PNG 嵌入 Word） -->
|
||
<dependency>
|
||
<groupId>org.jfree</groupId>
|
||
<artifactId>jfreechart</artifactId>
|
||
<version>1.5.4</version>
|
||
</dependency>
|
||
```
|
||
|
||
> poi-tl 1.10.x 兼容 POI 4.1.2；jfreechart 1.5.x 纯 Java、轻量。禁止再引入 docx4j 或 echarts 的 Java 包装。
|
||
|
||
---
|
||
|
||
# 11. ReportEngine
|
||
|
||
```java
|
||
public interface ReportEngine {
|
||
ReportResult generate(ReportRequest request);
|
||
}
|
||
```
|
||
|
||
默认实现：
|
||
|
||
```java
|
||
public class DefaultReportEngine implements ReportEngine {
|
||
|
||
private final ReportContextBuilder contextBuilder;
|
||
private final MonitorCategoryResolver categoryResolver;
|
||
private final ReportAnalyzerFactory analyzerFactory;
|
||
private final ReportAssembler reportAssembler;
|
||
private final ReportRenderer reportRenderer;
|
||
private final ReportPeriodResolver periodResolver;
|
||
private final ReportRecordService recordService;
|
||
|
||
@Override
|
||
public ReportResult generate(ReportRequest request) {
|
||
// 1. 参数校验 + 解析时间窗口
|
||
TimeWindow window = periodResolver.resolve(
|
||
request.getPeriod(), request.getAnchorDate());
|
||
if (request.getPeriod() == ReportPeriod.CUSTOM) {
|
||
window = new TimeWindow(request.getStartTime(), request.getEndTime());
|
||
}
|
||
|
||
// 2. 解析设备监测分类
|
||
MonitorCategory category = categoryResolver.resolveByDeviceId(request.getDeviceId());
|
||
|
||
// 3. 构建上下文（设备/产品/物模型/数据/阈值）
|
||
ReportContext context = contextBuilder.build(request, window, category);
|
||
|
||
// 4. 路由 Analyzer
|
||
ReportAnalyzer analyzer = analyzerFactory.get(category);
|
||
|
||
// 5. 执行分析
|
||
AnalysisResult analysis = analyzer.analyze(context, request);
|
||
|
||
// 6. 组装报告模型
|
||
ReportModel model = reportAssembler.assemble(context, analysis, request);
|
||
|
||
// 7. 渲染 Word
|
||
ReportResult result = reportRenderer.render(model, request);
|
||
|
||
// 8. 落库 ReportRecord
|
||
recordService.saveSuccess(request, window, category, result);
|
||
|
||
return result;
|
||
}
|
||
}
|
||
```
|
||
|
||
`ReportEngine` 不得包含具体设备分析逻辑。
|
||
|
||
---
|
||
|
||
# 12. ReportContext
|
||
|
||
Analyzer 的输入上下文，构建时一次性装配所有依赖数据：
|
||
|
||
```java
|
||
public class ReportContext {
|
||
private Project project;
|
||
private Device device;
|
||
private Product product;
|
||
private MonitorCategory category;
|
||
private TimeWindow window;
|
||
private List<ThingsModel> metrics; // isMonitor=1 的物模型
|
||
private Map<String, List<MetricData>> data; // identity -> 时序数据
|
||
private Map<String, ReportThreshold> thresholds; // identity -> 阈值
|
||
private ReportRequest request;
|
||
private Map<String, Object> attributes; // 扩展
|
||
}
|
||
```
|
||
|
||
`ReportContextBuilder` 统一完成：
|
||
|
||
```text
|
||
查设备 → 查产品 → 解析 MonitorCategory
|
||
→ 查物模型(isMonitor=1)
|
||
→ 查阈值(iot_report_threshold)
|
||
→ 查时序数据(DeviceLogMapper.listHistory)
|
||
→ 装入 ReportContext
|
||
```
|
||
|
||
Analyzer 不允许自己 `@Autowired` 业务 Service 查询。
|
||
|
||
---
|
||
|
||
# 13. ReportAnalyzer
|
||
|
||
```java
|
||
public interface ReportAnalyzer {
|
||
boolean supports(MonitorCategory category);
|
||
AnalysisResult analyze(ReportContext context, ReportRequest request);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 14. 通用分析能力
|
||
|
||
所有设备共享：
|
||
|
||
```text
|
||
StatisticsCalculator 统计（当前/初始/最小/最大/平均/中位/变化量/累计变化）
|
||
RateCalculator 变化速率（mm/day, kN/day）—— 需考虑时间间隔/数据缺失/异常值
|
||
TrendAnalyzer 趋势（UP/DOWN/STABLE/FLUCTUATION/UNKNOWN + 斜率 + 置信度）
|
||
QualityAnalyzer 数据质量（缺失/重复/越界/突变/平线/完整率）
|
||
WarningAnalyzer 预警（读 ReportThreshold，输出 NORMAL/WARNING/ALARM）
|
||
```
|
||
|
||
### Statistics
|
||
|
||
```java
|
||
public class Statistics {
|
||
private BigDecimal current; // 当前值
|
||
private BigDecimal baseline; // 初始值（窗口首条或设备激活首条）
|
||
private BigDecimal min;
|
||
private BigDecimal max;
|
||
private BigDecimal average;
|
||
private BigDecimal median;
|
||
private BigDecimal delta; // 本期变化量 = current - baseline
|
||
private BigDecimal cumulative; // 累计变化量（优先取 isCalculated=2 物模型值）
|
||
private String unit;
|
||
}
|
||
```
|
||
|
||
### RateCalculator 禁止简单 `(last-first)`
|
||
|
||
必须考虑：时间间隔、数据缺失段、异常值剔除（3σ 或 IQR）、采样周期不均。
|
||
|
||
### TrendAnalysis
|
||
|
||
```java
|
||
public class TrendAnalysis {
|
||
private TrendType trend; // UP/DOWN/STABLE/FLUCTUATION/UNKNOWN
|
||
private BigDecimal slope; // 线性回归斜率
|
||
private BigDecimal confidence; // R²
|
||
private String description;
|
||
}
|
||
```
|
||
|
||
V1 用简单线性回归；未来可升级移动平均/指数平滑/异常点剔除/季节性分析。
|
||
|
||
### QualityAnalysis
|
||
|
||
```java
|
||
public class QualityAnalysis {
|
||
private int total;
|
||
private int valid;
|
||
private int missing;
|
||
private int duplicate;
|
||
private int abnormal;
|
||
private BigDecimal integrityRate; // 完整率 = valid/total
|
||
private String status;
|
||
}
|
||
```
|
||
|
||
### WarningAnalysis
|
||
|
||
```java
|
||
public class WarningAnalysis {
|
||
private WarningStatus status; // NORMAL/WARNING/ALARM/UNKNOWN
|
||
private BigDecimal current;
|
||
private BigDecimal warningThreshold;
|
||
private BigDecimal alarmThreshold;
|
||
private BigDecimal controlValue; // 设计控制值（可选）
|
||
private String description;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 15. AnalysisResult
|
||
|
||
Analyzer 最终输出契约：
|
||
|
||
```java
|
||
public class AnalysisResult {
|
||
private Statistics statistics;
|
||
private TrendAnalysis trend;
|
||
private QualityAnalysis quality;
|
||
private WarningAnalysis warning;
|
||
private List<ChartData> charts;
|
||
private List<AnalysisConclusion> conclusions;
|
||
private Map<String, Object> extensions; // 设备专属分析结果
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
# 16. 设备专属分析
|
||
|
||
## 16.1 裂缝计（CRACK_METER）
|
||
|
||
```text
|
||
当前裂缝宽度、初始裂缝宽度、本期变化量、累计变化量
|
||
最大值、最小值、平均值、变化速率、趋势、预警状态
|
||
```
|
||
|
||
`extensions.put("crack", crackExtension)`
|
||
|
||
图表：`CRACK_TREND`（裂缝宽度时程图）
|
||
|
||
## 16.2 深部位移（DEEP_DISPLACEMENT）
|
||
|
||
不能当单值指标处理，需按深度维度组织：
|
||
|
||
```text
|
||
设备 → 深度 → 不同深度测点 → 位移值
|
||
```
|
||
|
||
输出：最大位移、最大位移深度、累计位移、位移速率、位移趋势、位移-深度剖面图。
|
||
|
||
图表：
|
||
- `DEEP_DISPLACEMENT_TREND`（位移时程图）
|
||
- `DEEP_DISPLACEMENT_PROFILE`（位移-深度剖面图）
|
||
|
||
## 16.3 轴力/压力计（AXIAL_FORCE）
|
||
|
||
```text
|
||
当前轴力、初始轴力、本期变化、累计变化、最大轴力、平均轴力
|
||
变化速率、趋势、控制值占比、预警状态
|
||
```
|
||
|
||
仅在阈值配置存在设计值/控制值/预警值/报警值时才评价。
|
||
|
||
## 16.4 静力水准仪（STATIC_LEVEL）
|
||
|
||
```text
|
||
当前相对高程、初始值、本期变化、累计沉降、最大沉降
|
||
沉降速率、趋势、差异沉降、预警状态
|
||
```
|
||
|
||
图表：`STATIC_LEVEL_TREND`（沉降时程）、`STATIC_LEVEL_COMPARE`（测点沉降对比）
|
||
|
||
## 16.5 振弦式采集仪（VIBRATING_WIRE）
|
||
|
||
区分原始物理量（频率/温度）与工程换算量：
|
||
|
||
```text
|
||
当前频率、平均频率、最大频率、最小频率、温度、工程换算值、趋势、数据质量
|
||
```
|
||
|
||
---
|
||
|
||
# 17. ReportAssembler
|
||
|
||
```java
|
||
public interface ReportAssembler {
|
||
ReportModel assemble(ReportContext context, AnalysisResult analysis, ReportRequest request);
|
||
}
|
||
```
|
||
|
||
职责：`ReportContext + AnalysisResult + ReportRequest → ReportModel`。
|
||
|
||
```java
|
||
public class ReportModel {
|
||
private ReportInfo report; // 报告编号、周期、时间窗口、生成时间
|
||
private Project project;
|
||
private Device device;
|
||
private Product product;
|
||
private MonitorCategory category;
|
||
private MonitoringSummary summary;
|
||
private AnalysisResult analysis;
|
||
private List<ChartData> charts;
|
||
private List<TableData> tables;
|
||
private Map<String, Object> variables; // Word 模板变量
|
||
}
|
||
```
|
||
|
||
WordRenderer 只依赖 `ReportModel`，**禁止查询数据库**。
|
||
|
||
---
|
||
|
||
# 18. WordRenderer（poi-tl）
|
||
|
||
```java
|
||
public interface ReportRenderer {
|
||
ReportResult render(ReportModel model, ReportRequest request);
|
||
}
|
||
```
|
||
|
||
## 18.1 渲染流程
|
||
|
||
```text
|
||
加载 Word 模板（WordTemplateResolver 按 templateCode + category 定位）
|
||
↓
|
||
poi-tl 渲染 {{}} 占位符
|
||
↓
|
||
插入图表 PNG（ChartData.image）
|
||
↓
|
||
生成 byte[]
|
||
↓
|
||
OssFactory.instance(redis).upload(byte[], path, "application/vnd.openxmlformats-officedocument.wordprocessingml.document")
|
||
↓
|
||
返回 fileUrl
|
||
```
|
||
|
||
## 18.2 模板命名规范
|
||
|
||
```text
|
||
DEVICE_CRACK_METER_V1.docx
|
||
DEVICE_DEEP_DISPLACEMENT_V1.docx
|
||
DEVICE_AXIAL_FORCE_V1.docx
|
||
DEVICE_STATIC_LEVEL_V1.docx
|
||
DEVICE_VIBRATING_WIRE_V1.docx
|
||
```
|
||
|
||
## 18.3 Word 变量规范（poi-tl `{{}}` 语法）
|
||
|
||
```text
|
||
{{report.no}}
|
||
{{report.periodDesc}} 日报/周报/半月报/月报
|
||
{{report.startTime}}
|
||
{{report.endTime}}
|
||
{{project.name}}
|
||
{{project.code}}
|
||
{{device.name}}
|
||
{{device.serialNumber}}
|
||
{{product.monitorCategoryDesc}}
|
||
{{analysis.statistics.current}}
|
||
{{analysis.statistics.min}}
|
||
{{analysis.statistics.max}}
|
||
{{analysis.statistics.average}}
|
||
{{analysis.statistics.delta}}
|
||
{{analysis.statistics.cumulative}}
|
||
{{analysis.rate}}
|
||
{{analysis.trend.description}}
|
||
{{analysis.quality.integrityRate}}
|
||
{{analysis.warning.status}}
|
||
{{analysis.warning.description}}
|
||
{{conclusions}} 循环列表（poi-tl 循环表格）
|
||
{{charts.crackTrend}} 图片占位符
|
||
```
|
||
|
||
禁止 Word 模板直接引用数据库字段。
|
||
|
||
## 18.4 模板表
|
||
|
||
```sql
|
||
CREATE TABLE report_template (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
template_code VARCHAR(128) NOT NULL,
|
||
template_name VARCHAR(128),
|
||
monitor_category_code VARCHAR(64) NOT NULL,
|
||
version VARCHAR(32),
|
||
file_path VARCHAR(512),
|
||
status TINYINT DEFAULT 1,
|
||
tenant_id BIGINT,
|
||
create_time DATETIME,
|
||
update_time DATETIME,
|
||
UNIQUE KEY uk_code_version (template_code, version)
|
||
) COMMENT '报告模板';
|
||
```
|
||
|
||
---
|
||
|
||
# 19. 图表规范
|
||
|
||
```java
|
||
public class ChartData {
|
||
private String chartCode;
|
||
private String title;
|
||
private ChartType type; // LINE / BAR / PROFILE / SCATTER
|
||
private byte[] image; // PNG 字节
|
||
}
|
||
```
|
||
|
||
图表生成链路：
|
||
|
||
```text
|
||
MetricData → AnalysisResult → ChartData(由 ChartGenerator 用 JFreeChart 生成 PNG) → WordRenderer → DOCX
|
||
```
|
||
|
||
Java 端用 JFreeChart 生成 PNG，Word 只负责放置图片。禁止在前端生成图回传后端。
|
||
|
||
---
|
||
|
||
# 20. ReportRecord（报告生命周期）
|
||
|
||
```sql
|
||
CREATE TABLE report_record (
|
||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||
report_no VARCHAR(64) NOT NULL COMMENT '报告编号 REPORT-yyyyMMddHHmmss-xxxx',
|
||
device_id BIGINT NOT NULL,
|
||
monitor_category_code VARCHAR(64) NOT NULL,
|
||
period VARCHAR(32) COMMENT 'DAY/WEEK/HALF_MONTH/MONTH/CUSTOM',
|
||
template_code VARCHAR(128),
|
||
template_version VARCHAR(32),
|
||
start_time DATETIME,
|
||
end_time DATETIME,
|
||
status VARCHAR(16) COMMENT 'CREATING/SUCCESS/FAILED',
|
||
file_url VARCHAR(512),
|
||
error_message VARCHAR(1024),
|
||
tenant_id BIGINT,
|
||
create_by VARCHAR(64),
|
||
create_time DATETIME,
|
||
KEY idx_device (device_id, create_time),
|
||
KEY idx_period (period, create_time)
|
||
) COMMENT '报告生成记录';
|
||
```
|
||
|
||
状态：`CREATING / SUCCESS / FAILED`。
|
||
|
||
---
|
||
|
||
# 21. API 设计
|
||
|
||
```text
|
||
POST /iot/report/device/generate 生成报告（同步）
|
||
GET /iot/report/list 报告列表
|
||
GET /iot/report/{reportNo} 报告详情
|
||
GET /iot/report/download/{reportNo} 下载（重定向 OSS URL）
|
||
```
|
||
|
||
### 生成请求
|
||
|
||
```json
|
||
POST /iot/report/device/generate
|
||
{
|
||
"deviceId": 10001,
|
||
"period": "WEEK",
|
||
"anchorDate": "2026-08-09",
|
||
"templateCode": "DEVICE_CRACK_METER_V1",
|
||
"format": "WORD"
|
||
}
|
||
```
|
||
|
||
或自定义时间范围：
|
||
|
||
```json
|
||
{
|
||
"deviceId": 10001,
|
||
"period": "CUSTOM",
|
||
"startTime": "2026-08-01 00:00:00",
|
||
"endTime": "2026-08-08 23:59:59",
|
||
"templateCode": "DEVICE_CRACK_METER_V1"
|
||
}
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"reportNo": "REPORT-202608090001",
|
||
"status": "SUCCESS",
|
||
"fileName": "304259363251-周报-监测分析报告.docx",
|
||
"fileUrl": "https://..."
|
||
}
|
||
```
|
||
|
||
### 权限
|
||
|
||
按 CLAUDE.md 权限策略，报告接口跨页面复用，读接口用 `hasAnyPermi`：
|
||
|
||
```java
|
||
// 生成（写）
|
||
@PreAuthorize("@ss.hasPermi('iot:report:generate')")
|
||
|
||
// 列表/详情/下载（读，跨页面复用）
|
||
@PreAuthorize("@ss.hasAnyPermi('iot:report:list,iot:device:list')")
|
||
```
|
||
|
||
---
|
||
|
||
# 22. OSS 文件路径规范
|
||
|
||
```text
|
||
/report/yyyy/MM/dd/device/{deviceId}/{reportNo}.docx
|
||
例：/report/2026/08/09/device/10001/REPORT-202608090001.docx
|
||
```
|
||
|
||
复用 `OssFactory.instance(redis).upload(byte[], path, contentType)`，禁止把 Word 永久存服务器本地。
|
||
|
||
---
|
||
|
||
# 23. 异步化建议
|
||
|
||
V1 单设备 + 数据量 < 100 万 → 同步生成即可。
|
||
|
||
后续若数据量大/图表多/Word 耗时：
|
||
|
||
```text
|
||
API → fastbee-mq(RocketMQ) → ReportConsumer → ReportEngine → OSS → ReportRecord
|
||
```
|
||
|
||
复用现有 `fastbee-mq`。V1 不要为异步而异步。
|
||
|
||
---
|
||
|
||
# 24. 报告结论生成原则
|
||
|
||
结论必须基于 `Statistics + Trend + Quality + Warning` 结构化结果，**不是**让 AI 直接读原始数据。
|
||
|
||
V1 用规则引擎 + 模板文字：
|
||
|
||
```java
|
||
if (warning == WARNING) {
|
||
conclusion = "当前监测值达到项目配置的预警阈值，建议持续关注。";
|
||
}
|
||
```
|
||
|
||
未来可接 LLM 做自然语言润色，但 **LLM 不负责工程安全判定**。
|
||
|
||
---
|
||
|
||
# 25. 第一阶段报告内容（单设备固定结构）
|
||
|
||
```text
|
||
1. 监测结论摘要
|
||
2. 设备基本信息（含监测分类）
|
||
3. 数据质量分析
|
||
4. 监测数据统计
|
||
5. 趋势分析
|
||
6. 预警分析
|
||
7. 设备专项分析（按 MonitorCategory）
|
||
8. 趋势图
|
||
9. 综合分析结论
|
||
```
|
||
|
||
暂不包含：项目总体分析、多设备关联、施工阶段关联、工程风险评价。
|
||
|
||
---
|
||
|
||
# 26. 不允许的设计
|
||
|
||
```text
|
||
❌ ReportEngine 直接操作 Mapper
|
||
❌ WordRenderer 查询数据库
|
||
❌ Word 模板写 SQL
|
||
❌ Analyzer 硬编码工程阈值
|
||
❌ 所有设备写在一个 Analyzer
|
||
❌ if(category==xxx) 巨型判断
|
||
❌ AI 直接判断结构是否安全
|
||
❌ 把所有报告逻辑放 fastbee-admin
|
||
❌ Word 模板和数据库字段直接绑定
|
||
❌ 复用 DeviceType 作为分类路由键（应使用 MonitorCategory）
|
||
❌ 重复实现 OSS / 数据查询 / 图表能力
|
||
❌ 把 iot_category 当作监测分类路由键
|
||
❌ 报告模块反向依赖 fastbee-iot-service 之外的循环依赖
|
||
```
|
||
|
||
---
|
||
|
||
# 27. 测试要求
|
||
|
||
每个 Analyzer 必须有单元测试，覆盖：
|
||
|
||
```text
|
||
正常数据 / 数据为空 / 数据不足 / 数据缺失 / 数据异常
|
||
持续增长 / 持续下降 / 波动 / 达到预警 / 达到报警
|
||
```
|
||
|
||
测试数据放 `src/test/resources/report/`：
|
||
|
||
```text
|
||
crack/normal.json, warning.json, alarm.json, abnormal.json, missing.json
|
||
displacement/normal.json, warning.json, profile.json
|
||
```
|
||
|
||
不依赖线上真实数据。
|
||
|
||
`ReportPeriodResolver` 必须测试边界：周末/月末/闰年二月/半月报 15 日分界。
|
||
|
||
---
|
||
|
||
# 28. 第一阶段开发顺序
|
||
|
||
## Step 0：基础设施
|
||
|
||
- [ ] 根 `pom.xml` 声明 poi-tl、jfreechart 版本
|
||
- [ ] `iot_product` 加 `monitor_category_code` 列 + 存量数据回填
|
||
- [ ] 新建 `iot_report_threshold`、`report_template`、`report_record` 三张表
|
||
- [ ] `MonitorCategory`、`ReportPeriod` 枚举放 `fastbee-common`
|
||
- [ ] `Product.java` 加 `monitorCategoryCode` 字段
|
||
|
||
## Step 1：fastbee-report 模块骨架
|
||
|
||
- [ ] 创建 `fastbee-report` 模块，加入根 pom `<modules>`
|
||
- [ ] `ReportRequest` / `ReportResult` / `ReportEngine` / `ReportContext`
|
||
|
||
## Step 2：分类与周期
|
||
|
||
- [ ] `MonitorCategoryResolver` / `DefaultMonitorCategoryResolver`
|
||
- [ ] `ReportPeriodResolver` / `DefaultReportPeriodResolver` + 单测
|
||
|
||
## Step 3：Analyzer 框架
|
||
|
||
- [ ] `ReportAnalyzer` / `ReportAnalyzerFactory` / `DefaultReportAnalyzerFactory`
|
||
|
||
## Step 4：先只实现 CrackMeterAnalyzer
|
||
|
||
- [ ] 不同时写 5 种
|
||
|
||
## Step 5：通用分析能力
|
||
|
||
- [ ] `StatisticsCalculator` / `TrendAnalyzer` / `RateCalculator` / `QualityAnalyzer` / `WarningAnalyzer`
|
||
|
||
## Step 6：数据与阈值 Provider
|
||
|
||
- [ ] `ReportDataProvider`（委托 `DeviceLogMapper`）
|
||
- [ ] `ReportThresholdProvider`（查 `iot_report_threshold`）
|
||
|
||
## Step 7：AnalysisResult + ReportModel + ReportAssembler
|
||
|
||
## Step 8：ChartGenerator（JFreeChart 生成 PNG）
|
||
|
||
## Step 9：WordRenderer（poi-tl）
|
||
|
||
## Step 10：制作 `DEVICE_CRACK_METER_V1.docx` 模板
|
||
|
||
## Step 11：闭环验证
|
||
|
||
- [ ] 设备 `304259363251` + 周报 + Word 完整跑通
|
||
- [ ] OSS 上传 + ReportRecord 落库 + 下载
|
||
|
||
## Step 12：扩展其他分类
|
||
|
||
- [ ] `DeepDisplacementAnalyzer`
|
||
- [ ] `AxialForceAnalyzer`
|
||
- [ ] `StaticLevelAnalyzer`
|
||
- [ ] `VibratingWireAnalyzer`
|
||
|
||
---
|
||
|
||
# 29. Definition of Done
|
||
|
||
```text
|
||
[ ] fastbee-report 模块创建完成，根 pom 已注册
|
||
[ ] Maven 依赖无循环
|
||
[ ] iot_product.monitor_category_code 列已加 + 存量回填
|
||
[ ] iot_report_threshold / report_template / report_record 三张表已建
|
||
[ ] MonitorCategory / ReportPeriod 枚举已放 fastbee-common
|
||
[ ] ReportEngine / ReportRequest / ReportContext 创建完成
|
||
[ ] MonitorCategoryResolver 创建完成
|
||
[ ] ReportPeriodResolver 创建完成 + 边界单测
|
||
[ ] ReportAnalyzer / AnalyzerFactory 创建完成
|
||
[ ] CrackMeterAnalyzer 创建完成
|
||
[ ] StatisticsCalculator / TrendAnalyzer / RateCalculator / QualityAnalyzer / WarningAnalyzer 创建完成
|
||
[ ] ReportDataProvider / ReportThresholdProvider 创建完成
|
||
[ ] AnalysisResult / ReportModel / ReportAssembler 创建完成
|
||
[ ] ChartGenerator（JFreeChart）创建完成
|
||
[ ] WordRenderer（poi-tl）创建完成
|
||
[ ] Word 模板 DEVICE_CRACK_METER_V1.docx 完成
|
||
[ ] OSS 上传完成（复用 OssFactory）
|
||
[ ] ReportRecord 落库完成
|
||
[ ] POST /iot/report/device/generate 等 API 完成
|
||
[ ] 单元测试完成（含 ReportPeriodResolver 边界）
|
||
[ ] 设备 304259363251 周报可成功生成 DOCX
|
||
[ ] 异常情况返回 FAILED 并落库
|
||
[ ] 生成后的报告可重新下载
|
||
[ ] 日报/周报/半月报/月报四种周期均可生成
|
||
```
|
||
|
||
---
|
||
|
||
# 30. 最终架构目标
|
||
|
||
第一阶段：
|
||
|
||
```text
|
||
304259363251 (deviceId)
|
||
│
|
||
ReportRequest(period=WEEK)
|
||
│
|
||
ReportPeriodResolver → [周一00:00, 周日23:59]
|
||
│
|
||
MonitorCategoryResolver → CRACK_METER
|
||
│
|
||
ReportEngine
|
||
│
|
||
CrackMeterAnalyzer
|
||
│
|
||
AnalysisResult
|
||
│
|
||
ReportModel
|
||
│
|
||
WordRenderer(poi-tl) + ChartGenerator(JFreeChart)
|
||
│
|
||
byte[] → OssFactory → OSS
|
||
│
|
||
ReportRecord
|
||
│
|
||
返回下载地址
|
||
```
|
||
|
||
未来：
|
||
|
||
```text
|
||
Project
|
||
│
|
||
┌───────────┼────────────┐
|
||
▼ ▼ ▼
|
||
CRACK AXIAL DISPLACEMENT
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
Analyzer Analyzer Analyzer
|
||
│ │ │
|
||
└───────────┼────────────┘
|
||
▼
|
||
ProjectReportEngine（聚合层）
|
||
│
|
||
▼
|
||
ProjectReportModel
|
||
│
|
||
▼
|
||
Word/PDF
|
||
```
|
||
|
||
> **单设备 Report Engine 是底层能力，项目报告只是未来的聚合层。**
|
||
|
||
---
|
||
|
||
# 31. AI Agent 执行规则
|
||
|
||
当 AI Agent 执行本 Skill 时：
|
||
|
||
## 第一原则：先读后写
|
||
|
||
重点搜索：`Device` / `Product` / `ThingsModel` / `DeviceLogMapper` / `TDDeviceLogMapper` / `OssFactory` / `Alert` / `Project` / `poi-ooxml`。禁止重复实现已有能力。
|
||
|
||
## 第二原则：先确认模块依赖
|
||
|
||
禁止循环依赖。`fastbee-report` 只能向下依赖 `fastbee-iot-service` / `fastbee-iot-data` / `fastbee-oss` / `fastbee-common`。
|
||
|
||
## 第三原则：先跑通裂缝计
|
||
|
||
验证完整链路后再扩展其他分类。不要一次性实现全部设备。
|
||
|
||
## 第四原则：复用优先
|
||
|
||
OSS / 数据查询 / Word / 图表，能复用就复用，不能复用才引入新依赖（poi-tl、jfreechart）。
|
||
|
||
## 第五原则：单一职责、低耦合、可测试、可扩展
|
||
|
||
---
|
||
|
||
# 32. 最终指令
|
||
|
||
你现在是 FastBee 项目的高级 Java 架构工程师。请严格按照本 Skill 实施。
|
||
|
||
执行前：
|
||
|
||
1. 阅读当前项目目录结构。
|
||
2. 搜索已有设备、物模型、DeviceLogMapper、TDDeviceLogMapper、OssFactory、Alert、Project、poi-ooxml 相关代码。
|
||
3. 判断哪些能力可以复用。
|
||
4. 不允许重复实现已有基础能力。
|
||
5. 不允许修改无关业务。
|
||
|
||
第一阶段只实现：
|
||
|
||
```text
|
||
单设备 + 报告周期(日/周/半月/月) + 裂缝计(CRACK_METER) + Word
|
||
```
|
||
|
||
必须先完成完整闭环。完成后再扩展：深部位移 / 轴力 / 静力水准 / 振弦。
|
||
|
||
代码必须遵循：
|
||
|
||
```text
|
||
ReportRequest(含 period)
|
||
↓
|
||
ReportPeriodResolver → TimeWindow
|
||
↓
|
||
MonitorCategoryResolver → MonitorCategory
|
||
↓
|
||
ReportContextBuilder → ReportContext
|
||
↓
|
||
ReportAnalyzerFactory.get(category)
|
||
↓
|
||
AnalysisResult
|
||
↓
|
||
ReportModel
|
||
↓
|
||
WordRenderer(poi-tl) + ChartGenerator(JFreeChart)
|
||
↓
|
||
OssFactory → OSS
|
||
↓
|
||
ReportRecord
|
||
```
|
||
|
||
不得破坏 FastBee 当前模块边界。
|
||
|
||
实现过程中优先保证：
|
||
|
||
```text
|
||
架构正确
|
||
数据正确
|
||
分析可测试
|
||
模板可替换
|
||
设备分类可扩展（MonitorCategory）
|
||
报告周期可扩展（ReportPeriod）
|
||
```
|
||
|
||
而不是追求一次实现所有功能。
|
||
|
||
最终输出：
|
||
|
||
```text
|
||
1. 修改文件列表
|
||
2. 新增文件列表
|
||
3. Maven 依赖变化
|
||
4. 数据库变化（iot_product 加列 + 3 张新表）
|
||
5. API 说明
|
||
6. Word 模板变量说明
|
||
7. 测试结果
|
||
8. 使用说明
|
||
9. 后续扩展建议
|
||
```
|