team/hyapi-server

Fork 0

Files

Mrxs c943f575d5 fadd

2026-07-21 15:53:29 +08:00

18 KiB

Raw Permalink Blame History

企业入驻 × e签宝功能分析

文档基于 hyapi-server 与 hyapi-consoleweb 代码梳理，最后更新：2026-07-13

1. 功能概述

企业入驻是独立的认证域（certification），通过自研 Go SDK（internal/shared/esign）对接 e签宝 OpenAPI，引导企业用户完成：

填写并提交企业信息（含人工审核）
e签宝机构实名认证
基于模板生成合作协议并电子签署
入驻完成（激活钱包、API 用户等）

核心实现文件：

层级	路径
业务编排	`internal/application/certification/certification_application_service_impl.go`
状态机实体	`internal/domains/certification/entities/certification.go`
e签宝 SDK	`internal/shared/esign/`
HTTP 路由	`internal/infrastructure/http/routes/certification_routes.go`
前端主流程	`hyapi-consoleweb/src/pages/certification/`

2. 涉及数据表

表结构通过 GORM AutoMigrate 自动创建（internal/app/app.go），无独立 SQL migration。

2.1 认证域（核心）

`certifications` — 认证主表（聚合根）

每个用户最多一条认证记录（user_id 唯一），贯穿全流程并存储 e签宝关键 ID/链接。

字段	类型	说明
`id`	varchar(64)	认证申请 ID
`user_id`	varchar(36)	用户 ID（唯一）
`status`	varchar(50)	认证状态（见第 3 节）
`info_submitted_at`	datetime	企业信息审核通过时间
`enterprise_verified_at`	datetime	e签宝企业认证完成时间
`contract_applied_at`	datetime	申请签署时间
`contract_signed_at`	datetime	签署完成时间
`completed_at`	datetime	入驻完成时间
`contract_file_created_at`	datetime	合同文件生成时间（用于 50 分钟过期判断）
`auth_flow_id`	varchar(500)	e签宝企业认证流程 ID
`auth_url`	varchar(500)	e签宝企业认证页面链接
`contract_code`	varchar(100)	合作协议编号（如 `HYDATA-20260713-R123456`）
`contract_file_id`	varchar(500)	e签宝合同文件 ID
`esign_flow_id`	varchar(500)	e签宝签署流程 ID
`contract_url`	varchar(500)	合同预览/下载 URL
`contract_sign_url`	varchar(500)	合同签署链接
`failure_reason` / `failure_message`	varchar/text	失败原因与详情
`retry_count`	int	重试次数（上限 3）
`last_transition_*`	—	状态转换审计字段

`enterprise_info_submit_records` — 企业信息提交与人工审核

用户每次提交企业信息时写入，承载审核材料与审核结果。

字段分组	主要字段	说明
企业四要素	`company_name`、`unified_social_code`、`legal_person_*`、`enterprise_address`	企业基本信息
授权代表	`authorized_rep_name/id/phone`、`authorized_rep_id_image_urls`	授权代表信息（身份证图片为 JSON 数组）
资质材料	`business_license_image_url`、`office_place_image_urls`、`api_usage`、`scenario_attachment_urls`	营业执照、办公场地、业务场景说明及附件
前置校验	`status`	`submitted` / `verified` / `failed`（西部数据三真等）
人工审核	`manual_review_status`	`pending` / `approved` / `rejected`
审核人	`manual_reviewer_id`、`manual_review_remark`、`manual_reviewed_at`	管理员审核信息

`esign_contract_generate_records` — 合同生成记录

字段	说明
`certification_id`、`user_id`	关联认证与用户
`template_id`	e签宝模板 ID
`contract_file_id`、`contract_url`、`contract_name`	生成结果
`status`	`success` / `failed`
`fill_time`	填单时间

`esign_contract_sign_records` — 合同签署记录

字段	说明
`esign_flow_id`、`contract_file_id`	e签宝流程与文件
`sign_url`、`sign_short_url`	签署链接
`signed_file_url`	已签署文件 URL
`status`	`pending` / `signing` / `success` / `failed` / `expired`
`signer_name/phone/id_card`	签署人信息
`request_at`、`signed_at`、`expired_at`	时间戳（默认 7 天过期）

2.2 用户域（认证完成后写入）

`enterprise_infos` — 已认证企业信息

认证通过后从提交记录同步，供充值、开票、API 调用等使用；与用户一对一。

字段	说明
`user_id`	用户 ID（唯一索引）
`company_name`	企业名称
`unified_social_code`	统一社会信用代码
`legal_person_name/id/phone`	法人信息
`enterprise_address`	企业地址

`contract_infos` — 已签署合同

签署完成后写入，一个企业可有多份合同。

字段	说明
`enterprise_info_id`、`user_id`	关联企业与用户
`contract_code`	合同编号（唯一）
`contract_name`	合同名称
`contract_type`	`cooperation`（入驻）/ `resign`（补签）
`contract_file_id`	e签宝文件 ID
`contract_file_url`	七牛云永久存储链接

2.3 入驻完成后关联表（非 e签宝直接写入，但属完成动作）

表名	说明
`wallets`	创建用户钱包
`api_users`	创建 API 调用身份
`users`	标记用户已完成认证（`CompleteCertification`）

3. 认证状态机

pending
  └─► info_pending_review（提交企业信息，等待人工审核）
        ├─► info_rejected（审核拒绝 / e签宝 认证失败）
        └─► info_submitted（审核通过，持有 auth_url）
              └─► enterprise_verified（e签宝 机构实名成功，已生成合同）
                    └─► contract_applied（已申请签署，持有 contract_sign_url）
                          ├─► contract_signed ──► completed（入驻完成）
                          ├─► contract_rejected（拒签，可重试）
                          └─► contract_expired（超时，可重试）

状态值	中文	进度	用户操作
`pending`	待认证	0%	填写企业信息
`info_pending_review`	企业信息待审核	15%	等待管理员
`info_submitted`	已提交企业信息	25%	完成 e签宝企业认证
`enterprise_verified`	已企业认证	50%	申请签署合同
`contract_applied`	已申请签署	75%	在 iframe 中签署
`contract_signed`	已签署合同	100%	等待系统处理
`completed`	认证完成	100%	可使用全部功能
`info_rejected`	企业信息被拒绝	—	修正后重新提交
`contract_rejected`	合同被拒签	—	重新申请
`contract_expired`	合同签署超时	—	重新申请

4. 主要业务流程

4.1 流程总览

flowchart TD
    A[用户注册/登录] --> B[POST /enterprise-info 提交企业信息]
    B --> C[短信验证 + 西部数据三真校验]
    C --> D[状态: info_pending_review]
    D --> E{管理员审核}
    E -->|拒绝| F[info_rejected]
    E -->|通过| G[调用 e签宝 /v3/org-auth-url]
    G --> H[状态: info_submitted<br/>写入 auth_url]
    H --> I[iframe 完成机构实名]
    I --> J{确认方式}
    J -->|回调 AUTH_PASS| K[enterprise_verified]
    J -->|轮询 GET /details 或 POST /confirm-auth| K
    K --> L[模板填单生成合同 PDF]
    L --> M[POST /apply-contract 申请签署]
    M --> N[状态: contract_applied]
    N --> O[iframe 签署合同]
    O --> P{确认方式}
    P -->|POST /confirm-sign 轮询| Q[contract_signed → completed]
    Q --> R[下载已签文件 → 七牛 → contract_infos]
    R --> S[创建钱包 + API 用户]

4.2 步骤一：提交企业信息

接口： POST /api/v1/certifications/enterprise-info（JWT + 日限流）

处理逻辑（SubmitEnterpriseInfo）：

防重复：若已有 info_pending_review 记录则拒绝重复提交
短信验证码校验（场景 SMSSceneCertification）
统一社会信用代码唯一性检查（enterprise_infos + enterprise_info_submit_records）
字段格式校验 + 西部数据三真（ValidateWithWestdex）
写入 enterprise_info_submit_records（状态 verified）
认证状态转为 info_pending_review
企业微信通知管理员待审核

此阶段不调用 e签宝。

辅助接口：

POST /ocr/business-license — 营业执照 OCR
POST /upload — 认证材料上传七牛云

4.3 步骤二：管理员人工审核

接口：

GET /api/v1/certifications/admin/submit-records — 列表
GET /api/v1/certifications/admin/submit-records/:id — 详情
POST /api/v1/certifications/admin/submit-records/:id/approve — 通过
POST /api/v1/certifications/admin/submit-records/:id/reject — 拒绝

审核通过（AdminApproveSubmitRecord）：

调用 esignClient.GenerateEnterpriseAuth() → e签宝 POST /v3/org-auth-url
若企业已在 e签宝实名（错误含「已实名」），则 QueryOrgIdentityInfo 后直接 completeEnterpriseVerification
否则状态 → info_submitted，写入 auth_flow_id、auth_url
提交记录 manual_review_status → approved

经办人信息： 当前使用法人作为 e签宝经办人（TransactorName = LegalPersonName），未使用授权代表字段。

4.4 步骤三：e签宝企业实名认证

前端： EnterpriseVerify.vue 通过 iframe 加载 metadata.auth_url

完成确认（双路径）：

路径	触发	处理
服务端回调	`POST /api/v1/certifications/callbacks/esign`，`action=AUTH_PASS` 且 `authType=ORG`	`HandleEsignCallback` → `completeEnterpriseVerification`
前端轮询	`GET /details` 或 `POST /confirm-auth`	查询 `GET /v3/organizations/identity-info`，`realnameStatus==1` 时推进

Redirect： 用户完成后跳转 auth.redirect_url（如 /certification/callback/auth），IframeCallback.vue 通过 postMessage 通知父页面刷新状态。

completeEnterpriseVerification 动作：

状态 → enterprise_verified
企业信息写入 enterprise_infos
调用 FillTemplate 填控件生成合同（见 4.5）
保存 contract_file_id、contract_url、contract_code

4.5 步骤四：生成合作协议

e签宝 API： POST /v3/files/create-by-doc-template

模板控件映射：

控件 key	填入内容
`jfqym` / `jfqym2`	企业名称
`jfsqdb`	授权代表姓名（无则用法人的）
`jftyshxydm`	统一社会信用代码
`jflxdz`	企业地址
`xybh`	协议编号
`qsrq1` / `qsrq2` / `qsrq3`	签署日期

合同编号规则： HYDATA-YYYYMMDD-R{6位随机数}（R = 入驻）

过期策略： 合同文件生成后 50 分钟过期，GET /details 时会自动重新生成（IsContractFileNeedUpdate）。

4.6 步骤五：申请并签署合同

接口： POST /api/v1/certifications/apply-contract

前置条件： 状态为 enterprise_verified

处理逻辑：

CreateSignFlow → POST /v3/sign-flow/create-by-file（甲方手动签 + 乙方自动盖章）
GetSignURL → POST /v3/sign-flow/{id}/sign-url
状态 → contract_applied，保存 esign_flow_id、contract_sign_url

签署确认：

前端 iframe 加载 contract_sign_url，完成后 redirect 到 sign.redirect_url
POST /confirm-sign 或 GET /details 轮询 QuerySignFlowDetail

签署状态码（业务使用）：

SignFlowStatus	含义	系统动作
`2`	签署完成	→ `contract_signed` → `completed`
`7`	拒签	→ `contract_rejected`
`5`	过期	→ `contract_expired`
其他	签署中	继续轮询

4.7 步骤六：入驻完成

handleContractAfterSignComplete：

DownloadSignedFile 从 e签宝下载已签 PDF
上传七牛云获取永久 URL
写入 contract_infos
completeUserActivationWithoutContract：
- 创建 wallets
- 创建 api_users
- 用户域标记认证完成
- 企业微信通知「企业认证成功」

5. API 端点汇总

5.1 本系统 REST API

前缀：/api/v1/certifications

方法	路径	认证	说明
GET	`/details`	JWT	获取/创建认证详情，自动同步 e签宝状态
POST	`/enterprise-info`	JWT + 日限流	提交企业信息
POST	`/ocr/business-license`	JWT	营业执照 OCR
POST	`/upload`	JWT	认证材料上传
POST	`/confirm-auth`	JWT	轮询确认企业实名
POST	`/apply-contract`	JWT	申请合同签署
POST	`/confirm-sign`	JWT	轮询确认签署状态
POST	`/callbacks/esign`	无	e签宝服务端回调
GET	``	JWT 管理员	认证列表
POST	`/admin/complete-without-contract`	管理员	跳过合同直接完成认证
POST	`/admin/transition-status`	管理员	手动变更状态
GET/POST	`/admin/submit-records[...]`	管理员	提交记录 CRUD + 审核

5.2 e签宝 OpenAPI（SDK 封装）

方法	路径	用途
POST	`/v3/org-auth-url`	获取机构认证页面链接
GET	`/v3/organizations/identity-info`	查询机构是否已实名
POST	`/v3/files/create-by-doc-template`	模板填单生成 PDF
POST	`/v3/sign-flow/create-by-file`	创建签署流程
POST	`/v3/sign-flow/{id}/sign-url`	获取签署链接
GET	`/v3/sign-flow/{id}/detail`	查询签署状态
GET	`/v3/sign-flow/{id}/file-download-url`	下载已签署文件

5.3 前端路由

路由	说明
`/profile/certification`	企业入驻主流程（5 步）
`/certification/callback/auth`	e签宝认证完成 redirect
`/certification/callback/sign`	e签宝签署完成 redirect
`/admin/certification-reviews`	管理端审核列表

6. e签宝配置项

配置文件：config.yaml / configs/env.{development,production}.yaml

esign:
  app_id: "..."              # 应用 ID
  app_secret: "..."          # 应用密钥（API 签名）
  server_url: "..."          # 沙箱: https://smlopenapi.esign.cn
                             # 生产: https://openapi.esign.cn
  template_id: "..."         # 合作协议模板 ID
  contract:
    name: "海宇数据-合作协议"
    expire_days: 7           # 签署链接有效期（天）
    retry_count: 3
  auth:
    org_auth_modes: ["PSN_MOBILE3"]
    default_auth_mode: "PSN_MOBILE3"
    psn_auth_modes: ["PSN_MOBILE3", "PSN_IDCARD"]
    willingness_auth_modes: ["CODE_SMS"]
    redirect_url: "https://console.haiyudata.com/certification/callback/auth"
  sign:
    auto_finish: true
    sign_field_style: 1
    client_type: "ALL"
    redirect_url: "https://console.haiyudata.com/certification/callback/sign"

Go 结构：config.EsignConfig → 注入为 esign.Config（container.go）。

7. 架构与代码组织

hyapi-server/
├── internal/
│   ├── application/certification/          # 应用服务（主业务编排）
│   ├── domains/certification/              # 领域模型、状态机、枚举
│   ├── domains/user/entities/              # enterprise_infos, contract_infos
│   ├── infrastructure/
│   │   ├── http/handlers/certification_handler.go
│   │   ├── http/routes/certification_routes.go
│   │   └── database/repositories/certification/
│   └── shared/esign/                       # e签宝 SDK
│       ├── client.go                       # 统一入口
│       ├── orgauth_service.go              # 机构认证
│       ├── org_identity.go                 # 实名查询
│       ├── template_service.go             # 模板填单
│       ├── signflow_service.go             # 签署流程
│       └── fileops_service.go              # 文件下载/状态查询

hyapi-consoleweb/
└── src/pages/certification/
    ├── index.vue                           # 主流程容器
    ├── IframeCallback.vue                  # e签宝 redirect 回调
    └── components/
        ├── EnterpriseInfo.vue              # 填写企业信息
        ├── ManualReviewPending.vue         # 人工审核等待
        ├── EnterpriseVerify.vue            # e签宝 认证 iframe
        ├── ContractPreview.vue / ContractSign.vue
        └── CertificationComplete.vue

8. 注意事项与已知问题

回调验签未启用
HandleEsignCallback 中 esign.VerifySignature 已被注释，生产环境存在安全风险。
遗留代码未接入
internal/infrastructure/external/esign/certification_esign_service.go 为模拟实现，未注册到 DI；CertificationWorkflowOrchestrator 部分方法为 stub。
双路径状态同步
企业认证支持「e签宝回调」与「前端轮询」两条路径；合同签署主要依赖 confirm-sign / GET /details 主动查询，回调仅处理 AUTH_PASS。
经办人默认法人
生成认证链接时经办人使用法人信息，授权代表字段仅用于合同模板 jfsqdb 控件。
签署状态码注释不一致
SDK 注释与业务代码对 SignFlowStatus 的含义存在差异，排查问题时以 checkAndUpdateSignStatus 中的判断为准（2=成功，7=拒签，5=过期）。
与 API 实名产品无关
IVYZSQ0E / IVYZFO5K 等数据 API 的身份证实名校验属于 API 调用产品，与本入驻流程无关。

9. 入驻完成后的系统能力

认证状态为 completed 后，用户可使用：

钱包充值（Wallet.vue）
开票申请（Invoice.vue）
API 调用（需 api_users）
IP 白名单等需认证页面（useCertification / CertificationBanner 检查 isCertified）

18 KiB Raw Permalink Blame History Unescape Escape

企业入驻 × e签宝 功能分析