# fysb_models **Repository Path**: 4u4e/fysb_models ## Basic Information - **Project Name**: fysb_models - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-08 - **Last Updated**: 2026-11-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 自然灾害动态风险评估系统 (Natural Hazards Dynamic Risk Assessment System) 基于统一四要素风险框架 `R = H × E × V / (1 + C)` 的 Java / Spring Boot 项目。系统注册并**全部上线**五个单灾种模块 + 一个上层**行政区域综合风险**模块:**山洪**(动态临界雨量法)、**地质灾害**(易发性 S × 触发危险度 T + 有效降水临界雨量曲线)、**森林火灾**(本底易燃性 B × 火险气象危险度 F)、**流域洪涝**(致洪危险度 Q × 承泄不足度 S + 动态临界面雨量与汇流滞后)、**城市内涝**(致涝危险度 Q × 排水不足度 D + 短历时雨强超设计重现期与快涨快退)。五个单灾种共享同一套计算内核、四级分级、配置中心与数据管理后台;综合风险模块消费五个单灾种结果,两级聚合到县 / 乡镇 / 村三级行政区,输出多灾种综合风险指数 CRI。 五个灾种除输出整场过程的**总体风险 R** 外,还统一输出**逐时间节点风险 R(t)** 曲线(过去实况 + 未来预报全时次),结果既内联在评估响应中,也自动落库到批次表 / 逐时次明细表 / 既有结果主表,可按批次、单元、灾种回溯查询;曲线在风险分布面板之外作为独立单点信息面板常显,与「卡片列表 / 地图 / 风险矩阵」三态切换互不干扰;分布面板内另有「逐时刻全点位风险回放」工具条(综合风险页为「逐时刻全行政区域回放」),拖动或播放时间轴即可横向查看同一时刻所有点位 / 行政区域的风险等级;轨道采用一格一时刻的「时刻格子」,每格直接标注 HH:mm,顶部色条显示该时刻全场最高风险等级颜色,角标显示达到该等级的点位数;轨道宽度贴合页面,超出部分用 ‹ › 左右翻页查看,不会产生页面级横向滚动条。详见「逐时间节点风险评估结果」与「逐时刻全点位风险分布回放」两章,综合页适配见「逐时刻全行政区域风险回放」。 页面入口:`index.html`(山洪)、`geo-hazard.html`(地质灾害)、`forest-fire.html`(森林火灾)、`river-flood.html`(流域洪涝)、`urban-waterlogging.html`(城市内涝)、`comprehensive-risk.html`(行政区域综合风险)、`admin.html`(共享数据管理后台)、`module-placeholder.html`(模块导航异常时的兜底占位页)。顶部模块导航由 `js/module-nav.js` 统一渲染,模块元数据来自 `GET /api/system/modules`(`moduleCount=6` / `readyCount=6`)。 ## 模块清单(五个单灾种 + 行政区域综合风险) | 模块 | 灾种枚举 | 模型 | 状态 | 入口 | |---|---|---|---|---| | 流域洪涝 | `RIVER_FLOOD` | Q × S + 动态临界面雨量与汇流滞后 | 已上线 | `river-flood.html` | | 山洪 | `FLASH_FLOOD` | 动态临界雨量法 | 已上线 | `index.html` | | 地质灾害 | `GEO_HAZARD` | S × T + 有效降水临界曲线 | 已上线 | `geo-hazard.html` | | 森林火灾 | `FOREST_FIRE` | B × F + 连续干燥度累积(FWI) | 已上线 | `forest-fire.html` | | 城市内涝 | `URBAN_WATERLOGGING` | Q × D + 短历时雨强超设计重现期与快涨快退 | 已上线 | `urban-waterlogging.html` | | **综合风险** | `COMPREHENSIVE` | 两级聚合:单元风险 → 区域单灾种风险 R(a,h) → 多灾种综合指数 CRI(分级 / 排序 / 下钻) | 已上线 | `comprehensive-risk.html` | 新增**单灾种**只需实现 `IHazardPlugin` 并注册参数包,统一内核 `RiskComputeEngine`、四级分级 `RiskLevel`、配置中心 `sys_risk_config`、通用 CRUD 管理端与空间地图视图均可直接复用。综合风险是上层模块,不实现 `IHazardPlugin`、不重算致灾因子,只消费单灾种结果(详见「行政区域综合风险动态评估模型」一章)。 ## 核心模型 统一风险公式(四要素归一化到 [0, 1]): ``` R = H × E × V / (1 + C) ``` | 符号 | 含义 | 说明 | |------|------|------| | H | 危险性 Hazard | 由致灾因子(降雨等)驱动,动态计算 | | E | 承灾体暴露度 Exposure | 人口、资产、设施总量 | | V | 脆弱性 Vulnerability | 承灾体的易损程度 | | C | 防灾减灾能力 Capacity | 预警、应急、防护工程,能力越强风险越低 | ### 风险等级(四级) | 等级 | 颜色 | 阈值 | |------|------|------| | 1 - 低风险 | 蓝 | R < 0.25 | | 2 - 中风险 | 黄 | 0.25 ≤ R < 0.5 | | 3 - 高风险 | 橙 | 0.5 ≤ R < 0.75 | | 4 - 极高风险 | 红 | R ≥ 0.75 | ## 山洪风险评估算法(动态临界雨量法) ### 计算流程 ``` 气象数据(NOW/OBS/FCST) → 多历时累积雨量 P_1h/3h/6h → 前期影响雨量 API ↓ 动态临界雨量 CR_t = Pt_t × α(API) ↓ 超阈比 ratio = max(P_t / CR_t) ↓ 分段归一化 → H ∈ [0,1] ↓ R = H × E × V / (1 + C) → 分级 ``` ### 关键公式 **前期影响雨量 API**(土壤饱和度代理): ``` API = Σ(Pᵢ · k^i), i=1..n k = 0.85(衰减系数), n = 15天 ``` **动态调整系数 α**(临界雨量随土壤湿度变化): ``` α(API) = clip(1 - β · (API - API₀)/API_max, α_min, 1) β = 0.5, α_min = 0.4 ``` **危险性 H 分段归一化**: ``` H = 0 ratio < 0.6 H = 线性拉伸到 [0,1] 0.6 ≤ ratio < 1.2 H = 1 ratio ≥ 1.2 ``` ## 地质灾害动态风险评估模型(技术方案 V1.0) 模型依据 `地质灾害动态风险评估模型技术方案.md` 实现,复用山洪的四要素内核,但按地灾机理把危险性拆成**静态本底 × 动态触发**: | 维度 | 山洪 | 地质灾害 | |---|---|---| | 危险性结构 | `H ≈ f(降雨, 临界阈值)` | `H = 易发性 S × 触发危险度 T` | | 主导因素 | 短历时雨强(1h / 3h) | 地质易发性本底,降水为触发 | | 前期降水 | API(k=0.85,n=15 天) | 有效降水 `R_eff`(K=0.80~0.84,n=15~30 天),衰减更慢 | | 阈值形态 | 单一临界雨量 × α(API) | 当日雨量—前期有效雨量曲线,预警线 / 危险线两级 | | 雨停之后 | 快速退水 | 滞后关注期内按衰减曲线延续,风险不立即归零 | | 评估单元 | 小流域 | 隐患点 / 斜坡单元 / 泥石流沟域 | ### 核心公式 ``` R_eff = R₀ + Σ(Rᵢ × Kⁱ) i = 1..n,K=0.80~0.84,n=15~30 天 saturation = min(1, R_eff / 参考有效降水) 预警线 = max(下限, 预警线基准 × (1 - γ × saturation)) # 前期越湿,触发所需当日降水越低 危险线 = max(下限 × 1.4, 危险线基准 × (1 - γ × saturation)) d = R₀ / 预警线 T = 0 d < 0.6 T ∈ [0, 0.6] 0.6 ≤ d < 1 (接近预警) T ∈ [0.6, 1.0] 1 ≤ d < 危险线/预警线(预警区) T = 1 d ≥ 危险线/预警线 (极可能触发) H = S × T R = H × E × V / (1 + C) ``` 短历时强降水(泥石流沟域)另按 1h 最大雨强独立触发,与累积型曲线取最不利;在册隐患点命中预警区时启用风险下限,避免「有险无灾」误降级漏警。 ### 动态机制 - **阈值动态**:前期有效降水越高,临界雨量曲线整体下移(已内含于当日雨量—前期有效雨量曲线)。 - **滞后延续**:雨停后 `T_lag = T_prev × lagDecay^小时数`,与当前 T 取较大者,并输出滞后关注期剩余时长。 - **数据质量**:必要降水缺失返回 `MET_MISSING`(区别于低风险,不输出风险等级);历史日降水序列不足 `geo_partial_days_min` 天返回 `PARTIAL`,仍输出可用结果。 - **气象输入**:过去 24h 逐小时实况、2h 短临(5min)、未来 72h 逐小时预报、15~30 天历史日降水序列。 ### 输出字段 `unitId / village / lon / lat / elevation`、`validTime`、`S`、`T`、`H/E/V/C`、`R / riskLevel / color`、`factors`(当日降水 R₀、短期/长期有效降水、预警线/危险线临界值、曲线位置比 d)、`triggerType`(短期强降水型 / 长期累积型 / 无触发)、`leadTimeMin`、`lagWindowMin`、`lagApplied`、`metQuality`、`hazardKind`、`siteType`、`status`。 ### 数据表(共享数据管理后台维护) | 表 | 用途 | |---|---| | `geo_hazard_site` | 隐患点 / 斜坡单元台账:易发性 S、E/V/C、曲线分区、`POINT SRID 4326` 空间点位 | | `geo_hazard_curve` | 分区临界雨量曲线:预警线 / 危险线基准、下移斜率 γ、K、n、滞后时长、风险下限 | | `geo_hazard_daily_rainfall` | 15~30 天历史日降水序列,用于 `R_eff` | | `sys_risk_config` | `hazard_type='GEO_HAZARD'` 的 16 项全局可率定参数(与山洪共用同一张表) | 初始化脚本:`src/main/resources/db/init_geo_hazard.sql`。三张表均已注册到 `AdminTableRegistry`,管理端可按灾种筛选,地图视图新增「地灾隐患点」图层。 ### 预设验证场景 `GET /api/risk/geo-hazard/scenarios` 返回 6 个场景:晴朗干燥、小雨、短时强降水、长期累积降雨、久雨初晴(滞后)、气象数据缺测。`target/dbinit/verify_geo_hazard.py` 端到端验证 73 项,短时强降水场景下 6 个隐患点覆盖蓝/黄/橙/红四级(`low:2 / medium:2 / high:1 / extremelyHigh:1`),并验证 S 主导、有险无灾、公式一致性、曲线动态下移、滞后延续与缺测阻断。 ## 森林火灾动态风险评估模型(技术方案 V1.0) 模型依据 `森林火灾动态风险评估模型技术方案.md` 实现,复用统一四要素内核,但致灾驱动由「降水」改为「降水缺失 + 高温低湿大风」: ``` D = 自上一次有效降水以来的连续无有效降水日数(久旱慢升、一雨快降) FWI = wT·f(T) + wRH·f(RH) + wW·f(W) + wD·f(D) (风速非线性放大) F = FWI × 当日降水抑制 B = 可燃物—地形静态本底易燃性(台账预计算,缺值时由类型/负荷/坡度/坡向/连续性合成) H = B × F R = H × E × V / (1 + C) ``` | 维度 | 说明 | |---|---| | 输入 | 过去 24h 逐小时气温 / 湿度 / 风速 / 降水实况 + 未来 72h 逐小时预报 + 历史日降水序列 | | 动态机制 | 连续干燥度单调累积抬升火险;一场有效降水清零 D 并快速回落(慢升快降非对称) | | 气象等级 | F 映射国标火险气象等级一至五级;与综合风险等级 R 是两个不同概念 | | 产品字段 | B / F / FWI / H / E / V / C / R、met_grade、dominant_factor、peak_hours、spread_dir、过去 24h 与未来 72h 逐小时 FWI 序列 | | 状态 | `OK` / `PARTIAL`(历史日序列不足)/ `MET_MISSING`(关键气象缺测,不输出风险) | | 保护 | 重点防护对象(景区 / 重大设施 / 林缘聚落)在 F 达高位时启用风险下限,避免降级漏警 | | 表 | 用途 | |---|---| | `forest_fire_stand` | 网格 / 林班台账:可燃物类型与负荷、坡向、本底 B、E/V/C、火险分区、`POINT SRID 4326` 点位 | | `forest_fire_zone` | 分区 FWI 权重、归一化节点、有效降水阈值、五级火险等级节点与风险下限 | | `forest_fire_daily_met` | 30 天历史日气象序列,连续干燥日数统计来源;可在前端切换为自动统计 | | `sys_risk_config` | `hazard_type='FOREST_FIRE'` 的 29 项全局可率定参数(与山洪 / 地灾共用同一张表) | 初始化脚本:`src/main/resources/db/init_forest_fire.sql`。三张表均已注册到 `AdminTableRegistry`,管理端可按灾种筛选,地图视图新增「森火单元」图层。后端分层与山洪 / 地灾一致:`ForestFireRiskModel`(纯算法内核)→ `ForestFirePlugin` → `RiskComputeEngine` → `ForestFireAssessmentService` → `ForestFireRiskController`。 接口:`GET /api/risk/forest-fire/stands|zones|params|scenarios`、`GET|POST /api/risk/forest-fire/assess/...`、`POST /api/risk/forest-fire/assess/custom/all`。全量评估只提交火险气象场景输入,B/E/V/C 按各单元台账读取,保留单元间差异。 ### 预设验证场景 `GET /api/risk/forest-fire/scenarios` 返回 8 个场景:雨后湿润、常规防火期、连旱高温、久旱大风、一雨解旱、稀疏可燃物、历史序列不足、气象数据缺测。`target/dbinit/verify_forest_fire.py` 端到端验证 64 项,`target/dbinit/test_forest_fire_runtime.js` 验证前端初始化、场景切换、参数作用域与图表降级。 ## 中小河流域洪涝动态风险评估模型(Q × S) 依据《中小河流域洪涝动态风险评估模型技术方案 V1.0》,以县域 / 河段控制单元为评估尺度,把「上游集水区产流致洪」与「河道承泄不足」拆成动态量 Q 与静态量 S: ``` API = Σ(Pᵢ × kⁱ) 前期影响雨量(流域湿润程度) C_r = max(C_min, C₀ × (1 − γ × API_norm)) 动态临界面雨量(越湿越易致洪) φ = φ₀ + φ₁ × API_norm 产流系数(越湿产流越多) ratio = P_acc × φ / C_r 来水相对致洪阈值的位置 Q = 分段归一化(ratio) + 上游演进来水 动态致洪危险度(含汇流滞后) S = 河道承泄不足度(静态本底,预计算缓存) H = Q × S R = H × E × V / (1 + C) ``` | 维度 | 说明 | |---|---| | 输入 | 5min 降水实况、0~2h 短临、过去 24h 逐小时面雨量实况、未来 72h 逐小时预报、历史日面雨量序列 | | 动态机制 | API 下调临界面雨量并抬升产流系数;上游 Q_local 按汇流时间滞后演进;雨停后按 exp(−Δt/τ) 退水延续,风险不立即清零 | | 防汛语义 | Q 映射「低于警戒水位 → 接近 / 超警戒 → 超保证水位 / 漫堤风险」,与四级综合风险等级并行输出 | | 产品字段 | Q / Q_local / S / H / E / V / C / R、P_acc、maxRain 3/6/12h、API、C_r、φ、估算来水、waterLevelRef、triggerType、peakTime、leadTimeMin、recessionWindowMin、upstreamContrib、过去 24h 与未来 72h Q 序列 | | 状态 | `OK` / `PARTIAL`(历史日面雨量不足)/ `MET_MISSING`(上游集水区面雨量缺测,不输出风险) | | 保护 | 穿城镇 / 重大保护对象河段 Q 高位时启用风险下限;无人区且 E 极低时折减,区分「有洪无灾」 | | 表 | 用途 | |---|---| | `river_flood_reach` | 河段控制单元台账:河流 / 河段 / 上下游拓扑 `upstream_ids`、汇流与传播时间、过流能力、堤防标准、承泄不足度 S、E/V/C、`POINT SRID 4326` 点位 | | `river_flood_zone` | 水系分区参数:API 消退、动态临界面雨量、Q 分段节点、退水时间常数、上游演进衰减、风险下限 | | `river_flood_daily_rain` | 30 天历史日面雨量序列(API 来源) | | `sys_risk_config` | `hazard_type='RIVER_FLOOD'` 的 30 项全局可率定参数(与其余灾种共用同一张表) | 初始化脚本:`src/main/resources/db/init_river_flood.sql`。三张表均已注册到 `AdminTableRegistry`,管理端可按灾种筛选,地图视图新增「洪涝河段」图层。后端分层与其余灾种一致:`RiverFloodRiskModel`(纯算法内核)→ `RiverFloodPlugin` → `RiskComputeEngine` → `RiverFloodAssessmentService` → `RiverFloodRiskController`;沿有向河网自上而下递归计算上游 `Q_local`,按 `travelTimeH + confluenceTimeH × 0.3` 形成汇流滞后。 接口:`GET /api/risk/river-flood/reaches|reaches/{id}|zones|params|scenarios`、`GET|POST /api/risk/river-flood/assess/...`、`POST /api/risk/river-flood/assess/custom/all`。全量评估只提交面雨量场景输入,S/E/V/C、临界雨量与河网拓扑按各河段台账读取,保留河段间差异(`RiverFloodAssessRequest.copyForReach()`)。 ### 洪涝预设验证场景 `GET /api/risk/river-flood/scenarios` 返回 9 个场景:枯水无雨、常规汛期、短历时强降水、长历时累积、前期湿润、上游暴雨下泄、雨停退水延续、历史序列不足、面雨量缺测。`target/dbinit/verify_river_flood.py` 端到端验证模型机理与管理端接入,`target/dbinit/test_river_flood_runtime.js` 验证前端初始化、场景切换、参数作用域与图表降级。 ## 城市内涝动态风险评估模型(Q × D) 依据《城市内涝动态风险评估模型技术方案》,以县域城区 / 排水分区 / 易涝点为评估尺度,把「短历时强降水超管网设计标准」与「排水能力不足」拆成动态量 Q 与静态量 D。与流域洪涝不同,内涝不用面雨量—API—临界面雨量,而用**就地短历时雨强与重现期超出度**判别,且提前量最短(默认 ≤ 120min): ``` I_10 / I_30 / I_1h = 5min 实况 + 0~2h 短临拼接后的多历时滑动最大雨强 (mm/h) ratio = max(I_t / I_design,t) 相对各历时管网设计雨强的超出度 Q = 分段归一化(ratio × exp(−Δt/τ)) 动态致涝危险度(低于设计标准 Q=0) τ = τ₀ + τ₁ × D 排水越差,雨停后退水越慢(快涨快退) D = 排水能力不足度(台账预计算;为空时按设计重现期 / 低洼 / 硬化 / 淤堵 / 历史积水加权合成) H = Q × D 雨再大若排水强则不涝,排水再弱若无强降雨也不积水 R = H × E × V / (1 + C) ``` | 维度 | 说明 | |---|---| | 输入 | 近 60min 逐 5min 降水实况、未来 0~2h 逐 10min 短临预报、过去 24h 逐小时实况、未来 72h 逐小时预报 | | 动态机制 | 短临与实况峰值按权重融合(默认 0.65 / 0.35)并保留实况峰值下限;0~2h 短临是提前量的唯一来源;雨停后按 `exp(−Δt/τ)` 消退而非立即清零 | | 主导历时 | 10min 突发型 / 30min 过渡型 / 1h 持续型,与综合风险等级并行输出 | | 防汛语义 | 积水深度语义由实际致涝危险性 `H = Q × D` 分级:无明显积水 → 轻微积水影响通行 → 较深积水车辆受困 → 深积水地下空间倒灌;估算积水深度 (m) 同样由 H 与低洼深度推算,避免「雨大但排水能力强」的高标准分区误报深积水 | | 产品字段 | Q / D / H / E / V / C / R、I_10 / I_30 / I_1h、峰值雨强、超出度、实际/设计重现期、主导历时、waterDepthRef、pondingDepthEstimateM、peakTime、leadTimeMin、recessionWindowMin、`observedQ` / `nowcastQ` 演变序列 | | 状态 | `OK` / `PARTIAL`(短临时次 < 6 或逐小时实况 < 12h)/ `MET_MISSING`(5min 实况或 0~2h 短临缺测,不输出风险) | | 保护 | 下穿隧道、地下空间、医院学校、变配电等要害对象采用更严格 Q 阈值与风险下限 `minRiskKeyObject`,避免降级漏警 | | 表 | 用途 | |---|---| | `urban_waterlogging_site` | 易涝点 / 排水分区台账:对象类别、街道、低洼深度、硬化率、设计重现期与 10min/30min/1h 设计雨强、泵站能力、淤堵顶托、历史积水、排水不足度 D、E/V/C、要害标记、`POINT SRID 4326` 点位 | | `urban_waterlogging_zone` | 排水分区参数:Q 分段节点、重现期换算指数、退水时间常数(τ 随 D 增大)、提前量上限、要害对象下限、D 合成权重与积水深度语义节点 | | `urban_waterlogging_ponding_record` | 历史积水事件(最大积水深度 / 历时 / 过程峰值雨强),校正台账 D 合成的积水本底 | | `sys_risk_config` | `hazard_type='URBAN_WATERLOGGING'` 的 27 项全局可率定参数(与其余灾种共用同一张表) | 初始化脚本:`src/main/resources/db/init_urban_waterlogging.sql`。三张表均已注册到 `AdminTableRegistry`,管理端可按灾种筛选,地图视图新增「城市易涝点」图层。后端分层与其余灾种一致:`UrbanWaterloggingRiskModel`(纯算法内核)→ `UrbanWaterloggingPlugin` → `RiskComputeEngine` → `UrbanWaterloggingAssessmentService` → `UrbanWaterloggingRiskController`。参数优先级:前端调试覆盖 > `urban_waterlogging_zone` 分区参数 > `sys_risk_config` 全局配置 > 内置默认值;全量评估只提交短历时降水场景输入,D/E/V/C 与设计雨强按各点位台账读取(`UrbanWaterloggingAssessRequest.copyForSite()`),保证同一降雨过程下各易涝点风险互不相同。 接口:`GET /api/risk/urban-waterlogging/sites|sites/{id}|zones|params|scenarios|records/{siteId}`、`GET|POST /api/risk/urban-waterlogging/assess/...`、`POST /api/risk/urban-waterlogging/assess/custom/all`。 ### 内涝预设验证场景 `GET /api/risk/urban-waterlogging/scenarios` 返回 10 个场景:无雨晴好、小雨低于设计、接近设计标准、10min 突发暴雨、1h 持续强降水、特大暴雨超设计、要害对象优先叫应(自动定位 `UW_002`)、雨停退水延续、短临序列不足(`PARTIAL`)、短临降水缺测(`MET_MISSING`)。场景雨强按 `UW_002`(1 年一遇,1h 设计雨强 18 mm/h)标定,使 Q 依次落在「低于设计 Q=0 / 接近设计 0~0.6 / 超设计 0.6~1.0 / 远超设计 Q=1」各分段,避免所有降雨场景一律饱和而看不出梯度。`target/dbinit/verify_urban_waterlogging.py` 端到端验证模型机理与管理端接入,`target/dbinit/test_urban_waterlogging_runtime.js` 验证前端初始化、场景切换、参数作用域与图表降级。 ## 行政区域综合风险动态评估模型(两级聚合 · CRI) > 参考 `自然灾害综合风险动态评估技术方案.md`。本模块位于五个单灾种模块**之上**:评估对象由「小流域 / 斜坡 / 林班 / 河段 / 易涝点」升级为**行政区域**(县 `COUNTY` → 乡镇/街道 `TOWNSHIP` → 村/社区 `VILLAGE`),输入是「多灾种联动场景 + 合成口径」,不直接接收气象致灾因子。 ### 计算链路 ``` POST /api/risk/comprehensive/assess/custom/all │ {scenario, method, adminLevel, horizon, includeHazards, paramOverrides} ▼ ComprehensiveScenarios ── 展开成 5 个单灾种场景输入 │ ├─ FlashFloodAssessmentService.assessAll(...) ├─ GeoHazardAssessmentService.assessAll(...) ├─ ForestFireAssessmentService.assessAll(...) ├─ RiverFloodAssessmentService.assessAll(...) └─ UrbanWaterloggingAssessmentService.assessAll(...) ▼ RiskAssessmentResult(单元级 R + timeline)→ ComprehensiveUnitRisk ▼ ① 行政区域—单元静态映射(跨界按 ratio 面积占比拆分) 村级 R(a,h) ──► ② 乡镇级 R(a,h) ──► ③ 县级 R(a,h)(逐级汇总,口径自洽) ▼ 第二级合成 CRI / 等级 / 排序 / 主导灾种 / 贡献度 / 并发灾种 / CRI(t) / 态势简报 ▼ ComprehensiveResultStore(结果快照落库 + 内存最近 N 轮历史) ``` ### 第一级:单元风险 → 行政区域单灾种风险 ``` R(a,h) = w_max · R_max + w_cov · R_cov + w_ρ · ρ ``` | 分量 | 含义 | 默认权重 | |------|------|---------| | `R_max` | 强度分量:辖区内该灾种单元风险峰值(宁高勿平) | `w_max = 0.55` | | `R_cov` | 广度分量:按单元暴露人口加权的风险均值 | `w_cov = 0.30` | | `ρ` | 高危单元占比(单元风险 ≥ `cr_high_threshold`) | `w_ρ = 0.15` | 三权重由 `ComprehensiveModelParams.normalizeAggregation()` 归一到和为 1。辖区内无该灾种评估单元,或该灾种 `MET_MISSING`,记为**缺项**(`present=false`),不按零风险计入。 ### 第二级:区域单灾种风险 → 多灾种综合指数 | 方法 | 公式 | 说明 | |------|------|------| | `WEIGHTED` | `CRI = Σ_h [λ_h · R(a,h)]` | 加权综合,各灾种线性可偿 | | `MAX_WEIGHTED`(默认) | `CRI = α·max_h R(a,h) + (1−α)·Σ_h[λ_h·R(a,h)]` | 取大加权混合,突出主导灾种,`α=0.45` | | `PROBABILISTIC` | `CRI = 1 − Π_h (1 − λ_h·R(a,h))` | 概率型合成,多灾并发时非线性放大 | `λ_h` 来自**区域灾种权重模板**,按行政区孕灾环境选择,参与灾种间重新归一:`BALANCED` / `MOUNTAIN` / `URBAN` / `FOREST` / `RIVER_VALLEY`,另有 `admin_code` 级微调行。 并发叠加与一致性校验: ``` CRI_final = CRI · (1 + γ·(n_high − 1)) γ = 0.08,截断到 [0,1] 综合等级 ≥ 主导灾种等级 − consistency_gap 默认 gap = 1(只上调等级,不改 CRI 数值) ``` `n_high` 为该区域达到 Ⅲ/Ⅳ 级的灾种数;主导灾种取 `contrib_h = λ_h·R(a,h) / Σ` 最大者,贡献度只在**参与合成**的灾种间计算,缺项灾种不进入集合。 ### 分级、排序与缺项 - 绝对四级:`<0.25` Ⅰ 低 / `[0.25,0.50)` Ⅱ 较高 / `[0.50,0.75)` Ⅲ 高 / `≥0.75` Ⅳ 极高,阈值 `cr_level_1/2/3` 可率定。 - 相对分级:同级行政区按 CRI 降序给出 `rank / rankTotal / percentile / relativeLevel`,支持跨区域横向比较。 - 状态:`OK`(五灾种齐备)/ `PARTIAL`(有缺项)/ `MET_MISSING`(全部缺测)。缺项灾种在研判卡、灾种构成条与时间轴明细中显式标注「不参与合成」。 ### 多时效对齐 CRI(t) 各单灾种时间轴粒度不同(内涝 5/10min、洪涝/森火 1h、山洪/地灾逐小时面雨量),综合层统一重采样为 **4h 时间桶**,`−24h ~ +72h` 共 **25 个节点**,同桶取最不利值,缺测节点丢弃不冒充零风险。每个节点输出 `CRI(t)`、等级、并发灾种数 `nHigh`、各灾种 `R(a,h,t)` 与 `missingHazards`;峰值节点 CRI 与总体 CRI 一致。 ### 数据表(`db/init_comprehensive.sql`,幂等) | 表 | 用途 | 初始化行数 | |----|------|-----------| | `comprehensive_admin_region` | 行政区台账:三级本底、人口 / 资产 / 重点防护对象 / 历史灾情 / 应急资源评分、权重模板、示意边界 WKT、`POINT SRID 4326` 中心点 | 26(1 县 + 6 乡镇 + 19 村) | | `comprehensive_region_unit` | 行政区—单灾种评估单元静态映射(跨界 `ratio` 拆分 + 暴露人口) | 34 | | `comprehensive_region_hazard_weight` | 区域灾种权重模板 λ_h(`template` 默认行 + `admin_code` 微调行) | 25 | | `comprehensive_risk_result` | 综合风险结果快照(`batch_id + admin_code` 唯一键,管理端只读,按批次保留最近 N 轮) | 由评估流程写入 | `sys_risk_config(hazard_type='COMPREHENSIVE')` 另插入 **16 条 `cr_*`** 可率定参数。运行时优先级:`paramOverrides` > `sys_risk_config` > 内置默认值;台账 / 映射 / 权重由 `ComprehensiveRepositoryImpl` 读 MySQL,数据库不可达时回退内置演示数据(5s 短缓存 + 60s 失败熔断,避免逐次远程往返)。`boundary_wkt` 为演示用规则多边形,生产应替换为真实行政区划边界。 ### 预设场景(8 个多灾种联动) | key | 场景 | 预期主导灾种 / 特征 | |-----|------|-------------------| | `normal` | 常态汛期 | 流域洪涝,县域 CRI ≈ 0.043 | | `dry_calm` | 晴朗无雨 | 全域低风险,CRI ≈ 0.009 | | `mountain_rainstorm` | 山区局地暴雨 | 山洪 / 地灾抬升 | | `urban_cloudburst` | 城区短历时强降水 | 城市内涝主导 | | `basin_flood` | 流域性持续降水 | 洪涝主导,CRI ≈ 0.626 | | `forest_drought` | 林区连旱大风 | 森林火险主导 | | `multi_hazard` | 多灾并发极端过程 | 并发修正生效,CRI ≈ 0.627 | | `data_gap` | 森林火险气象缺测 | `FOREST_FIRE` 缺项、`status=PARTIAL`、参与 4 类并重新归一 | ### 前端展示(`comprehensive-risk.html`) - **综合风险一张图**:`js/comprehensive-region-map.js` 用高德官方 SDK 把 `boundary_wkt` 转 GCJ-02 后分级着色,支持县→乡镇→村下钻、等级过滤、点击联动研判卡;未配 Key / SDK 失败时降级为「空间数据清单」,不影响评估。 - **分布视图**:卡片列表 / 一张图 / 风险矩阵三态互斥;CRI(t) 时间轴是分布面板**之外**的独立常显面板(与五灾种页面一致)。 - **应用组件**:行政区域清单、同级排行榜、区域综合研判卡、各灾种 R(a,h) 与贡献度双条、综合态势简报、主导灾种分布、跨轮次风险演变;「⏱ 风险时间轴」快捷入口与 `?view=timeline` 只滚动定位。 - **调试台**:合成方法、排行榜层级、时效窗、参与灾种开关、第一级三权重、α/γ/阈值及四个规则开关;`collectOverrides()` 只提交偏离 HTML 默认值的键,重置恢复默认。 - 所有图表用本地 `echarts.min.js`,缺失时降级为文本 / 明细表;全站静态资源版本 `?v=20261116c`。场景选项卡的 `tag` 是「山洪+地灾」这类中文短标签而非图标,字体样式由 `comprehensive.css` 中 `#cr-scenarios` 作用域单独定义(10px 徽标 + 12px/600 主名称),**不要**套用山洪页 `.scenario-icon` 的 22px 大图标样式。 ### 逐时刻全行政区域风险回放 综合风险页复用通用组件 `js/risk-timeline-scrubber.js`(`window.RiskTimelineScrubber`),在「综合风险一张图」分布面板内、卡片网格之前提供 ▶ 播放 / ⏸ 暂停 / 滑块拖动 / ↩ 总体 四类控制,用于横向查看**同一时刻多个行政区域**的 CRI 与等级。轨道与五灾种页共用同一套「时刻格子」:每格标注 HH:mm、跨天补 MM-dd,顶部色条为该时刻全场最高 CRI 等级颜色,角标为达到该等级的行政区域数(全部缺测为灰条且不显示角标)。25 个时间桶按容器宽度分页显示,‹ › 翻页查看其余时刻,轨道不会撑出页面横向滚动条。 - **统一时间桶**:后端每个行政区域的 `CRI(t)` 只覆盖实际有单灾种数据的桶(长度可能是 1 / 2 / 13 / 25,且 `slotIndex` 是压缩序号而非桶号)。页面按 `hourOffset` 把每个区域重采样成 `−24h ~ +72h` 的稠密 25 桶,缺桶标 `NO_TIMELINE`;**绝不按数组下标对齐**,否则会把 A 区的 −24h 和 B 区的 0h 放进同一帧。县级与乡镇级(默认展示层)均为完整 25 桶。 - **字段适配**:`cri / level / levelName / color` 映射成组件约定的 `riskValue / riskLevel`;帧行再归一回综合字段,并按该时刻 `hazardRisks` 重算灾种构成条、主导灾种与并发 / 缺项清单。 - **联动范围**:卡片列表、行政区域清单、同级排行榜、四级统计、区域研判卡、灾种构成条、「一张图」分级着色全部随帧刷新;回放时按该时刻 CRI 重排并给出帧内位次,卡片标注「逐时刻」与该时刻。 - **与单点曲线互补**:下方独立 CRI(t) 面板仍是「当前选中区域的整场过程曲线」,回放期间不逐帧重绘(避免图表闪烁),只在头部提示当前帧与该区域 CRI;曲线始终取后端原始节点,不因补桶画出「假零风险」谷值。 - **文案可配置**:通用组件新增 `title / hint / unitLabel / emptyText / modeOverall` 选项,默认值仍是「全部点位 / 个点位 / 总体风险」,五个单灾种页不传即保持原样;综合页传「全部行政区域 / 个行政区域 / 总体综合风险」。 - **零额外请求**:帧数据全部来自 `POST /assess/custom/all` 响应内联的 `results[i].timeline`;结果刷新时 `update()` 重建帧序列并保留正在播放的帧索引。 ### 主要接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/comprehensive/regions`、`/regions/{code}` | 行政区台账(三级、含边界 WKT) | | GET | `/api/risk/comprehensive/units` | 行政区—单灾种单元映射 | | GET | `/api/risk/comprehensive/params`、`/weights`、`/scenarios` | 生效参数 / 权重模板 / 8 个联动场景 | | **POST** | `/api/risk/comprehensive/assess/custom/all` | **前端主数据源**:全县三级 26 条结果 + 排行榜 + 简报 + 版本戳 | | POST | `/api/risk/comprehensive/assess/custom` | 单行政区域研判卡 | | GET | `/api/risk/comprehensive/assess/all`、`/assess/{code}` | 默认场景快速评估 | | GET | `/api/risk/comprehensive/ranking`、`/summary`、`/history` | 最近一轮排行榜 / 态势简报 / 跨轮次历史 | 响应类型刻意使用独立的 `ComprehensiveAssessmentResponse`(不复用 `AssessmentResponse` / `RiskAssessmentResult`),避免被 `RiskTimelinePersistenceAdvice` 按单灾种口径误落库;快照由 `ComprehensiveResultStore` 用单条多值 `INSERT ... ON DUPLICATE KEY UPDATE` 自行落库,失败只告警并降级为内存历史。 ### 验证 - 后端:`target/dbinit/verify_comprehensive.py`(58 项:台账 / 8 场景 / 三级汇总 / 三种合成方法 / 并发与一致性 / 缺项 / CRI(t) 25 桶 / 单区域 / 榜单 / 简报 / 历史 / 管理端四表) - 前端:`target/dbinit/test_comprehensive_runtime.js`(DOM mock:初始化 / 六个面板 / 时间轴降级 / 三态切换 / 地图降级 / 三级下钻 / 层级过滤 / 参数作用域 / 场景联动 / 缺项展示) - 逐时刻回放:`target/dbinit/verify_comprehensive_scrubber.py`(31 项:页面结构 / 适配层 / 通用组件向后兼容 / 后端 CRI(t) 桶覆盖与多区域差异 / 版本一致)、`test_comprehensive_scrubber.js`(28 项 DOM mock:25 帧构造 / 稀疏区域补桶 / 帧内排序与横向对比 / 播放暂停拖动重置 / 单点曲线不补零) - 纯算法单测:`src/test/java/com/fysb/risk/engine/ComprehensiveRiskModelTest.java`(11 例:三分量聚合 / 缺项标记 / 4h 时间桶对齐 / 三种 CRI 合成 / 并发放大 / 一致性校验 / 贡献度归一 / 分位数排序 / 权重归一);`mvn -o test` 全量 30 例通过、0 失败。 - 原有模块回归:`verify_timeline_scrubber.py` 226 项 / `verify_result_views.py` 194 项 / `verify_risk_timeline.py` 275 项,均 0 失败。 ## 逐时间节点风险评估结果(R(t)) ### 背景 此前五个灾种都把整段时间序列压缩成一个最终总体风险 R;已有的 `hourlyQ` / `forecastQ` / `observedQ` / `nowcastQ` / `hourlyFwi` / `forecastFwi` 只是**致灾驱动量 Q / FWI**,不是风险 R;`risk_assessment_result` 表虽存在但全项目没有写库代码,一直是空表。本章的能力解决了三件事:**每个时间节点都算出完整 H/E/V/C/R 与等级**、**响应直出**、**自动落库可回溯**。 ### 计算方式 统一内核 `RiskComputeEngine` 仍只负责整场过程聚合后的单值结果;时间维度由纯算法类 `RiskTimeline` 展开,用**同一个**四要素公式,不重复实现灾种机理: ``` H(t) = H_final × driver(t) / max(driver) R(t) = clamp01( H(t) × E × V / (1 + C) ) ``` - `driver(t)` 是该时间节点的致灾驱动量,峰值节点的 `H(t)` 等于最终总体危险性 `H`,保证过程曲线与总体结果自洽,不会出现「过程峰值高于总体风险」。 - `E` / `V` / `C` 在短时段内属评估单元固有属性,逐点保持不变。 - 最终结果若额外叠加「在册隐患点 / 要害对象风险下限」保护,最终 R 会略高于时间轴峰值 R,属预期行为。 各灾种自适应时间轴(优先复用内核已算出的逐时次序列,山洪 / 地灾回放 `MetData` 逐小时面雨量实况与预报): | 灾种 | 时间轴 | 粒度 | 驱动量 | |---|---|---|---| | 城市内涝 | 近 60min 实况 + 未来 0~2h 短临 | 5min / 10min | `observedQ` / `nowcastQ` | | 流域洪涝 | 过去 24h 涨水段 + 未来 0~72h 演进(含退水延续) | 1h | `hourlyQ` / `forecastQ` | | 森林火灾 | 过去 24h 实况 + 未来 0~72h 预报 | 1h | `hourlyFwi` / `forecastFwi` | | 山洪 / 地质灾害 | `MetData` 逐小时面雨量实况 + 预报 | 1h | 逐小时面雨量 (mm) | 每个节点带 `phase`(`OBSERVED` / `NOWCAST` / `FORECAST` / `CURRENT`)、`driverName`、`driverValue`、完整四要素、R、四级等级、颜色、`status` 与归属 `unitId` / `hazardType`。`MET_MISSING` / `PARAM_ERROR` / `COMPUTE_ERROR` 时**仍输出节点留痕**,但 R=0、等级为 null、状态明确标注,绝不冒充低风险;`PARTIAL` 正常绘制但标注置信度降低。 ### 数据表与落库策略 `src/main/resources/db/init_risk_timeseries.sql` 幂等新增两张表,并复用既有 `risk_assessment_result`: | 表 | 用途 | 关键字段 / 索引 | |---|---|---| | `risk_assessment_batch` | 一次评估 = 一个批次,含各单元最终总体风险快照 JSON | 主键 `batch_id`;`(hazard_type, assessment_time)` | | `risk_assessment_timeseries` | 每个单元每个时间节点一行,含完整 H/E/V/C/R 与等级 | 唯一键 `(batch_id, unit_id, slot_index)`;`(hazard_type, unit_id, slot_time)` | | `risk_assessment_result` | 既有主表,补写各单元最终总体风险快照 | 用 `met_version = 'batch:<批次UUID>'` 关联批次,不改表结构,随批次清理 | `ResultPersistenceService` 由 `RiskTimelinePersistenceAdvice`(`ResponseBodyAdvice`)在评估响应写出前统一调用,因此五个灾种共 20 余个单点 / 全量 / 自定义端点**无需逐个改 Controller**;响应对象同时回填 `batchId`,前端一次请求即可同时拿到结果与批次号。持久化异常只记 warn,绝不阻断评估响应;mock 模式或数据库不可达时自动降级为内存存储,查询接口仍可用。 - **节流**:同一灾种在 `risk.timeline.min-interval-seconds`(默认 30s)内复用同一 `batch_id`,明细按唯一键 UPSERT,避免「实时评估」滑杆刷爆数据库。 - **保留**:每个灾种只保留最近 `risk.timeline.keep-batches`(默认 20)个批次,写入后清理更早批次及其明细 / 主表快照,数据量有界。 - **性能**:明细与主表快照均为**单条多值 `INSERT ... ON DUPLICATE KEY UPDATE`**(参数全部绑定,只拼接 `(?,?,…)` 占位符),把逐行网络往返压成一次。远程 MySQL 下逐行写入曾让全量评估劣化到 7.7~27.2s;改造后实测五灾种全量评估 0.30~3.83s,A/B 对照(禁用持久化)测得落库净开销仅 **0.33~0.67s**。 配置(`application.yml`): ```yaml risk: timeline: enabled: true # 关闭后仍返回内联 timeline,但不落库 keep-batches: 20 min-interval-seconds: 30 ``` ### 查询接口 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/risk/timeline/summary` | 存储状态:是否启用、存储后端(MYSQL / MEMORY)、保留批次、节流窗口 | | GET | `/api/risk/timeline/batches` | 批次列表,可带 `hazardType`,按时间倒序 | | GET | `/api/risk/timeline/latest` | 最近一次评估的时间节点,可带 `hazardType` / `unitId` / `limit` | | GET | `/api/risk/timeline/points` | 通用明细查询:`batchId` / `hazardType` / `unitId` 任意组合 | | GET | `/api/risk/timeline/batch/{batchId}` | 指定批次全部时间节点,可带 `unitId` | ### 前端 R(t) 曲线(风险分布面板外的独立单点信息面板) `js/risk-timeline-chart.js` 暴露 `window.RiskTimelineChart`,五个评估页面共用,脚本顺序固定为「组件早于页面主逻辑」。**时间轴是「风险分布面板」之外的独立单点信息面板**:位于分布面板下方、与四要素剖面 / 致灾因子明细等单点面板并列常显,容器 id 为 `index-timeline-view` / `geo-timeline-view` / `ff-timeline-view` / `rf-timeline-view` / `uw-timeline-view`,带 `data-timeline-panel="1"`,**不设 `hidden`、不参与视图切换**。分布面板工具栏提供「卡片列表 / 地图 / 风险矩阵」三态;每次评估结果刷新或切换选中单元,页面调用 `renderRiskTimelineFromResults()` 重绘当前单元的 R(t) 并重算画布尺寸,容器始终可见,不存在隐藏容器里初始化导致画布宽度为 0 的问题。 **入口与直达链接**:顶部 `.top-stats` 工具栏的「⏱ 风险时间轴」按钮由 `js/risk-timeline-quick.js`(`window.RiskTimelineQuick`)统一联动,点击后**滚动定位**到下方独立面板并重算曲线尺寸,不改变「卡片列表 / 地图」视图;`<页面>.html?view=timeline`(如 `index.html?view=timeline`)直达链接同样定位到该面板,便于演示与分享。五个页面 `` 另有 no-cache meta,所有本地 JS/CSS 引用带 `?v=` 版本号,避免预览面板或浏览器复用旧页面。 主系列为风险 R(t),可叠加 H(t) / E / V / C,标注 0.25 / 0.50 / 0.75 四级阈值与峰值,按相位用浅色背景划分实况 / 短临 / 预报段;下方同时输出「逐时间节点明细表」(时刻 / 相位 / 驱动量 / H/E/V/C / R(t) / 等级 / 状态)。只依赖本地 ECharts 副本,图表库缺失时降级为明细表,绝不阻断评估流程。每页提供「查看已落库批次」按钮,调用 `/api/risk/timeline/latest` 回放历史结果。 验证:`target/dbinit/verify_risk_timeline.py`(覆盖五灾种响应内联 timeline、公式一致性、时间升序与相位、峰值、缺测语义、批次与三表落库、查询接口、节流、管理端注册、五页独立时间轴面板与三态切换)与 `target/dbinit/test_risk_timeline_runtime.js`(覆盖曲线配置、明细表、缺测断点、ECharts 缺失降级、历史批次查询)。 ## 项目结构 ``` dynamic-risk-assessment-agent/ ├── src/main/java/com/fysb/risk/ │ ├── RiskAssessmentApplication.java # Spring Boot 启动类 │ ├── controller/ # REST API 控制层 │ │ ├── FlashFloodRiskController.java │ │ ├── GeoHazardRiskController.java # 地质灾害评估接口 │ │ ├── ForestFireRiskController.java # 森林火灾评估接口 │ │ ├── RiverFloodRiskController.java # 流域洪涝评估接口 │ │ ├── UrbanWaterloggingRiskController.java # 城市内涝评估接口 │ │ ├── RiskTimelineController.java # 逐时间节点风险结果查询接口 │ │ ├── RiskTimelinePersistenceAdvice.java # 评估响应写出前统一落库切面 │ │ ├── ComprehensiveRiskController.java # 行政区域综合风险评估接口 │ │ ├── SystemController.java # 系统信息 / 六模块注册表 │ │ ├── RiskConfigController.java # 配置管理接口 │ │ └── AdminController.java # 管理端通用 CRUD 接口 │ ├── admin/ # 管理端白名单元数据 + 通用数据服务 │ │ ├── AdminTableMeta.java │ │ ├── AdminTableRegistry.java # 29 张可维护表注册(含山洪气象 / 综合风险 / 时间轴) │ │ └── AdminDataService.java │ ├── service/ # 业务服务层 │ │ ├── RiskAssessmentService.java # 服务接口 │ │ ├── RiskConfigService.java # 配置加载/同步/刷新 │ │ ├── GeoHazardConfigService.java # 地灾分区曲线参数 │ │ ├── ForestFireConfigService.java # 森火全局 + 分区参数解析 │ │ ├── RiverFloodConfigService.java # 洪涝全局 + 水系分区参数解析 │ │ ├── UrbanWaterloggingConfigService.java # 内涝全局 + 排水分区参数解析 │ │ ├── GeoHazardAssessmentService.java │ │ ├── ForestFireAssessmentService.java │ │ ├── RiverFloodAssessmentService.java # 河网级联与洪水演进 │ │ ├── UrbanWaterloggingAssessmentService.java # 5min 实况 / 0~2h 短临拼接与演变时序 │ │ ├── ResultPersistenceService.java # 逐时间节点风险结果落库(批次 / 明细 / 主表快照) │ │ ├── ComprehensiveConfigService.java # cr_* 参数解析(覆盖 > 数据库 > 内置默认) │ │ ├── ComprehensiveAssessmentService.java # 单灾种编排 + 两级聚合 + 排序 / 简报 │ │ └── ComprehensiveResultStore.java # 综合风险快照落库 + 跨轮次内存历史 │ │ └── impl/ │ │ └── FlashFloodAssessmentService.java │ ├── engine/ # 统一计算引擎 │ │ ├── RiskComputeEngine.java # R = H×E×V/(1+C) 核心 │ │ ├── RiskTimeline.java # 逐时间节点 R(t) 构建器(纯算法) │ │ ├── GeoHazardRiskModel.java # 地灾纯算法内核(S × T) │ │ ├── ForestFireRiskModel.java # 森火纯算法内核(B × F / FWI) │ │ ├── RiverFloodRiskModel.java # 洪涝纯算法内核(Q × S / API / 汇流滞后) │ │ ├── UrbanWaterloggingRiskModel.java # 内涝纯算法内核(Q × D / 短历时雨强 / 快涨快退) │ │ └── ComprehensiveRiskModel.java # 综合风险纯算法:两级聚合 / 三种 CRI / 并发 / 一致性 / 时间桶 / 分级排序 │ ├── plugin/ # 灾种插件 │ │ ├── IHazardPlugin.java # 插件接口契约 │ │ └── impl/ │ │ ├── FlashFloodPlugin.java # 山洪插件(核心算法) │ │ ├── GeoHazardPlugin.java # 地质灾害插件 │ │ ├── ForestFirePlugin.java # 森林火灾插件 │ │ ├── RiverFloodPlugin.java # 流域洪涝插件 │ │ └── UrbanWaterloggingPlugin.java # 城市内涝插件 │ ├── model/ # 数据模型 │ │ ├── enums/ # 枚举 │ │ ├── WatershedUnit.java # 小流域单元 │ │ ├── ComprehensiveAdminRegion / ComprehensiveRegionUnit / ComprehensiveRegionWeight # 行政区 / 映射 / 权重台账 │ │ ├── ComprehensiveUnitRisk / ComprehensiveHazardRisk / ComprehensiveModelParams # 第一级输入输出 / 参数包 │ │ ├── ComprehensiveRiskResult / ComprehensiveTimelinePoint # CRI 结果 / CRI(t) 节点 │ │ ├── RiskAssessmentResult.java # 统一评估结果(含各灾种扩展字段 + timeline / batchId / 峰值) │ │ ├── RiskTimelinePoint.java # 单个时间节点的 H/E/V/C/R 与等级 │ │ ├── HazardFactors.java # 致灾因子 │ │ ├── FlashFloodParams.java # 山洪参数包 │ │ ├── GeoHazardSite / GeoHazardCurve / GeoHazardModel* │ │ ├── ForestFireSite / ForestFireZone / ForestFireModel* # 台账 / 分区 / 输入输出 / 参数 │ │ ├── RiverFloodReach / RiverFloodZone / RiverFloodModel* / UpstreamFlow │ │ ├── UrbanWaterloggingSite / UrbanWaterloggingZone / UrbanWaterloggingModel* │ │ ├── MetData.java # 气象数据 │ │ ├── ExposureData.java # 承灾体 E │ │ ├── VulnerabilityData.java # 脆弱性 V │ │ └── CapacityData.java # 防灾能力 C │ ├── dto/ # 数据传输对象(含五灾种场景请求 / 预设场景) │ ├── repository/ # 数据访问层(接口) │ │ ├── jpa/ # 配置表 JPA Repository │ │ ├── mock/ # Mock 实现 │ │ └── impl/ # 地灾 / 森火 / 洪涝 / 内涝 / 综合风险 MySQL 仓储 + 内置演示数据兜底 │ ├── entity/ # 配置表实体 │ │ ├── RiskConfig.java │ │ └── FlashFloodCriticalRainfall.java │ └── config/ # 配置类 │ ├── FlashFloodRiskConfig.java │ └── JpaConfig.java # 按 risk.datasource.type 条件启用 JPA ├── src/main/resources/ │ ├── application.yml # 应用配置(含风险参数种子值) │ ├── application-mock.yml # 离线 Mock profile │ ├── db/ # 建表与初始化脚本(九份,均幂等) │ │ ├── init_risk_config.sql │ │ ├── init_business_tables.sql │ │ ├── init_geo_hazard.sql │ │ ├── init_forest_fire.sql │ │ ├── init_river_flood.sql │ │ ├── init_urban_waterlogging.sql │ │ ├── init_risk_timeseries.sql # 逐时间节点结果批次表 / 明细表 │ │ ├── init_comprehensive.sql # 综合风险四表 + 16 条 cr_* 配置 │ │ └── schema_postgis_reference.sql # PostGIS 设计稿,勿在 MySQL 执行 │ └── static/ # 前端(原生 HTML/CSS/JS,无需构建) │ ├── index.html / css/style.css / js/app.js # 山洪评估调试验证台 │ ├── geo-hazard.html / js/geo-hazard.js # 地质灾害调试验证台 │ ├── forest-fire.html / js/forest-fire.js # 森林火灾调试验证台 │ ├── river-flood.html / js/river-flood.js # 流域洪涝调试验证台 │ ├── urban-waterlogging.html / js/urban-waterlogging.js # 城市内涝调试验证台 │ ├── comprehensive-risk.html / js/comprehensive-risk.js / css/comprehensive.css # 行政区域综合风险 │ ├── js/comprehensive-region-map.js # 行政区分级着色一张图(WKT 解析 / WGS84→GCJ-02 / 降级清单) │ ├── module-placeholder.html / css/modules.css / js/module-nav.js # 六模块导航与占位页 │ ├── admin.html / admin-config.html / admin-history.html / admin-scenarios.html # 后台四模块 │ ├── css/admin.css / js/admin.js # 三个后台页面共用样式与 CRUD 逻辑(按 data-admin-module 分模块) │ ├── js/amap-config.js / js/amap-settings.js # Key + 统一官方卫星影像底图 / 「地图设置」弹窗(localStorage) │ ├── css/amap-settings.css / js/map-view.js # 设置弹窗样式 / 管理端空间渲染 │ ├── js/risk-map.js # 评估页全流域风险分布地图 │ ├── js/risk-result-map.js # 五灾种通用「评估结果地图」组件 + 三态视图切换器 │ ├── js/risk-matrix.js # 六页通用评估单元 × 时刻风险矩阵(第三结果视图) │ ├── js/risk-timeline-chart.js # 五灾种通用 R(t) 曲线(风险分布面板外独立单点信息面板) │ ├── js/risk-timeline-scrubber.js # 六页通用逐时刻全点位 / 全行政区域回放工具条(卡片 / 地图按帧渲染) │ └── js/vendor/echarts.min.js # 本地 ECharts 5.4.3(离线可用) ├── scripts/DbInitRunner.java # 无 mysql 客户端时的初始化工具 ├── target/dbinit/verify_*.py, test_*_runtime.js # 端到端与前端运行时验证脚本(构建产物目录) ├── src/test/java/com/fysb/risk/engine/ # 纯算法单测:RiskComputeEngine / RiskLevel / ComprehensiveRiskModel(11 例) ├── src/test/java/com/fysb/risk/service/ # FlashFloodAssessmentService 集成测试 └── pom.xml ``` ### 架构说明 - **插件化设计**:所有灾种实现 `IHazardPlugin` 接口,新增灾种只需编写新插件 + 配置参数包 - **数据层抽象**:Repository 接口定义数据访问契约;山洪气象 / 承灾体仍用 Mock,地灾 / 森火 / 洪涝 / 内涝台账已通过 `JdbcTemplate` 读 MySQL(不可达时回退内置演示数据),可无缝替换为真实数据源 - **五灾种同构分层**:`XxxRiskModel`(纯算法)→ `XxxPlugin` → `RiskComputeEngine` → `XxxAssessmentService` → `XxxRiskController`,山洪 / 地灾 / 森火 / 洪涝 / 内涝共用统一内核与四级分级 - **配置持久化**:临界雨量阈值与五灾种模型参数存于 MySQL,由 `RiskConfigService` / `GeoHazardConfigService` / `ForestFireConfigService` / `RiverFloodConfigService` / `UrbanWaterloggingConfigService` 加载,`application.yml` 仅作为初始化种子与兜底默认值 - **集中管理**:管理端 Web 页面 + 通用 CRUD API,可直接维护阈值、模型参数、流域/村落、隐患点、林班台账、河段与易涝点台账及历史序列,改动即时生效 - **空间可视化**:所有地图统一使用高德官方卫星影像 + 官方路网注记图层;管理端渲染流域出口、村落点位、流域边界、地灾隐患点、森火单元、洪涝河段与城市易涝点,五个灾种的风险分布均可用「卡片列表 / 地图 / 风险矩阵」三态切换查看,逐时间节点风险 R(t) 在下方独立单点信息面板常显,未配置 Key 时地图均降级为清单;分布面板内的逐时刻回放滑块可把卡片与地图切到任一时刻的全点位快照 - **合规 Key 管理**:源码只保留显式占位符,用户通过页面「⚙ 地图设置」把 Key 存入本机浏览器 `localStorage`,评估页与管理端共用,绝不写入源码或输出 - **行政区域综合风险上层模块**:`ComprehensiveRiskModel`(纯算法)消费五个单灾种结果,经第一级空间聚合、第二级 CRI 合成、并发修正与一致性校验,输出县 / 乡镇 / 村三级行政区的 CRI / 等级 / 排序 / 主导灾种 / CRI(t);台账、映射、权重与结果快照由四张独立表维护,前端「综合风险一张图」支持三级下钻,详见「行政区域综合风险动态评估模型」一章 - **逐时间节点结果**:`RiskTimeline`(纯算法)在五个 `XxxAssessmentService` 返回前挂载 R(t) 时间轴,`RiskTimelinePersistenceAdvice` 统一拦截评估响应并落库,前端 `js/risk-timeline-chart.js` 五页共用曲线组件并在风险分布面板之外的独立单点信息面板常显;异常降级不影响评估,详见「逐时间节点风险评估结果」一章 - **逐时刻全点位回放**:`js/risk-timeline-scrubber.js`(`window.RiskTimelineScrubber`)把每个点位响应内联的 `timeline` 按时间节点对齐成帧,拖动滑块 / 播放即可在「卡片列表 / 地图 / 风险矩阵」三态里查看该时刻全部点位的风险等级与 R,统计条同步按帧重算;点「↩ 总体」回到原有的「所有点位总风险情况」。组件不发起任何额外请求,与下方单点 R(t) 曲线互补;时间轴采用一格一时刻的时刻格子轨道,每格标注 HH:mm、顶部色条显示该时刻全场最高风险等级颜色、角标显示达到该等级的点位数。综合风险页复用同一组件,按 `hourOffset` 重采样成 25 个 4h 桶后回放全部行政区域的 CRI,卡片 / 排行榜 / 研判卡 / 一张图同步换帧,文案通过 `title / unitLabel / modeOverall` 等选项覆盖为「行政区域」口径。 - **统一计算引擎**:`RiskComputeEngine` 执行 `R = H × E × V / (1 + C)`,与具体灾种无关 ## 环境依赖 | 依赖 | 版本 | 说明 | |------|------|------| | JDK | 1.8+ | 当前适配 JDK 8,可升级到 JDK 17 + Spring Boot 3 | | Spring Boot | 2.7.18 | 适配 JDK 8 的最新稳定版 | | Maven | 3.6+ | 构建工具 | | Lombok | 1.18.x | 简化 POJO 代码 | | Jackson | 2.x | JSON 序列化 | > **数据库**:配置表与业务数据表均已在 MySQL 库 `fysb_riskmodel_db` 建好(共 23 张表,含逐时间节点结果批次表与明细表), > 脚本见 `src/main/resources/db/`,说明见「配置持久化」「数据存储层」两章。 > 当前气象等动态数据仍由 Mock Repository 提供;流域、村落、暴露度、防灾能力等静态数据已落库, > 实现对应 Repository 的 JPA 版本即可切换为库表读取。后续可考虑: > - PostgreSQL + PostGIS(空间数据) > - 时序数据库(气象数据,如 InfluxDB / TDengine) > - Redis(结果缓存) > **第三方组件**(后续扩展需要): > - Kafka(事件总线,气象数据驱动评估) > - 向量数据库(历史灾例 RAG 检索) > - LLM API(研判层、预警文稿生成) ## 配置持久化(数据库) `application.yml` 中 `risk.flash-flood` 下的临界雨量阈值、API 参数、α/β 系数、H 归一化阈值等已全部落库;地质灾害(`geo_*`)、森林火灾(`ff_*`)、流域洪涝(`rf_*`)、城市内涝(`uw_*`)与综合风险(`cr_*`,`hazard_type=COMPREHENSIVE`)的可率定参数同样只写入 `sys_risk_config(hazard_type=...)` 及各自分区 / 权重模板表,yml 里仅保留说明注释。运行期**以数据库为准**,yml 仅作为初始化种子与离线兜底默认值。 ### 数据表 | 表名 | 用途 | 唯一键 | |------|------|--------| | `sys_risk_config` | 全局 / 灾种级 KV 参数:山洪 `api_k`、`beta`、`alpha_min`、H 归一化阈值;地灾 `geo_*`(K、n、曲线、滞后参数);森火 `ff_*`(FWI 权重、归一化与等级节点、连续干燥度系数);洪涝 `rf_*`(API、动态临界面雨量、Q 分段、退水与演进参数);内涝 `uw_*`(短历时雨强 Q 分段、重现期指数、快涨快退时间常数、要害对象下限、D 合成权重);风险等级阈值 | `(config_key, hazard_type)` | | `flash_flood_critical_rainfall` | 各流域 1h/3h/6h 的准备转移雨量 `pw`、立即转移雨量 `pt`,以及流域级 `beta` / `baseline_api` / `alpha_min` 覆盖值 | `(unit_id, duration)` | 初始化数据量:`sys_risk_config` **共 129 条**(8 条 `FLASH_FLOOD` + 3 条 `GLOBAL` + 16 条 `GEO_HAZARD` + 29 条 `FOREST_FIRE` + 30 条 `RIVER_FLOOD` + 27 条 `URBAN_WATERLOGGING` + 16 条 `COMPREHENSIVE`),临界雨量 **12 条**(4 个小流域 × 3 个历时)。地灾 / 森火 / 洪涝 / 内涝的分区级差异另由 `geo_hazard_curve` / `forest_fire_zone` / `river_flood_zone` / `urban_waterlogging_zone` 覆盖全局值。字段与 `entity/` 下的 JPA 实体一一对应;`is_active=0` 可停用某项配置使其回退 yml 默认值。 ### 初始化(首次部署必需) 脚本:`src/main/resources/db/init_risk_config.sql`(配置与临界雨量)、`src/main/resources/db/init_comprehensive.sql`(综合风险四表 + `cr_*` 参数)。完整初始化顺序见 `src/main/resources/db/` 下九份脚本,均可用下面的 `DbInitRunner` 逐个执行。 ```bash # 方式一:有 mysql 客户端 mysql -h -P -u -p fysb_riskmodel_db \ < src/main/resources/db/init_risk_config.sql # 方式二:项目自带工具(无需 mysql 客户端,自动读取 application.yml 中的连接信息) javac -encoding UTF-8 -d target/dbinit scripts/DbInitRunner.java java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_risk_config.sql ``` 脚本幂等:`CREATE TABLE IF NOT EXISTS` + `INSERT IGNORE`,重复执行不会覆盖运维人员已在库中调整过的阈值。 > 应用启动**不会自动建表**(`spring.jpa.hibernate.ddl-auto=none`、`spring.sql.init.mode=never`),避免线上阈值表被 Hibernate 重建。表结构变更请通过版本化 SQL 脚本管理。 ### 生效链路与配置优先级 **数据库 > application.yml**。启动流程: 1. `RiskConfigService.initDbFromYml()` 逐键比对,把 yml 中**新增**的配置补齐入库(不覆盖库中现值); 2. `loadFromDb()` 读取启用状态的配置与临界雨量,组装 `FlashFloodParams` 并写入内存缓存; 3. `FlashFloodPlugin` / `FlashFloodAssessmentService` 通过 `getParams(unitId)`、`getDouble(...)` 读缓存参与计算; 4. 数据库不可达时自动回退 yml 默认值,评估服务仍可用。 改库后调用 `POST /api/risk/config/refresh` 刷新缓存即可生效,无需重启服务。综合风险 `cr_*` 参数由 `ComprehensiveConfigService` 每次评估实时读取(不缓存),改库后立即生效;行政区 / 映射 / 权重台账有 5s 短缓存,最多 5s 后生效。 ### 模式切换 | 模式 | 配置来源 | 启动方式 | |------|----------|----------| | `jpa`(默认) | MySQL,yml 兜底 | `mvn spring-boot:run` | | `mock`(离线) | 仅 application.yml | `--spring.profiles.active=mock`(该 profile 排除 JDBC/JPA 自动配置,完全不连库) | ```bash mvn spring-boot:run -Dspring-boot.run.profiles=mock # 或 java -jar target/dynamic-risk-assessment-agent-1.0.0.jar --spring.profiles.active=mock ``` ### 配置管理接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/config/list` | 缓存中的全部配置与各流域参数 | | GET | `/api/risk/config/{key}` | 查询单个配置项 | | PUT | `/api/risk/config/{key}` | 修改配置(jpa 模式写库),body:`{"value":"0.6","hazardType":"FLASH_FLOOD"}` | | POST | `/api/risk/config/refresh` | 从数据库重载缓存 | | POST | `/api/risk/config/sync-yml` | 把 yml 新增配置补齐入库并刷新 | | GET | `/api/risk/config/db/all` | 查看 `sys_risk_config` 原始记录 | | GET | `/api/risk/config/db/critical-rainfall` | 查看临界雨量原始记录 | ## 数据存储层(业务表) ### 山洪气象输入数据(与其余四灾种对齐) 山洪是最早实现的模块,气象输入长期由 `MockMetDataRepository` 在内存生成。现补齐两层落库输入,使六个模块统一为「日尺度前期本底落库 + 逐时数值序列可维护」: - `flash_flood_daily_rain`:`(unit_id, rain_date)` 唯一,按日期倒序取 `api_days` 天,供 `API = Σ(Pᵢ · kⁱ)` 计算前期影响雨量; - `flash_flood_met_series`:`(unit_id, met_type, slot_index)` 唯一,分别存 MET_NOW 5min×24 / MET_OBS 1h×24 / MET_FCST 1h×72 的时次降水量。 `JdbcMetDataRepository`(`@Primary`)通过 `ObjectProvider` 读表,数据库不可用、`application-mock.yml` 排除 JDBC 或表内无数据时自动回退 `MockMetDataRepository`,离线演示与既有单测不受影响。表中 `slot_time` 仅作来源时次标注:读取后按各 MetType 固定间隔以评估基准时刻重建 `times`,避免固定日期造成时间轴错帧,因此 `IHazardPlugin.deriveFactors` / `RiskComputeEngine` / `RiskTimeline.attach` 的 `Map` 契约保持不变。日序列经 `MetData.dailyRainfall` 可选字段交给 `FlashFloodPlugin.computeAPI()`,字段为空时仍回退到逐小时实况按天聚合。两张表归入「基础数据」组、`hazardScopes = GLOBAL + FLASH_FLOOD`,由 `AdminTableRegistry` 注册为 DATA 模块可编辑表。 按技术方案的空间数据库设计,在现有 MySQL 库中创建了 27 张通用业务数据表(含综合风险四表与山洪气象两表)。管理端注册 **29 张表**(2 张配置表 + 27 张通用业务表),另有场景台账 `hazard_scenario` 由独立页面维护。 | 表 | 用途 | 初始化行数 | |----|------|-----------| | `watershed_unit` | 小流域主表:面积、汇流时间、比降、出口经纬度与点位几何、流域边界 | 4 | | `watershed_village` | 流域内村落(一对多):海拔、人口、距沟道距离、相对高差、点位几何 | 5 | | `flash_flood_params` | 按流域的临界雨量宽表,含率定版本号 | 4 | | `model_coefficient` | 单行全局率定系数(`api_k` / `beta` / `alpha_min` / H 归一化阈值等) | 1 | | `flash_flood_daily_rain` | 山洪 30 天前期日降水序列(API = Σ(Pᵢ·kⁱ) 的前期分量) | 120 | | `flash_flood_met_series` | 山洪 MET_NOW / MET_OBS / MET_FCST 逐时数值序列(5min×24 / 1h×24 / 1h×72) | 480 | | `exposure_data` | 承灾体暴露度 E(预计算) | 4 | | `capacity_data` | 防灾减灾能力 C(预计算) | 4 | | `risk_assessment_result` | 既有主表:每次评估各单元的最终总体风险快照(H/E/V/C/R、等级、致灾因子 JSON),`met_version='batch:<批次UUID>'` 关联批次 | 由评估流程写入 | | `geo_hazard_site` | 地灾隐患点 / 斜坡单元:易发性 S、E/V/C、曲线分区、空间点位 | 6 | | `geo_hazard_curve` | 分区临界雨量曲线(预警线 / 危险线、K、n、滞后参数) | 3 | | `geo_hazard_daily_rainfall` | 地灾 30 天历史日降水序列(`R_eff` 前期分量) | 180 | | `forest_fire_stand` | 森火网格 / 林班:可燃物—地形本底易燃性 B、E/V/C、火险分区、空间点位 | 6 | | `forest_fire_zone` | 森火分区 FWI 权重、归一化节点与国标五级火险等级节点 | 3 | | `forest_fire_daily_met` | 森火 30 天历史日气象序列(连续干燥日数统计来源) | 180 | | `river_flood_reach` | 洪涝河段控制单元:上下游拓扑、汇流 / 传播时间、过流能力、承泄不足度 S、E/V/C、空间点位 | 6 | | `river_flood_zone` | 洪涝水系分区参数(API / 动态临界面雨量 / 退水与演进) | 3 | | `river_flood_daily_rain` | 洪涝 30 天历史日面雨量序列(API 来源) | 180 | | `urban_waterlogging_site` | 城市易涝点 / 排水分区:设计重现期与各历时设计雨强、排水不足度 D、E/V/C、空间点位 | 6 | | `urban_waterlogging_zone` | 内涝排水分区参数(Q 分段 / 重现期指数 / 快涨快退 / 要害对象下限) | 3 | | `urban_waterlogging_ponding_record` | 历史积水事件(最大积水深度 / 历时 / 过程峰值雨强) | 18 | | `risk_assessment_batch` | 评估批次:一次评估一行,含单元数 / 时间节点数 / 最终总体风险快照 JSON | 由评估流程写入 | | `risk_assessment_timeseries` | 逐时间节点风险明细:每单元每时刻的 H/E/V/C/R 与四级等级 | 由评估流程写入 | | `comprehensive_admin_region` | 行政区域台账(县 / 乡镇 / 村)+ 示意边界 WKT + POINT 中心点 | 26 | | `comprehensive_region_unit` | 行政区—单灾种评估单元映射(跨界面积占比 + 暴露人口) | 34 | | `comprehensive_region_hazard_weight` | 五类区域灾种权重模板 λ_h | 25 | | `comprehensive_risk_result` | 行政区域综合风险结果快照(管理端只读,按批次保留) | 由评估流程写入 | ### 脚本与方言转换 - `db/schema_postgis_reference.sql`:PostgreSQL + PostGIS 设计稿(`GEOMETRY(MultiPolygon,4326)`、GIST、`BIGSERIAL`、`NUMERIC`、`JSONB`),供后续迁移 PostGIS 使用,**不要在 MySQL 执行**。 - `db/init_business_tables.sql`:MySQL 8 等价实现 + 初始化数据,幂等可重复执行。 | PostGIS 设计 | MySQL 8 实现 | |--------------|--------------| | `GEOMETRY(MultiPolygon, 4326)` | `MULTIPOLYGON SRID 4326` | | `CREATE INDEX ... USING GIST` | `SPATIAL INDEX`(索引列必须 NOT NULL) | | `BIGSERIAL` | `BIGINT AUTO_INCREMENT` | | `NUMERIC` / `JSONB` / `now()` | `DECIMAL` / `JSON` / `CURRENT_TIMESTAMP` | 执行顺序:`init_risk_config.sql` → `init_business_tables.sql`(后者会从配置表聚合出参数宽表)→ `init_geo_hazard.sql` → `init_forest_fire.sql` → `init_river_flood.sql` → `init_urban_waterlogging.sql` → `init_risk_timeseries.sql`,七份脚本均幂等: ```bash java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_business_tables.sql java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_geo_hazard.sql java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_forest_fire.sql java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_river_flood.sql java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_urban_waterlogging.sql java -cp "target/dbinit;" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_risk_timeseries.sql ``` ### 空间字段说明 - MySQL 8 中 SRID 4326 的 WKT 默认轴序为「纬度 经度」,脚本统一用 `ST_GeomFromText(..., 4326, 'axis-order=long-lat')` 按「经度 纬度」书写。 - `watershed_unit.outlet_point` 与 `watershed_village.geom` 为 `NOT NULL` 并建 `SPATIAL INDEX`,已用 `MBRContains` 验证空间检索可用。 - `watershed_unit.boundary` 暂无真实边界数据,允许 NULL,因此暂不建空间索引(MySQL 的 SPATIAL INDEX 要求列 NOT NULL)。导入真实边界后可执行: ```sql ALTER TABLE watershed_unit MODIFY boundary MULTIPOLYGON SRID 4326 NOT NULL; ALTER TABLE watershed_unit ADD SPATIAL INDEX idx_watershed_boundary (boundary); ``` - 村落表补充 `(unit_id, village_name)` 唯一键,保证初始化脚本重复执行不产生重复村落。 ### 与配置表的关系 `flash_flood_params` / `model_coefficient` 是运行时配置表 `flash_flood_critical_rainfall` / `sys_risk_config` 的**按流域宽表投影**,初始化时由配置表聚合生成(不重复硬编码),已校验 `pt1h/pt3h/pt6h` 等阈值完全一致。 评估运行时仍以配置表为准(`RiskConfigService`);若调整了配置表阈值,把 `init_business_tables.sql` 中聚合段首的 `INSERT IGNORE` 改成 `REPLACE` 后重新执行即可同步宽表。 ## 后台管理控制台(四个一级模块) **四个一级模块**(各自独立页面,顶部 `admin-feature-nav` 互相跳转): | 模块 | 页面 | 职责 | |---|---|---| | ▦ 数据台账 | `admin.html` | 评估单元台账、历史观测序列、空间地图 | | ⚙ 参数配置 | `admin-config.html` | 运行时模型参数、临界阈值、分区率定参数、区域灾种权重 | | ◷ 历史结果 | `admin-history.html` | 六个灾种 Tab 分别查询评估历史结果 / 评估批次 / 逐时次风险明细(综合另有行政区域快照,四张只读表) | | ◈ 场景管理 | `admin-scenarios.html` | 六灾种预设场景台账(独立功能,见下章) | 评估页右上角「⚙ 数据管理」仍跳转到 `admin.html`(数据台账),再经一级导航进入另三个模块。**数据台账 / 参数配置**两个通用表格页共用 `js/admin.js` 与同一套 DOM id,按 `` 请求各自模块的表清单;**历史结果**页已改版为分灾种 Tab 独立页面,使用 `js/admin-history.js`,不再加载通用表格脚本。 **导航层级**:四个后台页面都**不显示评估页的「灾害模块」那一栏**——`.module-nav` DOM 与 `js/module-nav.js` 只由六个评估页 / `module-placeholder.html` 引入。后台只保留顶栏六个评估页跳转链接与「后台功能」一级导航;`admin.css` 另有 `body[data-module="admin"] .module-nav { display: none !important; }` 兜底,避免后续误加回标签或脚本时该栏重新出现。数据台账 / 参数配置页左侧「灾种」下拉按**适用范围**过滤数据表;历史结果页按需求**已去掉该下拉**,改为六个灾种 Tab,见下方专节。 29 张通用表按 10 组导航(表名 / 列名全部来自 `AdminTableRegistry` 静态白名单),并由后端统一标注一级模块归属;场景台账 `hazard_scenario` 不在通用白名单,由独立页面与 `/api/admin/scenarios/*` 维护。模块归属由 `AdminTableRegistry.CONFIG_TABLES` / `HISTORY_TABLES` 两个白名单单一数据源定义(启动期自检表名与互斥性): | 模块 | 表数 | 表 | |---|---|---| | `CONFIG` 参数配置 | 9 | `sys_risk_config`、`flash_flood_critical_rainfall`、`model_coefficient` 🔒、`flash_flood_params` 🔒、`geo_hazard_curve`、`forest_fire_zone`、`river_flood_zone`、`urban_waterlogging_zone`、`comprehensive_region_hazard_weight` | | `DATA` 数据台账 | 16 | 小流域 / 村落、E / C、山洪前期日降水与气象时序、地灾隐患点与日降水、森火单元与日气象、洪涝河段与日面雨量、内涝易涝点与积水事件、行政区域与映射 | | `HISTORY` 历史结果 | 4 | `risk_assessment_result` 🔒、`risk_assessment_batch` 🔒、`risk_assessment_timeseries` 🔒、`comprehensive_risk_result` 🔒 | 两个通用表格页通过 `GET /api/admin/tables?module=CONFIG|DATA` 与 `/overview?module=...` 只取自己模块的表;历史结果页取 `module=HISTORY` 的列元数据,行数据走按灾种查询接口(见下)。不传 `module` 时接口仍返回全部 29 张表(兼容既有调用),非法值返回 400。参数配置页没有空间点位表,`admin.css` 隐藏其地图视图切换器与地图面板;历史结果表含 `unit_id`,仍可用地图定位。全量 29 张表按 10 组分组: | 分组 | 表 | 可编辑 | |------|----|--------| | 模型配置 | 模型参数配置、率定系数(宽表) | ✅ / 🔒 | | 临界阈值 | 临界雨量阈值、临界雨量(宽表) | ✅ / 🔒 | | 基础数据 | 小流域、流域村落、山洪前期日降水、山洪气象时序 | ✅ | | 评估要素 | 承灾体暴露度 E、防灾减灾能力 C | ✅ | | 历史结果 | 评估结果历史、评估批次、逐时次风险明细 | 🔒 | | 地灾数据 | 地灾隐患点台账、地灾临界雨量曲线、地灾前期日降水 | ✅ | | 森火数据 | 森火评估单元台账、森火气象分区参数、森火历史日气象 | ✅ | | 洪涝数据 | 洪涝河段控制单元台账、水系分区参数、历史日面雨量 | ✅ | | 内涝数据 | 城市易涝点台账、内涝排水分区参数、历史积水事件 | ✅ | | 综合风险 | 行政区域台账、行政区—单元映射、区域灾种权重模板、综合风险结果快照 | ✅ / 🔒 | `sys_risk_config` 按 `hazard_type` 区分灾种(`FLASH_FLOOD` / `GEO_HAZARD` / `FOREST_FIRE` / `RIVER_FLOOD` / `URBAN_WATERLOGGING` / `COMPREHENSIVE` / `GLOBAL`),森火 FWI 权重、洪涝动态临界面雨量与内涝短历时雨强参数均在同一张表维护;分区级差异由 `geo_hazard_curve` / `forest_fire_zone` / `river_flood_zone` / `urban_waterlogging_zone` 覆盖全局值。 主要功能: - **概览卡片**:配置源、当前模块的表 / 记录数、当前生效的 β、α_min、H 归一化区间、WS_001 的 1h 立即转移阈值 - **表格管理**:全字段展示、搜索过滤、行内「编辑 / 删除」、新增/编辑表单(按字段类型自动渲染、必填校验)、CSV 导出 - **灾种筛选按适用范围(数据台账 / 参数配置页)**:`hazardType` 是单值,无法表达跨灾种共享表,因此后端另给每张表输出 `hazardScopes`,由 `AdminTableRegistry.SHARED_HAZARD_SCOPES` 单一数据源标注:`sys_risk_config` 与三张 `risk_assessment_*` 结果表覆盖六个灾种 + `GLOBAL`;山洪口径的 `watershed_unit` / `watershed_village` / `exposure_data` / `capacity_data` 同时属于 `GLOBAL` 与 `FLASH_FLOOD`;其余表沿用单值归属。前端 `visibleTables()` 按列表过滤(无该字段时回退 `hazardType`),切换灾种后若当前表不在范围内会自动打开第一张可见表,任一模块 × 任一灾种都不再出现空列表 - **历史结果页改为六灾种 Tab**:不再用下拉,改用一级 Tab 按 `hazard_type` 分别查询行数据,详见下方「历史结果页:六灾种 Tab」小节 - **快捷操作**:参数配置页提供「刷新配置缓存 / 同步 YML 新增配置 / 重载参数数据」;数据台账页与历史结果页提供「重载数据」与跨模块入口。`js/admin.js` 的 `on()` 会对不存在的按钮静默跳过,通用表格页可自由裁剪快捷操作 - **改完即生效**:修改 `sys_risk_config` 或 `flash_flood_critical_rainfall` 后,后端自动调用 `RiskConfigService.refresh()`,无需重启即可作用于后续评估 - **空间点位联动**:数据台账页修改流域/村落经纬度时,后端自动用 `ST_GeomFromText(..., 4326, 'axis-order=long-lat')` 同步 `outlet_point` / `geom`,几何列以 WKT 只读展示 - **表格 / 地图视图切换**:数据台账页与历史结果页提供(顶部「▦ 表格」「◎ 地图」),参数配置页隐藏;带 ◎ 标记的表行内提供「定位」,可跳到地图并聚焦对应点位。默认选中表:参数配置 `sys_risk_config`、数据台账 `watershed_unit`、历史结果 `risk_assessment_result`(综合 Tab 默认 `comprehensive_risk_result`) ### 历史结果页:六灾种 Tab 「◷ 历史结果」页(`admin-history.html` + `js/admin-history.js`)**去掉原左侧「灾种」下拉与表导航**,改为两层 Tab: | 层级 | 内容 | |---|---| | 一级 Tab | 山洪 / 地灾 / 森火 / 洪涝 / 内涝 / 综合(顺序与标签由 `AdminTableRegistry.historyHazards()` 单一数据源给出) | | 二级 Tab | 评估历史结果 `risk_assessment_result`、评估批次 `risk_assessment_batch`、逐时次风险明细 `risk_assessment_timeseries`;综合 Tab 另有「综合风险结果快照」`comprehensive_risk_result` | - 后端接口:`GET /api/admin/history/overview` 一次返回六灾种 × 四张结果表的行数、最近评估时间与 `compositeOnly` 标记(Tab 数字与概览卡片都由它驱动);`GET /api/admin/tables/{key}/rows?hazardType=&limit=` 按 `hazard_type` 参数绑定过滤、按该表时间列倒序、限量最多 5000 条。不传参数时 `/rows` 仍是原来的全表查询,其它后台页面与其它调用方不受影响。 - 三张共用结果表按灾种分别查询,互不混合;综合快照表没有 `hazard_type` 列,全部计入综合 Tab,其它灾种下不显示该表也不返回其数据。非法灾种、对非历史表传 `hazardType` 均返回 400。 - 页面只读:保留搜索、CSV 导出(文件名带灾种与表名)、表格 / 地图视图切换与行内 ◎定位;新增「最近 200 / 500 / 1000 / 2000 条」限量选择,表格底部同时显示**该灾种该表总行数**,避免把限量结果误认为全部历史。每个灾种记住自己上次查看的结果表,切换 Tab 时用 `loadToken` 丢弃过期请求。 - 结果表全部由评估流程自动写入,不支持新增 / 编辑 / 删除,页面不再引入编辑 / 删除弹窗。回归脚本:`target/dbinit/verify_admin_history_tabs.py`。 ### 「行政区-单元映射」灾种联动 `comprehensive_region_unit` 的唯一键是 `(admin_code, hazard_type, unit_id)`,单元编号必须来自**所选灾种自己的**评估单元台账,五张台账的主键列名并不相同: | 灾种 | 评估单元台账 | 编号列 | |------|--------------|--------| | `FLASH_FLOOD` | `watershed_unit` | `unit_id` | | `GEO_HAZARD` | `geo_hazard_site` | `site_id` | | `FOREST_FIRE` | `forest_fire_stand` | `stand_id` | | `RIVER_FLOOD` | `river_flood_reach` | `reach_id` | | `URBAN_WATERLOGGING` | `urban_waterlogging_site` | `site_id` | 新增 / 编辑弹窗选择「灾种」后,前端按 `GET /api/admin/lookup/hazard-units?hazardType=...` 懒加载并按灾种缓存该台账,把编号 + 名称统一投影成 `unitId` / `unitName`,同时刷新 `unit_id` 的候选 `datalist` 与「从台账选择单元编号」下拉,标题显示台账名与单元数。切换灾种会清空旧的 `unit_id` / `unit_name` 并提示重选(旧编号不属于新灾种,且是唯一键的一部分);从下拉选择或手动输入编号时自动带出台账 `unit_name`。编辑既有记录时按该行 `hazard_type` 加载。其余山洪口径表(临界雨量、E / C、村落等)的 `unit_id` 仍使用全局 `unit-id-list`,不受影响。 后端只接受内置映射的五个灾种编码,表名 / 列名一律经 `AdminTableRegistry` 白名单校验,非法或缺省参数返回 400 与统一错误结构,绝不把 `hazardType` 拼进 SQL 标识符。快速切换数据表时用 `tableLoadToken` 丢弃过期的行数据请求,避免旧表数据按新表列渲染。 ### 管理端接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/admin/overview?module=CONFIG\|DATA\|HISTORY` | 概览(模块内表 / 行数、生效参数与阈值;不传 `module` 统计全部 29 张) | | GET | `/api/admin/tables?module=CONFIG\|DATA\|HISTORY` | 表清单与字段元数据(含 `module` 模块归属、`hazardType` / `hazardScopes` 灾种适用范围、`spatial` / `mapFocusKey` / `mapPkColumn` 空间定位元数据;不传 `module` 返回全部 29 张) | | GET | `/api/admin/lookup/hazard-units?hazardType=...` | 按灾种列出该灾种评估单元的编号 + 名称(供「行政区-单元映射」表单联动) | | GET | `/api/admin/tables/{key}/rows` | 查询记录 | | POST | `/api/admin/tables/{key}/rows` | 新增记录 | | PUT | `/api/admin/tables/{key}/rows/{pk}` | 修改记录 | | DELETE | `/api/admin/tables/{key}/rows/{pk}` | 删除(外键冲突返回友好提示) | | POST | `/api/admin/config/refresh` | 刷新运行时配置缓存 | | POST | `/api/admin/config/sync-yml` | 把 yml 新增配置补齐入库 | 实现要点:表名与列名全部来自 `AdminTableRegistry` 静态白名单,用户输入只作为 PreparedStatement 参数绑定;`lookup/hazard-units` 用内置映射把灾种编码转成注册表 key,再校验编号列 / 名称列后才拼 SQL;只读派生表/历史表禁止写入;管理端接口仅在 `risk.datasource.type=jpa` 时注册,离线 mock 模式下不可用。 ### 空间数据地图视图(高德地图) 管理端右上「◎ 地图」把具备空间属性的评估输入数据叠加到地图上: | 图层 | 数据来源 | 说明 | |------|----------|------| | 流域出口 | `watershed_unit.outlet_point` | 蓝色点位;信息窗体展示流域属性、1h/3h/6h 临界雨量、暴露度 E 与防灾能力 C | | 村落点位 | `watershed_village.geom` | 青色点位;信息窗体展示人口、海拔、距沟道与相对高差 | | 流域边界 | `watershed_unit.boundary` | 紫色多边形;当前初始化数据未导入真实边界,导入后自动呈现 | | 地灾隐患点 | `geo_hazard_site.geom` | 橙色点位;信息窗体展示易发性 S、E/V/C、曲线分区与隐患类型 | | 森火单元 | `forest_fire_stand.geom` | 红色点位;信息窗体展示可燃物类型与负荷、本底 B、E/V/C、火险分区与重点防护标记 | | 洪涝河段 | `river_flood_reach.geom` | 紫色点位;信息窗体展示河流 / 河段、上下游拓扑、汇流时间、承泄不足度 S 与重点防护标记 | | 城市易涝点 | `urban_waterlogging_site.geom` | 天蓝色点位;信息窗体展示对象类别、低洼深度 / 硬化率、设计重现期与各历时设计雨强、排水不足度 D 与要害对象标记 | 顶部工具栏提供「森火单元」「地灾隐患点」「洪涝河段」「城市易涝点」等七类图层显隐开关,未配置 Key 时降级清单同样包含这些点位。 `flash_flood_critical_rainfall`、`flash_flood_params`、`exposure_data`、`capacity_data`、`risk_assessment_result` 等表虽无几何列,但含 `unit_id`,行内「定位」会按流域编号聚焦到该流域的出口点;地灾曲线 / 森火分区 / 历史日序列等仅含分区或单元编号的表同理按自身主键定位。`/api/admin/tables` 返回的 `spatial` / `mapFocusKey` / `mapPkColumn` 由 `AdminDataService` 依据「是否有 POINT 列、是否含 unit_id」自动推导。 #### 配置自己的 Key(源码不内置有效 Key) 本项目只使用**高德地图 JS API 2.0 官方 SDK 与官方卫星影像 / 路网注记图层**,代码里不放任何有效 Key。评估页与管理端共用同一份配置,提供两种方式: **方式一(推荐):页面「⚙ 地图设置」** 1. 到[高德开放平台控制台](https://console.amap.com/) → 应用管理 → 我的应用 → 创建新应用 → 添加 Key,服务平台选「**Web端 (JS API)**」。 2. 点击页面右上角「**⚙ 地图设置**」粘贴 Key;若控制台启用了安全密钥,一并填写 `securityJsCode`。 3. 点「保存并刷新」即可。评估页与管理端自动共用,也可随时在弹窗里「清除本地 Key」。 此方式下 Key 只写入**本机浏览器 `localStorage`**(键名 `fysb.amap.jsapi.key` / `fysb.amap.jsapi.security`),不写入源码、不进入版本库、不上传服务端;换浏览器或清理站点数据后需重新填写。未配置 Key 时地图自动降级为清单,降级提示内也提供「打开地图设置」快捷按钮。 **方式二:修改源码占位符(适合固定部署)** 把 `src/main/resources/static/js/amap-config.js` 中的 `fileKey` 由默认占位符改为自己的 Key: ```javascript var fileKey = PLACEHOLDER; // ← 改为 '你自己的Key' global.AMAP_CONFIG = { jsApiKey: storedKey || fileKey, // 本机存储优先,其次源码值 securityJsCode: read(STORAGE_CODE) || '', version: '2.0', plugins: 'AMap.ToolBar,AMap.Scale', mapType: 'satellite', // 所有地图统一为官方卫星影像 + 官方路网注记 mapStyle: 'amap://styles/dark' // 仅 SDK 不支持卫星图层时的标准底图兜底 }; ``` > 注意:该方式会把 Key 写进源码,请勿提交到公开仓库;`localStorage` 的值优先级更高,会覆盖源码值。 #### 底图:统一官方卫星影像 系统内**所有地图**(山洪常驻风险分布地图、五灾种评估结果地图视图、管理端空间数据地图)统一使用高德官方卫星影像,由 `js/amap-config.js` 的 `window.AmapBaseLayers` 集中构造: ```javascript // 高德 JS API 2.0 官方图层:卫星与路网通常一起使用 var satellite = new AMap.TileLayer.Satellite(); var roadNet = new AMap.TileLayer.RoadNet(); new AMap.Map(container, { layers: [satellite, roadNet], zoom: 10, ... }); ``` - **`layers` 与 `mapStyle` 互斥**:使用卫星图层时必须移除 `mapStyle`,否则卫星底图不会生效;这一步由 `AmapBaseLayers.options()` 统一处理,三个地图组件只需传入基础参数。 - **切换回标准矢量底图**:把 `AMAP_CONFIG.mapType` 改为 `'standard'` 即可,无需改各页面代码。 - **安全回退**:SDK 未提供 `AMap.TileLayer.Satellite`(如旧版本 / 裁剪版)时自动回退到 `amap://styles/dark` 标准底图,地图与评估功能均不中断。 - 卫星影像与路网注记均为**高德官方图层**,不接入任何第三方 / 境外瓦片源;卫星底图下深色标签、信息窗体与彩色风险点位保持原有对比度,无需额外改样式。 安全与合规建议: - 在高德控制台为 Key 配置 **Referer 域名白名单**,避免被他人盗用;不要把有效 Key 提交到公开仓库。 - 商业或对外发布场景建议由**后端代理鉴权**后再下发,不要明文暴露前端 Key。 - 仅使用高德官方 SDK 与官方卫星影像 / 路网注记图层,不接入任何境外或第三方瓦片源,不缓存、转售或再分发底图数据;对外发布前按高德开放平台协议确认卫星影像的授权范围与相关合规要求。 - 库内坐标为 **WGS84 (SRID 4326)**,`map-view.js` 在叠加前统一做 **WGS84 → GCJ-02** 正向转换(`wgs84ToGcj02`),境外坐标原样返回;不要跳过转换,否则国内点位会有数百米偏移。 #### 降级行为 未配置 Key、SDK 加载失败或空间数据读取失败时,地图区域自动降级为**空间数据清单**(列出流域/村落点位 WKT 与 1h 立即转移阈值),并给出具体排查提示。表格视图的增删改查完全不受影响。地图工具栏还提供图层显隐开关与「重载空间数据」;表格数据变更后地图会按需自动刷新。 > **安全提示**:当前版本未启用鉴权,任何可访问服务的人都能修改阈值。生产部署请补充登录认证与操作审计。 ## 分灾种场景管理(自定义预设场景) 六个评估模块的「预设场景」原先分散在五个 `XxxScenarios` 静态类与山洪页 `app.js` 的硬编码常量中,管理端无法维护。现已统一收敛到数据库台账 `hazard_scenario`,并由**后台独立页面 `admin-scenarios.html`(「◈ 场景管理」)**按灾种自定义;该页面与「▦ 数据台账」「⚙ 参数配置」「◷ 历史结果」平级,场景台账不进入模型参数配置等数据表卡片列表。 ### 数据表与预设数据 `db/init_scenario.sql` 幂等建表并灌入全部当前预设场景,共 **47 条 / 6 个灾种**: | 灾种 | 预设场景数 | 说明 | |---|---|---| | `FLASH_FLOOD` 山洪 | 6 | 特大暴雨 / 暴雨 / 中雨 / 小雨 / 典型山洪 / 土壤饱和 | | `GEO_HAZARD` 地质灾害 | 6 | 干燥、小雨、短时强降水、长期累积、雨停滞后、气象缺测 | | `FOREST_FIRE` 森林火灾 | 8 | 雨后回落、连旱高温、久旱大风、一雨解旱等 | | `RIVER_FLOOD` 流域洪涝 | 9 | 枯水、短历时、长历时、前期湿润、上游级联、雨停退水等 | | `URBAN_WATERLOGGING` 城市内涝 | 10 | 无雨、接近设计、10min 突发、1h 持续、特大暴雨、要害对象等 | | `COMPREHENSIVE` 综合风险 | 8 | 常态汛期、山区暴雨、城区强降水、流域洪水、林区连旱、多灾并发、缺项处理等 | 主要列:`hazard_type` / `scene_key`(唯一键)、`name` / `description` / `tag`、`params_json`、`sort_order`、`is_active`、`is_builtin`、`source`。`params_json` 对单灾种是扁平场景输入(直接展开为 `XxxAssessRequest`),对综合风险是 `{ hazardInputs: { 五个灾种各自输入 }, missingHazards: [...] }`。 脚本由 `scripts/ScenarioSqlGenerator.java` 从 `scenario/BuiltinScenarios.java`(内置场景唯一数据源)生成,保证 SQL 种子、离线兜底与管理端「恢复内置场景」三者口径完全一致: ```bash javac -encoding UTF-8 -cp target/classes -d target/dbinit scripts/ScenarioSqlGenerator.java java -cp "target/dbinit;target/classes" ScenarioSqlGenerator src/main/resources/db/init_scenario.sql java -cp "target/dbinit;target/dbinit/mysql-driver.jar" DbInitRunner \ src/main/resources/application.yml src/main/resources/db/init_scenario.sql ``` `CREATE TABLE IF NOT EXISTS` + `INSERT IGNORE`,重复执行不会覆盖管理端已调整的场景。 ### 运行时口径 - **优先级:数据库 > 内置静态场景**。`ScenarioService` 只读取 `is_active=1` 的记录,按 `sort_order, id` 排序;数据库不可用、未建表或离线 mock 模式自动回退 `BuiltinScenarios`,评估页仍可用。 - 六个模块的 `GET /api/risk/{module}/scenarios` 契约保持不变(单灾种返回 `{key,name,description,...输入}`,综合返回 `{key,name,description,tag,hazardInputs,missingHazards}`),因此五个模块页零改动;山洪页新增同名端点,`app.js` 启动时拉取并动态渲染按钮,接口不可用时保留内置按钮。 - 综合评估 `assessAll` 的场景查找与五灾种输入也改走场景库,`hazardScenarios` 覆盖逻辑不变。 - 场景列表在进程内缓存;`ScenarioAdminService` 的任何写操作都会立即触发 `ScenarioService.invalidate()`,**无需重启服务**,评估页刷新即可选用。场景台账已从 `AdminTableRegistry` 通用表格白名单移除,`/api/admin/tables` 不再返回该表,专用 API 是唯一写入口。 - 停用(`is_active=0`)只从评估页隐藏,台账保留;删除内置场景后可用「恢复内置场景」补回。 ### 管理端操作(独立页面) 「场景管理」是后台的**独立功能**,不再作为 `admin.html` 的第三个视图、也不出现在通用数据台账卡片中。四个模块页面通过顶部一级功能导航条互相跳转,`admin.html` 左侧「快捷操作」也有同名入口。 | 页面 | 职责 | |---|---| | `admin.html` | ▦ 数据台账:评估单元台账 / 历史观测序列 / 空间地图(表格 + 地图两态) | | `admin-config.html` | ⚙ 参数配置:模型参数 / 临界阈值 / 分区率定参数 / 区域灾种权重(仅表格视图) | | `admin-history.html` | ◷ 历史结果:六个灾种 Tab 分别查询评估历史结果 / 批次 / 逐时次明细(综合另有结果快照),四张只读表,支持限量、地图定位与 CSV 导出 | | `admin-scenarios.html` | ◈ 场景管理:分灾种预设场景(独立台账 `hazard_scenario`),含概览统计、场景卡片、编辑弹窗 | - 按 6 个灾种 Tab 浏览场景卡片,显示内置 / 自定义 / 启用状态、排序与参数摘要;顶部统计场景总数 / 启用数 / 自定义数。 - 新增 / 编辑 / 复制 / 删除 / 启停 / 恢复内置 / 导出当前灾种 CSV;编辑弹窗按 `scenario/ScenarioSchema.java` 的字段元数据结构化渲染(数字 / 整数 / 布尔 / 文本、可空字段留空即 `null`),综合场景按五个灾种分组并支持勾选缺项灾种。 - 弹窗底部提供「完整参数 JSON」:修改结构化字段会自动同步;直接编辑 JSON 时以 JSON 为准,可添加未登记的扩展字段。 - 页面复用 `js/admin-scenarios.js` 与全站双主题;仅在 `risk.datasource.type=jpa` 模式下可用,离线 mock 模式 API 返回 404,评估页回退内置预设。 - `AdminDataService` 中原有的通用表格 JSON 校验与场景缓存刷新分支已随注册一并移除,避免两套写入路径并存。 ### 场景管理接口 | 接口 | 用途 | |---|---| | `GET /api/admin/scenarios/schema` | 六灾种字段元数据、综合场景灾种分组、内置数量 | | `GET /api/admin/scenarios/stats` | 各灾种总数 / 启用数 / 自定义数 | | `GET /api/admin/scenarios/list?hazardType=` | 场景行(含停用场景与解析后的参数对象) | | `POST /api/admin/scenarios/save` | 新增 / 编辑(`id` 为空即新增) | | `DELETE /api/admin/scenarios/{id}` | 删除 | | `POST /api/admin/scenarios/{id}/toggle` | 启用 / 停用 | | `POST /api/admin/scenarios/restore-builtin` | 恢复内置预设(单条多值 SQL,不影响自建场景) | > 场景只提交「情景输入」。临界雨量 Pt、E/V/C、设计雨强、排水本底等仍属评估单元固有属性,由后端按台账读取,不要在场景里统一覆盖;山洪场景中的 `e/v/c` 是调试面板历史遗留的本底覆盖字段,仅单流域调试生效,批量评估不使用。综合场景的 `missingHazards` 表示该灾种按缺项处理,权重会重新归一。 ## 全站双主题皮肤(默认浅色,可切换) 十一个页面(六个评估模块、数据台账 / 参数配置 / 历史结果 / 场景管理四个后台功能页、兜底页)统一支持浅色 / 深色皮肤,**首次访问默认浅色**,顶栏 `.top-stats` 右侧有 `☾ 深色` / `☀ 浅色` 切换按钮。 | 文件 | 职责 | |---|---| | `static/css/theme.css` | `:root` 保留原深色变量并补充 `--chart-*` / `--inline-*`;`:root[data-theme="light"]` 覆盖为浅色;末尾集中覆盖原 CSS 硬编码的深色半透明底、亮色文字、地图标签与弹窗阴影 | | `static/js/theme.js` | `` 同步应用主题、偏好持久化、注入切换控件、图表调色板、切换后刷新已存在的 ECharts 实例 | 实现口径: - `` 是静态兜底;`theme.js` 在所有 `` 之后、样式表之前同步执行,读取 `localStorage['fysb.theme']`(非法值回退 `light`)并写 `data-theme` 与 `colorScheme`,**不会先闪一下深色**。 - 主题偏好按浏览器保存,跨页面保持一致;`storage` 事件让多个标签页同步。`localStorage` 不可用时仅当前页生效,不报错。 - `theme.css` 必须排在其它样式表之后,通过 `[data-theme="light"]` 前缀提高优先级;深色主题完全沿用原 CSS,观感不变。 - 图表配色统一走 `ChartPal()`(由 `Theme.palette()` 注入):坐标轴、网格线、tooltip、图例、分级线、风险等级色都取自同一套变量;切换主题时 `Theme.redrawCharts()` 依据 `getOption()` 里**实际存在**的组件做补丁式 `setOption`,不重写数据、不新增组件。 - JS 拼接的内联 `style="color:#xxx"` 改为 `var(--inline-*)` CSS 变量,切换皮肤无需重渲染 DOM;标准矢量底图通过 `AmapBaseLayers.mapStyle()` 跟随主题(卫星 + 路网底图不受影响)。 - 对外 API:`Theme.current()` / `isDark()` / `set(theme)` / `toggle()` / `palette()` / `onChange(fn)` / `redrawCharts()` / `refreshControls()`,以及全局 `ChartPal()`;主题变化派发 `window` 上的 `themechange` 事件(`detail: { theme, dark, palette }`)。 验证脚本:`node target/dbinit/verify_theme.js`(DOM 桩,27 项断言覆盖默认浅色、切换持久化、跨标签同步、调色板、ECharts 补丁刷新、无图表环境降级)。 ## 快速开始 > 首次部署请按顺序执行 `db/init_risk_config.sql`、`db/init_business_tables.sql`、`db/init_geo_hazard.sql`、`db/init_forest_fire.sql`、`db/init_river_flood.sql` 五份建表脚本 > (见「配置持久化」「数据存储层」章节);后续模块还需 `db/init_urban_waterlogging.sql`、`db/init_risk_timeseries.sql`、`db/init_comprehensive.sql`,六个模块的预设场景台账执行 `db/init_scenario.sql`(见「分灾种场景管理」)。若配置表不存在或数据库不可达,服务会自动回退到 yml 默认值与内置演示台账,评估功能仍可用;离线演示可加 `--spring.profiles.active=mock`。 ### 构建项目 ```bash cd dynamic-risk-assessment-agent mvn clean package -DskipTests ``` ### 运行项目 ```bash mvn spring-boot:run ``` 或运行打包后的 JAR: ```bash java -jar target/dynamic-risk-assessment-agent-1.0.0.jar ``` 服务启动后访问:`http://localhost:8649` ### 运行测试 ```bash mvn test ``` 测试覆盖: - 风险等级判定逻辑(边界值验证) - 核心公式 R = H×E×V/(1+C) 正确性 - 防灾能力 C 的抑制作用验证 - 气象数据缺失处理(MET_MISSING) - H/E/V/C 超出 [0,1] 的裁剪逻辑 - 全流域评估集成测试 - 按风险等级过滤 - 高/低风险场景验证 ## Web 调试验证台 项目内置了一个基于纯 HTML/CSS/JS 的前端测试页面(深色科技感主题,ECharts 可视化),无需额外构建,Spring Boot 启动后直接访问。 ### 访问方式 启动项目后,在浏览器中打开: ``` http://localhost:8649/ ``` 或直接访问:`http://localhost:8649/index.html` ### 页面功能 页面采用三栏布局: #### 左侧栏 - **流域列表**:展示所有小流域(名称、编号、面积、比降),点击选中进行评估 - **预设场景**:6 个一键加载的典型场景(切换后自动刷新单流域详情与全流域地图 / 结果列表) - ⚡ 特大暴雨 — 极高风险场景 - 🌧️ 暴雨 — 高风险场景 - 🌦️ 中雨 — 中低风险场景 - ☁️ 小雨 — 低风险场景 - 🔥 典型山洪 — 短历时强降雨 + 高脆弱村落 - 💧 土壤饱和 — 前期降雨量大,临界雨量降低 - **全流域概览**:一键触发全流域评估 + 风险等级图例 #### 中间主展示区 - **风险分布面板(三态视图)**:位于中间列最上方,按风险等级着色**同时呈现多条流域评估结果**;工具栏提供「卡片列表 / 地图 / 风险矩阵」三个并列视图(详见下节与「评估单元 × 时刻风险矩阵」) - **逐时刻全点位风险回放**:分布面板顶部的滑块工具条,默认「总体风险(整场过程聚合)」;拖动后卡片列表与地图同时切换为该时刻所有点位的风险等级快照,支持 ▶ 播放 / ⏸ 暂停 / ↩ 总体(详见下节) - **逐时间节点风险 R(t) 曲线**:风险分布面板**之外**的独立单点信息面板(紧接分布面板下方常显),五灾种页面共用 `js/risk-timeline-chart.js`,展示当前选中单元过去实况 + 未来预报全时次的风险涨落、峰值与四级阈值,下方输出逐节点 H/E/V/C/R 明细表;可点「查看已落库批次」回放历史结果(详见「逐时间节点风险评估结果」一章)。切换分布视图或选中单元时曲线同步联动。 - **四要素雷达图**:H/E/V/C 四维可视化 - **降雨超阈比柱状图**:1h/3h/6h 降雨超阈比对比,带临界线参考 - **致灾因子明细表**:各历时降雨量、动态临界雨量、超阈比、API、α 系数 - **全流域评估结果列表**:支持按等级过滤(全部 / 中风险↑ / 高风险↑) #### 右侧参数面板 - **实时评估开关**:开启后参数变化自动重新评估(带 300ms 防抖) - **降雨参数**:1h/3h/6h 降雨量、前期影响雨量 API - **四要素参数**:暴露度 E、脆弱性 V、防灾能力 C(单流域调试覆盖;全流域评估使用各流域库内数据) - **模型阈值参数**(可折叠):各历时临界雨量 Pt、动态调整强度 β、H 归一化高低阈值、α 下限(Pt 仅作用于单流域调试) - **立即评估 / 重置参数** 按钮 ### 全流域风险分布地图(中间上方) 在中间主展示区最上方,以地图方式**同时显示多条流域的风险评估结果**。结果由 `js/app.js` 调用 `POST /api/risk/flash-flood/assess/custom/all`(携带当前预设场景参数)获取后注入 `RiskMap.update()`;流域名称 / 行政区 / 面积来自 `GET /api/risk/flash-flood/watersheds`。页面加载即自动评估一次,切换预设场景、调节降雨参数、点击「一键全流域评估」或地图右上角「刷新」都会重新计算。 | 呈现项 | 说明 | |--------|------| | 等级着色点位 | 低=青 / 中=黄 / 高=橙 / 极高=红;圆点内数字为风险等级,圆点大小随综合风险值 R 增大 | | 常驻标签 | 每个点位顶部常驻显示 `流域编号 + R 值`,无需点击即可同时读取多条结果 | | 信息窗体 | 点击点位展示流域属性、风险等级、R、H/E/V/C、最不利历时与提前量、WGS84 坐标 | | 顶部统计与图例 | 各等级数量、总流域数、四级色标 | | 联动 | 点击点位 → 选中该流域并刷新详情;点击左侧列表或结果列表 → 地图聚焦;「中风险↑ / 高风险↑」过滤按钮同时作用于地图点位 | | 刷新 | 重新拉取评估结果与流域元数据并重绘 | 地图使用**高德地图 JS API 2.0 官方 SDK 与官方卫星影像 / 路网注记图层**,与管理端共用同一份 Key 配置,源码不内置任何有效 Key:点击地图工具栏「⚙ 地图设置」粘贴 Key(仅存本机 `localStorage`),保存后刷新即生效,两页共用;也可按上文「配置自己的 Key」的方式二修改源码占位符。建议配置 Referer 域名白名单;商业或对外发布场景由后端代理鉴权后再下发 Key。 库内坐标是 **WGS84**,`js/risk-map.js` 在叠加卫星底图前统一正向转换为 **GCJ-02**(境外坐标原样返回),不要跳过转换。仅使用高德官方 SDK 与官方卫星影像 / 路网注记图层,不接入任何境外或第三方瓦片源。 **降级行为**:未配置 Key、SDK 加载失败或数据读取失败时,地图区域自动降级为「全流域风险分布清单」——卡片网格同样同时展示全部流域的等级、R 值与坐标,点击卡片仍可联动详情,评估计算与图表完全不受影响。 ### 五灾种评估结果视图切换(卡片列表 / 地图 / 风险矩阵 三态 + 独立时间轴面板) 五个灾种的**风险分布面板**内提供「**卡片列表**」「**地图**」「**风险矩阵**」三个互斥视图,由工具栏的 `.view-switch` 切换按钮控制;切换只改变分布结果的呈现方式,不会重新发起评估、不会影响详情面板与图表。**逐时间节点风险 R(t) 是单个评估单元的多要素时间序列**,不属于全流域/全点位分布视图,因此按需求移到分布面板之外,作为与「四要素剖面 / 致灾因子明细」并列的独立单点信息面板常显,切换视图时始终可见。 | 页面 | 分布面板默认视图 | 独立时间轴面板 id | 说明 | |------|------------------|-------------------|------| | `index.html`(山洪) | 地图 | `index-timeline-view` | 沿用原有的常驻「全流域风险分布地图」,可切到卡片列表 / 风险矩阵;时间轴常显于下方独立面板 | | `geo-hazard.html` / `forest-fire.html` / `river-flood.html` / `urban-waterlogging.html` | 卡片列表 | `geo-timeline-view` / `ff-timeline-view` / `rf-timeline-view` / `uw-timeline-view` | 保持原有风险分布卡片网格,地图 / 风险矩阵为可选视图;时间轴常显于下方独立面板 | - **通用组件**:`js/risk-result-map.js` 暴露 `window.RiskResultMap` 与 `window.ResultViewSwitch`(三态)以及 `window.RiskMatrix`。四个新增灾种页面在 `init()` 里传入 `switchId / cardsId / mapId / statusId / timelineId / matrixId / getBaseResults / matrix / onShowTimeline / getResults / onSelect`,并在结果刷新、等级过滤后调用 `ResultViewSwitch.update()` / `.setFilter()`;`update()` 无论当前是卡片还是地图,都会回调 `onShowTimeline()` 重绘独立时间轴面板。`timelineId` 仅为兼容旧参数保留,组件不再隐藏/显示时间轴。 - **懒加载**:默认卡片列表(山洪默认地图)时不加载高德 SDK;只有首次切到「地图」才按需加载官方 SDK 并渲染点位。独立时间轴面板不产生任何外部请求。 - **独立时间轴面板**:常显于分布面板下方,头部显示「当前单元」,曲线随左侧列表 / 地图点位 / 卡片点击联动;`RiskTimelineQuick.activate()` 只做滚动定位与 `RiskTimelineChart.resize()`,历史调用 `show('timeline')` / `showResultView('timeline')` 同样只定位、不改变分布视图。 - **山洪页接线**:`js/app.js` 的 `showResultView()` 支持三态,同时切换地图容器 / 卡片容器 / 矩阵容器 / 图例 / 页脚与标题文案;切回地图时调用 `RiskMap.resize()` 重算画布尺寸,避免 `display:none` 期间初始化导致的空白地图;切视图时同步刷新独立时间轴面板。 - **样式互斥**:`css/modules.css` 的 `[hidden]` 规则带 `!important`,覆盖 `.geo-hero-grid { display:grid }` 与 `.rf-chain { display:flex }`,保证卡片 / 地图 / 矩阵三视图严格互斥;`.risk-timeline-card` 用独立卡片样式与 300px 图表区呈现,不受视图切换影响。 - **入口可见性与缓存**:顶部 `.top-stats` 的 `.btn-timeline-quick` 是醒目入口,`.risk-map-toolbar` / `.top-stats` 允许换行;五个页面加 no-cache meta 且本地资源带 `?v=` 版本号,重新部署后强制拿到新页面。 - **点位与联动**:地图按四级风险着色(青 / 黄 / 橙 / 红),点击点位或降级清单卡片联动详情;等级过滤同时作用于卡片与地图;`MET_MISSING` 缺测结果在地图清单中单独标注,不与低风险混淆。 - **合规与降级**:Key 仍走「⚙ 地图设置」写入本机 `localStorage`,源码不内置有效 Key;底图统一为高德官方卫星影像,库内 WGS84 坐标叠加前统一转 GCJ-02。未配置 Key、SDK 失败或点位无坐标时,地图视图自动降级为「风险分布清单」卡片网格;ECharts 缺失时时间轴降级为逐节点明细表。评估与 CRUD 完全不受影响。 - **验证**:`target/dbinit/verify_result_views.py`(三态结构 + 独立时间轴面板 + 服务可达性 + 五灾种坐标)、`target/dbinit/verify_risk_timeline.py`(时间轴为面板外独立卡片 + 三态接线)、`target/dbinit/test_result_view_runtime.js`(通用组件 DOM mock 三态运行时)、`target/dbinit/test_index_runtime.js`(山洪整页三态视图切换与按钮点击)、`target/dbinit/test_timeline_quick_runtime.js`(顶部快捷入口滚动定位)全部通过;逐时刻回放另有 `verify_timeline_scrubber.py`(五页接线 + 五灾种接口 timeline 数据自洽)与 `test_timeline_scrubber_runtime.js`(帧构造 / 播放 / 缺测 / 视图联动);卫星影像底图另有 `verify_satellite.py` 与 `test_satellite_layers.js`。 ### 逐时刻全点位风险分布回放(时间轴拖动) 「卡片列表 / 地图 / 风险矩阵」三态视图默认展示 **所有点位的总体风险情况**(整场过程聚合后的单值 R 与四级等级,来自 `AssessmentResponse.results` 与 `levelStats`),这部分保持不变。在分布面板顶部另加一条**逐时刻全点位风险回放工具条**:把每个点位结果内联的 `results[i].timeline` 按时间节点对齐成帧,拖动滑块即可横向对比**同一时刻所有点位的风险等级**,卡片列表、地图、顶部统计条与左侧点位列表同步换帧。 | 能力 | 说明 | |------|------| | 总体 / 逐时刻互斥 | 默认「总体风险(整场过程聚合)」;拖动滑块或 ▶ 播放进入逐时刻帧,点 ↩ 总体 回到原视图 | | 拖动 / 播放 | 滑块 `oninput` + `onchange` 双通道;▶ 播放按 700ms 逐帧循环,⏸ 暂停清除定时器 | | 帧构造 | 以 `timeline` 最长的点位为基准建帧,帧元数据含时刻 / 相位 / 驱动量;短序列点位在该帧标 `NO_TIMELINE` | | 数据归一 | 后端节点 `riskLevel` 是数字 1~4,帧行统一转成 `LEVEL_N` + `blue/yellow/orange/red`,兼容地图与卡片组件 | | 台账字段保留 | 帧行由总体行拷贝,保留编号、名称、经纬度、台账属性与**完整 `timeline`**,地图可绘、单点面板可读 | | 缺测语义 | `MET_MISSING` / `PARAM_ERROR` / `COMPUTE_ERROR` / `NO_TIMELINE` 一律 `riskLevel: null`、灰色「无结果」,不冒充低风险 | | 统计重算 | 逐时刻模式按当前帧重算低 / 中 / 高 / 极高 / 无结果数量,回填 `stat-high` 与 `{prefix}-dist-stats` | | 零额外请求 | 全部数据来自已有的 `/assess/custom/all` 响应,不新增接口、不加载外部资源 | | 时刻格子 | 轨道一格一个时间节点,格内直接显示 `HH:mm`;跨天首格额外补 `MM-dd` 日期分界,`title` 给出完整日期时间、相位、最高等级与缺测数 | | 最高等级色条 | 每格顶部色条取该时刻全场 `max(riskLevel)` 的颜色:蓝 / 黄 / 橙 / 红依次对应低 / 中 / 高 / 极高;全部缺测为灰条、不显示角标,避免把「无结果」冒充低风险 | | 数量角标 | 角标 = 该时刻达到最高风险等级的点位数(综合页为行政区域数),由 `framePeak()` 在结果刷新时预计算到 `state.peaks`,切帧只切 `active` 不重算 | | 选中指示 | 选中格高亮并在下方显示三角指示,同步 `aria-pressed`;点击格内时间文字 / 色条 / 角标均可切帧,事件委托只认数字 `data-ts-frame`,不影响 ▶ 播放 / ↩ 总体 | | 跨度与图例 | 轨道上方给出首末时刻与总帧数,并列出四级色 + 灰「无结果」图例,避免跨天只看 `HH:mm` 产生歧义 | | 贴合宽度 + 翻页 | 每页格数 `pageSize` 按轨道可用宽度计算(3~12 格、单格最小 88px),CSS 用 `grid-template-columns: repeat(var(--ts-page-size), minmax(0,1fr))` 平分;`‹ / ›` 按钮与「第 x / y 页」页码翻看其余时刻。**轨道总宽恒等于容器宽度**,容器链统一 `min-width:0 / max-width:100%`,不产生页面级横向滚动条 | | 自动跟随 | 点击 / 播放 / 滑块切帧自动翻到该帧所在页;格子的 `data-ts-frame` 始终是全局帧索引,翻页不改变当前选中帧与结果视图;`resize` 或结果刷新后重算页数并保持当前帧可见 | - **组件接口**:`js/risk-timeline-scrubber.js` 暴露 `window.RiskTimelineScrubber`:`init / update / activeRows / stats / isActive / isPlaying / frameCount / index / frame / framePeaks / page / pageCount / pageSize / setPage / setIndex / reset / play / pause`;`init` 可传 `pageSize` 固定每页格数,不传则按容器宽度自适应;`framePeaks()` 返回每帧 `{level, color, name, count, missing, total}`,`_utils` 另暴露 `shortTime / dayOf / framePeak / statsOf / buildFrames / frameRows / levelOf` 等纯函数供回归脚本校验。脚本顺序为 `risk-timeline-chart.js` → `risk-timeline-scrubber.js` → 页面主逻辑。 - **页面接线**:五页 HTML 在分布面板内插入 `
`;四个模块页与 `js/app.js` 统一用 `displayResults()` 作为卡片网格 / 结果列表 / 点位列表 / 地图的数据源——总体模式返回 `state.results` / `state.allResults`,逐时刻模式返回 `activeRows()`。`ResultViewSwitch` 的 `getResults` 也改为 `displayResults`;`app.js` 另用 `updateTopStats()`、`RiskMap.update(displayResults())` 同步刷新。 - **互补关系**:下方的**单点 R(t) 独立面板**展示某个单元在多个时刻的 H/E/V/C/R 过程曲线,始终读总体结果,不受帧切换影响;回放期间 `renderRiskTimelineFromResults()` 直接跳过,避免每帧重复 `setOption` 造成闪烁。回放工具条展示的是「一个时刻 × 全部点位」,单点曲线展示的是「一个点位 × 全部时刻」,两者互不替代。 - **结果刷新**:每次 `/assess/custom/all` 返回后调用 `RiskTimelineScrubber.update()` 重建帧,保留当前帧索引与播放状态;无 `timeline` 时自动退回总体并提示「本次评估未返回逐时间节点结果,无法回放」。 - **样式**:`css/modules.css` 在 `.timeline-scrubber` 上定义 `--ts-frame-*` / `--ts-level-*` CSS 变量,并追加 `.ts-track-wrap / .ts-track-range / .ts-legend / .ts-track / .ts-frame / .ts-frame-bar / .ts-frame-badge / .ts-frame-day / .ts-frame-time / .ts-frame.active::after`;原滑块改为轨道下方的细进度线,`.ts-controls` 位于头部右侧。`css/theme.css` 的 `[data-theme="light"] .timeline-scrubber` 只覆盖格子表面色(白底深字 + 浅蓝选中态),**四级风险色不随主题改变**。新增 `.ts-track-row / .ts-page-btn / .ts-page-info`,翻页按钮在浅色主题下有独立配色与首尾页禁用态;工具条常显,不参与 `cards / map` 互斥切换。 - **回归**:`target/dbinit/test_timeline_frames.js`(19 项 DOM mock:每帧最高等级 / 色条 / 角标 / `HH:mm` / 跨天 `MM-dd` / 全缺测灰条 / 点击切帧 / `aria-pressed` / 双主题变量)与新增 `test_timeline_pager.js`(21 项:宽度自适应 / 分页渲染 / 翻页按钮 / 全局索引 / 自动跟随 / 播放跨页 / resize / 无横向滚动 CSS)及既有 `test_timeline_scrubber_runtime.js`、`verify_timeline_scrubber.py` 全部通过。 - **静态资源版本**:十一个页面本地 JS/CSS 统一带版本查询串,避免预览面板复用旧页面(当前全站 `?v=20261116c`);三个后台页面共用的 `admin.css` / `admin.js` 同样带该版本串,改动后必须重新打包并用新版本 URL 刷新。 - **顶栏时间轴快捷入口已隐藏**:六个评估页顶栏原有的「⏱ 风险时间轴」按钮(`#btn-timeline-quick`)已从 HTML 移除,并由 `modules.css` 的 `.top-stats .btn-timeline-quick{display:none!important}` 兜底。R(t) / CRI(t) 时间轴面板本身仍常显、不参与视图切换;`?view=timeline` 直达链接、`window.RiskTimelineQuick.activate()` 与历史 `[data-timeline-open]` 入口仍可用,仅去掉顶栏跳转按钮。 ### 评估单元 × 时刻风险矩阵(第三个并列结果视图) 参考「赛事智能风险研判」的「赛事 × 时次全貌」矩阵,六个评估页的结果分布视图由「卡片列表 / 地图」两态扩展为 **卡片列表 / 地图 / 风险矩阵** 三态并列标签页。第三个按钮统一为 `data-view="matrix"`,容器 `{prefix}-risk-matrix`,通用脚本 `js/risk-matrix.js` 在 `risk-timeline-scrubber.js` 之后、页面主逻辑之前加载;五个后台 / 占位页不引入该组件。 | 能力 | 说明 | |------|------| | 行 × 列 | 行 = 评估单元(`unitId` / `village`,按 `district`、`adminLevelName` 等分组,可全部展开 / 收起),列 = `results[i].timeline` 对齐出的逐时刻时间轴,列头 `HH:mm`、跨天补 `MM-dd` | | 两种着色口径 | 默认「风险等级」= 该单元该时刻的四级风险(低蓝 / 中黄 / 高橙 / 极高红);切换「中及以上数」后行折叠为分组,色 = 该分组该时刻达到中风险及以上的单元数分档 **0 / 1–2 / 3–4 / ≥5**,与参考设计一致 | | 缺测语义 | `MET_MISSING` / `NO_TIMELINE` / 无等级一律灰格,不冒充低风险;`title` 与底部详情条给出完整时刻、等级、R 值或中及以上数量 | | 起止时间筛选 | 两个 `datetime-local` 输入按 `slotTime` 过滤列,默认全量程;无法解析的时刻不参与筛选,避免稀疏桶被误丢弃 | | 贴合宽度 + 翻页 | 每页列数 `pageSizeFor(width, fixed)` 按容器宽度计算(4~14 列、单格最小 52px),CSS 用 `grid-template-columns: var(--rm-label-w) repeat(var(--rm-cols), minmax(0,1fr))` 平分;`‹ / ›` 按钮与「第 x / y 页」页码翻看其余时刻。`data-rm-slot` 始终是**全局时刻索引**,行区只纵向滚动,面板 `min-width:0 / max-width:100% / overflow:hidden`,不产生页面级横向滚动条 | | 点击联动 | 点击格子高亮并回调 `onSelect(unitId, slotIndex, slotTime, info)` 定位该单元,再由组件调用 `RiskTimelineScrubber.setIndex(slotIndex)` 切到该时次;回放切帧时矩阵自动高亮对应列并翻到该列所在页,选中格子保持不变 | | 数据源 | 必须消费含完整 `timeline` 的**总体结果**(`state.results` / `state.allResults`),不能用 `displayResults()` 的回放当前帧;综合页复用 `scrubberRows()` 的稠密 25 桶,避免稀疏区域被补成假零风险。零额外请求、零外部资源 | | 双主题 | `modules.css` 在 `.risk-matrix-panel` 定义 `--rm-*` 表面色与四级风险色;`theme.css` 的 `[data-theme="light"] .risk-matrix-panel` 只覆盖白底深字与按钮配色,**四级风险色不随主题改变** | - **组件接口**:`window.RiskMatrix` 暴露 `init / update / setVisible / setMode / mode / setExpanded / expanded / setPage / page / pageCount / pageSize / setActiveSlot / activeSlot / selection / slots / visibleSlots / groups / units / cells / focus / isVisible`;`_utils` 暴露 `timeKey / shortTime / dayOf / toInput / levelOf / bandOf / cellOf / countOf / buildSlots / buildModel / pageSizeFor` 等纯函数供回归校验。 - **页面接线**:`ResultViewSwitch` 新增 `matrixId` / `getBaseResults` / `matrix` 三个选项,`showView` 改三态并在结果刷新时调 `RiskMatrix.update()`;山洪页 `app.js` 与综合页 `comprehensive-risk.js` 各自实现三态切换与矩阵初始化,四个单灾种模块页由通用切换器统一接管。综合页按 `adminCode` / `adminName` / `adminLevelName` 组织行与分组,矩阵视图下隐藏地图图例与公式说明。 - **直达链接**:六个评估页均支持 `?view=matrix` 直接打开风险矩阵标签页(通用 `ResultViewSwitch`、山洪 `app.js`、综合 `comprehensive-risk.js` 各读一次 `location.search`),便于分享与预览。 - **回归**:`target/dbinit/test_risk_matrix_runtime.js`(30 项 DOM mock:时刻解析 / 等级与分档 / 分组建模 / 两种口径 / 起止筛选 / 列分页与全局索引 / 点击联动 / 回放列高亮 / 折叠 / 说明 / resize / XSS)与 `verify_risk_matrix.py`(页面接线 / 三态切换 / 双主题 / 无横向滚动 / 版本串 / 脚本顺序 / 直达参数)。 - **静态资源版本**:本次改动统一升到 `?v=20261116c`,十一个页面与 README / 技术方案保持同步。 ### 预设场景与全流域评估联动 早期「一键全流域评估」走 `GET /api/risk/flash-flood/assess/all`:后端构造空的 `AssessmentRequest`、使用固定 Mock 气象数据,**不接收任何前端参数**,因此切换预设场景后全流域风险值恒定不变。现已修复: - 新增 `POST /api/risk/flash-flood/assess/custom/all`(详见下节),前端把当前面板的场景输入提交给后端;服务端遍历所有流域,复用 `assessWithCustomParams` 逐流域重算,返回与 `/assess/all` 同结构的 `AssessmentResponse`(含 `levelStats`)。 - `js/app.js` 抽出 `collectParams(opts)`:单流域评估提交全部参数,全流域评估只提交降雨 / API / 模型系数;`refreshAssessment()` 统一刷新单流域详情与全流域结果,预设场景切换、重置、参数滑杆(300ms 防抖)、实时评估开关都走它。 - `js/risk-map.js` 的地图「刷新」按钮通过 `window.RiskMapRefresh` 复用同一套参数重算,不会退回到无参的默认结果。 **参数作用域**(重要): | 参数 | 全流域评估 | 单流域详情 | |------|-----------|-----------| | 1h/3h/6h 降雨、API、β、H 归一化高低阈值、α 下限 | ✅ 作为场景输入作用于每个流域 | ✅ | | 临界雨量阈值 Pt(1h/3h/6h) | ❌ 按各流域配置表基线读取 | ✅ 面板覆盖值 | | 暴露度 E、脆弱性 V、防灾能力 C | ❌ 按各流域 `exposure_data` / `capacity_data` / 插件计算 | ✅ 面板覆盖值 | 这样设计是为了让**同一场景下各流域风险值仍互不相同**(1h 转移雨量 50/55/65/40mm、E 0.82/0.65/0.38/0.42、C 0.72/0.62/0.50/0.40),且管理端修改这些业务数据能直接反映到地图与结果列表。切换场景时 4 个流域的 R 值同步变化:小雨场景全部为 0,特大暴雨场景为 0.124~0.439,等级分布从 `low:4` 变为 `low:1 / medium:3`。 > 极端场景下危险性 H 会因分段归一化饱和(小雨全 0、特大暴雨全 1),此时流域间差异主要来自 E/C;中等降雨落在 H 的线性区间,阈值差异体现得最明显。这是模型固有特性,不是计算错误。 验证脚本:`target/dbinit/verify_scenario.py`(小雨 / 中等 / 特大暴雨三场景,断言 4 个流域 R 全部变化、同场景内互不相同、levelStats 变化、各流域使用自身 E/C)。 ### 后端新接口 为支持前端参数调试,新增接口: **POST** `/api/risk/flash-flood/assess/custom` 使用自定义参数进行单流域评估,前端调节参数后调用此接口。 请求体: ```json { "unitId": "WS_001", "p1h": 30.0, "p3h": 60.0, "p6h": 80.0, "api": 40.0, "exposure": 0.65, "vulnerability": 0.6, "capacity": 0.5, "pt1h": 50.0, "pt3h": 80.0, "pt6h": 110.0, "beta": 0.5, "hazardLowRatio": 0.6, "hazardHighRatio": 1.2, "alphaMin": 0.4 } ``` 所有参数除 unitId 外均可选,未传则使用默认值或流域配置值。 **POST** `/api/risk/flash-flood/assess/custom/all` 使用当前预设场景参数**批量评估全部流域**。请求体字段与 custom 接口相同,但 `unitId` 被忽略;全流域评估只需提交场景输入(E/V/C 与 Pt 由后端按各流域自身数据读取,见上节): ```json { "p1h": 55.0, "p3h": 110.0, "p6h": 160.0, "api": 60.0, "beta": 0.5, "hazardLowRatio": 0.6, "hazardHighRatio": 1.2, "alphaMin": 0.4 } ``` 响应与 `GET /assess/all` 同结构:`totalUnits` / `levelStats` / `results[]`,前端可直接复用结果列表与地图渲染。`GET /assess/all` 保留兼容(仍基于固定 Mock 数据),不再作为调试台的数据源。 ### 技术说明 - 前端框架:原生 HTML + CSS + JavaScript(无构建工具) - 图表库:ECharts 5.4.3(Apache-2.0,**本地内置** `static/js/vendor/echarts.min.js`,不依赖外网 CDN) - 图表降级:`app.js` 在 `echarts` 未加载或初始化失败时显示占位提示,并继续完成流域加载、参数配置、事件绑定与评估计算,页面不会整体失效 - 风险分布地图:`js/risk-map.js`(高德官方 SDK,WGS84→GCJ-02,未配置 Key 时降级为风险分布清单) - 地图 Key 自助配置:`js/amap-config.js` 只保留占位符 + `js/amap-settings.js` 弹窗把 Key 写入本机 `localStorage`,两页共用,保存后刷新生效 - 后端接口:复用现有 REST API + 新增 custom 评估接口 - 页面文件位于 `src/main/resources/static/`,Spring Boot 自动托管 ## REST API 接口 ### 1. 山洪风险评估 **POST** `/api/risk/flash-flood/assess` 请求体(可选,不传则评估全部流域): ```json { "hazardType": "FLASH_FLOOD", "unitId": "WS_001", "baseTime": "2026-06-15T14:00:00", "minLevel": 2 } ``` | 参数 | 类型 | 说明 | |------|------|------| | hazardType | 枚举 | 灾种类型,默认 FLASH_FLOOD | | unitId | 字符串 | 指定小流域 ID,为空评估全部 | | baseTime | 日期时间 | 评估基准时间,为空使用当前时间 | | minLevel | 整数 | 最低返回等级(1-4),用于过滤 | 响应示例: ```json { "hazardType": "FLASH_FLOOD", "assessmentTime": "2026-06-15T14:00:00", "totalUnits": 4, "levelStats": { "low": 1, "medium": 1, "high": 1, "extremelyHigh": 1 }, "results": [ { "unitId": "WS_001", "village": "青龙沟", "lon": 105.235, "lat": 32.518, "hazard": 0.88, "exposure": 0.82, "vulnerability": 0.72, "capacity": 0.72, "riskValue": 0.303, "riskLevel": "LEVEL_2", "color": "yellow", "factors": { "p1h": 58.0, "p3h": 92.0, "p6h": 120.0, "api": 71.0, "cr1hDynamic": 42.0, "cr3hDynamic": 67.2, "cr6hDynamic": 92.4 }, "dominantDuration": "1h", "leadTimeMin": 45, "metVersion": "NOW@14:00|OBS@14:00|FCST@14:00", "status": "OK" } ] } ``` ### 2. 快速评估接口 **POST** `/api/risk/flash-flood/assess/custom/all` — 用当前场景参数批量评估全部流域(调试台「一键全流域评估」使用) **GET** `/api/risk/flash-flood/assess/all` — 评估全部流域(固定 Mock 数据,兼容保留) **GET** `/api/risk/flash-flood/assess/{unitId}` — 评估指定流域 ### 3. 流域信息 **GET** `/api/risk/flash-flood/watersheds` — 查询所有小流域 **GET** `/api/risk/flash-flood/watersheds/{unitId}` — 查询指定小流域详情 ### 4. 参数查询 **GET** `/api/risk/flash-flood/params` — 获取山洪参数包(阈值、系数等,取自当前生效配置) **GET** `/api/risk/flash-flood/config` — 获取完整配置(含各流域临界雨量) ### 5. 配置管理接口(数据库持久化) **GET** `/api/risk/config/list` — 运行时生效的全部配置与各流域阈值 **GET** `/api/risk/config/db/all` 与 `/api/risk/config/db/critical-rainfall` — 查看两张配置表的原始记录 **PUT** `/api/risk/config/{key}` — 修改参数并写库 **POST** `/api/risk/config/refresh` — 改库后刷新缓存(无需重启) **POST** `/api/risk/config/sync-yml` — 把 yml 新增配置补齐入库 详见 [配置持久化(数据库)](#配置持久化数据库)。 ### 6. 地质灾害风险评估 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/geo-hazard/sites` | 全部隐患点 / 斜坡单元台账 | | GET | `/api/risk/geo-hazard/sites/{siteId}` | 指定隐患点详情 | | GET | `/api/risk/geo-hazard/params` | 生效参数包,可选 `zoneCode`(默认 `ZONE_HIGH`)、`hazardKind`(默认 `ALL`) | | GET | `/api/risk/geo-hazard/scenarios` | 6 个预设验证场景 | | GET | `/api/risk/geo-hazard/assess/all` | 全部隐患点默认场景评估 | | GET | `/api/risk/geo-hazard/assess/{siteId}` | 单隐患点默认场景评估 | | POST | `/api/risk/geo-hazard/assess/custom` | 自定义降雨场景单点评估(支持 S/E/V/C 覆盖) | | POST | `/api/risk/geo-hazard/assess/custom/all` | 自定义场景全量评估,S/E/V/C 与临界曲线按各隐患点台账读取 | ### 7. 森林火灾风险评估 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/forest-fire/stands` | 全部网格 / 林班台账(可燃物本底、E/V/C、分区、点位) | | GET | `/api/risk/forest-fire/stands/{standId}` | 指定林班详情 | | GET | `/api/risk/forest-fire/zones` | 火险气象分区参数清单(3 个分区) | | GET | `/api/risk/forest-fire/params` | 生效参数包,可选 `zoneCode`(默认 `FF_ZONE_HIGH`),含 FWI 权重、等级节点、有效降水阈值与参数来源 | | GET | `/api/risk/forest-fire/scenarios` | 8 个预设验证场景 | | GET | `/api/risk/forest-fire/assess/all` | 全部林班默认场景评估 | | GET | `/api/risk/forest-fire/assess/{standId}` | 单林班默认场景评估 | | POST | `/api/risk/forest-fire/assess/custom` | 自定义火险气象场景单点评估(支持 B/E/V/C 覆盖) | | POST | `/api/risk/forest-fire/assess/custom/all` | 自定义场景全量评估,B/E/V/C 与分区参数按各林班台账读取 | 自定义场景请求体(字段均可省略,省略时取内置默认或台账值): ```json { "standId": "FF_002", "scenario": "drought_wind", "tempMax": 35.0, "rhMin": 18.0, "windMax": 14.0, "todayRainfall": 0.0, "forecastRainfall": 0.0, "dryDays": 22, "historyDays": 30, "metAvailable": true, "paramOverrides": { "ff_grade4": 0.6 } } ``` `dryDays` 传 `null` 时由后端按 `forest_fire_daily_met` 历史日降水序列自动统计连续干燥日数;`metAvailable=false` 返回 `MET_MISSING`(不输出风险等级),历史日序列不足返回 `PARTIAL`。**全量接口只提交火险气象场景输入**,`baseFlammability` / `exposure` / `vulnerability` / `capacity` 覆盖值在批量评估时被忽略,保证同一场景下各林班风险仍互不相同(`ForestFireAssessRequest.copyForStand()`)。 配置优先级:`paramOverrides` > `forest_fire_zone` 分区参数 > `sys_risk_config(hazard_type='FOREST_FIRE')` 全局参数 > 内置默认值。 ### 8. 流域洪涝风险评估 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/river-flood/reaches` | 全部河段控制单元台账(上下游拓扑、承泄能力、E/V/C、点位) | | GET | `/api/risk/river-flood/reaches/{reachId}` | 指定河段详情 | | GET | `/api/risk/river-flood/zones` | 水系分区参数清单(3 个分区) | | GET | `/api/risk/river-flood/params` | 生效参数包,可选 `zoneCode`(默认 `RF_ZONE_MID`),含 API、动态临界面雨量、Q 分段、退水与演进参数及来源 | | GET | `/api/risk/river-flood/scenarios` | 9 个预设验证场景 | | GET | `/api/risk/river-flood/assess/all` | 全部河段默认场景评估 | | GET | `/api/risk/river-flood/assess/{reachId}` | 单河段默认场景评估 | | POST | `/api/risk/river-flood/assess/custom` | 自定义面雨量场景单点评估(支持 S/E/V/C 覆盖) | | POST | `/api/risk/river-flood/assess/custom/all` | 自定义场景全量评估,S/E/V/C 与河网拓扑按各河段台账读取 | 自定义场景请求体(字段均可省略,省略时取内置默认或台账值): ```json { "reachId": "RF_005", "scenario": "upstream_cascade", "arealRain24h": 20.0, "rainHours": 6, "rainEndHoursAgo": 0, "forecastRainPerHour": 1.0, "forecastHours": 72, "shortTermRainPerHour": 0.0, "nowRainPerHour": 0.0, "antecedentScale": 1.0, "historyDays": 15, "hoursSinceRain": null, "upstreamRainScale": 6.0, "metAvailable": true, "paramOverrides": { "rf_critical_rain_base_mm": 110.0 } } ``` `hoursSinceRain` 传 `null` 时由后端按逐小时实况序列自动判定雨停时长;`upstreamRainScale > 1` 模拟上游暴雨、本区间小雨;`metAvailable=false` 返回 `MET_MISSING`,历史日面雨量序列不足返回 `PARTIAL`。**全量接口只提交面雨量场景输入**,`conveyanceDeficit` / `exposure` / `vulnerability` / `capacity` 覆盖值在批量评估时被忽略。 配置优先级:`paramOverrides` > `river_flood_zone` 分区参数 > `sys_risk_config(hazard_type='RIVER_FLOOD')` 全局参数 > 内置默认值。 ### 9. 城市内涝风险评估 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/urban-waterlogging/sites` | 全部易涝点 / 排水分区台账(设计重现期、各历时设计雨强、D、E/V/C、点位) | | GET | `/api/risk/urban-waterlogging/sites/{siteId}` | 指定易涝点详情 | | GET | `/api/risk/urban-waterlogging/zones` | 排水分区参数清单(3 个分区) | | GET | `/api/risk/urban-waterlogging/params` | 生效参数包,可选 `zoneCode`,含 Q 分段、退水时间常数、要害对象下限等及来源 | | GET | `/api/risk/urban-waterlogging/scenarios` | 10 个预设验证场景 | | GET | `/api/risk/urban-waterlogging/records/{siteId}` | 指定易涝点历史积水事件 | | GET | `/api/risk/urban-waterlogging/assess/all` | 全部易涝点默认场景评估 | | GET | `/api/risk/urban-waterlogging/assess/{siteId}` | 单易涝点默认场景评估 | | POST | `/api/risk/urban-waterlogging/assess/custom` | 自定义短历时降水场景单点评估(支持 D/E/V/C 覆盖) | | POST | `/api/risk/urban-waterlogging/assess/custom/all` | 自定义场景全量评估,D/E/V/C 与设计雨强按各点位台账读取 | 自定义场景请求体核心字段(均可省略):`scenario`、`obsRain5min`(近 60min 逐 5min 实况)、`nowcastRain10min`(0~2h 逐 10min 短临)、`peakBoost`、`burstSlots`、`hourlyObsRain`、`hourlyFcstRain`、`nowcastSlots`、`minutesSinceRain`、`metAvailable`、`nowcastAvailable`、`paramOverrides`(`uw_*`)。**全量接口只提交短历时降水场景输入**,`drainageDeficit` / `exposure` / `vulnerability` / `capacity` 覆盖值在批量评估时被忽略(`UrbanWaterloggingAssessRequest.copyForSite()`),且 `collectOverrides()` 只提交偏离 HTML 默认值的可率定参数,避免抹平点位差异。`metAvailable=false` 或 `nowcastAvailable=false` 返回 `MET_MISSING`,短临时次不足返回 `PARTIAL`。 配置优先级:`paramOverrides` > `urban_waterlogging_zone` 分区参数 > `sys_risk_config(hazard_type='URBAN_WATERLOGGING')` 全局参数 > 内置默认值。 ### 10. 逐时间节点风险结果查询 五个灾种的评估响应本身已内联 `timeline`(每个时间节点含 H/E/V/C/R、等级、相位、驱动量)、`timelinePointCount` / `timelinePeakRisk` / `timelinePeakTime` 与 `batchId`;本节接口提供按批次 / 单元 / 灾种的历史回溯能力。 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/timeline/summary` | 存储状态概览:`enabled` / `storage`(MYSQL\|MEMORY) / `keepBatches` / `minIntervalSeconds` / 批次数 | | GET | `/api/risk/timeline/batches` | 批次列表,可带 `hazardType`,按时间倒序 | | GET | `/api/risk/timeline/latest` | 最近一次评估的时间节点,可带 `hazardType` / `unitId` / `limit` | | GET | `/api/risk/timeline/points` | 通用明细查询:`batchId` / `hazardType` / `unitId` 任意组合 + `limit` | | GET | `/api/risk/timeline/batch/{batchId}` | 指定批次全部时间节点,可带 `unitId` | 明细点字段:`slotIndex` / `slotTime` / `phase` / `phaseLabel` / `driverName` / `driverValue` / `hazard` / `exposure` / `vulnerability` / `capacity` / `riskValue` / `riskLevel` / `riskLevelName` / `color` / `status` / `unitId` / `hazardType`。缺测节点 `riskLevel=null`、`riskValue=0`、`status=MET_MISSING`,与真实低风险区分。落库由 `RiskTimelinePersistenceAdvice` 统一触发,异常只记 warn 不影响评估响应,配置见「逐时间节点风险评估结果」一章。 ### 11. 行政区域综合风险评估 主数据源为 `POST /api/risk/comprehensive/assess/custom/all`,请求体(字段均可省略): ```json { "scenario": "multi_hazard", "method": "MAX_WEIGHTED", "adminLevel": "TOWNSHIP", "horizon": "CURRENT", "includeHazards": ["FLASH_FLOOD", "GEO_HAZARD", "FOREST_FIRE", "RIVER_FLOOD", "URBAN_WATERLOGGING"], "paramOverrides": { "cr_alpha": 0.6, "cr_gamma": 0.12 } } ``` 响应核心字段:`results[]`(全县三级 26 个行政区,含 `hazardRisks` / `hazardContrib` / `timeline` / `children`)、`ranking[]`(当前层级 CRI 降序)、`levelStats`、`summary`(县域 CRI / 高风险区域 / 并发区域 / 主导灾种分布 / 调度建议)、`weights` / `params` / `sourceVersions` / `participatingHazards` / `missingHazards` / `inputUnitCounts` / `batchId` / `status`。 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/risk/comprehensive/regions`、`/regions/{adminCode}` | 行政区台账 | | GET | `/api/risk/comprehensive/units` | 行政区—单元映射(34 条) | | GET | `/api/risk/comprehensive/params` | 生效参数 + 两级公式 + 权重模板 | | GET | `/api/risk/comprehensive/weights` | 五类区域灾种权重模板 | | GET | `/api/risk/comprehensive/scenarios` | 8 个多灾种联动场景 | | GET | `/api/risk/comprehensive/assess/all` | 默认场景全量评估 | | GET | `/api/risk/comprehensive/assess/{adminCode}` | 默认场景单区域研判卡 | | POST | `/api/risk/comprehensive/assess/custom` | 自定义场景单区域评估 | | POST | `/api/risk/comprehensive/assess/custom/all` | 自定义场景全县三级评估 | | GET | `/api/risk/comprehensive/ranking?adminLevel=TOWNSHIP` | 最近一轮排行榜 | | GET | `/api/risk/comprehensive/summary` | 最近一轮综合态势简报 | | GET | `/api/risk/comprehensive/history` | 跨轮次态势历史(`items[]`) | `data_gap` 场景返回 `status=PARTIAL`、`missingHazards=["FOREST_FIRE"]`、`participatingHazards` 为 4 类,且缺项灾种不进入 `hazardContrib`。模型公式、数据表与前端展示见「行政区域综合风险动态评估模型」一章。 ## 示例数据说明 内置 4 个典型小流域的 Mock 数据,覆盖不同风险场景: | 流域ID | 名称 | 降雨强度 | 暴露度 | 预期风险 | |--------|------|----------|--------|----------| | WS_001 | 青龙沟 | 特大暴雨 (60mm/h) | 高 (0.82) | 高/极高风险 | | WS_002 | 白沙河 | 大雨 (25mm/h) | 中 (0.65) | 中风险 | | WS_003 | 翠溪谷 | 小雨 (8mm/h) | 低 (0.38) | 低风险 | | WS_004 | 黑石沟 | 暴雨 (50mm/h) | 中 (0.42) | 高风险 | 每个流域包含:短临降水(5min×2h)、实况降水(1h×24h)、预报降水(1h×72h)、 承灾体暴露度 E、防灾能力 C、临界雨量参数等。 地质灾害、森林火灾与流域洪涝各内置 6 个评估单元(地灾隐患点 `GH_001`~`GH_006`、森火网格 / 林班 `FF_001`~`FF_006`、洪涝河段 `RF_001`~`RF_006`), 分别覆盖不同易发性 / 可燃物本底、E/V/C 与分区曲线 / 火险气象参数;每个单元配套 30 天历史日降水 / 日气象序列(共 360 条), 用于有效降水累积与连续干燥日数统计。台账已落库,可在共享管理端直接修改并即时作用于下一次评估。 ## 替换真实数据的方法 当前气象等动态数据仍由 Mock Repository 生成;流域、村落、暴露度、防灾能力等静态数据已入库(见「数据存储层」),实现对应 Repository 的 JPA 版本即可切换。替换为真实数据源步骤: ### 1. 气象数据 实现 `MetDataRepository` 接口: ```java @Repository public class RealMetDataRepository implements MetDataRepository { // 对接气象 API / 时序数据库 // 从 MET-NOW / MET-OBS / MET-FCST 数据源获取 } ``` 需要注意: - 短临数据(MET_NOW):5 分钟间隔,覆盖 0-2 小时 - 实况数据(MET_OBS):1 小时间隔,覆盖近 24 小时 - 预报数据(MET_FCST):1 小时间隔,覆盖未来 72 小时 ### 2. 小流域数据 实现 `WatershedRepository` 接口,从 PostGIS 或其他空间数据库读取小流域边界、属性、村落实体等。 ### 3. 承灾体 & 防灾能力 实现 `ExposureRepository` 和 `CapacityRepository` 接口,从台账数据库或预计算结果读取。 ### 4. 参数配置 各小流域的临界雨量阈值与模型参数已入库(见 [配置持久化(数据库)](#配置持久化数据库))。 `application.yml` 中的 `risk.flash-flood.watershed-params` 仅作为初始化种子与离线兜底值, 运行时以 `flash_flood_critical_rainfall` / `sys_risk_config` 两张表为准。 新增流域只需在 yml 中追加配置并重启,或调用 `POST /api/risk/config/sync-yml`, 服务会自动把新记录补齐入库,且不覆盖库中已调整过的阈值。 ## 扩展新灾种 按照插件化架构,新增灾种(如中小河流域洪涝)步骤: 1. **新增灾种枚举**:在 `HazardType` 中添加 2. **纯算法内核**:编写 `XxxRiskModel`(不依赖 Spring / DB,可独立单元测试),再实现 `XxxPlugin implements IHazardPlugin` - `getRequiredMetTypes()` — 声明必要气象因子 - `deriveFactors()` — 派生致灾指标(各灾种专用字段放入 `context` / `HazardFactors`) - `computeHazard()` — 计算危险性 H - `computeVulnerability()` — 计算脆弱性 V - `getParamPack()` — 返回参数包 3. **配置参数**:参数统一写入 `sys_risk_config(hazard_type='XXX')` 与灾种分区表,`application.yml` 只保留兜底说明,不写死阈值 4. **注册服务与接口**:添加 `XxxConfigService` / `XxxAssessmentService` / `XxxRiskController`,复用 `RiskComputeEngine` 5. **数据表与管理端**:编写幂等 `init_xxx.sql`,在 `AdminTableRegistry` 注册表(含 POINT 列与空间定位元数据) 6. **前端模块**:新增 `xxx.html` / `js/xxx.js`,把 `SystemController` 与 `module-nav.js` 中该模块状态改为 `ready`,`map-view.js` 增加图层 五个单灾种均已按此粒度上线:地质灾害(`GeoHazardRiskModel` → `GeoHazardPlugin` → 三张台账表 → `geo-hazard.html`)、森林火灾(`ForestFireRiskModel` → `ForestFirePlugin` → 三张台账表 → `forest-fire.html`)、流域洪涝(`RiverFloodRiskModel` → `RiverFloodPlugin` → 三张台账表 → `river-flood.html`)、城市内涝(`UrbanWaterloggingRiskModel` → `UrbanWaterloggingPlugin` → 三张台账表 → `urban-waterlogging.html`)。新增灾种无需另行接入时间轴:`RiskTimeline.attach()` 会在 `XxxAssessmentService` 返回前挂载 R(t),`RiskTimelinePersistenceAdvice` 自动落库,前端只需引入 `js/risk-timeline-chart.js` 并在结果渲染处调用 `RiskTimelineChart.render(r)`。综合风险是上层模块,粒度不同:`ComprehensiveRiskModel`(纯算法)→ 台账 / 映射 / 权重 / 输入输出模型 → `ComprehensiveScenarios` → `ComprehensiveRepositoryImpl` → `ComprehensiveConfigService` → `ComprehensiveAssessmentService`(消费五个单灾种 `assessAll`)→ `ComprehensiveRiskController` → `init_comprehensive.sql` → `AdminTableRegistry` 四表 → `comprehensive-region-map.js` → `comprehensive-risk.html/js`。新增灾种时还需同步 `SystemController.readyCount`、`module-nav.js` fallback、`admin.html`、`module-placeholder.html`、`HazardType` 与 README。 ## SaaS 集成:租户 / 部门隔离(阶段二已落地 · 行级隔离) 为把评估能力接入已有 SaaS 平台,工程按 `tenantId`(租户)+ `orgId`(部门)对业务数据做**行级隔离**。阶段一落地请求级上下文;阶段二已完成 DDL 迁移、全链路增删改查谓词注入、缓存分桶、JPA 实体扩展与多组示例数据。 ### 隔离边界与表分类 `tenant_id` / `org_id` 均为 `VARCHAR(100) NOT NULL DEFAULT ''`,空串 `''` 是全局哨兵(不用 NULL——MySQL 唯一键中 NULL 不参与去重,会允许无限重复的全局行)。30 张物理表中,只有 2 张**完全与租户 / 部门无关的基础信息表**保持整表共享: | 模式 | 张数 | 范围 | 语义 | |------|------|------|------| | `SHARED` | 2 | `model_coefficient`、`comprehensive_admin_region` | 平台统一维护的全局系数 / 国标行政区划字典,不加租户列、不加谓词 | | `OVERLAY` | 9 | CONFIG 8 张 + `hazard_scenario` | 三级覆盖链:部门行 > 租户级行 > 全局底座行 | | `STRICT` | 19 | DATA 15 张 + HISTORY 4 张 | 强隔离,必须精确命中 `tenant_id + org_id`,绝不回退全局 | 合计 30 张,其中 28 张带两列。归属由 `com.fysb.risk.tenant.TenantScopeCatalog` 单一真源声明,`TenantSql.predicate(table)` / `predicateArgs(table)` 按模式自动选择参数个数:SHARED 0 个、STRICT 2 个、OVERLAY 3 个(当前作用域 / 租户级 / 全局)。`diff()` 可把分类清单与物理表清单比对;未知表默认按 `STRICT` 处理(宁可查不到,也不能越权读到别的租户数据)。 ### 请求上下文 | 组件 | 职责 | |------|------| | `TenantScope` | 不可变值对象,`cacheKey()` 可直接作为缓存分桶 key;标识统一清洗并截断到 100 字符,与 DDL `VARCHAR(100)` 对齐 | | `TenantContext` | `ThreadLocal` 绑定,取不到时返回全局;`callIn()` / `wrap()` 支持后台任务与线程池传递 | | `TenantContextFilter` | 请求进入时 `set`、执行链路、`finally clear()`,避免 Tomcat 线程复用串租户;静态资源不绑定 | | `TenantProperties` | `risk.tenant.*` 配置,全部带默认值,**无需改动 `application.yml`** | | `TenantWebConfig` | 以 `HIGHEST_PRECEDENCE + 20` 注册过滤器,保证持久化切面与各 Service 读取时上下文已就绪 | | `TenantSql` | 表级 `predicate/predicateArgs/where/insertColumns/insertValues/selectAll/dedupOverlay`;`strict()` 2 参数、`overlay()` 3 参数,全部 `?` 绑定 | | `TenantController` | `/api/tenant/current`、`/api/tenant/scopes`、`/api/tenant/demo-scopes` 只读自省接口,供联调与运维排查 | 取值来源由 `risk.tenant.source` 指定:`HEADER`(默认,只读 `X-Tenant-Id` / `X-Org-Id`)、`PARAM`、`JWT`(解析 Bearer Token 的 claim,**不验签**)、`AUTO`(头 → 参数 → JWT)、`DISABLED`。 ```bash # 集成示例:改用平台自定义头,并锁定为只允许网关注入 java -jar target/dynamic-risk-assessment-agent-1.0.0-exec.jar \ --risk.tenant.source=HEADER \ --risk.tenant.tenant-header=X-SaaS-Tenant \ --risk.tenant.org-header=X-SaaS-Org \ --risk.tenant.allow-override=false ``` 也可用环境变量 `RISK_TENANT_SOURCE` / `RISK_TENANT_TENANT_HEADER` 等覆盖。未携带租户信息时缺省为 `("", "")`,与当前单租户数据完全等价,因此阶段一**不改变任何现有查询结果**。 ### 阶段二:落库、接口改造与示例数据(已实施) - **DDL**:28 张 scoped 表在 `db/init_*.sql` 的 `CREATE TABLE` 内置两列;18 个业务唯一键扩为 `(tenant_id, org_id, 原自然键)`;每张表补 `idx__scope (tenant_id, org_id)`。存量库用 `scripts/TenantScopeMigration.java` 幂等补列、重建唯一键、回填 `NULL → ''`,重复执行零变更。4 个外键仍指向 `watershed_unit(unit_id)` 单列主键,管理端单列主键 CRUD 契约保持不变;不同租户复用相同业务编码时需改用带前缀的编码(示例数据用 `SCQC_` / `GDSZ_`)。 - **增删改查**:`AdminDataService` 通用 CRUD、`ScenarioAdminService`、`ScenarioService`、五灾种 / 综合配置服务、7 个 Repository、JPA `RiskConfig` / `FlashFloodCriticalRainfall` 与 `RiskConfigController` 均按表模式注入谓词。写入时两列**只取自 `TenantContext`**,请求体伪造的 `tenant_id` / `org_id` 一律忽略;更新 / 删除使用 `strict()`,无法越权改全局底座行或他租户行。 - **持久化**:`ResultPersistenceService`、`ComprehensiveResultStore` 的 4 处 `INSERT ... ON DUPLICATE KEY UPDATE`、批次清理 SQL 与内存镜像都带作用域;批次 ID 生成与 30s 节流窗口按租户分桶。 - **缓存分桶**:`RiskConfigService`、`ScenarioService`、`ComprehensiveRepositoryImpl`、`ComprehensiveAssessmentService`、`ComprehensiveResultStore`、`ResultPersistenceService` 的进程内缓存按 `TenantContext.cacheKey()` 分桶,`invalidate()` 只失效当前桶。 #### 示例作用域组合 `db/init_tenant_scope_demo.sql` 与 `GET /api/tenant/demo-scopes` 给出 6 组组合: | tenant_id | org_id | 内容 | |---|---|---| | `''` | `''` | 平台全局底座行(内置配置 / 场景 / 台账) | | `TENANT_SC` | `''` | 四川省平台租户级配置 / 场景覆盖 | | `TENANT_SC` | `ORG_QC` | 青川县应急局:完整台账 + 部门级覆盖 | | `TENANT_SC` | `ORG_JG` | 剑阁县应急局:仅配置 / 场景覆盖,可观察租户级继承 | | `TENANT_GD` | `''` | 广东省平台租户级覆盖 | | `TENANT_GD` | `ORG_SZ` | 深圳市应急局:完整台账 + 部门级覆盖 | 联调示例(三级覆盖链实际生效值): ```bash curl --noproxy '*' -H 'X-Tenant-Id: TENANT_SC' -H 'X-Org-Id: ORG_JG' \ http://127.0.0.1:8649/api/risk/config/list # beta 继承租户级 0.58、api_k 部门覆盖 0.80 curl --noproxy '*' -H 'X-Tenant-Id: TENANT_SC' -H 'X-Org-Id: ORG_QC' \ http://127.0.0.1:8649/api/admin/tables/watershed_unit/rows # 只见 SCQC_ 台账 ``` > 两个「完整台账」部门同时克隆了整套 `sys_risk_config`,因此部门行会覆盖租户级 `beta`;要演示部门继承租户级覆盖请用 `TENANT_SC/ORG_JG`。 #### 回归入口 ```bash mvn -o test # 单元测试 python scripts/verify_tenant_scope_runtime.py # 运行时隔离回归(需启动 8649) python target/dbinit/run_all_regression.py # 全量静态 / 前端回归 ``` > **安全提示**:工程当前无鉴权,默认允许请求头直接指定租户,仅用于联调。生产环境必须由 SaaS 网关校验并覆盖这两个头,或设置 `risk.tenant.allow-override=false` 锁定作用域;JWT 模式只提取 claim、不验签,签名校验由网关负责。`application.yml` 中的明文数据库口令也需脱敏轮换。 ## 本地打包发布(jar 被占用) ### 当前产物布局(`classifier=exec`) `pom.xml` 给 `spring-boot-maven-plugin` 配了 `exec`,因此打包后同时产出: | 文件 | 说明 | |------|------| | `target/dynamic-risk-assessment-agent-1.0.0-exec.jar` | **约 40 MB 可执行 fat jar**,启动时用这个 | | `target/dynamic-risk-assessment-agent-1.0.0.jar` | 约 1.3 MB 普通薄 jar,仅作依赖产物,**不能直接 `java -jar`** | 该配置同时规避了 Windows 上的文件锁问题:若去掉 classifier,`repackage` 会把 `xxx.jar` 重命名为 `xxx.jar.original` 再写回,运行中的 JVM 持有句柄时会报 `Unable to rename ...jar.original`,并把 `xxx.jar` 覆盖成不可启动的薄 jar。`scripts/build_release.py` 会从 `pom.xml` 自动识别 classifier,两种布局都能正确校验产物。 ### 一键处理(推荐) ```bash python scripts/build_release.py --restart ``` 脚本会依次:按 8649 端口找到监听进程并校验是 `java.exe`(**不会误杀其它项目**)→ 停止并等待端口释放 → 清理残留 `.jar.original` → 离线 `mvn package`(**绝不加 clean**)→ 按 classifier 定位并校验可执行 fat jar → 后台重新拉起服务。 | 参数 | 作用 | |------|------| | `--dry-run` | 只诊断占用进程与 Maven 路径,不做任何改动 | | `--no-stop` | 确认无占用时跳过停进程 | | `--online` | 允许 Maven 联网解析依赖(默认 `-o` 离线) | | `--tests` | 执行单元测试(默认 `-DskipTests`) | | `--port 8649` | 指定服务端口 | | `--mvn "D:\...\bin\mvn.cmd"` | 显式指定 Maven(找不到时) | 不带 `--restart` 时只打包不启动,脚本会打印下一步的手动启动命令。 ### 手动处理 ```bash # 1) 停掉正在运行的本系统服务(Git Bash 下) ps -ef | grep dynamic-risk-assessment-agent-1.0.0-exec.jar kill # Windows 原生命令行也可用:taskkill /PID /F /T # 2) 重新打包:绝不加 clean mvn -o -q -DskipTests package # 3) 启动(SERVER__PORT 宿主变量会覆盖 server.port,必须 unset) env -u SERVER__PORT java -jar target/dynamic-risk-assessment-agent-1.0.0-exec.jar --server.port=8649 ``` > **铁律:不要用 `mvn clean package` 绕过**。`target/dbinit/` 存放着全部端到端回归脚本(Python 静态校验 + Node DOM 运行时验证)、SQL 执行器与驱动 jar,`clean` 会整体删除该目录;项目约定一律使用**不带 clean** 的 `mvn -o -q -DskipTests package`。 ### 产物自检 发布前确认打出来的是可执行的 fat jar: ```bash python -c "import zipfile,os; p='target/dynamic-risk-assessment-agent-1.0.0-exec.jar'; \ z=zipfile.ZipFile(p); n=set(z.namelist()); \ print(os.path.getsize(p)//1048576, 'MB', \ 'BOOT-INF/classes/application.yml' in n, \ any(x.endswith('JarLauncher.class') for x in n))" ``` 预期约 **40 MB**、两个布尔值均为 `True`。若只有 1~2 MB,说明 `repackage` 没跑完,按上面流程重打。`scripts/build_release.py` 已内置该项校验,校验不通过会以非零码退出。 ## 技术方案映射 | 技术方案章节 | 代码实现 | |-------------|----------| | 3.1 统一评估内核 | `RiskComputeEngine` + `RiskLevel` | | 3.2 灾种插件接口 | `IHazardPlugin` 接口 | | 4.1 计算单元:小流域 | `WatershedUnit` 模型 | | 4.3 致灾因子派生 | `FlashFloodPlugin.deriveFactors()` | | 4.4 动态临界雨量法 | `FlashFloodPlugin.computeHazard()` | | 4.5 E/V/C 静态要素 | `ExposureData`/`VulnerabilityData`/`CapacityData` | | 4.6 风险合成与分级 | `RiskComputeEngine.compute()` | | 综合方案 5 第一级聚合 R(a,h) | `ComprehensiveRiskModel.aggregate()` | | 综合方案 6~8 CRI 合成 / 权重 / 并发 | `ComprehensiveRiskModel.synthesize()` + `comprehensive_region_hazard_weight` | | 综合方案 9 多时效对齐 CRI(t) | `ComprehensiveRiskModel.alignTimeline()`(4h × 25 桶) | | 综合方案 10 分级排序与主导灾种 | `ComprehensiveRiskModel.assignRanks()` / `ComprehensiveAssessmentService.buildSummary()` | | 综合方案 11 输出与产品 | `ComprehensiveAssessmentResponse` / `comprehensive-risk.html` | ## 后续规划 - [x] 模型阈值与参数配置持久化(MySQL + JPA) - [x] 业务数据存储表建模与初始化(流域/村落/参数/暴露度/防灾能力/评估结果) - [ ] 接入真实气象数据源 - [ ] 接入 PostGIS 空间数据库 - [ ] 添加 LLM 研判层(RAG + 预警文稿生成) - [ ] 实现事件驱动调度(Kafka) - [x] 扩展地质灾害、森林火灾、流域洪涝、城市内涝插件(含前端模块、数据表与共享管理端接入) - [x] 逐时间节点风险 R(t) 计算、响应直出、批次 / 明细 / 主表快照落库与历史回溯接口(五灾种全覆盖) - [x] 行政区域综合风险评估模块(两级聚合 CRI、8 个联动场景、三级下钻一张图、态势简报与跨轮次历史) - [x] 预设场景分灾种入库与后台自定义(`hazard_scenario` 47 条预设 / 6 灾种、`admin-scenarios.html` 独立页面、离线兜底) - [x] 全站双主题皮肤(默认浅色、顶栏切换、偏好持久化、ECharts / 内联样式 / 矢量底图联动) - [x] SaaS 集成阶段一:租户 / 部门请求上下文、表隔离归属清单、统一 SQL 谓词构造器与自省接口 - [ ] SaaS 集成阶段二:DDL 迁移(30 表加列 + 复合唯一键)、查询谓词注入、四组缓存按租户分桶 - [ ] 添加阈值率定工具(历史灾例回算) - [ ] 实现风险产品生成(图、简报) ## License MIT