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/docs/前后端联调指南.md

759 lines
45 KiB
Markdown
Raw Permalink Normal View History

docs: 添加项目指引 + 前后端联调指南 + 错题库 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-21 17:22:27 +08:00
# OARMS 前后端联调指南
> AI 可执行的联调自动化校验手册。按模块逐层核对 PRD→前端接口→后端API→DTO→数据库表的完整链路。
## 一、联调流程总览
联调链路：**PRD文档 → 前端接口定义 → 后端API路由 → 入参DTO → 数据库表 → 字段映射**
每个模块的联调校验分为 5 层：
| 层级 | 校验内容 | 数据来源 |
| ----------- | ---------------------- | -------------------------- |
| L1 接口存在性 | 前端调用的路由是否在后端有对应实现 | Controller @RequestMapping |
| L2 参数一致性 | 前端传参字段名/类型是否与后端 DTO 一致 | Query/Req 类字段 vs 前端请求体 |
| L3 返回值一致性 | 后端返回字段是否满足前端展示需要 | VO/Entity 字段 vs 前端消费字段 |
| L4 DTO-DB映射 | Entity 字段是否与数据库列一一对应 | @TableField vs DDL 列定义 |
| L5 数据完整性 | 表是否存在、是否有初始数据、字段约束是否满足 | DDL 文件 + 数据库查询 |
## 二、可执行校验规则
### 2.1 接口存在性校验
```
CHECK: 对前端每个 API 调用，在后端 Controller 中查找匹配路由
RULE: HTTP方法 + 路径 必须精确匹配
FAIL: 前端调用 POST /api/xxx/save 但后端无此路由 → 缺少接口
```
### 2.2 参数一致性校验
```
CHECK: 前端请求体字段 vs 后端 Query/Req 类字段
RULE:
- 字段名必须完全一致（camelCase）
- 字段类型兼容（前端String ↔ 后端String/Integer/LocalDate等）
- 必填字段标记一致
FAIL:
- 前端传 screenName 但后端 DTO 无此字段 → 字段缺失
- 前端传 String 但后端期望 Integer → 类型不匹配
```
### 2.3 返回值一致性校验
```
CHECK: 后端 VO/Entity 返回字段 vs 前端渲染需要的字段
RULE:
- 前端表格列(col.prop) 必须与返回 JSON key 一致
- 分页字段：后端 MyBatis-Plus 返回 records，非 list
- 日期格式：后端 @JsonFormat 自动格式化，前端直接展示
- JSON字符串字段：relatedRules/relatedLawClauses/scopeDistricts 返回 String，前端需 JSON.parse()
FAIL:
- 前端用 res.data.list 但后端返回 records → 分页字段不匹配
- 前端直接对 JSON 字符串调 .map() → 类型错误
```
### 2.4 DTO-DB映射校验
```
CHECK: Entity 字段 vs 数据库表列
RULE:
- @TableField("column_name") 的 column_name 必须在 DDL 中存在
- Java类型映射：String↔VARCHAR/CLOB, Integer↔TINYINT/INT, BigDecimal↔DECIMAL, LocalDate↔DATE, LocalDateTime↔TIMESTAMP
- SuperEntity 审计字段（createBy/createTime/createName/updateBy/updateTime/updateName）不在 Entity 中声明但 DB 有对应列
FAIL:
- Entity 字段无对应 DB 列 → 字段映射缺失
- 类型不匹配（如 Java String vs DB INT）→ 类型映射错误
```
### 2.5 数据完整性校验
```
CHECK: 数据库表是否存在、是否有初始数据
RULE:
- 每个 Entity 对应的表必须在 DDL 文件中定义
- 有 init_data.sql 的表应包含种子数据
- 唯一约束字段必须有 check 接口支持
FAIL:
- DDL 文件不存在 → 需创建表
- 有表无数据 → 需补充初始数据
```
### 2.6 高频错误模式速查
| 错误模式 | 检测方法 | 修复方案 |
| ------------------------ | -------------------- | ----------------------------------- |
| 字段名不匹配（中文prop vs 英文key） | 对比前端prop与后端VO字段 | prop 必须与 JSON key 一致 |
| rowKey不匹配（默认id vs 实际主键名） | 检查Entity @TableId字段名 | 显式设置 row-key="实际主键名" |
| 分页字段名（list vs records） | 检查返回类型 Page\<Entity> | 统一用 res.records |
| JSON字符串未解析 | 检查CLOB/JSON字段前端处理 | JSON.parse() 或 Array.isArray() 判断 |
| 数组当单对象 | 检查一对多关系的详情接口 | Array.isArray() ? data\[0] : data |
| 导出接口未设blob | 检查文件下载请求 | 设置 responseType: 'blob' |
| null值导致组件报错 | 检查码表/选项接口返回 | .filter(item => item.value != null) |
| 排序字段驼峰未转下划线 | 检查后端排序逻辑 | 字段名转下划线后再拼SQL |
***
## 三、模块核对表
### 3.1 BS-1 大屏管理
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | --------------------------- | ----------------------------------- | ---------------------------------- | ------ |
| POST | /api/screen/query | ScreenQuery | RestResult\<Page\<ScreenDetailVO>> | 分页查询 |
| GET | /api/screen/detail | String id | RestResult\<ScreenDetailVO> | 详情 |
| POST | /api/screen/save | ScreenSaveReq | RestResult\<?> | 新增 |
| POST | /api/screen/update | ScreenSaveReq | RestResult\<?> | 更新 |
| POST | /api/screen/remove | String id | RestResult\<?> | 删除 |
| GET | /api/screen/options | - | RestResult\<List\<Map>> | 选项列表 |
| GET | /api/screen/district/list | - | RestResult\<List\<Map>> | 行政区划选项 |
| POST | /api/screen/toggle-status | String id, Integer status | RestResult\<?> | 切换状态 |
| GET | /api/screen/check-code | String screenCode, String excludeId | RestResult\<Map> | 编码唯一校验 |
| GET | /api/screen/check-address | String address, String excludeId | RestResult\<Map> | 地址唯一校验 |
| GET | /api/screen/export | ScreenQuery | RestResult\<List\<Map>> | 导出 |
| POST | /api/screen/import | List\<Map> dataList | RestResult\<Map> | 导入 |
| GET | /api/screen/import-template | - | RestResult\<List\<Map>> | 导入模板 |
| GET | /api/screen/histories | String id | RestResult\<List\<Map>> | 历史版本 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| ------------ | ------- | --- | ----- |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| keyword | String | - | 关键词搜索 |
| district | String | - | 区域筛选 |
| screenStatus | Integer | - | 状态筛选 |
#### SaveReq 字段
| 字段 | 类型 | 说明 |
| --------------- | ---------- | -------------- |
| id | String | 主键（更新时必传） |
| screenCode | String | 大屏编码（唯一）**必传** |
| screenName | String | 大屏名称 **必传** |
| address | String | 地址（唯一）**必传** |
| district | String | 所属区域 **必传** |
| ownerUnit | String | 业主单位 **必传** |
| ownerContact | String | 业主联系方式 |
| operatorUnit | String | 运营单位 **必传** |
| operatorContact | String | 运营联系方式 |
| advertiser | String | 广告主 |
| screenSpec | String | 屏幕规格 **必传** |
| adPlayTimeRange | String | 广告播放时间段 **必传** |
| screenStatus | Integer | 状态 |
| longitude | BigDecimal | 经度 |
| latitude | BigDecimal | 纬度 |
#### 数据库表：bs\_screen
| DB列 | Java字段 | 类型 | 约束 |
| --------------------- | --------------- | ------------- | ------------------------------ |
| ID | id | VARCHAR(50) | PK, ASSIGN\_UUID |
| SCREEN\_CODE | screenCode | VARCHAR(30) | NOT NULL, UNIQUE |
| SCREEN\_NAME | screenName | VARCHAR(100) | NOT NULL |
| ADDRESS | address | VARCHAR(200) | NOT NULL, UNIQUE |
| DISTRICT | district | VARCHAR(20) | NOT NULL |
| OWNER\_UNIT | ownerUnit | VARCHAR(100) | NOT NULL |
| OWNER\_CONTACT | ownerContact | VARCHAR(20) | <br /> |
| OPERATOR\_UNIT | operatorUnit | VARCHAR(100) | NOT NULL |
| OPERATOR\_CONTACT | operatorContact | VARCHAR(20) | <br /> |
| ADVERTISER | advertiser | VARCHAR(100) | <br /> |
| SCREEN\_SPEC | screenSpec | VARCHAR(50) | NOT NULL |
| AD\_PLAY\_TIME\_RANGE | adPlayTimeRange | VARCHAR(20) | NOT NULL |
| SCREEN\_STATUS | screenStatus | TINYINT | NOT NULL, 默认1, 1=正常,2=停用,3=维修中 |
| LONGITUDE | longitude | DECIMAL(10,6) | <br /> |
| LATITUDE | latitude | DECIMAL(10,6) | <br /> |
| CREATE\_BY | - (SuperEntity) | VARCHAR(50) | <br /> |
| CREATE\_TIME | - (SuperEntity) | TIMESTAMP | <br /> |
| CREATE\_NAME | - (SuperEntity) | VARCHAR(50) | <br /> |
| UPDATE\_BY | - (SuperEntity) | VARCHAR(50) | <br /> |
| UPDATE\_TIME | - (SuperEntity) | TIMESTAMP | <br /> |
| UPDATE\_NAME | - (SuperEntity) | VARCHAR(50) | <br /> |
关联表：bs\_screen\_history（历史版本）
DDL：V1.0.0\_\_BS\_screen\_ddl.sql + V1.0.0\_\_BS\_screen\_init\_data.sql
***
### 3.2 LB-1 法律法规
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | ----------------------------------- | ------------------------------------- | ----------------------------------- | ------- |
| POST | /api/law-clause/query | LawClauseQuery | RestResult\<Page\<LawClauseEntity>> | 分页查询 |
| GET | /api/law-clause/detail | String id | RestResult\<LawClauseEntity> | 详情 |
| POST | /api/law-clause/save | LawClauseSaveReq | RestResult\<?> | 新增 |
| POST | /api/law-clause/update | LawClauseSaveReq | RestResult\<?> | 更新 |
| POST | /api/law-clause/remove | String id | RestResult\<?> | 删除 |
| GET | /api/law-clause/options | - | RestResult\<List\<Map>> | 选项列表 |
| POST | /api/law-clause/repeal | String id | RestResult\<?> | 废止 |
| GET | /api/law-clause/check-clause-number | String clauseNumber, String excludeId | RestResult\<Map> | 条款号唯一校验 |
| GET | /api/law-clause/effective | - | RestResult\<List\<LawClauseEntity>> | 已生效条款 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| --------------- | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| keyword | String | - | 关键词搜索 |
| effectiveStatus | Integer | - | 生效状态筛选 |
#### SaveReq 字段
| 字段 | 类型 | 说明 |
| -------------------- | --------- | -------------- |
| id | String | 主键（更新时必传） |
| clauseCode | String | 条款编号（唯一）**必传** |
| lawName | String | 法规名称 **必传** |
| clauseNumber | String | 条款号 **必传** |
| clauseContent | String | 条款内容 **必传** |
| clauseContentSummary | String | 条款摘要 |
| effectiveStatus | Integer | 生效状态 1=有效,2=废止 |
| publishDate | LocalDate | 发布日期 |
#### 数据库表：lb\_law\_clause
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | -------------------- | ------------- | ------------------------ |
| ID | id | VARCHAR(50) | PK, ASSIGN\_UUID |
| CLAUSE\_CODE | clauseCode | VARCHAR(30) | UNIQUE |
| LAW\_NAME | lawName | VARCHAR(200) | NOT NULL |
| CLAUSE\_NUMBER | clauseNumber | VARCHAR(50) | NOT NULL |
| CLAUSE\_CONTENT | clauseContent | VARCHAR(2000) | NOT NULL |
| CLAUSE\_CONTENT\_SUMMARY | clauseContentSummary | VARCHAR(200) | <br /> |
| EFFECTIVE\_STATUS | effectiveStatus | TINYINT | NOT NULL, 默认1, 1=有效,2=废止 |
| PUBLISH\_DATE | publishDate | DATE | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V2.0.0\_\_LB\_law\_ddl.sql + V2.0.0\_\_LB\_law\_init\_data.sql
***
### 3.3 MR-1 监测规则
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | ------------------------------------ | --------------------------------- | ------------------------------------------ | ------ |
| POST | /api/monitoring-rules/query | MonitoringRuleQuery | RestResult\<Page\<MonitoringRuleDetailVO>> | 分页查询 |
| GET | /api/monitoring-rules/detail | String id | RestResult\<MonitoringRuleDetailVO> | 详情 |
| POST | /api/monitoring-rules/save | MonitoringRuleSaveReq | RestResult\<?> | 新增 |
| POST | /api/monitoring-rules/update | MonitoringRuleSaveReq | RestResult\<?> | 更新 |
| POST | /api/monitoring-rules/remove | String id | RestResult\<?> | 删除 |
| POST | /api/monitoring-rules/toggle-status | String id, Integer status | RestResult\<?> | 切换启用状态 |
| GET | /api/monitoring-rules/check-name | String ruleName, String excludeId | RestResult\<Map> | 名称唯一校验 |
| GET | /api/monitoring-rules/enabled | - | RestResult\<List\<Map>> | 已启用规则 |
| GET | /api/monitoring-rules/scope-types | - | RestResult\<List\<Map>> | 范围类型选项 |
| GET | /api/monitoring-rules/status-options | - | RestResult\<List\<Map>> | 状态选项 |
| POST | /api/monitoring-rules/export | MonitoringRuleQuery | RestResult\<List\<Map>> | 导出 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| ------------ | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| keyword | String | - | 关键词搜索 |
| enableStatus | Integer | - | 启用状态筛选 |
| scopeType | Integer | - | 范围类型筛选 |
#### SaveReq 字段
| 字段 | 类型 | 说明 |
| -------------- | ------------- | ------------------------------------ |
| id | String | 主键（更新时必传） |
| ruleCode | String | 规则编码（唯一） |
| ruleName | String | 规则名称（唯一） |
| ruleContent | String | 规则内容 |
| scopeType | Integer | 适用范围 1=全部大屏,2=指定区域 |
| scopeDistricts | String | 适用区域列表（JSON数组字符串）⚠️前端需JSON.stringify |
| enableStatus | Integer | 启用状态 1=已启用,2=已停用 |
| clauseIds | List\<String> | 关联法条ID列表 |
#### DetailVO 额外字段
| 字段 | 类型 | 说明 |
| ---------- | ---------- | -------- |
| lawClauses | List\<Map> | 关联法条详情列表 |
| histories | List\<Map> | 操作历史列表 |
#### 数据库表
主表：mr\_monitoring\_rule
关联表：mr\_rule\_law\_clause\_rel（规则-法条关联）
日志表：mr\_rule\_operation\_history（操作历史）
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | --------------- | ------------- | ---------------------- |
| ID | id | VARCHAR(50) | PK |
| RULE\_CODE | ruleCode | VARCHAR(30) | UNIQUE |
| RULE\_NAME | ruleName | VARCHAR(100) | UNIQUE |
| RULE\_CONTENT | ruleContent | VARCHAR(2000) | <br /> |
| SCOPE\_TYPE | scopeType | TINYINT | 1=全部,2=指定区域 |
| SCOPE\_DISTRICTS | scopeDistricts | CLOB | JSON数组 ⚠️前端需JSON.parse |
| ENABLE\_STATUS | enableStatus | TINYINT | 1=启用,2=停用 |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V6.0.0\_\_MR\_monitoring\_rule\_ddl.sql + V6.0.0\_\_MR\_monitoring\_rule\_init\_data.sql
⚠️ **JSON字段注意**：scopeDistricts 在 DB 中为 CLOB 存储 JSON 数组，后端 Entity 返回 String 类型。前端使用时需要 JSON.parse() 解析，不能直接当数组用。
***
### 3.4 AM-1 录屏设置
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | ------------------------------------------ | ------------------------- | ----------------------------------------- | ------- |
| POST | /api/recording-config/query | RecordingConfigQuery | RestResult\<Page\<RecordingConfigEntity>> | 分页查询 |
| GET | /api/recording-config/detail | String id | RestResult\<RecordingConfigEntity> | 详情 |
| POST | /api/recording-config/save | RecordingConfigSaveReq | RestResult\<?> | 新增 |
| POST | /api/recording-config/update | RecordingConfigSaveReq | RestResult\<?> | 更新 |
| POST | /api/recording-config/remove | String id | RestResult\<?> | 删除 |
| GET | /api/recording-config/configurable-screens | - | RestResult\<List\<Map>> | 可配置大屏列表 |
| POST | /api/recording-config/toggle-status | String id, Integer status | RestResult\<?> | 切换启用状态 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| ------------ | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| keyword | String | - | 关键词搜索 |
| district | String | - | 区域筛选 |
| configStatus | Integer | - | 配置状态筛选 |
#### SaveReq 字段
| 字段 | 类型 | 说明 |
| --------------- | ------- | ---------------- |
| id | String | 主键（更新时必传） |
| screenId | String | 大屏ID（唯一约束） |
| screenName | String | 大屏名称（冗余） |
| screenAddress | String | 大屏地址（冗余） |
| district | String | 所属区域（冗余） |
| recordStartTime | String | 录屏开始时间 HH:MM:SS |
| recordEndTime | String | 录屏结束时间 HH:MM:SS |
| recordDuration | Integer | 单次录屏时长（秒，10-300） |
| recordFrequency | Integer | 录屏频率（分钟，1-60） |
| configStatus | Integer | 配置状态 1=已启用,2=已停用 |
#### 数据库表：am\_recording\_config
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | --------------- | ------------ | --------- |
| ID | id | VARCHAR(50) | PK |
| SCREEN\_ID | screenId | VARCHAR(50) | UNIQUE |
| SCREEN\_NAME | screenName | VARCHAR(200) | <br /> |
| SCREEN\_ADDRESS | screenAddress | VARCHAR(500) | <br /> |
| DISTRICT | district | VARCHAR(50) | <br /> |
| RECORD\_START\_TIME | recordStartTime | VARCHAR(8) | HH:MM:SS |
| RECORD\_END\_TIME | recordEndTime | VARCHAR(8) | HH:MM:SS |
| RECORD\_DURATION | recordDuration | INT | 10-300 |
| RECORD\_FREQUENCY | recordFrequency | INT | 1-60 |
| CONFIG\_STATUS | configStatus | TINYINT | 1=启用,2=停用 |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V3.0.0\_\_AM\_recording\_config\_ddl.sql（无 init\_data）
***
### 3.5 AM-2 随机录屏
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | -------------------------- | ------------------ | --------------------------------------- | ---- |
| POST | /api/recording-task/query | RecordingTaskQuery | RestResult\<Page\<RecordingTaskEntity>> | 分页查询 |
| GET | /api/recording-task/detail | String id | RestResult\<Map> | 详情 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| -------------- | ------- | --- | ------- |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| screenId | String | - | 大屏筛选 |
| taskStatus | Integer | - | 任务状态筛选 |
| startTimeBegin | String | - | 开始时间范围起 |
| startTimeEnd | String | - | 开始时间范围止 |
| district | String | - | 区域筛选 |
| screenName | String | - | 大屏名称筛选 |
#### 数据库表：am\_recording\_task
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | --------------- | ------------ | ---------------- |
| ID | id | VARCHAR(50) | PK |
| SCREEN\_ID | screenId | VARCHAR(50) | <br /> |
| CONFIG\_ID | configId | VARCHAR(50) | <br /> |
| ACTUAL\_START\_TIME | actualStartTime | TIMESTAMP | <br /> |
| ACTUAL\_END\_TIME | actualEndTime | TIMESTAMP | <br /> |
| TASK\_STATUS | taskStatus | TINYINT | 1=录屏中,2=已完成,3=失败 |
| VIDEO\_FILE\_PATH | videoFilePath | VARCHAR(500) | <br /> |
| RETRY\_COUNT | retryCount | INT | <br /> |
| ERROR\_MESSAGE | errorMessage | VARCHAR(500) | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
关联表：am\_alert\_notification（告警通知）
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | --------------- | ------------ | -------------------- |
| ID | id | VARCHAR(50) | PK |
| TASK\_ID | taskId | VARCHAR(50) | <br /> |
| SCREEN\_ID | screenId | VARCHAR(50) | <br /> |
| ALERT\_TYPE | alertType | TINYINT | 1=录屏失败,2=录屏超时,3=设备离线 |
| ALERT\_MESSAGE | alertMessage | VARCHAR(500) | <br /> |
| IS\_RESOLVED | isResolved | TINYINT | 0=未处理,1=已处理 |
| RESOLVED\_BY | resolvedBy | VARCHAR(100) | <br /> |
| RESOLVED\_AT | resolvedAt | TIMESTAMP | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V4.0.0\_\_AM\_recording\_task\_ddl.sql（无 init\_data）
***
### 3.6 AM-3 广告画面监控
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | -------------------------- | ------------------ | --------------------------------------- | ---- |
| POST | /api/monitor-record/query | MonitorRecordQuery | RestResult\<Page\<MonitorRecordEntity>> | 分页查询 |
| GET | /api/monitor-record/detail | String id | RestResult\<MonitorRecordEntity> | 详情 |
| POST | /api/monitor-record/start | String id | RestResult\<?> | 开始监控 |
| POST | /api/monitor-record/judge | MonitorJudgeReq | RestResult\<?> | 监控判定 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| ------------- | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| screenId | String | - | 大屏筛选 |
| monitorStatus | Integer | - | 监控状态筛选 |
| district | String | - | 区域筛选 |
| startTime | String | - | 开始时间 |
| endTime | String | - | 结束时间 |
| monitorPerson | String | - | 监控人 |
| screenName | String | - | 大屏名称 |
#### JudgeReq 字段
| 字段 | 类型 | 说明 |
| ------------- | ------- | -------------- |
| id | String | 记录ID |
| monitorStatus | Integer | 判定状态 3=正常,4=违规 |
| monitorResult | String | 判定结果描述 |
#### 数据库表：am\_monitor\_record
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | --------------- | ------------ | --------------------- |
| ID | id | VARCHAR(50) | PK |
| TASK\_ID | taskId | VARCHAR(50) | <br /> |
| SCREEN\_ID | screenId | VARCHAR(50) | <br /> |
| SCREEN\_NAME | screenName | VARCHAR(200) | 冗余 |
| SCREEN\_ADDRESS | screenAddress | VARCHAR(500) | 冗余 |
| DISTRICT | district | VARCHAR(50) | 冗余 |
| MONITOR\_STATUS | monitorStatus | TINYINT | 1=待监控,2=监控中,3=正常,4=违规 |
| MONITOR\_RESULT | monitorResult | VARCHAR(500) | <br /> |
| MONITOR\_PERSON | monitorPerson | VARCHAR(100) | <br /> |
| MONITORED\_AT | monitoredAt | TIMESTAMP | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V5.0.0\_\_AM\_monitor\_record\_ddl.sql（无 init\_data）
***
### 3.7 CW-1 固化取证
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | ----------------------------- | --------------------- | ------------------------------------------ | ---- |
| POST | /api/evidence-record/query | EvidenceRecordQuery | RestResult\<Page\<EvidenceRecordDetailVO>> | 分页查询 |
| GET | /api/evidence-record/detail | String id | RestResult\<EvidenceRecordDetailVO> | 详情 |
| POST | /api/evidence-record/save | EvidenceRecordSaveReq | RestResult\<?> | 保存取证 |
| GET | /api/evidence-record/download | String id | RestResult\<Map> | 下载地址 |
| GET | /api/evidence-record/play | String id | RestResult\<Map> | 播放地址 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| -------------- | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| district | String | - | 区域筛选 |
| evidenceStatus | Integer | - | 取证状态筛选 |
| startTime | String | - | 开始时间 |
| endTime | String | - | 结束时间 |
| evidencePerson | String | - | 取证人 |
#### SaveReq 字段
| 字段 | 类型 | 说明 |
| ----------------- | ------- | ---------------------- |
| monitorRecordId | String | 关联监测记录ID **必传** |
| screenId | String | 大屏ID **必传** |
| evidenceVideoFile | String | 取证视频文件路径 **必传** |
| clipStartTime | String | 片段起始时间 HH:MM:SS **必传** |
| clipEndTime | String | 片段结束时间 HH:MM:SS **必传** |
| clipDuration | Integer | 片段时长（秒，>=3）**必传** |
| evidencePerson | String | 取证人 **必传** |
#### DetailVO 额外字段
| 字段 | 类型 | 说明 |
| ------------- | ---------- | ------ |
| statusHistory | List\<Map> | 状态变更历史 |
#### 数据库表
主表：cw\_evidence\_record
日志表：cw\_evidence\_status\_history
主表字段：
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | ------------------- | ------------ | -------------------------------------- |
| ID | id | VARCHAR(50) | PK |
| MONITOR\_RECORD\_ID | monitorRecordId | VARCHAR(50) | NOT NULL |
| SCREEN\_ID | screenId | VARCHAR(50) | NOT NULL |
| SCREEN\_NAME | screenName | VARCHAR(200) | NOT NULL, 冗余 |
| SCREEN\_ADDRESS | screenAddress | VARCHAR(500) | NOT NULL, 冗余 |
| DISTRICT | district | VARCHAR(50) | NOT NULL, 冗余 |
| EVIDENCE\_VIDEO\_FILE | evidenceVideoFile | VARCHAR(500) | NOT NULL, UNIQUE |
| CLIP\_START\_TIME | clipStartTime | VARCHAR(8) | NOT NULL, HH:MM:SS |
| CLIP\_END\_TIME | clipEndTime | VARCHAR(8) | NOT NULL, HH:MM:SS |
| CLIP\_DURATION | clipDuration | INT | NOT NULL, >=3 |
| EVIDENCE\_STATUS | evidenceStatus | TINYINT | NOT NULL, 默认1, 1=待关联规则,2=已关联规则,3=已生成线索 |
| EVIDENCE\_PERSON | evidencePerson | VARCHAR(100) | NOT NULL |
| EVIDENCED\_AT | evidencedAt | TIMESTAMP | NOT NULL |
| SOURCE\_MONITOR\_PERSON | sourceMonitorPerson | VARCHAR(100) | NOT NULL, 冗余 |
| SOURCE\_MONITOR\_TIME | sourceMonitorTime | TIMESTAMP | 冗余 |
| SOURCE\_MONITOR\_REMARK | sourceMonitorRemark | VARCHAR(500) | 冗余 |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V7.0.0\_\_CW\_evidence\_ddl.sql（无 init\_data）
⚠️ **文件下载/播放**：download 和 play 接口当前为占位实现，需对接文件存储系统。
***
### 3.8 CW-2 规则关联
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | --------------------------------------------- | ----------------- | ----------------------- | -------- |
| GET | /api/evidence-rule-relation/query-by-evidence | String evidenceId | RestResult\<List\<Map>> | 按证据查关联规则 |
| POST | /api/evidence-rule-relation/relate | RuleRelateReq | RestResult\<?> | 关联规则 |
#### RuleRelateReq 字段
| 字段 | 类型 | 说明 |
| ---------- | ------------- | ------ |
| evidenceId | String | 证据ID |
| ruleIds | List\<String> | 规则ID列表 |
#### 数据库表：cw\_evidence\_rule\_relation
| DB列 | Java字段 | 类型 | 约束 |
| -------------- | ------------ | ----------- | ------ |
| ID | id | VARCHAR(50) | PK |
| EVIDENCE\_ID | evidenceId | VARCHAR(50) | <br /> |
| RULE\_ID | ruleId | VARCHAR(50) | <br /> |
| ASSOCIATED\_BY | associatedBy | VARCHAR(50) | <br /> |
| ASSOCIATED\_AT | associatedAt | TIMESTAMP | <br /> |
DDL：V8.0.0\_\_CW\_evidence\_rule\_relation\_ddl.sql（无 init\_data）
***
### 3.9 CW-3 线索生成
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | ----------------------------------- | ------------------- | ------------------------------------------ | ------- |
| POST | /api/monitoring-clue/query | MonitoringClueQuery | RestResult\<Page\<MonitoringClueDetailVO>> | 分页查询 |
| GET | /api/monitoring-clue/detail | String id | RestResult\<MonitoringClueDetailVO> | 详情 |
| POST | /api/monitoring-clue/generate | String evidenceId | RestResult\<?> | 生成线索 |
| GET | /api/monitoring-clue/clue-preview | String evidenceId | RestResult\<Map> | 生成前预览 |
| GET | /api/monitoring-clue/status-summary | - | RestResult\<List\<Map>> | 各状态数量统计 |
#### Query 字段
| 字段 | 类型 | 默认值 | 说明 |
| ---------- | ------- | --- | ------ |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| clueCode | String | - | 线索编码 |
| district | String | - | 区域筛选 |
| clueStatus | Integer | - | 线索状态筛选 |
| keyword | String | - | 关键词 |
#### DetailVO 额外字段
| 字段 | 类型 | 说明 |
| -------------- | ---------- | ------ |
| generationLogs | List\<Map> | 生成日志列表 |
#### 数据库表
主表：cw\_monitoring\_clue
日志表：cw\_clue\_generation\_log
主表字段：
| DB列 | Java字段 | 类型 | 约束 |
| -------------------------- | ----------------- | ------------ | ------------------------------- |
| ID | id | VARCHAR(50) | PK |
| CLUE\_CODE | clueCode | VARCHAR(20) | UNIQUE, 格式 XS-{YYYYMMDD}-{seq3} |
| EVIDENCE\_ID | evidenceId | VARCHAR(50) | UNIQUE |
| SCREEN\_ID | screenId | VARCHAR(50) | <br /> |
| SCREEN\_NAME | screenName | VARCHAR(100) | 冗余 |
| SCREEN\_ADDRESS | screenAddress | VARCHAR(200) | 冗余 |
| DISTRICT | district | VARCHAR(20) | 冗余 |
| OWNER\_UNIT | ownerUnit | VARCHAR(100) | 冗余 |
| OWNER\_CONTACT | ownerContact | VARCHAR(20) | 冗余 |
| OPERATOR\_UNIT | operatorUnit | VARCHAR(100) | 冗余 |
| OPERATOR\_CONTACT | operatorContact | VARCHAR(20) | 冗余 |
| ADVERTISER | advertiser | VARCHAR(100) | 冗余 |
| RELATED\_RULES | relatedRules | CLOB | JSON数组 ⚠️需JSON.parse |
| RELATED\_LAW\_CLAUSES | relatedLawClauses | CLOB | JSON数组 ⚠️需JSON.parse |
| VIDEO\_EVIDENCE\_PATH | videoEvidencePath | VARCHAR(500) | <br /> |
| CLIP\_START\_TIME | clipStartTime | VARCHAR(8) | 冗余 |
| CLIP\_END\_TIME | clipEndTime | VARCHAR(8) | 冗余 |
| CLIP\_DURATION | clipDuration | INT | 冗余 |
| CLUE\_STATUS | clueStatus | TINYINT | 1=待转办,2=已转办,3=处理中,4=已办结 |
| GENERATED\_BY | generatedBy | VARCHAR(100) | <br /> |
| GENERATED\_AT | generatedAt | TIMESTAMP | <br /> |
| TRANSFERRED\_AT | transferredAt | TIMESTAMP | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V9.0.0\_\_CW\_monitoring\_clue\_ddl.sql（无 init\_data）
⚠️ **JSON字段注意**：relatedRules 和 relatedLawClauses 为 CLOB 存储 JSON 数组，前端需 JSON.parse()。
⚠️ **线索编码规则**：自动生成，格式 `XS-{YYYYMMDD}-{seq3}`。
***
### 3.10 CW-4 线索转办
#### 接口清单
| 方法 | 路径 | 入参类型 | 返回类型 | 说明 |
| ---- | --------------------------------------------------- | ----------------------- | ---------------------------------------- | ---------- |
| POST | /api/clue-transfer/query | ClueTransferQuery | RestResult\<Page\<ClueTransferDetailVO>> | 分页查询 |
| GET | /api/clue-transfer/detail | String id | RestResult\<ClueTransferDetailVO> | 详情 |
| POST | /api/clue-transfer/submit | ClueTransferReq | RestResult\<?> | 提交转办 |
| GET | /api/clue-transfer/targets/districts | - | RestResult\<List\<Map>> | 目标区域 |
| GET | /api/clue-transfer/targets/departments | String districtCode | RestResult\<List\<Map>> | 目标部门 |
| GET | /api/clue-transfer/targets/persons | String departmentId | RestResult\<List\<Map>> | 目标人员 |
| GET | /api/clue-transfer/clues/{clueId}/disposal-feedback | String clueId | RestResult\<Map> | 处置反馈 |
| POST | /api/clue-transfer/pending-clues/query | PendingClueQuery | RestResult\<Page\<PendingClueVO>> | 待转办线索查询 |
| GET | /api/clue-transfer/pending-clues/detail | String clueId | RestResult\<PendingClueDetailVO> | 待转办线索详情 |
| GET | /api/clue-transfer/operation-logs | String transferRecordId | RestResult\<List\<OperationLogVO>> | 操作日志 |
| POST | /api/clue-transfer/status-update | TransferStatusUpdateReq | RestResult\<?> | 状态更新（外部回调） |
| POST | /api/clue-transfer/urge | TransferUrgeReq | RestResult\<?> | 催办 |
| POST | /api/clue-transfer/withdraw | TransferWithdrawReq | RestResult\<?> | 撤回 |
#### ClueTransferQuery 字段
| 字段 | 类型 | 默认值 | 说明 |
| ---------------------- | ------- | --- | ---- |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| clueId | String | - | 线索ID |
| transferTargetDistrict | String | - | 目标区域 |
| transferStatus | String | - | 转办状态 |
#### ClueTransferReq 字段
| 字段 | 类型 | 说明 |
| ------------------------ | ------ | ----- |
| clueId | String | 线索ID |
| transferTargetDistrict | String | 目标区域 |
| transferTargetDepartment | String | 目标部门 |
| transferTargetPerson | String | 目标联系人 |
| transferDescription | String | 转办说明 |
#### PendingClueQuery 字段
| 字段 | 类型 | 默认值 | 说明 |
| -------- | ------- | --- | ---- |
| pageNum | Integer | 1 | 页码 |
| pageSize | Integer | 10 | 每页条数 |
| clueCode | String | - | 线索编码 |
| district | String | - | 区域 |
| keyword | String | - | 关键词 |
#### 其他 Req 字段
**TransferStatusUpdateReq**
| 字段 | 类型 | 说明 |
| ---------------- | ------ | ------ |
| transferRecordId | String | 转办记录ID |
| newStatus | String | 新状态 |
| externalClueId | String | 外部线索ID |
| disposalResult | String | 处置结果 |
| remark | String | 备注 |
**TransferUrgeReq**
| 字段 | 类型 | 说明 |
| ---------------- | ------ | ------ |
| transferRecordId | String | 转办记录ID |
| urgeMessage | String | 催办信息 |
**TransferWithdrawReq**
| 字段 | 类型 | 说明 |
| ---------------- | ------ | ------ |
| transferRecordId | String | 转办记录ID |
| withdrawReason | String | 撤回原因 |
#### ClueTransferDetailVO 额外字段
| 字段 | 类型 | 说明 |
| ------------- | ---------- | ---- |
| clueCode | String | 线索编码 |
| operationLogs | List\<Map> | 操作日志 |
#### 数据库表
主表：cw\_clue\_transfer\_record
日志表：cw\_transfer\_operation\_log
主表字段：
| DB列 | Java字段 | 类型 | 约束 |
| ---------------------------- | ------------------------ | ------------- | --------------------------------------- |
| ID | id | VARCHAR(50) | PK |
| CLUE\_ID | clueId | VARCHAR(50) | <br /> |
| TRANSFER\_TARGET\_DISTRICT | transferTargetDistrict | VARCHAR(20) | <br /> |
| TRANSFER\_TARGET\_DEPARTMENT | transferTargetDepartment | VARCHAR(100) | <br /> |
| TRANSFER\_TARGET\_PERSON | transferTargetPerson | VARCHAR(50) | <br /> |
| TRANSFER\_DESCRIPTION | transferDescription | VARCHAR(500) | <br /> |
| TRANSFER\_PERSON | transferPerson | VARCHAR(100) | <br /> |
| TRANSFERRED\_AT | transferredAt | TIMESTAMP | <br /> |
| TRANSFER\_STATUS | transferStatus | VARCHAR(20) | transferred/processing/completed/failed |
| EXTERNAL\_CLUE\_ID | externalClueId | VARCHAR(100) | <br /> |
| DISPOSAL\_RESULT | disposalResult | VARCHAR(2000) | <br /> |
| DISPOSAL\_COMPLETED\_AT | disposalCompletedAt | TIMESTAMP | <br /> |
| CREATE\_BY \~ UPDATE\_NAME | - (SuperEntity) | - | 审计字段 |
DDL：V10.0.0\_\_CW\_clue\_transfer\_ddl.sql（无 init\_data）
⚠️ **模拟数据**：targets/districts、targets/departments、targets/persons 接口当前返回模拟数据，需对接组织架构系统。
⚠️ **状态流转**：transferred → processing → completed/failed，通过 status-update 接口由外部系统回调。