登录体系统一整合方案

日期：2026-06-29 | 基于《统一认证服务（UAS）概要设计 v3》及 VTS 消息推送需求

1. 现状梳理与问题定义

1.1 涉及系统与组件总览

1.2 各端登录流程现状

1.3 核心问题分析

问题一：openID/unionid 分散

现状：

• 每个微信小程序和公众号各自持有独立的 openID
• unionid 需要所有应用绑定到同一微信开放平台账号才能获取
• 当前 openID 存储分散：通行证存一部分、微信代理存一部分、教学服务存一部分
• 语雀文档明确指出："openid 不在通行证关联，因为全日制或者有些业务不用通行证"

断裂点：

1. 城市服务号与通行证之间没有直接关联，openID 存于教学服务
2. 全日制业务不使用通行证，其用户的 openID 与通行证体系完全脱节
3. 不同公众号的 openID 无法直接互通，依赖 unionid 桥接但覆盖不全

问题二：多端登录不互通

现状：

• 小程序走 UAS（Token-Based）
• H5/Web 走 SSO（CAS Cookies/Session）
• 公众号 H5 走微信 OAuth2，业务系统自行处理身份
• UAS 与 SSO 之间仅有单向桥接（小程序 -> H5），缺少反向桥接

断裂点：

1. 公众号 H5 场景下获取的 openID 无法与 UAS 通行证身份关联
2. SSO 登录后无法获取 UAS Token，Web 端与小程序端身份不互通
3. 各业务系统（网报、TMS/evip）接入认证方式不统一

问题三：消息推送与身份脱节

现状：

• VTS 按城市服务号推送模板消息，需要知道用户在目标服务号下的 openID
• openID 来源分散：通行证、微信代理、教学服务各自存储
• VTS 无法统一查询"某用户在某服务号下的 openID"

断裂点：

1. 用户更换城市后，新城市服务号的 openID 可能未被记录
2. 会员库 memberid 与服务号 openID 之间缺少统一映射
3. "不关注公众号也可获取 openID"的场景下，openID 的存储与查询链路不清晰

2. openID/unionid 统一管理方案

2.1 核心原则

1. unionid 作为微信生态层的统一用户标识：所有公众号、小程序必须绑定到同一微信开放平台账号，确保 unionid 可获取
2. openID 映射集中管理：建立统一的 openID 映射表，收口各渠道的 openID 数据
3. 兼容非通行证用户：全日制等不使用通行证的业务，通过会员 memberid 关联，不强制绑定通行证

2.2 微信开放平台绑定要求

前提条件：所有应用必须绑定到同一微信开放平台账号，否则无法获取 unionid，跨应用身份打通将无法实现。

2.3 openID 映射表设计

在 UCOUT 服务中新建统一的微信身份映射表，收口所有 openID 数据：

-- 微信身份映射表（集中管理所有公众号/小程序的 openID）
CREATE TABLE pp_wechat_openid_map (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    unionid         VARCHAR(64)  NULL     COMMENT '微信 unionid（开放平台绑定后可获取）',
    openid          VARCHAR(64)  NOT NULL COMMENT '微信 openid',
    wechat_type     VARCHAR(32)  NOT NULL COMMENT '微信应用类型标识（对应 UCOUT wechat_type）',
    app_id          VARCHAR(64)  NOT NULL COMMENT '微信应用 AppID',
    app_category    VARCHAR(16)  NOT NULL COMMENT '应用类别：miniprogram / mp_service / mp_subscribe',
    pptid           BIGINT       NULL     COMMENT '通行证 ID（已绑定时关联）',
    member_id       BIGINT       NULL     COMMENT '会员库 memberid（非通行证用户关联）',
    bindsource      VARCHAR(16)  NULL     COMMENT '绑定来源：passport / member / teaching',
    status          TINYINT      DEFAULT 1 COMMENT '状态：1-有效 0-无效',
    created_at      DATETIME     DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_openid_apptype (openid, wechat_type),
    KEY idx_unionid (unionid),
    KEY idx_pptid (pptid),
    KEY idx_member_id (member_id),
    KEY idx_appid (app_id)
) COMMENT '微信 openID 统一映射表';

表设计说明：

• unionid 可为空：部分场景下（如用户仅在某公众号内授权）可能暂时拿不到 unionid
• pptid 可为空：兼容全日制等不使用通行证的业务，通过 member_id 关联
• bindsource 标记数据来源：passport（通行证绑定）、member（会员库关联）、teaching（教学服务同步）
• 唯一键 (openid, wechat_type) 确保同一应用下 openID 不重复

2.4 与 UCOUT 现有接口的关系

当前 UCOUT 提供的微信相关接口：

新增接口：

# 根据 unionid 查询用户在指定公众号下的 openID
POST /ucout/wechat/openid/query
Content-Type: application/json

{
    "unionid": "xxx",          // 或 member_id
    "target_app_id": "xxx"     // 目标公众号/小程序的 AppID
}

# 响应
{
    "openid": "xxx",
    "wechat_type": "xxx",
    "bindstatus": "bound"      // bound / unbound
}

# 批量同步 openID 数据（用于历史数据迁移）
POST /ucout/wechat/openid/sync
Content-Type: application/json

{
    "records": [
        {
            "openid": "xxx",
            "wechat_type": "xxx",
            "unionid": "xxx",
            "pptid": 123,
            "member_id": 456,
            "bindsource": "teaching"
        }
    ]
}

2.5 非通行证用户的兼容方案

针对全日制等不使用通行证的业务：

1. 通过会员 memberid 关联：openID 映射表中 pptid 为空时，使用 member_id 作为关联键
2. 双通道查询：VTS 查询 openID 时，优先通过 unionid 查询，其次通过 member_id 查询
3. 渐进式绑定：非通行证用户后续如使用小程序等功能，引导绑定通行证后自动补充 pptid

3. 多端登录互通方案

3.1 目标

所有端（小程序、公众号 H5、Web）的登录认证统一收口到 UAS，各业务系统只需对接 UAS 即可完成身份认证。

3.2 各端登录流程统一设计

3.2.1 小程序登录（保持不变）

3.2.2 公众号 H5 登录（新增 grant_type）

场景：用户在公众号内访问 H5 页面，通过公众号 OAuth2 授权获取身份。

新增 UAS grant_type：mp_oauth（公众号网页授权模式）

接口定义：

# 公众号 H5 网页授权模式获取令牌
POST /uas/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=mp_oauth
&app_id=wxXXX
&login_code=微信OAuth2授权码
&client_id=xxx
&client_secret=xxx

# 成功响应
{
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 7200,
    "scope": "openid profile",
    "pptid": 12345,
    "openid": "xxx",
    "unionid": "xxx"
}

3.2.3 小程序 -> H5 联合认证（保持现有方案）

现有 UAS 联合认证方案（authorize_type=sso_auth）已满足此场景，无需改造：

1. 小程序使用已有 access_token 请求 UAS 获取 uas_sso_code
2. 携带 uas_sso_code 跳转到 H5 页面的 SSO 登录链接
3. H5 页面通过 SSO 验证 uas_sso_code 完成登录

3.2.4 Web 端 SSO 登录（保持 + 补充 Token 互认）

保持现有 SSO 登录流程不变，补充 SSO -> UAS Token 互认能力：

新增 UAS grant_type：sso_bridge（SSO 桥接模式），让 Web 端业务系统在 SSO 登录后也能获取 UAS Token，实现与小程序端的身份互通。

# SSO 桥接模式获取 UAS Token
POST /uas/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=sso_bridge
&sso_ticket=ST-xxx
&client_id=xxx
&client_secret=xxx

3.2.5 各业务系统统一接入规范

4. 消息推送与身份关联方案

4.1 问题定义

VTS 消息推送的核心链路：

业务系统触发事件 -> VTS 消息服务 -> 确定目标城市+服务号 -> 查找用户在该服务号下的 openID -> 发送模板消息

当前断裂点：VTS 无法可靠地查到"某用户在某城市服务号下的 openID"。

4.2 openID 查询方案

方案：VTS 通过 UCOUT 统一查询 openID

4.3 openID 数据采集策略

针对不同场景，openID 写入映射表的时机和方式：

4.4 关键约束处理

约束 1："不关注公众号也可获取 openID"

微信公众号 OAuth2 网页授权（scope=snsapi_base）可以在用户不关注公众号的情况下获取 openID。因此：

• 用户通过公众号内 H5 页面 OAuth2 授权时，openID 即可写入映射表
• 无需等用户关注公众号，只要用户点击进入公众号菜单/链接触发 OAuth2 即可

约束 2："用户可在新城市公众号登录绑定"

用户跨城市场景：

1. 用户原在城市 A 的服务号有 openID_A
2. 用户到城市 B 后，进入城市 B 公众号，OAuth2 授权获取 openID_B
3. 通过 unionid 关联，系统识别为同一用户
4. openID_B 自动写入映射表，VTS 后续可向城市 B 服务号推送消息

约束 3："openid 不在通行证关联"

对于全日制等不使用通行证的业务：

• openID 映射表支持 pptid 为空，通过 member_id 关联
• VTS 查询 openID 时支持按 member_id 查询
• 业务系统触发消息推送时，传递 member_id 而非 pptid

4.5 VTS 对接接口

UCOUT 新增查询接口：

# VTS 查询目标 openID
POST /ucout/wechat/openid/resolve
Content-Type: application/json

{
    "member_id": 12345,        // 会员 memberid（优先）
    "unionid": "xxx",          // 或 unionid（兜底）
    "target_app_id": "wxXXX"   // 目标服务号 AppID
}

# 响应
{
    "openid": "oXXXX",         // 目标服务号下的 openID
    "found": true
}

VTS 服务号配置表（VTS 自身维护）：

-- VTS 城市与服务号关系（语雀文档中已规划）
CREATE TABLE vts_city_service (
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    city_code   VARCHAR(16)  NOT NULL COMMENT '城市编码',
    app_id      VARCHAR(64)  NOT NULL COMMENT '服务号 AppID',
    app_name    VARCHAR(128) NULL     COMMENT '服务号名称',
    status      TINYINT      DEFAULT 1,
    created_at  DATETIME     DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_city_app (city_code, app_id)
);

-- VTS 服务号与模板关系（语雀文档中已规划）
CREATE TABLE vts_template_config (
    id           BIGINT AUTO_INCREMENT PRIMARY KEY,
    app_id       VARCHAR(64)  NOT NULL COMMENT '服务号 AppID',
    template_id  VARCHAR(128) NOT NULL COMMENT '微信模板消息 ID',
    msg_type     VARCHAR(64)  NOT NULL COMMENT '消息类型标识',
    status       TINYINT      DEFAULT 1,
    created_at   DATETIME     DEFAULT CURRENT_TIMESTAMP
);

5. 整合架构总览

5.1 整合后全链路架构图

5.2 核心数据流向

6. 补充说明

6.1 迁移策略

建议分三个阶段推进：

第一阶段：基础设施搭建（1-2 周）

第二阶段：认证层改造（2-4 周）

第三阶段：业务系统接入与消息推送（2-4 周）

6.2 风险评估

6.3 与 UAS 概要设计文档的关系

本文档是 UAS 概要设计的上层补充：

• UAS 概要设计定义了"如何认证"，本文档定义了"认证后如何打通各系统"
• 本文档提出的 mp_oauth、sso_bridge 两个新 grant_type 需要在 UAS 概要设计中补充详细设计
• 本文档提出的 openID 映射表是对 UCOUT 用户数据层的扩展，不影响 UAS 核心架构