# 监管端驾驶舱（/container/driver → Cockpit）接口设计

> 适用范围：前端「监管端」大屏（`src/pages/Container/Supervision/Cockpit`）。
> 设计原则：高内聚（一业务域一接口）、松耦合（前端只消费扁平 CO）、高性能（单接口聚合 + 短 TTL 缓存）、稳定性（面板级接口独立、可降级）、业务边界清晰。
> 实现约束：全部为**新增接口**，落在新的 `RegulatorCockpitController`，不改/不删任何既有功能；聚合逻辑在 `RegulatorCockpitExecutor` 内基于现有 Gateway 完成（监管端上下文 orgId 为空，Gateway `page` 不强制机构过滤，返回全市数据）。

---

## 一、总体说明

大屏原 `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_code` 1在职/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_code` 1未发现问题/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` 四项复用既有聚合 SQL `EvalProjectMapper.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，聚合逻辑）