# OARMS 后端全模块开发计划

## 目标
完成广州广告监管系统全部 10 个模块的后端代码生成、DDL 建表语句生成、初始数据准备并执行到 DM8 数据库。

## 当前阶段

**状态**: 全部 10 个阶段已完成，编译验证通过 ✅，DDL 已执行到 DM8 ✅，缺失接口已补齐 ✅，端到端接口测试通过 ✅
**下一步**: 提交代码到 git

## 模块开发顺序（按依赖关系）

| 阶段 | 模块 | 实体/表 | 依赖 | 状态 |
|------|------|---------|------|------|
| Phase 1 | BS-1 大屏基础信息管理 | bs_screen, bs_screen_history | 无 | ✅ 完成 |
| Phase 2 | LB-1 法律法规管理 | lb_law_clause | 无 | ✅ 完成 |
| Phase 3 | MR-1 监测规则管理 | mr_monitoring_rule, mr_rule_law_clause_rel, mr_rule_operation_history | LB-1 | ✅ 完成 |
| Phase 4 | AM-1 录屏设置管理 | am_recording_config | BS-1 | ✅ 完成 |
| Phase 5 | AM-2 随机录屏 | am_recording_task, am_alert_notification | BS-1, AM-1 | ✅ 完成 |
| Phase 6 | AM-3 广告画面监控 | am_monitor_record | BS-1, AM-2 | ✅ 完成 |
| Phase 7 | CW-1 固化取证 | cw_evidence_record, cw_evidence_status_history | BS-1, AM-3 | ✅ 完成 |
| Phase 8 | CW-2 规则关联 | cw_evidence_rule_relation | CW-1, MR-1 | ✅ 完成 |
| Phase 9 | CW-3 线索生成 | cw_monitoring_clue, cw_clue_generation_log | CW-1, CW-2, BS-1, MR-1 | ✅ 完成 |
| Phase 10 | CW-4 线索转办 | cw_clue_transfer_record, cw_transfer_operation_log | CW-3 | ✅ 完成 |

## 每阶段执行步骤
1. 生成 DDL SQL 文件到 docs/db/sql/
2. 执行 DDL 到 DM8 数据库
3. 生成初始数据 SQL 并执行
4. 生成 Java 代码（Entity → Query/Req/VO → Mapper → Service → Controller）
5. 编译验证

## 后续待办

- [x] 执行 mvn compile 编译验证 ✅ 2026-05-18 BUILD SUCCESS
- [x] 确认 DM8 数据库连接参数 ✅ 172.22.80.70:15236 连通
- [x] 执行 DDL 到目标数据库 ✅ OARMS schema 下已有 17 张表
- [x] PRD vs 后端代码覆盖比对 ✅ 已完成
- [ ] 补齐缺失接口（分 4 批） ✅ 2026-05-18 全部完成
- [ ] 端到端接口测试 ✅ 2026-05-18 40/40 接口通过

---

## 缺失接口补齐计划

按业务影响度分为 4 个优先级批次。新增接口保持现有路径风格（单数名词、POST 为主）。

### P0 — 核心状态流转（阻塞业务流程）

| # | 模块 | 接口 | Controller 方法 | 说明 |
|---|------|------|----------------|------|
| 1 | BS-1 | `POST /api/screen/toggle-status` | toggleStatus(String id, Integer status) | 大屏启停用 |
| 2 | AM-1 | `POST /api/recording-config/toggle-status` | toggleStatus(String id, Integer status) | 配置启停用 |
| 3 | LB-1 | `POST /api/law-clause/repeal` | repeal(String id) | 条款废止（effectiveStatus → 0） |

### P1 — 前端页面必需（校验 & 列表 & 预览）

| # | 模块 | 接口 | Controller 方法 | 说明 |
|---|------|------|----------------|------|
| 4 | BS-1 | `GET /api/screen/check-code` | checkCode(String screenCode, String excludeId) | 编码唯一校验 |
| 5 | BS-1 | `GET /api/screen/check-address` | checkAddress(String address, String excludeId) | 地址唯一校验 |
| 6 | LB-1 | `GET /api/law-clause/check-clause-number` | checkClauseNumber(String clauseNumber, String excludeId) | 条款号唯一校验 |
| 7 | LB-1 | `GET /api/law-clause/effective` | effectiveList() | 已生效条款下拉 |
| 8 | CW-3 | `GET /api/monitoring-clue/clue-preview/{evidenceId}` | cluePreview(String evidenceId) | 线索生成前预览 |
| 9 | CW-3 | `GET /api/monitoring-clue/status-summary` | statusSummary() | 各状态线索数量统计 |

### P2 — 级联选择器（CW-4 转办页面依赖）

| # | 模块 | 接口 | Controller 方法 | 说明 |
|---|------|------|----------------|------|
| 10 | CW-4 | `GET /api/clue-transfer/targets/districts` | districtList() | 转办目标区域列表 |
| 11 | CW-4 | `GET /api/clue-transfer/targets/departments` | departmentList(String districtCode) | 按区域查部门 |
| 12 | CW-4 | `GET /api/clue-transfer/targets/persons` | personList(String departmentId) | 按部门查人员 |
| 13 | CW-4 | `GET /api/clue-transfer/clues/{clueId}/disposal-feedback` | disposalFeedback(String clueId) | 线索处置反馈 |

### P3 — 文件操作 & 导入导出（可延后）

| # | 模块 | 接口 | Controller 方法 | 说明 |
|---|------|------|----------------|------|
| 14 | CW-1 | `GET /api/evidence-record/download/{id}` | downloadUrl(String id) | 取证视频下载地址 |
| 15 | CW-1 | `GET /api/evidence-record/play/{id}` | playUrl(String id) | 取证视频播放地址 |
| 16 | BS-1 | `GET /api/screen/export` | export(ScreenQuery query) | 导出大屏数据 |
| 17 | BS-1 | `POST /api/screen/import` | importData(MultipartFile file) | 批量导入大屏 |
| 18 | BS-1 | `GET /api/screen/import-template` | importTemplate() | 下载导入模板 |
| 19 | BS-1 | `GET /api/screen/{id}/histories` | histories(String id) | 大屏历史版本列表 |
| 20 | MR-1 | `POST /api/monitoring-rules/export` | export(MonitoringRuleQuery query) | 导出规则 Excel |

### 实施规则

1. 新增接口在已有 Controller 中追加方法，不新建 Controller
2. Service 层新增方法在已有 ServiceImpl 中实现
3. 路径风格遵循现有规范：单数名词 + 小写 + 短横线分隔
4. 编译验证在每批次完成后执行

## 错误记录

| # | 问题 | 修复 | 日期 |
|---|------|------|------|
| 1 | 8 个未使用 import 被 Checkstyle 拦截 | 删除多余 import | 2026-05-18 |
| 2 | 13 个 Entity 的 SuperEntity 泛型参数错误 | 批量替换为无参 `extends SuperEntity` | 2026-05-18 |
| 3 | 7 处 AssertUtils.isTrue 签名不匹配 | 加 BaseResultCode.PARAM_IS_INVALID 参数 | 2026-05-18 |
| 4 | LawClauseEntity.getClauseName() 不存在 | 改为 getLawName() | 2026-05-18 |
| 5 | JDK 25 不兼容 | pom.xml 改为 JDK 21 | 2026-05-18 |
| 6 | spring-boot:run classpath 只含 target/classes | ZIP layout + includes nothing 过滤了依赖；改用 java -cp | 2026-05-18 |
| 7 | DM8 不支持 `select version()` | validation-query 改为 `SELECT 1` | 2026-05-18 |
| 8 | Sa-Token NPE 导致所有写入失败 | UserBaseServiceImpl catch NotLoginException → Exception | 2026-05-18 |
| 9 | NotLoginException import 未使用 | 删除多余 import | 2026-05-18 |