在前后端开发联调前 的提交20260223

.kiro/specs/etl-staff-dimension/requirements.md

@@ -0,0 +1,82 @@
+# 需求文档：ETL 员工维度表（staff_info）
+
+## 概述
+
+为飞球 ETL 连接器新增"员工"维度表，从上游 `SearchSystemStaffInfo` API 抓取球房员工数据，经 ODS 落地后清洗装载至 DWD 层，走 SCD2 缓慢变化维度。
+
+## 用户故事
+
+### US-1：API 对接与 ODS 落地
+作为 ETL 开发者，我需要将 `SearchSystemStaffInfo` API 融入现有 API 请求框架，并将原始数据落地到 ODS 层，以便后续清洗使用。
+
+验收标准：
+- 1.1 在 `ODS_TASK_SPECS` 中新增 `ODS_STAFF_INFO` 任务规格，endpoint 为 `/PersonnelManagement/SearchSystemStaffInfo`
+- 1.2 API 请求体包含必要的筛选参数（`workStatusEnum`、`staffIdentity` 等），使用现有 `APIClient.iter_paginated` 分页机制
+- 1.3 ODS 表 `ods.staff_info_master` 包含 API 返回的所有业务字段 + ETL 元数据列（`content_hash`、`source_file`、`fetched_at`、`payload`）
+- 1.4 任务配置为 `snapshot_mode=FULL_TABLE`（全量快照，无时间窗口），`requires_window=False`
+- 1.5 在 `DEFAULT_LIST_KEYS` 中添加 `staffProfiles`（API 响应的列表键名）
+- 1.6 在 `ENABLED_ODS_CODES` 中注册 `ODS_STAFF_INFO`
+
+### US-2：DWD 维度表设计与 SCD2 装载
+作为数据分析师，我需要一张清洗后的员工维度表，以便在 DWS 汇总层关联员工信息。
+
+验收标准：
+- 2.1 创建 `dwd.dim_staff` 主表，包含核心业务字段（员工 ID、姓名、手机号、角色、门店、在职状态等）+ SCD2 列
+- 2.2 创建 `dwd.dim_staff_ex` 扩展表，包含次要/低频变更字段 + SCD2 列
+- 2.3 在 `DwdLoadTask.TABLE_MAP` 中注册 `dwd.dim_staff` → `ods.staff_info_master` 和 `dwd.dim_staff_ex` → `ods.staff_info_master` 的映射
+- 2.4 在 `DwdLoadTask.FACT_MAPPINGS` 中配置字段映射（ODS 列名 → DWD 列名，含必要的类型转换）
+- 2.5 DWD 装载走 SCD2 合并路径，变更检测正常工作
+
+### US-3：DDL 创建与归档
+作为 DBA，我需要 ODS 和 DWD 层的 DDL 被正确创建并归档到项目文档中。
+
+验收标准：
+- 3.1 编写 ODS 层 DDL（`ods.staff_info_master`），在测试库执行
+- 3.2 编写 DWD 层 DDL（`dwd.dim_staff`、`dwd.dim_staff_ex`），在测试库执行
+- 3.3 DDL 归档至 `docs/database/ddl/etl_feiqiu__ods.sql` 和 `docs/database/ddl/etl_feiqiu__dwd.sql`
+- 3.4 编写迁移脚本至 `db/etl_feiqiu/migrations/`（日期前缀）
+
+### US-4：文档增补
+作为团队成员，我需要所有相关文档同步更新，以便理解新增的数据流。
+
+验收标准：
+- 4.1 新增 ODS mapping 文档：`apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_SearchSystemStaffInfo_staff_info_master.md`
+- 4.2 新增 ODS BD_manual 文档：`apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_staff_info_master.md`
+- 4.3 新增 DWD BD_manual 文档：`apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff.md`
+- 4.4 更新 `apps/etl/connectors/feiqiu/docs/database/README.md`，增加员工表条目
+- 4.5 更新 `apps/etl/connectors/feiqiu/docs/etl_tasks/ods_tasks.md`，增加 ODS_STAFF_INFO 任务说明
+- 4.6 更新 `docs/database/README.md`，增加员工相关表的条目
+- 4.7 新增 DWD BD_manual 扩展表文档：`apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff_ex.md`（如有扩展表）
+
+## API 信息
+
+| 属性 | 值 |
+|------|-----|
+| URL | `https://pc.ficoo.vip/apiprod/admin/v1/PersonnelManagement/SearchSystemStaffInfo` |
+| 方法 | POST |
+| 端点路径 | `/PersonnelManagement/SearchSystemStaffInfo` |
+| 认证 | Bearer Token（标准飞球 API 认证） |
+| 分页 | `page` + `limit`（与现有接口一致） |
+
+### 请求体参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| workStatusEnum | int | 0 | 在职状态筛选（0=全部） |
+| dingTalkSynced | int | 0 | 钉钉同步状态（0=全部） |
+| staffIdentity | int | 0 | 员工身份筛选（0=全部） |
+| rankId | int | 0 | 职级筛选（0=全部） |
+| criticismStatus | int | 0 | 批评状态（0=全部） |
+| signStatus | int | -1 | 签约状态（-1=全部） |
+| page | int | 1 | 页码 |
+| limit | int | 50 | 每页条数 |
+
+## 技术约束
+
+- 员工表为维度表，DWD 层走 SCD2
+- ODS 使用 `SnapshotMode.FULL_TABLE`（全量快照软删除）
+- 不需要时间窗口（`requires_window=False`，`time_fields=None`）
+- 主键为 `id`（员工 ID）
+- API 响应结构已确认：`data.staffProfiles` 为列表键，`data.total` 为总数
+- 员工表与助教表（`assistant_accounts_master`）是完全独立的实体
+- DWD 层拆分为主表（`dim_staff`）+ 扩展表（`dim_staff_ex`）