# P10-NS4-02：门店切换功能的交互规范

## 简要结论
- 状态：⚠️ 部分解决
- 后端数据隔离和 JWT 门店权限体系完整；前端 SiteSelector 组件已实现但仅在维客线索页集成，全局布局未放置门店选择器，用户审核和 Excel 上传页面缺少门店筛选，门店名称显示为 ID 而非中文名。

## 详细审查

### 数据库端

**auth.tenant_admins 表**（DDL: `db/zqyy_app/migrations/2026-03-20__ns4_tenant_admin_tables.sql`）

| 字段 | 类型 | 说明 |
|------|------|------|
| managed_site_ids | BIGINT[] | 管辖门店 ID 数组，用于数据隔离 |
| tenant_id | BIGINT | 所属租户 |
| is_active | BOOLEAN | 账号状态 |

✅ `managed_site_ids` 为 PostgreSQL 数组类型，支持多门店管辖场景。

**public.site_code_mapping 表**（被后端多处引用）

| 用途 | 说明 |
|------|------|
| site_code → site_id 映射 | 用户申请时通过球房编号关联门店 |
| site_id → site_name 映射 | 用户列表、线索搜索时补充门店名称 |

✅ 门店名称映射表存在，后端已在 `tenant_users.py` 和 `tenant_clues.py` 中使用。

**结论**：数据库层面完整支持多门店管辖和门店名称映射。

### 后端代码

#### 1. 登录与 JWT（`tenant_auth.py`）
✅ 登录成功后返回的 JWT payload 包含 `managed_site_ids` 数组：
```python
payload = {
    "sub": str(admin_id),
    "tenant_id": tenant_id,
    "managed_site_ids": managed_site_ids,  # ← 门店列表
    "aud": "tenant-admin",
}
```
✅ refresh_token 也携带 `managed_site_ids`，刷新后不丢失。

#### 2. 认证中间件（`auth/tenant_admins.py`）
✅ `CurrentTenantAdmin` dataclass 包含 `managed_site_ids: list[int]`。
✅ `site_filter_clause()` 工具函数生成 `site_id IN (...)` SQL 片段，用于数据隔离。
✅ `verify_site_access()` 校验单个 site_id 是否在管辖范围内，越权返回 403。
✅ 空 managed_site_ids 时生成 `1 = 0` 条件，不匹配任何行（安全兜底）。

#### 3. 查询接口（`tenant_users.py`）
✅ `list_applications` — 通过 `site_filter_clause` 附加 `site_id IN (管辖列表)` 条件。
✅ `list_users` — 同上，JOIN `user_site_roles` 表做门店隔离。
✅ `approve_application` / `reject_application` — 调用 `verify_site_access` 校验单门店权限。
✅ `edit_user` — 新 site_id 必须在管辖范围内。

#### 4. 维客线索（`tenant_clues.py`，grep 结果确认）
✅ 搜索接口支持 `site_id` 参数筛选。
✅ 返回结果补充 `site_name`（通过 `site_code_mapping` 查询）。

**后端结论**：数据隔离体系完整，所有查询均附加 `site_id IN (管辖列表)` 条件，符合 P10 spec 要求。

### 前端代码

#### 1. SiteSelector 组件（`components/SiteSelector/index.tsx`）
✅ 组件已实现，基于 Ant Design Select，支持多选/全选。
✅ 配套 `useSiteFilter` hook，管理选中状态，提供 `effectiveSiteIds`（空选时返回全部）。
✅ 数据源来自 `useAuth().user.managedSiteIds`。

#### 2. useAuth hook（`hooks/useAuth.tsx`）
✅ 从 JWT payload 解析 `managedSiteIds` 数组。
✅ 登录后通过 `extractUserInfo` 提取并存入 React Context。
✅ 页面刷新时从 localStorage 恢复。

#### 3. API 服务（`services/api.ts`）
✅ JWT 自动附加到请求头。
✅ 401 时自动刷新 token（含并发保护）。
⚠️ 无全局 site_id 拦截器——各页面需自行传递 site_id 参数。

#### 4. App.tsx 全局布局
❌ **全局布局未集成 SiteSelector**。侧边栏仅包含导航菜单和退出按钮，无门店选择器。
❌ 无全局 "当前选中门店" 状态管理（无 SiteContext/SiteProvider）。

#### 5. 各页面集成情况

| 页面 | SiteSelector 集成 | site_id 传递 | 门店名称显示 |
|------|-------------------|-------------|-------------|
| 维客线索 (RetentionClues) | ✅ 已集成 | ✅ 单门店时传 site_id | ⚠️ 显示 `门店 {id}` |
| 用户管理 (UserManagement) | ❌ 未集成 | ❌ 依赖后端 JWT 隔离 | ⚠️ 显示 `门店 {id}` |
| 用户审核 (UserApproval) | ❌ 未集成 | ❌ 依赖后端 JWT 隔离 | ❌ 仅显示球房编号 |
| Excel 上传 (ExcelUpload) | ❌ 未集成 | ❌ 无门店筛选 | ❌ 无门店信息 |

#### 6. 门店名称问题
⚠️ SiteSelector 选项显示为 `门店 {id}`（硬编码数字），未查询 `site_code_mapping` 获取真实门店名称。用户无法通过名称识别门店。

### 差距分析

| P10 要求 | 当前状态 | 差距 |
|----------|---------|------|
| 租户级管理员管辖所有店铺 | ✅ managed_site_ids 支持 | 无 |
| 店铺级管理员只管指定 site_id | ✅ JWT + site_filter_clause | 无 |
| 所有查询附加 site_id IN 条件 | ✅ 后端全部实现 | 无 |
| 门店选择器 UI | ⚠️ 组件存在但未全局集成 | 仅维客线索页使用 |
| 切换门店后数据自动刷新 | ⚠️ 维客线索页有效 | 其他页面无此机制 |
| 门店选择器位置 | ❌ 未定义全局位置 | App.tsx 布局无选择器 |
| 门店名称可读性 | ❌ 显示 ID 而非名称 | 需查询 site_name |

### 建议

1. **全局门店选择器**：在 `App.tsx` 的 `Content` 区域顶部（或 Header）放置 SiteSelector，创建 `SiteContext` 全局管理当前选中门店，各页面通过 Context 消费。

2. **门店名称映射**：登录后或首次加载时调用后端接口获取 `managed_site_ids → site_name` 映射，SiteSelector 选项显示真实门店名称（如"朗朗桌球·XX店"）。

3. **页面集成**：UserApproval、UserManagement、ExcelUpload 页面接入全局门店筛选，API 请求携带 `site_ids` 参数。

4. **切换刷新机制**：门店切换时触发数据重新加载（可通过 `useEffect` 监听 `selectedSiteIds` 变化，或使用 React Query 的 `queryKey` 包含 site_ids 实现自动 refetch）。

5. **后端补充**：新增 `GET /api/tenant/sites` 接口，返回当前管理员管辖门店的 `{site_id, site_name}` 列表，供前端门店选择器使用。