Neo
b25308c3f4
## P1 数据库基础 - zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu - etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表 - 清理 assistant_abolish 残留数据 ## P2 ETL/DWS 扩展 - 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution) - 新增 assistant_order_contribution_task 任务及 RLS 视图 - member_consumption 增加充值字段、assistant_daily 增加处罚字段 - 更新 ODS/DWD/DWS 任务文档及业务规则文档 - 更新 consistency_checker、flow_runner、task_registry 等核心模块 ## P3 小程序鉴权系统 - 新增 xcx_auth 路由/schema（微信登录 + JWT） - 新增 wechat/role/matching/application 服务层 - zqyy_app 鉴权表迁移 + 角色权限种子数据 - auth/dependencies.py 支持小程序 JWT 鉴权 ## 文档与审计 - 新增 DOCUMENTATION-MAP 文档导航 - 新增 7 份 BD_Manual 数据库变更文档 - 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth） - 新增全栈集成审计记录、部署检查清单更新 - 新增 BACKLOG 路线图、FDW→Core 迁移计划 ## Kiro 工程化 - 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务） - 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan） - 新增 6 个 Hook（合规检查/会话日志/提交审计等） - 新增 doc-map steering 文件 ## 运维与测试 - 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告 - 新增属性测试：test_dws_contribution / test_auth_system - 清理过期 export 报告文件 - 更新 .gitignore 排除规则
134 lines
4.6 KiB
Markdown
134 lines
4.6 KiB
Markdown
# P10：租户管理后台 — tenant-admin-web
|
||
|
||
> 优先级：P10（依赖 P1 + P3，可与 P4-P9 并行）
|
||
> 预估工作量：中等
|
||
|
||
---
|
||
|
||
## 需求（Requirements）
|
||
|
||
### 用户故事
|
||
|
||
1. 作为租户管理员，我需要独立的 Web 管理后台来审核用户申请。
|
||
2. 作为租户管理员，我需要管理用户（编辑身份、店铺归属、关联助教）。
|
||
3. 作为租户管理员，我需要上传 Excel 数据（财务支出/团购收入/助教奖罚/充值业绩归属）。
|
||
4. 作为租户管理员，上传 Excel 时如果发现主键冲突，我需要逐条确认替换或保留（类似 diff 交互）。
|
||
5. 作为系统，租户管理员只能看到自己租户下的店铺数据。
|
||
|
||
### 验收标准
|
||
|
||
- AC1：租户管理后台是独立 Web 应用，独立登录入口
|
||
- AC2：租户管理员只能看到自己租户下的店铺和用户
|
||
- AC3：用户审核页面：申请列表、状态筛选、球房ID+手机号关联建议（同时匹配助教表+员工信息表）、审核操作
|
||
- AC4：Excel 上传校验：必填、金额精度、表头格式、类型合法
|
||
- AC5：主键冲突时前端展示 diff 交互，逐条确认后保存
|
||
- AC6：助教奖罚支持同一助教同月多笔
|
||
|
||
---
|
||
|
||
## 设计要点
|
||
|
||
### 技术栈
|
||
|
||
- 独立 Web 应用：React + Vite + Ant Design（与 `apps/admin-web/` 同技术栈）
|
||
- 部署路径：`apps/tenant-admin/`
|
||
- 后端复用 `apps/backend/` 的 FastAPI，新增租户管理路由模块
|
||
|
||
### 登录体系
|
||
|
||
- 独立凭据：每个租户有若干管理员账号（用户名+密码）
|
||
- 租户级管理员：可管理租户下所有店铺
|
||
- 店铺级管理员：只能管理指定店铺
|
||
- 与系统管理后台（`apps/admin-web/`）完全隔离
|
||
|
||
### Excel 4 种模板
|
||
|
||
#### 1. 财务支出（按月）
|
||
|
||
| 列名 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| 月份 | YYYY-MM | 是 | 提交月份 |
|
||
| 支出类别 | 文本 | 是 | 房租/水电/物业/食品饮料进货/耗材/报销/固定人员工资/其他费用 |
|
||
| 金额 | 数值(2) | 是 | 支出金额 |
|
||
| 备注 | 文本 | 否 | |
|
||
|
||
主键：月份 + 支出类别
|
||
|
||
#### 2. 团购平台收入（按月）
|
||
|
||
| 列名 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| 月份 | YYYY-MM | 是 | |
|
||
| 平台名称 | 文本 | 是 | |
|
||
| 收入金额 | 数值(2) | 是 | |
|
||
| 备注 | 文本 | 否 | |
|
||
|
||
主键：月份 + 平台名称
|
||
|
||
#### 3. 助教奖罚（按月）
|
||
|
||
| 列名 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| 月份 | YYYY-MM | 是 | |
|
||
| 助教姓名 | 文本 | 是 | |
|
||
| 助教编号 | 文本 | 是 | |
|
||
| 类型 | 文本 | 是 | 扣款/奖金 |
|
||
| 金额 | 数值(2) | 是 | |
|
||
| 原因 | 文本 | 是 | |
|
||
|
||
主键：月份 + 助教姓名 + 助教编号 + 类型 + 原因（同一助教同月可多笔）
|
||
|
||
#### 4. 充值业绩归属（按月）
|
||
|
||
| 列名 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| 充值日期 | YYYY-MM-DD | 是 | |
|
||
| 会员名称 | 文本 | 是 | |
|
||
| 充值金额 | 数值(2) | 是 | |
|
||
| 归属助教 | 文本 | 是 | |
|
||
| 奖励金额 | 数值(2) | 是 | |
|
||
|
||
主键：充值日期 + 会员名称 + 归属助教
|
||
|
||
### 冲突处理流程
|
||
|
||
```
|
||
上传 Excel → 后端解析+校验 → 返回校验结果
|
||
├── 无冲突 → 直接写入
|
||
└── 有冲突 → 返回冲突列表（旧值 vs 新值）
|
||
→ 前端展示 diff 交互
|
||
→ 用户逐条选择"替换"或"保留"
|
||
→ 提交确认 → 后端按选择写入
|
||
```
|
||
|
||
### 新建表
|
||
|
||
```
|
||
biz.salary_adjustments
|
||
- id, site_id, assistant_id, assistant_name, assistant_number
|
||
- salary_month, adjustment_type (deduction/bonus)
|
||
- amount, reason
|
||
- upload_batch_id, created_at
|
||
|
||
biz.excel_upload_log
|
||
- id, site_id, upload_type (expense/platform_income/salary_adj/recharge_commission)
|
||
- file_name, uploaded_by, row_count
|
||
- conflict_count, resolved_count
|
||
- status (pending/confirmed/failed)
|
||
- created_at
|
||
```
|
||
|
||
---
|
||
|
||
## 任务清单
|
||
|
||
- [ ] T1：创建 `apps/tenant-admin/` 项目骨架（React + Vite + Ant Design）
|
||
- [ ] T2：实现租户管理员登录（独立凭据）
|
||
- [ ] T3：实现用户审核页面（申请列表 + 状态筛选 + 关联建议 + 审核操作）
|
||
- [ ] T4：实现用户管理页面（用户列表 + 身份编辑 + 店铺归属）
|
||
- [ ] T5：创建 `biz.salary_adjustments` + `biz.excel_upload_log` 表
|
||
- [ ] T6：实现 Excel 上传后端（解析 + 校验 + 冲突检测）
|
||
- [ ] T7：实现 Excel 上传前端（模板下载 + 上传 + diff 交互 + 确认）
|
||
- [ ] T8：实现 4 种 Excel 模板的校验规则
|
||
- [ ] T9：实现人员姓名+编号匹配校验（同时对照 `dim_assistant` 助教表和 `dim_staff` + `dim_staff_ex` 员工信息表）
|