team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

temp

Browse Source
This commit is contained in:
liangzai
2025-07-20 20:53:26 +08:00
parent 83bf9aea7d
commit 8ad1d7288e
158 changed files with 18156 additions and 13188 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
docs/e签宝集成使用指南.md Normal file
View File

@@ -0,0 +1,328 @@
# e签宝集成使用指南
## 概述
本项目已集成e签宝电子签名服务，用于企业认证流程中的合同签署。e签宝服务提供了完整的电子签名功能，包括合同生成、签署流程管理、文件下载等。
## 架构设计
### 服务结构
- **EQService**: 统一的e签宝服务，提供底层API封装和业务集成方法
- **配置管理**: 在主配置文件中统一管理e签宝配置
- **应用服务**: 直接调用EQService的业务方法
### 核心功能
1. **合同生成**: 使用模板生成合同文件
2. **签署流程**: 创建和管理签署流程
3. **签署链接**: 获取签署页面链接
4. **状态查询**: 查询签署流程状态
5. **文件下载**: 下载已签署的文件
## 配置说明
### 主配置文件 (config.go)
```go
type Config struct {
// ... 其他配置 ...
// e签宝配置
Esign EsignConfig `yaml:"esign"`
}
type EsignConfig struct {
AppID string `yaml:"app_id"` // e签宝应用ID
AppSecret string `yaml:"app_secret"` // e签宝应用密钥
ServerURL string `yaml:"server_url"` // e签宝服务器地址
TemplateID string `yaml:"template_id"` // 合同模板ID
EnableDebug bool `yaml:"enable_debug"` // 是否启用调试模式
}
```
### 环境配置文件
```yaml
# configs/env.development.yaml
esign:
app_id: "your_app_id"
app_secret: "your_app_secret"
server_url: "https://esign-api.antfin.com"
template_id: "your_template_id"
enable_debug: true
```
## 使用方法
### 1. 在应用服务中使用
```go
// 注入e签宝服务
type CertificationApplicationServiceImpl struct {
// ... 其他依赖 ...
esignService *esign_service.EQService
}
// 生成合同
func (s *CertificationApplicationServiceImpl) ApplyContract(ctx context.Context, userID string) (*responses.CertificationResponse, error) {
// 1. 获取企业信息
enterpriseInfo, err := s.enterpriseService.GetEnterpriseInfo(ctx, userID)
if err != nil {
return nil, err
}
// 2. 准备合同签署请求
contractReq := &esign_service.ContractSignRequest{
CertificationID: certification.ID,
UserID: userID,
CompanyName: enterpriseInfo.CompanyName,
UnifiedSocialCode: enterpriseInfo.UnifiedSocialCode,
LegalPersonName: enterpriseInfo.LegalPersonName,
LegalPersonIDCard: enterpriseInfo.LegalPersonID,
LegalPersonPhone: user.Phone,
}
// 3. 生成合同
contractResp, err := s.esignService.GenerateContract(contractReq)
if err != nil {
return nil, fmt.Errorf("生成合同失败: %w", err)
}
// 4. 创建合同记录
contractRecord := entities.NewEsignContractGenerateRecord(
certification.ID,
userID,
"企业认证服务协议",
"certification_agreement",
)
contractRecord.MarkAsSuccess(
contractResp.SignFlowID,
contractResp.FileID,
contractResp.SignURL,
)
// 5. 保存记录到数据库
// ... 保存逻辑 ...
return response, nil
}
```
### 2. 获取签署链接
```go
// 获取签署链接
func (s *CertificationApplicationServiceImpl) GetContractSignURL(ctx context.Context, cmd *commands.GetContractSignURLCommand) (*responses.ContractSignURLResponse, error) {
// 1. 从数据库获取签署流程ID
signFlowID := "从数据库获取的流程ID"
// 2. 获取签署链接
signURL, shortURL, err := s.esignService.GetContractSignURL(signFlowID, user.Phone, enterpriseInfo.LegalPersonName)
if err != nil {
return nil, fmt.Errorf("获取签署链接失败: %w", err)
}
response := &responses.ContractSignURLResponse{
SignURL: signURL,
ShortURL: shortURL,
SignFlowID: signFlowID,
ContractName: "企业认证服务协议",
ExpireAt: time.Now().AddDate(0, 0, 7).Format(time.RFC3339),
}
return response, nil
}
```
### 3. 检查签署状态
```go
// 检查签署是否完成
func (s *CertificationApplicationServiceImpl) CheckSignStatus(ctx context.Context, signFlowID string) (bool, error) {
completed, err := s.esignService.IsSignFlowCompleted(signFlowID)
if err != nil {
return false, fmt.Errorf("检查签署状态失败: %w", err)
}
return completed, nil
}
```
## API接口
### 1. 申请合同
```http
POST /api/certification/apply-contract
Authorization: Bearer {token}
Response:
{
"code": 200,
"message": "合同申请成功",
"data": {
"id": "certification_id",
"user_id": "user_id",
"status": "contract_applied",
"status_name": "已申请合同",
"progress": 60,
"contract_applied_at": "2024-01-01T12:00:00Z"
}
}
```
### 2. 获取签署链接
```http
GET /api/certification/contract-sign-url
Authorization: Bearer {token}
Response:
{
"code": 200,
"message": "获取签署链接成功",
"data": {
"sign_url": "https://esign.antfin.com/sign/...",
"short_url": "https://short.url/...",
"sign_flow_id": "flow_id",
"contract_name": "企业认证服务协议",
"expire_at": "2024-01-08T12:00:00Z"
}
}
```
### 3. 完成合同签署
```http
POST /api/certification/complete-contract-sign
Authorization: Bearer {token}
Content-Type: application/json
{
"contract_url": "https://esign.antfin.com/sign/..."
}
Response:
{
"code": 200,
"message": "合同签署完成",
"data": null
}
```
## 数据库表结构
### esign_contract_generate_records (合同生成记录表)
```sql
CREATE TABLE esign_contract_generate_records (
id VARCHAR(36) PRIMARY KEY,
certification_id VARCHAR(36) NOT NULL,
user_id VARCHAR(36) NOT NULL,
esign_flow_id VARCHAR(100),
contract_file_id VARCHAR(100),
contract_url VARCHAR(500),
contract_name VARCHAR(200) NOT NULL,
contract_type VARCHAR(50) NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'pending',
request_at TIMESTAMP NOT NULL,
generated_at TIMESTAMP NULL,
failed_at TIMESTAMP NULL,
failure_reason TEXT,
retry_count INT DEFAULT 0,
max_retries INT DEFAULT 3,
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
deleted_at TIMESTAMP NULL,
INDEX idx_certification_id (certification_id),
INDEX idx_user_id (user_id),
INDEX idx_esign_flow_id (esign_flow_id),
INDEX idx_contract_file_id (contract_file_id)
);
```
### esign_contract_sign_records (合同签署记录表)
```sql
CREATE TABLE esign_contract_sign_records (
id VARCHAR(36) PRIMARY KEY,
certification_id VARCHAR(36) NOT NULL,
user_id VARCHAR(36) NOT NULL,
esign_flow_id VARCHAR(100) NOT NULL,
sign_url VARCHAR(500),
short_url VARCHAR(500),
sign_status VARCHAR(20) NOT NULL DEFAULT 'pending',
signed_at TIMESTAMP NULL,
expire_at TIMESTAMP NULL,
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
deleted_at TIMESTAMP NULL,
INDEX idx_certification_id (certification_id),
INDEX idx_user_id (user_id),
INDEX idx_esign_flow_id (esign_flow_id)
);
```
## 错误处理
### 常见错误
1. **配置错误**: 检查e签宝配置是否正确
2. **网络错误**: 检查网络连接和e签宝服务状态
3. **参数错误**: 检查请求参数是否完整
4. **权限错误**: 检查e签宝应用权限
### 错误响应格式
```json
{
"code": 500,
"message": "生成合同失败: 网络连接超时",
"data": null
}
```
## 最佳实践
### 1. 配置管理
- 使用环境变量管理敏感配置
- 不同环境使用不同的配置
- 定期更新e签宝应用密钥
### 2. 错误处理
- 实现重试机制
- 记录详细的错误日志
- 提供友好的错误提示
### 3. 性能优化
- 使用缓存减少API调用
- 异步处理长时间操作
- 合理设置超时时间
### 4. 安全考虑
- 验证用户权限
- 加密敏感数据
- 记录操作日志
## 开发调试
### 启用调试模式
```yaml
esign:
enable_debug: true
```
### 查看日志
```bash
# 查看应用日志
tail -f logs/app.log | grep esign
# 查看e签宝API调用日志
tail -f logs/app.log | grep "e签宝"
```
### 测试流程
1. 配置测试环境
2. 创建测试用户
3. 提交企业信息
4. 申请合同
5. 获取签署链接
6. 完成签署流程
## 注意事项
1. **模板配置**: 确保e签宝模板配置正确
2. **字段映射**: 注意模板字段与业务数据的映射关系
3. **状态同步**: 及时同步e签宝状态到本地数据库
4. **数据备份**: 定期备份合同相关数据
5. **合规要求**: 确保符合电子签名相关法规要求