1 changed files with 339 additions and 0 deletions
@ -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<T>`： |
|||
|
|||
| 字段 | 类型 | 说明 | |
|||
|---|---|---| |
|||
| `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 独立判断是否还有下一页，不要只看某一个列表是否为空 |
|||
Loading…
Reference in new issue