242 lines
22 KiB
Markdown
242 lines
22 KiB
Markdown
# 需求文档：租户管理后台（tenant-admin-web）
|
||
|
||
## 简介
|
||
|
||
构建独立的租户管理 Web 应用（`apps/tenant-admin/`），面向租户管理员，提供用户审核与管理、Excel 数据上传（4 种模板）、维客线索管理三大功能模块。前端采用 React + Vite + Ant Design（与 `apps/admin-web/` 同技术栈），后端复用 `apps/backend/` FastAPI 新增 4 个路由模块。认证体系与小程序完全隔离，使用独立的 `auth.tenant_admins` 表、用户名+密码登录、不同 JWT audience。所有数据查询附加 `site_id IN (管辖列表)` 条件实现多门店数据隔离。
|
||
|
||
## 术语表
|
||
|
||
- **Tenant_Admin_Web**：租户管理后台前端应用，部署在 `apps/tenant-admin/`
|
||
- **Backend_API**：FastAPI 后端服务，部署在 `apps/backend/`，为 Tenant_Admin_Web 提供 RESTful API
|
||
- **Tenant_Admin**：租户管理员，由系统管理后台 Operator 创建的账号，使用用户名+密码登录租户管理后台
|
||
- **Operator**：系统管理后台操作员，在 `apps/admin-web/` 中管理租户管理员账号
|
||
- **Site**：门店，通过 `site_id` 标识，是多门店数据隔离的基本单位
|
||
- **Site_Code**：球房编号，用户申请时输入的门店标识码，通过 `auth.site_code_mapping` 映射到 `site_id`
|
||
- **User_Application**：用户入驻申请，小程序用户提交的申请记录，存储在 `auth.user_applications`
|
||
- **Retention_Clue**：维客线索，助教为会员记录的销售/维护线索，存储在 `public.member_retention_clue`
|
||
- **Staging_Table**：暂存表，Excel 上传数据先写入业务库暂存表，再由 ETL 同步到 DWS 层
|
||
- **Upload_Batch**：上传批次，一次 Excel 上传操作的记录，存储在 `biz.excel_upload_log`
|
||
- **Salary_Adjustment**：助教奖罚明细，通过 Excel 上传写入 `biz.salary_adjustments`
|
||
- **Managed_Site_Ids**：管辖门店列表，Tenant_Admin 被授权管理的 `site_id` 数组
|
||
|
||
## 需求
|
||
|
||
### 需求 1：租户管理员认证
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望通过用户名和密码登录租户管理后台，以便安全地执行用户审核、数据上传等管理操作。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 提交有效的用户名和密码, THE Backend_API SHALL 验证凭据（bcrypt 哈希比对），签发 JWT 访问令牌（audience 为 `tenant-admin`，与小程序 `xcx` 隔离），并返回访问令牌和刷新令牌
|
||
2. WHEN Tenant_Admin 提交无效的用户名或密码, THE Backend_API SHALL 返回 401 状态码和错误描述，不泄露具体是用户名还是密码错误
|
||
3. IF Tenant_Admin 账号状态为禁用（`is_active = false`）, THEN THE Backend_API SHALL 返回 403 状态码并提示账号已被禁用
|
||
4. WHILE Tenant_Admin 持有有效的 JWT 令牌, THE Backend_API SHALL 允许访问 `/api/tenant/*` 路径下的受保护端点
|
||
5. WHEN JWT 访问令牌过期, THE Tenant_Admin_Web SHALL 使用刷新令牌自动获取新的访问令牌；WHEN 刷新令牌也过期, THE Tenant_Admin_Web SHALL 将 Tenant_Admin 重定向到登录页面
|
||
6. THE Backend_API SHALL 通过 JWT 中的 `aud` 字段区分租户管理员和小程序用户，使用独立的认证依赖注入（`require_tenant_admin()`），拒绝小程序 JWT 访问租户管理端点
|
||
|
||
### 需求 2：数据隔离与权限控制
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望只能查看和操作自己管辖门店的数据，以确保多门店之间的数据安全隔离。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Backend_API SHALL 在所有租户管理端点的数据查询中附加 `site_id IN (managed_site_ids)` 条件，其中 `managed_site_ids` 从当前 Tenant_Admin 的 JWT 令牌或 `auth.tenant_admins` 记录中获取
|
||
2. WHEN Tenant_Admin 的 `managed_site_ids` 包含多个 site_id, THE Backend_API SHALL 支持跨门店聚合查询（合并多个 site_id 的结果）
|
||
3. IF Tenant_Admin 尝试访问不在其 `managed_site_ids` 范围内的数据, THEN THE Backend_API SHALL 返回 403 状态码
|
||
4. THE Tenant_Admin_Web SHALL 在页面顶部提供门店筛选器，允许 Tenant_Admin 在管辖范围内切换或选择门店
|
||
|
||
### 需求 3：用户申请审核
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望查看和审核小程序用户的入驻申请，以便控制哪些用户可以使用系统。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 打开用户审核页面, THE Tenant_Admin_Web SHALL 从 Backend_API 获取管辖门店范围内的用户申请列表，支持按状态筛选（全部 / 待审核 pending / 已通过 approved / 已拒绝 rejected），支持分页
|
||
2. THE Backend_API SHALL 返回每条申请的以下信息：申请人昵称、手机号、球房编号（site_code）、申请角色文本、员工编号、申请时间、当前状态
|
||
3. WHEN Tenant_Admin 查看某条待审核申请的关联建议, THE Backend_API SHALL 根据申请中的球房编号通过 `auth.site_code_mapping` 查得 `site_id`，再并行匹配 `fdw_etl.v_dim_assistant`（phone 匹配，`scd2_is_current=1`）和 `fdw_etl.v_dim_staff` + `v_dim_staff_ex`（phone 匹配），返回匹配建议列表
|
||
4. WHEN Tenant_Admin 审核通过一条申请, THE Backend_API SHALL 接受角色（助教/管理者/员工）、关联助教 ID（可选）、关联员工 ID（可选），执行以下操作：更新 `auth.users.status = 'approved'`、写入 `auth.user_site_roles`（分配角色）、写入 `auth.user_assistant_binding`（关联助教/员工，含 staff_id）、更新 `auth.user_applications.status = 'approved'` 及审核人和审核时间
|
||
5. WHEN Tenant_Admin 审核拒绝一条申请, THE Backend_API SHALL 接受拒绝原因（必填），更新 `auth.user_applications.status = 'rejected'`、`review_note` 和审核时间
|
||
6. IF 申请状态不是 pending, THEN THE Backend_API SHALL 拒绝审核操作并返回 409 状态码
|
||
|
||
### 需求 4：用户管理
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望管理已通过审核的用户信息，包括修改角色、店铺归属和助教绑定关系，以便维护用户数据的准确性。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 打开用户管理页面, THE Tenant_Admin_Web SHALL 展示管辖门店范围内已通过审核的用户列表，包含姓名、角色、关联助教姓名、所属门店、账号状态，支持按角色筛选和关键词搜索，支持分页
|
||
2. WHEN Tenant_Admin 编辑用户信息, THE Backend_API SHALL 允许修改以下字段：角色（助教/管理者/员工）、所属门店（`site_id`，限管辖范围内）、账号状态（启用/禁用）
|
||
3. WHEN Tenant_Admin 修改用户的助教/员工绑定关系, THE Backend_API SHALL 更新 `auth.user_assistant_binding` 记录，接受新的 `assistant_id` 和/或 `staff_id`
|
||
4. WHEN Tenant_Admin 禁用某用户账号, THE Backend_API SHALL 将 `auth.users.status` 设为 `disabled`，该用户后续登录小程序时 SHALL 被拒绝
|
||
5. IF Tenant_Admin 尝试将用户的 site_id 修改为不在其管辖范围内的值, THEN THE Backend_API SHALL 返回 403 状态码
|
||
|
||
### 需求 5：Excel 上传 — 文件解析与格式校验
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望上传 Excel 文件并获得即时的格式校验反馈，以便在数据写入前发现和修正错误。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 选择模板类型并上传 Excel 文件, THE Backend_API SHALL 解析文件内容，按对应模板的列定义进行格式校验，并返回校验结果
|
||
2. THE Backend_API SHALL 支持 4 种模板类型的格式校验：
|
||
- 财务支出（expense）：月份（YYYY-MM，不超过当前月）、支出类别（枚举 8 值：房租/水电/物业/食品饮料进货/耗材/报销/固定人员工资/其他费用）、金额（> 0，精度 2 位小数）、备注（可选，最长 500 字符）
|
||
- 团购收入（platform_income）：月份（YYYY-MM）、平台名称（非空）、收入金额（> 0）、备注（可选，最长 500 字符）
|
||
- 助教奖罚（salary_adj）：月份（YYYY-MM）、助教姓名（非空）、助教编号（非空）、类型（枚举：扣款/奖金）、金额（> 0）、原因（非空，最长 200 字符）
|
||
- 充值业绩归属（recharge_commission）：充值日期（YYYY-MM-DD）、会员名称（非空）、充值金额（> 0）、归属助教（非空）、奖励金额（≥ 0）
|
||
3. WHEN 校验发现格式错误行, THE Backend_API SHALL 返回错误行号、列名和具体错误描述，Tenant_Admin_Web SHALL 标红展示错误行
|
||
4. WHEN 校验全部通过, THE Backend_API SHALL 创建 `biz.excel_upload_log` 记录（状态为 pending），返回 upload_id 和解析后的数据预览
|
||
5. IF 上传文件不是有效的 Excel 格式（.xlsx/.xls）, THEN THE Backend_API SHALL 返回 400 状态码并提示文件格式错误
|
||
|
||
### 需求 6：Excel 上传 — 人员匹配校验
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望上传助教奖罚和充值业绩归属数据时，系统能自动校验助教信息的准确性，以减少数据录入错误。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 上传助教奖罚（salary_adj）或充值业绩归属（recharge_commission）模板时, THE Backend_API SHALL 对每行数据中的助教姓名+助教编号执行匹配校验
|
||
2. THE Backend_API SHALL 按以下顺序匹配：先查 `fdw_etl.v_dim_assistant`（nickname + assistant_number，`scd2_is_current=1`），如不匹配再查 `fdw_etl.v_dim_staff` + `v_dim_staff_ex`（name + staff_number）
|
||
3. WHEN 匹配成功, THE Backend_API SHALL 在返回数据中填充 `assistant_id`
|
||
4. WHEN 匹配失败, THE Backend_API SHALL 标记该行为校验警告（warning），不阻断上传流程，但在前端以黄色高亮提示 Tenant_Admin 确认
|
||
5. THE Tenant_Admin_Web SHALL 在校验结果页面汇总展示：通过行数、警告行数、错误行数
|
||
|
||
### 需求 7：Excel 上传 — 冲突检测与解决
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望在数据写入前看到与已有数据的冲突情况，并能逐行选择处理方式，以避免误覆盖历史数据。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 格式校验通过后, THE Backend_API SHALL 按各模板的主键规则检测冲突：
|
||
- 财务支出：月份 + 支出类别
|
||
- 团购收入：月份 + 平台名称
|
||
- 助教奖罚：月份 + 助教姓名 + 助教编号 + 类型 + 原因
|
||
- 充值业绩归属：充值日期 + 会员名称 + 归属助教
|
||
2. WHEN 检测到冲突行（主键已存在）, THE Backend_API SHALL 返回 diff 数据（旧值 vs 新值，按字段逐一对比）
|
||
3. THE Tenant_Admin_Web SHALL 展示 diff 交互表格，每行显示字段名、旧值、新值和操作选项（替换/保留），支持"全部替换"和"全部保留"快捷操作
|
||
4. WHEN Tenant_Admin 确认冲突解决方案并提交, THE Backend_API SHALL 接受 upload_id 和每行的解决方案（resolutions 数组），按选择执行写入
|
||
5. WHEN 无冲突行, THE Backend_API SHALL 直接标记为"待写入"，Tenant_Admin 确认后写入
|
||
|
||
### 需求 8：Excel 上传 — 数据写入与记录
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望确认后的数据能正确写入目标表，并保留上传历史记录以便追溯。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 确认写入, THE Backend_API SHALL 将数据写入对应目标表：
|
||
- 助教奖罚 → `biz.salary_adjustments`（直接写入业务库）
|
||
- 财务支出 → `biz.stg_finance_expense`（staging 表，由 ETL 同步到 DWS）
|
||
- 团购收入 → `biz.stg_platform_income`（staging 表）
|
||
- 充值业绩归属 → `biz.stg_recharge_commission`（staging 表）
|
||
2. THE Backend_API SHALL 在写入完成后更新 `biz.excel_upload_log` 记录：状态设为 `confirmed`、记录实际写入行数、冲突解决数、确认时间
|
||
3. IF 写入过程中发生数据库错误, THEN THE Backend_API SHALL 回滚整个批次的写入，将 `biz.excel_upload_log` 状态设为 `failed`，记录错误详情到 `error_detail` 字段
|
||
4. WHEN Tenant_Admin 查看上传记录页面, THE Backend_API SHALL 返回管辖门店范围内的历史上传记录列表，包含模板类型、文件名、上传人、上传时间、行数、冲突数、状态，支持分页
|
||
5. WHEN Tenant_Admin 下载空白模板, THE Backend_API SHALL 返回对应模板类型的 Excel 文件（含表头和格式说明）
|
||
|
||
### 需求 9：维客线索 — 客户搜索
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望通过客户姓名或手机号搜索客户，以便查看和管理其维客线索。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 输入搜索关键词, THE Backend_API SHALL 在管辖门店范围内搜索客户，匹配 `fdw_etl.v_dim_member` 的 `nickname`（模糊匹配）或 `mobile`（精确匹配），返回客户列表（member_id、姓名、手机号脱敏、所属门店）
|
||
2. THE Backend_API SHALL 通过 `member_id` JOIN `fdw_etl.v_dim_member`（`scd2_is_current=1`）获取客户姓名和手机号，不使用结算单上的冗余字段（DQ-6 规则）
|
||
3. WHEN Tenant_Admin 选择门店筛选条件, THE Backend_API SHALL 在搜索结果中仅返回该门店的客户
|
||
4. IF 搜索结果为空, THEN THE Tenant_Admin_Web SHALL 展示"未找到匹配客户"的提示
|
||
|
||
### 需求 10：维客线索 — 线索列表与展示
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望查看某客户的全部维客线索，以便了解客户画像和历史记录。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 选择某客户, THE Backend_API SHALL 返回该客户在管辖门店范围内的全部维客线索列表，包含：线索 ID、大类标签（category）、摘要（summary）、详情（detail）、提供人（recorded_by_name）、来源（source：manual / ai_consumption / ai_note）、记录时间（recorded_at）、隐藏状态（is_hidden）
|
||
2. THE Tenant_Admin_Web SHALL 按大类标签分组展示线索，支持按来源和隐藏状态筛选
|
||
3. THE Tenant_Admin_Web SHALL 对已隐藏的线索以灰色或删除线样式区分展示
|
||
|
||
### 需求 11：维客线索 — 编辑
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望修改维客线索的标签、摘要和详情，以便纠正错误或补充信息。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 编辑某条线索, THE Backend_API SHALL 接受修改后的 category（枚举 6 值：客户基础/消费习惯/玩法偏好/促销偏好/社交关系/重要反馈）、summary（非空，最长 200 字符）、detail（可选）
|
||
2. THE Backend_API SHALL 验证 category 值在枚举范围内，summary 非空且不超过长度限制
|
||
3. IF 线索 ID 不存在或不在管辖门店范围内, THEN THE Backend_API SHALL 返回 404 状态码
|
||
|
||
### 需求 12：维客线索 — 删除
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望删除错误或无效的维客线索，以保持数据整洁。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 请求删除某条线索, THE Tenant_Admin_Web SHALL 弹出二次确认对话框，明确提示"删除后不可恢复"
|
||
2. WHEN Tenant_Admin 确认删除, THE Backend_API SHALL 对该线索执行物理删除（`DELETE FROM public.member_retention_clue WHERE id = ?`）
|
||
3. IF 线索 ID 不存在或不在管辖门店范围内, THEN THE Backend_API SHALL 返回 404 状态码
|
||
|
||
### 需求 13：维客线索 — 隐藏与显示
|
||
|
||
**用户故事：** 作为 Tenant_Admin，我希望隐藏某些线索使其不在小程序端展示，同时保留在管理后台可见，以便灵活控制线索的可见性。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Tenant_Admin 切换某条线索的隐藏状态, THE Backend_API SHALL 更新 `public.member_retention_clue.is_hidden` 字段（true=隐藏，false=显示）
|
||
2. WHILE 线索的 `is_hidden = true`, THE Backend_API SHALL 确保小程序端查询线索时通过 `WHERE is_hidden = false` 条件过滤该线索
|
||
3. THE Tenant_Admin_Web SHALL 允许 Tenant_Admin 将已隐藏的线索恢复为显示状态（`is_hidden = false`）
|
||
4. IF 线索 ID 不存在或不在管辖门店范围内, THEN THE Backend_API SHALL 返回 404 状态码
|
||
|
||
### 需求 14：管理后台 — 租户管理员账号管理
|
||
|
||
**用户故事：** 作为 Operator，我希望在系统管理后台（admin-web）中创建、编辑和管理租户管理员账号，以便控制谁可以登录租户管理后台。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN Operator 打开租户管理员管理页面, THE admin-web SHALL 展示所有租户管理员列表，包含用户名、显示名称、管辖门店、账号状态（启用/禁用）、创建时间、最后登录时间，支持分页和关键词搜索
|
||
2. WHEN Operator 创建新的租户管理员, THE Backend_API SHALL 接受用户名（唯一）、初始密码、显示名称、tenant_id、managed_site_ids（门店列表），将密码 bcrypt 哈希后写入 `auth.tenant_admins`，记录 `created_by` 为当前 Operator 的 user_id
|
||
3. IF 用户名已存在, THEN THE Backend_API SHALL 返回 409 状态码并提示"用户名已存在"
|
||
4. WHEN Operator 编辑租户管理员信息, THE Backend_API SHALL 允许修改以下字段：显示名称、managed_site_ids、is_active（启用/禁用）
|
||
5. WHEN Operator 重置租户管理员密码, THE Backend_API SHALL 接受新密码，bcrypt 哈希后更新 `auth.tenant_admins.password_hash`
|
||
6. IF Operator 禁用某租户管理员（is_active=false）, THEN 该管理员后续登录租户管理后台时 SHALL 被拒绝（返回 403）
|
||
7. THE Backend_API SHALL 要求 Operator 具有 site_admin 或 tenant_admin 角色才能访问租户管理员管理端点
|
||
|
||
### 需求 15：数据库变更 — 新建表
|
||
|
||
**用户故事：** 作为开发者，我需要创建 NS4 所需的新数据库表，以支撑租户管理后台的全部功能。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 迁移脚本 SHALL 在 `auth` Schema 中创建 `tenant_admins` 表，包含字段：id（BIGSERIAL PK）、username（VARCHAR(50) UNIQUE NOT NULL）、password_hash（VARCHAR(255) NOT NULL）、display_name（VARCHAR(100)）、tenant_id（BIGINT NOT NULL）、managed_site_ids（BIGINT[] NOT NULL）、is_active（BOOLEAN DEFAULT true）、created_by（BIGINT）、created_at（TIMESTAMPTZ DEFAULT NOW()）、last_login_at（TIMESTAMPTZ），并创建 tenant_id 索引
|
||
2. THE 迁移脚本 SHALL 在 `biz` Schema 中创建 `salary_adjustments` 表，包含字段：id（BIGSERIAL PK）、site_id（BIGINT NOT NULL）、assistant_id（BIGINT 可空）、assistant_name（VARCHAR(100) NOT NULL）、assistant_number（VARCHAR(50) NOT NULL）、salary_month（VARCHAR(7) NOT NULL）、adjustment_type（CHECK IN deduction/bonus）、amount（NUMERIC(12,2) > 0）、reason（VARCHAR(200) NOT NULL）、upload_batch_id（FK → excel_upload_log）、created_at、created_by，并创建 (site_id, salary_month) 和 (assistant_id, salary_month) 索引
|
||
3. THE 迁移脚本 SHALL 在 `biz` Schema 中创建 `excel_upload_log` 表，包含字段：id（BIGSERIAL PK）、site_id（BIGINT NOT NULL）、upload_type（CHECK IN expense/platform_income/salary_adj/recharge_commission）、file_name（VARCHAR(255) NOT NULL）、uploaded_by（BIGINT NOT NULL）、row_count（INTEGER DEFAULT 0）、conflict_count（INTEGER DEFAULT 0）、resolved_count（INTEGER DEFAULT 0）、status（CHECK IN pending/confirmed/failed）、error_detail（JSONB）、created_at、confirmed_at，并创建 (site_id, created_at DESC) 索引
|
||
4. THE 迁移脚本 SHALL 在 `biz` Schema 中创建 3 张 staging 表：`stg_finance_expense`、`stg_platform_income`、`stg_recharge_commission`，各表包含 site_id、业务字段、upload_batch_id（FK）、synced_at（TIMESTAMPTZ 可空，NULL 表示未同步）、created_at
|
||
|
||
### 需求 16：数据库变更 — 表结构修改
|
||
|
||
**用户故事：** 作为开发者，我需要为现有表添加 NS4 所需的字段，以支持维客线索隐藏功能。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 迁移脚本 SHALL 为 `public.member_retention_clue` 表添加 `is_hidden` 列（BOOLEAN NOT NULL DEFAULT false），并添加列注释说明"是否隐藏（true=管理后台保留但小程序不展示）"
|
||
2. THE 迁移脚本 SHALL 确保已有数据的 `is_hidden` 值为 false（通过 DEFAULT 约束保证）
|
||
3. THE 小程序端现有的线索查询 API SHALL 在查询条件中增加 `WHERE is_hidden = false`，确保隐藏线索不在小程序端展示
|
||
|
||
### 需求 17：前端应用骨架
|
||
|
||
**用户故事：** 作为开发者，我需要搭建租户管理后台的前端项目骨架，以便后续功能页面的开发。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE 前端项目 SHALL 在 `apps/tenant-admin/` 目录下创建，使用 React + Vite + Ant Design 技术栈，包含 `package.json`、`vite.config.ts`、`tsconfig.json` 等配置文件
|
||
2. THE Tenant_Admin_Web SHALL 提供侧边栏导航，包含四个功能模块入口：用户审核、用户管理、Excel 上传、维客线索管理
|
||
3. THE Tenant_Admin_Web SHALL 实现登录页面，未认证时自动重定向到登录页
|
||
4. THE Tenant_Admin_Web SHALL 封装统一的 API 调用层（`services/api.ts`），处理 JWT 令牌的自动附加、刷新和过期重定向
|
||
5. THE Tenant_Admin_Web SHALL 使用与 Backend_API 一致的响应格式（`{ code: 0, data: ... }`），Pydantic 使用 `alias_generator=to_camel` 实现驼峰命名转换
|
||
|
||
### 需求 18：后端路由模块
|
||
|
||
**用户故事：** 作为开发者，我需要在 FastAPI 后端中创建租户管理专用的路由模块，以提供 NS4 所需的全部 API 端点。
|
||
|
||
#### 验收标准
|
||
|
||
1. THE Backend_API SHALL 在 `apps/backend/app/routers/` 下创建 4 个路由文件：`tenant_auth.py`（登录/JWT 签发/鉴权）、`tenant_users.py`（用户审核+用户管理）、`tenant_excel.py`（Excel 上传/校验/冲突处理）、`tenant_clues.py`（维客线索管理），以及 1 个管理端路由文件 `admin_tenant_admins.py`（租户管理员 CRUD）
|
||
2. THE Backend_API SHALL 将所有租户管理端点注册在 `/api/tenant/` 路径前缀下，管理端租户管理员 CRUD 端点注册在 `/api/admin/tenant-admins/` 路径前缀下，与小程序端点（`/api/xcx/`）隔离
|
||
3. THE Backend_API SHALL 为所有 `/api/tenant/*` 端点（登录接口除外）添加 `require_tenant_admin()` 认证依赖，验证 JWT 的 `aud` 字段为 `tenant-admin`；为 `/api/admin/tenant-admins/*` 端点添加 `_require_admin()` 认证依赖，验证 site_admin 或 tenant_admin 角色
|
||
4. THE Backend_API SHALL 遵循现有的 API 响应格式约定：成功返回 `{ code: 0, data: ... }`，失败返回 `{ code: number, message: string }`，分页返回 `{ items: T[], total: number, page: number, pageSize: number }`
|