简介

┌─────────────────────────────────────────────────────────┐
│                     应用层 (Application)                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │ Admin UI │  │seal-core │  │mini-cont.│  │Portal  │ │
│  │ (管理后台) │  │ (签署引擎) │  │(小程序/H5)│  │(PC门户) │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  接口层 (Controller)                    │
│  ┌────────────┐  ┌────────────┐  ┌──────────────────┐  │
│  │  Admin API  │  │   App API   │  │   Portal API    │  │
│  │ (管理端)     │  │ (签署/认证)  │  │  (PC门户端)      │  │
│  └────────────┘  └────────────┘  └──────────────────┘  │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Open API（第三方开放接口）                         │   │
│  │  认证 → 签署任务 → Webhook 回调                    │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  业务层 (Service)                       │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐           │
│  │SealSign  │  │Seal      │  │Notification│           │
│  │TaskSvc   │  │ConfigSvc │  │Service     │           │
│  │(签署任务)  │  │(配置读取)  │  │(通知&短链接) │           │
│  └──────────┘  └──────────┘  └────────────┘           │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐           │
│  │Signature │  │IntentVer.│  │Template    │           │
│  │Service   │  │Service   │  │Service     │           │
│  │(PDF签名)  │  │(意愿验证)  │  │(模板管理)   │           │
│  └──────────┘  └──────────┘  └────────────┘           │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  扩展层 (SPI / Starter)                 │
│  ┌────────────────────┐  ┌──────────────────────────┐  │
│  │  UserInfoProvider   │  │  QuotaValidator          │  │
│  │  (用户信息获取)       │  │  (配额校验)               │  │
│  └────────────────────┘  └──────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                  数据层 (DAO / Mapper)                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │  MySQL   │  │  Redis   │  │  OSS     │             │
│  │ (业务数据) │  │ (短链接/缓存)│  │ (文件存储) │             │
│  └──────────┘  └──────────┘  └──────────┘             │
└─────────────────────────────────────────────────────────┘

yudao-module-seal/
├── yudao-module-seal-api/                  # 公共 API（DTO、枚举、SPI 接口）
│   └── api/
│       ├── auth/                           #   认证 SPI（SealAuthProvider）
│       ├── storage/                        #   存储 SPI（SealStorageProvider）
│       └── validator/                      #   校验 SPI（SealQuotaValidator、SealUserValidator）
├── yudao-module-seal-biz/                  # 业务实现（Controller、Service、DAL）
│   └── service/user/                       #   用户信息 SPI（UserInfoProvider、UserInfoAdapter）
└── yudao-module-seal-spring-boot-starter/  # 产品化 Starter（SPI 适配、License）
    ├── adapter/                            #   SPI 适配器实现（auth、storage、user、enterprise）
    └── validator/                          #   SPI 校验器实现（Ruoyi 适配 + NoOp 降级）

yudao-module-seal-biz/src/main/java/cn/iocoder/yudao/module/seal/
├── controller/
│   ├── admin/                    # 管理端 API
│   │   ├── sealsigntask/         # 签署任务管理
│   │   └── vo/                   # 管理端 VO
│   ├── app/                      # App 端 API（小程序/H5 直接调用）
│   │   ├── signtask/             # 签署任务（含 auth-by-ref 认证）
│   │   ├── seal/                 # 印章操作
│   │   ├── shortlink/            # 短链接信息
│   │   └── template/             # 模板操作
│   ├── portal/                   # Portal 端 API（PC 门户调用）
│   └── open/                     # Open API（第三方开放接口）
│       ├── OpenSealAuthController    # 认证（AppKey/Secret → Token）
│       ├── OpenSignTaskController    # 签署任务 CRUD
│       ├── OpenWebhookController     # Webhook 回调配置
│       └── vo/                       # Open API 请求/响应 VO
├── service/
│   ├── sealsigntask/             # 签署任务核心业务
│   ├── config/                   # 配置服务（SealConfigService）
│   ├── notification/             # 通知 & 短链接生成
│   ├── signature/                # PDF 数字签名
│   ├── intentverification/       # 签署意愿验证
│   └── webhook/                  # Webhook 回调服务
│       ├── SealWebhookService        # 接口
│       └── SealWebhookServiceImpl    # 实现（WebClient + 异步 + 重试）
├── dal/
│   ├── dataobject/               # 数据对象（DO）
│   │   └── webhook/              # Webhook 相关 DO
│   │       ├── SealWebhookConfigDO   # 回调配置
│   │       └── SealWebhookLogDO      # 回调日志
│   ├── mysql/                    # Mapper
│   │   └── webhook/              # Webhook Mapper
│   └── redis/                    # Redis Key 常量
├── framework/
│   └── security/                 # Seal Token 认证体系
└── util/
    └── jwt/                      # JWT 工具

┌─────────────────────────────────────────────────────────────────┐
│                    seal-biz（业务层）                             │
│                                                                 │
│  SealSignTaskServiceImpl                                        │
│    ├── @Resource UserInfoProvider          ← 获取用户手机号等    │
│    ├── @Resource SealUserValidator         ← 校验用户/实名认证   │
│    ├── @Autowired(required=false)                               │
│    │   SealQuotaValidator                  ← 配额校验（可选）    │
│    └── @Autowired(required=false)                               │
│        EnterpriseAccessValidator           ← 企业权限校验（可选） │
│                                                                 │
│  PdfDigitalSignatureService                                     │
│    └── @Resource SealStorageProvider       ← 文件上传/下载       │
│                                                                 │
│  SealTokenAdapter                                               │
│    └── @Resource SealAuthProvider          ← 用户认证            │
└────────────────────────┬────────────────────────────────────────┘
                         │ 接口调用（无编译依赖）
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│                 seal-spring-boot-starter（适配层）                │
│                                                                 │
│  ┌─────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │ RuoyiAuthAdapter │  │RuoyiQuotaValid.  │  │UserInfoAdapter│  │
│  │ JwtAuthAdapter   │  │RuoyiUserValid.   │  │  Impl         │  │
│  │ OAuth2AuthAdapter│  │NoOpQuotaValid.   │  │NoOpUserInfo   │  │
│  └─────────────────┘  │NoOpUserValid.    │  │  Adapter      │  │
│                        └──────────────────┘  └───────────────┘  │
│  ┌──────────────────────┐  ┌──────────────────────────────┐     │
│  │ RuoyiFileClientAdapter│  │EnterpriseAccessValidatorImpl │     │
│  │ OssStorageAdapter     │  │NoOpEnterpriseAccessValidator │     │
│  │ MinioStorageAdapter   │  └──────────────────────────────┘     │
│  │ LocalStorageAdapter   │                                       │
│  └──────────────────────┘                                       │
│                                                                 │
│  通过 @Conditional 注解自动选择实现                                │
└─────────────────────────────────────────────────────────────────┘

                        seal-biz 定义
┌──────────────┐    ┌──────────────────┐    ┌──────────────┐
│ Service 层    │───▶│ UserInfoProvider  │◀──│UserInfoPro-  │
│ (业务代码调用) │    │ (接口)            │    │viderBridge   │
└──────────────┘    └──────────────────┘    └──────┬───────┘
                                                   │ 委托
                                                   ▼
                    ┌──────────────────┐    ┌──────────────┐
                    │ UserInfoAdapter   │◀──│UserInfoAdap- │  seal-starter 实现
                    │ (接口)            │    │terImpl       │
                    └──────────────────┘    └──────────────┘

spring.factories
  └── SealAutoConfiguration (@ConditionalOnProperty: yudao.seal.mode=starter)
        ├── @ComponentScan 扫描 seal.biz + seal.starter 包
        ├── RuoyiAuthAdapter      (@ConditionalOnClass: SecurityFrameworkUtils)
        ├── RuoyiQuotaValidator   (@ConditionalOnProperty: quota-validator=ruoyi, 默认)
        ├── RuoyiUserValidator    (@ConditionalOnProperty: user-validator=ruoyi, 默认)
        ├── UserInfoAdapterImpl   (@ConditionalOnClass: MemberUserApi)
        ├── UserInfoProviderBridge(@ConditionalOnBean: UserInfoAdapter)
        ├── NoOpQuotaValidator    (@ConditionalOnProperty: quota-validator=noop)
        ├── NoOpUserValidator     (@ConditionalOnProperty: user-validator=noop)
        ├── NoOpUserInfoAdapter   (@ConditionalOnMissingBean: UserInfoAdapter)
        └── NoOpEnterpriseAccess  (@ConditionalOnMissingBean: EnterpriseAccessValidator)

管理后台「参数配置」
    ↓ 写入
infra_config 表（config_key + value + visible）
    ↓ 读取
ConfigApi.getVisibleConfigValueByKey()
    ↓ visible=false 返回 null
SealConfigService.getVisibleConfig()
    ↓ null 或空 → 返回 ""（功能禁用）
业务代码调用（如 getSealCoreH5Domain()、isMiniprogramEnabled()）

调用方未指定 platform 参数
    ↓
SealConfigService.isMiniprogramEnabled() ?
    ├── true  → platform = "miniprogram" → 生成 /m/{ref}
    └── false → platform = "h5"          → 生成 /s/{ref}

用户点击签署链接
    ↓
前端调用 /app-api/api/v1/seal/auth/by-ref?ref=xxx
    ↓
后端返回认证结果 + platformRouting
    ↓
┌─ linkType = QUICK_SIGN（快捷签署）
│   → 直接跳转到签署页面 /h5/sign/document
│
├─ linkType = PREVIEW_LINK（预览）
│   → 跳转到预览页面 /h5/preview/contract
│
└─ linkType = SECURE_SIGN（登录签署）
    ↓
    ┌─ /m/ 路径（小程序链接）
    │   ├─ 微信内 → 显示小程序桥接页（打开小程序按钮）
    │   └─ 非微信 → 显示「请使用微信打开」页面（复制链接按钮）
    │              └─ 如果 H5 也启用 → 底部显示「使用网页签署」回退链接
    │
    └─ /s/ 路径（H5 链接）
        ├─ 微信内 + 小程序可用 → 显示小程序桥接页
        ├─ H5 可用 → 跳转 H5 登录页（mini-contract 登录页）
        ├─ 仅小程序（非微信）→ 显示「请使用微信打开」页面
        └─ 都不可用 → 显示错误提示

{
  "preferMiniprogram": true,
  "miniprogram": {
    "enabled": true,
    "appId": "wx22db0d6ebe81e2ee",
    "name": "MiniContract.Pro",
    "logo": "https://...",
    "urlScheme": "weixin://dl/business/?appid=wx...&path=..."
  },
  "h5LoginUrl": "https://app.example.com/#/pages/login/index?redirect=..."
}

创建签署链接时：
    ├─ 快捷签署 → Redis 存储完整 Seal-Token → 前端拿到 token 直接签署
    └─ 登录签署 → Redis 存储元数据（taskId, participantId, tenantId）
                → 前端需要用户登录后，带着登录态再请求签署

前端认证时（/auth/by-ref）：
    ├─ 快捷签署 → 直接返回 Seal-Token，linkType=QUICK_SIGN
    └─ 登录签署 → 返回 requireLogin=true，linkType=SECURE_SIGN
                → 同时返回 platformRouting 告诉前端如何跳转

┌──────────────────────────────────────────────────────────────────┐
│                      第三方系统                                   │
│                                                                  │
│  1. 获取 Token    2. 创建签署任务    3. 嵌入签署页面    4. 接收回调  │
└──────┬───────────────┬──────────────────┬──────────────┬─────────┘
       │               │                  │              │
       ▼               ▼                  ▼              ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Open API 接口层                                │
│                    路径前缀: /open-api（框架自动添加）               │
│                                                                  │
│  ┌─────────────────┐  ┌──────────────────┐  ┌────────────────┐  │
│  │OpenSealAuth     │  │OpenSignTask      │  │OpenWebhook     │  │
│  │Controller       │  │Controller        │  │Controller      │  │
│  │                 │  │                  │  │                │  │
│  │POST /auth/token │  │POST /sign-tasks  │  │POST /webhooks  │  │
│  │(AppKey/Secret   │  │GET  /sign-tasks/ │  │GET  /webhooks  │  │
│  │ → Seal-Token)   │  │     {taskId}     │  │DELETE /webhooks│  │
│  │                 │  │POST /sign-tasks/ │  │                │  │
│  │                 │  │     {taskId}/     │  │                │  │
│  │                 │  │     cancel       │  │                │  │
│  │                 │  │GET  /sign-tasks/ │  │                │  │
│  │                 │  │     {taskId}/     │  │                │  │
│  │                 │  │     sign-links   │  │                │  │
│  │                 │  │GET  /sign-tasks/ │  │                │  │
│  │                 │  │     {taskId}/     │  │                │  │
│  │                 │  │     download     │  │                │  │
│  └─────────────────┘  └──────────────────┘  └────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────────────┐
│                    业务层 (Service)                               │
│                                                                  │
│  ┌──────────────────────┐  ┌─────────────────────────────────┐  │
│  │SealSignTaskService   │  │SealWebhookService               │  │
│  │(复用已有签署任务服务)   │  │                                 │  │
│  │                      │  │ saveWebhookConfig()  配置回调    │  │
│  │ createSignTask()     │  │ sendWebhook()        异步发送    │  │
│  │ generateSignLink()   │  │ retryFailedWebhooks() 失败重试  │  │
│  │ cancelSignTask()     │  │                                 │  │
│  └──────────────────────┘  │ HTTP 客户端: WebClient           │  │
│                            │ 签名算法: HMAC-SHA256             │  │
│                            │ 重试策略: 指数退避 (1/5/30 min)    │  │
│                            └─────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                            ↓
┌──────────────────────────────────────────────────────────────────┐
│                    数据层 (Database)                              │
│                                                                  │
│  ┌──────────────────────┐  ┌─────────────────────────────────┐  │
│  │seal_api_key          │  │seal_webhook_config              │  │
│  │(API 密钥表)           │  │(回调配置表)                      │  │
│  │                      │  │                                 │  │
│  │ id (Integer)         │  │ id, api_key_id, callback_url    │  │
│  │ app_name             │  │ secret, events, status          │  │
│  │ api_key, secret_key  │  └─────────────────────────────────┘  │
│  │ status               │  ┌─────────────────────────────────┐  │
│  └──────────────────────┘  │seal_webhook_log                 │  │
│                            │(回调日志表)                       │  │
│                            │                                 │  │
│                            │ id, webhook_config_id, task_id   │  │
│                            │ event_type, request_body         │  │
│                            │ response_status, response_body   │  │
│                            │ status, retry_count              │  │
│                            │ next_retry_time                  │  │
│                            └─────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

第三方系统                          Contract.Pro                    签署人
    │                                   │                            │
    │  1. POST /auth/token              │                            │
    │     (apiKey + secretKey + nonce)   │                            │
    │ ◀─── Seal-Token ─────────────────│                            │
    │                                   │                            │
    │  2. POST /sign-tasks              │                            │
    │     (模板ID + 参与人 + callbackUrl)│                            │
    │ ◀─── taskId + signUrl ───────────│                            │
    │                                   │                            │
    │  3. 将 signUrl 嵌入 iframe/WebView │                            │
    │ ─────────────────────────────────────────── signUrl ──────────▶│
    │                                   │                            │
    │                                   │  4. 用户在 seal-core 签署   │
    │                                   │ ◀──── 签署完成 ────────────│
    │                                   │                            │
    │  5. Webhook 回调                   │                            │
    │ ◀─── POST callbackUrl ───────────│                            │
    │     {eventType: "sign_completed", │                            │
    │      taskId, signedFileUrl}       │                            │
    │                                   │                            │
    │  6. GET /sign-tasks/{id}/download │                            │
    │ ◀─── signedFileUrl ──────────────│                            │
    │                                   │                            │

POST {callbackUrl}
Headers:
  Content-Type: application/json
  X-Seal-Signature: {HMAC-SHA256 签名}
  X-Seal-Event: {事件类型}
  X-Seal-Timestamp: {时间戳}

Body:
{
  "eventType": "sign_completed",
  "taskId": 1024,
  "taskName": "劳动合同",
  "status": 3,
  "timestamp": 1707724800000,
  "signedFileUrl": "https://oss.example.com/signed/xxx.pdf"
}

<dependency>
    <groupId>cn.iocoder.boot</groupId>
    <artifactId>yudao-module-seal-spring-boot-starter</artifactId>
    <version>${revision}</version>
</dependency>

========================================
Seal 模块配置检查（数据来源：管理后台「参数配置」）
========================================
  [seal-core H5 域名] = https://seal.example.com (已启用)
  [Mini-Contract H5 域名] 未配置或已禁用（配置键: seal.platform.mini-contract-h5-domain）
  [小程序 AppID] = wx22db0d6ebe81e2ee (已启用)
========================================