4.5 KiB
4.5 KiB
需求文档：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）