253 lines
10 KiB
Markdown
253 lines
10 KiB
Markdown
# 法大大（天远）接入待办清单
|
||
|
||
> 代码已从 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
|
||
```
|