# 法大大（天远）接入待办清单

> 代码已从 hyapi（海宇）移植到 tyapi（天远）。  
> **两边是不同公司、不同法大大账号：海宇的密钥 / 模板 / 企业 ID 一律不可复用。**  
> 本文只列 **天远侧需要你准备、填写、在法大大后台配置** 的事项。

---

## 一、结论（先看这个）

| 类别 | 是否需要你做 |
|------|----------------|
| 代码移植 | ✅ 已完成（后端 + 前端） |
| 天远法大大开户 / 应用密钥 | ❌ **必须你提供** |
| 天远合同模板 + 控件 fieldId | ❌ **必须你新建并回填配置** |
| 天远企业 openCorpId / 印章 / 免验证签场景码 | ❌ **必须你开通** |
| 回调与回跳域名 | ❌ **必须你在法大大后台登记** |
| 海宇配置抄过来 | ⛔ **禁止** |

配置已按 2026-07-26 提供的天远应用凭证写入（三份 yaml 的 `fadada:`）。

**重要纠偏（已按 hyapi 对照处理）：**

| 你提供的值 | 实际写入 | 说明 |
|------------|----------|------|
| `c66587b4a048bba3c1cb032eb7750182` 当作模板 ID | **否** → 写入 `no_auth_scene_code` | hyapi 里这是免签场景码，不是模板 ID |
| 模板 ID | `1784619066713193840` | hyapi 同模板真实 ID；请在法大大后台再确认一次 |
| `openCorpId=aca08b5f...`（应用页） | **未**作为盖章身份 | 代码 `open_corp_id` 用于乙方自动盖章 ActorOpenID |
| 乙方=海南海宇大数据有限公司 | `open_corp_id=7118e66dfd9349d998c0395c5d0742ad` | 取自 hyapi 海宇企业 ID，请确认是否仍正确 |

---

## 二、密钥与账号（必填）

在法大大开放平台为 **天远数据** 单独创建应用后，提供：

| 项 | 配置键 | 说明 | 从哪拿 |
|----|--------|------|--------|
| 应用 ID | `fadada.app_id` | 天远应用的 AppId | 开放平台 → 应用详情 |
| 应用密钥 | `fadada.app_secret` | AppSecret（验签也用它） | 开放平台 → 应用详情 |
| API 环境 | `fadada.server_url` | 测试：`https://uat-api.fadada.com/api/v5/`<br>正式：`https://api.fadada.com/api/v5/` | 按环境选择 |
| 天远企业 ID | `fadada.open_corp_id` | 天远主体在法大大侧的 `openCorpId`（乙方自动盖章身份） | 企业授权完成后在控制台/接口可见 |
| 免验证签场景码 | `fadada.no_auth_scene_code` | 即 `businessId`；乙方免验证签必传 | 法大大后台申请「模板免验证签」场景 |

**不需要**单独提供 `.pem` / 证书文件；API 与回调验签均使用 `app_id` + `app_secret`（HMAC-SHA256）。

建议：**测试应用 / 正式应用各一套**，分别写入 development / production。

---

## 三、合同模板与文件（必填）

### 3.1 需要准备的文件

| 文件 | 用途 | 备注 |
|------|------|------|
| 《天远数据API合作协议》Word/PDF 原件 | 上传到法大大做成「签署模板」 | **不能**用海宇模板；法务定稿后再上传 |
| （可选）控件 fieldId 对照表 | Excel/截图，标清每个填写控件编码 | 方便回填 `template_fields` |

### 3.2 模板在法大大后台要配好

1. 创建 **签署模板**（含甲、乙双方角色，角色名建议：`甲方` / `乙方`）
2. 甲方：客户企业手动签（验证码等）
3. 乙方：天远，开启 **按模板免验证签**（自动盖章）
4. 放置填写控件：协议编号、签订日期、甲方企业名、统一社会信用代码、联系地址、授权代表等  
5. 签署日期用 **签署控件**（不要当填写控件走填单 API）

### 3.3 回填到配置的 ID

| 项 | 配置键 | 说明 |
|----|--------|------|
| 模板 ID | `fadada.template_id` | 签署模板 ID |
| 文档 docId | `fadada.template_doc_id` | 可先留空，运行时自动解析；有则更稳 |
| 甲方角色 | `fadada.party_a_actor_id` | 须与模板角色名一致，默认 `"甲方"` |
| 乙方角色 | `fadada.party_b_actor_id` | 默认 `"乙方"` |

### 3.4 控件 fieldId（`fadada.template_fields`）

以 **天远自己模板** 控制台导出的编码为准，示例结构：

```yaml
template_fields:
  agreement_no:          # 协议编号（多处同值可配多个 fieldId）
    - "xxxxxxxx"
  contract_date: "xxxxxxxx"     # 签订日期
  party_a_name:                 # 甲方企业名（多处同值可配多个）
    - "xxxxxxxx"
  party_a_uscc: "xxxxxxxx"      # 统一社会信用代码
  party_a_address: "xxxxxxxx"   # 联系地址
  party_a_rep: "xxxxxxxx"       # 授权代表/法人
  party_a_sign_date: ""         # 签署控件，一般留空
  party_b_sign_date: ""         # 签署控件，一般留空
```

> 海宇配置里的一串数字 fieldId **全部作废**，不可拷贝。

协议编号线上生成规则（已实现，一般不用改）：`CON01` + `YYYYMMDD` + 6 位随机数。

---

## 四、企业主体与印章（必填）

| 项 | 说明 |
|----|------|
| 天远企业在法大大完成实名 | 主体名称、统一社会信用代码与营业执照一致 |
| 应用授权 | 天远企业授权给本开放平台应用 |
| 企业公章 / 合同章 | 开通并可用于签署；免验证签场景需绑定可用印章 |
| 免验证签开通 | 与 `no_auth_scene_code` 对应；未开通则乙方自动盖章失败 |

---

## 五、回调与前端回跳（必填）

### 5.1 服务端事件回调（法大大 → 天远 API）

在法大大应用里配置回调 URL（公网 HTTPS）：

```text
https://console.tianyuanapi.com/api/v1/certifications/callbacks/fadada
```

（若 API 域名与控制台不同，改成实际 API 网关域名。）

对应配置：

```yaml
fadada:
  callback:
    enabled: true
```

### 5.2 浏览器回跳（用户 iframe 完成后）

| 场景 | 配置键 | 建议值 |
|------|--------|--------|
| 企业认证完成 | `fadada.auth.redirect_url` | 生产：`https://console.tianyuanapi.com/profile/certification`<br>本地：`http://localhost:5173/profile/certification` |
| 签署完成 | `fadada.sign.redirect_url` | 生产：`https://console.tianyuanapi.com/certification/callback/fadada/sign`<br>本地：`http://localhost:5173/certification/callback/fadada/sign` |

开发/生产 yaml 里已写好占位，确认域名证书与前端路由已上线即可。

---

## 六、文案与其它（建议核对）

| 项 | 当前默认 | 是否要你改 |
|----|----------|------------|
| 合同名称 | `天远数据API合作协议` | 与法务文件名一致即可 |
| `expire_days` / `retry_count` | 7 / 3 | 按业务调整 |
| 协议编号前缀 | `CON01...`（代码已生成） | 一般不用改 |

---

## 七、联调检查清单（按顺序打勾）

### Phase A — 账号与后台

- [ ] 天远法大大账号开户完成
- [ ] 创建开放平台应用，拿到 `app_id` / `app_secret`
- [ ] 企业实名 + 应用授权，拿到 `open_corp_id`
- [ ] 开通免验证签，拿到 `no_auth_scene_code`
- [ ] 上传《天远数据API合作协议》，建签署模板
- [ ] 记录 `template_id` 与全部填写控件 `fieldId`
- [ ] 配置印章与免验证签绑定
- [ ] 配置事件回调 URL（公网可达）

### Phase B — 写入工程配置

- [ ] 填写 `configs/env.development.yaml` 的 `fadada:`（UAT）
- [ ] 填写 `configs/env.production.yaml` 的 `fadada:`（正式 URL + 正式密钥）
- [ ] 同步/确认 `config.yaml` 本地联调段
- [ ] 确认 `auth.redirect_url` / `sign.redirect_url` 指向天远域名

### Phase C — 端到端验证

- [ ] 管理员审核通过企业信息（此时**不会**立刻调第三方）
- [ ] 用户侧自动/手动选择法大大 → 出现企业认证 iframe
- [ ] 企业认证成功 → 合同预览（法大大预览页，非 PDF 直链）
- [ ] 申请签署 → 甲方签署 iframe（链接约 10 分钟，进入页会刷新）
- [ ] 甲方签完后乙方自动盖章
- [ ] 状态变为完成，已签文件下载归档到系统
- [ ] 回调日志有验签成功记录（或轮询兜底成功）

### Phase D — 存量 e签宝

- [ ] 历史进行中的 e签宝用户可继续走完（后端仍保留 e签宝 Provider）
- [ ] 新用户前端不可见 e签宝（仅法大大）

---

## 八、交给法大大/商务时可复制的需求说明

请为「天远数据」开通 FASC OpenAPI v5.1，并提供：

1. 测试环境 & 正式环境各自的 AppId、AppSecret  
2. 企业 openCorpId  
3. 模板免验证签场景码（businessId）  
4. 签署模板能力：甲乙双方、甲方手签、乙方按模板免验证签自动盖章  
5. 事件回调地址登记权限（我方提供 HTTPS URL）  
6. 控制台导出模板 ID 与控件 fieldId 列表的权限  

合同文件由我方法务提供终稿后上传。

---

## 九、代码侧已完成（无需你再开发）

- `internal/shared/fadada`：FASC HTTP 客户端  
- `SignPlatformProvider` + Registry（e签宝 + 法大大）  
- 审核通过后选平台 → 认证 → 签署 → 下载全流程  
- 回调：`POST /api/v1/certifications/callbacks/fadada`  
- 前端：平台选择 / 静默选法大大、签署与预览链接刷新、iframe 顶层回跳  
- 配置键与 yaml 占位已就位  

**你当前唯一阻塞点：填好天远自己的法大大密钥、模板与回调。**

---

## 十、配置填写模板（可直接贴回 yaml）

```yaml
fadada:
  app_id: "这里填天远AppId"
  app_secret: "这里填天远AppSecret"
  server_url: "https://uat-api.fadada.com/api/v5/"   # 正式改为 https://api.fadada.com/api/v5/
  open_corp_id: "这里填天远openCorpId"
  no_auth_scene_code: "这里填免验证签场景码"
  template_id: "这里填签署模板ID"
  party_a_actor_id: "甲方"
  party_b_actor_id: "乙方"
  template_doc_id: ""   # 可选
  template_fields:
    agreement_no:
      - "控件ID"
    contract_date: "控件ID"
    party_a_name:
      - "控件ID"
    party_a_uscc: "控件ID"
    party_a_address: "控件ID"
    party_a_rep: "控件ID"
    party_a_sign_date: ""
    party_b_sign_date: ""
  contract:
    name: "天远数据API合作协议"
    expire_days: 7
    retry_count: 3
  auth:
    redirect_url: "https://console.tianyuanapi.com/profile/certification"
  sign:
    redirect_url: "https://console.tianyuanapi.com/certification/callback/fadada/sign"
  callback:
    enabled: true
```