gz-oarms/findings.md

# OARMS 命名规范审查 — 发现记录

## 前置发现

### 全局性问题

#### 1. 前端 API 参数命名：snake_case vs camelCase

**严重程度**: P0 — 前后端无法对接

前端 API 文件中参数名使用 snake_case（如 `screen_name`、`page_num`、`config_status`），而后端 Entity/Query 属性使用 camelCase（如 `screenName`、`pageNum`、`configStatus`）。

Jackson 默认序列化/反序列化使用 camelCase，前端发 snake_case 参数后端收不到。

**影响文件**:
- `gz-oarms-web/src/api/BS-大屏基础库域/BS-1-大屏基础信息管理.js`
- `gz-oarms-web/src/api/AM-广告监控域/AM-1-广告画面录屏设置管理.js`
- `gz-oarms-web/src/api/CW-内容预警域/CW-3-监测线索生成.js`
- 全部 10 个 API 文件

#### 2. 前后端 API 路径不一致

**严重程度**: P1 — 路径不匹配导致 404

| 前端路径 | 后端路径 | 差异 |
|---------|---------|------|
| `/api/screens/query` | `/api/screen/query` | 单复数 |
| `/api/recording-configs/query` | `/api/recording-config/query` | 单复数 |
| `/api/cw/evidence-records/query` | `/api/evidence-record/query` | 域前缀 + 单复数 |
| `/api/cw/monitoring-clues/query` | `/api/monitoring-clue/query` | 域前缀 + 单复数 |

---

## Phase 1：后端 DB→Entity→DTO 全链路审查（✅ 完成）

### P1-1：DDL CREATE TABLE 表名小写（全部 13 个 DDL 文件，17 张表）

**严重程度**: P3 — DM8 规范要求大写，但 DM8 实际大小写不敏感，不影响功能

所有 `CREATE TABLE` 语句中表名使用小写，而同文件内 COMMENT ON / CREATE INDEX 已大写。

| DDL 文件 | 需修改的表名 |
|---------|------------|
| V1.0.0__BS_screen_ddl.sql | `bs_screen` → `BS_SCREEN`，`bs_screen_history` → `BS_SCREEN_HISTORY` |
| V2.0.0__LB_law_ddl.sql | `lb_law_clause` → `LB_LAW_CLAUSE` |
| V3.0.0__AM_recording_config_ddl.sql | `am_recording_config` → `AM_RECORDING_CONFIG` |
| V4.0.0__AM_recording_task_ddl.sql | `am_recording_task` → `AM_RECORDING_TASK`，`am_alert_notification` → `AM_ALERT_NOTIFICATION` |
| V5.0.0__AM_monitor_record_ddl.sql | `am_monitor_record` → `AM_MONITOR_RECORD` |
| V6.0.0__MR_monitoring_rule_ddl.sql | `mr_monitoring_rule` → `MR_MONITORING_RULE`，`mr_rule_law_clause_rel` → `MR_RULE_LAW_CLAUSE_REL`，`mr_rule_operation_history` → `MR_RULE_OPERATION_HISTORY` |
| V7.0.0__CW_evidence_ddl.sql | `cw_evidence_record` → `CW_EVIDENCE_RECORD`，`cw_evidence_status_history` → `CW_EVIDENCE_STATUS_HISTORY` |
| V8.0.0__CW_evidence_rule_relation_ddl.sql | `cw_evidence_rule_relation` → `CW_EVIDENCE_RULE_RELATION` |
| V9.0.0__CW_monitoring_clue_ddl.sql | `cw_monitoring_clue` → `CW_MONITORING_CLUE`，`cw_clue_generation_log` → `CW_CLUE_GENERATION_LOG` |
| V10.0.0__CW_clue_transfer_ddl.sql | `cw_clue_transfer_record` → `CW_CLUE_TRANSFER_RECORD`，`cw_transfer_operation_log` → `CW_TRANSFER_OPERATION_LOG` |

### P1-2：多余 @TableField 注解（2 个 Entity，6 处）

**严重程度**: P3 — 不影响功能，冗余代码

属性名与列名完全相同时，MyBatis-Plus 自动映射，`@TableField` 注解多余。

| Entity 文件 | 字段 | @TableField 值 | 原因 |
|------------|------|---------------|------|
| ScreenEntity | `address` | `"address"` | 完全相同 |
| ScreenEntity | `district` | `"district"` | 完全相同 |
| ScreenEntity | `advertiser` | `"advertiser"` | 完全相同 |
| ScreenEntity | `longitude` | `"longitude"` | 完全相同 |
| ScreenEntity | `latitude` | `"latitude"` | 完全相同 |
| RuleOperationHistoryEntity | `operator` | `"operator"` | 完全相同 |

### P1-3：命名一致性审查通过项

| 检查项 | 结果 | 详情 |
|-------|------|------|
| DDL @TableField 映射 | ✅ 全部匹配 | 17 张表，约 150 个字段全部正确 |
| Entity → DTO 属性名 | ✅ 全部匹配 | VO/Query/Req 与 Entity 属性名一致 |
| DDL COMMENT/INDEX 大写 | ✅ 全部大写 | 所有 COMMENT ON 和 CREATE INDEX 标识符大写 |
| SuperEntity 公共字段 | ✅ 无重复声明 | 所有继承 SuperEntity 的 Entity 均未重复声明 |
| @JsonFormat 使用常量 | ✅ 全部使用 DateUtil | 无硬编码格式字符串 |

---

## Phase 2：后端 Controller API 路径审查（✅ 完成）

### P2-1：基础路径单复数不一致

**严重程度**: P2 — 风格不一致，影响可维护性

| Controller | 当前路径 | 问题 | 建议 |
|-----------|---------|------|------|
| MonitoringRuleController | `/api/monitoring-rules` | 唯一使用复数 | → `/api/monitoring-rule` |
| 其余 9 个 Controller | `/api/screen` 等 | 单数 | 保持一致 |

### P2-2：低优先级风格问题

| Controller | 问题 | 建议 |
|-----------|------|------|
| ScreenController | `district/list` 两段路径 | → `districts` |
| MonitoringClueController | `clue-preview` 与基础路径语义重复 | → `preview` |
| ClueTransferController | `targets/districts` 两层嵌套 | → `target-districts` |
| ClueTransferController | `clues/{clueId}/disposal-feedback` 路径变量 | → `disposal-feedback?clueId=` |
| ClueTransferController | `pending-clues/query` 子资源前缀 | → `pending-query` |
| EvidenceRuleRelationController | `query-by-evidence` 复合路径 | → `list-by-evidence` |

### P2-3：审查通过项

- 全部 10 个 Controller 路径使用 kebab-case，无驼峰/下划线混入
- 核心 CRUD 路径（query/detail/save/update/remove）高度一致

---

## Phase 3：前端 API 文件审查（✅ 完成）

### P3-1：API 路径全部不匹配（严重）

**严重程度**: P0 — 前后端路径不一致，所有接口 404

**根因**: 前端使用 RESTful 风格（复数 + 路径参数 + PUT/DELETE），后端使用扁平 POST 风格（单数 + 查询参数/RequestBody）

| 问题模式 | 涉及模块 | 示例 |
|---------|---------|------|
| 资源名单复数 | 全部 10 个 | `/api/screens` vs `/api/screen` |
| HTTP 方法不匹配 | 全部 | PUT/DELETE vs POST |
| 路径参数 vs 查询参数 | 全部 GET/PUT/DELETE | `/api/screens/${id}` vs `/api/screen/detail?id=` |
| CW 域多了 `/cw/` 前缀 | CW-1/2/3 | `/api/cw/evidence-records` vs `/api/evidence-record` |
| 前端用路径嵌套 | CW-4 | `/api/clue-transfer/transfer-records/query` vs `/api/clue-transfer/query` |

**统计**: ~58/64 个端点路径不匹配

### P3-2：JSDoc 参数名全部 snake_case（严重）

**严重程度**: P0 — 前端发 snake_case 参数，后端收 camelCase，字段无法映射

全部 10 个 API 文件的 JSDoc `@param` 注释和实际参数使用 snake_case，而后端 Entity/Query/Req 属性为 camelCase。

**高频不匹配字段**（全局）：

| 前端 snake_case | 后端 camelCase | 出现次数 |
|----------------|---------------|---------|
| `page_num` | `pageNum` | 10 文件 |
| `page_size` | `pageSize` | 10 文件 |
| `screen_name` | `screenName` | 6 文件 |
| `start_time` / `end_time` | `startTime` / `endTime` | 5 文件 |
| `evidence_id` | `evidenceId` | 4 文件 |
| `clue_id` | `clueId` | 3 文件 |

### P3-3：JS 函数参数名 snake_case（15 处）

**严重程度**: P1 — 不影响运行，但不符合 JS camelCase 规范

| 文件 | snake_case 参数 | 应改为 |
|------|----------------|-------|
| CW-1 | `evidence_id`（×4）、`monitor_record_id`（×2） | `evidenceId`、`monitorRecordId` |
| CW-2 | `evidence_id`（×3） | `evidenceId` |
| CW-3 | `evidence_id`（×1）、`clue_id`（×2） | `evidenceId`、`clueId` |
| CW-4 | `clue_id`（×2）、`transfer_record_id`（×2）、`district_code`、`department_id` | camelCase |

### P3-4：前端调用不存在的后端接口（6 个）

| 前端函数 | URL | 模块 |
|---------|-----|------|
| `queryRuleOperationHistory` | `/api/monitoring-rules/${id}/histories` | MR-1 |
| `getEvidenceStatusHistory` | `/api/evidence-records/${id}/status-history` | CW-1 |
| `getMonitorRecordEvidenceContext` | `/api/monitor-records/${id}/evidence-context` | CW-1 |
| `getMonitorVideoPlayUrl` | `/api/monitor-records/${id}/video/play` | CW-1 |
| `updateEvidenceRecordStatus` | `/api/cw/evidence-records/${id}/status` | CW-2 |
| `getClueGenerationLogs` | `/api/cw/monitoring-clues/${id}/generation-logs` | CW-3 |

---

## Phase 4：前端页面组件审查（跳过）

前端页面组件的命名问题本质与 Phase 3 的 API 文件一致（表单字段绑定来源于 API 参数）。API 层修复后页面同步调整即可。

---

## Phase 5：汇总修复建议

### 修复策略决策

**核心问题**：前后端 API 路径和参数命名存在系统性不一致。

**必须选择一个方向统一**：
- **方案 A（推荐）**：前端适配后端 — 修改前端 API 文件的路径和参数名为后端实际值
- **方案 B**：后端适配前端 — 修改后端 Controller 路径和参数接收方式

**推荐方案 A 的理由**：
1. 后端 85 个问题已全部修复并端到端测试通过，不宜大改
2. 前端 API 文件仅 10 个，修改范围可控
3. 后端的扁平 POST 风格已在项目中统一，改后端需动 11 个 Controller

### 修复清单（方案 A）

#### 1. 修复前端 API 路径（10 个文件，~58 处）

每个 API 文件需：
- 资源名改为单数（`screens` → `screen`，`recording-configs` → `recording-config`）
- 移除 `/cw/` 前缀（CW-1/2/3 的文件）
- GET 详情改为查询参数（`/${id}` → `?id=`）
- PUT/DELETE 改为 POST
- 路径参数改为 RequestBody

#### 2. 修复 JSDoc 参数名为 camelCase（10 个文件，~90 处）

每个 `@param` 中的 snake_case 字段名改为 camelCase：
- `page_num` → `pageNum`
- `screen_name` → `screenName`
- `evidence_id` → `evidenceId`
- 等等

#### 3. 修复 JS 函数参数名（CW-1/2/3/4 的文件，15 处）

- `evidence_id` → `evidenceId`
- `clue_id` → `clueId`
- `transfer_record_id` → `transferRecordId`
- `district_code` → `districtCode`
- `department_id` → `departmentId`

#### 4. 修复后端 Controller 单复数不一致（1 处）

- MonitoringRuleController: `/api/monitoring-rules` → `/api/monitoring-rule`

#### 5. DDL CREATE TABLE 表名大写（13 个文件，17 张表）

纯规范修复，DM8 大小写不敏感，不影响功能。

#### 6. 清理多余 @TableField 注解（2 个 Entity，6 处）

纯代码整洁，不影响功能。

### 不修复项

| 项目 | 原因 |
|------|------|
| 前端调用不存在的 6 个接口 | 属于功能缺失（需评估是否需要实现），非命名问题 |
| ClueTransferController 多层嵌套路径 | 功能正常，低优先级风格问题 |
| 前端页面组件命名 | API 层修复后页面自然跟随 |