83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 需求文档：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`）
|