9.2 KiB
9.2 KiB
监管端驾驶舱（/container/driver → Cockpit）接口设计
适用范围：前端「监管端」大屏（
src/pages/Container/Supervision/Cockpit）。 设计原则：高内聚（一业务域一接口）、松耦合（前端只消费扁平 CO）、高性能（单接口聚合 + 短 TTL 缓存）、稳定性（面板级接口独立、可降级）、业务边界清晰。 实现约束：全部为新增接口，落在新的RegulatorCockpitController，不改/不删任何既有功能；聚合逻辑在RegulatorCockpitExecutor内基于现有 Gateway 完成（监管端上下文 orgId 为空，Gatewaypage不强制机构过滤，返回全市数据）。
一、总体说明
大屏原 RegulatorRiskCenterController 为内存 Mock；本设计基于现有数据源给出可用的真实接口，剔除无数据源的板块（风险预警研判、隐患整改率、合格率）。
新增 7 个聚合接口（基址 /safetyEval/regulator/cockpit）：
| # | 路径 | 对应板块 | 主数据源 |
|---|---|---|---|
| 1 | GET /qualification-overview |
资质全生命周期管理 | org_info、org_personnel、IndustryEnum |
| 2 | GET /kpi |
核心KPI（仅开展评价率） | eval_project、eval_risk_analysis |
| 3 | GET /region-distribution |
区域地图分布 | eval_project、org_info |
| 4 | GET /process-overview |
执业全过程管控 + 项目流程 | 8 个节点（复用 EvalProjectNodeOverviewAssembler）+ eval_project |
| 5 | GET /eval-type-trend |
评价类型趋势 | eval_project、insp_notice |
| 6 | GET /review-summary |
复盘评估改进提效 | insp_notice、eval_project |
| 7 | GET /project-monitor |
项目实时监控 | eval_project、eval_project_process_waring、复用 selectRegulatorSurveyStat |
二、各接口详细设计
1. 资质全生命周期管理 qualification-overview
- 入参：
year（可选，默认当前年）。 - 出参：
lifecycleStats{newFilingOrgCount, currentFilingOrgCount, logoutOrgCount, totalFilingOrgCount, exitedEvaluatorCount, currentEvaluatorCount}；progress{filingCompleteRate, bizActiveRate, newGrowthRate}；industryList[{industryCode, industryName, orgCount, typeCount}]。 - 边界：仅机构/人员/资质维度；不含项目与风险。
- 数据源：
org_info（filing_record_status_code、create_time、district_code、safety_industry_category_code）、org_personnel（person_type_code='2' 专职评价师、employment_status_code1在职/2离职）、eval_project（计算开展业务率：有在监项目的机构数 ÷ 当前备案机构数）、IndustryEnum（行业字典）。 - 业务逻辑：
currentFilingOrgCount=filing_record_status_code=1（已备案）机构数；newFilingOrgCount= 同上且create_time落在year；totalFilingOrgCount= 全部机构数；logoutOrgCount= 当前字典无「注销」状态，暂置 0（待补来源）。- 评价师按
person_type_code='2'且employment_status_code区分在职/离职计数。 industryList按safety_industry_category_code分组（支持单值或逗号分隔多值）。
- 已知缺口：
logoutOrgCount无「注销」状态，需后续补数据源。
2. 核心KPI kpi
- 入参：
cycle（year|quarter|month，默认 year）、year（可选）。 - 出参：
items[{code, name, value, yoy}]。 - 边界：仅提供「备案项目开展评价率」（现有数据可支撑）；不提供「企业评价项目合格率」（无合格状态字段）、「隐患整改率」（无隐患表）。
- 数据源：
eval_project（is_statutory=1）、eval_risk_analysis（风险分析已建立=已开展评价）。 - 业务逻辑：分母=法定项目数；分子=存在
eval_risk_analysis的项目数；value=率值；yoy=当前周期率−上一周期率（百分点）。
3. 区域地图分布 region-distribution
- 入参：无。
- 出参：
list[{districtCode, districtName, evalProjectCount, filingOrgCount}]；summary{totalEvalProject, totalFilingOrg}。 - 边界：仅「评价项目数」「备案机构数」两维度；隐患/整改率无数据源，前端可用项目数替代。
- 数据源：
eval_project.district_code（法定项目按区县计数）、org_info.district_code（已备案机构按区县计数）。 - 业务逻辑：两路按
district_code分组后按区县编码对齐，缺侧补 0。
4. 执业全过程管控 + 项目流程 process-overview
- 入参：无。
- 出参：
nodes[{nodeCode, nodeName, totalCount, pendingCount}]。 - 边界：
totalCount=到达该节点项目数（状态≠未开始）；pendingCount=未开始（待办）项目数。覆盖 8 个真实节点（风险分析/合同签订/成立项目组/现场勘查/过程管控/报告草稿/内审/技审）；大屏额外的「初勘/从业告知/编制检查表/制定工作计划/归档」无独立实体，由前端并入相邻节点或留空。 - 数据源：复用
EvalProjectNodeOverviewAssembler.buildForRegulator(projectId)逐项目取节点状态，再全局累加。 - 业务逻辑：遍历法定项目，对每个节点累计 reached/pending（statusName≠「未开始」即 reached，否则 pending）。
5. 评价类型趋势 eval-type-trend
- 入参：
period（year|quarter|month，必填）、year（可选）。 - 出参：
buckets[时间桶]；series[{evalTypeCode, evalTypeName, projectCounts[], inspCounts[]}]。 - 边界：
projectCounts来自eval_project按eval_type_code+时间桶；inspCounts来自insp_notice经project_id关联eval_project的eval_type_code+时间桶。 - 数据源：
eval_project.eval_type_code/create_time、insp_notice.create_time/project_id。 - 业务逻辑：先按项目建
projectId→evalTypeCode映射；项目按创建时间入桶，监督检查按创建时间入桶（仅统计能关联到项目的检查）。
6. 复盘评估改进提效 review-summary
- 入参：
year（可选，默认当前年）。 - 出参：
stats{inspCount, onsiteCheckCount(项目过程检查), qualKeepCount(资质保持检查), specialCount(专项检查), checkedOrgCount, foundProblemCount(resultCode=2/3)}；pie[{OVERDUE 超期未完成数, PUNISH 监管处罚数}]。 - 边界：基于
insp_notice真实字段（insp_type_code= PROJECT_PROCESS/QUAL_KEEP/SPECIAL；result_code1未发现问题/2责令整改/3转入风险预警）。原大屏 pie 中的「现场确认风险隐患数/复查评估报告数/项目主要负责人变更数」无现成数据源，本次仅输出可用的 OVERDUE、PUNISH 两项。 - 数据源：
insp_notice、eval_project（plan_end_date逾期、未归档）。 - 业务逻辑：检查类按
insp_type_code与result_code分组；OVERDUE=法定未归档且plan_end_date早于今日；PUNISH=result_code=3检查数。
7. 项目实时监控 project-monitor
- 入参：
month（可选，yyyy-MM，默认当前月）。 - 出参：
monitor{activeProjectCount, normalExecCount, warningCount, monthPlanFinishCount}；survey{noticeArchived, noticeAbnormal, clockInNormal, clockInAbnormal}。 - 边界：
activeProjectCount=法定项目数；normalExecCount=clock_in_status='NORMAL'；warningCount=存在过程预警的项目数（真实计算，替代原硬编码 0）；monthPlanFinishCount=plan_end_date落在month的项目数。survey四项复用既有聚合 SQLEvalProjectMapper.selectRegulatorSurveyStat()（告知书/打卡数据源正确性）；监控/预警/计划完成数为本次新实现。
- 数据源：
eval_project、eval_project_process_waring、eval_survey_attach（经既有 Mapper）。 - 业务逻辑：遍历法定项目计数；
warningCount调EvalProjectProcessWaringGateway.checkProjectHasWaring(projectId)。
三、实现要点与性能建议
- 聚合方式：监管端无机构上下文，
Gateway.page()不强制 org 过滤；Executor 以较大pageSize拉取全量后在内存聚合，避免 N+1 与脆弱手写 SQL。 - 缓存：大屏建议对 7 个接口加 30~60s 短 TTL 缓存，降低 DB 压力。
- 索引建议：
eval_project(is_statutory, district_code, eval_type_code, create_time, plan_end_date, clock_in_status)、insp_notice(insp_type_code, result_code, create_time, project_id, org_id)、org_info(filing_record_status_code, district_code)。 - 故障隔离：7 个接口相互独立，单接口异常不影响其余面板。
四、已剔除（无现有数据源）
risk-overview（资质备案类失信统计、违法触发饼图）——RegulatorRiskCenterController为内存 Mock，缺信/违法实体。- KPI「企业评价项目合格率」「隐患整改率」——缺合格状态字段与隐患表。
五、新增文件清单
safety-eval-adapter/.../web/regulator/RegulatorCockpitController.java（新 Controller）safety-eval-client/.../api/regulator/RegulatorCockpitApi.java（新 Api）safety-eval-client/.../co/regulator/cockpit/*.java（7 个 CO）safety-eval-app/.../executor/regulator/RegulatorCockpitExecutor.java（新 Executor，聚合逻辑）