# api/common

> 统一响应格式：`{"code": 1, "message": "success", "data": ...}`，下文「响应参数」均指 `data` 字段。

## 接口总览

| # | 方法 | 路径 | 说明 | 认证 |
|---|---|---|---|---|
| 1 | GET | `/api/common/send` | 发送短信 | 否 |
| 2 | GET | `/api/common/idCard` | 身份证OCR识别 | 否 |
| 3 | GET | `/api/common/business_license` | 营业执照OCR识别 | 否 |
| 4 | GET | `/api/common/bankcard` | 银行卡OCR识别 | 否 |
| 5 | GET | `/api/common/oss_sts` | 获取 OSS STS 临时凭证（供前端直传） | 否 |
| 6 | POST | `/api/common/upload_oss` | 上传本地文件到 OSS | 否 |
| 7 | GET | `/api/common/js` | 获取微信 JS-SDK 签名信息 | 否 |

---

## 接口详情

### 1. GET `/api/common/send`

- **说明**: 发送短信
- **认证**: 否
- **Handler**: `api.CommonController{}.SendSms`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `phone` | string | 是 | 手机号 | len=11 |
| `send_type` | string | 是 | 发送类型 | - |

**响应参数**

`string`（示例: `发送成功`）

---

### 2. GET `/api/common/idCard`

- **说明**: 身份证OCR识别
- **认证**: 否
- **Handler**: `api.CommonController{}.IdCardOcr`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `img_url` | string | 是 | 身份证图片地址 | url |
| `side` | string | 是 | 身份证正反面 | oneof=front back |

**响应参数**

object，类型 `ocr.IDCardData`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `name` | string | 姓名 |
| `id_number` | string | 公民身份号码 |
| `sex` | string | 性别 |
| `nation` | string | 民族 |
| `birth` | string | 出生日期 |
| `address` | string | 住址 |
| `issuing_auth` | string | 签发机关 |
| `issue_date` | string | 签发日期（反面） |
| `valid_date` | string | 有效期限（反面） |

---

### 3. GET `/api/common/business_license`

- **说明**: 营业执照OCR识别
- **认证**: 否
- **Handler**: `api.CommonController{}.BusinessLicenseOcr`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `img_url` | string | 是 | 图片地址 | url |

**响应参数**

object，类型 `ocr.BusinessLicenseData`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `credit_code` | string | 统一社会信用代码 |
| `name` | string | 单位名称 |
| `legal_person` | string | 法人 |
| `registration_no` | string | 证件编号 |
| `registered_capital` | string | 注册资本 |
| `paid_in_capital` | string | 实收资本 |
| `establish_date` | string | 成立日期 |
| `valid_period` | string | 有效期 |
| `valid_from` | string | 有效期起始日期 |
| `approval_date` | string | 核准日期 |
| `address` | string | 地址 |
| `business_scope` | string | 经营范围 |
| `company_type` | string | 类型 |
| `organization_form` | string | 组成形式 |
| `registration_authority` | string | 登记机关 |
| `tax_registration_no` | string | 税务登记号 |

---

### 4. GET `/api/common/bankcard`

- **说明**: 银行卡OCR识别
- **认证**: 否
- **Handler**: `api.CommonController{}.BankCardOcr`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `img_url` | string | 是 | 图片地址 | url |

**响应参数**

object，类型 `ocr.BankCardData`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `card_number` | string | 银行卡号（已去除空格） |
| `bank_name` | string | 银行名称 |

---

### 5. GET `/api/common/oss_sts`

- **说明**: 获取 OSS STS 临时凭证（供前端直传）
- **认证**: 否
- **Handler**: `api.CommonController{}.OssSts`

**请求参数**: 无

**响应参数**

object，类型 `service.StsTokenData`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `access_key_id` | string | AccessKeyID |
| `access_key_secret` | string | AccessKeySecret |
| `security_token` | string | SecurityToken |
| `expiration` | int | Expiration |
| `region` | string | Region |
| `bucket` | string | Bucket |
| `endpoint` | string | Endpoint |

---

### 6. POST `/api/common/upload_oss`

- **说明**: 上传本地文件到 OSS
- **认证**: 否
- **Handler**: `api.CommonController{}.UploadOssFile`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `local_path` | string | 是 | 本地文件路径 | - |
| `oss_key` | string | 是 | OSS文件路径 | - |

**响应参数**

`string`

---

### 7. GET `/api/common/js`

- **说明**: 获取微信 JS-SDK 签名信息
- **认证**: 否
- **Handler**: `api.CommonController{}.WechatJsConfig`

**请求参数**

| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| `url` | string | 否 | 当前页面地址 | - |

**响应参数**

object，类型 `service.WechatJsConfigResp`：

| 字段 | 类型 | 说明 |
|---|---|---|
| `appid` | string | AppID |
| `noncestr` | string | NonceStr |
| `timestamp` | int | Timestamp |
| `url` | string | URL |
| `signature` | string | Signature |

---