hyapi-server/internal/domains/certification/ports/sign_platform_provider.go

package ports

import (
	"context"

	"hyapi-server/internal/domains/certification/enums"
)

// EnterpriseAuthRequest 企业认证链接请求
type EnterpriseAuthRequest struct {
	ClientCorpID      string
	ClientUserID      string
	CompanyName       string
	UnifiedSocialCode string
	LegalPersonName   string
	LegalPersonID     string
	TransactorName    string
	TransactorMobile  string
	TransactorID      string
}

// AuthLinkResult 企业认证链接结果
type AuthLinkResult struct {
	AuthFlowID   string
	AuthURL      string
	AuthShortURL string
}

// OrgIdentityQuery 企业实名查询
type OrgIdentityQuery struct {
	OrgName      string
	OrgIdentNo   string
	OpenCorpID   string
	ClientCorpID string
}

// ContractGenerateRequest 合同模板填单
type ContractGenerateRequest struct {
	AgreementNo       string
	CompanyName       string
	UnifiedSocialCode string
	EnterpriseAddress string
	AuthorizedRepName string
	SignDate          string
	FileName          string
}

// ContractFileResult 合同文件结果
type ContractFileResult struct {
	FileID          string
	FileDownloadURL string
}

// SignFlowCreateRequest 创建签署流程
type SignFlowCreateRequest struct {
	Subject          string
	FileID           string
	DocName          string
	PartyAOpenCorpID string
	PartyAName       string
	PartyAUSCC       string
	TransactorName   string
	TransactorMobile string
	TransactorID     string
	TransReferenceID string
	Fill             *ContractGenerateRequest
	// SkipActorURL 为企业认证后预创建任务时跳过取签署链接（避免消耗 10 分钟单次 EmbedURL）
	SkipActorURL bool
}

// SignFlowResult 签署流程创建结果
type SignFlowResult struct {
	SignFlowID string
	// SignURL 可供 iframe 嵌入的签署长链（法大大 actorSignTaskEmbedUrl / e签宝 url）
	SignURL string
	// ShortURL 短链（法大大 actorSignTaskUrl，不可 iframe）
	ShortURL string
}

// GetActorSignURLRequest 重新获取参与方签署链接
type GetActorSignURLRequest struct {
	SignFlowID       string
	TransactorMobile string
	PartyAName       string
}

// ActorSignURLResult 参与方签署链接（长链可 iframe，短链不可）
type ActorSignURLResult struct {
	SignFlowID string
	EmbedURL   string // iframe 用
	ShortURL   string // 短链，一年有效，需登录
}

// SignTaskPreviewURLResult 签署任务预览链接
type SignTaskPreviewURLResult struct {
	SignFlowID string
	PreviewURL string
}

// SignStatusResult 签署状态
type SignStatusResult struct {
	SignFlowID string
	Status     string
	Completed  bool
	Rejected   bool
	Expired    bool
	Message    string
}

// SignedFile 已签文件
type SignedFile struct {
	DownloadURL string
	DownloadID  string
}

// CallbackEvent 回调事件
type CallbackEvent struct {
	Event         string
	AuthPassed    bool
	SignCompleted bool
	SignRejected  bool
	SignFlowID    string
	AuthFlowID    string
	OrgName       string
	Raw           map[string]interface{}
}

// SignPlatformProvider 签署平台统一能力（e签宝 / 法大大）
type SignPlatformProvider interface {
	Platform() enums.SignPlatform

	GenerateEnterpriseAuth(ctx context.Context, req *EnterpriseAuthRequest) (*AuthLinkResult, error)
	QueryOrgVerified(ctx context.Context, req *OrgIdentityQuery) (bool, error)

	GenerateContractFile(ctx context.Context, req *ContractGenerateRequest) (*ContractFileResult, error)
	CreateSignFlow(ctx context.Context, req *SignFlowCreateRequest) (*SignFlowResult, error)
	// GetActorSignURL 按已有签署任务重新获取参与方链接（法大大长链 10 分钟/单次，进入签署页时应刷新）
	GetActorSignURL(ctx context.Context, req *GetActorSignURLRequest) (*ActorSignURLResult, error)
	// GetSignTaskPreviewURL 获取签署任务预览链接（法大大 EUI，约 2 小时/单次；勿用 PDF 直链做预览）
	GetSignTaskPreviewURL(ctx context.Context, signFlowID string) (*SignTaskPreviewURLResult, error)
	QuerySignStatus(ctx context.Context, flowID string) (*SignStatusResult, error)
	DownloadSignedFiles(ctx context.Context, flowID string) ([]*SignedFile, error)

	VerifyCallback(ctx context.Context, headers map[string]string, body []byte) error
	ParseCallback(ctx context.Context, headers map[string]string, body []byte) (*CallbackEvent, error)
}

// SignPlatformRegistry 按平台路由 Provider
type SignPlatformRegistry interface {
	Get(platform enums.SignPlatform) (SignPlatformProvider, error)
	List() []SignPlatformProvider
}