# Implementation Plan: 用户企业认证、身份认证和员工CA二维码认证

## Overview

本实现计划将用户企业认证、身份认证和员工CA二维码认证功能分解为可执行的开发任务。实现将采用增量开发方式，优先实现核心功能，然后逐步添加高级特性。

## Tasks

- [x] 1. 数据库表结构和权限初始化
  - 创建用户企业认证表、用户身份认证表、认证审核日志表（包含operator_roles字段）
  - 创建员工实名认证二维码表、CA服务配置表
  - 初始化CA服务配置数据
  - 创建认证审核员和认证管理员角色
  - 创建认证管理相关菜单和权限
  - 为角色分配相应的权限
  - _Requirements: 所有需求的数据基础, 10.1, 10.2, 10.3_

- [x] 2. 通用工具类和权限常量实现
  - [x] 2.1 创建权限常量类 (VerificationPermissions)
    - 定义所有认证相关的权限常量
    - _Requirements: 10.4_

  - [x] 2.2 创建角色常量类 (VerificationRoles)
    - 定义认证审核员角色常量
    - 定义认证管理员角色常量
    - _Requirements: 10.1_

  - [x] 2.3 实现身份证号验证工具类 (IdCardValidator)
    - 实现GB 11643-1999标准的身份证号格式验证
    - 实现身份证号校验位验证
    - _Requirements: 2.3_

  - [ ]* 2.4 编写身份证号验证的属性测试
    - **Property 6: 身份证号格式验证**
    - **Validates: Requirements 2.3**

  - [x] 2.5 实现加密工具类 (EncryptionUtil)
    - 实现AES-256-GCM加密方法
    - 实现AES-256-GCM解密方法
    - 实现RSA签名和验证方法
    - _Requirements: 8.1, 8.4, 8.5_

  - [ ]* 2.6 编写加密工具的属性测试
    - **Property 7: 身份证号加密存储 (round-trip)**
    - **Validates: Requirements 2.5, 8.1**

  - [x] 2.7 实现二维码生成工具类 (QRCodeGenerator)
    - 使用ZXing库生成二维码图片
    - 支持自定义二维码尺寸
    - _Requirements: 4.1, 4.2_

  - [ ]* 2.8 编写二维码生成的单元测试
    - 测试二维码生成功能
    - 测试不同尺寸的二维码生成
    - _Requirements: 4.1, 4.2_

- [x] 3. CA服务接口适配层实现
  - [x] 3.1 创建CA服务适配器接口和数据模型
    - 定义CAServiceAdapter接口
    - 定义IdentityVerificationRequest/Response
    - _Requirements: 4.1, 4.2_

  - [x] 3.2 实现CA服务配置类 (CAServiceConfig)
    - 从数据库读取CA服务配置
    - 支持配置热更新
    - _Requirements: 4.2_

  - [x] 3.3 实现Mock CA服务适配器 (MockCAServiceAdapter)
    - 实现身份认证Mock逻辑
    - _Requirements: 4.5_

  - [ ]* 3.4 编写CA服务适配器的单元测试
    - 测试Mock适配器的各个方法
    - 测试配置读取功能
    - _Requirements: 4.2, 4.5_

  - [x] 3.5 实现CA服务调用的错误处理和超时控制
    - 实现30秒超时机制
    - 实现错误日志记录
    - 实现友好的错误信息返回
    - _Requirements: 4.3, 4.6, 4.7_

  - [ ]* 3.6 编写CA服务错误处理的属性测试
    - **Property 17: CA服务错误处理**
    - **Property 18: CA服务超时处理**
    - **Property 19: CA服务调用日志**
    - **Validates: Requirements 4.3, 4.6, 4.7**

- [x] 4. Checkpoint - 确保基础工具和CA适配层测试通过
  - 确保所有测试通过，如有问题请向用户询问

- [x] 5. 用户企业认证功能实现
  - [x] 5.1 创建用户企业认证实体类和Mapper
    - 创建UserEnterpriseVerification实体类
    - 创建UserEnterpriseVerificationMapper接口
    - 创建Mapper XML文件
    - _Requirements: 1.1, 1.2_

  - [x] 5.2 实现用户企业认证Service层
    - 实现提交企业认证申请方法
    - 实现查询企业认证状态方法
    - 实现管理员审核企业认证方法（添加@PreAuthorize权限注解）
    - 实现企业认证列表查询方法（添加@PreAuthorize权限注解）
    - 实现权限验证逻辑
    - _Requirements: 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 10.4, 10.5_

  - [ ]* 5.3 编写企业认证的属性测试
    - **Property 1: 企业认证信息验证**
    - **Property 2: 企业认证状态转换**
    - **Property 3: 企业认证错误处理**
    - **Property 4: 企业认证审核记录**
    - **Property 5: 企业认证重新申请**
    - **Validates: Requirements 1.2, 1.3, 1.4, 1.6, 1.7**

  - [ ]* 5.4 编写权限控制的单元测试
    - 测试具有权限的用户可以审核
    - 测试不具有权限的用户被拒绝
    - 测试超级管理员可以审核
    - _Requirements: 1.6, 10.4, 10.5, 10.7_

  - [x] 5.5 实现用户企业认证Controller层
    - 实现提交企业认证申请接口
    - 实现查询企业认证状态接口
    - 实现管理员审核企业认证接口
    - 实现企业认证列表查询接口
    - 添加权限不足的异常处理
    - _Requirements: 1.1, 1.2, 1.5, 10.5_

  - [ ]* 5.6 编写企业认证Controller的集成测试
    - 使用MockMvc测试API接口
    - 测试请求参数验证
    - 测试响应格式
    - 测试权限控制
    - _Requirements: 1.1, 1.2, 1.5, 10.4_

- [x] 6. 用户身份认证功能实现
  - [x] 6.1 创建用户身份认证实体类和Mapper
    - 创建UserIdentityVerification实体类
    - 创建UserIdentityVerificationMapper接口
    - 创建Mapper XML文件
    - _Requirements: 2.1, 2.2_

  - [x] 6.2 实现用户身份认证Service层
    - 实现提交身份认证申请方法（调用CA服务）
    - 实现查询身份认证状态方法
    - 实现身份认证列表查询方法
    - 集成IdCardValidator进行身份证号验证
    - 集成EncryptionUtil进行身份证号加密
    - _Requirements: 2.2, 2.3, 2.4, 2.5, 2.6_

  - [ ]* 6.3 编写身份认证的属性测试
    - **Property 8: CA服务身份认证调用**
    - **Property 9: CA身份认证成功处理**
    - **Property 10: CA身份认证失败处理**
    - **Validates: Requirements 2.5, 2.6, 2.7**

  - [x] 6.4 实现用户身份认证Controller层
    - 实现提交身份认证申请接口
    - 实现查询身份认证状态接口
    - 实现身份认证列表查询接口
    - _Requirements: 2.1, 2.2_

  - [ ]* 6.5 编写身份认证Controller的集成测试
    - 使用MockMvc测试API接口
    - 测试CA服务集成
    - _Requirements: 2.1, 2.2, 2.5_

- [x] 7. 认证审核日志功能实现
  - [x] 7.1 创建认证审核日志实体类和Mapper
    - 创建VerificationAuditLog实体类（包含operator_roles字段）
    - 创建VerificationAuditLogMapper接口
    - 创建Mapper XML文件
    - _Requirements: 1.7, 6.7, 10.6_

  - [x] 7.2 在认证Service中集成审核日志记录
    - 在企业认证审核时记录日志（包含操作人角色）
    - 在认证状态变更时记录日志
    - 获取当前用户的角色信息并记录
    - _Requirements: 1.7, 6.7, 10.6_

  - [ ]* 7.3 编写审核日志的单元测试
    - 测试日志记录功能
    - 测试日志查询功能
    - 测试角色信息记录
    - _Requirements: 1.7, 6.7, 10.6_

- [x] 8. Checkpoint - 确保用户认证功能测试通过
  - 确保所有测试通过，如有问题请向用户询问

- [x] 9. 员工实名认证二维码功能实现
  - [x] 9.1 创建员工实名认证二维码实体类和Mapper
    - 创建EmployeeQRCode实体类（包含员工ID、姓名、身份证号、时间戳）
    - 创建EmployeeQRCodeMapper接口
    - 创建Mapper XML文件
    - _Requirements: 3.1, 3.2_

  - [x] 9.2 实现员工实名认证二维码Service层
    - 实现生成二维码方法（包含员工身份信息）
    - 实现获取二维码图片方法
    - 实现验证二维码方法（调用CA服务进行身份认证）
    - 实现二维码过期检查逻辑
    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6_

  - [ ]* 9.3 编写员工实名认证二维码的属性测试
    - **Property 11: 二维码内容完整性**
    - **Property 12: 二维码CA认证调用**
    - **Property 13: 二维码认证成功处理**
    - **Property 14: 二维码认证失败处理**
    - **Property 15: 二维码过期验证**
    - **Validates: Requirements 3.1, 3.3, 3.4, 3.5, 3.6_

  - [x] 9.4 实现员工实名认证二维码Controller层
    - 实现生成二维码接口
    - 实现获取二维码图片接口
    - 实现验证二维码接口（调用CA服务）
    - _Requirements: 3.2, 3.3, 3.4, 3.5_

  - [ ]* 9.5 编写二维码Controller的集成测试
    - 使用MockMvc测试API接口
    - 测试二维码生成和CA认证流程
    - _Requirements: 3.2, 3.3, 3.4_

- [x] 10. Checkpoint - 确保员工实名认证二维码功能测试通过
  - 确保所有测试通过，如有问题请向用户询问

- [x] 11. 认证状态权限控制实现
  - [x] 11.1 实现认证拦截器 (VerificationInterceptor)
    - 检查用户的企业认证和身份认证状态
    - 拦截未认证用户访问受限功能
    - 超级管理员例外处理
    - _Requirements: 5.1, 5.3, 5.5, 5.8_

  - [x] 11.2 配置拦截器和受限路径
    - 在WebMvcConfig中注册拦截器
    - 配置需要认证的路径（如/credit/contract/**）
    - 排除认证接口本身
    - _Requirements: 5.3, 5.9_

  - [ ]* 11.3 编写权限控制的属性测试
    - **Property 20: 未认证用户访问拦截**
    - **Property 21: 双认证完成解除限制**
    - **Property 22: 超级管理员特殊权限**
    - **Property 23: 权限检查双认证状态**
    - **Property 24: 认证菜单配置化**
    - **Validates: Requirements 5.1, 5.3, 5.4, 5.5, 5.8, 5.9**

  - [x] 11.4 实现认证状态查询Service方法
    - 实现isUserFullyVerified方法
    - 实现getUserVerificationStatus方法
    - _Requirements: 5.4, 5.8_

  - [ ]* 11.5 编写权限控制的集成测试
    - 测试拦截器功能
    - 测试不同认证状态的访问权限
    - 测试超级管理员例外
    - _Requirements: 5.1, 5.3, 5.4, 5.5_

- [x] 12. 企业认证管理功能实现
  - [x] 12.1 实现企业认证管理Service方法
    - 实现企业认证列表查询（支持筛选和搜索，添加@PreAuthorize权限注解）
    - 实现企业认证详情查询（包含审核历史，添加@PreAuthorize权限注解）
    - 实现批量审核企业认证方法（添加@PreAuthorize权限注解）
    - 实现导出企业认证数据方法（添加@PreAuthorize权限注解）
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 10.4_

  - [x] 12.2 实现企业认证管理Controller层
    - 实现企业认证列表查询接口
    - 实现企业认证详情查询接口
    - 实现批量审核接口
    - 实现导出企业认证数据接口
    - 添加权限不足的异常处理
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.6, 10.5_

  - [ ]* 12.3 编写企业认证管理的单元测试
    - 测试列表查询和筛选功能
    - 测试批量审核功能
    - 测试导出功能
    - 测试权限控制
    - _Requirements: 6.1, 6.2, 6.4, 6.6, 10.4_

- [x] 13. 通知机制实现
  - [x] 13.1 集成现有的通知服务
    - 实现认证申请确认通知
    - 实现认证审核通过通知
    - 实现认证审核拒绝通知
    - 支持站内消息和邮件两种方式
    - _Requirements: 8.1, 8.2, 8.3, 8.5_

  - [ ]* 13.2 编写通知功能的单元测试
    - 测试各种通知场景
    - 测试通知内容格式
    - _Requirements: 8.1, 8.2, 8.3_

- [x] 14. Checkpoint - 确保后端所有功能测试通过
  - 确保所有测试通过，如有问题请向用户询问

- [x] 15. 前端Vue3界面实现 - 用户认证模块
  - [x] 15.1 创建用户认证页面组件
    - 创建企业认证表单组件
    - 创建身份认证表单组件
    - 创建认证状态显示组件
    - _Requirements: 9.1, 9.2, 9.3_

  - [x] 15.2 实现认证表单验证
    - 实现企业信息格式验证
    - 实现身份证号格式验证
    - 实现实时验证反馈
    - _Requirements: 9.4_

  - [x] 15.3 集成认证API接口
    - 调用提交企业认证接口
    - 调用提交身份认证接口
    - 调用查询认证状态接口
    - _Requirements: 9.1, 9.2_

  - [ ]* 15.4 编写前端组件测试
    - 使用Vitest测试组件渲染
    - 测试表单验证逻辑
    - _Requirements: 9.1, 9.2, 9.3, 9.4_

- [x] 16. 前端Vue3界面实现 - 认证提示横幅
  - [x] 16.1 创建认证提示横幅组件
    - 显示企业认证和身份认证状态
    - 提供快速认证入口链接
    - 支持关闭和最小化
    - _Requirements: 5.1, 5.2, 5.6, 9.7_

  - [x] 16.2 实现路由守卫
    - 在Vue Router中添加beforeEach守卫
    - 检查用户认证状态
    - 显示认证提示横幅
    - 阻止未认证用户访问受限页面
    - _Requirements: 5.1, 5.3, 5.6, 5.7_

  - [ ]* 16.3 编写路由守卫测试
    - 测试不同认证状态的路由行为
    - 测试超级管理员例外
    - _Requirements: 5.1, 5.3, 5.5_

- [x] 17. 前端Vue3界面实现 - 员工实名认证二维码
  - [x] 17.1 在员工管理页面添加"实名认证"按钮和二维码显示功能
    - 在员工操作列添加"实名认证"按钮
    - 点击按钮后显示员工实名认证二维码
    - 提供二维码下载功能
    - 提供二维码打印功能
    - 显示二维码有效期和认证状态
    - _Requirements: 3.1, 3.2, 9.5_

  - [x] 17.2 集成员工实名认证二维码API接口
    - 调用生成员工实名认证二维码接口
    - 调用获取二维码图片接口
    - 调用验证二维码接口（扫描后调用CA服务）
    - _Requirements: 3.2, 3.3, 9.5_

  - [ ]* 17.3 编写员工实名认证二维码组件测试
    - 测试组件渲染
    - 测试API调用
    - 测试二维码显示和下载功能
    - _Requirements: 3.2, 9.5_

- [ ] 18. 前端Vue3界面实现 - 企业认证管理页面
  - [x] 18.1 创建企业认证管理页面
    - 创建企业认证列表组件
    - 创建认证筛选组件
    - 创建企业认证详情对话框（显示审核历史和审核人角色）
    - 创建批量审核对话框
    - _Requirements: 6.1, 6.2, 6.3, 6.6, 9.6, 10.6_

  - [x] 18.2 实现企业认证管理功能
    - 实现企业认证列表查询和分页
    - 实现认证状态筛选
    - 实现企业认证搜索（按用户姓名、企业名称、企业代码）
    - 实现企业认证详情查看（包含审核人角色信息）
    - 实现批量审核企业认证
    - 实现导出企业认证数据
    - 实现权限控制（根据用户角色显示/隐藏功能）
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 9.6, 10.3, 10.4_

  - [ ]* 18.3 编写企业认证管理页面测试
    - 测试列表渲染
    - 测试筛选和搜索功能
    - 测试审核功能
    - 测试权限控制
    - _Requirements: 6.1, 6.2, 6.3, 6.6, 9.6, 10.4_

- [ ] 19. Checkpoint - 确保前端所有功能正常
  - 确保所有前端功能正常，如有问题请向用户询问

- [x] 20. 数据安全和权限加固
  - [x] 20.1 实现数据访问权限控制
    - 在Service层添加权限检查
    - 记录敏感数据访问日志
    - 验证用户只能访问自己的认证数据（管理员除外）
    - _Requirements: 7.6, 10.4, 10.5_

  - [ ]* 20.2 编写数据安全的属性测试
    - **Property 25: 认证数据访问权限**
    - **Validates: Requirements 7.6**

  - [ ]* 20.3 编写权限控制的集成测试
    - 测试不同角色的权限边界
    - 测试未授权访问被拒绝
    - 测试审核日志记录角色信息
    - _Requirements: 10.4, 10.5, 10.6_

  - [x] 20.4 配置HTTPS和安全头
    - 配置HTTPS证书
    - 配置安全响应头（HSTS, CSP等）
    - _Requirements: 7.2_

- [x] 21. 性能优化
  - [x] 21.1 实现认证状态缓存
    - 使用Redis缓存用户认证状态
    - 设置合理的缓存过期时间
    - 认证状态变更时清除缓存

  - [x] 21.2 实现二维码图片缓存
    - 缓存生成的二维码图片
    - 设置合理的缓存过期时间

  - [x] 21.3 优化数据库查询
    - 添加必要的索引
    - 优化复杂查询的SQL

- [ ] 22. 文档和部署准备
  - [ ] 22.1 编写API文档
    - 使用Swagger生成API文档
    - 补充接口说明和示例

  - [ ] 22.2 编写部署文档
    - 数据库迁移脚本说明
    - 配置项说明
    - 部署步骤说明

  - [ ] 22.3 准备数据库迁移脚本
    - 创建Flyway或Liquibase迁移脚本
    - 测试迁移脚本

- [ ] 23. 最终集成测试和验收
  - [ ] 23.1 执行完整的E2E测试
    - 测试用户企业认证完整流程
    - 测试用户身份认证完整流程
    - 测试员工实名认证二维码生成和验证流程
    - 测试权限控制流程
    - 测试认证管理流程

  - [ ] 23.2 性能测试
    - 测试并发认证申请
    - 测试CA服务调用性能
    - 测试二维码生成性能

  - [ ] 23.3 安全测试
    - 测试加密功能
    - 测试权限控制
    - 测试SQL注入防护
    - 测试XSS防护

## Notes

- 标记为 `*` 的任务是可选的测试任务，可以根据项目进度决定是否执行
- 每个Checkpoint任务是重要的验证点，确保在继续之前所有功能正常
- CA服务适配器使用Mock实现进行开发和测试，真实CA服务对接可以在后期进行
- 前端开发可以与后端开发并行进行，使用Mock数据进行开发
- 属性测试使用jqwik框架，每个测试至少运行100次迭代
- 单元测试使用JUnit 5框架
- 集成测试使用Spring Boot Test和MockMvc