# Refashion UIN 证书生成接口文档

## 接口地址

**POST** `/fr_epr_reg/api/epr/generate-refashion-uin-certificate`

服务器地址：`http://automation.usaeu.com:8888/`

完整地址：`http://automation.usaeu.com:8888/fr_epr_reg/api/epr/generate-refashion-uin-certificate`

## 功能说明

生成 **Refashion（法国纺织法）UIN 证书**：接收公司证书数据（英文名、注册国、
营业执照号、UIN 号、中文名），基于 `storage/Refashion_UIN_Template.docx` 模板
填充 5 个文本占位符（其中 `{{NameEng}}` 出现两次），转换为 PDF 后上传到
腾讯云 COS，返回 PDF 访问地址。

与 `generate-refashion-poa` 的区别：

- **数据全部由接口直接传参**（非源库查询）——下号当天日期（`{{CurrentDay}}`）
  除外，该日期由服务端使用当天日期（`Y.m.d`，如 `2026.04.24`），不从接口传值；
- 文件名使用**公司中文名称**：`法国纺织UIN证书-{CompanyCnName}.pdf`；
- 无签名图片、无客户经理通知。

COS 配置与其他接口一致（复用 `tencent_oss` 磁盘与 `OSS_*` 环境变量），
仅目录前缀独立：`refashion_uin/`。

## 访问控制

接口受 `internal.network` 中间件保护，仅允许内网（172.16.x.x 子网）请求访问，非内网请求返回 401。

> **注意**：IP 限制默认开启（生产环境，由 `INTERNAL_NETWORK_ENFORCE` 控制，默认 `true`）。本地开发机不在 172.16 子网时，可在 `.env` 设置 `INTERNAL_NETWORK_ENFORCE=false` 临时关闭。

## 请求

### Content-Type

`application/json`

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| NameEng | string | 是 | 公司英文名称（模板 `{{NameEng}}` 出现两次），最长 255 字符 |
| CountryReg | string | 是 | 公司注册国（模板 `{{CountryReg}}`），最长 255 字符 |
| BusinessLicenseNo | string | 是 | 营业执照号（模板 `{{BusinessLicenseNo}}`），最长 255 字符 |
| UIN | string | 是 | UIN 号（模板 `{{UIN}}`），最长 255 字符 |
| CompanyCnName | string | 是 | 公司中文名称，仅用于文件名 `法国纺织UIN证书-{CompanyCnName}.pdf`，最长 255 字符 |

所有参数均为必填且不能为空，任一缺失或为空返回 400。

### 请求示例

```json
{
    "NameEng": "Acme France SARL",
    "CountryReg": "France",
    "BusinessLicenseNo": "FR123456789",
    "UIN": "FR-ABC-123",
    "CompanyCnName": "测试公司"
}
```

## 响应

### 成功响应（200）

```json
{
    "code": 200,
    "msg": "Refashion UIN certificate generated successfully",
    "data": {
        "pdf_url": "https://vat-1259285998.cos.ap-guangzhou.myqcloud.com/refashion_uin/Acme France SARL/6a4ca7840d26c/法国纺织UIN证书-测试公司.pdf"
    }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码，200 表示成功 |
| msg | string | 响应消息 |
| data.pdf_url | string | 生成的 UIN 证书 PDF 文件腾讯云 COS 访问地址 |

### 参数校验失败（400）

```json
{
    "code": 400,
    "msg": "UIN is required",
    "data": null
}
```

### 业务错误（400）

模板缺失 / DOCX 生成失败 / PDF 转换失败 / OSS 上传失败（如 `{{CurrentDay}}` 外的
占位符未替换、COS 凭证错误、网络异常）：

```json
{
    "code": 400,
    "msg": "Refashion UIN certificate template not found: E:/ou/meiou-app/fr_epr/fr_epr_reg/storage/Refashion_UIN_Template.docx",
    "data": null
}
```

```json
{
    "code": 400,
    "msg": "Refashion UIN certificate upload to OSS failed: ...",
    "data": null
}
```

### 非内网访问（401）

```json
{
    "code": 401,
    "msg": "Unauthorized: internal network only",
    "data": null
}
```

## 生成细节

### 模板占位符

模板：`storage/Refashion_UIN_Template.docx`。5 个占位符，6 处使用，全部为纯文本替换（无图片）：

| 占位符 | 使用次数 | 来源 |
|--------|----------|------|
| `{{NameEng}}` | 2 | 接口参数 NameEng（公司英文名称） |
| `{{CountryReg}}` | 1 | 接口参数 CountryReg（公司注册国） |
| `{{BusinessLicenseNo}}` | 1 | 接口参数 BusinessLicenseNo（营业执照号） |
| `{{UIN}}` | 1 | 接口参数 UIN（UIN 号） |
| `{{CurrentDay}}` | 1 | `date('Y.m.d')`（下号当天日期，如 `2026.04.24`，不从接口传值） |

### 生成流程

接口参数校验（`GenerateRefashionUinCertificateRequest`，5 个参数必填非空） ->
`WordTemplateProcessor` 生成 DOCX（纯文本占位符替换） ->
`PdfConverter::convertDocxToPdf($path, false)`（保留全部页，同 Refashion POA） ->
`OssUploader` 上传 COS `refashion_uin/` 目录 ->
返回 `{pdf_url}`。

### 文件名与 COS 路径

文件名：`法国纺织UIN证书-{FileNameSanitizer::sanitize(CompanyCnName)}.pdf`，
公司名（中/英文）经 `FileNameSanitizer` 净化（移除 `\ / : * ? " ' < > | # %`）。
COS 路径：`refashion_uin/{净化后NameEng}/{uniqid}/法国纺织UIN证书-{净化后CompanyCnName}.pdf`，
以 `{uniqid}` 隔离同名公司多次生成，避免覆盖。
返回的 `pdf_url` 中文件名已解码为可读形式（中文、`&`、空格以原始字符出现），
调用方**不要**再对 URL 做 urldecode（否则 `+` 会被误转为空格）。

## 日志

日志通道 `api_refashion_uin`，文件 `storage/logs/api/refashion-uin-YYYY-MM-DD.log`（每日轮转，30 天保留，`LOG_API_DAYS` 环境变量）。

## cURL 调用示例

```bash
curl -X POST \
  http://automation.usaeu.com:8888/fr_epr_reg/api/epr/generate-refashion-uin-certificate \
  -H 'Content-Type: application/json' \
  -d '{
    "NameEng": "Acme France SARL",
    "CountryReg": "France",
    "BusinessLicenseNo": "FR123456789",
    "UIN": "FR-ABC-123",
    "CompanyCnName": "测试公司"
  }'
```