diff --git a/zdxt-modules/zdxt-enforcement-code/docs/龙岗外部接口-获取案件信息.md b/zdxt-modules/zdxt-enforcement-code/docs/龙岗外部接口-获取案件信息.md new file mode 100644 index 00000000..d0f04e79 --- /dev/null +++ b/zdxt-modules/zdxt-enforcement-code/docs/龙岗外部接口-获取案件信息.md @@ -0,0 +1,339 @@ +# 外部接口:同步案件信息 + +## 1. 基本信息 + +| 项 | 说明 | +|---|---| +| 接口名称 | 同步案件信息(行政检查 / 行政处罚 / 行政强制) | +| 用途 | 供外部系统全量/按日增量同步案件数据 | +| 请求方式 | `POST` | +| 路径 | `/external/api/lg/case/sync` | +| Content-Type | `application/json` | +| 鉴权 | 请求头 `App-Key`(渠道密钥) | + +--- + +## 2. 请求头 + +| 参数名 | 必填 | 说明 | +|---|---|---| +| `App-Key` | 是 | 调用方渠道密钥;缺失/无效会直接失败 | + +--- + +## 3. 请求体 + +### 首次全量同步 + +```json +{ + "pageNum": 1, + "pageSize": 100 +} +``` + +### 按日增量同步 + +```json +{ + "syncDate": "2026-09-16", + "pageNum": 1, + "pageSize": 100 +} +``` + +| 字段 | 类型 | 必填 | 默认值 | 说明 | +|---|---|---|---|---| +| `syncDate` | String(yyyy-MM-dd) | 否 | 空 | 为空=全量;有值=只返回该自然日数据 | +| `pageNum` | Integer | 否 | `1` | 页码,从 1 开始 | +| `pageSize` | Integer | 否 | `100` | 每页条数;三类主表各自按此分页,上限 `500` | + +--- + +## 4. 同步规则 + +| 场景 | 入参 | 行为 | +|---|---|---| +| 首次同步 | 不传 `syncDate` | 返回全部案件(分页拉取) | +| 日常增量 | 传当天 `syncDate` | 只返回该自然日数据 | + +按日过滤字段: + +| 类型 | 过滤字段 | 说明 | +|---|---|---| +| 行政检查 | `inspectionDate` | 检查日期落在当天 | +| 行政处罚 | `cdTime` | 最后变更时间落在当天 | +| 行政强制 | `cdTime` | 最后变更时间落在当天 | + +分页说明: + +- `pageNum` / `pageSize` 对三类主表**同时生效、各自独立计数** +- 响应里分别返回 `xzjcTotal` / `xzcfTotal` / `xzqzTotal` +- 对方应继续翻页,直到三类数据都拉完(当前页三类列表都为空,或页码已超过各自总页数) + +数据组装: + +| 类型 | 主表 | 明细 | 当事人 | 关联键 | +|---|---|---|---|---| +| 行政检查 | `sxt_jcdzb107522` | `items` ← `sxt_xzjcjcxxx050280` | `parties` ← `sxt_xzjcdsrxx016987` | `sign_id` = `c601000` | +| 行政处罚 | `sxt_xzcfajjbxx026705` | `decisions` ← `sxt_xzcfajjdxx778518` | `parties` ← `sxt_xzcfajdsrxx594019` | `c201000` | +| 行政强制 | `sxt_xzqzjbxx173774` | `measures` ← `sxt_xzqzcsxx274939` | `parties` ← `sxt_xzqzdsrxx997874` | `c301000` | + +--- + +## 5. 响应结构 + +统一包装 `R`: + +| 字段 | 类型 | 说明 | +|---|---|---| +| `code` | int | `200` 成功,非 `200` 失败 | +| `msg` | String | 提示信息 | +| `data` | Object | 同步结果 | + +### 5.1 `data`(`LongGangCaseSyncVo`) + +| 字段 | 类型 | 说明 | +|---|---|---| +| `pageNum` | Integer | 当前页 | +| `pageSize` | Integer | 每页条数 | +| `xzjcList` | Array | 行政检查列表 | +| `xzjcTotal` | Long | 行政检查主表总条数 | +| `xzcfList` | Array | 行政处罚列表 | +| `xzcfTotal` | Long | 行政处罚主表总条数 | +| `xzqzList` | Array | 行政强制列表 | +| `xzqzTotal` | Long | 行政强制主表总条数 | + +### 5.2 `xzjcList[]` 行政检查包 + +| 字段 | 类型 | 对应表 | 说明 | +|---|---|---|---| +| `master` | Object | `sxt_jcdzb107522` | 检查单主表 | +| `items` | Array | `sxt_xzjcjcxxx050280` | 行政检查项 | +| `parties` | Array | `sxt_xzjcdsrxx016987` | 当事人 | + +**`master` 常用字段** + +| 字段 | 说明 | +|---|---| +| `signId` | 业务主键(关联检查项/当事人) | +| `caseCode` | 案件编号 | +| `inspActionName` | 检查行为名称 | +| `subName` | 行政执法主体名称 | +| `inspectionNumber` | 检查单号 | +| `inspectionDate` | 检查日期 | +| `inspectionAddr` | 检查地点 | +| `isInspectionPass` | 检查结果 | +| `inspDecision` | 检查决定 | + +**`items[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c602000` | 检查项主键 | +| `c601000` | 关联主表 `signId` | +| `c601004` | 检查单号 | +| `c602001` | 检查事项名称 | +| `c602002` | 检查项 | +| `c602003` | 检查结果 | + +**`parties[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c604001` | 当事人主键 | +| `c601000` | 关联主表 `signId` | +| `c601031` | 当事人类型 | +| `c601032` | 当事人名称 | +| `c601033` | 证件类型 | +| `c601034` | 证件号码 | +| `c601035` | 法定代表人 | + +### 5.3 `xzcfList[]` 行政处罚包 + +| 字段 | 类型 | 对应表 | 说明 | +|---|---|---|---| +| `master` | Object | `sxt_xzcfajjbxx026705` | 案件基本信息 | +| `decisions` | Array | `sxt_xzcfajjdxx778518` | 决定信息 | +| `parties` | Array | `sxt_xzcfajdsrxx594019` | 当事人 | + +**`master` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c201000` | 业务主键 | +| `c201001` | 案件编号 | +| `c201002` | 案件名称 | +| `f101001` | 处罚事项名称 | +| `c201003` | 执法主体名称 | +| `cdTime` | 最后变更时间 | + +**`decisions[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c206000` | 决定主键 | +| `c201000` | 关联主表 | +| `c206001` | 是否涉刑案件 | +| `c206002` | 是否重大案件 | +| `c206007` | 违法事实 | +| `c206008` | 违法依据 | +| `c206009` | 处罚依据 | + +**`parties[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c209001` | 当事人主键 | +| `c201000` | 关联主表 | +| `c206000` | 关联决定(可空) | +| `c201013` | 当事人类型 | +| `c201014` | 当事人名称 | +| `c201016` | 证件号码 | + +### 5.4 `xzqzList[]` 行政强制包 + +| 字段 | 类型 | 对应表 | 说明 | +|---|---|---|---| +| `master` | Object | `sxt_xzqzjbxx173774` | 基本信息 | +| `measures` | Array | `sxt_xzqzcsxx274939` | 措施信息 | +| `parties` | Array | `sxt_xzqzdsrxx997874` | 当事人 | + +**`master` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c301000` | 业务主键 | +| `c301001` | 案件来源 | +| `c301002` | 案件名称 | +| `c301003` | 案件编号 | +| `f101001` | 行政强制事项名称 | +| `c301004` | 执法主体名称 | +| `cdTime` | 最后变更时间 | + +**`measures[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c302000` | 措施主键 | +| `c301000` | 关联主表 | +| `c302001` | 措施名称 | +| `c302002` | 措施种类 | +| `c302004` | 措施详情 | + +**`parties[]` 常用字段** + +| 字段 | 说明 | +|---|---| +| `c304001` | 当事人主键 | +| `c301000` | 关联主表 | +| `c301007` | 当事人类型 | +| `c301008` | 当事人名称 | +| `c301010` | 证件号码 | + +> 上表只列对接常用字段;完整字段以对应 Vo 类为准。 + +--- + +## 6. 响应示例 + +### 成功 + +```json +{ + "code": 200, + "msg": "操作成功", + "data": { + "pageNum": 1, + "pageSize": 100, + "xzjcTotal": 230, + "xzcfTotal": 56, + "xzqzTotal": 12, + "xzjcList": [ + { + "master": { + "signId": "JC20250001", + "caseCode": "JC-2025-0001", + "inspActionName": "日常检查", + "subName": "某某局", + "inspectionNumber": "JCD20250001", + "inspectionDate": "2025-08-01" + }, + "items": [ + { + "c602000": "ITEM001", + "c601000": "JC20250001", + "c602001": "食品安全检查", + "c602003": "合格" + } + ], + "parties": [ + { + "c604001": "DSR001", + "c601000": "JC20250001", + "c601032": "某某科技有限公司", + "c601034": "91440300XXXXXXXXXX" + } + ] + } + ], + "xzcfList": [], + "xzqzList": [] + } +} +``` + +### 失败 + +```json +{ + "code": 500, + "msg": "缺少请求头: App-Key", + "data": null +} +``` + +常见失败原因: + +- 缺少请求头 `App-Key` +- 无效的 `appKey` +- 渠道未配置 `channelNo` + +--- + +## 7. 调用示例(curl) + +### 全量第一页 + +```bash +curl -X POST 'https://{host}/external/api/lg/case/sync' \ + -H 'Content-Type: application/json' \ + -H 'App-Key: {your-app-key}' \ + -d '{ + "pageNum": 1, + "pageSize": 100 + }' +``` + +### 增量(当天) + +```bash +curl -X POST 'https://{host}/external/api/lg/case/sync' \ + -H 'Content-Type: application/json' \ + -H 'App-Key: {your-app-key}' \ + -d '{ + "syncDate": "2026-09-16", + "pageNum": 1, + "pageSize": 100 + }' +``` + +--- + +## 8. 对接建议 + +1. 首次:不带 `syncDate`,从 `pageNum=1` 开始翻页,直到三类都拉完 +2. 之后:每天带当天 `syncDate` 增量拉取 +3. 落库幂等键:检查用 `signId`,处罚用 `c201000`,强制用 `c301000` +4. 明细/当事人建议按主表关联键先删后插,或按各自主键 upsert +5. 三类 total 独立判断是否还有下一页,不要只看某一个列表是否为空