1607 lines
49 KiB
Markdown
1607 lines
49 KiB
Markdown
# 企业认证系统实施计划
|
||
|
||
## 📋 需求概述
|
||
|
||
### 业务流程
|
||
|
||
用户注册后需要进行企业认证以使用平台核心功能，认证流程如下：
|
||
|
||
1. **提交企业信息**：用户上传营业执照，系统通过百度 OCR 自动识别企业四要素
|
||
2. **人脸识别**：法人进行人脸识别验证
|
||
3. **申请电子合同**：系统生成申请记录
|
||
4. **管理员审核**：管理员收到企业微信通知，审核后手工上传签署链接
|
||
5. **签署合同**：用户收到短信通知，点击链接完成签署
|
||
6. **认证完成**：系统为用户生成钱包和 Access Key
|
||
|
||
### 企业四要素
|
||
|
||
- 企业名称
|
||
- 统一信用代码
|
||
- 企业法人姓名
|
||
- 法人身份证号
|
||
|
||
## 📊 业务流程图
|
||
|
||
整个企业认证流程包含 10 个主要状态节点，涉及用户、系统、管理员和第三方服务的协同工作：
|
||
|
||
### 流程说明
|
||
|
||
1. **用户操作阶段**（蓝色节点）
|
||
|
||
- 用户上传营业执照图片（自动上传至七牛云并 OCR 识别）
|
||
- 确认或修改 OCR 识别的企业四要素信息
|
||
- 进行阿里云人脸识别验证
|
||
- 申请电子合同
|
||
- 查看合同链接并签署电子合同
|
||
|
||
2. **系统自动处理**（紫色节点）
|
||
|
||
- 创建认证申请记录
|
||
- 七牛云文件存储和百度 OCR 识别
|
||
- 将合同申请转为待审核状态
|
||
- 确认合同签署状态
|
||
- 生成钱包和 Access Key
|
||
|
||
3. **管理员审核**（橙色节点）
|
||
|
||
- 审核企业认证申请
|
||
- **手工上传电子合同签署链接**
|
||
- 处理审核结果（通过/拒绝）
|
||
|
||
4. **等待状态**（紫色节点）
|
||
|
||
- 合同待审核状态（等待管理员处理）
|
||
- 合同已审核状态（等待用户签署）
|
||
|
||
5. **第三方服务**（绿色节点）
|
||
|
||
- 七牛云文件存储
|
||
- 百度 OCR 识别营业执照
|
||
- 阿里云 InitFaceVerify 人脸识别
|
||
|
||
6. **决策节点**（红色节点）
|
||
- 企业信息确认（OCR 成功与否都允许用户确认）
|
||
- 人脸识别结果验证
|
||
- 管理员审核结果（通过/拒绝）
|
||
- 合同签署状态
|
||
|
||
### 关键特性
|
||
|
||
- **一体化处理**：营业执照上传、存储、OCR 识别一次完成
|
||
- **容错性强**：OCR 识别失败不影响流程，用户可手动填写信息
|
||
- **异步审核**：用户申请合同后，管理员异步审核并上传链接，用户无需实时等待
|
||
- **手工上传**：管理员手工上传电子合同签署链接，确保合同的准确性和合规性
|
||
- **状态分离**：合同申请、待审核、已审核（有链接）、已签署状态清晰分离
|
||
- **重试机制**：人脸识别、合同签署都支持失败重试
|
||
- **多渠道通知**：企业微信通知管理员新申请，短信通知用户合同就绪和认证完成
|
||
- **状态追踪**：每个环节都有明确的状态标识和时间戳记录
|
||
- **安全存储**：营业执照文件安全存储在七牛云，支持 CDN 加速访问
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### 新增域结构
|
||
|
||
```
|
||
internal/domains/
|
||
├── certification/ # 企业认证域
|
||
│ ├── entities/ # 实体层
|
||
│ │ ├── certification.go # 认证申请实体
|
||
│ │ ├── enterprise.go # 企业信息实体
|
||
│ │ └── contract.go # 电子合同实体
|
||
│ ├── dto/ # 数据传输对象
|
||
│ │ ├── certification_dto.go
|
||
│ │ ├── enterprise_dto.go
|
||
│ │ └── ocr_dto.go
|
||
│ ├── repositories/ # 仓储层
|
||
│ │ ├── certification_repository.go
|
||
│ │ ├── enterprise_repository.go
|
||
│ │ └── contract_repository.go
|
||
│ ├── services/ # 服务层
|
||
│ │ ├── certification_service.go
|
||
│ │ ├── enterprise_service.go
|
||
│ │ ├── ocr_service.go
|
||
│ │ └── face_verification_service.go
|
||
│ ├── handlers/ # 处理器层
|
||
│ │ ├── certification_handler.go
|
||
│ │ └── admin_certification_handler.go
|
||
│ ├── routes/ # 路由层
|
||
│ │ ├── certification_routes.go
|
||
│ │ └── admin_certification_routes.go
|
||
│ ├── events/ # 事件层
|
||
│ │ └── certification_events.go
|
||
│ ├── enums/ # 枚举定义
|
||
│ │ └── certification_status.go
|
||
│ └── migrations/ # 数据库迁移
|
||
├── finance/ # 财务域（独立域）
|
||
│ ├── entities/
|
||
│ │ └── wallet.go
|
||
│ ├── dto/
|
||
│ │ └── wallet_dto.go
|
||
│ ├── repositories/
|
||
│ │ └── wallet_repository.go
|
||
│ ├── services/
|
||
│ │ └── wallet_service.go
|
||
│ ├── handlers/
|
||
│ │ └── wallet_handler.go
|
||
│ ├── routes/
|
||
│ │ └── wallet_routes.go
|
||
│ └── migrations/
|
||
├── admin/ # 管理员域
|
||
│ ├── entities/
|
||
│ │ └── admin.go
|
||
│ ├── repositories/
|
||
│ │ └── admin_repository.go
|
||
│ ├── services/
|
||
│ │ └── admin_service.go
|
||
│ ├── handlers/
|
||
│ │ └── admin_handler.go
|
||
│ └── routes/
|
||
│ └── admin_routes.go
|
||
└── notification/ # 通知域（扩展）
|
||
├── services/
|
||
│ ├── notification_service.go
|
||
│ ├── wechat_work_service.go
|
||
│ └── enhanced_sms_service.go
|
||
└── providers/
|
||
├── wechat_work_provider.go
|
||
└── sms_template_provider.go
|
||
```
|
||
|
||
### 共享服务重构
|
||
|
||
```
|
||
internal/shared/
|
||
├── sms/ # 短信服务（现有，需扩展）
|
||
│ ├── sms_service.go # 基础短信服务
|
||
│ ├── template_service.go # 短信模板服务（新增）
|
||
│ └── notification_sms.go # 通知类短信服务（新增）
|
||
├── ocr/ # OCR服务（新增）
|
||
│ ├── baidu_ocr_service.go # 百度OCR实现
|
||
│ └── ocr_interface.go # OCR接口定义
|
||
├── storage/ # 文件存储服务（新增）
|
||
│ ├── qiniu_storage_service.go # 七牛云存储实现
|
||
│ └── storage_interface.go # 存储接口定义
|
||
└── third_party/ # 第三方服务（新增）
|
||
├── aliyun/
|
||
│ ├── face_verify_service.go # 阿里云人脸识别
|
||
│ └── sms_service.go # 阿里云短信服务
|
||
├── qiniu/
|
||
│ └── qiniu_client.go # 七牛云客户端
|
||
└── wechat_work/
|
||
└── wechat_work_api.go
|
||
```
|
||
|
||
## 📊 核心实体设计
|
||
|
||
### 认证状态枚举
|
||
|
||
```go
|
||
type CertificationStatus string
|
||
|
||
const (
|
||
StatusPending CertificationStatus = "pending" // 待开始
|
||
StatusEnterpriseSubmitted = "enterprise_submitted" // 企业信息已提交
|
||
StatusOCRProcessed = "ocr_processed" // OCR识别完成
|
||
StatusFaceVerified = "face_verified" // 人脸识别完成
|
||
StatusContractApplied = "contract_applied" // 已申请合同
|
||
StatusContractPending = "contract_pending" // 合同待审核
|
||
StatusContractApproved = "contract_approved" // 合同已审核（有链接）
|
||
StatusContractSigned = "contract_signed" // 合同已签署
|
||
StatusCompleted = "completed" // 认证完成
|
||
StatusRejected = "rejected" // 已拒绝
|
||
)
|
||
```
|
||
|
||
### 认证申请实体
|
||
|
||
```go
|
||
type Certification struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
UserID string `gorm:"type:varchar(36);not null;index"`
|
||
EnterpriseID string `gorm:"type:varchar(36);index"`
|
||
Status CertificationStatus `gorm:"type:varchar(50);not null;index"`
|
||
|
||
// 流程节点时间戳
|
||
InfoSubmittedAt *time.Time `json:"info_submitted_at"`
|
||
FaceVerifiedAt *time.Time `json:"face_verified_at"`
|
||
ContractAppliedAt *time.Time `json:"contract_applied_at"`
|
||
ContractApprovedAt *time.Time `json:"contract_approved_at"`
|
||
ContractSignedAt *time.Time `json:"contract_signed_at"`
|
||
CompletedAt *time.Time `json:"completed_at"`
|
||
|
||
// 审核信息
|
||
AdminID *string `gorm:"type:varchar(36)"`
|
||
ApprovalNotes string `gorm:"type:text"`
|
||
RejectReason string `gorm:"type:text"`
|
||
|
||
// 合同信息
|
||
ContractURL string `gorm:"type:varchar(500)"`
|
||
SigningURL string `gorm:"type:varchar(500)"`
|
||
SignedAt *time.Time
|
||
|
||
// OCR识别信息
|
||
OCRRequestID string `gorm:"type:varchar(100)"`
|
||
OCRConfidence float64 `gorm:"type:decimal(5,2)"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 企业信息实体
|
||
|
||
```go
|
||
type Enterprise struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
CertificationID string `gorm:"type:varchar(36);not null"`
|
||
|
||
// 企业四要素
|
||
CompanyName string `gorm:"type:varchar(255);not null"` // 企业名称
|
||
UnifiedSocialCode string `gorm:"type:varchar(50);not null"` // 统一社会信用代码
|
||
LegalPersonName string `gorm:"type:varchar(100);not null"` // 法定代表人姓名
|
||
LegalPersonID string `gorm:"type:varchar(50);not null"` // 法定代表人身份证号
|
||
|
||
// OCR识别结果
|
||
BusinessLicenseURL string `gorm:"type:varchar(500);not null"` // 营业执照图片URL
|
||
OCRRawData string `gorm:"type:text"` // OCR原始返回数据
|
||
OCRConfidence float64 `gorm:"type:decimal(5,2)"` // 识别置信度
|
||
|
||
// 验证状态
|
||
IsOCRVerified bool `gorm:"default:false"`
|
||
IsFaceVerified bool `gorm:"default:false"`
|
||
VerificationData string `gorm:"type:text"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 钱包实体（财务域）
|
||
|
||
```go
|
||
type Wallet struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
UserID string `gorm:"type:varchar(36);not null;uniqueIndex"`
|
||
|
||
// 钱包状态
|
||
IsActive bool `gorm:"default:true"`
|
||
Balance decimal.Decimal `gorm:"type:decimal(20,8);default:0"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 用户密钥实体（财务域）
|
||
|
||
```go
|
||
type UserSecrets struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
UserID string `gorm:"type:varchar(36);not null;uniqueIndex"`
|
||
AccessID string `gorm:"type:varchar(100);not null;uniqueIndex"`
|
||
AccessKey string `gorm:"type:varchar(255);not null"`
|
||
|
||
// 密钥状态
|
||
IsActive bool `gorm:"default:true"`
|
||
LastUsedAt *time.Time
|
||
ExpiresAt *time.Time
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 营业执照上传记录实体
|
||
|
||
```go
|
||
type LicenseUploadRecord struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
CertificationID string `gorm:"type:varchar(36);not null;index"`
|
||
UserID string `gorm:"type:varchar(36);not null;index"`
|
||
|
||
// 文件信息
|
||
OriginalFileName string `gorm:"type:varchar(255);not null"`
|
||
FileSize int64 `gorm:"not null"`
|
||
FileType string `gorm:"type:varchar(50);not null"`
|
||
FileURL string `gorm:"type:varchar(500);not null"`
|
||
QiNiuKey string `gorm:"type:varchar(255);not null"`
|
||
|
||
// OCR处理结果
|
||
OCRProcessed bool `gorm:"default:false"`
|
||
OCRSuccess bool `gorm:"default:false"`
|
||
OCRConfidence float64 `gorm:"type:decimal(5,2)"`
|
||
OCRRawData string `gorm:"type:text"`
|
||
OCRErrorMessage string `gorm:"type:varchar(500)"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 人脸识别记录实体
|
||
|
||
```go
|
||
type FaceVerifyRecord struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
CertificationID string `gorm:"type:varchar(36);not null;index"`
|
||
UserID string `gorm:"type:varchar(36);not null;index"`
|
||
|
||
// 阿里云人脸识别信息
|
||
CertifyID string `gorm:"type:varchar(100);not null"`
|
||
VerifyURL string `gorm:"type:varchar(500)"`
|
||
ReturnURL string `gorm:"type:varchar(500)"`
|
||
|
||
// 身份信息
|
||
RealName string `gorm:"type:varchar(100);not null"`
|
||
IDCardNumber string `gorm:"type:varchar(50);not null"`
|
||
|
||
// 验证结果
|
||
Status string `gorm:"type:varchar(50);not null"` // PROCESSING, SUCCESS, FAIL
|
||
ResultCode string `gorm:"type:varchar(50)"`
|
||
ResultMessage string `gorm:"type:varchar(500)"`
|
||
VerifyScore float64 `gorm:"type:decimal(5,2)"`
|
||
|
||
// 时间信息
|
||
InitiatedAt time.Time `gorm:"autoCreateTime"`
|
||
CompletedAt *time.Time
|
||
ExpiresAt time.Time `gorm:"not null"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 通知记录实体
|
||
|
||
```go
|
||
type NotificationRecord struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
CertificationID string `gorm:"type:varchar(36);index"`
|
||
UserID string `gorm:"type:varchar(36);index"`
|
||
|
||
// 通知类型和渠道
|
||
NotificationType string `gorm:"type:varchar(50);not null"` // SMS, WECHAT_WORK, EMAIL
|
||
NotificationScene string `gorm:"type:varchar(50);not null"` // ADMIN_NEW_APPLICATION, USER_CONTRACT_READY, etc.
|
||
|
||
// 接收方信息
|
||
Recipient string `gorm:"type:varchar(255);not null"`
|
||
|
||
// 消息内容
|
||
Title string `gorm:"type:varchar(255)"`
|
||
Content string `gorm:"type:text;not null"`
|
||
TemplateID string `gorm:"type:varchar(100)"`
|
||
TemplateParams string `gorm:"type:text"` // JSON格式
|
||
|
||
// 发送状态
|
||
Status string `gorm:"type:varchar(50);not null"` // PENDING, SENT, FAILED
|
||
ErrorMessage string `gorm:"type:varchar(500)"`
|
||
SentAt *time.Time
|
||
RetryCount int `gorm:"default:0"`
|
||
MaxRetryCount int `gorm:"default:3"`
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
### 合同记录实体
|
||
|
||
```go
|
||
type ContractRecord struct {
|
||
ID string `gorm:"primaryKey;type:varchar(36)"`
|
||
CertificationID string `gorm:"type:varchar(36);not null;index"`
|
||
UserID string `gorm:"type:varchar(36);not null;index"`
|
||
AdminID string `gorm:"type:varchar(36);index"`
|
||
|
||
// 合同信息
|
||
ContractType string `gorm:"type:varchar(50);not null"` // ENTERPRISE_CERTIFICATION
|
||
ContractURL string `gorm:"type:varchar(500)"`
|
||
SigningURL string `gorm:"type:varchar(500)"`
|
||
|
||
// 签署信息
|
||
SignatureData string `gorm:"type:text"`
|
||
SignedAt *time.Time
|
||
ClientIP string `gorm:"type:varchar(50)"`
|
||
UserAgent string `gorm:"type:varchar(500)"`
|
||
|
||
// 状态信息
|
||
Status string `gorm:"type:varchar(50);not null"` // PENDING, APPROVED, SIGNED, EXPIRED
|
||
ApprovalNotes string `gorm:"type:text"`
|
||
RejectReason string `gorm:"type:text"`
|
||
ExpiresAt *time.Time
|
||
|
||
CreatedAt time.Time `gorm:"autoCreateTime"`
|
||
UpdatedAt time.Time `gorm:"autoUpdateTime"`
|
||
DeletedAt gorm.DeletedAt `gorm:"index"`
|
||
}
|
||
```
|
||
|
||
## 🔄 状态管理设计
|
||
|
||
### 认证状态枚举扩展
|
||
|
||
```go
|
||
type CertificationStatus string
|
||
|
||
const (
|
||
// 主流程状态
|
||
StatusPending CertificationStatus = "pending" // 待开始
|
||
StatusInfoSubmitted = "info_submitted" // 企业信息已提交
|
||
StatusFaceVerified = "face_verified" // 人脸识别完成
|
||
StatusContractApplied = "contract_applied" // 已申请合同
|
||
StatusContractPending = "contract_pending" // 合同待审核
|
||
StatusContractApproved = "contract_approved" // 合同已审核（有链接）
|
||
StatusContractSigned = "contract_signed" // 合同已签署
|
||
StatusCompleted = "completed" // 认证完成
|
||
|
||
// 失败和重试状态
|
||
StatusFaceFailed = "face_failed" // 人脸识别失败
|
||
StatusSignFailed = "sign_failed" // 签署失败
|
||
StatusRejected = "rejected" // 已拒绝
|
||
)
|
||
```
|
||
|
||
### 状态转换规则
|
||
|
||
```go
|
||
type StateTransition struct {
|
||
From CertificationStatus
|
||
To CertificationStatus
|
||
Action string
|
||
AllowUser bool // 是否允许用户操作
|
||
AllowAdmin bool // 是否允许管理员操作
|
||
}
|
||
|
||
var stateTransitions = []StateTransition{
|
||
// 正常流程转换
|
||
{StatusPending, StatusInfoSubmitted, "submit_info", true, false},
|
||
{StatusInfoSubmitted, StatusFaceVerified, "face_verify", true, false},
|
||
{StatusFaceVerified, StatusContractApplied, "apply_contract", true, false},
|
||
{StatusContractApplied, StatusContractPending, "system_process", false, false}, // 系统自动
|
||
{StatusContractPending, StatusContractApproved, "admin_approve", false, true},
|
||
{StatusContractApproved, StatusContractSigned, "user_sign", true, false},
|
||
{StatusContractSigned, StatusCompleted, "system_complete", false, false}, // 系统自动
|
||
|
||
// 失败和重试转换
|
||
{StatusInfoSubmitted, StatusFaceFailed, "face_fail", false, false},
|
||
{StatusFaceFailed, StatusInfoSubmitted, "retry_face", true, false},
|
||
{StatusContractPending, StatusRejected, "admin_reject", false, true},
|
||
{StatusRejected, StatusInfoSubmitted, "restart_process", true, false},
|
||
{StatusContractApproved, StatusSignFailed, "sign_fail", false, false},
|
||
{StatusSignFailed, StatusContractApproved, "retry_sign", true, false},
|
||
}
|
||
```
|
||
|
||
### 状态管理服务
|
||
|
||
```go
|
||
type CertificationStateMachine struct {
|
||
transitions map[CertificationStatus][]CertificationStatus
|
||
repo *CertificationRepository
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func NewCertificationStateMachine(repo *CertificationRepository, logger *zap.Logger) *CertificationStateMachine {
|
||
sm := &CertificationStateMachine{
|
||
transitions: make(map[CertificationStatus][]CertificationStatus),
|
||
repo: repo,
|
||
logger: logger,
|
||
}
|
||
|
||
// 构建状态转换映射
|
||
for _, transition := range stateTransitions {
|
||
sm.transitions[transition.From] = append(sm.transitions[transition.From], transition.To)
|
||
}
|
||
|
||
return sm
|
||
}
|
||
|
||
func (sm *CertificationStateMachine) CanTransition(from, to CertificationStatus) bool {
|
||
allowedStates, exists := sm.transitions[from]
|
||
if !exists {
|
||
return false
|
||
}
|
||
|
||
for _, allowedState := range allowedStates {
|
||
if allowedState == to {
|
||
return true
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
|
||
func (sm *CertificationStateMachine) TransitionTo(ctx context.Context, certificationID string, newStatus CertificationStatus, operatorID string, notes string) error {
|
||
// 获取当前认证记录
|
||
certification, err := sm.repo.GetByID(ctx, certificationID)
|
||
if err != nil {
|
||
return fmt.Errorf("获取认证记录失败: %w", err)
|
||
}
|
||
|
||
// 检查状态转换是否合法
|
||
if !sm.CanTransition(certification.Status, newStatus) {
|
||
return fmt.Errorf("不允许从状态 %s 转换到 %s", certification.Status, newStatus)
|
||
}
|
||
|
||
// 更新状态和时间戳
|
||
oldStatus := certification.Status
|
||
certification.Status = newStatus
|
||
sm.updateTimestamp(certification, newStatus)
|
||
|
||
// 记录操作信息
|
||
if operatorID != "" {
|
||
certification.AdminID = &operatorID
|
||
}
|
||
if notes != "" {
|
||
certification.ApprovalNotes = notes
|
||
}
|
||
|
||
// 保存更新
|
||
if err := sm.repo.Update(ctx, certification); err != nil {
|
||
return fmt.Errorf("更新认证状态失败: %w", err)
|
||
}
|
||
|
||
sm.logger.Info("认证状态已更新",
|
||
zap.String("certification_id", certificationID),
|
||
zap.String("from_status", string(oldStatus)),
|
||
zap.String("to_status", string(newStatus)),
|
||
zap.String("operator_id", operatorID))
|
||
|
||
return nil
|
||
}
|
||
|
||
func (sm *CertificationStateMachine) updateTimestamp(cert *entities.Certification, status CertificationStatus) {
|
||
now := time.Now()
|
||
switch status {
|
||
case StatusInfoSubmitted:
|
||
cert.InfoSubmittedAt = &now
|
||
case StatusFaceVerified:
|
||
cert.FaceVerifiedAt = &now
|
||
case StatusContractApplied:
|
||
cert.ContractAppliedAt = &now
|
||
case StatusContractApproved:
|
||
cert.ContractApprovedAt = &now
|
||
case StatusContractSigned:
|
||
cert.ContractSignedAt = &now
|
||
case StatusCompleted:
|
||
cert.CompletedAt = &now
|
||
}
|
||
}
|
||
|
||
func (sm *CertificationStateMachine) GetNextAllowedStates(currentStatus CertificationStatus) []CertificationStatus {
|
||
return sm.transitions[currentStatus]
|
||
}
|
||
|
||
func (sm *CertificationStateMachine) GetRetryAction(status CertificationStatus) *string {
|
||
retryMap := map[CertificationStatus]string{
|
||
StatusFaceFailed: "重新进行人脸识别",
|
||
StatusSignFailed: "重新签署合同",
|
||
StatusRejected: "重新提交申请",
|
||
}
|
||
|
||
if action, exists := retryMap[status]; exists {
|
||
return &action
|
||
}
|
||
return nil
|
||
}
|
||
```
|
||
|
||
## 📱 分阶段接口设计
|
||
|
||
### 阶段 1: 上传营业执照（前端交互）
|
||
|
||
```http
|
||
POST /api/v1/certification/upload-license
|
||
Content-Type: multipart/form-data
|
||
|
||
{
|
||
"business_license": "file", // 营业执照图片文件
|
||
"user_id": "string" // 用户ID
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "营业执照上传成功",
|
||
"data": {
|
||
"upload_record_id": "upload_123456",
|
||
"license_url": "https://qiniu.example.com/licenses/cert_123456.jpg",
|
||
"ocr_result": {
|
||
"success": true,
|
||
"confidence": 95.5,
|
||
"enterprise_info": {
|
||
"company_name": "示例科技有限公司",
|
||
"unified_social_code": "91110000123456789X",
|
||
"legal_person_name": "张三",
|
||
"legal_person_id": "110101199001011234"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**OCR 失败响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "营业执照上传成功，OCR识别失败",
|
||
"data": {
|
||
"upload_record_id": "upload_123456",
|
||
"license_url": "https://qiniu.example.com/licenses/cert_123456.jpg",
|
||
"ocr_result": {
|
||
"success": false,
|
||
"error": "图片模糊，无法识别企业信息",
|
||
"enterprise_info": {
|
||
"company_name": "",
|
||
"unified_social_code": "",
|
||
"legal_person_name": "",
|
||
"legal_person_id": ""
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 2: 提交企业信息 (pending → info_submitted)
|
||
|
||
```http
|
||
POST /api/v1/certification/submit-enterprise-info
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"upload_record_id": "upload_123456",
|
||
"company_name": "示例科技有限公司",
|
||
"unified_social_code": "91110000123456789X",
|
||
"legal_person_name": "张三",
|
||
"legal_person_id": "110101199001011234"
|
||
}
|
||
```
|
||
|
||
**信息提交成功:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "企业信息提交成功",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "info_submitted",
|
||
"next_step": "进行人脸识别",
|
||
"next_action": "face_verify"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 3: 人脸识别 (info_submitted → face_verified/face_failed)
|
||
|
||
```http
|
||
POST /api/v1/certification/{certification_id}/face-verify
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"legal_person_name": "张三",
|
||
"legal_person_id": "110101199001011234",
|
||
"return_url": "https://yourdomain.com/certification/face-result"
|
||
}
|
||
```
|
||
|
||
**人脸识别初始化成功:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "人脸识别初始化成功",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"certify_id": "face_certify_789",
|
||
"verify_url": "https://cloudauth.aliyun.com/web/verify?token=xxx",
|
||
"status": "face_processing",
|
||
"next_step": "请在30分钟内完成人脸识别",
|
||
"expire_time": "2024-01-15T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
**人脸识别结果查询:**
|
||
|
||
```http
|
||
GET /api/v1/certification/{certification_id}/face-result
|
||
```
|
||
|
||
**人脸识别成功:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "人脸识别成功",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "face_verified",
|
||
"verify_result": "通过",
|
||
"next_step": "申请电子合同",
|
||
"next_action": "apply_contract"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 4: 申请电子合同 (face_verified → contract_applied → contract_pending)
|
||
|
||
```http
|
||
POST /api/v1/certification/{certification_id}/apply-contract
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"contact_phone": "13800138000",
|
||
"contact_email": "example@company.com"
|
||
}
|
||
```
|
||
|
||
**申请成功:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "电子合同申请已提交",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "contract_applied",
|
||
"next_step": "系统正在处理申请",
|
||
"estimated_time": "1-3个工作日"
|
||
}
|
||
}
|
||
```
|
||
|
||
**系统自动转换状态查询:**
|
||
|
||
```http
|
||
GET /api/v1/certification/{certification_id}/status
|
||
```
|
||
|
||
**转换为待审核状态:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "合同申请已进入审核队列",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "contract_pending",
|
||
"next_step": "等待管理员审核并上传合同链接",
|
||
"estimated_time": "1-3个工作日",
|
||
"notification": "已通过企业微信通知管理员，审核结果将通过短信通知您"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 5: 管理员审核和合同链接上传 (contract_pending → contract_approved/rejected)
|
||
|
||
**管理员获取待审核列表:**
|
||
|
||
```http
|
||
GET /api/v1/admin/certifications?status=contract_pending
|
||
```
|
||
|
||
**管理员审核通过并上传合同链接:**
|
||
|
||
```http
|
||
POST /api/v1/admin/certifications/{certification_id}/approve
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"admin_id": "admin_123",
|
||
"contract_signing_url": "https://contract-platform.com/sign/contract_456",
|
||
"approval_notes": "企业信息核实无误，准予签署合同",
|
||
"expire_hours": 72
|
||
}
|
||
```
|
||
|
||
**审核通过响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "审核通过，合同链接已上传",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "contract_approved",
|
||
"signing_url": "https://contract-platform.com/sign/contract_456",
|
||
"expire_time": "2024-01-18T15:00:00Z",
|
||
"next_step": "已通过短信通知用户签署合同"
|
||
}
|
||
}
|
||
```
|
||
|
||
**管理员拒绝申请:**
|
||
|
||
```http
|
||
POST /api/v1/admin/certifications/{certification_id}/reject
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"admin_id": "admin_123",
|
||
"reject_reason": "企业信息与工商数据不符，请重新提交",
|
||
"allow_retry": true
|
||
}
|
||
```
|
||
|
||
**拒绝响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "申请已拒绝",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "rejected",
|
||
"reject_reason": "企业信息与工商数据不符，请重新提交",
|
||
"next_step": "已通过短信通知用户重新申请"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 6: 用户查看合同链接并签署 (contract_approved → contract_signed/sign_failed)
|
||
|
||
**用户查询状态（收到短信通知后）:**
|
||
|
||
```http
|
||
GET /api/v1/certification/{certification_id}/status
|
||
```
|
||
|
||
**用户看到合同链接:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "合同已准备就绪",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "contract_approved",
|
||
"contract_info": {
|
||
"signing_url": "https://contract-platform.com/sign/contract_456",
|
||
"expire_time": "2024-01-18T15:00:00Z",
|
||
"remaining_hours": 48
|
||
},
|
||
"next_step": "请点击链接签署电子合同",
|
||
"next_action": "sign_contract"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 7: 用户签署合同 (contract_approved → contract_signed/sign_failed)
|
||
|
||
```http
|
||
POST /api/v1/certification/{certification_id}/sign-contract
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"signature_data": "base64_signature_string",
|
||
"sign_timestamp": "2024-01-16T14:30:00Z",
|
||
"client_ip": "192.168.1.100"
|
||
}
|
||
```
|
||
|
||
**签署成功:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "合同签署成功",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "contract_signed",
|
||
"signed_at": "2024-01-16T14:30:00Z",
|
||
"next_step": "正在生成钱包账户",
|
||
"estimated_completion": "2-5分钟"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 阶段 8: 认证完成 (contract_signed → completed)
|
||
|
||
**系统自动完成，用户查询最终状态:**
|
||
|
||
```http
|
||
GET /api/v1/certification/{certification_id}/final-result
|
||
```
|
||
|
||
**认证完成响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "企业认证已完成",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"status": "completed",
|
||
"completed_at": "2024-01-16T14:35:00Z",
|
||
"wallet_info": {
|
||
"wallet_id": "wallet_789",
|
||
"balance": "0.00",
|
||
"is_active": true
|
||
},
|
||
"user_secrets": {
|
||
"access_id": "AK_123456789",
|
||
"access_key": "SK_abcdef123456", // 加密显示
|
||
"is_active": true
|
||
},
|
||
"certificate_url": "https://cdn.example.com/certificates/cert_123456.pdf"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 状态查询统一接口
|
||
|
||
```http
|
||
GET /api/v1/certification/status?user_id={user_id}
|
||
```
|
||
|
||
**通用状态响应格式:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "状态查询成功",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"user_id": "user_123",
|
||
"current_status": "face_verified",
|
||
"current_status_name": "人脸识别完成",
|
||
"progress": {
|
||
"total_steps": 8,
|
||
"completed_steps": 4,
|
||
"percentage": 50
|
||
},
|
||
"timeline": [
|
||
{
|
||
"status": "pending",
|
||
"status_name": "待开始",
|
||
"completed_at": "2024-01-15T09:00:00Z",
|
||
"is_completed": true
|
||
},
|
||
{
|
||
"status": "info_submitted",
|
||
"status_name": "企业信息已提交",
|
||
"completed_at": "2024-01-15T09:05:00Z",
|
||
"is_completed": true
|
||
},
|
||
{
|
||
"status": "face_verified",
|
||
"status_name": "人脸识别完成",
|
||
"completed_at": "2024-01-15T09:15:00Z",
|
||
"is_completed": true
|
||
},
|
||
{
|
||
"status": "contract_applied",
|
||
"status_name": "已申请合同",
|
||
"completed_at": "2024-01-15T09:20:00Z",
|
||
"is_completed": true
|
||
},
|
||
{
|
||
"status": "contract_pending",
|
||
"status_name": "合同待审核",
|
||
"completed_at": null,
|
||
"is_completed": false,
|
||
"is_current": true
|
||
}
|
||
],
|
||
"next_action": {
|
||
"action": "apply_contract",
|
||
"action_name": "申请电子合同",
|
||
"description": "请点击申请电子合同按钮继续",
|
||
"can_retry": false
|
||
},
|
||
"retry_info": null,
|
||
"estimated_completion": "2024-01-18T17:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔄 重试机制接口
|
||
|
||
**通用重试接口:**
|
||
|
||
```http
|
||
POST /api/v1/certification/{certification_id}/retry
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"retry_type": "face_failed|sign_failed|rejected",
|
||
"additional_data": {} // 根据重试类型提供额外数据
|
||
}
|
||
```
|
||
|
||
**重试响应:**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "重试请求已处理",
|
||
"data": {
|
||
"certification_id": "cert_123456",
|
||
"old_status": "face_failed",
|
||
"new_status": "info_submitted",
|
||
"retry_count": 2,
|
||
"max_retry_count": 3,
|
||
"next_step": "请重新进行人脸识别"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 核心服务设计
|
||
|
||
### 企业认证服务
|
||
|
||
```go
|
||
type CertificationService struct {
|
||
// 依赖注入
|
||
repo *CertificationRepository
|
||
enterpriseRepo *EnterpriseRepository
|
||
ocrService *OCRService
|
||
faceVerificationSvc *AliYunFaceVerifyService
|
||
notificationService *NotificationService
|
||
walletService *WalletService
|
||
eventBus interfaces.EventBus
|
||
logger *zap.Logger
|
||
}
|
||
|
||
// 核心业务方法
|
||
func (s *CertificationService) SubmitBusinessLicense(ctx context.Context, userID string, licenseImageURL string) (*dto.CertificationResponse, error)
|
||
func (s *CertificationService) ConfirmEnterpriseInfo(ctx context.Context, certificationID string, req *dto.ConfirmEnterpriseInfoRequest) error
|
||
func (s *CertificationService) PerformFaceVerification(ctx context.Context, certificationID string, req *dto.FaceVerificationRequest) error
|
||
func (s *CertificationService) ApplyForContract(ctx context.Context, certificationID string) error
|
||
func (s *CertificationService) SignContract(ctx context.Context, certificationID string, signatureData string) error
|
||
func (s *CertificationService) GetCertificationStatus(ctx context.Context, userID string) (*dto.CertificationStatusResponse, error)
|
||
```
|
||
|
||
### 百度 OCR 服务
|
||
|
||
```go
|
||
type BaiduOCRService struct {
|
||
client *ocr.Client
|
||
appID string
|
||
apiKey string
|
||
secretKey string
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func (s *BaiduOCRService) RecognizeBusinessLicense(ctx context.Context, imageURL string) (*dto.BusinessLicenseOCRResult, error)
|
||
func (s *BaiduOCRService) ValidateOCRResult(result *dto.BusinessLicenseOCRResult) error
|
||
```
|
||
|
||
### 阿里云人脸识别服务
|
||
|
||
```go
|
||
type AliYunFaceVerifyService struct {
|
||
client *cloudauth.Client
|
||
accessKeyId string
|
||
accessSecret string
|
||
regionId string
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func (s *AliYunFaceVerifyService) InitFaceVerify(ctx context.Context, req *dto.FaceVerifyInitRequest) (*dto.FaceVerifyInitResponse, error)
|
||
func (s *AliYunFaceVerifyService) DescribeFaceVerify(ctx context.Context, certifyId string) (*dto.FaceVerifyResultResponse, error)
|
||
func (s *AliYunFaceVerifyService) ValidateFaceVerifyResult(ctx context.Context, certifyId string) error
|
||
```
|
||
|
||
### 通知服务扩展
|
||
|
||
```go
|
||
type NotificationService struct {
|
||
smsService *sms.Service
|
||
wechatWorkService *WechatWorkService
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func (s *NotificationService) NotifyAdminNewApplication(ctx context.Context, certification *entities.Certification) error
|
||
func (s *NotificationService) NotifyUserContractReady(ctx context.Context, userPhone, contractURL string) error
|
||
func (s *NotificationService) NotifyUserCertificationCompleted(ctx context.Context, userPhone string, accessID string) error
|
||
```
|
||
|
||
### 七牛云存储服务
|
||
|
||
```go
|
||
type QiNiuStorageService struct {
|
||
accessKey string
|
||
secretKey string
|
||
bucket string
|
||
domain string
|
||
region string
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func (s *QiNiuStorageService) UploadFile(ctx context.Context, fileBytes []byte, fileName string) (*dto.UploadResult, error)
|
||
func (s *QiNiuStorageService) GenerateUploadToken(ctx context.Context, key string) (string, error)
|
||
func (s *QiNiuStorageService) GetFileURL(ctx context.Context, key string) string
|
||
func (s *QiNiuStorageService) DeleteFile(ctx context.Context, key string) error
|
||
```
|
||
|
||
### 营业执照处理服务
|
||
|
||
```go
|
||
type LicenseProcessService struct {
|
||
ocrService *BaiduOCRService
|
||
storageService *QiNiuStorageService
|
||
logger *zap.Logger
|
||
}
|
||
|
||
func (s *LicenseProcessService) ProcessLicense(ctx context.Context, fileBytes []byte, userID string) (*dto.LicenseProcessResult, error) {
|
||
// 1. 上传文件到七牛云
|
||
uploadResult, err := s.storageService.UploadFile(ctx, fileBytes, generateFileName(userID))
|
||
if err != nil {
|
||
return nil, fmt.Errorf("文件上传失败: %w", err)
|
||
}
|
||
|
||
// 2. OCR识别营业执照
|
||
ocrResult, err := s.ocrService.RecognizeBusinessLicense(ctx, uploadResult.URL)
|
||
if err != nil {
|
||
s.logger.Warn("OCR识别失败", zap.Error(err))
|
||
// OCR失败不影响整体流程，返回空的企业信息供用户手动填写
|
||
}
|
||
|
||
return &dto.LicenseProcessResult{
|
||
LicenseURL: uploadResult.URL,
|
||
EnterpriseInfo: ocrResult,
|
||
OCRSuccess: err == nil,
|
||
OCRError: getErrorMessage(err),
|
||
}, nil
|
||
}
|
||
```
|
||
|
||
## 🌐 API 设计
|
||
|
||
### 用户端 API
|
||
|
||
```
|
||
POST /api/v1/certification/submit-license # 提交营业执照
|
||
PUT /api/v1/certification/{id}/confirm-info # 确认企业信息
|
||
POST /api/v1/certification/{id}/face-verify # 人脸识别
|
||
POST /api/v1/certification/{id}/apply-contract # 申请电子合同
|
||
POST /api/v1/certification/{id}/sign-contract # 签署合同
|
||
GET /api/v1/certification/status # 查询认证状态
|
||
GET /api/v1/certification/{id} # 获取认证详情
|
||
```
|
||
|
||
### 管理员端 API
|
||
|
||
```
|
||
GET /api/v1/admin/certifications # 获取待审核申请列表
|
||
GET /api/v1/admin/certifications/{id} # 获取认证详情
|
||
POST /api/v1/admin/certifications/{id}/approve # 审核通过并上传合同链接
|
||
POST /api/v1/admin/certifications/{id}/reject # 审核拒绝
|
||
PUT /api/v1/admin/certifications/{id}/contract # 上传合同签署链接
|
||
```
|
||
|
||
### 财务 API
|
||
|
||
```
|
||
GET /api/v1/finance/wallet # 获取钱包信息
|
||
GET /api/v1/finance/wallet/balance # 获取余额
|
||
GET /api/v1/finance/wallet/transactions # 获取交易记录
|
||
GET /api/v1/finance/secrets # 获取用户密钥信息
|
||
POST /api/v1/finance/secrets/regenerate # 重新生成Access Key
|
||
```
|
||
|
||
## 🗄️ 数据库设计
|
||
|
||
### 新增数据表
|
||
|
||
```sql
|
||
-- 认证申请表
|
||
CREATE TABLE certifications (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
user_id VARCHAR(36) NOT NULL,
|
||
enterprise_id VARCHAR(36),
|
||
status VARCHAR(50) NOT NULL,
|
||
info_submitted_at DATETIME,
|
||
face_verified_at DATETIME,
|
||
contract_applied_at DATETIME,
|
||
contract_approved_at DATETIME,
|
||
contract_signed_at DATETIME,
|
||
completed_at DATETIME,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_status (status),
|
||
INDEX idx_created_at (created_at)
|
||
);
|
||
|
||
-- 企业信息表
|
||
CREATE TABLE enterprises (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
certification_id VARCHAR(36) NOT NULL,
|
||
company_name VARCHAR(255) NOT NULL,
|
||
unified_social_code VARCHAR(50) NOT NULL,
|
||
legal_person_name VARCHAR(100) NOT NULL,
|
||
legal_person_id VARCHAR(50) NOT NULL,
|
||
license_upload_record_id VARCHAR(36) NOT NULL, -- 关联营业执照上传记录
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_certification_id (certification_id),
|
||
INDEX idx_unified_social_code (unified_social_code),
|
||
INDEX idx_license_upload_record_id (license_upload_record_id)
|
||
);
|
||
|
||
-- 钱包表
|
||
CREATE TABLE wallets (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
user_id VARCHAR(36) NOT NULL UNIQUE,
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
balance DECIMAL(20,8) DEFAULT 0,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_user_id (user_id)
|
||
);
|
||
|
||
-- 用户密钥表
|
||
CREATE TABLE user_secrets (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
user_id VARCHAR(36) NOT NULL UNIQUE,
|
||
access_id VARCHAR(100) NOT NULL UNIQUE,
|
||
access_key VARCHAR(255) NOT NULL,
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
last_used_at DATETIME,
|
||
expires_at DATETIME,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_access_id (access_id)
|
||
);
|
||
|
||
-- 营业执照上传记录表
|
||
CREATE TABLE license_upload_records (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
certification_id VARCHAR(36),
|
||
user_id VARCHAR(36) NOT NULL,
|
||
original_file_name VARCHAR(255) NOT NULL,
|
||
file_size BIGINT NOT NULL,
|
||
file_type VARCHAR(50) NOT NULL,
|
||
file_url VARCHAR(500) NOT NULL,
|
||
qiniu_key VARCHAR(255) NOT NULL,
|
||
ocr_processed BOOLEAN DEFAULT FALSE,
|
||
ocr_success BOOLEAN DEFAULT FALSE,
|
||
ocr_confidence DECIMAL(5,2),
|
||
ocr_raw_data TEXT,
|
||
ocr_error_message VARCHAR(500),
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_certification_id (certification_id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_qiniu_key (qiniu_key)
|
||
);
|
||
|
||
-- 人脸识别记录表
|
||
CREATE TABLE face_verify_records (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
certification_id VARCHAR(36) NOT NULL,
|
||
user_id VARCHAR(36) NOT NULL,
|
||
certify_id VARCHAR(100) NOT NULL,
|
||
verify_url VARCHAR(500),
|
||
return_url VARCHAR(500),
|
||
real_name VARCHAR(100) NOT NULL,
|
||
id_card_number VARCHAR(50) NOT NULL,
|
||
status VARCHAR(50) NOT NULL,
|
||
result_code VARCHAR(50),
|
||
result_message VARCHAR(500),
|
||
verify_score DECIMAL(5,2),
|
||
initiated_at DATETIME NOT NULL,
|
||
completed_at DATETIME,
|
||
expires_at DATETIME NOT NULL,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_certification_id (certification_id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_certify_id (certify_id),
|
||
INDEX idx_status (status)
|
||
);
|
||
|
||
-- 通知记录表
|
||
CREATE TABLE notification_records (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
certification_id VARCHAR(36),
|
||
user_id VARCHAR(36),
|
||
notification_type VARCHAR(50) NOT NULL,
|
||
notification_scene VARCHAR(50) NOT NULL,
|
||
recipient VARCHAR(255) NOT NULL,
|
||
title VARCHAR(255),
|
||
content TEXT NOT NULL,
|
||
template_id VARCHAR(100),
|
||
template_params TEXT,
|
||
status VARCHAR(50) NOT NULL,
|
||
error_message VARCHAR(500),
|
||
sent_at DATETIME,
|
||
retry_count INT DEFAULT 0,
|
||
max_retry_count INT DEFAULT 3,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_certification_id (certification_id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_status (status),
|
||
INDEX idx_notification_type (notification_type)
|
||
);
|
||
|
||
-- 合同记录表
|
||
CREATE TABLE contract_records (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
certification_id VARCHAR(36) NOT NULL,
|
||
user_id VARCHAR(36) NOT NULL,
|
||
admin_id VARCHAR(36),
|
||
contract_type VARCHAR(50) NOT NULL,
|
||
contract_url VARCHAR(500),
|
||
signing_url VARCHAR(500),
|
||
signature_data TEXT,
|
||
signed_at DATETIME,
|
||
client_ip VARCHAR(50),
|
||
user_agent VARCHAR(500),
|
||
status VARCHAR(50) NOT NULL,
|
||
approval_notes TEXT,
|
||
reject_reason TEXT,
|
||
expires_at DATETIME,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_certification_id (certification_id),
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_admin_id (admin_id),
|
||
INDEX idx_status (status)
|
||
);
|
||
|
||
-- 管理员表
|
||
CREATE TABLE admins (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
username VARCHAR(100) NOT NULL UNIQUE,
|
||
password VARCHAR(255) NOT NULL,
|
||
name VARCHAR(100) NOT NULL,
|
||
email VARCHAR(255),
|
||
phone VARCHAR(20),
|
||
is_active BOOLEAN DEFAULT TRUE,
|
||
last_login_at DATETIME,
|
||
created_at DATETIME NOT NULL,
|
||
updated_at DATETIME NOT NULL,
|
||
deleted_at DATETIME,
|
||
|
||
INDEX idx_username (username)
|
||
);
|
||
```
|
||
|
||
## 🚀 分阶段实施计划
|
||
|
||
### ✅ 阶段一：基础架构搭建（3-4 天）- 已完成
|
||
|
||
#### 1.1 创建域结构
|
||
|
||
- [x] 创建 `certification` 域的完整目录结构
|
||
- [x] 创建 `finance` 域的完整目录结构
|
||
- [x] 创建 `admin` 域的基础结构
|
||
- [x] 定义核心实体和枚举类型
|
||
|
||
#### 1.2 数据库层
|
||
|
||
- [x] 使用 GORM AutoMigrate 进行数据库迁移（已更新）
|
||
- [x] 实现基础的 Repository 接口和实现
|
||
- [x] 添加必要的数据库索引和约束
|
||
|
||
#### 1.3 共享服务扩展
|
||
|
||
- [x] 扩展短信服务支持模板化消息
|
||
- [x] 创建百度 OCR 服务基础架构
|
||
- [x] 实现七牛云存储服务
|
||
- [x] 实现企业微信通知服务基础结构
|
||
|
||
### ✅ 阶段二：核心业务逻辑（5-6 天）- 已完成
|
||
|
||
#### 2.1 认证服务核心功能
|
||
|
||
- [x] 实现营业执照上传、存储和 OCR 识别一体化服务
|
||
- [x] 实现企业信息确认功能
|
||
- [x] 实现人脸识别接口
|
||
- [x] 实现申请电子合同功能
|
||
- [x] 实现状态查询功能
|
||
|
||
#### 2.2 状态管理
|
||
|
||
- [x] 实现认证状态机（第一阶段已完成）
|
||
- [x] 添加状态转换验证
|
||
- [x] 实现状态变更事件发布
|
||
|
||
#### 2.3 基础 API 接口
|
||
|
||
- [x] 实现用户端认证相关 API
|
||
- [x] 添加参数验证和错误处理
|
||
- [x] 完善 API 响应格式
|
||
|
||
### ✅ 阶段三：第三方集成（4-5 天）- 已完成
|
||
|
||
#### 3.1 百度 OCR 和七牛云存储集成
|
||
|
||
- [x] 实现七牛云文件上传服务
|
||
- [x] 实现百度 OCR API 调用
|
||
- [x] 处理 OCR 识别结果解析
|
||
- [x] 添加 OCR 识别置信度验证
|
||
- [x] 实现营业执照处理一体化服务
|
||
|
||
#### 3.2 阿里云人脸识别集成
|
||
|
||
- [ ] 集成阿里云 InitFaceVerify API
|
||
- [ ] 实现人脸识别初始化流程
|
||
- [ ] 实现人脸识别结果查询
|
||
- [ ] 添加人脸识别状态验证
|
||
|
||
#### 3.3 通知服务完善
|
||
|
||
- [x] 实现企业微信机器人通知
|
||
- [ ] 扩展短信模板支持认证流程
|
||
- [ ] 添加通知发送失败重试机制
|
||
|
||
### 阶段四：管理员功能（3-4 天）
|
||
|
||
#### 4.1 管理员系统
|
||
|
||
- [ ] 实现管理员登录认证
|
||
- [ ] 创建管理员权限管理
|
||
- [ ] 实现管理员操作日志
|
||
|
||
#### 4.2 审核功能
|
||
|
||
- [ ] 实现待审核申请列表
|
||
- [ ] 实现认证详情查看
|
||
- [ ] 实现审核通过/拒绝功能
|
||
- [ ] 实现合同链接上传功能
|
||
|
||
#### 4.3 管理后台 API
|
||
|
||
- [ ] 完善管理员端 API 接口
|
||
- [ ] 添加分页和筛选功能
|
||
- [ ] 实现审核操作记录
|
||
|
||
### ✅ 阶段五：财务系统（3-4 天）- 已完成
|
||
|
||
#### 5.1 财务服务
|
||
|
||
- [x] 实现钱包生成功能
|
||
- [x] 生成 Access ID 和 Access Key
|
||
- [x] 实现钱包状态管理
|
||
|
||
#### 5.2 财务 API
|
||
|
||
- [x] 实现钱包信息查询
|
||
- [x] 实现 Access Key 重新生成
|
||
- [x] 添加钱包安全验证
|
||
|
||
#### 5.3 认证完成流程
|
||
|
||
- [x] 完善认证完成后的钱包创建
|
||
- [x] 实现认证完成通知
|
||
- [x] 添加钱包激活功能
|
||
|
||
### 🔄 阶段六：事件驱动和完善（2-3 天）
|
||
|
||
#### 6.1 事件系统
|
||
|
||
- [ ] 实现完整的认证事件定义
|
||
- [ ] 添加事件处理器
|
||
- [ ] 完善事件驱动的通知机制
|
||
|
||
#### 6.2 系统完善
|
||
|
||
- [ ] 添加全面的日志记录
|
||
- [ ] 实现性能监控和指标
|
||
- [ ] 完善错误处理和回滚机制
|
||
|
||
#### 6.3 测试和文档
|
||
|
||
- [ ] 编写单元测试
|
||
- [ ] 完善 API 文档
|
||
- [ ] 编写操作手册
|
||
|
||
## 🔧 技术要点
|
||
|
||
### 第三方服务配置
|
||
|
||
#### 百度 OCR 配置
|
||
|
||
```yaml
|
||
baidu_ocr:
|
||
app_id: "your_app_id"
|
||
api_key: "your_api_key"
|
||
secret_key: "your_secret_key"
|
||
endpoint: "https://aip.baidubce.com"
|
||
timeout: 30s
|
||
```
|
||
|
||
#### 七牛云存储配置
|
||
|
||
```yaml
|
||
qiniu_storage:
|
||
access_key: "your_access_key"
|
||
secret_key: "your_secret_key"
|
||
bucket: "enterprise-certification"
|
||
domain: "https://qiniu.example.com"
|
||
region: "z0" # 华东区域
|
||
timeout: 30s
|
||
```
|
||
|
||
#### 阿里云人脸识别配置
|
||
|
||
```yaml
|
||
aliyun_face_verify:
|
||
access_key_id: "your_access_key_id"
|
||
access_key_secret: "your_access_key_secret"
|
||
region_id: "cn-hangzhou"
|
||
endpoint: "https://cloudauth.cn-hangzhou.aliyuncs.com"
|
||
timeout: 30s
|
||
```
|
||
|
||
#### 企业微信配置
|
||
|
||
```yaml
|
||
wechat_work:
|
||
webhook_url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
|
||
timeout: 10s
|
||
```
|
||
|
||
### 安全考虑
|
||
|
||
- Access Key 采用加密存储
|
||
- 营业执照图片需要安全存储
|
||
- 人脸识别数据不保存原始图片
|
||
- 管理员操作需要审计日志
|
||
|
||
### 性能优化
|
||
|
||
- OCR 识别结果缓存
|
||
- 状态查询接口优化
|
||
- 批量通知处理
|
||
- 数据库查询优化
|
||
|
||
## 📝 注意事项
|
||
|
||
1. **状态一致性**：所有状态变更都需要通过事务保证一致性
|
||
2. **幂等性**：关键操作需要支持幂等，避免重复处理
|
||
3. **错误处理**：第三方服务调用需要完善的错误处理和重试机制
|
||
4. **数据安全**：敏感信息需要加密存储
|
||
5. **监控告警**：关键业务节点需要监控和告警
|
||
6. **备份恢复**：重要数据需要定期备份
|
||
|
||
## 🎯 成功标准
|
||
|
||
- [ ] 用户可以顺利完成企业认证全流程
|
||
- [ ] 管理员可以高效处理认证审核
|
||
- [ ] 系统可以自动识别营业执照信息
|
||
- [ ] 通知机制工作正常
|
||
- [ ] 财务系统功能完整
|
||
- [ ] API 接口稳定可靠
|
||
- [ ] 系统性能满足要求
|
||
- [ ] 代码质量符合规范
|
||
|
||
---
|
||
|
||
**预计总开发时间：20-26 天**
|
||
**核心开发人员：1-2 人**
|
||
**测试时间：3-5 天**
|