tyapi-server/docs/法大大天远侧配置待办清单.md

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

代码已从 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/ 正式：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）

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

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）：

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

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

对应配置：

fadada:
  callback:
    enabled: true

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

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

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