# qiyuesuo-client

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

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

## 模块路径

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

## 依赖

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

## 快速开始

```go
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，不直接依赖本库亦可） |

## 版本发布

```bash
git tag v0.1.0
git push origin v0.1.0
```

业务服务：

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

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

## 本地联调（monorepo）

```go
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](../docs/hcs/qiyuesuo-integration-plan.md) — 对接方案与职责划分