feat: chat integration, tenant admin spec, backend chat service, miniprogram updates, DEMO moved to tmp, XCX-TEST removed, migrations & docs

2026-03-20 09:02:10 +08:00
parent 3d2e5f8165
commit beb88d5bea
388 changed files with 6436 additions and 25458 deletions
--- a/.kiro/specs/tenant-admin-web/design.md
+++ b/.kiro/specs/tenant-admin-web/design.md
@@ -0,0 +1,623 @@
+# 技术设计文档：租户管理后台（tenant-admin-web）
+
+## 概述
+
+本设计为 NS4 租户管理后台提供完整的技术方案。系统面向租户管理员（Tenant_Admin），提供用户审核与管理、Excel 数据上传（4 种模板）、维客线索管理三大功能模块。
+
+前端为独立 React 应用（`apps/tenant-admin/`），后端复用现有 FastAPI 服务（`apps/backend/`）新增 4 个路由模块，所有端点注册在 `/api/tenant/` 前缀下。认证体系与小程序完全隔离，使用独立的 `auth.tenant_admins` 表、用户名+密码登录、JWT `aud=tenant-admin`。
+
+### 关键设计决策
+
+| 决策 | 选择 | 理由 |
+|------|------|------|
+| 认证表 | 独立 `auth.tenant_admins` | 与小程序 `auth.users`（微信登录）完全隔离，避免 user_type 判断复杂度 |
+| JWT 隔离 | `aud` 字段区分 | 复用现有 `jose` + `bcrypt` 基础设施，仅扩展 payload |
+| Excel 写入策略 | staging 表 + ETL 同步（方案 B） | 数据经 ETL 标准流程，一致性有保障；助教奖罚直接写 biz |
+| FDW 多店铺查询 | 逐 site_id 查询合并 | RLS 视图要求 `SET LOCAL app.current_site_id`，单次只能设一个 |
+| 前端技术栈 | React + Vite + Ant Design | 与 `apps/admin-web/` 一致，降低维护成本 |
+| 响应格式 | `{ code: 0, data }` | 复用现有 `ResponseWrapperMiddleware`，前端统一解包 |
+
+---
+
+## 架构
+
+### 高层架构图
+
+```mermaid
+graph TB
+    subgraph "前端 apps/tenant-admin/"
+        FE[React + Vite + Ant Design]
+        API_LAYER[services/api.ts<br/>JWT 自动附加/刷新]
+    end
+
+    subgraph "后端 apps/backend/"
+        subgraph "路由层 /api/tenant/*"
+            R_AUTH[tenant_auth.py<br/>登录/刷新]
+            R_USERS[tenant_users.py<br/>审核+管理]
+            R_EXCEL[tenant_excel.py<br/>上传/校验/冲突]
+            R_CLUES[tenant_clues.py<br/>线索管理]
+        end
+
+        AUTH_DEP[require_tenant_admin<br/>认证依赖注入]
+        MIDDLEWARE[ResponseWrapperMiddleware<br/>全局响应包装]
+    end
+
+    subgraph "数据层"
+        APP_DB[(zqyy_app<br/>auth + biz + public)]
+        ETL_DB[(etl_feiqiu<br/>fdw_etl 视图)]
+    end
+
+    FE --> API_LAYER
+    API_LAYER -->|HTTP| MIDDLEWARE
+    MIDDLEWARE --> R_AUTH
+    MIDDLEWARE --> R_USERS
+    MIDDLEWARE --> R_EXCEL
+    MIDDLEWARE --> R_CLUES
+    R_USERS --> AUTH_DEP
+    R_EXCEL --> AUTH_DEP
+    R_CLUES --> AUTH_DEP
+    R_AUTH -->|登录无需认证| APP_DB
+    AUTH_DEP --> APP_DB
+    R_USERS -->|FDW 人员匹配| ETL_DB
+    R_EXCEL -->|FDW 助教匹配| ETL_DB
+    R_CLUES -->|FDW 客户搜索| ETL_DB
+```
+
+### 认证流程
+
+```mermaid
+sequenceDiagram
+    participant FE as Tenant Admin Web
+    participant BE as Backend API
+    participant DB as auth.tenant_admins
+
+    FE->>BE: POST /api/tenant/auth/login {username, password}
+    BE->>DB: SELECT password_hash WHERE username=? AND is_active=true
+    alt 凭据有效
+        BE->>BE: bcrypt.checkpw() 验证
+        BE->>BE: 签发 JWT (aud=tenant-admin, sub=admin_id, managed_site_ids)
+        BE-->>FE: {access_token, refresh_token}
+    else 凭据无效
+        BE-->>FE: 401 用户名或密码错误
+    else 账号禁用
+        BE-->>FE: 403 账号已被禁用
+    end
+
+    Note over FE,BE: 后续请求
+    FE->>BE: GET /api/tenant/* (Authorization: Bearer <token>)
+    BE->>BE: require_tenant_admin() 验证 aud=tenant-admin
+    BE->>BE: 提取 managed_site_ids，附加数据隔离条件
+```
+
+### Excel 上传流程
+
+```mermaid
+flowchart TD
+    A[选择模板类型 + 上传 Excel] --> B[后端解析 + 格式校验]
+    B --> C{校验结果}
+    C -->|格式错误| D[返回错误行号/列名/描述<br/>前端标红展示]
+    D --> A
+    C -->|校验通过| E[人员匹配校验<br/>仅 salary_adj / recharge_commission]
+    E --> F[冲突检测<br/>按主键规则匹配]
+    F --> G{有冲突?}
+    G -->|是| H[返回 diff 数据<br/>前端展示 diff 表格]
+    H --> I[用户逐行选择<br/>替换/保留]
+    G -->|否| J[标记为待写入]
+    I --> K[确认写入]
+    J --> K
+    K --> L{写入目标}
+    L -->|助教奖罚| M[biz.salary_adjustments]
+    L -->|财务支出| N[biz.stg_finance_expense]
+    L -->|团购收入| O[biz.stg_platform_income]
+    L -->|充值归属| P[biz.stg_recharge_commission]
+    K --> Q[更新 excel_upload_log<br/>status=confirmed]
+```
+
+---
+
+## 组件与接口
+
+### 后端路由模块
+
+#### 1. `tenant_auth.py` — 认证路由
+
+| 端点 | 方法 | 路径 | 认证 | 说明 |
+|------|------|------|------|------|
+| 登录 | POST | `/api/tenant/auth/login` | 无 | 用户名+密码 → JWT 令牌对 |
+| 刷新 | POST | `/api/tenant/auth/refresh` | 无 | refresh_token → 新令牌对 |
+
+
+#### 2. `tenant_users.py` — 用户审核 + 管理路由
+
+| 端点 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 申请列表 | GET | `/api/tenant/applications` | status 筛选 + 分页 |
+| 关联建议 | GET | `/api/tenant/applications/{id}/match-suggestions` | FDW 助教/员工匹配 |
+| 审核通过 | POST | `/api/tenant/applications/{id}/approve` | 分配角色 + 绑定 |
+| 审核拒绝 | POST | `/api/tenant/applications/{id}/reject` | 填写拒绝原因 |
+| 用户列表 | GET | `/api/tenant/users` | 角色筛选 + 搜索 + 分页 |
+| 编辑用户 | PATCH | `/api/tenant/users/{id}` | 修改角色/门店/状态 |
+| 修改绑定 | PUT | `/api/tenant/users/{id}/binding` | 更新助教/员工绑定 |
+
+#### 3. `tenant_excel.py` — Excel 上传路由
+
+| 端点 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 上传解析 | POST | `/api/tenant/excel/upload` | multipart/form-data，校验+冲突检测 |
+| 确认写入 | POST | `/api/tenant/excel/confirm` | upload_id + resolutions[] |
+| 上传记录 | GET | `/api/tenant/excel/logs` | 历史记录列表 + 分页 |
+| 模板下载 | GET | `/api/tenant/excel/template/{type}` | 下载空白 Excel 模板 |
+
+#### 4. `tenant_clues.py` — 维客线索路由
+
+| 端点 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 客户搜索 | GET | `/api/tenant/customers/search` | keyword + site_id 筛选 |
+| 线索列表 | GET | `/api/tenant/customers/{member_id}/clues` | 该客户全部线索 |
+| 修改线索 | PATCH | `/api/tenant/clues/{id}` | category + summary + detail |
+| 删除线索 | DELETE | `/api/tenant/clues/{id}` | 物理删除 |
+| 隐藏/显示 | PATCH | `/api/tenant/clues/{id}/visibility` | is_hidden 切换 |
+
+### 认证依赖注入
+
+```python
+@dataclass(frozen=True)
+class CurrentTenantAdmin:
+    """从 JWT 解析出的租户管理员上下文。"""
+    admin_id: int
+    tenant_id: int
+    managed_site_ids: list[int]
+    display_name: str | None = None
+
+async def require_tenant_admin(
+    credentials: HTTPAuthorizationCredentials = Depends(_bearer_scheme),
+) -> CurrentTenantAdmin:
+    """
+    验证 JWT aud=tenant-admin，提取管理员信息。
+    拒绝小程序 JWT（aud 不匹配）。
+    """
+    payload = decode_access_token(token)  # 复用现有解码
+    if payload.get("aud") != "tenant-admin":
+        raise HTTPException(401, "令牌类型不匹配")
+    return CurrentTenantAdmin(
+        admin_id=int(payload["sub"]),
+        tenant_id=payload["tenant_id"],
+        managed_site_ids=payload["managed_site_ids"],
+    )
+```
+
+数据隔离通过 `managed_site_ids` 实现：
+
+```python
+def site_filter_clause(admin: CurrentTenantAdmin) -> tuple[str, tuple]:
+    """生成 site_id IN (...) SQL 片段。"""
+    placeholders = ",".join(["%s"] * len(admin.managed_site_ids))
+    return f"site_id IN ({placeholders})", tuple(admin.managed_site_ids)
+```
+
+### 前端组件结构
+
+```
+apps/tenant-admin/src/
+├── pages/
+│   ├── Login/              # 登录页
+│   ├── UserApproval/       # 用户审核（申请列表 + 关联建议 + 审核操作）
+│   ├── UserManagement/     # 用户管理（列表 + 编辑 + 绑定）
+│   ├── ExcelUpload/        # Excel 上传（模板选择 + 上传 + 校验 + diff + 确认）
+│   └── RetentionClues/     # 维客线索（客户搜索 + 线索列表 + 编辑/删除/隐藏）
+├── components/
+│   ├── SiteSelector/       # 门店筛选器（页面顶部）
+│   ├── DiffTable/          # 冲突 diff 交互表格
+│   └── ClueEditor/         # 线索编辑表单
+├── services/
+│   └── api.ts              # API 调用封装（JWT 自动附加/刷新）
+├── hooks/
+│   └── useAuth.ts          # 认证状态管理
+├── utils/
+│   └── format.ts           # 格式化工具（手机号脱敏等）
+└── App.tsx                 # 路由配置 + 侧边栏布局
+```
+
+### API 调用层设计
+
+复用 `apps/admin-web/src/api/client.ts` 的模式：
+- axios 实例，`baseURL: "/api/tenant"`
+- 请求拦截器：从 localStorage 读取 access_token 附加 Authorization header
+- 响应拦截器：401 时用 refresh_token 刷新，刷新失败重定向 `/login`
+- 并发刷新保护：多个 401 只触发一次 refresh，其余排队
+- 响应解包：`{ code: 0, data }` → 提取 `data`
+
+### 响应格式约定
+
+成功响应（由 `ResponseWrapperMiddleware` 自动包装）：
+```json
+{ "code": 0, "data": { ... } }
+```
+
+错误响应（由异常处理器格式化）：
+```json
+{ "code": 401, "message": "用户名或密码错误" }
+```
+
+分页响应：
+```json
+{
+  "code": 0,
+  "data": {
+    "items": [...],
+    "total": 100,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
+
+Pydantic 模型使用 `alias_generator=to_camel` 实现 snake_case → camelCase 转换。
+
+---
+
+## 数据模型
+
+### 新建表
+
+#### 1. `auth.tenant_admins` — 租户管理员表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| username | VARCHAR(50) | UNIQUE NOT NULL | 登录用户名 |
+| password_hash | VARCHAR(255) | NOT NULL | bcrypt 哈希 |
+| display_name | VARCHAR(100) | — | 显示名称 |
+| tenant_id | BIGINT | NOT NULL | 所属租户 |
+| managed_site_ids | BIGINT[] | NOT NULL | 管辖门店 ID 列表 |
+| is_active | BOOLEAN | DEFAULT true | 账号状态 |
+| created_by | BIGINT | — | 创建者（Operator ID） |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
+| last_login_at | TIMESTAMPTZ | — | 最后登录时间 |
+
+索引：`idx_tenant_admin_tenant ON (tenant_id)`
+
+#### 2. `biz.excel_upload_log` — Excel 上传记录表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| site_id | BIGINT | NOT NULL | 门店 ID |
+| upload_type | VARCHAR(30) | CHECK IN (expense, platform_income, salary_adj, recharge_commission) | 模板类型 |
+| file_name | VARCHAR(255) | NOT NULL | 原始文件名 |
+| uploaded_by | BIGINT | NOT NULL | 上传人（管理员 ID） |
+| row_count | INTEGER | DEFAULT 0 | 数据行数 |
+| conflict_count | INTEGER | DEFAULT 0 | 冲突行数 |
+| resolved_count | INTEGER | DEFAULT 0 | 已解决冲突数 |
+| status | VARCHAR(20) | CHECK IN (pending, confirmed, failed) | 批次状态 |
+| error_detail | JSONB | — | 错误详情 |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 上传时间 |
+| confirmed_at | TIMESTAMPTZ | — | 确认时间 |
+
+索引：`idx_excel_log_site ON (site_id, created_at DESC)`
+
+#### 3. `biz.salary_adjustments` — 助教奖罚明细表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| site_id | BIGINT | NOT NULL | 门店 ID |
+| assistant_id | BIGINT | — | 匹配到的助教 ID（可空） |
+| assistant_name | VARCHAR(100) | NOT NULL | 助教姓名 |
+| assistant_number | VARCHAR(50) | NOT NULL | 助教编号 |
+| salary_month | VARCHAR(7) | NOT NULL | 月份 YYYY-MM |
+| adjustment_type | VARCHAR(20) | CHECK IN (deduction, bonus) | 类型 |
+| amount | NUMERIC(12,2) | CHECK > 0 | 金额 |
+| reason | VARCHAR(200) | NOT NULL | 原因 |
+| upload_batch_id | BIGINT | FK → excel_upload_log | 上传批次 |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
+| created_by | BIGINT | — | 上传人 |
+
+索引：`(site_id, salary_month)`, `(assistant_id, salary_month)`
+
+#### 4. `biz.stg_finance_expense` — 财务支出暂存表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| site_id | BIGINT | NOT NULL | 门店 ID |
+| expense_month | VARCHAR(7) | NOT NULL | 月份 |
+| category | VARCHAR(50) | NOT NULL | 支出类别（8 值枚举） |
+| amount | NUMERIC(12,2) | NOT NULL | 金额 |
+| remark | TEXT | — | 备注 |
+| upload_batch_id | BIGINT | FK → excel_upload_log | 上传批次 |
+| synced_at | TIMESTAMPTZ | — | ETL 同步时间（NULL=未同步） |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
+
+#### 5. `biz.stg_platform_income` — 团购收入暂存表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| site_id | BIGINT | NOT NULL | 门店 ID |
+| income_month | VARCHAR(7) | NOT NULL | 月份 |
+| platform_name | VARCHAR(100) | NOT NULL | 平台名称 |
+| amount | NUMERIC(12,2) | NOT NULL | 收入金额 |
+| remark | TEXT | — | 备注 |
+| upload_batch_id | BIGINT | FK → excel_upload_log | 上传批次 |
+| synced_at | TIMESTAMPTZ | — | ETL 同步时间 |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
+
+#### 6. `biz.stg_recharge_commission` — 充值业绩归属暂存表
+
+| 列名 | 类型 | 约束 | 说明 |
+|------|------|------|------|
+| id | BIGSERIAL | PK | 自增主键 |
+| site_id | BIGINT | NOT NULL | 门店 ID |
+| recharge_date | DATE | NOT NULL | 充值日期 |
+| member_name | VARCHAR(100) | NOT NULL | 会员名称 |
+| recharge_amount | NUMERIC(12,2) | NOT NULL | 充值金额 |
+| assigned_assistant | VARCHAR(100) | NOT NULL | 归属助教 |
+| reward_amount | NUMERIC(12,2) | NOT NULL | 奖励金额 |
+| upload_batch_id | BIGINT | FK → excel_upload_log | 上传批次 |
+| synced_at | TIMESTAMPTZ | — | ETL 同步时间 |
+| created_at | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
+
+### 表结构变更
+
+#### `public.member_retention_clue` — 新增 `is_hidden` 列
+
+```sql
+ALTER TABLE public.member_retention_clue
+    ADD COLUMN is_hidden BOOLEAN NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN public.member_retention_clue.is_hidden
+    IS '是否隐藏（true=管理后台保留但小程序不展示）';
+```
+
+已有数据通过 `DEFAULT false` 保证兼容。小程序端线索查询需增加 `WHERE is_hidden = false`。
+
+### 复用的现有表（auth Schema）
+
+| 表 | 用途 |
+|---|------|
+| `auth.users` | 小程序用户主表（审核时更新 status） |
+| `auth.user_applications` | 用户入驻申请（审核列表数据源） |
+| `auth.site_code_mapping` | 球房编号 → site_id 映射 |
+| `auth.roles` | 角色定义（coach/staff/site_admin/tenant_admin） |
+| `auth.user_site_roles` | 用户-门店-角色关联（审核通过时写入） |
+| `auth.user_assistant_binding` | 用户-助教/员工绑定（审核通过时写入） |
+
+### FDW 数据源（ETL 库只读）
+
+| 视图 | 用途 | 查询场景 |
+|------|------|---------|
+| `fdw_etl.v_dim_assistant` | 助教维度表 | 用户审核关联建议、Excel 人员匹配 |
+| `fdw_etl.v_dim_staff` + `v_dim_staff_ex` | 员工维度表 | 用户审核关联建议、Excel 人员匹配 |
+| `fdw_etl.v_dim_member` | 会员维度表 | 维客线索客户搜索（DQ-6 规则） |
+
+多店铺查询策略：逐 `site_id` 调用 `get_etl_readonly_connection(site_id)` 查询后合并结果。
+
+### Pydantic Schema 设计
+
+```python
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+class TenantBaseModel(BaseModel):
+    """租户管理后台基础模型，统一驼峰命名。"""
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+    )
+
+class PaginatedResponse(TenantBaseModel, Generic[T]):
+    items: list[T]
+    total: int
+    page: int
+    page_size: int
+```
+
+
+---
+
+## 正确性属性（Correctness Properties）
+
+*属性（Property）是在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格说明与机器可验证正确性保证之间的桥梁。*
+
+### Property 1: 认证正确性
+
+*For any* 用户名和密码组合，如果该组合对应一个活跃的 `auth.tenant_admins` 记录且密码哈希匹配，则登录应返回包含 `aud=tenant-admin` 的有效 JWT 令牌对；如果用户名不存在或密码不匹配，则应返回 401 且错误消息不区分是用户名还是密码错误。
+
+**Validates: Requirements 1.1, 1.2**
+
+### Property 2: JWT 隔离与端点保护
+
+*For any* JWT 令牌和任意 `/api/tenant/*` 受保护端点，当且仅当令牌有效且 `aud=tenant-admin` 时请求应被允许；`aud` 不匹配（如小程序 JWT `aud=xcx`）、令牌过期或令牌无效时应返回 401。
+
+**Validates: Requirements 1.4, 1.6, 17.3**
+
+### Property 3: 数据隔离
+
+*For any* 租户管理员和任意数据查询端点，返回结果中每条记录的 `site_id` 必须属于该管理员的 `managed_site_ids` 集合；尝试访问不在 `managed_site_ids` 范围内的数据应返回 403。
+
+**Validates: Requirements 2.1, 2.2, 2.3**
+
+### Property 4: 审核通过多表一致性
+
+*For any* 状态为 `pending` 的用户申请，执行审核通过操作后，以下条件应同时成立：`auth.users.status = 'approved'`、`auth.user_site_roles` 中存在对应角色记录、`auth.user_assistant_binding` 中存在绑定记录（如提供了 assistant_id/staff_id）、`auth.user_applications.status = 'approved'` 且审核人和审核时间已填写。
+
+**Validates: Requirements 3.4**
+
+### Property 5: 审核拒绝状态更新
+
+*For any* 状态为 `pending` 的用户申请和任意非空拒绝原因字符串，执行审核拒绝操作后，`auth.user_applications.status` 应为 `rejected`，`review_note` 应等于提交的拒绝原因，`reviewed_at` 应非空。
+
+**Validates: Requirements 3.5**
+
+### Property 6: 申请关联匹配
+
+*For any* 用户申请中的手机号和球房编号，关联匹配逻辑应：先通过 `site_code_mapping` 解析 `site_id`，然后在 `v_dim_assistant`（`scd2_is_current=1`）和 `v_dim_staff` + `v_dim_staff_ex` 中按 phone 匹配，返回的候选列表应仅包含 phone 匹配的记录。
+
+**Validates: Requirements 3.3**
+
+### Property 7: 用户管理编辑
+
+*For any* 已通过审核的用户和任意有效的编辑参数（角色、site_id 在管辖范围内、状态），编辑操作后用户记录应反映新值；修改绑定关系后 `user_assistant_binding` 应更新为新的 `assistant_id`/`staff_id`。
+
+**Validates: Requirements 4.2, 4.3, 4.4**
+
+### Property 8: Excel 格式校验
+
+*For any* 模板类型和任意数据行集合，校验器应：对符合模板列定义的行标记为通过，对不符合的行返回包含行号、列名和错误描述的错误信息；校验全部通过时应创建 `excel_upload_log` 记录（status=pending）；通过行数 + 警告行数 + 错误行数 = 总行数。
+
+**Validates: Requirements 5.1, 5.2, 5.3, 5.4, 6.5**
+
+### Property 9: 人员匹配校验
+
+*For any* 助教姓名+编号组合和给定的助教/员工数据集，匹配逻辑应：优先在 `v_dim_assistant`（nickname + assistant_number）中匹配，未匹配时再查 `v_dim_staff` + `v_dim_staff_ex`（name + staff_number）；匹配成功时填充 `assistant_id`，匹配失败时标记为 warning 且不阻断流程。
+
+**Validates: Requirements 6.1, 6.2, 6.3, 6.4**
+
+### Property 10: 冲突检测
+
+*For any* 模板类型、上传数据集和已有数据集，冲突检测应：按模板主键规则（如财务支出的"月份+支出类别"）识别主键重复的行，对冲突行返回逐字段 diff（旧值 vs 新值），非冲突行标记为待写入。
+
+**Validates: Requirements 7.1, 7.2**
+
+### Property 11: 数据写入 round-trip
+
+*For any* 确认写入的数据批次和冲突解决方案，写入后从目标表读取的数据应与提交的数据一致（选择"替换"的行使用新值，选择"保留"的行保持旧值）；`excel_upload_log` 状态应更新为 `confirmed`，实际写入行数应正确记录。
+
+**Validates: Requirements 7.4, 7.5, 8.1, 8.2**
+
+### Property 12: 客户搜索
+
+*For any* 搜索关键词和管辖门店范围，搜索结果应满足：每条结果的 `nickname` 包含关键词（模糊匹配）或 `mobile` 等于关键词（精确匹配），且 `site_id` 在管辖范围内；指定门店筛选时结果应仅包含该门店的客户。
+
+**Validates: Requirements 9.1, 9.3**
+
+### Property 13: 线索编辑校验
+
+*For any* 有效的编辑参数（category 在 6 值枚举内、summary 非空且 ≤200 字符），编辑操作后线索记录应反映新值；对于无效的 category 或空/超长 summary，应拒绝操作。
+
+**Validates: Requirements 11.1, 11.2**
+
+### Property 14: 线索删除
+
+*For any* 存在且在管辖门店范围内的线索，执行删除操作后，该线索应不可通过任何查询接口获取（物理删除）。
+
+**Validates: Requirements 12.2**
+
+### Property 15: 线索隐藏/显示 round-trip
+
+*For any* 线索，将 `is_hidden` 设为 `true` 后，小程序端查询（`WHERE is_hidden = false`）不应返回该线索，但管理后台查询应返回；再将 `is_hidden` 设回 `false` 后，小程序端查询应恢复返回该线索。
+
+**Validates: Requirements 13.1, 13.2, 13.3, 15.3**
+
+### Property 16: 响应格式一致性
+
+*For any* `/api/tenant/*` 端点的成功响应，响应体应符合 `{ code: 0, data: ... }` 格式；错误响应应符合 `{ code: <status_code>, message: <string> }` 格式；分页响应的 `data` 应包含 `items`、`total`、`page`、`pageSize` 字段。
+
+**Validates: Requirements 17.4**
+
+---
+
+## 错误处理
+
+### 认证错误
+
+| 场景 | HTTP 状态码 | 错误消息 | 处理方式 |
+|------|------------|---------|---------|
+| 用户名或密码错误 | 401 | "用户名或密码错误" | 统一消息，不区分 |
+| 账号已禁用 | 403 | "账号已被禁用" | 检查 `is_active` |
+| JWT 过期 | 401 | "令牌已过期" | 前端自动刷新 |
+| JWT 无效/aud 不匹配 | 401 | "无效的令牌" | 重定向登录页 |
+| 刷新令牌过期 | 401 | "刷新令牌已过期" | 清除令牌，重定向登录页 |
+
+### 数据隔离错误
+
+| 场景 | HTTP 状态码 | 错误消息 |
+|------|------------|---------|
+| 访问非管辖门店数据 | 403 | "无权访问该门店数据" |
+| 修改 site_id 超出管辖范围 | 403 | "目标门店不在管辖范围内" |
+
+### 业务逻辑错误
+
+| 场景 | HTTP 状态码 | 错误消息 |
+|------|------------|---------|
+| 审核非 pending 状态的申请 | 409 | "该申请已被处理" |
+| 线索 ID 不存在 | 404 | "线索不存在" |
+| 线索不在管辖范围 | 404 | "线索不存在" |
+| category 枚举值无效 | 422 | "无效的线索大类" |
+| summary 为空或超长 | 422 | "摘要不能为空且不超过200字符" |
+
+### Excel 上传错误
+
+| 场景 | HTTP 状态码 | 错误消息 |
+|------|------------|---------|
+| 文件格式非 .xlsx/.xls | 400 | "请上传有效的 Excel 文件" |
+| 格式校验失败 | 200 | 返回错误行详情（不阻断，前端标红） |
+| 人员匹配失败 | 200 | 标记为 warning（不阻断，前端黄色高亮） |
+| 写入数据库失败 | 500 | 回滚整批，log status=failed，记录 error_detail |
+
+### 数据库事务策略
+
+- Excel 写入：整批次在单个事务中执行，任何行写入失败则回滚全部
+- 审核通过：多表写入在单个事务中执行（users + user_site_roles + user_assistant_binding + user_applications）
+- 线索操作：单条记录操作，无需跨表事务
+
+---
+
+## 测试策略
+
+### 双轨测试方法
+
+本项目采用单元测试 + 属性测试的双轨策略：
+
+- **单元测试**：验证具体示例、边界条件和错误处理
+- **属性测试**：验证跨所有输入的通用属性
+
+两者互补：单元测试捕获具体 bug，属性测试验证通用正确性。
+
+### 属性测试配置
+
+- **库**：Python 后端使用 `hypothesis`（项目已有 `.hypothesis/` 目录）；前端使用 `fast-check`
+- **迭代次数**：每个属性测试最少 100 次迭代
+- **标签格式**：`Feature: tenant-admin-web, Property {number}: {property_text}`
+- **每个正确性属性对应一个属性测试**
+
+### 单元测试覆盖
+
+| 模块 | 测试重点 |
+|------|---------|
+| `tenant_auth.py` | 登录成功/失败、禁用账号、JWT 签发/验证、刷新令牌 |
+| `tenant_users.py` | 申请列表筛选、审核通过/拒绝、非 pending 状态拒绝（409）、用户编辑、绑定修改 |
+| `tenant_excel.py` | 4 种模板格式校验、人员匹配、冲突检测、写入回滚、模板下载 |
+| `tenant_clues.py` | 客户搜索、线索 CRUD、隐藏/显示、枚举校验、越权访问 |
+| 前端 `services/api.ts` | JWT 自动附加、401 刷新、并发刷新保护 |
+
+### 属性测试覆盖
+
+| Property | 测试描述 | 生成器 |
+|----------|---------|--------|
+| P1 | 认证正确性 | 随机用户名+密码 |
+| P2 | JWT 隔离 | 随机 JWT payload（不同 aud） |
+| P3 | 数据隔离 | 随机 managed_site_ids + 随机数据 |
+| P4 | 审核通过一致性 | 随机 pending 申请 + 角色/绑定参数 |
+| P5 | 审核拒绝 | 随机 pending 申请 + 随机拒绝原因 |
+| P6 | 关联匹配 | 随机手机号 + 随机助教/员工数据集 |
+| P7 | 用户编辑 | 随机用户 + 随机编辑参数 |
+| P8 | Excel 校验 | 随机模板类型 + 随机数据行（含有效/无效） |
+| P9 | 人员匹配 | 随机姓名+编号 + 随机助教/员工数据集 |
+| P10 | 冲突检测 | 随机上传数据 + 随机已有数据 |
+| P11 | 写入 round-trip | 随机数据 + 随机冲突解决方案 |
+| P12 | 客户搜索 | 随机关键词 + 随机客户数据集 |
+| P13 | 线索编辑 | 随机 category + 随机 summary |
+| P14 | 线索删除 | 随机线索 ID |
+| P15 | 隐藏/显示 round-trip | 随机线索 + 隐藏→显示→验证 |
+| P16 | 响应格式 | 随机端点调用 |
+
+### 边界条件测试（单元测试覆盖）
+
+- 禁用账号登录（1.3）→ 403
+- 非 pending 申请审核（3.6）→ 409
+- 越权修改 site_id（4.5）→ 403
+- 无效 Excel 文件格式（5.5）→ 400
+- 写入数据库失败回滚（8.3）→ log status=failed
+- 线索 ID 不存在/越权（11.3, 12.3, 13.4）→ 404