Universal Login Api

universal-login-api

多系统账户互通模块：宿主账户 ↔ 第三方应用身份的绑定，以及第三方应用的注册与密钥管理。

⚠️ 唯一权威声明

"第三方应用接入 / 应用密钥 / 账户绑定"三类需求，本技能是唯一权威。

本模块不定义账户表、不定义角色表、不定义 RBAC：

• 账户 = 宿主 wg_sys_user（由 springboot-auth-module-skill 提供）
• 角色 / 菜单 / 权限 = 宿主 wg_sys_role / _sys_menu / _sys_user_role / _sys_role_menu

历史版本自带 sys_main_account + sys_role + sys_permission 三张表，形成第二套账户与第二套 RBAC， 且 sys_app_binding.main_account_id 指向 sys_main_account，与宿主 wg_sys_user 无任何映射 —— 于是"绑定成功"也只是在绑定表里凭空加一行，登录态依然只认宿主账户。该设计已作废。

定位

一句话：让第三方系统直接复用宿主账户体系，不再各建一套用户表。

• 目标：在已有 springboot-init-skill + springboot-auth-module-skill 的骨架上，叠加应用接入与账户绑定模块。
• 输出：实体、仓储、服务、控制器、DTO、Flyway 迁移、应用签名鉴权、接口契约、Security 接入指南。
• 不做：不生成登录/注册/找回密码/验证码/JWT（宿主已有）；不生成角色与菜单（宿主已有）；不生成统一响应信封（宿主已有）。

依赖（前置，缺一不可）

本模块代码中 import 的宿主类：{{basePackage}}.common.ApiResponse、{{basePackage}}.common.CurrentUser、 {{basePackage}}.common.PageResponse、{{basePackage}}.common.BusinessException、 {{basePackage}}.auth.entity.SysUser、{{basePackage}}.auth.repository.SysUserRepository。 若宿主把账户实体放在别的包，只需改 import。

用户问题（最多 3 个）

Copy code
1. Spring 包名是什么？（默认 {{basePackage}} = com.example.demo）
2. 表前缀是什么？（默认 wg）
3. 是否启用「应用级开放接口」/api/open/**（server-to-server 签名调用）？（默认启用）

核心概念

职责收敛：App 管「应用是什么」，AppKey 管「怎么证明自己是这个应用」。 历史版本两处都存 appKey + appSecret，导致密钥可以绕过轮换长期存活 —— 已删除 App.appSecret。

能力清单（8 项）

表设计（4 张，统一 wg_ 前缀）

sqlCopy code
wg_sys_app          id, app_name, app_key, description, logo, callback_url,
                          status, owner_id, created_at, updated_at, deleted_at
                          ★ 无 app_secret

wg_sys_app_key      id, app_id, key_name, api_key, api_secret,
                          status, last_used_at, created_at, deleted_at
                          ★ api_secret 仅创建时返回一次

wg_sys_app_binding  id, sys_user_id, app_id, app_user_id, app_user_name,
                          bind_type, is_default, bind_at, created_at, deleted_at
                          UNIQUE (sys_user_id, app_id)   ★ 锚点是 sys_user_id

wg_sys_bind_code    id, code, direction, app_id, sys_user_id, app_user_id,
                          app_user_name, status, expire_at, used_at, created_at
                          ★ 一次性；direction = app_initiated / user_initiated

不建的表：sys_main_account、sys_role、sys_permission、sys_captcha （账户/角色/权限/验证码都归宿主技能，重复建表 = 双权威）。

接口清单

统一 /api 前缀，与 springboot-auth-module-skill、springboot-init-skill 一致。

A. 应用管理（宿主登录 + 权限码）

B. 账户绑定（宿主登录 + 权限码）

C. 开放接口（应用级签名，hasAuthority("APP")）

绑定流程

流程一：应用发起 → 宿主确认

Copy code
1. 用户在第三方应用 B 点击「绑定到我的宿主账号」
2. 应用 B 后端（AppKey 签名）POST /api/open/bind/apply { appUserId, appUserName }
   → 返回 { code, direction: "app_initiated", expireSeconds: 300 }
3. 用户被引导到宿主系统，若未登录先登录
4. 宿主前端 POST /api/bind/confirm { code }     ← 身份来自 JWT，不收密码
5. 落库 wg_sys_app_binding(sys_user_id = 当前用户, app_id, app_user_id)
6. 应用 B 之后可用 GET /api/open/userinfo?appUserId=xxx 换宿主用户信息

流程二：宿主发起 → 应用认领（扫码）

Copy code
1. 宿主用户在「我的绑定」选择应用 → POST /api/bind/code { appId }
   → 返回 { code, direction: "user_initiated" }（sys_user_id 此刻已写入）
2. 用户把 code（或二维码）交给第三方应用 B
3. 应用 B 后端（AppKey 签名）POST /api/open/bind/claim { code, appUserId, appUserName }
4. 绑定完成，code 立即失效

两条流程的共同硬约束：绑定码落库、5 分钟有效、一次性消费（并发下用 UPDATE ... WHERE status = 0 的受影响行数判定，返回 0 即报 -1005）。

权限码（沿用 springboot-auth-module-skill 全量表）

Copy code
system:app:list          system:app:create        system:app:edit
system:app:delete        system:app:key-manage
account:bind:list        account:bind:create      account:bind:delete
account:bind:set-default

三段式 模块:资源:动作；前端路由 meta.permission、v-permission、后端 @PreAuthorize、DB wg_sys_menu.permission 必须逐字一致。

错误码（沿用宿主负数表）

红线

交付自检（缺一不可）

交付物

后续迭代

• 绑定码清理定时任务（BindCodeRepository.expireOutdated）。
• 应用级权限范围（scope）与授权码模式（OAuth2 授权码 + PKCE）。
• 应用回调 webhook（callback_url 当前仅存储，未投递）。
• 与 fastapi-auth-module-skill 保持 API 字段一致，便于前后端跨语言复用。

【考拉搞AI】，带你全面进入 VibeCoding 的世界~