zhzhy
/
gz-oarms
generated from youfool-project/youfool-prj-springboot3-template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
gz-oarms/findings.md

10 KiB
Raw Blame History

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 层修复后页面自然跟随