Skip to main content

GSS UC Integration — 用户中心 SSO / 在线主数据查询(Fred 子系统共享包)

将各子系统里同构的 modules/uc_integration 抽成可安装包,避免复制粘贴分叉。

能力

接口 说明
GET /{mount}/sso/callback 内置 SSO 落地页(HTML+JS 换票写 localStorage;见下文)
GET /{subsystem}/uc_integration/auth/sso/config 登录模式
POST /{subsystem}/uc_integration/auth/sso/exchange UC 一次性 code → 本地 JWT(不接受 accessToken)
POST /{subsystem}/uc_integration/auth/sso/refresh UC refreshToken 续期
POST /{subsystem}/uc_integration/auth/sso/admin/exchange 管理端:code → 按 username 同步本地 admin → JWT
POST /{subsystem}/uc_integration/auth/sso/admin/refresh 管理端续期
POST /{subsystem}/uc_integration/internal/uc-sync UC 主数据推送(仅本机)(已停用):UC 不再推送,端点仍挂载但不会被调用,子系统无需实现/验证
GET /{subsystem}/uc_integration/internal/uc-sync 接收端存活探测(不查本地表)(已停用):UC 不再调用,子系统无需联调

服务层(无子系统 HTTP):按用户 id 查组织 + 门店

只读走 UC Open API /open_api/internal/*,依赖 USER_CENTER_BASE_URL / USER_CENTER_INTERNAL_SECRET。

from uc_integration.service.UcStoreScopeService import (
    UcStoreScopeService,
    UcScopeQueryError,
)

try:
    scope = UcStoreScopeService().get_org_and_stores_by_user_id(user_id)
except UcScopeQueryError as e:
    # UC HTTP 失败 / 内部密钥未配置(含明确中文说明)
    ...
# 用户不存在 → None
# scope['departments']  — 所属组织
# scope['stores'] / scope['store_ids']  — 可访问门店
from uc_integration.service.UcUserQueryService import UcUserQueryService
from uc_integration.service.UcDeptQueryService import UcDeptQueryService
from uc_integration.service.UcStoreQueryService import UcStoreQueryService
from uc_integration.service.UcDeptUserQueryService import UcDeptUserQueryService
from uc_integration.service.UcBusinessRoleService import UcBusinessRoleService
from uc_integration.service.UcPermissionService import UcPermissionService
from uc_integration.service.UcStorePickerService import UcStorePickerService
from uc_integration.service.UserCenterClient import UserCenterClient
from uc_integration.service.OmniChatService import OmniChatService

user = UcUserQueryService().get_user_by_id(user_id)          # 无则 None
depts = UcDeptQueryService().list_departments(dept_type=1)   # 门店型部门
tree = UcDeptQueryService().build_dept_tree()                # parent_id = 远程 dept_id
store = UcStoreQueryService().get_store_by_id(store_id)
dept_ids = UcDeptUserQueryService().list_dept_ids_by_user_id(user_id)
roles = UcBusinessRoleService().list_roles_for_user(user_id) # HTTP 失败 → []
# 业务功能权限(角色功能权限 ∪ 用户额外功能权限);subsystem 省略则用 UC_SUBSYSTEM_CODE
perms = UcPermissionService().permissions_for_user(user_id)              # 本子系统
portal_perms = UcPermissionService().permissions_for_user(user_id, 'portal')
ok = UcPermissionService().has_permission(user_id, 'todo.task.assign')
catalog = UcStorePickerService().list_catalog(user_id)       # 选店列表 + 按门店裁剪的品牌/区域/省市
# catalog['stores'] / catalog['filters']
# 不要用 list_brand_departments / list_region_departments 做选店筛选(全量部门,仅管理端)

cfg = UserCenterClient().get_sys_config('OMNI_CHAT_URL')     # {name,value,desc} 或 None
vals = UserCenterClient().get_sys_configs(['OMNI_CHAT_URL', 'OMNI_CHAT_TOKEN', 'OMNI_CHAT_MODEL'])
text = OmniChatService().complete([{'role': 'user', 'content': 'hi'}])  # 凭证取自 UC sys_config

# 其它子系统 HTTP origin(= UC「子系统管理 → 访问地址」routePath;换域名只改 UC 登记)
finance_origin = UserCenterClient().get_subsystem_base_url('finance')  # 或 get_subsystem_catalog('finance')
# 禁止写死 http://127.0.0.1:5007

# AI 预览 / 加入模块:幂等登记为「开发中」(服务端 → UC internal,无 CORS)
draft = UserCenterClient().ensure_subsystem_draft(
    'my-mod', name='我的模块', route_path='https://host/my-mod/',
)

User / Dept / Store / DeptUser / Scope 只读调 UC,返回 dict(不返回 ORM)。空 IN → [] / {},不发 HTTP。

本地 JWT 的 sub 含:

  • 本地身份:id / username / name / store_id(当前选中,可空)/ role
  • uc 精简:code / name / store / is_store_manager,以及 departments / roles / roleCodes(payload 有则带)
  • 不含全量 store_ids / stores(避免 Authorization 过大 → 431)

换票响应 body 可另含 storeIds(当次组织现查结果,供前端首屏),不进 JWT。后续门店列表应走服务端按部门现查。

权限目录(UC 点「同步」时拉取)

GET /{subsystem}/uc_integration/internal/permissions/catalog(内部密钥鉴权)。目录由两部分合成:

  1. yaml 钉子:common/permissions.yaml(或 UC_PERMISSIONS_FILE)里登记的权限码原样输出,永不被自动覆盖;yaml 里登记过的接口(含 permission: null、common.public / login_only)不会再出自动码。
  2. 自动派生:代码里有、yaml 没登记的路由,按确定性规则(codeRule: "v1")自动出码,条目带 auto: true。没有 yaml 的子系统整份目录都是自动生成,不再 404。

码规则:<UC子系统码>.<路径段>.<method小写>,动态段(<int:x> 等)写成 id,如 GET /reports → finance.reports.get,POST /subtasks/<int:subtask_id>/submit → todo.subtasks.id.submit.post。码只由 (METHOD, 路径形状) 决定,与路由注册顺序、重启、PYTHONHASHSEED 无关,所以重复同步只会「新增」,不会改动已有授权。

  • UC_PERMISSION_API_PREFIX(Config 或环境变量,可选):无 yaml 时业务路由前缀,缺省 /{mount};须以 / 开头且不以 / 结尾。
  • 显式设置了 UC_PERMISSIONS_FILE 但文件不存在 → 404(配置错误,不静默降级);合成后目录为空 → 422,不会清空 UC 授权。
  • 路径重构会让自动码变化:旧码进入 UC 的「待禁用」确认;要保住授权,在 yaml 里把旧码钉到新路径上。
  • 「不需要鉴权」的接口不出码:登录、退出、SSO、公开页、健康检查、验证码、埋点、当前用户画像等,按路径约定排除(/auth/**、/sso/**、/public/**、/**/login|logout|dev-login、/**/health|healthz|ping、/**/captcha|img_captcha、/page-track、顶层 /profile、/me;按路径段整段匹配、大小写不敏感、与 HTTP 方法无关,所以 /health_score/...、/users/me 不会被误伤)。命中的接口不进 permissions / apis,只列在响应的 audit.excluded(无 yaml 也列出,便于确认有没有误伤);排除不改变其它接口的码。
  • UC_PERMISSION_EXCLUDE(Config 或环境变量,Config 优先;列表,或逗号 / 换行分隔字符串):追加排除规则,与默认取并集。语法:* 段内通配、** 独占一整段并匹配零个或多个段、可带大写 METHOD 前缀只排除该方法(如 POST /uploads/callback)。没命中约定的免鉴权接口(如公开的 /display_config)在这里追加即可。
  • 默认规则误伤了业务接口:在 yaml 里登记它(并给权限码)即可,yaml 已登记的接口永远按 yaml 输出,不受排除规则影响。
  • 自动码只供 UC 授权展示,不是鉴权守卫;排除表只是路径约定,将来做守卫须按 yaml 的 public / login_only 豁免。
  • permission_scaffold 派生的是语义码(如 todo.history_report.view),与自动码是两套体系:对已自动出现在 UC 的接口,钉 yaml 时 permission 必须填自动码,否则会出现新旧两个码、授权对不上。

安装

# 开发:可编辑安装
pip install -e /path/to/uc-integration

# 或从 git
pip install "gss-uc-integration @ git+ssh://git@github.com/org/uc-integration.git"

Fred >=1.0.17 用 EXTERNAL_MODULES 从 site-packages 加载蓝图,不要再软链进 modules/:

EXTERNAL_MODULES = ["uc_integration"]

旧脚本 scripts/link_to_project.py 仅兼容更早的 Fred,新项目不要跑。

宿主配置

最小部署 Config

多数子系统只需下面几项(其余有包内默认):

EXTERNAL_MODULES = ['uc_integration']
DEFAULT_MODULE = 'todo'          # 或与 UC 码相同的下划线段
SSO_LOGIN_MODE = 'uc'
USER_CENTER_BASE_URL = 'https://...'
USER_CENTER_INTERNAL_SECRET = '...'
# 可选:USER_CENTER_SSL_VERIFY / PORTAL_CORS_*
# 通常不必:UC_SUBSYSTEM_CODE(=DEFAULT_MODULE)、UC_INTEGRATION_MOUNT、SSO_CALLBACK_*、SSO_LOCAL_TOKEN_KEY、SSO_PINIA_*
# 例外:UC 码带连字符、或多模块 Pinia 命名非 {mod}-user 时再显式覆盖

说明:

  • 挂载段:UC_INTEGRATION_MOUNT → DEFAULT_MODULE → UC_SUBSYSTEM_CODE
  • 内置回调:SSO_CALLBACK_ENABLED 缺省 True;SSO_LOCAL_TOKEN_KEY 缺省 token;SSO_CALLBACK_DEFAULT_REDIRECT 缺省 /{prefix}/
  • Pinia:未配 SSO_PINIA_PERSIST_KEY 时,由 LOAD_CUSTOM_MODULES 各段生成 {mod}-user(去重)并确保含 {mount}-user;无 LOAD_CUSTOM_MODULES 则仅 {mount}-user(ai-dev 双模块可不配)
# 可选进阶
UC_INCLUDE_STORE_SCOPE = True            # 解析/返回门店 scope + 当前 store_id;不写全量 store_ids 进 JWT(默认 True)
UC_STORE_FALLBACK_FIRST = True           # 无匹配门店时回退第一个(默认 True;仅关闭 scope 时的选店回退)
UC_SUBSYSTEM_CODE = 'ai-dev'             # 仅当 UC 注册码带连字符、与 DEFAULT_MODULE 不一致时需要

必填(UC 主数据只读 HTTP)

配置 用途
USER_CENTER_BASE_URL UC Open API 基址
USER_CENTER_SSL_VERIFY 默认 True;本地 mkcert/自签可设 False 跳过 HTTPS 证书校验
USER_CENTER_INTERNAL_SECRET 请求头 X-UC-Internal-Secret(与 UC OPEN_API_INTERNAL_SECRET 一致)
DEFAULT_MODULE(或显式 UC_SUBSYSTEM_CODE) 挂载 / 子系统码;请求头 X-UC-Subsystem-Code:preview → 显式 UC_SUBSYSTEM_CODE → DEFAULT_MODULE(空或 app 不带头)

UC 主数据 reads 只走 HTTP(/open_api/internal/*),不对本地 uc_* 做 SELECT。

说明:UC 已停用「数据同步」——UC 不再向子系统主动推送用户/组织/门店主数据。internal/uc-sync 端点与 UcDataSyncService 仍随包挂载(代码保留),但 UC 不会调用它们,子系统无需实现、验证或联调;用户/门店/组织一律走 UcUserQueryService / UcStoreQueryService / UcStoreScopeService / UcStorePickerService 在线 HTTP 查询。本地 uc_* 镜像表不再由 UC 更新,请勿依赖其新鲜度。

本地库仅用于:

  1. 接收 UC push upsert(UcDataSyncService POST 写本地 uc_*) (已停用:UC 不再推送)
  2. 其它业务表(与 UC 实体无关);SSO / 组织 / 门店 / 角色 / scope 不再读本地 UC 镜像

GET .../internal/uc-sync 为接收端存活探测(status=ok, mode=receiver),不 COUNT 本地表(已停用:UC 不再调用,子系统无需验证)。

宿主前置条件

  • 配置 USER_CENTER_BASE_URL、USER_CENTER_INTERNAL_SECRET、DEFAULT_MODULE(UC 码与挂载段不一致时再配 UC_SUBSYSTEM_CODE / UC_INTEGRATION_MOUNT)
  • 本地 uc_* 镜像表原仅服务 push 接收(已停用:UC 不再推送,镜像表不再由 UC 更新,勿依赖其新鲜度);只读查询与 SSO 换票不依赖它们
  • 依赖:fred_admin、Flask、SQLAlchemy(由子系统环境提供;SQLAlchemy 仅 push 写入需要,该路径已停用)

目录结构(Fred 兼容)

uc_integration/
  __init__.py              # 导出蓝图
  static/
    sso_callback.html      # 内置 SSO 落地页模板
  backend/
    __init__.py            # Blueprint + url_prefix
    deps.py                # 惰性解析 model.model
    controller/
    service/
    schema/

内置 SSO 回调:只装包 + 配置

新子系统不必再写 Vue SsoCallback:装好本包并配置后,浏览器打开:

GET /{prefix}/sso/callback?code=...&redirect=/{prefix}/

其中 prefix 为任意单段合法前缀([A-Za-z0-9_-]+),不必等于本进程的 Blueprint mount。同进程多模块(如 ai_dev + pc_ai_dev)时,各子系统可用各自 /{code}/sso/callback,无需再改库里的 sso_callback_path。

页面会同域 POST /{mount}/uc_integration/auth/sso/exchange(mount = UC_INTEGRATION_MOUNT / DEFAULT_MODULE,与 URL 前缀无关),解 Fred 信封,写入 localStorage,再 location.replace 安全跳转。

UC 子系统的 sso_callback_path 可留空:UC 默认即为 /{subsystem_code}/sso/callback,本包通配路由可直接命中。若显式配置,也请用 /{code}/sso/callback。既有子系统的 Vue 回调可继续保留;本包注册 Flask 路由后同路径以服务端为准。

Config.py 覆盖示例(均可选,默认已可用;见上文「最小部署 Config」):

SSO_CALLBACK_ENABLED = True                 # False 则不注册路由;缺省 True
SSO_LOCAL_TOKEN_KEY = 'token'               # 缺省 token;同进程多模块共用,不按前缀区分
SSO_UC_ACCESS_TOKEN_KEY = 'gss_uc_access_token'
SSO_UC_REFRESH_TOKEN_KEY = 'gss_uc_refresh_token'
SSO_PINIA_PERSIST_KEY = ''                  # 空则从 LOAD_CUSTOM_MODULES/{mount} 推导 {mod}-user;显式可逗号/分号多 key
SSO_CALLBACK_DEFAULT_REDIRECT = '/finance/' # 缺省 /{prefix}/(请求前缀)

Query 可覆盖:pinia_key / token_key(单值,写入该 Pinia persist key)。

Redirect 仅允许相对路径 /...(非 //)或同 origin 绝对 URL;javascript: 等一律回退默认路径。

从旧模块迁移

  1. pip install "uc-integration>=0.1.13"(或 -e /path/to/uc-integration)
  2. 删除子系统里的 modules/uc_integration(拷贝或软链都删)
  3. Config.py 设 EXTERNAL_MODULES = ["uc_integration"],不要把它写进 LOAD_CUSTOM_MODULES
  4. 确认 UC_SUBSYSTEM_CODE 与门户子系统编码一致
  5. 重启进程,验证 GET /{code}/uc_integration/auth/sso/config

版本

当前 0.1.50:live-preview 下 SSO redirect 强制留在 /live-preview/{code}/;并保留 0.1.49 的 exchange 路径前缀修复。

0.1.49:live-preview 同源预览下,SSO callback 按 pathname 走 /live-preview/{code}/uc_integration/auth/sso/exchange(避免打到主网关 404)。

0.1.48:内置 SSO 落盘键统一为 token(SSO_LOCAL_TOKEN_KEY 可覆盖);同进程多前缀回调共用一把业务 token,不再写 {mount}_token / {prefix}_token。

0.1.47:曾按请求 prefix 写 {prefix}_token;已被 0.1.48 的统一 token 取代。

0.1.43:X-UC-Subsystem-Code 解析改为 preview → 显式 UC_SUBSYSTEM_CODE → get_subsystem_code()/DEFAULT_MODULE;空或字面量 app 不带头(避免 UC 403)。仅配 DEFAULT_MODULE 的宿主(如 ai-dev)也会正确带头。

0.1.42:未配 SSO_PINIA_PERSIST_KEY 时,由 LOAD_CUSTOM_MODULES 各段推导 {mod}-user(去重)并确保含 {mount}-user;无模块列表则仅 {mount}-user。最小部署 Config 通常不必再写回调/Pinia/挂载覆盖项。

0.1.41:为已知前缀额外注册静态 /{prefix}/sso/callback(赢过 SPA <path:> catch-all);前缀来自 mount / Config / LOAD_CUSTOM_MODULES / SSO_CALLBACK_PREFIXES / PORTAL_CORS_PATH_PREFIXES / Blueprint url_prefix;通配仍保留。

0.1.40:内置 SSO 回调改为 GET /<prefix>/sso/callback 通配单段前缀;UC sso_callback_path 可留空用默认 /{code}/sso/callback;换票仍走 /{mount}/uc_integration/auth/sso/exchange;未配 SSO_CALLBACK_DEFAULT_REDIRECT 时回跳 /{prefix}/。

0.1.39:SSO_PINIA_PERSIST_KEY 支持逗号/分号多 key;query pinia_key/token_key 可单值覆盖。

0.1.38:内置 GET /{mount}/sso/callback 配置化 HTML 落地页(只装包 + Config,无需每模块 Vue SsoCallback)。

0.1.37:挂载段优先 UC_INTEGRATION_MOUNT → DEFAULT_MODULE(再才 UC_SUBSYSTEM_CODE),并在 Blueprint register 时刷新 url_prefix,避免 import 时冻死 /ai-dev/ 等连字符前缀。

0.1.36:ensure_subsystem_draft 对齐 UC——非保护码一律开发中,并声明 status=2;UC 侧会停止运行中部署(呈「未部署」)。

0.1.35:共享预览支持按请求路径覆盖 subsystem code(唯一 uc_integration 挂载服务多模块换票)。

0.1.34:新增 UcHttpTransport;UserCenterClient 走可配置 HTTPS 证书校验(USER_CENTER_SSL_VERIFY,本地 mkcert/自签可关)。

0.1.33:UserCenterClient.ensure_subsystem_draft 参数为 draft_owner_uc_user_id(对应 UC ensure-draft 的 draftOwnerUcUserId;0.1.32 曾为 draft_owner_admin_id,与 ai-dev 不兼容,请升级)。

0.1.32:权限与其它能力见下文历史说明。

0.1.31:权限目录支持自动派生(见上文「权限目录」);catalog v2 增加接口映射 / 运行时对账 / 空目录保护,新增 permission_scaffold 只读骨架工具。

0.1.30:UcPermissionService.permissions_for_user / has_permission 支持可选 subsystem_code;权限码走 Redis 共享缓存(uc:perm:v1:{user_id}:{subsystem},TTL 3600s,与 UC 同契约;Redis 异常降级 OpenAPI)。用于门户等场景只认 UC 角色∪用户功能权限。

Metadata

Release files for uc-integration 0.1.50

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uc-integration 0.1.50
File Size Uploaded Provenance Actions
uc_integration-0.1.50.tar.gz 84.4 kB Without provenance Details for uc_integration-0.1.50.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uc-integration 0.1.50
File Interpreter ABI Platform Actions
uc_integration-0.1.50-py3-none-any.whl Python 3 none any Details for uc_integration-0.1.50-py3-none-any.whl

Total release size: 178.9 kB

Release files / uc_integration-0.1.50.tar.gz

Download URL uc_integration-0.1.50.tar.gz
Size 84.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a9e29f3350e82ae7878c4f1c07620444181721c3bd3fb3e31142b730bc7ba2cb
BLAKE2b-256 checksum
How to use checksums
5ff5f46f98ed0d13f2b59ed6e02fc11acf8e55f3e77802dba39c1462e9535387
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Release files / uc_integration-0.1.50-py3-none-any.whl

Download URL uc_integration-0.1.50-py3-none-any.whl
Size 94.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e6ea368e25c71febde52b69adf15076433e50b5ad19fdce2ac64478a749d560
BLAKE2b-256 checksum
How to use checksums
f3fc8c34571ac95ed319da74416abc28d7a7cd2a88a4d3f07dd061891696c6ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Security for uc-integration 0.1.50

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.50 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page