gulop-member-wx/开发文档.md

1. 用户认证，相关控制器MemberAuthController

• 获取所有的认证信息 getAuthInfo
• 个人运营商三要素认证 threeElementAuth
• OCR身份证识别 uploadOcr

• 请求个人人脸活体认证 personFace

• 个人银行卡四要素比对 fourElementAuth

• 保存资质证书 checkCertificate

• 上传文件 upload

数据表

• 用户表 ums_member

  CREATE TABLE `ums_member` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '用户ID（即member_id）',
  `phone` varchar(30) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT 'phone',
  `is_three_auth` tinyint DEFAULT '0' COMMENT '三要素认证 0-未认证 1-已认证',
  `is_four_auth` tinyint DEFAULT '0' COMMENT '四要素认证 0-未认证 1-已认证',
  `is_ocr_auth` tinyint DEFAULT '0' COMMENT 'OCR认证 0-未认证 1-已认证',
  `is_liveness_auth` tinyint DEFAULT '0' COMMENT '活体认证 0-未认证 1-已认证',
  `is_esign_auth` tinyint DEFAULT '0' COMMENT '电子签认证 0-未认证 1-已认证',
  `three_auth_info` json DEFAULT NULL COMMENT '三要素认证数据（姓名/身份证/手机号）',
  `four_auth_info` json DEFAULT NULL COMMENT '四要素认证数据（+银行卡号）',
  `ocr_info` json DEFAULT NULL COMMENT 'OCR识别数据（身份证正反面/有效期）',
  `liveness_info` json DEFAULT NULL COMMENT '活体检测数据（视频/分数）',
  `user_seal_no` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '生成默认印章编号',
  `certificate_info` json DEFAULT NULL COMMENT '证书',
  `esign_info` json DEFAULT NULL COMMENT '电子签数据（合同/签章位置）',
  `create_by` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '创建人',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_by` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '更新人',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `del_flag` tinyint DEFAULT '0' COMMENT '删除标记 0-正常 1-已删除',
  `lock_flag` tinyint DEFAULT '0' COMMENT '锁定标记 0-可编辑 1-只读',
  PRIMARY KEY (`id`) USING BTREE,
  KEY `idx_auth_status` (`is_three_auth`,`is_four_auth`,`is_esign_auth`) USING BTREE,
  KEY `idx_update` (`update_time`) USING BTREE
  ) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci ROW_FORMAT=DYNAMIC COMMENT='统一用户认证信息表'
  

2. 报告/协议相关控制器

• 获取签约列表 getList
• 签约 signContract
• 查看合同信息（同步合同信息和状态） signCheck
• 获取报告列表 getReportList
• 下载报告 getReportDown

数据表

• 报告、协议配置表

  CREATE TABLE `gig_config` (
  `config_id` bigint NOT NULL AUTO_INCREMENT COMMENT 'id',
  `ent_code` varchar(18) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '企业三合一码',
  `protocol` varchar(5) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '协议',
  `gateway_host` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '网关域名',
  `subject_name` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '结算主体名称',
  `subject_type` int NOT NULL COMMENT '结算主体',
  `subject_location` varchar(16) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '结算税源地',
  `subject_channel` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL,
  `app_id` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '主体id',
  `merchant_private_key` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '私钥',
  `public_key` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '公钥',
  `location_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '所属地id',
  `sign_type` varchar(16) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '签名算法类型',
  `opt_flag` int NOT NULL DEFAULT '1' COMMENT '启用标记',
  `def_flag` tinyint(1) NOT NULL DEFAULT '0' COMMENT '默认标记',
  `end_type` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '端类型',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `modified_time` datetime NOT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  `is_sign` tinyint DEFAULT '0' COMMENT '需要签约',
  `agreement_url` text CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci COMMENT '需要签约的协议',
  `agreement_template` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '协议对应的模板编号',
  `enterprise_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '企业在爱签的account',
  `platform_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '平台在爱签的account',
  `is_file_type` tinyint DEFAULT '0' COMMENT '文件类型 0 是协议 1是报告',
  `reception_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '接包方企业在爱签的account (报告才有)',
  PRIMARY KEY (`config_id`) USING BTREE,
  KEY `gig_config_ent_code` (`ent_code`) USING BTREE
  ) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci ROW_FORMAT=DYNAMIC COMMENT='结算主体配置信息表';
  

• 用户已签约表

  CREATE TABLE `smart_contract` (
  `contract_id` bigint NOT NULL AUTO_INCREMENT COMMENT '协议唯一标识，自增主键',
  `config_id` bigint NOT NULL,
  `contract_no` varchar(32) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '唯一协议编号(如:SC_年月日+流水号)',
  `contract_title` varchar(255) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '协议标题（前端展示用）',
  `preview_url` text CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '签约协议预览地址',
  `contract_content` text CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '协议的文件地址',
  `contract_status` tinyint NOT NULL DEFAULT '1' COMMENT '协议状态:1-待签署 2-签署中 3-已完成 4-已终止',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '协议创建时间',
  `expire_time` datetime NOT NULL COMMENT '签署截止时间',
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '最后更新时间',
  `user_id` bigint NOT NULL COMMENT '发起用户',
  `user_account` varchar(255) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '用户在爱签ID',
  `enterprise_account` varchar(255) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '企业在爱签ID',
  `platform_account` varchar(255) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '平台在爱签的ID',
  `complete_time` datetime DEFAULT NULL COMMENT '完成时间',
  `sign_info` json DEFAULT NULL,
  PRIMARY KEY (`contract_id`) USING BTREE,
  UNIQUE KEY `contract_no` (`contract_no`) USING BTREE,
  KEY `idx_status` (`contract_status`) USING BTREE,
  KEY `idx_expire` (`expire_time`) USING BTREE
  ) ENGINE=MyISAM AUTO_INCREMENT=7 DEFAULT CHARSET=utf8mb3 COLLATE=utf8mb3_unicode_ci ROW_FORMAT=DYNAMIC COMMENT='智能合约主表，集成签约方预置与状态跟踪';
  

3. 其他数据表

• 爱签配置表

  CREATE TABLE `gig_config` (
  `config_id` bigint NOT NULL AUTO_INCREMENT COMMENT 'id',
  `ent_code` varchar(18) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '企业三合一码',
  `protocol` varchar(5) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '协议',
  `gateway_host` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '网关域名',
  `subject_name` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '结算主体名称',
  `subject_type` int NOT NULL COMMENT '结算主体',
  `subject_location` varchar(16) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '结算税源地',
  `subject_channel` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL,
  `app_id` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '主体id',
  `merchant_private_key` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '私钥',
  `public_key` varchar(2048) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '公钥',
  `location_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '所属地id',
  `sign_type` varchar(16) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '签名算法类型',
  `opt_flag` int NOT NULL DEFAULT '1' COMMENT '启用标记',
  `def_flag` tinyint(1) NOT NULL DEFAULT '0' COMMENT '默认标记',
  `end_type` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL COMMENT '端类型',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `modified_time` datetime NOT NULL ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
  `is_sign` tinyint DEFAULT '0' COMMENT '需要签约',
  `agreement_url` text CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci COMMENT '需要签约的协议',
  `agreement_template` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '协议对应的模板编号',
  `enterprise_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '企业在爱签的account',
  `platform_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '平台在爱签的account',
  `is_file_type` tinyint DEFAULT '0' COMMENT '文件类型 0 是协议 1是报告',
  `reception_account` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci DEFAULT NULL COMMENT '接包方企业在爱签的account (报告才有)',
  PRIMARY KEY (`config_id`) USING BTREE,
  KEY `gig_config_ent_code` (`ent_code`) USING BTREE
  ) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci ROW_FORMAT=DYNAMIC COMMENT='结算主体配置信息表';
  

• 爱签api调用历史表

  CREATE TABLE `ums_ext_api_his` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `ext_id` varchar(50) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '第三方接口ID',
  `user_id` bigint NOT NULL COMMENT '用户ID',
  `api_name` varchar(100) CHARACTER SET utf8mb3 COLLATE utf8mb3_unicode_ci NOT NULL COMMENT '接口名称',
  `request_data` json DEFAULT NULL COMMENT '请求数据',
  `response_data` json DEFAULT NULL COMMENT '响应数据',
  `status` tinyint DEFAULT '1' COMMENT '状态：0-失败，1-成功',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  PRIMARY KEY (`id`) USING BTREE
  ) ENGINE=MyISAM AUTO_INCREMENT=94 DEFAULT CHARSET=utf8mb3 COLLATE=utf8mb3_unicode_ci ROW_FORMAT=DYNAMIC COMMENT='接口调用历史表';
  

​ 数据表参考原有代码里的数据表，并增加了一些字段上去

4. 需要注意的地方

• 4.1 没有登录功能，因此在控制器里固定了用户ID，并传递用户ID到服务层、数据层

• 4.2 活体认证通过后爱签是直接在小程序的webview组件中返回成功/失败结果，根据此结果再调用后台其他逻辑（保存认证结果、添加实名人到爱签）

• 4.3 报告、协议配置表gig_config新增字段说明：

  • agreement_url 协议或报告URL

  • is_sign 为是否需要签约 若不需要，用户则调用税地（调用代码在签约功能中，已注释）

  • 企业在爱签的account （报告和协议需要）

  • 平台在爱签的account (报告需要)

  • 接包方企业在爱签的account (报告需要)

  • is_file_type 文件类型 0 是协议 1是报告

• 4.4 报告的骑缝章需要指定加盖的页码，因此每个报告可能不一致，需要在配置表中配置

### 现在的demo六里，各个配置是手动添加到数据库的

​