gz-oarms/docs/前后端联调指南.md

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)
OPERATOR_UNIT	operatorUnit	VARCHAR(100)	NOT NULL
OPERATOR_CONTACT	operatorContact	VARCHAR(20)
ADVERTISER	advertiser	VARCHAR(100)
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)
LATITUDE	latitude	DECIMAL(10,6)
CREATE_BY	- (SuperEntity)	VARCHAR(50)
CREATE_TIME	- (SuperEntity)	TIMESTAMP
CREATE_NAME	- (SuperEntity)	VARCHAR(50)
UPDATE_BY	- (SuperEntity)	VARCHAR(50)
UPDATE_TIME	- (SuperEntity)	TIMESTAMP
UPDATE_NAME	- (SuperEntity)	VARCHAR(50)

关联表：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)
EFFECTIVE_STATUS	effectiveStatus	TINYINT	NOT NULL, 默认1, 1=有效,2=废止
PUBLISH_DATE	publishDate	DATE
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)
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)
SCREEN_ADDRESS	screenAddress	VARCHAR(500)
DISTRICT	district	VARCHAR(50)
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)
CONFIG_ID	configId	VARCHAR(50)
ACTUAL_START_TIME	actualStartTime	TIMESTAMP
ACTUAL_END_TIME	actualEndTime	TIMESTAMP
TASK_STATUS	taskStatus	TINYINT	1=录屏中,2=已完成,3=失败
VIDEO_FILE_PATH	videoFilePath	VARCHAR(500)
RETRY_COUNT	retryCount	INT
ERROR_MESSAGE	errorMessage	VARCHAR(500)
CREATE_BY ~ UPDATE_NAME	- (SuperEntity)	-	审计字段

关联表：am_alert_notification（告警通知）

DB列	Java字段	类型	约束
ID	id	VARCHAR(50)	PK
TASK_ID	taskId	VARCHAR(50)
SCREEN_ID	screenId	VARCHAR(50)
ALERT_TYPE	alertType	TINYINT	1=录屏失败,2=录屏超时,3=设备离线
ALERT_MESSAGE	alertMessage	VARCHAR(500)
IS_RESOLVED	isResolved	TINYINT	0=未处理,1=已处理
RESOLVED_BY	resolvedBy	VARCHAR(100)
RESOLVED_AT	resolvedAt	TIMESTAMP
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)
SCREEN_ID	screenId	VARCHAR(50)
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)
MONITOR_PERSON	monitorPerson	VARCHAR(100)
MONITORED_AT	monitoredAt	TIMESTAMP
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)
RULE_ID	ruleId	VARCHAR(50)
ASSOCIATED_BY	associatedBy	VARCHAR(50)
ASSOCIATED_AT	associatedAt	TIMESTAMP

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)
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)
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)
GENERATED_AT	generatedAt	TIMESTAMP
TRANSFERRED_AT	transferredAt	TIMESTAMP
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)
TRANSFER_TARGET_DISTRICT	transferTargetDistrict	VARCHAR(20)
TRANSFER_TARGET_DEPARTMENT	transferTargetDepartment	VARCHAR(100)
TRANSFER_TARGET_PERSON	transferTargetPerson	VARCHAR(50)
TRANSFER_DESCRIPTION	transferDescription	VARCHAR(500)
TRANSFER_PERSON	transferPerson	VARCHAR(100)
TRANSFERRED_AT	transferredAt	TIMESTAMP
TRANSFER_STATUS	transferStatus	VARCHAR(20)	transferred/processing/completed/failed
EXTERNAL_CLUE_ID	externalClueId	VARCHAR(100)
DISPOSAL_RESULT	disposalResult	VARCHAR(2000)
DISPOSAL_COMPLETED_AT	disposalCompletedAt	TIMESTAMP
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 接口由外部系统回调。