qiyuesuo-client

qiyuesuo-client

契约锁（Qiyuesuo）开放平台 Go 客户端 SDK，封装 HTTP 签名、认证授权、PDF 静默签章与回调解密。

业务状态机（租户入驻、成员加入、续签入口）由 NGTenantManage / 各业务服务 实现；本库 仅负责契约锁 API 调用。

模块路径

git.sxidc.com/health-checkup-system/qiyuesuo-client

依赖

• git.sxidc.com/student-physical-examination/contract_lock_sdk — 官方 DTO 与 SdkClient（创建合同、静默签署）
• github.com/google/uuid — 请求 nonce

快速开始

import qiyuesuosdk "git.sxidc.com/health-checkup-system/qiyuesuo-client"

client := qiyuesuosdk.New(qiyuesuosdk.Config{
    Address:   "https://qys.example.com",
    AppToken:  "...",
    AppSecret: "...",
}, qiyuesuosdk.SignDefaults{
    ProcessID:  "用印流程ID",
    TenantName: "发起方企业名称",
})

// 机构认证页
url, err := client.CompanyCertificationURL(qiyuesuosdk.OrgCertParams{
    CompanyName: "某某医院", Charger: "张三", Mobile: "13800000000",
    OpenCompanyID: tenantID, // 通常等于平台 tenant_id
})

// PDF 签章
signed, err := client.SignDocument(qiyuesuosdk.SignDocumentRequest{
    PDF: []byte("..."), Subject: "体检报告",
    CompanySeal: qiyuesuosdk.CompanySealSpec{
        CompanyName: "某某医院", Keyword: "报告日期", OffsetY: "0.03",
    },
    PersonalSeals: []qiyuesuosdk.PersonalSealSpec{
        {OpenUserID: openID, Keyword: "李医生"},
    },
})

// 回调解析（在 Gateway/ngtm  handler 中）
event, err := client.ParseCallback(qiyuesuosdk.CallbackRequest{...})

API 分组

文件	能力
auth.go	机构法人认证、机构印章静默授权、授权记录查询
user.go	内部用户创建、个人静默授权 URL、个人授权记录
sign.go	SignDocument（机构+个人）、SignDualCompany（双机构）
callback.go	回调 AES 解密 + SHA256 验签

与各服务的关系

服务	职责
qiyuesuo-client	契约锁 HTTP/SDK 封装
NGTenantManage	租户/成员电子签章状态、认证授权 API、回调写库
HealthCheckService	签章前查 ngtm 状态 → 调 SignDocument → 写 med_sign_reports
WeChatService	小程序「电子签名授权/续签」页面（调 ngtm，不直接依赖本库亦可）

版本发布

git tag v0.1.0
git push origin v0.1.0

业务服务：

go get git.sxidc.com/health-checkup-system/qiyuesuo-client@v0.1.0

私服需配置 GOPRIVATE=git.sxidc.com。

本地联调（monorepo）

replace git.sxidc.com/health-checkup-system/qiyuesuo-client => ../qiyuesuo-client
replace git.sxidc.com/student-physical-examination/contract_lock_sdk => ../contract_lock_sdk

文档

• docs/hcs/qiyuesuo-integration-plan.md — 对接方案与职责划分