Metadata-Version: 2.4
Name: uc-integration
Version: 0.1.5
Summary: GSS 用户中心 SSO / 主数据同步 Fred 模块（子系统可 pip 安装）
Author: GSS
License: Proprietary
Project-URL: Homepage, https://github.com/renzhong/gss
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: flask>=2.0
Requires-Dist: flask-smorest>=0.40
Requires-Dist: flask-jwt-extended>=4.0
Requires-Dist: flask-babelplus>=2.0
Requires-Dist: marshmallow>=3.0
Requires-Dist: sqlalchemy>=1.4
Requires-Dist: pip==26.1.2
Provides-Extra: fred
Requires-Dist: fred-admin; extra == "fred"
Dynamic: requires-python

# 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 → **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` | 同步健康检查 |

本地 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**。后续门店列表应走服务端按部门现查。

## 安装

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

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

Fred 只从项目 `modules/` 扫描蓝图，安装后必须链接：

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

等价手动操作：

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

## 宿主配置

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

```python
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.0`，以 ai_check（UC 原样透传）+ todo（门店 scope / 动态前缀）合并为基准。
