docs: 添加项目指引 + 前后端联调指南 + 错题库

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Run
+
+```bash
+# 编译（开发阶段跳过 checkstyle）
+mvn compile -Dcheckstyle.skip=true
+
+# 完整编译（含 checkstyle）
+mvn compile
+
+# 打包（默认跳过测试）
+mvn clean package
+
+# 本地运行（因 ZIP layout 无法用 spring-boot:run）
+mvn dependency:build-classpath -Dmdep.outputFile=classpath.txt
+java -cp "target/classes;$(cat classpath.txt)" -Dfile.encoding=UTF-8 com.chinaweal.youfool.prj.YoufoolApplication
+```
+
+## Architecture
+
+OARMS — 广州市户外广告监管系统后端，Spring Boot 3.4.5 + JDK 21 + 达梦 DM8 数据库。
+
+### 业务域与模块
+
+5 大业务域、10 个模块，按域组织在 `modules/` 下：
+
+| 域 | 模块 | 包路径 | 表前缀 |
+|----|------|--------|--------|
+| BS 基础 | 大屏管理 | `modules/screen` | `bs_` |
+| LB 法律 | 法律法规 | `modules/law` | `lb_` |
+| MR 监测 | 监测规则 | `modules/rule` | `mr_` |
+| AM 监控 | 录屏设置/任务/画面监控 | `modules/monitor/{config,task,record}` | `am_` |
+| CW 取证 | 固化取证/规则关联/线索生成/线索转办 | `modules/evidence/{record,relation,clue,transfer}` | `cw_` |
+
+### 分层结构
+
+每个模块遵循 Controller → Service → Mapper 三层，实体包内分 `query/`、`req/`、`vo/`：
+
+```
+modules/{module}/
+├── entity/          # Entity + query/ + req/ + vo/
+├── mapper/          # extends BaseMapper<Entity>
+├── service/         # I{Entity}Service + impl/
+└── controller/
+```
+
+### 关键约定
+
+- **事务**：必须用 `@DSTransactional`，不能用 `@Transactional`（动态数据源要求）
+- **数据源**：`@DS("master")` + `@TableName(schema = "OARMS", value = "表名")`
+- **Entity**：继承 `SuperEntity`（含 createBy/createTime/createName/updateBy/updateTime/updateName，不含 id）
+- **DI**：`@AllArgsConstructor` + `private final`
+- **返回值**：`RestResult.ok(data)` / `RestResult.ok()`
+- **日志**：`log.info("[OK] 操作描述: key={}", value)`
+- **Mapper 扫描**：`com.chinaweal.youfool.prj.**.mapper`，新模块放此包下自动注册
+- **API 路径**：所有接口以 `/api/` 开头
+
+### 数据源
+
+两个数据源，通过 dynamic-datasource 切换：
+- `master`（primary）→ OARMS schema，业务数据
+- `youfool` → YOUFOOL schema，框架日志（restLog）
+
+### DM8 数据库要点
+
+- DDL/COMMENT/INDEX 中表名列名必须大写，INSERT 中列名可用小写
+- 日期字段：`@JsonFormat(pattern = DateUtil.DATE_DEFAULT_FORMAT, timezone = "GMT+8")`
+- 日期时间字段：`@JsonFormat(pattern = DateUtil.DATETIME_DEFAULT_FORMAT, timezone = "GMT+8")`
+- DDL 文件放在 `docs/db/sql/`，命名 `V{版本号}__{模块描述}_{ddl|init_data}.sql`
+
+## Development Guide
+
+详细开发指南见 `docs/backend-module-dev-guide.md`，包含 Entity/Controller/Service/Mapper/Query 模板代码和 DM8 类型映射表。

docs/fix/错题库/2026-05/2026-05-21-001-前端联调高频错误模式归纳.md

@@ -0,0 +1,106 @@
+# LE-2026-05-001 - 前端联调高频错误模式归纳（来自 gz-atms-web 项目）
+
+**日期**：2026-05-21
+**模块**：通用
+**分类**：前后端数据映射 / 接口参数 / 组件框架 / 数据库SQL
+**严重程度**：P1(严重)
+
+## 问题描述
+
+从 gz-atms-web 项目（`D:\chinaweal\gz-atms\gz-atms-web\docs\fix\错题库`）的 12 条错题中，归纳出前后端联调的 8 大高频错误模式。
+
+## 错误模式归纳
+
+### 模式 1：字段名不匹配
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 表格数据为空，prop 与后端返回的 JSON key 不一致 |
+| 根因 | 前端 prop 用中文/自定义名，后端返回 Java camelCase 字段名 |
+| 修复 | prop 必须与 API 返回的 JSON key 精确一致 |
+| 检测 | 对比前端 table column prop 与后端 VO 字段名 |
+
+### 模式 2：rowKey 不匹配
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 翻页后操作列按钮消失、DOM 状态错乱 |
+| 根因 | 默认 rowKey='id'，但后端主键字段名不同（如 marketId） |
+| 修复 | 显式设置 `row-key="实际主键名"` |
+| 检测 | 检查 Entity @TableId 的字段名，与前端 row-key 对比 |
+
+### 模式 3：分页字段名（list vs records）
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 列表数据加载不出来 |
+| 根因 | MyBatis-Plus 分页返回 `records`，前端误用 `list` |
+| 修复 | 统一使用 `res.records` |
+| 检测 | 后端返回 `Page<Entity>` 时，前端取列表数据的字段名 |
+
+### 模式 4：JSON 字符串未解析
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 调用 `.map()` 报 TypeError: xxx.map is not a function |
+| 根因 | 后端 CLOB/JSON 字段返回 String，前端当数组直接使用 |
+| 修复 | `JSON.parse(data)` 或 `Array.isArray(data) ? data : JSON.parse(data)` |
+| 检测 | 后端 Entity 中 String 类型但实际存储 JSON 的字段（如 relatedRules、scopeDistricts） |
+
+### 模式 5：数组与单对象混淆
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 访问属性报 undefined，渲染异常 |
+| 根因 | 一对多关系后端返回数组，前端当单个对象使用 |
+| 修复 | `Array.isArray(data) ? data[0] : data` |
+| 检测 | 详情接口返回类型如果是 `List<Entity>` 而非 `Entity` |
+
+### 模式 6：响应拦截器自动解包
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 取 res.data.data 报 undefined |
+| 根因 | request.js 拦截器已自动解包 `response.data`，业务代码再解包一次就多了一层 |
+| 修复 | 直接使用 `res.list`、`res.total` 等已解包字段 |
+| 检测 | 检查前端 request.js 响应拦截器的 return 逻辑 |
+
+### 模式 7：导出接口 responseType 未设 blob
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 文件下载报"业务出错"或下载文件损坏 |
+| 根因 | 未设置 `responseType: 'blob'`，二进制数据被当文本处理 |
+| 修复 | 请求配置中添加 `responseType: 'blob'` |
+| 检测 | 所有文件下载接口的前端请求配置 |
+
+### 模式 8：排序字段驼峰未转下划线
+
+| 维度 | 说明 |
+|------|------|
+| 表现 | 达梦数据库报错"列名无效" |
+| 根因 | 前端传驼峰字段名，后端直接拼 SQL，DM8 要求大写下划线列名 |
+| 修复 | 后端排序字段先转下划线再拼 SQL，或前端直接传下划线格式 |
+| 检测 | 后端 QueryWrapper orderBy 使用了 camelCase 字段名的位置 |
+
+## AI 检测规则
+
+```
+CHECK: 对 OARMS 项目进行以下 8 项自动检测
+RULE:
+  1. 前端 table column prop == 后端 VO/Entity 字段名
+  2. 前端 row-key == 后端 @TableId 字段名
+  3. 前端分页取数据字段 == "records"（非 "list"）
+  4. 后端 CLOB/String 字段（relatedRules, scopeDistricts 等）前端有 JSON.parse
+  5. 详情接口返回数组时前端有 Array.isArray 判断
+  6. 前端 request.js 拦截器解包逻辑与业务代码一致
+  7. 文件下载接口前端有 responseType:'blob'
+  8. 后端排序字段名已转下划线
+FAIL: 任一规则不满足 → 报告具体位置和修复建议
+```
+
+## 参考
+
+原始错题来源：`D:\chinaweal\gz-atms\gz-atms-web\docs\fix\错题库\`
+- 2026-01: 3 条（方法调用错误、拦截器解包、路径错误）
+- 2026-05: 9 条（字段映射、分页、JSON解析、导出、排序等）

docs/fix/错题集索引.md

@@ -0,0 +1,72 @@
+# OARMS 错题集索引
+
+> 前后端联调过程中发现的问题记录，按分类汇总。每条错题对应 `错题库/` 下的一个详细文件。
+
+## 索引
+
+### 按分类
+
+#### 前后端数据映射
+
+| 编号 | 日期 | 标题 | 模块 |
+|------|------|------|------|
+| LE-2026-05-001 | 2026-05-21 | [前端联调高频错误模式归纳（8大模式）](错题库/2026-05/2026-05-21-001-前端联调高频错误模式归纳.md) | 通用 |
+
+#### 接口参数/返回值
+
+| 编号 | 日期 | 标题 | 模块 |
+|------|------|------|------|
+| （暂无） | | | |
+
+#### 组件/框架问题
+
+| 编号 | 日期 | 标题 | 模块 |
+|------|------|------|------|
+| （暂无） | | | |
+
+#### 数据库/SQL
+
+| 编号 | 日期 | 标题 | 模块 |
+|------|------|------|------|
+| （暂无） | | | |
+
+---
+
+## 错题编写模板
+
+新增错题时复制以下模板，保存为 `错题库/YYYY-MM/YYYY-MM-DD-NNN-简述.md`：
+
+```markdown
+# 编号 - 标题
+
+**日期**：YYYY-MM-DD
+**模块**：BS-1 / LB-1 / MR-1 / AM-1~3 / CW-1~4 / 通用
+**分类**：前后端数据映射 / 接口参数 / 组件框架 / 数据库SQL
+**严重程度**：P0(阻塞) / P1(严重) / P2(一般) / P3(建议)
+
+## 问题描述
+
+（具体的现象和复现步骤）
+
+## 根因分析
+
+（问题的根本原因）
+
+## 解决方案
+
+（修复方法和代码变更）
+
+## AI 检测规则
+
+（AI 可执行的检测逻辑，用于自动发现同类问题）
+
+```
+CHECK:
+RULE:
+FAIL:
+```
+```
+
+## 参考
+
+错题模式参考 gz-atms-web 项目的错题库：`D:\chinaweal\gz-atms\gz-atms-web\docs\fix\错题库\`

docs/前后端联调指南.md

@@ -0,0 +1,758 @@
+# 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 接口由外部系统回调。