# 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 | 处置反馈 | ❌ 未实现 |

#### 缺失接口汇总

| 类别 | 缺失接口数 | 涉及模块 |
|------|-----------|---------|
| 导入/导出/模板下载 | 3 | BS-1, MR-1 |
| 唯一性校验 | 2 | BS-1, LB-1 |
| 状态变更/废止 | 2 | BS-1, AM-1, LB-1 |
| 历史版本 | 1 | BS-1 |
| 文件下载/播放 | 2 | CW-1 |
| 级联选择（区域/部门/人员） | 3 | CW-4 |
| 线索预览/统计 | 2 | CW-3 |
| 处置反馈 | 1 | CW-4 |
| **合计** | **~16** | |

### 框架 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` — 参数为空