# 外部接口：同步案件信息

## 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 独立判断是否还有下一页，不要只看某一个列表是否为空