# 第三方店铺同步接口文档

> 版本：V1.0  
> 更新日期：2026-07-11  
> 说明：第三方（如省药监平台）将药店入驻信息同步到我方系统，自动创建/更新用户及入驻记录

---

## 1. 概述

本接口用于第三方系统向我方同步药店入驻信息。按手机号自动匹配用户，用户不存在则自动创建，并同步入驻信息到 `t_business_license`。

| 项目 | 说明 |
|------|------|
| **接口名称** | 第三方店铺信息同步 |
| **请求方式** | `POST` |
| **接口路径** | `/api/sync_shop_resource/report_user` |
| **鉴权** | **无鉴权**（白名单路径，对第三方开放） |
| **Content-Type** | `application/json` |

---

## 2. 请求参数

所有参数通过 **JSON Body** 传递，字段名使用 **snake_case** 格式。

### 2.1 必填字段

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `phone` | String | 是 | 手机号码（用于识别客户唯一身份） |

### 2.2 用户/药店信息字段（全部可选）

| 参数名 | 类型 | 必填 | 说明 | 映射我方字段 |
|--------|------|------|------|--------------|
| `contact_name` | String | 否 | 联系人名称 | `nickname`, `contact_person` |
| `contact_phone` | String | 否 | 联系电话 | `contact_phone` |
| `contact_shop` | String | 否 | 店铺名称 | `pharmacy_name`, `store_name` |
| `contact_province` | String | 否 | 省份 | `province` |
| `contact_city` | String | 否 | 城市 | `city` |
| `contact_area` | String | 否 | 地区 | `district` |
| `contact_addr` | String | 否 | 详细地址 | `pharmacy_address`, `store_address` |

### 2.3 店铺类型

| 参数名 | 类型 | 必填 | 说明 | 映射值 |
|--------|------|------|------|--------|
| `shop_type` | String | 否 | 店铺类型 | `1`→SINGLE 单店 / `2`→CHAIN 连锁 / `3`→CLINIC 诊所、社康 |

### 2.4 证照图片字段（全部可选）

| 参数名 | 类型 | 必填 | 说明 | 映射我方字段 |
|--------|------|------|------|--------------|
| `business_license_image` | String | 否 | 营业执照图片URL | `license_image_url` |
| `drug_business_license_image` | String | 否 | 药品经营许可证图片URL | `drug_license_url` |
| `two_medical_device_registration` | String | 否 | 二类医疗器械备案图片URL | `medical_device_class2_url` |
| `three_medical_device_business_license` | String | 否 | 三类医疗器械经营许可图片URL | `medical_device_class3_url` |

### 2.5 审核与操作字段

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `status` | String | 否 | 审核状态：`0`=审核中 / `1`=审核成功 / `2`=审核失败（不传默认`0`） |
| `remarks` | String | 否 | 备注信息（如拒绝原因等） |
| `operator_userid` | String | 否 | 操作人用户ID（默认`0`） |
| `user_type` | String | 否 | 用户类型：`1`=客户端用户 / `2`=后台用户 |
| `app_id` | String | 否 | 小程序APPID |

---

## 3. 请求示例

```json
{
  "phone": "13800138000",
  "contact_name": "张老三",
  "contact_shop": "好店铺",
  "shop_type": "1",
  "contact_province": "广东省",
  "contact_city": "深圳市",
  "contact_area": "龙华新区",
  "contact_addr": "上芬街道",
  "contact_phone": "18219207546",
  "business_license_image": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "drug_business_license_image": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "two_medical_device_registration": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "three_medical_device_business_license": "https://kailin-saas.oss-cn-shenzhen.aliyuncs.com/uploads/process/2026/07/ch8K4VULklSVWYEYolVPTxvURA7fJlDsnzpHRZno.png",
  "status": "0",
  "remarks": "资料不全，缺少药品经营许可证",
  "operator_userid": "0",
  "user_type": "1",
  "app_id": "wx246605ec671bf08d"
}
```

---

## 4. 响应

### 4.1 通用响应格式

```json
{
  "code": "success",
  "msg": "同步成功",
  "data": {
    "user_id": "1234567890123456789",
    "new_user": false
  }
}
```

### 4.2 响应字段

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | String | `"success"` 成功 / `"error"` 失败 |
| `msg` | String | 提示信息 |
| `data.user_id` | String | 我方系统中的用户ID |
| `data.new_user` | Boolean | 是否为新创建的用户 |

### 4.3 错误响应

```json
{
  "code": "error",
  "msg": "手机号不能为空"
}
```

---

## 5. 业务逻辑

### 5.1 用户处理

| 场景 | 行为 |
|------|------|
| 手机号**不存在** | 自动创建新用户（PLUS 会员），昵称用 contactName |
| 手机号**已存在** | 更新非空的用户信息字段 |

### 5.2 入驻信息处理

> 💡 **核心原则：以第三方传入的最新数据为准**，非空字段直接覆盖本地记录。

| 场景 | 行为 |
|------|------|
| 无入驻记录 | 创建新记录，写入全部证照和店铺信息 |
| 已有入驻记录（非 APPROVED） | 以第三方传入字段覆盖本地，同时更新审核状态 |
| 已有入驻记录（已 APPROVED） | 以第三方传入字段覆盖本地，重置为 PENDING 待重新审核；奖励标记保留，不重复发放 |

### 5.3 审核状态

| status 值 | 我方状态 | 说明 |
|-----------|----------|------|
| `0` 或不传 | `PENDING` | 待运营审核 |
| `1` | `APPROVED` | 审核通过，**首次通过赠送 30 天 PRO 高级会员** |
| `2` | `REJECTED` | 审核失败 |

> 💡 已 APPROVED 的记录再次同步时，更新入驻字段并重置为 PENDING 待重新审核；奖励仅首次发放，不会重复。

### 5.4 shopType 映射

| 第三方值 | 我方 terminalType |
|----------|-------------------|
| `"1"` | `SINGLE`（单店） |
| `"2"` | `CHAIN`（连锁） |
| `"3"` | `CLINIC`（诊所、社康） |
| 其他 | 原值透传 |

---

## 6. 字段映射表

### 6.1 用户信息（t_users）

| 第三方字段 | 我方字段 | 说明 |
|------------|----------|------|
| `phone` | `phone` | 手机号（唯一标识） |
| `contact_name` | `nickname` | 用户昵称 |
| `contact_shop` | `pharmacy_name` | 药店名称 |
| `contact_province` | `province` | 省 |
| `contact_city` | `city` | 市 |
| `contact_area` | `district` | 区 |
| `contact_addr` | `pharmacy_address` | 详细地址 |
| `contact_phone` | `contact_phone` | 联系电话 |

### 6.2 入驻信息（t_business_license）

| 第三方字段 | 我方字段 | 说明 |
|------------|----------|------|
| `contact_shop` | `store_name` | 店铺名称 |
| `shop_type` | `terminal_type` | 终端类型（`1`→SINGLE / `2`→CHAIN / `3`→CLINIC） |
| `contact_province` | `province` | 省 |
| `contact_city` | `city` | 市 |
| `contact_area` | `district` | 区 |
| `contact_addr` | `store_address` | 详细地址 |
| `contact_name` | `contact_person` | 联系人 |
| `contact_phone` | `contact_phone` | 联系电话 |
| `business_license_image` | `license_image_url` | 营业执照图片URL |
| `drug_business_license_image` | `drug_license_url` | 药品经营许可证图片URL |
| `two_medical_device_registration` | `medical_device_class2_url` | 二类医疗器械备案图片URL |
| `three_medical_device_business_license` | `medical_device_class3_url` | 三类医疗器械备案图片URL |
| `status` | `review_status` | 审核状态（`0`→PENDING / `1`→APPROVED / `2`→REJECTED） |
| `remarks` | `remark` | 备注（如拒绝原因等） |

> 💡 入驻记录保存时，自动补充以下字段：
> - `sync_source` ← 固定为 `MINIAPP_SYNC`
> - `show_verified_badge` ← 首次审核通过时设为 `true`
> - `credit_code` ← 本次不自动填入（第三方可通过 `/external/sync` 接口传入 `businessLicenseNo` 补充）

---

## 7. 注意事项

| # | 说明 |
|---|------|
| 1 | 本接口**无鉴权**，直接对第三方开放，路径已加入白名单 |
| 2 | 请求参数通过 JSON Body 传递，字段名使用 snake_case 格式 |
| 3 | 手机号未注册时自动创建用户，初始化 PLUS 会员 |
| 4 | 不返回 Token，仅返回同步确认（user_id + new_user） |
| 5 | 如需返回 Token，请调用登录接口 `/api/auth/external/miniapp-token` |
| 6 | 建议第三方在店铺信息变更时主动调用本接口更新 |
| 7 | 状态字段为字符串类型（`"0"`/`"1"`/`"2"`），内部自动转为 Integer |

---

## 8. 变更记录

| 版本 | 日期 | 变更内容 |
|------|------|----------|
| V1.1 | 2026-07-15 | 新增 `remarks` 字段，支持双向传递拒绝原因等备注信息 |
| V1.0 | 2026-07-11 | 初始版本，支持第三方通过 Query 参数同步店铺信息 |