# 需求文档 — NS4.1 + P16：Admin-Web 管理后台增强

## 简介

本 Spec 合并两个独立需求：NS4.1（租户管理员页面重构 + 项目级注册体系）和 P16（调度任务最小运行间隔机制）。两者均为 admin-web 管理后台的功能增强，改动文件无重叠，合并执行以减少上下文切换。

### 合并理由

- 两者都是 admin-web 后台功能迭代，共享同一前端项目（`apps/admin-web/`）和后端项目（`apps/backend/`）
- NS4.1 改动集中在租户管理员页面（`TenantAdmins/`）+ 新建注册体系路由，P16 改动集中在调度任务页面（`ScheduleTab.tsx`）+ 调度器逻辑
- 改动文件完全不重叠，合并不增加冲突风险
- 共享收尾流程（DDL 合并、BD 手册、文档同步）

### 依赖

- NS4（租户管理后台基础设施）— `tenant-admin-web` spec 已完成
- P3（用户认证体系）— `03-miniapp-auth-system` spec 已完成

### 来源文档（权威参考）

实施过程中如遇细节不明确，应优先查阅以下 PRD 原文：

- `docs/prd/Neo_Specs/NS4.1-tenant-admin-redesign.md` — NS4.1 PRD 主文档（数据模型 DDL、页面布局、接口设计、迁移步骤、边界条件）
- `docs/prd/specs/P16-task-min-run-interval.md` — P16 PRD 主文档（调度器逻辑、API 扩展、前端变更、边界条件）

### 不在本 spec 范围

- P15（AI 监控后台 + 测试重建 + 回填）— 单独 Spec
- 多连接器完整实现（仅预留 `biz.connectors` 表结构）
- `dwd.dim_site` 物理迁移（保留在 `dwd` schema）
- 租户管理员自助注册
- 简写ID 自动生成
- ETL 任务注册机制修改（`TaskMeta`/`TaskRegistry`）
- 批量 seed SQL 设定初始间隔值

## 术语表

- **admin-web**：系统管理后台（`apps/admin-web/`），面向系统管理员
- **tenant-admin**：租户管理后台（`apps/tenant-admin/`），面向租户管理员
- **biz.connectors**：连接器注册表，记录接入的上游 SaaS 系统
- **biz.tenants**：租户注册表，连接器下的租户
- **biz.sites**：店铺注册表，合并原 `auth.site_code_mapping`
- **biz.site_code_history**：简写ID 变更历史表
- **site_code**：店铺简写ID，6 位字符（3+3 格式，如 `LLQ001`）
- **min_run_interval**：调度任务最小运行间隔，任务开始执行后的最小等待时间
- **scheduled_tasks**：调度任务表（`public.scheduled_tasks`），存储 ETL 调度配置
- **scheduler.py**：调度器核心逻辑，每 30 秒轮询到期任务

## 需求

### 模块 A：NS4.1 — 租户管理员页面重构 + 项目级注册体系

#### 需求 A1：项目级注册体系 — 连接器/租户/店铺三级表

**用户故事：** 作为系统管理员，我希望建立「连接器 → 租户 → 店铺」三级注册体系，以便统一管理上游 SaaS 系统、租户和店铺的关系，并为简写ID 提供归属。

##### 验收标准

1. THE Backend SHALL 在 `biz` schema 新建 `connectors` 表（id, connector_key UNIQUE, display_name, is_active, created_at），初始数据插入 `('feiqiu', '飞球')`
2. THE Backend SHALL 在 `biz` schema 新建 `tenants` 表（id, connector_id FK, tenant_id BIGINT, tenant_name, is_active, created_at, updated_at），UNIQUE(connector_id, tenant_id)
3. THE Backend SHALL 在 `biz` schema 新建 `sites` 表（id, tenant_id FK, site_id BIGINT UNIQUE, site_name, site_code VARCHAR(6) UNIQUE, site_label, is_active, created_at, updated_at）
4. THE Backend SHALL 在 `biz` schema 新建 `site_code_history` 表（id, site_id BIGINT, site_code VARCHAR(6) UNIQUE, is_current BOOLEAN, created_at, retired_at）
5. THE Backend SHALL 将 `auth.site_code_mapping` 中真实数据（`tenant_id IS NOT NULL`）迁移到 `biz.sites`，并为已有 `site_code` 创建 `site_code_history` 记录（`is_current=true`）
6. THE Backend SHALL 在迁移完成并验证后，将 `auth.site_code_mapping` 重命名为 `auth._archived_site_code_mapping`

#### 需求 A1b：数据迁移后初始同步

**用户故事：** 作为系统管理员，我希望迁移完成后立即运行一次 ETL 同步，补充 `biz.sites` 中缺失的店铺（`dwd.dim_site` 中有但 `auth.site_code_mapping` 中没有的），确保注册体系数据完整。

##### 验收标准

1. THE Backend SHALL 在数据迁移（A1）完成后、代码切换（A6）之前，执行一次店铺同步（复用 A5 的同步逻辑），将 `dwd.dim_site`（`scd2_is_current=1`）中存在但 `biz.sites` 中不存在的店铺补充插入
2. THE Backend SHALL 在初始同步完成后输出同步结果（新增数/更新数），供验证使用

#### 需求 A2：租户/店铺管理 API

**用户故事：** 作为系统管理员，我希望通过 API 查询租户列表和店铺列表，以便在创建管理员时选择所属租户和管辖门店。

##### 验收标准

1. THE Backend SHALL 实现 `GET /api/admin/tenants` 端点，返回所有活跃租户（含连接器名称）
2. THE Backend SHALL 实现 `GET /api/admin/tenants/{tenant_id}/sites` 端点，返回指定租户下所有活跃店铺（含当前 site_code）
3. THE Backend SHALL 实现 `DELETE /api/admin/tenant-admins/{id}` 端点，软删除管理员（`is_active=false`）
4. THE Backend SHALL 实现 `PUT /api/admin/sites/{site_id}/site-code` 端点，设置/修改店铺简写ID
5. THE Backend SHALL 实现 `GET /api/admin/sites/{site_id}/site-code-history` 端点，查看简写ID 变更历史
6. THE Backend SHALL 修改 `POST /api/admin/tenant-admins` 端点，创建时 `tenant_id` 从 `biz.tenants` 选择，`managed_site_ids` 从 `biz.sites` 选择
7. THE Backend SHALL 修改 `GET /api/admin/tenant-admins` 端点，默认只返回 `is_active=true`，增加 `include_inactive` 参数
8. THE Backend SHALL 修改 `PATCH /api/admin/tenant-admins/{id}` 端点，支持修改 `username`（需校验全局唯一性，冲突返回 409）

#### 需求 A3：简写ID 管理逻辑

**用户故事：** 作为系统管理员，我希望在管理后台设置和修改店铺简写ID，并保留变更历史，以便保护已提交但未审核的用户申请。

##### 验收标准

1. WHEN 修改简写ID 时，THE Backend SHALL 在事务内执行：旧 code 标记 `is_current=false` + `retired_at=NOW()`，新 code 插入 `site_code_history`（`is_current=true`），更新 `biz.sites.site_code`
2. THE Backend SHALL 校验新 code 格式（6 位，3+3 模式，统一大写存储）和全局唯一性（含 `biz.sites.site_code` + `biz.site_code_history.site_code`）
3. WHEN 旧 code 有未审核申请引用（`auth.user_applications WHERE site_code = :old_code AND status = 'pending'`）时，THE Backend SHALL 保留历史记录不删除
4. WHEN 旧 code 无任何申请引用时，THE Backend SHALL 从 `biz.site_code_history` 中删除该条记录

#### 需求 A4：租户管理员页面重构（admin-web）

**用户故事：** 作为系统管理员，我希望在 admin-web 中通过改进的界面管理租户管理员，支持 2 步创建流程、软删除和简写ID 管理。

##### 验收标准

1. THE admin-web SHALL 重构租户管理员列表页，新增「删除」操作按钮（二次确认 → 软删除），默认只显示活跃记录，可选「显示已禁用」开关
2. THE admin-web SHALL 实现 2 步创建流程：第 1 步选择租户（下拉 `biz.tenants`）+ 输入账号信息 + 选择管辖门店（`biz.sites`）；第 2 步可选设置简写ID
3. THE admin-web SHALL 在编辑弹窗中增加「管理简写ID」区域，展示该租户下所有店铺及其当前 code，支持修改；编辑时所属租户（`tenant_id`）为只读不可修改；用户名（`username`）可修改（需校验唯一性）
4. THE admin-web SHALL 新增简写ID 管理弹窗，展示变更历史，支持修改操作
5. THE admin-web SHALL 新增 `src/api/registry.ts` 封装租户/店铺列表 API 调用

#### 需求 A5：ETL 店铺信息增量同步

**用户故事：** 作为系统管理员，我希望 ETL 完成后能自动同步店铺信息到业务库，以便 `biz.sites` 中的店铺名称和标签保持最新。

##### 验收标准

1. THE Backend SHALL 实现店铺同步逻辑：通过 FDW 读取 ETL 库 `dwd.dim_site`（`scd2_is_current=1`），对比 `biz.sites`，新增店铺 INSERT（`site_code` 留空），名称/标签变更 UPDATE
2. THE Backend SHALL 不删除已有店铺记录（即使上游标记为关闭）
3. THE Backend SHALL 支持手动触发同步（管理后台按钮或 API 端点）
4. THE Backend SHALL 支持定时触发同步（随 ETL 日常调度，DWD 层完成后通过内部 API 触发）

#### 需求 A6：后端代码切换 — site_code 查询源

**用户故事：** 作为后端开发者，我希望所有读取 `auth.site_code_mapping` 的代码切换到 `biz.sites` + `biz.site_code_history`，以便完成数据迁移。

##### 验收标准

1. THE Backend SHALL 将所有读取 `auth.site_code_mapping` 的查询切换到 `biz.sites`
2. THE 小程序端 SHALL 将用户申请时的 `site_code` 查询从 `auth.site_code_mapping` 切换到 `biz.sites` + `biz.site_code_history`
3. THE Backend SHALL 确保切换后所有现有功能（用户申请、关联建议匹配等）正常工作

---

### 模块 B：P16 — 调度任务最小运行间隔机制

#### 需求 B1：scheduled_tasks 表扩展

**用户故事：** 作为管理员，我希望为每个调度任务设置最小运行间隔，使任务即使调度到期也不会在间隔内重复执行。

##### 验收标准

1. THE Backend SHALL 在 `scheduled_tasks` 表新增 `min_run_interval_value`（INTEGER DEFAULT 0）、`min_run_interval_unit`（VARCHAR(20) DEFAULT 'minutes'）、`last_success_at`（TIMESTAMPTZ NULL）3 个字段
2. THE Backend SHALL 确保 `min_run_interval_value = 0` 表示无限制，与现有行为完全一致（向后兼容）

#### 需求 B2：调度器核心逻辑 — 并发检查 + 间隔检查

**用户故事：** 作为管理员，我希望调度器在轮询时自动检查最小间隔和并发状态，避免任务重复执行或并发执行。

##### 验收标准

1. THE scheduler SHALL 在 `check_and_enqueue()` 中新增并发检查：若 `last_status = 'running'`，跳过本次入队，日志记录 `skipped_concurrent`
2. THE scheduler SHALL 在 `check_and_enqueue()` 中新增间隔检查：若 `min_run_interval_value > 0` 且 `now() - last_run_at < min_interval_seconds`，跳过本次执行并推进 `next_run_at`，日志记录 `skipped_interval`
3. WHEN `last_run_at IS NULL`（从未执行）时，THE scheduler SHALL 跳过间隔检查，正常执行
4. THE scheduler SHALL 在任务成功完成时同时更新 `last_success_at = NOW()`，失败时不更新 `last_success_at`
5. THE scheduler SHALL 实现 `_convert_interval_to_seconds(value, unit)` 辅助函数，支持 `minutes`/`hours`/`days` 单位

#### 需求 B3：API 扩展 — 创建/更新/手动执行

**用户故事：** 作为管理员，我希望通过 API 配置最小运行间隔，并在必要时强制执行任务。

##### 验收标准

1. THE Backend SHALL 在 `POST /api/schedules` 和 `PUT /api/schedules/{id}` 端点的请求体中新增 `min_run_interval_value`（int, default=0）和 `min_run_interval_unit`（str, default='minutes'）
2. THE Backend SHALL 在 `GET /api/schedules` 响应中新增 `min_run_interval_value`、`min_run_interval_unit`、`last_success_at` 字段
3. THE Backend SHALL 在 `POST /api/schedules/{id}/run` 端点新增 `force: bool = False` 查询参数
4. WHEN `force=true` 时，THE Backend SHALL 绕过最小间隔和并发检查，直接入队执行
5. WHEN `force=false` 且间隔未到时，THE Backend SHALL 返回 409 Conflict，提示"最小运行间隔未到，距下次可执行还有 X 分钟"
6. WHEN `force=false` 且任务正在运行时，THE Backend SHALL 返回 409 Conflict，提示"任务正在执行中"

#### 需求 B4：Admin Web 前端 — ScheduleTab 扩展

**用户故事：** 作为管理员，我希望在调度任务管理界面中看到和配置最小运行间隔。

##### 验收标准

1. THE admin-web SHALL 在创建/编辑调度任务表单中新增「最小运行间隔」行：`InputNumber`（数值）+ `Select`（单位：分钟/小时/天），数值为 0 时显示提示"无限制"
2. THE admin-web SHALL 在任务列表表格中新增「最小间隔」列（显示如"10 天"、"无限制"）和「上次成功」列（相对时间）
3. THE admin-web SHALL 在手动执行确认框中新增「强制执行（忽略最小间隔）」勾选项，默认不勾选
4. WHEN 勾选强制执行时，THE admin-web SHALL 调用 `POST /api/schedules/{id}/run?force=true`