Skip to main content

GSS UC Integration — 用户中心 SSO / 主数据同步(Fred 子系统共享包)

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

能力

接口 说明
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 主数据推送(仅本机)
GET /{subsystem}/uc_integration/internal/uc-sync 接收端存活探测(不查本地表)

服务层(无子系统 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。后续门店列表应走服务端按部门现查。

安装

# 开发:可编辑安装
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,新项目不要跑。

宿主配置

common/config/Config.py(或等价配置):

EXTERNAL_MODULES = ["uc_integration"]   # 必填;不要把 uc_integration 放进 LOAD_CUSTOM_MODULES / modules/

SSO_LOGIN_MODE = 'uc'                    # 或 'local'
UC_SUBSYSTEM_CODE = 'ai_check'           # 路由前缀:/{code}/uc_integration;内部请求头 X-UC-Subsystem-Code
USER_CENTER_BASE_URL = 'http://127.0.0.1:5001'
USER_CENTER_INTERNAL_SECRET = '...'      # 与 UC OPEN_API_INTERNAL_SECRET 一致

# 可选
UC_INCLUDE_STORE_SCOPE = True            # 解析/返回门店 scope + 当前 store_id;不写全量 store_ids 进 JWT(默认 True)
UC_STORE_FALLBACK_FIRST = True           # 无匹配门店时回退第一个(默认 True;仅关闭 scope 时的选店回退)

必填(UC 主数据只读 HTTP)

配置 用途
USER_CENTER_BASE_URL UC Open API 基址
USER_CENTER_INTERNAL_SECRET 请求头 X-UC-Internal-Secret(与 UC OPEN_API_INTERNAL_SECRET 一致)
UC_SUBSYSTEM_CODE 请求头 X-UC-Subsystem-Code;UC 侧若带此头则校验子系统已登记且 status=1

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

本地库仅用于:

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

GET .../internal/uc-sync 为接收端存活探测(status=ok, mode=receiver),不 COUNT 本地表。

宿主前置条件

  • 配置 USER_CENTER_BASE_URL、USER_CENTER_INTERNAL_SECRET、UC_SUBSYSTEM_CODE
  • 本地 uc_* 镜像表仅服务 push 接收;只读查询与 SSO 换票不依赖它们
  • 依赖:fred_admin、Flask、SQLAlchemy(由子系统环境提供;SQLAlchemy 仅 push 写入需要)

目录结构(Fred 兼容)

uc_integration/
  __init__.py              # 导出蓝图
  backend/
    __init__.py            # Blueprint + url_prefix
    deps.py                # 惰性解析 model.model
    controller/
    service/
    schema/

从旧模块迁移

  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.29:UcPermissionService.permissions_for_user / has_permission 支持可选 subsystem_code;按 (user_id, subsystem) 短缓存。用于门户等场景只认 UC 角色∪用户功能权限。

Metadata

Release files for uc-integration 0.1.29

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.29
File Size Uploaded Provenance Actions
uc_integration-0.1.29.tar.gz 44.4 kB Without provenance Details for uc_integration-0.1.29.tar.gz

Built distribution (wheel)

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

Total release size: 98.6 kB

Release files / uc_integration-0.1.29.tar.gz

Download URL uc_integration-0.1.29.tar.gz
Size 44.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1702797fdaad51ad9e6d69495fa270eca5c2fe3f85857a3d1af90debbc19f4c9
BLAKE2b-256 checksum
How to use checksums
af258dde44320c20541c06c20259ab7a460e3d1fb3b0d72c9a053d0df23b3a90
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.1

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

Download URL uc_integration-0.1.29-py3-none-any.whl
Size 54.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5bbd11b80a5d6815d7a007565878e85b4b990fd0ebeb5fb61bf6cd0b599f6412
BLAKE2b-256 checksum
How to use checksums
b4113207917e6158dd880487866a94bfae226dc2e0049067feb3218105282ccf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.10.1

Security for uc-integration 0.1.29

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.29 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