Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P10-NS4-02.md

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 数组：

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} 列表，供前端门店选择器使用。