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

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

能力

服务层（无 HTTP）：按用户 id 查组织 + 门店

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

try:
    scope = UcStoreScopeService().get_org_and_stores_by_user_id(user_id)
except UcScopeQueryError as e:
    # 镜像表缺失 / DB 会话不可用 / SQL 失败（含明确中文说明）
    ...
# 用户不存在（uc_user 无有效行）→ None
# scope['departments']  — 所属组织
# scope['stores'] / scope['store_ids']  — 可访问门店

纯原生 SQL 查询 uc_user / uc_dept / uc_dept_user_relation / uc_store，不依赖 ORM 模型类。先校验用户存在，再查组织/门店。

本地 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 只从项目 modules/ 扫描蓝图，安装后必须链接：

# 在子系统根目录（含 modules/）
python /path/to/uc-integration/scripts/link_to_project.py .
# 或覆盖已有 symlink
python /path/to/uc-integration/scripts/link_to_project.py . --force

等价手动操作：

ln -sfn "$(python -c 'import uc_integration,pathlib; print(pathlib.Path(uc_integration.__file__).parent)')" \
  modules/uc_integration

宿主配置

common/config/Config.py（或等价配置）：

LOAD_CUSTOM_MODULES = [..., "uc_integration"]

SSO_LOGIN_MODE = 'uc'                    # 或 'local'
UC_SUBSYSTEM_CODE = 'ai_check'           # 路由前缀：/{code}/uc_integration
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_user / uc_store 等镜像表（可由 sync DDL 自动建）
• ORM：model.model 中存在 UcUser（以及门店 scope 需要的 UcDept 等）
• 依赖：fred_admin、Flask、SQLAlchemy（由子系统环境提供）

目录结构（Fred 兼容）

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

从旧模块迁移

1. pip install -e ../uc-integration
2. 备份并删除子系统 modules/uc_integration
3. python ../uc-integration/scripts/link_to_project.py .
4. 确认 UC_SUBSYSTEM_CODE 与门户子系统编码一致
5. 验证 GET /{code}/uc_integration/auth/sso/config

版本

当前 0.1.10。SSO 换票下发 uc_role（roles / roleCodes / role_name）；换票时可用 UC 画像补齐本地部门/门店镜像（无全量 sync 也可鉴权门店）。业务角色查询见 UcBusinessRoleService。无业务角色时 role_name 为空。