# 碳信网 SSO 认证模块详解

> 本文档基于 txw-sso 服务代码分析，详细说明注册登录流程、表结构定义、外部服务依赖。

---

## 一、模块定位

txw-sso 是碳信网项目的**统一认证服务**，负责：
- 用户账号密码登录/短信验证码登录
- OAuth2.0 令牌管理
- DID（去中心化身份）登录集成
- 图形验证码/短信验证码服务
- 账户锁定（防暴力破解）

---

## 二、核心表结构

### 2.1 OAuth2 令牌相关表

#### txw_sso_access_token（访问令牌表）
```sql
CREATE TABLE txw_sso_access_token (
  uuid VARCHAR(64) PRIMARY KEY,        -- 令牌UUID
  yh_uuid VARCHAR(64),                  -- 用户UUID
  qyuuid VARCHAR(64),                  -- 企业UUID
  access_token VARCHAR(512),           -- 访问令牌
  refresh_token VARCHAR(512),          -- 刷新令牌
  clientid VARCHAR(64),                -- 客户端ID
  sqnr TEXT,                           -- 授权内容(JSON)
  gqsj DATETIME,                       -- 过期时间
  gllp VARCHAR(512)                    -- 关联令牌(第三方token)
);
```

#### txw_sso_refresh_token（刷新令牌表）
```sql
CREATE TABLE txw_sso_refresh_token (
  uuid VARCHAR(64) PRIMARY KEY,
  yh_uuid VARCHAR(64),
  refresh_token VARCHAR(512),
  clientid VARCHAR(64),
  sqnr TEXT,
  gqsj DATETIME                         -- 过期时间(通常30天)
);
```

#### txw_sso_code（授权码表）
```sql
CREATE TABLE txw_sso_code (
  uuid VARCHAR(64) PRIMARY KEY,
  yh_uuid VARCHAR(64),
  sqm VARCHAR(128),                    -- 授权码
  clientid VARCHAR(64),
  sqnr TEXT,
  gqsj DATETIME,                       -- 过期时间(通常10分钟)
  cdxdz VARCHAR(512),                  -- 重定向地址
  rzzt VARCHAR(2),                     -- 认证状态
  access_token VARCHAR(512)
);
```

#### txw_sso_client（OAuth2客户端表）
```sql
CREATE TABLE txw_sso_client (
  uuid VARCHAR(64) PRIMARY KEY,
  clientid VARCHAR(64),                -- 客户端ID
  sqmy VARCHAR(256),                    -- 授权密钥(secret)
  yxbz VARCHAR(2),                      -- 有效标志(Y/N)
  fwlpyxq VARCHAR(32),                 -- 访问令牌有效期(秒)
  sxlpyxq VARCHAR(32),                 -- 刷新令牌有效期(秒)
  cdxdz VARCHAR(512),                  -- 重定向地址
  sqnr TEXT,                           -- 授权范围
  dcdz VARCHAR(512)                    -- 登出地址
);
```

### 2.2 用户信息存储

**注意：** 用户信息（账号、密码、手机号等）**不存储在 SSO 服务**，而是存储在 **txw-mhzc（碳门户）服务**中，通过 API 调用获取。

用户信息表结构在 mhzc 服务中定义（YhxxbDTO）。

---

## 三、登录流程详解

### 3.1 账号密码登录

```
用户输入(用户名+密码+图形验证码)
         │
         ▼
┌─────────────────────────────────────────────────┐
│  校验图形验证码                                  │
│  verifyService.checkCaptcha(uuid, code)        │
│  验证码错误 → 返回错误                           │
└─────────────────────┬───────────────────────────┘
                      │ 验证通过
                      ▼
┌─────────────────────────────────────────────────┐
│  校验账号                                        │
│  yhxxService.getYhxxByDlzh(username)            │
│  用户不存在 → 返回"用户名或密码错误"             │
└─────────────────────┬───────────────────────────┘
                      │ 用户存在
                      ▼
┌─────────────────────────────────────────────────┐
│  检查账户锁定状态                                │
│  accountLockService.checkLockStatus(yhUuid)      │
│  已锁定 → 返回"密码错误次数过多，账户已锁定"      │
└─────────────────────┬───────────────────────────┘
                      │ 未锁定
                      ▼
┌─────────────────────────────────────────────────┐
│  校验密码                                        │
│  MD5(rawPassword) == dlmm                      │
│  密码错误 → 记录错误次数 → 达到阈值则锁定         │
│            → 返回"用户名或密码错误"              │
└─────────────────────┬───────────────────────────┘
                      │ 密码正确
                      ▼
┌─────────────────────────────────────────────────┐
│  清除密码错误次数缓存                            │
│  accountLockService.clearCache(yhUuid)          │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  创建访问令牌                                    │
│  oauth2TokenService.createAccessToken()          │
│  → 生成 access_token + refresh_token            │
│  → 存储到数据库 + Redis                         │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  返回登录凭证                                    │
│  { accessToken, refreshToken, expiresTime }     │
│  同时写入 HttpOnly Cookie                        │
└─────────────────────────────────────────────────┘
```

**API 路径：** `POST /sso/auth/login`

**请求参数：**
```json
{
  "username": "string",           // 登录账号
  "password": "string",           // 密码(MD5)
  "captchaVerification": "uuid",  // 图形验证码UUID
  "captchaCode": "string"         // 图形验证码内容
}
```

### 3.2 短信验证码登录

```
用户输入(手机号+短信验证码+图形验证码)
         │
         ▼
┌─────────────────────────────────────────────────┐
│  校验图形验证码                                  │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  检查短信验证码是否正确                          │
│  Redis: sms_token:{phone+sms}                   │
│  不存在或已过期 → 返回"验证码错误"               │
└─────────────────────┬───────────────────────────┘
                      │ 验证码正确
                      ▼
┌─────────────────────────────────────────────────┐
│  根据手机号查询用户                              │
│  yhxxService.getYhxxBySjhm(phone)              │
│  用户不存在 → 返回"该手机号未注册"              │
└─────────────────────┬───────────────────────────┘
                      │ 用户存在
                      ▼
┌─────────────────────────────────────────────────┐
│  创建访问令牌(同账号密码登录)                    │
└─────────────────────────────────────────────────┘
```

**API 路径：** `POST /sso/auth/loginBySMS`

**请求参数：**
```json
{
  "sjhm": "string",               // 手机号
  "sms": "string",                // 短信验证码
  "captchaVerification": "uuid",  // 图形验证码UUID
  "captchaCode": "string"         // 图形验证码内容
}
```

### 3.3 DID 登录（去中心化身份）

**概述：** DID登录是基于区块链的去中心化身份认证，用户通过DID APP扫描二维码获取可验证凭证（Verifiable Presentation），完成身份认证。

**关键概念：**
- **DID（Decentralized Identifier）**：去中心化身份标识符
- **VP（Verifiable Presentation）**：可验证展示，包含用户身份证明
- **VC（Verifiable Credential）**：可验证凭证，由可信签发者签发

**完整流程（时序图）：**

```
┌─────────┐         ┌─────────┐         ┌─────────┐         ┌─────────┐
│  用户   │         │ 前端    │         │ SSO服务  │         │DID服务   │
└────┬────┘         └────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │                   │
     │  1.点击登录        │                   │                   │
     │──────────────────>│                   │                   │
     │                   │                   │                   │
     │  2.请求二维码       │                   │                   │
     │                   │POST /did/pub/login/qrcode            │
     │                   │───────────────────────────────────────>
     │                   │                   │                   │
     │                   │                   │  3.生成reqId      │
     │                   │                   │  4.缓存状态=PAGE  │
     │                   │                   │                   │
     │                   │  5.返回{reqId, url}│                   │
     │                   │<───────────────────────────────────────│
     │                   │                   │                   │
     │  6.显示二维码       │                   │                   │
     │<───────────────────│                   │                   │
     │                   │                   │                   │
     │  7.扫描二维码       │                   │                   │
     │───────────────────────────────────────────────────────────│
     │                   │                   │                   │
     │                   │                   │  8.用户在DID APP  │
     │                   │                   │     确认授权      │
     │                   │                   │                   │
     │  9.VP返回          │                   │                   │
     │<──────────────────────────────────────────────────────────│
     │                   │                   │                   │
     │  10.提交VP验证     │                   │                   │
     │                   │POST /did/pub/getvp/login?reqId=xxx   │
     │                   │───────────────────────────────────────>
     │                   │                   │                   │
     │                   │                   │  11.验证VP         │
     │                   │                   │  12.更新状态=QR    │
     │                   │                   │                   │
     │                   │                   │  13.DID回调        │
     │                   │                   │POST /did/pub/callback/login
     │                   │                   │<──────────────────────────────────────────────────│
     │                   │                   │                   │
     │                   │                   │  14.验证VP签名     │
     │                   │                   │                   │
     │                   │                   │  15.提取身份信息   │
     │                   │                   │     (手机号/DID)   │
     │                   │                   │                   │
     │                   │                   │  16.查询/创建用户  │
     │                   │                   │     绑定DID       │
     │                   │                   │                   │
     │                   │                   │  17.更新状态=CALLBACK│
     │                   │                   │                   │
     │                   │  18.轮询结果       │                   │
     │                   │GET /did/pub/backresult/login?reqId=xxx│
     │                   │───────────────────────────────────────>
     │                   │                   │                   │
     │                   │                   │  19.检查状态      │
     │                   │                   │  20.返回用户信息  │
     │                   │  21.返回authLoginRespVO               │
     │                   │<───────────────────────────────────────│
     │                   │                   │                   │
     │  22.登录成功       │                   │                   │
     │<───────────────────│                   │                   │
```

**DID登录状态机：**

| 状态 | 值 | 说明 |
|------|---|------|
| PAGE | 1 | 初始状态，等待扫码 |
| QR | 2 | 已扫码，等待授权 |
| CALLBACK | 3 | 已授权，流程完成 |
| PHONE_BIND | 4 | 需要手机号绑定（手机号为空时） |
| BUSI_FAILURE | 5 | 认证失败 |
| BUSI_SUCCESS | 6 | 认证成功 |

**伪代码：**

```java
// ========== DID Controller ==========

/**
 * 1. 获取登录二维码
 * 流程：请求DID服务端获取二维码URL，生成reqId并缓存状态
 */
@PostMapping("/pub/login/qrcode")
public CommonResult<QrCodeInfo> getLoginUrlQRCode() {
    // 1. 从系统参数获取DID登录VP请求地址
    String vpUrl = XtcsUtils.getXtcs("TXW_DID_LOGIN_VP_URL");
    
    // 2. 生成唯一请求标识
    String reqId = UUID.randomUUID().toString() + UUID.randomUUID().toString();
    
    // 3. 构建完整URL
    String qrCodeUrl = vpUrl + "?reqId=" + reqId;
    
    // 4. 缓存请求状态（30分钟过期）
    CacheUtils.cacheData("TXW:DID:REQ:ID:" + reqId, "1", 30*60*1000);
    
    // 5. 返回二维码信息
    return CommonResult.success(QrCodeInfo.builder()
        .reqId(reqId)
        .url(qrCodeUrl)
        .build());
}

/**
 * 2. 获取登录凭证（VP）
 * 流程：验证状态，调用DID SDK构建VP请求
 */
@GetMapping("/pub/getvp/login")
public String getLoginVP(@RequestParam String reqId) {
    // 1. 验证请求状态
    String status = CacheUtils.getCacheData("TXW:DID:REQ:ID:" + reqId);
    if (!"1".equals(status)) {
        return jsonError("请求状态不正确，请重新操作");
    }
    
    // 2. 更新状态为已扫码
    CacheUtils.cacheData("TXW:DID:REQ:ID:" + reqId, "2");
    
    // 3. 创建DID客户端
    IDidClient didClient = new DidClient(
        XtcsUtils.getXtcs("TXW_DID_CONSOLE_LOGIN_URL"),
        DidClient.version15
    );
    
    // 4. DID控制台登录
    Response<AccessToken> login = didClient.login(
        XtcsUtils.getXtcs("TXW_DID_CONSOLE_USERNAME"),
        XtcsUtils.getXtcs("TXW_DID_CONSOLE_PASSWORD")
    );
    
    // 5. 构建VP请求扩展信息
    LoginExtend extend = LoginExtend.builder()
        .requestId(reqId)
        .method("POST")
        .callbackUrl(callbackUrl + "?reqId=" + reqId)
        .authorizedName("碳信网")
        .authorizedNameEn("TanxinWeb")
        .build();
    
    // 6. 添加需要获取的凭证类型
    List<DidExtendVcsInfo> vcs = new ArrayList<>();
    vcs.add(DidExtendVcsInfo.builder()
        .vctId("100001")  // 个人身份凭证
        .vctVersion("v9")
        .issuer("did:cndid:cndid")
        .build());
    extend.setVcs(vcs);
    
    // 7. 构建可验证展示
    VerifiablePresentation<LoginExtend> loginvp = VerifiablePresentation.builder()
        .presentationUsage("DID_LOGIN_REQUEST")
        .proof(proofList)
        .extend(extend)
        .build();
    
    // 8. 生成并签名VP
    Response<VerifiablePresentation<LoginExtend>> res = 
        didClient.vpSign(loginvp, LoginExtend.class);
    
    // 9. 返回VP JSON
    return JsonUtils.toJson(res);
}

/**
 * 3. 登录回调处理
 * 流程：DID服务端回调，验证VP，创建/绑定用户
 */
@PostMapping("/pub/callback/login")
public String getLoginVPCallback(@RequestParam String reqId, 
                                  @RequestBody Map<String, Object> vpRequestBody) {
    // 1. 解析VP
    VerifiablePresentation request = BeanUtils.toBean(vpRequestBody, 
        VerifiablePresentation.class);
    
    // 2. 验证VP签名
    String checkMsg = checkvp(request);
    if (checkMsg != null) {
        return jsonError(checkMsg);
    }
    
    // 3. 更新状态为已回调
    CacheUtils.cacheData("TXW:DID:REQ:ID:" + reqId, "3");
    
    // 4. 提取凭证信息
    List<VerifiableCredential> vcList = request.getVerifiableCredential();
    if (vcList == null || vcList.isEmpty()) {
        return jsonError("凭证为空");
    }
    
    VerifiableCredential vc = vcList.get(0);
    String holderDid = vc.getHolder();  // 获取DID标识
    
    // 5. 提取身份信息
    DidCredentialSubject cs = BeanUtils.toBean(vc.getCredentialSubject(), 
        DidCredentialSubject.class);
    String phone = cs.getPhone();  // 手机号
    String legalName = cs.getLegalName();  // 法人姓名
    String entName = cs.getEntname();  // 企业名称
    
    // 6. 根据不同条件查找/创建用户
    YhxxbDTO yhxx = null;
    if (StringUtils.isNotBlank(phone)) {
        // 6.1 根据手机号查找
        yhxx = yhxxService.getYhxxBySjhm(phone);
    } else if (idCard != null) {
        // 6.2 根据身份证查找
        yhxx = yhxxService.getYhxxBySfzjhm(idCard);
    } else {
        // 6.3 根据DID查找
        yhxx = yhxxService.getYhxxByDid(holderDid);
    }
    
    if (yhxx == null && StringUtils.isBlank(phone)) {
        // 6.4 手机号为空，需要后续绑定
        CacheUtils.cacheData("TXW:DID:USER:DID:" + reqId, holderDid, 30*60*1000);
        CacheUtils.cacheData("TXW:DID:USER:DID:Data:" + reqId, 
            JsonUtils.toJson(cs), 30*60*1000);
        CacheUtils.cacheData("TXW:DID:REQ:ID:" + reqId, "4");  // PHONE_BIND
        return jsonSuccess("需要手机绑定");
    }
    
    if (yhxx == null && StringUtils.isNotBlank(phone)) {
        // 6.5 新用户，创建用户
        yhxx = new YhxxbDTO();
        yhxx.setYhUuid(IdUtil.fastSimpleUUID());
        yhxx.setDid(holderDid);
        yhxx.setSjhm1(phone);
        yhxx.setDlzh(phone);
        yhxx.setZsxm1(legalName != null ? legalName : entName);
        yhxx = yhxxService.saveYhxxByDid(yhxx);
    } else {
        // 6.6 已有用户，绑定DID
        yhxx.setDid(holderDid);
        yhxxService.updateDid(yhxx);
    }
    
    // 7. 创建企业信息（DID企业认证）
    if (StringUtils.isNotBlank(entName)) {
        YhxxbDTO qyxx = new YhxxbDTO();
        qyxx.setQymc(entName);
        qyxx.setNsrsbh(cs.getUniscid());  // 统一社会信用代码
        qyxx.setYhUuid(yhxx.getYhUuid());
        yhxxService.intQyxxByDid(qyxx);
    }
    
    // 8. 缓存用户信息
    CacheUtils.cacheData("TXW:DID:USER:Data:" + reqId, 
        JsonUtils.toJson(yhxx), 30*60*1000);
    
    return jsonSuccess("true");
}

/**
 * 4. 查询登录结果（轮询）
 * 流程：前端轮询检查状态，返回accessToken
 */
@GetMapping("/pub/backresult/login")
public CommonResult<R> getLoginCallbackResult(@RequestParam String reqId) {
    // 1. 获取状态
    String status = CacheUtils.getCacheData("TXW:DID:REQ:ID:" + reqId);
    
    if ("6".equals(status)) {  // 认证成功
        // 2. 获取用户信息
        String userJson = CacheUtils.getCacheData("TXW:DID:USER:Data:" + reqId);
        YhxxbDTO yhxx = JsonUtils.toBean(userJson, YhxxbDTO.class);
        
        // 3. 创建Token
        OAuth2AccessTokenDO accessTokenDO = oauth2TokenService.createAccessToken(
            yhxx.getYhUuid(), "default", null);
        
        // 4. 返回登录凭证
        AuthLoginRespVO respVO = new AuthLoginRespVO();
        respVO.setAccessToken(accessTokenDO.getAccessToken());
        respVO.setRefreshToken(accessTokenDO.getRefreshToken());
        respVO.setExpiresTime(accessTokenDO.getGqsj());
        
        // 5. 写入Cookie
        Cookie cookie = new Cookie("TXW_TOKEN", accessTokenDO.getAccessToken());
        cookie.setPath("/");
        cookie.setHttpOnly(true);
        response.addCookie(cookie);
        
        return CommonResult.success(R.ok().put("status", status)
            .put("authLoginRespVO", respVO));
    } else if ("5".equals(status)) {  // 认证失败
        String msg = CacheUtils.getCacheData("TXW:DID:BUSI:FAILURE:MSG:" + reqId);
        return CommonResult.success(R.ok().put("status", status).put("msg", msg));
    }
    
    // 继续轮询
    return CommonResult.success(R.ok().put("status", status));
}

/**
 * 5. DID绑定手机号（DID用户关联手机号）
 */
@PostMapping("/auth/didBindPhone")
public CommonResult<AuthLoginRespVO> didBindPhone(@RequestBody DidBindPhoneReqVO reqVO) {
    // 1. 验证短信验证码
    String sms = reqVO.getSms();
    String phone = reqVO.getSjhm();
    if (!stringRedisTemplate.hasKey("sms_token:" + phone + sms)) {
        throw exception("验证码错误");
    }
    
    // 2. 获取缓存的DID信息
    String reqId = reqVO.getReqId();
    String holderDid = CacheUtils.getCacheData("TXW:DID:USER:DID:" + reqId);
    String csJson = CacheUtils.getCacheData("TXW:DID:USER:DID:Data:" + reqId);
    
    if (holderDid == null || csJson == null) {
        throw exception("缓存DID为空");
    }
    
    // 3. 创建用户
    DidCredentialSubject cs = JsonUtils.toBean(csJson, DidCredentialSubject.class);
    YhxxbDTO existYhxx = yhxxService.getYhxxBySjhm(phone);
    
    if (existYhxx != null) {
        throw exception("该手机号已注册");
    }
    
    YhxxbDTO yhxx = new YhxxbDTO();
    yhxx.setYhUuid(IdUtil.fastSimpleUUID());
    yhxx.setDid(holderDid);
    yhxx.setSjhm1(phone);
    yhxx.setDlzh(phone);
    yhxx.setZsxm1(cs.getLegalName() != null ? cs.getLegalName() : cs.getEntname());
    yhxx = yhxxService.saveYhxxByDid(yhxx);
    
    // 4. 创建企业信息
    YhxxbDTO qyxx = new YhxxbDTO();
    qyxx.setQymc(cs.getEntname());
    qyxx.setNsrsbh(cs.getUniscid());
    qyxx.setYhUuid(yhxx.getYhUuid());
    yhxxService.intQyxxByDid(qyxx);
    
    // 5. 创建Token并返回
    return createTokenAfterLoginSuccess(yhxx.getYhUuid());
}
```

**DID SDK 调用伪代码：**

```java
// ========== DID SDK 使用示例 ==========

/**
 * DID客户端初始化
 */
IDidClient didClient = new DidClient(
    consoleUrl,           // DID控制台地址
    DidClient.version15   // API版本
);

/**
 * 1. 控制台登录
 */
Response<AccessToken> loginResponse = didClient.login(
    username,  // 用户名
    password   // 密码
);
// 返回: { code: 200000, data: { accessToken: "xxx", expiresIn: 3600 } }

/**
 * 2. 构建登录VP请求
 */
LoginExtend extend = LoginExtend.builder()
    .requestId(reqId)           // 请求唯一标识
    .method("POST")              // 回调方法
    .callbackUrl(callbackUrl)   // 回调地址
    .authorizedName("碳信网")    // 授权平台名称
    .authorizedNameEn("TanxinWeb")
    .build();

List<Proof> proofList = new ArrayList<>();

VerifiablePresentationBuilder<LoginExtend> builder = 
    VerifiablePresentation.builder();
builder.presentationUsage("DID_LOGIN_REQUEST");
builder.proof(proofList);
builder.extend(extend);

VerifiablePresentation<LoginExtend> loginvp = builder.build();

/**
 * 3. 生成并签名VP
 */
Response<VerifiablePresentation<LoginExtend>> signResponse = 
    didClient.vpSign(loginvp, LoginExtend.class);
// 返回签名后的VP JSON

/**
 * 4. 验证VP
 */
Response<Boolean> verifyResponse = didClient.vpVerify(vpJson);
// 返回: { code: 200000, data: true/false }

/**
 * 5. 提取凭证信息
 */
VerifiableCredential vc = vp.getVerifiableCredential().get(0);
String holderDid = vc.getHolder();  // DID标识符
DidCredentialSubject subject = vc.getCredentialSubject();
// subject.getPhone()      - 手机号
// subject.getLegalName()  - 法人姓名
// subject.getEntname()    - 企业名称
// subject.getUniscid()    - 统一社会信用代码
```

**VP数据结构示例：**

```json
{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiablePresentation"],
  "holder": "did:cndid:xxxxxx",
  "verifiableCredential": [{
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiableCredential"],
    "credentialSubject": {
      "id": "did:cndid:xxxxxx",
      "phone": "13800138000",
      "legalName": "张三",
      "entname": "示例企业",
      "uniscid": "91110000xxxxxxxxxx"
    },
    "proof": {
      "type": "EcdsaSecp256k1Signature2019",
      "creator": "did:cndid:issuer",
      "created": "2025-01-01T00:00:00Z"
    }
  }],
  "proof": {
    "type": "EcdsaSecp256k1Signature2019",
    "created": "2025-01-01T00:00:00Z"
  }
}
```

**前端轮询实现伪代码：**

```javascript
/**
 * DID登录轮询
 */
async pollLoginResult() {
    while (this.isPolling) {
        try {
            // 1. 查询登录结果
            const { data } = await rzbackresultlogin(this.reqId);
            
            // 2. 根据状态处理
            switch (data.status) {
                case 6:  // 认证成功
                    this.stopPolling();
                    await this.yhinit();  // 刷新用户信息
                    break;
                    
                case 5:  // 认证失败
                    this.stopPolling();
                    MessagePlugin.info({ content: data.msg });
                    break;
                    
                case 4:  // 需要手机绑定
                    // 显示手机绑定界面
                    this.showPhoneBind = true;
                    this.stopPolling();
                    break;
                    
                default:  // 继续轮询
                    // 2秒后继续
                    await new Promise(resolve => setTimeout(resolve, 2000));
                    break;
            }
        } catch (error) {
            console.error('查询失败', error);
            // 1.5秒后重试
            await new Promise(resolve => setTimeout(resolve, 1500));
        }
    }
}

/**
 * 生成二维码
 */
generateQRCode() {
    new QRCode(this.$refs.qrcodeElement, {
        text: this.qrcodeText,
        width: 200,
        height: 200,
        colorDark: '#000000',
        colorLight: '#ffffff',
        correctLevel: QRCode.CorrectLevel.H
    });
}
```

### 3.4 OAuth2 授权码模式

```
用户访问第三方应用
         │
         ▼
┌─────────────────────────────────────────────────┐
│  第三方应用重定向到授权页面                       │
│  GET /oauth2/authorize?clientId=xxx&redirectUri= │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  用户在授权页面点击授权                          │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  生成授权码                                      │
│  oauth2CodeService.createCode()                 │
│  → 存储到数据库(10分钟过期)                      │
│  → 重定向到第三方应用redirectUri?code=xxx        │
└─────────────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  第三方应用用授权码换取令牌                       │
│  POST /oauth2/token/create                       │
│  → 验证clientId + clientSecret                   │
│  → 验证授权码                                    │
│  → 生成 accessToken + refreshToken               │
│  → 返回令牌                                      │
└─────────────────────────────────────────────────┘
```

---

## 四、Token 创建与刷新机制

### 4.1 创建访问令牌

```java
// OAuth2TokenServiceImpl.createAccessToken()
1. 验证客户端配置 (clientId)
2. 创建 SessionInfo
3. 创建 refreshToken (如果非default客户端)
4. 创建 accessToken
5. 存储到数据库
6. 缓存到 Redis
7. 返回令牌信息
```

**Redis Key 格式：**
```
oauth2_access_token:{accessToken} → SessionInfo JSON
```

### 4.2 刷新令牌

```
用户使用 refreshToken 请求刷新
         │
         ▼
┌─────────────────────────────────────────────────┐
│  验证 refreshToken 是否有效                      │
│  → 检查是否过期                                 │
│  → 检查 clientId 是否匹配                        │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  删除旧的 accessToken                           │
│  → 从数据库删除                                 │
│  → 从 Redis 删除                                │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  生成新的 accessToken                           │
│  → 沿用原来的 refreshToken                      │
│  → 更新过期时间                                 │
└─────────────────────────────────────────────────┘
```

**API 路径：** `PUT /oauth2/token/refresh?refreshToken=xxx&clientId=xxx`

---

## 五、验证码服务

### 5.1 图形验证码

```
请求获取验证码
         │
         ▼
┌─────────────────────────────────────────────────┐
│  生成验证码 UUID + 图片                          │
│  verifyService.getCaptcha(remoteId)             │
│  → UUID 存入 Redis (5分钟过期)                   │
│  → 返回 { uuid, 图片Base64 }                    │
└─────────────────────────────────────────────────┘

校验验证码
         │
         ▼
┌─────────────────────────────────────────────────┐
│  verifyService.checkCaptcha(uuid, code)         │
│  → 从 Redis 获取 UUID 对应的验证码                │
│  → 比较用户输入与存储的验证码(忽略大小写)          │
│  → 验证后删除 Redis 记录                         │
└─────────────────────────────────────────────────┘
```

### 5.2 短信验证码

```
发送短信请求
         │
         ▼
┌─────────────────────────────────────────────────┐
│  校验图形验证码                                  │
└─────────────────────┬───────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────┐
│  检查手机号是否被锁定                            │
│  Redis: sms_token:{phone} 存在则锁定             │
│  锁定中 → 返回"操作过于频繁"                     │
└─────────────────────┬───────────────────────────┘
                      │ 未锁定
                      ▼
┌─────────────────────────────────────────────────┐
│  发送短信                                        │
│  smService.sendCaptcha(phone, code)              │
│  → 调用外部短信网关(阿里云)                      │
│  → 验证码存入 Redis: sms_token:{phone+code}      │
│    有效期3分钟                                  │
└─────────────────────────────────────────────────┘
```

**Redis Key 规则：**
```
sms_token:{phone}         → 锁定标记(1分钟)
sms_token:{phone+code}   → 验证码(3分钟)
```

---

## 六、外部服务依赖

### 6.1 依赖关系图

```
                    ┌──────────────────┐
                    │   外部服务       │
                    └───────┬──────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  短信网关     │    │  DID服务     │    │  mhzc服务    │
│ (阿里云)      │    │ (ChainWeaver)│   │ (用户中心)   │
└──────────────┘    └──────────────┘    └──────────────┘
        │                   │                   │
        │                   │                   │
        ▼                   ▼                   ▼
┌──────────────────────────────────────────────────┐
│              txw-sso 服务                        │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │
│  │ AuthService │ │ DidController│ │YhxxService │ │
│  └─────────────┘ └─────────────┘ └────────────┘ │
└──────────────────────────────────────────────────┘
```

### 6.2 外部服务清单

| 服务 | 依赖方式 | 用途 |
|------|---------|------|
| **短信网关(阿里云)** | REST API | 发送短信验证码 |
| **DID服务** | SDK (org.chainweaver.did.sdk) | DID登录、企业实名认证 |
| **txw-mhzc** | Feign RPC | 用户信息查询、用户注册 |

### 6.3 短信网关配置

```java
// SMSConfig 配置
sms.host      → 短信API地址
sms.app       → 应用标识
sms.key       → 密钥(用于签名校验)
sms.template  → 短信模板(验证码内容格式)
```

**签名校验算法：**
```java
vcode = MD5(MD5(timestamp + app + token + key))
```

### 6.4 DID 服务配置

| 配置项 | 说明 |
|--------|------|
| `TXW_DID_LOGIN_VP_URL` | 登录凭证请求地址 |
| `TXW_DID_BUSI_LICE_VP_URL` | 企业实名凭证请求地址 |
| `TXW_DID_LOGIN_CALLBACK_URL` | 登录回调地址 |
| `TXW_DID_BUSI_LICE_CALLBACK_URL` | 企业实名回调地址 |
| `TXW_DID_CONSOLE_LOGIN_URL` | DID控制台登录地址 |
| `TXW_DID_CONSOLE_USERNAME` | DID控制台用户名 |
| `TXW_DID_CONSOLE_PASSWORD` | DID控制台密码 |
| `TXW_DID_CONSOLE_DIDCODE` | DID标识 |
| `TXW_DID_AUTH_NAME` | 授权平台名称 |
| `TXW_DID_AUTH_EN_NAME` | 授权平台英文名称 |

---

## 七、Redis 缓存设计

### 7.1 Key 规则汇总

| Key Pattern | 值类型 | 过期时间 | 用途 |
|------------|-------|---------|------|
| `oauth2_access_token:%s` | SessionInfo JSON | 动态(令牌过期时间) | 访问令牌缓存 |
| `sms_token:%s` | phone | 1分钟 | 手机号锁定 |
| `sms_token:%s%s` | phone | 3分钟 | 短信验证码 |
| `TXW:DID:REQ:ID:%s` | status | 30分钟 | DID请求状态 |
| `TXW:DID:USER:DID:%s` | did | 30分钟 | DID用户绑定 |
| `TXW:DID:USER:DID:Data:%s` | DidCredentialSubject JSON | 30分钟 | DID用户数据 |
| `TXW:DID:USER:Data:%s` | YhxxbDTO JSON | 30分钟 | DID登录用户信息 |
| `TXW:DID:BUSI:FAILURE:MSG:%s` | msg | 30分钟 | DID认证失败消息 |

### 7.2 账户锁定 Key

| Key Pattern | 说明 |
|------------|------|
| `account_lock:%s` | 账户锁定标记 |

**锁定规则：** 密码连续错误5次，锁定30分钟

---

## 八、接口清单

### 8.1 认证接口 (/auth)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/auth/login` | POST | 账号密码登录 |
| `/auth/logout` | POST | 登出 |
| `/auth/refresh-token` | POST | 刷新令牌 |
| `/auth/sendMsg` | POST | 发送短信验证码 |
| `/auth/loginBySMS` | POST | 短信验证码登录 |
| `/auth/didBindPhone` | POST | DID绑定手机号 |
| `/auth/changePassword` | POST | 修改密码 |
| `/auth/resetPassword` | POST | 重置密码(管理员) |

### 8.2 OAuth2接口 (/oauth2)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/oauth2/token/create` | POST | 创建令牌 |
| `/oauth2/token/check` | GET | 校验令牌 |
| `/oauth2/token/remove` | DELETE | 删除令牌 |
| `/oauth2/token/refresh` | PUT | 刷新令牌 |
| `/oauth2/authorize` | GET | 授权码模式授权 |
| `/oauth2/authorize` | POST | 授权确认 |

### 8.3 验证码接口 (/verify)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/verify/get` | POST | 获取滑动验证码 |
| `/verify/captcha` | POST | 获取图形验证码 |
| `/verify/checkCaptcha` | POST | 校验图形验证码 |

### 8.4 DID接口 (/did)

| 接口 | 方法 | 说明 |
|------|------|------|
| `/did/pub/login/qrcode` | POST | 获取登录二维码 |
| `/did/pub/getvp/login` | GET | 获取登录凭证 |
| `/did/pub/callback/login` | POST | 登录回调 |
| `/did/pub/backresult/login` | GET | 查询登录结果 |
| `/did/busilice/qrcode` | POST | 获取认证二维码 |
| `/did/pub/getvp/busi` | GET | 获取企业实名凭证 |
| `/did/pub/callback/busi` | POST | 企业实名回调 |
| `/did/pub/backresult/busi` | GET | 查询认证结果 |

---

## 九、安全机制

### 9.1 密码安全

- 密码使用 **MD5** 存储（实际应为更安全的哈希算法）
- 支持密码复杂度校验（6-20位，字母+数字）
- 新旧密码不能相同

### 9.2 防暴力破解

- 密码连续错误5次，锁定账户30分钟
- 短信验证码错误3次，锁定手机号1分钟
- 验证码一次性使用，验证后立即失效

### 9.3 Token安全

- AccessToken 默认有效期：2小时（从客户端配置读取）
- RefreshToken 默认有效期：30天
- Token 支持客户端关联，支持第三方平台SSO

### 9.4 Cookie安全

```java
Cookie cookie = new Cookie(COOKIE_TOKEN_KEY, token);
cookie.setPath("/");
cookie.setHttpOnly(true);  // 防止XSS读取
// cookie.setMaxAge(-1);  // 浏览器会话级别
```

---

## 十、错误码

| 错误码 | 说明 |
|--------|------|
| `AUTH_LOGIN_BAD_CREDENTIALS` | 用户名或密码错误 |
| `AUTH_LOGIN_CAPTCHA_CODE_ERROR` | 验证码错误 |
| `AUTH_LOGIN_PASSWORD_ERROR_LOCK` | 密码错误次数过多，账户已锁定 |
| `AUTH_PASSWORD_CONFIRM_MISMATCH` | 新密码与确认密码不一致 |
| `AUTH_PASSWORD_COMPLEXITY_INVALID` | 密码复杂度不符合要求 |
| `AUTH_PASSWORD_SAME_AS_OLD` | 新密码不能与旧密码相同 |
| `OAUTH2_SJHM_LOCK` | 手机号操作过于频繁 |
| `OAUTH2_SJHM_NOT_EXISTS` | 手机号未注册 |
| `OAUTH2_LOGIN_SMS_NOT_EXISTS` | 短信验证码不存在或已过期 |
| `OAUTH2_LOGIN_SJHM_NOT_EXISTS` | 短信登录手机号不存在 |

---

*文档生成时间: 2026-05-03*
*基于 txw-sso 服务代码分析*