gz-oarms/findings.md

OARMS 研究与发现记录

代码结构发现

模块对应关系（计划 vs 实际）

计划阶段	计划模块	SQL DDL	SQL 初始数据	Java 代码层	状态
Phase 1	BS-1 大屏基础信息管理	✅ V1.0.0__BS_screen_ddl.sql	✅ V1.0.0__BS_screen_init_data.sql	✅ screen (Entity/Query/Req/VO/Mapper/Service/Controller)	✅ 完成
Phase 2	LB-1 法律法规管理	✅ V2.0.0__LB_law_ddl.sql	✅ V2.0.0__LB_law_init_data.sql	✅ law (Entity/Query/Req/Mapper/Service/Controller)	✅ 完成
Phase 3	MR-1 监测规则管理	✅ V6.0.0__MR_monitoring_rule_ddl.sql	✅ V6.0.0__MR_monitoring_rule_init_data.sql	✅ rule (Entity×3/Query/Req/VO/Mapper×3/Service/Controller)	✅ 完成
Phase 4	AM-1 录屏设置管理	✅ V3.0.0__AM_recording_config_ddl.sql	❌ 无初始数据	✅ monitor.config (Entity/Query/Req/Mapper/Service/Controller)	✅ 完成
Phase 5	AM-2 随机录屏	✅ V4.0.0__AM_recording_task_ddl.sql	❌ 无初始数据	✅ monitor.task (Entity×2/Query/Mapper×2/Service/Controller)	✅ 完成
Phase 6	AM-3 广告画面监控	✅ V5.0.0__AM_monitor_record_ddl.sql	❌ 无初始数据	✅ monitor.record (Entity/Query/Req/Mapper/Service/Controller)	✅ 完成
Phase 7	CW-1 固化取证	✅ V7.0.0__CW_evidence_ddl.sql	❌ 无初始数据	✅ evidence.record (Entity×2/Query/Req/VO/Mapper×2/Service/Controller)	✅ 完成
Phase 8	CW-2 规则关联	✅ V8.0.0__CW_evidence_rule_relation_ddl.sql	❌ 无初始数据	✅ evidence.relation (Entity/Query/Req/Mapper/Service/Controller)	✅ 完成
Phase 9	CW-3 线索生成	✅ V9.0.0__CW_monitoring_clue_ddl.sql	❌ 无初始数据	✅ evidence.clue (Entity×2/Query/VO/Mapper×2/Service/Controller)	✅ 完成
Phase 10	CW-4 线索转办	✅ V10.0.0__CW_clue_transfer_ddl.sql	❌ 无初始数据	✅ evidence.transfer (Entity×2/Query/Req/VO/Mapper×2/Service/Controller)	✅ 完成

关键发现

1. SQL 版本号与计划阶段不一致: SQL 文件版本号 (V1~V10) 与计划阶段 (Phase 1~10) 顺序不同。MR-1 监测规则在计划中是 Phase 3，但 SQL 编号为 V6。这不影响功能，但说明 SQL 文件是按模块类别分组而非按依赖顺序编号。
2. 无 Mapper XML 文件: 所有模块使用 MyBatis-Plus 注解方式，没有 XML mapper 文件，这是正常的。
3. 初始数据: 仅 BS-1、LB-1、MR-1 有初始数据 SQL，其余模块无需预置数据（合理）。
4. 编译状态: 代码已通过 git commit c06a4e5 提交，commit 信息为 "feat: OARMS 全模块后端代码 + DM8 数据库适配"。

技术栈确认

• 框架: Spring Boot + MyBatis-Plus
• 数据库: DM8（达梦数据库），版本 --03134283914-20220901-168571-20009
• 权限: Sa-Token（StpInterfaceImpl 存在）
• 项目结构: modules/{模块}/{子模块}/{layer}

数据源架构决策（2026-05-18）

项目配置了两个数据源，共用同一 DM8 实例 172.22.80.70:15236：

数据源名	Schema	用途	决策
master	OARMS	业务数据（全部 17 张业务表）	保留
youfool	YOUFOOL	框架 restLog（接口访问日志），RestLogServiceImpl 硬编码 @DS("youfool")	保留

决策: 保持现状，不合并。框架代码不可修改，youfool 数据源是框架层强制依赖。

PRD vs 后端代码覆盖分析（2026-05-18）

比对方法

读取每个模块的 S4-API设计.md，逐条对照后端 Controller 中实际定义的接口。

整体结论

• 10 个模块全部有基础 CRUD 后端代码（Entity/Mapper/Service/Controller）
• 路径命名风格不一致：后端统一用单数名词（/api/screen），PRD 用复数（/api/screens）
• HTTP 方法不一致：后端几乎全用 POST，PRD 规范使用 RESTful 风格（PUT/DELETE）
• 高级功能接口大量缺失

逐模块覆盖详情

BS-1 大屏基础信息管理

PRD 接口	功能	后端状态
POST /api/screens/query	列表查询	✅
POST /api/screens	新增	✅ (路径 /api/screen/save)
PUT /api/screens/{id}	编辑	✅ (路径 /api/screen/update)
GET /api/screens/{id}	详情	✅ (路径 /api/screen/detail)
DELETE /api/screens/{id}	删除	✅ (路径 /api/screen/remove)
PUT /api/screens/{id}/status	状态变更	❌ 未实现
GET /api/screens/export	导出	❌ 未实现
POST /api/screens/import	批量导入	❌ 未实现
GET /api/screens/import-template	下载导入模板	❌ 未实现
GET /api/screens/{id}/histories	历史版本列表	❌ 未实现
GET /api/screens/check-code	编码唯一校验	❌ 未实现
GET /api/screens/check-address	地址唯一校验	❌ 未实现

LB-1 法律法规管理

PRD 接口	功能	后端状态
POST /api/law-clauses/query	列表查询	✅
POST /api/law-clauses	新增	✅ (路径 /api/law-clause/save)
PUT /api/law-clauses/{id}	编辑	✅ (路径 /api/law-clause/update)
GET /api/law-clauses/{id}	详情	✅ (路径 /api/law-clause/detail)
DELETE /api/law-clauses/{id}	删除	✅ (路径 /api/law-clause/remove)
PUT /api/law-clauses/{id}/repeal	废止条款	❌ 未实现
GET /api/law-clauses/check-clause-number	条款号唯一校验	❌ 未实现
GET /api/law-clauses/effective	已生效条款列表	❌ 未实现

MR-1 监测规则管理

PRD 接口	功能	后端状态
POST /api/monitoring-rules/query	列表查询	✅
POST /api/monitoring-rules	新增	✅
PUT /api/monitoring-rules/{id}	编辑	✅ (POST /update)
GET /api/monitoring-rules/{id}	详情	✅ (GET /detail)
DELETE /api/monitoring-rules/{id}	删除	✅ (POST /remove)
PUT /api/monitoring-rules/{id}/toggle-status	切换启用状态	✅ (POST /toggle-status)
GET /api/monitoring-rules/check-name	名称唯一校验	✅
GET /api/monitoring-rules/enabled	已启用规则列表	✅
GET /api/monitoring-rules/{id}/histories	操作历史	❌ 未实现（详情接口已含历史）
POST /api/monitoring-rules/export	导出Excel	❌ 未实现

AM-1 录屏设置管理

PRD 接口	功能	后端状态
POST /api/recording-configs/query	列表查询	✅
POST /api/recording-configs	新增	✅
PUT /api/recording-configs/{id}	编辑	✅ (POST /update)
GET /api/recording-configs/{id}	详情	✅
PUT /api/recording-configs/{id}/status	状态变更	❌ 未实现
GET /api/screens/available	可配置大屏列表	✅ (路径不同)

AM-2 随机录屏

PRD 接口	功能	后端状态
POST /api/recording-tasks/query	列表查询	✅
GET /api/recording-tasks/{id}	详情	✅

AM-3 广告画面监控

PRD 接口	功能	后端状态
POST /api/monitor-records/query	列表查询	✅
GET /api/monitor-records/{id}	详情	✅
PUT /api/monitor-records/{id}/start	开始监控	✅
PUT /api/monitor-records/{id}/judge	监控判定	✅

CW-1 固化取证

PRD 接口	功能	后端状态
POST /api/evidence-records/query	列表查询	✅
GET /api/evidence-records/{id}	详情	✅
POST /api/evidence-records	保存取证	✅
GET /api/evidence-records/{id}/status-history	状态历史	❌ 未实现（详情接口已含）
GET /api/evidence-records/{id}/download	下载地址	❌ 未实现
GET /api/evidence-records/{id}/play	播放地址	❌ 未实现

CW-2 规则关联

PRD 接口	功能	后端状态
GET /api/evidence-rule-relations	查询已关联规则	✅
POST /api/evidence-rule-relations	关联规则	✅

CW-3 线索生成

PRD 接口	功能	后端状态
POST /api/monitoring-clues/query	列表查询	✅
GET /api/monitoring-clues/{id}	详情	✅
POST /api/monitoring-clues	生成线索	✅
GET /api/evidence-records/{id}/clue-preview	线索预览	❌ 未实现
GET /api/monitoring-clues/status-summary	状态统计	❌ 未实现

CW-4 线索转办

PRD 接口	功能	后端状态
POST /api/clue-transfer/query	转办记录列表	✅
GET /api/clue-transfer/{id}	转办详情	✅
POST /api/clue-transfer/submit	提交转办	✅
GET /api/clue-transfer/districts	区域列表	❌ 未实现
GET /api/clue-transfer/districts/{code}/departments	部门列表	❌ 未实现
GET /api/clue-transfer/departments/{id}/persons	人员列表	❌ 未实现
GET /api/clue-transfer/clues/{id}/disposal-feedback	处置反馈	❌ 未实现

缺失接口汇总

注：下表中标记 ❌ 的接口已在 2026-05-18 的"缺失接口补齐"和"CW-4 完善"中全部实现。此表保留作为历史对照。

类别	原缺失数	当前状态
导入/导出/模板下载	3	✅ 已补齐
唯一性校验	2	✅ 已补齐
状态变更/废止	2	✅ 已补齐
历史版本	1	✅ 已补齐
文件下载/播放	2	✅ 已补齐
级联选择	3	✅ 已补齐
线索预览/统计	2	✅ 已补齐
处置反馈	1	✅ 已补齐
CW-4 业务闭环	6	✅ 已补齐（pending-clues/status-update/urge/withdraw/operation-logs）

---

PRD vs 后端代码详细差异分析（2026-05-18 更新）

基础 CRUD 和 P0-P3 补齐接口均已实现并通过端到端测试。以下仅列出仍然存在的差异。

一、风格差异（不影响功能）

项目	PRD 要求	后端实现	影响
路径命名	复数名词 /api/screens	单数名词 /api/screen	不影响
HTTP 方法	RESTful（PUT/DELETE）	统一 POST	不影响
状态枚举值	字符串 "RECORDING"/"COMPLETED"	数字 1/2/3	不影响
分页默认大小	20 条/页	10 条/页	不影响
API 前缀	部分 PRD 要求 /api/cw/	无 /cw/ 前缀	不影响

二、缺失的业务逻辑（需补充）

AM-1 录屏设置

• 唯一性校验：PRD 要求同一大屏只能有一条配置，后端未在 save/update 中校验
• 时间范围校验：PRD 要求录屏时间必须在广告播放时间段内，后端未实现

AM-2 随机录屏

• 查询条件缺失：缺少 district（区域）和 screenName（大屏名称模糊匹配）筛选条件
• 时间范围限制：PRD 要求最大查询范围不超过 90 天，后端未限制

AM-3 广告画面监控

• 查询条件缺失：缺少时间范围（start_time/end_time）、监控人员（monitor_person）筛选
• 默认状态过滤：PRD 要求默认只查询未归档记录，后端未实现
• 并发控制：PRD 要求同一记录只能由一人监控，后端未实现
• 自动联动：PRD 要求判定为违法时自动触发 CW-1 取证流程，后端未实现

CW-1 固化取证

• 状态历史独立接口：PRD 要求 GET /evidence-records/{id}/status-history，当前详情接口已含但无独立入口
• 关联上下文接口：PRD 要求 GET /monitor-records/{id}/evidence-context（来源监控记录关联信息），后端未实现

CW-2 规则关联

• 搜索可关联规则：PRD 要求搜索可关联的监测规则列表，当前只能在 MR-1 的 enabled 接口获取

CW-3 线索生成

• 线索生成日志：PRD 要求 GET /monitoring-clues/{id}/generation-logs，后端未实现独立接口
• 广告主补充：PRD 要求线索确认时可补充广告主信息，后端 generate 接口未支持

三、缺失的通用功能

功能	涉及模块	说明
权限控制	全部	PRD 定义了市局/区局角色数据范围过滤，后端未实现
关联对象返回	AM-1/2/3, CW-1	PRD 要求返回 screen_info/config_info/video_info 嵌套对象，后端返回平铺字段
状态中文名	全部	PRD 要求返回 xxx_text 中文字段（如 task_status_text），后端未实现
归档标志	AM-3	PRD 要求 archive_flag 字段区分已归档/未归档，后端无此字段

四、CW-4 已超出 PRD 的实现

以下接口为后端主动扩展，PRD 中未要求但已实现：

接口	说明
POST /api/clue-transfer/status-update	外部系统回调状态流转
POST /api/clue-transfer/urge	催办
POST /api/clue-transfer/withdraw	撤回
GET /api/clue-transfer/pending-clues/query	待转办线索列表
GET /api/clue-transfer/pending-clues/detail	待转办线索详情
GET /api/clue-transfer/operation-logs	操作日志独立查询

框架 API 发现（2026-05-18 编译修复过程中）

SuperEntity（框架基类）

• 位置: com.chinaweal.youfool.framework.springboot.mybatis.plus.SuperEntity
• 不是泛型类，直接 extends SuperEntity 即可
• 提供字段: createBy, createTime, updateBy, updateTime, createName, updateName
• 自动填充策略: INSERT 时填充 createBy/createTime, INSERT_UPDATE 时填充 updateBy/updateTime

AssertUtils（断言工具）

• 位置: com.chinaweal.youfool.framework.springboot.common.util.AssertUtils
• isTrue(boolean, ResultCode, Object... params) — 第二个参数是 ResultCode 枚举，不是 String
• isNotNull(Object...) — 无消息参数版本，使用 BaseResultCode.PARAM_NOT_COMPLETE
• isNotBlank(String...) — 无消息参数版本，使用 BaseResultCode.PARAM_IS_BLANK
• isNotBlank(String, String) — 带消息参数的重载（varargs 导致编译通过）

RestResult（统一返回）

• 位置: com.chinaweal.youfool.framework.springboot.rest.RestResult
• ok() / ok(T data) — 成功返回
• error(ResultCode) / error(ResultCode, String msg) / error(ResultCode, T data) — 错误返回
• 没有 fail() 方法，统一使用 error()

BaseResultCode（常用错误码）

• SUCCESS — 成功
• PARAM_IS_INVALID — 参数无效
• PARAM_NOT_COMPLETE — 参数不完整
• PARAM_IS_BLANK — 参数为空