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

apps/etl/connectors/feiqiu/docs/architecture/ods_taskspec_refactor_proposal.md

@@ -64,7 +64,7 @@
 - 为全部 23 张 ODS 表创建 `(业务主键, fetched_at DESC)` 复合索引
 - 使用 `CREATE INDEX CONCURRENTLY IF NOT EXISTS`，保证幂等且不锁表
 - 索引命名规范：`idx_ods_{table_name}_latest`
-- 同步更新 `db/etl_feiqiu/schemas/ods.sql` 中的索引定义
+- 同步更新 `docs/database/ddl/etl_feiqiu__ods.sql` 中的索引定义
 
 ### 用途
 

apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff.md

@@ -0,0 +1,44 @@
+# dim_staff 员工档案主表
+
+> 生成时间：2026-02-23
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | dwd |
+| 表名 | dim_staff |
+| 主键 | staff_id, scd2_start_time |
+| 扩展表 | dim_staff_ex |
+| ODS 来源 | ods.staff_info_master |
+| 说明 | 员工档案维度主表（SCD2），包含核心业务字段 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
+|------|--------|------|------|------|------|
+| 1 | staff_id | BIGINT | NO | PK | 员工唯一标识（映射自 ODS id） |
+| 2 | staff_name | TEXT | YES | | 员工姓名 |
+| 3 | alias_name | TEXT | YES | | 别名 |
+| 4 | mobile | TEXT | YES | | 手机号 |
+| 5 | gender | INTEGER | YES | | 性别 |
+| 6 | job | TEXT | YES | | 职位（店长/主管/教练/收银员等） |
+| 7 | tenant_id | BIGINT | YES | | 租户 ID |
+| 8 | site_id | BIGINT | YES | | 门店 ID |
+| 9 | system_role_id | INTEGER | YES | | 系统角色 ID |
+| 10 | staff_identity | INTEGER | YES | | 员工身份类型 |
+| 11 | status | INTEGER | YES | | 账号状态 |
+| 12 | leave_status | INTEGER | YES | | 在职状态（0=在职，1=离职） |
+| 13 | entry_time | TIMESTAMPTZ | YES | | 入职时间 |
+| 14 | resign_time | TIMESTAMPTZ | YES | | 离职时间 |
+| 15 | is_delete | INTEGER | YES | | 删除标记 |
+| 16 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
+| 17 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
+| 18 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
+| 19 | scd2_version | INTEGER | YES | | 版本号 |
+
+## 与其他表的关系
+
+- 扩展表：`dwd.dim_staff_ex`（次要/低频变更字段）
+- ODS 来源：`ods.staff_info_master`
+- 与助教维度表（`dim_assistant`）是完全独立的实体

apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff_ex.md

@@ -0,0 +1,51 @@
+# dim_staff_ex 员工档案扩展表
+
+> 生成时间：2026-02-23
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | dwd |
+| 表名 | dim_staff_ex |
+| 主键 | staff_id, scd2_start_time |
+| 主表 | dim_staff |
+| ODS 来源 | ods.staff_info_master |
+| 说明 | 员工档案维度扩展表（SCD2），包含次要/低频变更字段 |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
+|------|--------|------|------|------|------|
+| 1 | staff_id | BIGINT | NO | PK | 员工唯一标识（映射自 ODS id） |
+| 2 | avatar | TEXT | YES | | 头像 URL |
+| 3 | job_num | TEXT | YES | | 工号 |
+| 4 | account_status | INTEGER | YES | | 账号启用状态 |
+| 5 | rank_id | INTEGER | YES | | 职级 ID |
+| 6 | rank_name | TEXT | YES | | 职级名称 |
+| 7 | new_rank_id | INTEGER | YES | | 新职级 ID |
+| 8 | new_staff_identity | INTEGER | YES | | 新员工身份 |
+| 9 | is_reserve | INTEGER | YES | | 预约标记 |
+| 10 | shop_name | TEXT | YES | | 门店名称 |
+| 11 | site_label | TEXT | YES | | 门店标签 |
+| 12 | tenant_org_id | BIGINT | YES | | 租户组织 ID |
+| 13 | system_user_id | BIGINT | YES | | 系统用户 ID |
+| 14 | cashier_point_id | BIGINT | YES | | 收银点 ID |
+| 15 | cashier_point_name | TEXT | YES | | 收银点名称 |
+| 16 | group_id | BIGINT | YES | | 分组 ID |
+| 17 | group_name | TEXT | YES | | 分组名称 |
+| 18 | staff_profile_id | BIGINT | YES | | 员工档案 ID |
+| 19 | auth_code | TEXT | YES | | 授权码 |
+| 20 | auth_code_create | TIMESTAMPTZ | YES | | 授权码创建时间 |
+| 21 | ding_talk_synced | INTEGER | YES | | 钉钉同步状态 |
+| 22 | salary_grant_enabled | INTEGER | YES | | 工资发放启用 |
+| 23 | entry_type | INTEGER | YES | | 入职类型 |
+| 24 | entry_sign_status | INTEGER | YES | | 入职签约状态 |
+| 25 | resign_sign_status | INTEGER | YES | | 离职签约状态 |
+| 26 | criticism_status | INTEGER | YES | | 批评状态 |
+| 27 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
+| 28 | user_roles | JSONB | YES | | 用户角色列表 |
+| 29 | scd2_start_time | TIMESTAMPTZ | NO | PK | SCD2 版本生效时间 |
+| 30 | scd2_end_time | TIMESTAMPTZ | YES | | SCD2 版本失效时间 |
+| 31 | scd2_is_current | INTEGER | YES | | 当前版本标记 |
+| 32 | scd2_version | INTEGER | YES | | 版本号 |

apps/etl/connectors/feiqiu/docs/database/ODS/main/BD_manual_staff_info_master.md

@@ -0,0 +1,70 @@
+# staff_info_master 员工档案主表
+
+> 生成时间：2026-02-23
+
+## 表信息
+
+| 属性 | 值 |
+|------|-----|
+| Schema | ods |
+| 表名 | staff_info_master |
+| 主键 | id |
+| 数据来源 | SearchSystemStaffInfo API |
+| 快照模式 | FULL_TABLE |
+| 说明 | 员工档案主数据（店长、主管、教练、收银员等） |
+
+## 字段说明
+
+| 序号 | 字段名 | 类型 | 可空 | 说明 |
+|------|--------|------|------|------|
+| 1 | id | BIGINT | NO | 员工主键 ID |
+| 2 | tenant_id | BIGINT | YES | 租户 ID |
+| 3 | site_id | BIGINT | YES | 门店 ID |
+| 4 | tenant_org_id | BIGINT | YES | 租户组织 ID |
+| 5 | system_user_id | BIGINT | YES | 系统用户 ID |
+| 6 | staff_name | TEXT | YES | 员工姓名 |
+| 7 | alias_name | TEXT | YES | 别名 |
+| 8 | mobile | TEXT | YES | 手机号 |
+| 9 | avatar | TEXT | YES | 头像 URL |
+| 10 | gender | INTEGER | YES | 性别（3=未知） |
+| 11 | job | TEXT | YES | 职位（店长/主管/教练/收银员等） |
+| 12 | job_num | TEXT | YES | 工号 |
+| 13 | staff_identity | INTEGER | YES | 员工身份类型 |
+| 14 | status | INTEGER | YES | 账号状态 |
+| 15 | account_status | INTEGER | YES | 账号启用状态 |
+| 16 | system_role_id | INTEGER | YES | 系统角色 ID |
+| 17 | rank_id | INTEGER | YES | 职级 ID |
+| 18 | rank_name | TEXT | YES | 职级名称 |
+| 19 | new_rank_id | INTEGER | YES | 新职级 ID |
+| 20 | new_staff_identity | INTEGER | YES | 新员工身份 |
+| 21 | leave_status | INTEGER | YES | 在职状态（0=在职，1=离职） |
+| 22 | entry_time | TIMESTAMP | YES | 入职时间 |
+| 23 | resign_time | TIMESTAMP | YES | 离职时间 |
+| 24 | create_time | TIMESTAMP | YES | 创建时间 |
+| 25 | is_delete | INTEGER | YES | 删除标记 |
+| 26 | is_reserve | INTEGER | YES | 预约标记 |
+| 27 | shop_name | TEXT | YES | 门店名称 |
+| 28 | site_label | TEXT | YES | 门店标签 |
+| 29 | cashier_point_id | BIGINT | YES | 收银点 ID |
+| 30 | cashier_point_name | TEXT | YES | 收银点名称 |
+| 31 | group_id | BIGINT | YES | 分组 ID |
+| 32 | group_name | TEXT | YES | 分组名称 |
+| 33 | staff_profile_id | BIGINT | YES | 员工档案 ID |
+| 34 | auth_code | TEXT | YES | 授权码 |
+| 35 | auth_code_create | TIMESTAMP | YES | 授权码创建时间 |
+| 36 | ding_talk_synced | INTEGER | YES | 钉钉同步状态 |
+| 37 | salary_grant_enabled | INTEGER | YES | 工资发放启用 |
+| 38 | entry_type | INTEGER | YES | 入职类型 |
+| 39 | entry_sign_status | INTEGER | YES | 入职签约状态 |
+| 40 | resign_sign_status | INTEGER | YES | 离职签约状态 |
+| 41 | criticism_status | INTEGER | YES | 批评状态 |
+| 42 | user_roles | JSONB | YES | 用户角色列表 |
+| 43 | content_hash | TEXT | NO | 记录内容哈希 |
+| 44 | source_file | TEXT | YES | 来源文件路径 |
+| 45 | fetched_at | TIMESTAMPTZ | YES | 抓取时间 |
+| 46 | payload | JSONB | NO | 原始 JSON |
+
+## 与其他表的关系
+
+- 员工表与助教表（`assistant_accounts_master`）是完全独立的实体
+- 下游：`dwd.dim_staff`（主表）、`dwd.dim_staff_ex`（扩展表）

apps/etl/connectors/feiqiu/docs/database/ODS/mappings/mapping_SearchSystemStaffInfo_staff_info_master.md

@@ -0,0 +1,80 @@
+# 员工档案（SearchSystemStaffInfo） → staff_info_master 字段映射
+
+> 生成时间：2026-02-23
+
+## 端点信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PersonnelManagement/SearchSystemStaffInfo` |
+| 请求方法 | POST |
+| ODS 对应表 | `ods.staff_info_master` |
+| JSON 数据路径 | `data.staffProfiles` |
+| 快照模式 | FULL_TABLE（全量快照） |
+
+## 请求参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| workStatusEnum | int | 0 | 在职状态筛选（0=全部） |
+| dingTalkSynced | int | 0 | 钉钉同步状态（0=全部） |
+| staffIdentity | int | 0 | 员工身份筛选（0=全部） |
+| rankId | int | 0 | 职级筛选（0=全部） |
+| criticismStatus | int | 0 | 批评状态（0=全部） |
+| signStatus | int | -1 | 签约状态（-1=全部） |
+
+## 字段映射
+
+| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
+|-----------|----------|----------|------|
+| id | id | int→BIGINT | 员工主键 ID |
+| tenant_id | tenant_id | int→BIGINT | 租户 ID |
+| site_id | site_id | int→BIGINT | 门店 ID |
+| tenant_org_id | tenant_org_id | int→BIGINT | 租户组织 ID |
+| system_user_id | system_user_id | int→BIGINT | 系统用户 ID |
+| staff_name | staff_name | string→TEXT | 员工姓名 |
+| alias_name | alias_name | string→TEXT | 别名 |
+| mobile | mobile | string→TEXT | 手机号 |
+| avatar | avatar | string→TEXT | 头像 URL |
+| gender | gender | int→INTEGER | 性别（3=未知） |
+| job | job | string→TEXT | 职位名称（店长/主管/教练等） |
+| job_num | job_num | string→TEXT | 工号 |
+| staff_identity | staff_identity | int→INTEGER | 员工身份类型 |
+| status | status | int→INTEGER | 账号状态 |
+| account_status | account_status | int→INTEGER | 账号启用状态 |
+| system_role_id | system_role_id | int→INTEGER | 系统角色 ID |
+| rank_id | rank_id | int→INTEGER | 职级 ID |
+| rankName | rank_name | string→TEXT | 职级名称（驼峰→蛇形） |
+| new_rank_id | new_rank_id | int→INTEGER | 新职级 ID |
+| new_staff_identity | new_staff_identity | int→INTEGER | 新员工身份 |
+| leave_status | leave_status | int→INTEGER | 在职状态（0=在职） |
+| entry_time | entry_time | string→TIMESTAMP | 入职时间 |
+| resign_time | resign_time | string→TIMESTAMP | 离职时间 |
+| create_time | create_time | string→TIMESTAMP | 创建时间 |
+| is_delete | is_delete | int→INTEGER | 删除标记 |
+| is_reserve | is_reserve | int→INTEGER | 预约标记 |
+| shop_name | shop_name | string→TEXT | 门店名称 |
+| site_label | site_label | string→TEXT | 门店标签 |
+| cashierPointId | cashier_point_id | int→BIGINT | 收银点 ID（驼峰→蛇形） |
+| cashierPointName | cashier_point_name | string→TEXT | 收银点名称（驼峰→蛇形） |
+| groupId | group_id | int→BIGINT | 分组 ID（驼峰→蛇形） |
+| groupName | group_name | string→TEXT | 分组名称（驼峰→蛇形） |
+| staff_profile_id | staff_profile_id | int→BIGINT | 员工档案 ID |
+| auth_code | auth_code | string→TEXT | 授权码 |
+| auth_code_create | auth_code_create | string→TIMESTAMP | 授权码创建时间 |
+| ding_talk_synced | ding_talk_synced | int→INTEGER | 钉钉同步状态 |
+| salary_grant_enabled | salary_grant_enabled | int→INTEGER | 工资发放启用 |
+| entry_type | entry_type | int→INTEGER | 入职类型 |
+| entry_sign_status | entry_sign_status | int→INTEGER | 入职签约状态 |
+| resign_sign_status | resign_sign_status | int→INTEGER | 离职签约状态 |
+| criticism_status | criticism_status | int→INTEGER | 批评状态 |
+| userRoles | user_roles | array→JSONB | 用户角色列表（驼峰→蛇形） |
+
+## ETL 元数据列
+
+| 列名 | 类型 | 说明 |
+|------|------|------|
+| content_hash | TEXT | 记录内容哈希（去重用） |
+| source_file | TEXT | 来源文件路径 |
+| fetched_at | TIMESTAMPTZ | 抓取时间 |
+| payload | JSONB | 原始 JSON 完整保留 |

apps/etl/connectors/feiqiu/docs/database/README.md

@@ -1,230 +1,38 @@
-# BD_Manual — 飞球 ETL 数据库手册
+# 飞球 ETL 数据库手册
 
-> 本文档是 `docs/bd_manual/` 目录的导航索引，涵盖 ODS、DWD、DWS、ETL_Admin 四个数据层的表级文档、字段映射文档和变更记录。
+> 模块专属的表级文档、字段映射、扩展表说明。
+> DDL 基线见项目级 `docs/database/ddl/`，变更记录已归档至 `_archived/`。
 
 ## 目录结构
 
 ```
-docs/bd_manual/
-├── README.md                  ← 本文件（根索引）
-├── ddl_compare_results.md     ← DDL 对比结果汇总
-├── ODS/                       ← 操作数据存储层（ods schema）
-│   ├── main/                  ←   表级文档
-│   ├── mappings/              ←   API JSON → ODS 字段映射文档
-│   └── changes/               ←   变更记录
-├── DWD/                       ← 明细数据层（dwd schema）
-│   ├── main/                  ←   表级文档
-│   ├── Ex/                    ←   扩展表文档（SCD2 维度扩展等）
-│   └── changes/               ←   变更记录
-├── DWS/                       ← 数据服务层（dws schema）
-│   ├── main/                  ←   表级文档
-│   └── changes/               ←   变更记录
-└── ETL_Admin/                 ← ETL 管理层（meta schema）
-    ├── main/                  ←   表级文档
-    └── changes/               ←   变更记录
+database/
+├── ODS/
+│   ├── main/       — ODS 表级文档（BD_manual_*.md）
+│   └── mappings/   — API JSON → ODS 字段映射（mapping_*.md）
+├── DWD/
+│   ├── main/       — DWD 主表文档
+│   └── Ex/         — DWD 扩展表文档
+├── DWS/
+│   └── main/       — DWS 汇总表文档
+├── ETL_Admin/
+│   └── main/       — meta schema 表文档
+└── _archived/      — 过时的变更记录、DDL 对比报告、已删除表文档
 ```
 
-## 文档命名规范
+## 文档类型
 
-| 文档类型 | 命名格式 | 示例 |
-|----------|----------|------|
-| 表级文档 | `BD_manual_{表名}.md` | `BD_manual_member_profiles.md` |
-| 映射文档 | `mapping_{API端点名}_{ODS表名}.md` | `mapping_GetTenantMemberList_member_profiles.md` |
-| 变更记录 | `{YYYYMMDD}_{变更简述}.md` 或 `{YYYY-MM-DD}_{变更简述}.md` | `2026-02-13_ddl_sync_ods.md` |
+| 类型 | 命名规则 | 说明 |
+|------|---------|------|
+| 表级文档 | `BD_manual_{表名}.md` | 字段说明、主键、业务含义 |
+| 扩展表文档 | `BD_manual_{表名}_ex.md` | SCD2 扩展字段、溢出字段 |
+| 字段映射 | `mapping_{API端点}_{ODS表名}.md` | API JSON 字段 → ODS 列的映射关系 |
 
-## ODS 层文档清单（ods）
+## 与项目级文档的关系
 
-### 表级文档（`ODS/main/`）— 共 23 份
-
-| 序号 | 文件名 | 对应表 |
-|------|--------|--------|
-| 1 | `BD_manual_assistant_accounts_master.md` | assistant_accounts_master |
-| 2 | `BD_manual_assistant_cancellation_records.md` | assistant_cancellation_records |
-| 3 | `BD_manual_assistant_service_records.md` | assistant_service_records |
-| 4 | `BD_manual_goods_stock_movements.md` | goods_stock_movements |
-| 5 | `BD_manual_goods_stock_summary.md` | goods_stock_summary |
-| 6 | `BD_manual_group_buy_packages.md` | group_buy_packages |
-| 7 | `BD_manual_group_buy_redemption_records.md` | group_buy_redemption_records |
-| 8 | `BD_manual_member_balance_changes.md` | member_balance_changes |
-| 9 | `BD_manual_member_profiles.md` | member_profiles |
-| 10 | `BD_manual_member_stored_value_cards.md` | member_stored_value_cards |
-| 11 | `BD_manual_payment_transactions.md` | payment_transactions |
-| 12 | `BD_manual_platform_coupon_redemption_records.md` | platform_coupon_redemption_records |
-| 13 | `BD_manual_recharge_settlements.md` | recharge_settlements |
-| 14 | `BD_manual_refund_transactions.md` | refund_transactions |
-| 15 | `BD_manual_settlement_records.md` | settlement_records |
-| 16 | `BD_manual_settlement_ticket_details.md` | settlement_ticket_details |
-| 17 | `BD_manual_site_tables_master.md` | site_tables_master |
-| 18 | `BD_manual_stock_goods_category_tree.md` | stock_goods_category_tree |
-| 19 | `BD_manual_store_goods_master.md` | store_goods_master |
-| 20 | `BD_manual_store_goods_sales_records.md` | store_goods_sales_records |
-| 21 | `BD_manual_table_fee_discount_records.md` | table_fee_discount_records |
-| 22 | `BD_manual_table_fee_transactions.md` | table_fee_transactions |
-| 23 | `BD_manual_tenant_goods_master.md` | tenant_goods_master |
-
-### API→ODS 字段映射文档（`ODS/mappings/`）— 共 23 份
-
-| 序号 | 文件名 | API 端点 → ODS 表 |
-|------|--------|-------------------|
-| 1 | `mapping_GetAbolitionAssistant_assistant_cancellation_records.md` | GetAbolitionAssistant → assistant_cancellation_records |
-| 2 | `mapping_GetAllOrderSettleList_settlement_records.md` | GetAllOrderSettleList → settlement_records |
-| 3 | `mapping_GetGoodsInventoryList_store_goods_master.md` | GetGoodsInventoryList → store_goods_master |
-| 4 | `mapping_GetGoodsSalesList_store_goods_sales_records.md` | GetGoodsSalesList → store_goods_sales_records |
-| 5 | `mapping_GetGoodsStockReport_goods_stock_summary.md` | GetGoodsStockReport → goods_stock_summary |
-| 6 | `mapping_GetMemberCardBalanceChange_member_balance_changes.md` | GetMemberCardBalanceChange → member_balance_changes |
-| 7 | `mapping_GetOfflineCouponConsumePageList_platform_coupon_redemption_records.md` | GetOfflineCouponConsumePageList → platform_coupon_redemption_records |
-| 8 | `mapping_GetOrderAssistantDetails_assistant_service_records.md` | GetOrderAssistantDetails → assistant_service_records |
-| 9 | `mapping_GetOrderSettleTicketNew_settlement_ticket_details.md` | GetOrderSettleTicketNew → settlement_ticket_details |
-| 10 | `mapping_GetPayLogListPage_payment_transactions.md` | GetPayLogListPage → payment_transactions |
-| 11 | `mapping_GetRechargeSettleList_recharge_settlements.md` | GetRechargeSettleList → recharge_settlements |
-| 12 | `mapping_GetRefundPayLogList_refund_transactions.md` | GetRefundPayLogList → refund_transactions |
-| 13 | `mapping_GetSiteTableOrderDetails_table_fee_transactions.md` | GetSiteTableOrderDetails → table_fee_transactions |
-| 14 | `mapping_GetSiteTables_site_tables_master.md` | GetSiteTables → site_tables_master |
-| 15 | `mapping_GetSiteTableUseDetails_group_buy_redemption_records.md` | GetSiteTableUseDetails → group_buy_redemption_records |
-| 16 | `mapping_GetTaiFeeAdjustList_table_fee_discount_records.md` | GetTaiFeeAdjustList → table_fee_discount_records |
-| 17 | `mapping_GetTenantMemberCardList_member_stored_value_cards.md` | GetTenantMemberCardList → member_stored_value_cards |
-| 18 | `mapping_GetTenantMemberList_member_profiles.md` | GetTenantMemberList → member_profiles |
-| 19 | `mapping_QueryGoodsOutboundReceipt_goods_stock_movements.md` | QueryGoodsOutboundReceipt → goods_stock_movements |
-| 20 | `mapping_QueryPackageCouponList_group_buy_packages.md` | QueryPackageCouponList → group_buy_packages |
-| 21 | `mapping_QueryPrimarySecondaryCategory_stock_goods_category_tree.md` | QueryPrimarySecondaryCategory → stock_goods_category_tree |
-| 22 | `mapping_QueryTenantGoods_tenant_goods_master.md` | QueryTenantGoods → tenant_goods_master |
-| 23 | `mapping_SearchAssistantInfo_assistant_accounts_master.md` | SearchAssistantInfo → assistant_accounts_master |
-
-### 变更记录（`ODS/changes/`）
-
-| 文件名 | 说明 |
-|--------|------|
-| `2026-02-13_ddl_sync_ods.md` | DDL 对比同步 — ODS 层 |
-| `20260213_align_ods_with_api.md` | ODS 表结构与 API 对齐 |
-| `20260214_drop_ods_option_name_able_site_transfer.md` | 移除 ODS 冗余字段/表 |
-| `20260214_drop_ods_settlelist.md` | 移除 ODS settle_list 表 |
-
-## DWD 层文档清单（dwd）
-
-### 表级文档（`DWD/main/`）— 共 22 份
-
-| 序号 | 文件名 | 对应表 |
-|------|--------|--------|
-| 1 | `BD_manual_dwd.md` | dwd（层级概览） |
-| 2 | `BD_manual_dim_assistant.md` | dim_assistant |
-| 3 | `BD_manual_dim_goods_category.md` | dim_goods_category |
-| 4 | `BD_manual_dim_groupbuy_package.md` | dim_groupbuy_package |
-| 5 | `BD_manual_dim_member.md` | dim_member |
-| 6 | `BD_manual_dim_member_card_account.md` | dim_member_card_account |
-| 7 | `BD_manual_dim_site.md` | dim_site |
-| 8 | `BD_manual_dim_store_goods.md` | dim_store_goods |
-| 9 | `BD_manual_dim_table.md` | dim_table |
-| 10 | `BD_manual_dim_tenant_goods.md` | dim_tenant_goods |
-| 11 | `BD_manual_dwd_assistant_service_log.md` | dwd_assistant_service_log |
-| 12 | `BD_manual_dwd_assistant_trash_event.md` | dwd_assistant_trash_event |
-| 13 | `BD_manual_dwd_groupbuy_redemption.md` | dwd_groupbuy_redemption |
-| 14 | `BD_manual_dwd_member_balance_change.md` | dwd_member_balance_change |
-| 15 | `BD_manual_dwd_payment.md` | dwd_payment |
-| 16 | `BD_manual_dwd_platform_coupon_redemption.md` | dwd_platform_coupon_redemption |
-| 17 | `BD_manual_dwd_recharge_order.md` | dwd_recharge_order |
-| 18 | `BD_manual_dwd_refund.md` | dwd_refund |
-| 19 | `BD_manual_dwd_settlement_head.md` | dwd_settlement_head |
-| 20 | `BD_manual_dwd_store_goods_sale.md` | dwd_store_goods_sale |
-| 21 | `BD_manual_dwd_table_fee_adjust.md` | dwd_table_fee_adjust |
-| 22 | `BD_manual_dwd_table_fee_log.md` | dwd_table_fee_log |
-
-### 扩展表文档（`DWD/Ex/`）— 共 19 份
-
-| 序号 | 文件名 | 对应扩展表 |
-|------|--------|------------|
-| 1 | `BD_manual_dim_assistant_ex.md` | dim_assistant_ex |
-| 2 | `BD_manual_dim_groupbuy_package_ex.md` | dim_groupbuy_package_ex |
-| 3 | `BD_manual_dim_member_card_account_ex.md` | dim_member_card_account_ex |
-| 4 | `BD_manual_dim_member_ex.md` | dim_member_ex |
-| 5 | `BD_manual_dim_site_ex.md` | dim_site_ex |
-| 6 | `BD_manual_dim_store_goods_ex.md` | dim_store_goods_ex |
-| 7 | `BD_manual_dim_table_ex.md` | dim_table_ex |
-| 8 | `BD_manual_dim_tenant_goods_ex.md` | dim_tenant_goods_ex |
-| 9 | `BD_manual_dwd_assistant_service_log_ex.md` | dwd_assistant_service_log_ex |
-| 10 | `BD_manual_dwd_assistant_trash_event_ex.md` | dwd_assistant_trash_event_ex |
-| 11 | `BD_manual_dwd_groupbuy_redemption_ex.md` | dwd_groupbuy_redemption_ex |
-| 12 | `BD_manual_dwd_member_balance_change_ex.md` | dwd_member_balance_change_ex |
-| 13 | `BD_manual_dwd_platform_coupon_redemption_ex.md` | dwd_platform_coupon_redemption_ex |
-| 14 | `BD_manual_dwd_recharge_order_ex.md` | dwd_recharge_order_ex |
-| 15 | `BD_manual_dwd_refund_ex.md` | dwd_refund_ex |
-| 16 | `BD_manual_dwd_settlement_head_ex.md` | dwd_settlement_head_ex |
-| 17 | `BD_manual_dwd_store_goods_sale_ex.md` | dwd_store_goods_sale_ex |
-| 18 | `BD_manual_dwd_table_fee_adjust_ex.md` | dwd_table_fee_adjust_ex |
-| 19 | `BD_manual_dwd_table_fee_log_ex.md` | dwd_table_fee_log_ex |
-
-### 变更记录（`DWD/changes/`）
-
-| 文件名 | 说明 |
-|--------|------|
-| `2026-02-13_ddl_sync_dwd.md` | DDL 对比同步 — DWD 层 |
-| `20260214_drop_dwd_settle_list.md` | 移除 DWD settle_list 表 |
-
-## DWS 层文档清单（dws）
-
-### 表级文档（`DWS/main/`）— 共 29 份
-
-| 序号 | 文件名 | 对应表 |
-|------|--------|--------|
-| 1 | `BD_manual_cfg_area_category.md` | cfg_area_category |
-| 2 | `BD_manual_cfg_assistant_level_price.md` | cfg_assistant_level_price |
-| 3 | `BD_manual_cfg_bonus_rules.md` | cfg_bonus_rules |
-| 4 | `BD_manual_cfg_index_parameters.md` | cfg_index_parameters |
-| 5 | `BD_manual_cfg_performance_tier.md` | cfg_performance_tier |
-| 6 | `BD_manual_cfg_skill_type.md` | cfg_skill_type |
-| 7 | `BD_manual_dws_assistant_customer_stats.md` | dws_assistant_customer_stats |
-| 8 | `BD_manual_dws_assistant_daily_detail.md` | dws_assistant_daily_detail |
-| 9 | `BD_manual_dws_assistant_finance_analysis.md` | dws_assistant_finance_analysis |
-| 10 | `BD_manual_dws_assistant_monthly_summary.md` | dws_assistant_monthly_summary |
-| 11 | `BD_manual_dws_assistant_recharge_commission.md` | dws_assistant_recharge_commission |
-| 12 | `BD_manual_dws_assistant_salary_calc.md` | dws_assistant_salary_calc |
-| 13 | `BD_manual_dws_finance_daily_summary.md` | dws_finance_daily_summary |
-| 14 | `BD_manual_dws_finance_discount_detail.md` | dws_finance_discount_detail |
-| 15 | `BD_manual_dws_finance_expense_summary.md` | dws_finance_expense_summary |
-| 16 | `BD_manual_dws_finance_income_structure.md` | dws_finance_income_structure |
-| 17 | `BD_manual_dws_finance_recharge_summary.md` | dws_finance_recharge_summary |
-| 18 | `BD_manual_dws_index_percentile_history.md` | dws_index_percentile_history |
-| 19 | `BD_manual_dws_member_assistant_intimacy.md` | dws_member_assistant_intimacy |
-| 20 | `BD_manual_dws_member_assistant_relation_index.md` | dws_member_assistant_relation_index |
-| 21 | `BD_manual_dws_member_consumption_summary.md` | dws_member_consumption_summary |
-| 22 | `BD_manual_dws_member_newconv_index.md` | dws_member_newconv_index |
-| 23 | `BD_manual_dws_member_visit_detail.md` | dws_member_visit_detail |
-| 24 | `BD_manual_dws_member_winback_index.md` | dws_member_winback_index |
-| 25 | `BD_manual_dws_ml_manual_order_alloc.md` | dws_ml_manual_order_alloc |
-| 26 | `BD_manual_dws_ml_manual_order_source.md` | dws_ml_manual_order_source |
-| 27 | `BD_manual_dws_order_summary.md` | dws_order_summary |
-| 28 | `BD_manual_dws_platform_settlement.md` | dws_platform_settlement |
-| 29 | `BD_manual_v_member_recall_priority.md` | v_member_recall_priority |
-
-### 变更记录（`DWS/changes/`）
-
-| 文件名 | 说明 |
-|--------|------|
-| `2026-02-13_ddl_sync_dws.md` | DDL 对比同步 — DWS 层 |
-
-## ETL_Admin 层文档清单（etl_admin）
-
-### 表级文档（`ETL_Admin/main/`）— 共 3 份
-
-| 序号 | 文件名 | 对应表 |
-|------|--------|--------|
-| 1 | `BD_manual_etl_cursor.md` | etl_cursor |
-| 2 | `BD_manual_etl_run.md` | etl_run |
-| 3 | `BD_manual_etl_task.md` | etl_task |
-
-### 变更记录（`ETL_Admin/changes/`）
-
-暂无变更记录。
-
-## 相关资源
-
-| 资源 | 路径 | 说明 |
+| 内容 | 位置 | 说明 |
 |------|------|------|
-| ODS 数据字典 | `docs/dictionary/ods_tables_dictionary.md` | ODS 层所有表的概览汇总 |
-| DDL 对比结果 | `docs/bd_manual/ddl_compare_results.md` | DDL 文件与数据库实际状态的对比报告 |
-| DDL 文件 — ODS | `database/schema_ODS_doc.sql` | ODS 层表结构定义 |
-| DDL 文件 — DWD | `database/schema_dwd_doc.sql` | DWD 层表结构定义 |
-| DDL 文件 — DWS | `database/schema_dws.sql` | DWS 层表结构定义 |
-| DDL 文件 — ETL_Admin | `database/schema_etl_admin.sql` | ETL_Admin 层表结构定义 |
-| API 端点文档 | `docs/api-reference/endpoints/` | 上游 SaaS API 端点说明 |
-| DDL 对比脚本 | `scripts/compare_ddl_db.py` | DDL 与数据库实际状态对比工具 |
-| 文档验证脚本 | `scripts/validate_bd_manual.py` | BD_Manual 文档覆盖率和格式验证 |
+| DDL 基线 | `docs/database/ddl/` | 从数据库自动导出，按 schema 分文件 |
+| ODS→DWD 字段映射 | `docs/database/BD_Manual_*.md` | 跨层映射（ODS 表 → DWD 表） |
+| 表级字段说明 | 本目录 `*/main/BD_manual_*.md` | 单表字段详情 |
+| API→ODS 字段映射 | 本目录 `ODS/mappings/` | API JSON → ODS 列映射 |

apps/etl/connectors/feiqiu/docs/etl_tasks/README.md

@@ -51,7 +51,7 @@ graph LR
 | 文档 | 说明 |
 |------|------|
 | [BaseTask 公共机制](base_task_mechanism.md) | 任务基类模板方法、TaskContext、时间窗口、注册表、Flow 执行 |
-| [ODS 层任务](ods_tasks.md) | 23 个通用 ODS 任务的架构、配置结构、API 端点、目标表 |
+| [ODS 层任务](ods_tasks.md) | 22 个通用 ODS 任务的架构、配置结构、API 端点、目标表 |
 | [DWD 层任务](dwd_tasks.md) | DWD_LOAD_FROM_ODS 核心装载、SCD2 处理、质量校验 |
 | [DWS 层任务](dws_tasks.md) | 助教业绩、会员分析、财务统计、运维任务共 13 个 DWS 任务 |
 | [INDEX 层任务](index_tasks.md) | WBI/NCI/RS 指数算法 + ML 手动台账导入 |
@@ -88,7 +88,6 @@ graph LR
 | `ODS_TABLE_FEE_DISCOUNT` | `OdsTableDiscountTask` | `ods.table_fee_discount_records` | 台费折扣/调账 | [查看](ods_tasks.md) |
 | `ODS_STORE_GOODS_SALES` | `OdsGoodsLedgerTask` | `ods.store_goods_sales_records` | 门店商品销售流水 | [查看](ods_tasks.md) |
 | `ODS_TENANT_GOODS` | `OdsTenantGoodsTask` | `ods.tenant_goods_master` | 租户商品档案 | [查看](ods_tasks.md) |
-| `ODS_SETTLEMENT_TICKET` | `OdsSettlementTicketTask` | `ods.settlement_ticket_details` | 结账小票详情 | [查看](ods_tasks.md) |
 | `ODS_SETTLEMENT_RECORDS` | `OdsOrderSettleTask` | `ods.settlement_records` | 结账记录 | [查看](ods_tasks.md) |
 
 ### DWD 层（明细数据）
@@ -280,6 +279,7 @@ Flow（执行流程）定义了多层任务的执行顺序。通过 `--flow` 参
 | `--idle-start` | str | — | 闲时窗口开始（HH:MM） |
 | `--idle-end` | str | — | 闲时窗口结束（HH:MM） |
 | `--allow-empty-advance` | flag | `false` | 允许空结果推进窗口 |
+| `--force-full` | flag | `false` | 强制全量处理：跳过 ODS hash 去重和 DWD 变更对比，无条件写入 |
 
 ### 已弃用参数
 

apps/etl/connectors/feiqiu/docs/etl_tasks/confirmed_changes.md

@@ -14,8 +14,8 @@
 |------|------|----------|
 | Task 1 | 新增 `SnapshotMode` 枚举（`FULL_SET` / `TIME_WINDOW` / `NONE`） | `tasks/ods/ods_tasks.py` |
 | Task 2 | content_hash 算法从 MD5 改为 SHA-256 | `tasks/ods/ods_tasks.py` |
-| Task 3 | ODS DDL 补齐 `content_hash` 列 + `is_delete` 列 + `(pk, fetched_at DESC)` 索引 | `db/etl_feiqiu/schemas/ods.sql` |
-| Task 4 | 迁移脚本：为已有 ODS 表添加 `latest_version` 索引 | `db/etl_feiqiu/migrations/2026-02-17__add_ods_latest_version_indexes.sql` |
+| Task 3 | ODS DDL 补齐 `content_hash` 列 + `is_delete` 列 + `(pk, fetched_at DESC)` 索引 | `docs/database/ddl/etl_feiqiu__ods.sql`（原 `db/etl_feiqiu/schemas/ods.sql`，已归档） |
+| Task 4 | 迁移脚本：为已有 ODS 表添加 `latest_version` 索引 | `db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-17__add_ods_latest_version_indexes.sql`（已归档） |
 | Task 5 | 软删除重构：`_mark_missing_as_deleted` 改为 INSERT 删除版本行 | `tasks/ods/ods_tasks.py` |
 | Task 6 | 属性测试覆盖去重和软删除逻辑 | `tests/unit/test_ods_dedup_properties.py` |
 | Task 7-9 | 文档同步、集成验证 | 多文件 |

apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md

@@ -1480,3 +1480,107 @@ recharge_order_flag = (consume_money = 0 AND pay_amount > 0)
 
 - `refreshed`：刷新的物化视图数量
 - `cleaned`：清理的历史数据行数
+
+
+---
+
+## 库存汇总域
+
+库存汇总域包含 3 个任务，围绕商品库存的日度、周度、月度汇总展开。数据流向为：
+
+```
+dwd_goods_stock_summary ──┬──► DWS_GOODS_STOCK_DAILY（日度汇总）
+                          ├──► DWS_GOODS_STOCK_WEEKLY（周度汇总）
+                          └──► DWS_GOODS_STOCK_MONTHLY（月度汇总）
+```
+
+三个任务均依赖 `DWD_LOAD_FROM_ODS` 完成后的 `dwd.dwd_goods_stock_summary` 数据。
+
+---
+
+### DWS_GOODS_STOCK_DAILY — 库存日度汇总
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_GOODS_STOCK_DAILY` |
+| Python 类 | `GoodsStockDailyTask`（`tasks/dws/goods_stock_daily_task.py`） |
+| 目标表 | `dws.dws_goods_stock_daily_summary` |
+| 主键 | `site_id`, `stat_date`, `site_goods_id` |
+| 粒度 | 日期 + 门店 + 商品 |
+| 更新策略 | upsert（ON CONFLICT DO UPDATE） |
+| 更新频率 | 每日更新 |
+| 依赖 | `DWD_LOAD_FROM_ODS` |
+
+#### 数据来源
+
+| 来源表 | Schema | 用途 |
+|--------|--------|------|
+| `dwd_goods_stock_summary` | `dwd` | 库存汇总明细（按 fetched_at 日期聚合） |
+
+#### 核心业务逻辑
+
+- 按 `fetched_at` 的日期部分分组，同一天同一商品可能有多条 DWD 记录
+- 数值指标（入库/出库/销售等）取 SUM 聚合
+- `range_start_stock` 取当日第一条记录的值（期初快照）
+- `range_end_stock` / `current_stock` 取当日最后一条记录的值（期末快照）
+- `stat_period = 'daily'`
+
+---
+
+### DWS_GOODS_STOCK_WEEKLY — 库存周度汇总
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_GOODS_STOCK_WEEKLY` |
+| Python 类 | `GoodsStockWeeklyTask`（`tasks/dws/goods_stock_weekly_task.py`） |
+| 目标表 | `dws.dws_goods_stock_weekly_summary` |
+| 主键 | `site_id`, `stat_date`, `site_goods_id` |
+| 粒度 | ISO 周 + 门店 + 商品 |
+| 更新策略 | upsert（ON CONFLICT DO UPDATE） |
+| 更新频率 | 每周更新 |
+| 依赖 | `DWD_LOAD_FROM_ODS` |
+
+#### 数据来源
+
+| 来源表 | Schema | 用途 |
+|--------|--------|------|
+| `dwd_goods_stock_summary` | `dwd` | 库存汇总明细（按 ISO 周聚合） |
+
+#### 核心业务逻辑
+
+- 按 ISO 周分组（isocalendar），`stat_date` = 该周的周一日期
+- 同一周同一商品可能有多条 DWD 记录
+- 数值指标取 SUM 聚合
+- `range_start_stock` 取该周第一条记录的值（期初快照）
+- `range_end_stock` / `current_stock` 取该周最后一条记录的值（期末快照）
+- `stat_period = 'weekly'`
+
+---
+
+### DWS_GOODS_STOCK_MONTHLY — 库存月度汇总
+
+| 属性 | 值 |
+|------|-----|
+| 任务代码 | `DWS_GOODS_STOCK_MONTHLY` |
+| Python 类 | `GoodsStockMonthlyTask`（`tasks/dws/goods_stock_monthly_task.py`） |
+| 目标表 | `dws.dws_goods_stock_monthly_summary` |
+| 主键 | `site_id`, `stat_date`, `site_goods_id` |
+| 粒度 | 自然月 + 门店 + 商品 |
+| 更新策略 | upsert（ON CONFLICT DO UPDATE） |
+| 更新频率 | 每日更新当月数据 |
+| 依赖 | `DWD_LOAD_FROM_ODS` |
+
+#### 数据来源
+
+| 来源表 | Schema | 用途 |
+|--------|--------|------|
+| `dwd_goods_stock_summary` | `dwd` | 库存汇总明细（按自然月聚合） |
+
+#### 核心业务逻辑
+
+- 按自然月分组，`stat_date` = 该月的第一天（如 2026-01-01 代表 2026 年 1 月）
+- 同一月同一商品可能有多条 DWD 记录
+- 数值指标取 SUM 聚合
+- `range_start_stock` 取该月第一条记录的值（期初快照）
+- `range_end_stock` / `current_stock` 取该月最后一条记录的值（期末快照）
+- `stat_period = 'monthly'`

apps/etl/connectors/feiqiu/docs/etl_tasks/index_tasks.md

@@ -751,5 +751,5 @@ ORDER BY effective_from DESC
 | `compression_mode` | 1 | 压缩模式（默认 log1p） |
 | `use_smoothing` / `ewma_alpha` | 1 / 0.2 | EWMA 平滑 |
 
-> 种子数据脚本：`database/seed_index_parameters.sql`
-> DDL 定义：`database/schema_dws.sql`（第 21 节）
+> 种子数据脚本：`db/etl_feiqiu/seeds/seed_index_parameters.sql`
+> DDL 定义：`docs/database/ddl/etl_feiqiu__dws.sql`

apps/etl/connectors/feiqiu/docs/etl_tasks/ods_task_params_matrix.md

@@ -1,6 +1,6 @@
 # ODS 任务参数矩阵
 
-> 本文档列举所有 23 个 ODS 任务的关键配置参数，说明每个参数在 ETL 处理流程中的作用，
+> 本文档列举所有 22 个 ODS 任务的关键配置参数，说明每个参数在 ETL 处理流程中的作用，
 > 并以通俗语言概述飞球 ETL 的 API → ODS 现状。
 >
 > 数据来源：`tasks/ods/ods_tasks.py` 中的 `ODS_TASK_SPECS` 声明。
@@ -12,7 +12,7 @@
 
 ### 从哪抓
 
-从上游飞球 SaaS 平台的 REST API 抓取，共对接 22 个不同的 API 端点（加上小票的特殊接口共 23 个）。覆盖台球门店的核心业务：订单结账、支付退款、会员档案与余额、助教服务与废除、商品库存、台桌、团购套餐、台费折扣等。每个端点对应一个 ODS 任务。
+从上游飞球 SaaS 平台的 REST API 抓取，共对接 22 个不同的 API 端点。覆盖台球门店的核心业务：订单结账、支付退款、会员档案与余额、助教服务与废除、商品库存、台桌、团购套餐、台费折扣等。每个端点对应一个 ODS 任务。
 
 ### 怎么解析
 
@@ -20,11 +20,11 @@ API 返回的 JSON 响应通过两级路径定位数据：先按 `data_path`（
 
 ### 写到哪
 
-全部写入 PostgreSQL 的 `ods.*` schema（对应实际的 `ods` schema），23 张表一一对应 23 个任务。
+全部写入 PostgreSQL 的 `ods.*` schema（对应实际的 `ods` schema），22 张表一一对应 22 个任务。
 
 ### 怎么去重
 
-所有 23 个任务默认开启 `skip_unchanged=True`：基于原始 payload + is_delete 计算 content_hash（SHA-256），若与数据库中该业务 ID 最新版本的 hash 相同则跳过写入，避免无意义的版本膨胀。
+所有 22 个任务默认开启 `skip_unchanged=True`：基于原始 payload + is_delete 计算 content_hash（SHA-256），若与数据库中该业务 ID 最新版本的 hash 相同则跳过写入，避免无意义的版本膨胀。
 
 冲突处理模式默认是 `update`（全字段对比，有变化才更新），也支持 `backfill`（只回填 NULL 列）和 `nothing`（跳过已存在记录），通过运行时配置 `run.ods_conflict_mode` 控制。
 
@@ -34,7 +34,7 @@ API 返回的 JSON 响应通过两级路径定位数据：先按 `data_path`（
 
 - 全表快照（5 个任务）：API 返回全量数据，本次没返回但数据库里有的记录插入一条 `is_delete=1` 的删除版本行。适用于维度表/档案表，数据量小。
 - 窗口快照（8 个任务）：只在指定时间列的窗口范围内做软删除。适用于流水表，数据量大，只能按时间段比对。
-- 无快照（10 个任务）：纯增量写入，不做软删除。
+- 无快照（9 个任务）：纯增量写入，不做软删除。
 
 下游 DWD 层取数规约：`DISTINCT ON (id) ORDER BY id, fetched_at DESC`，再过滤 `is_delete = 0`。
 
@@ -96,12 +96,10 @@ API 返回的 JSON 响应通过两级路径定位数据：先按 `data_path`（
 | `ODS_STORE_GOODS` | ❌ | 默认 | ❌ | ✅ | ✅ | `FULL_TABLE` | — |
 | `ODS_TABLE_FEE_DISCOUNT` | ❌ | 默认 | ❌ | ✅ | ✅ | `WINDOW` | `create_time` |
 | `ODS_TENANT_GOODS` | ❌ | 默认 | ❌ | ✅ | ✅ | `FULL_TABLE` | — |
-| `ODS_SETTLEMENT_TICKET` | ❌ | — | ✅ | ✅ | ✅ | `NONE` | — |
 
 > - "默认" `time_fields` 表示 `(startTime, endTime)`
 > - "—" 表示该参数为 `None` 或不适用
 > - `skip_unchanged` 所有任务均为 `True`（默认值），基于 payload + is_delete 计算 content_hash
-> - `ODS_SETTLEMENT_TICKET` 的 `time_fields` 为 `—` 是因为它不走标准分页抓取流程，而是先收集 `orderSettleId` 再逐个调用小票接口
 > - `ODS_RECHARGE_SETTLE` 是唯一手动映射 60+ 列的任务（其余任务按 DB schema 自动匹配）
 
 
@@ -109,7 +107,7 @@ API 返回的 JSON 响应通过两级路径定位数据：先按 `data_path`（
 
 ## 去重策略
 
-所有 23 个任务统一使用 `skip_unchanged=True`（默认值）：
+所有 22 个任务统一使用 `skip_unchanged=True`（默认值）：
 
 - content_hash 基于原始 payload（`json.dumps(sort_keys=True, separators=(',',':'), ensure_ascii=False)`）+ `is_delete` 值计算 SHA-256
 - 写入时与数据库中该业务 ID 最新版本的 content_hash 比对，相同则跳过
@@ -121,6 +119,6 @@ API 返回的 JSON 响应通过两级路径定位数据：先按 `data_path`（
 |------|:---:|----------|------|
 | 全表快照 | `FULL_TABLE` | `ODS_ASSISTANT_ACCOUNT`、`ODS_MEMBER_CARD`、`ODS_GROUP_PACKAGE`、`ODS_STORE_GOODS`、`ODS_TENANT_GOODS`（5 个） | API 返回全量，不在返回集中的记录插入一条 `is_delete=1` 的删除版本行 |
 | 窗口快照 | `WINDOW` | `ODS_TABLE_USE`、`ODS_ASSISTANT_LEDGER`、`ODS_STORE_GOODS_SALES`、`ODS_REFUND`、`ODS_PLATFORM_COUPON`、`ODS_MEMBER_BALANCE`、`ODS_GROUP_BUY_REDEMPTION`、`ODS_TABLE_FEE_DISCOUNT`（8 个） | 仅在 `snapshot_time_column` 指定的时间列窗口范围内做软删除 |
-| 无快照 | `NONE` | 其余 10 个 | 纯增量写入，不做软删除 |
+| 无快照 | `NONE` | 其余 9 个 | 纯增量写入，不做软删除 |
 
 软删除语义：INSERT 一条 `is_delete=1` 的新版本行（而非 UPDATE 历史版本），保持 ODS 追加写入的一致性。若最新版本已是 `is_delete=1` 则跳过（幂等）。

apps/etl/connectors/feiqiu/docs/etl_tasks/ods_tasks.md

@@ -40,7 +40,7 @@ ODS 层采用**声明式配置**驱动的通用任务模式：由 `BaseOdsTask`
 | `ODS_STORE_GOODS` | `OdsStoreGoodsTask` | `/TenantGoods/GetGoodsInventoryList` | `store_goods_master` | 门店商品档案 |
 | `ODS_TABLE_FEE_DISCOUNT` | `OdsTableDiscountTask` | `/Site/GetTaiFeeAdjustList` | `table_fee_discount_records` | 台费折扣/调账 |
 | `ODS_TENANT_GOODS` | `OdsTenantGoodsTask` | `/TenantGoods/QueryTenantGoods` | `tenant_goods_master` | 租户商品档案 |
-| `ODS_SETTLEMENT_TICKET` | `OdsSettlementTicketTask` | `/Order/GetOrderSettleTicketNew` | `settlement_ticket_details` | 结账小票详情 |
+| `ODS_STAFF_INFO` | `OdsStaffInfoTask` | `/PersonnelManagement/SearchSystemStaffInfo` | `staff_info_master` | 员工档案（含在职/离职） |
 
 > 所有目标表均位于 `ods` schema 下。
 
@@ -228,7 +228,7 @@ execute(cursor_data)
 
 ### content_hash 去重机制
 
-`content_hash` 是通用 ODS 任务的核心去重手段，所有 23 个任务默认开启（`skip_unchanged=True`）。
+`content_hash` 是通用 ODS 任务的核心去重手段，所有 22 个任务默认开启（`skip_unchanged=True`）。
 
 #### 计算方式
 
@@ -295,8 +295,6 @@ ORDER BY id, fetched_at DESC;
 | `ODS_STORE_GOODS` | 否 | `FULL_TABLE` | — | 门店商品档案 |
 | `ODS_TABLE_FEE_DISCOUNT` | 否 | `WINDOW` | `create_time` | 台费折扣/调账 |
 | `ODS_TENANT_GOODS` | 否 | `FULL_TABLE` | — | 租户商品档案 |
-| `ODS_SETTLEMENT_TICKET` | 否 | `NONE` | — | 结账小票详情（专用实现，见下文） |
+| `ODS_STAFF_INFO` | 否 | `FULL_TABLE` | — | 员工档案，全量快照 |
 
 > 所有 23 个任务默认 `skip_unchanged=True`（去重开启）。
-
-> **特殊任务**：`ODS_SETTLEMENT_TICKET` 虽然在 `ODS_TASK_SPECS` 中声明，但其 `ODS_TASK_CLASSES` 条目被 `OdsSettlementTicketTask` 专用实现覆盖。该任务不走标准分页抓取流程，而是先从 `payment_transactions` 表或支付 API 收集 `orderSettleId`，再逐个调用小票接口获取详情。

apps/etl/connectors/feiqiu/docs/etl_tasks/utility_tasks.md

@@ -52,8 +52,11 @@ load()
 
 | DDL 文件 | 创建的 Schema | 主要内容 |
 |----------|--------------|----------|
-| `database/schema_etl_admin.sql` | `meta` | `etl_task`（任务注册表）、`etl_cursor`（游标表）、`etl_run`（运行记录表） |
-| `database/schema_ODS_doc.sql` | `ods` | 20+ 张 ODS 原始表（member_profiles、settlement_records、payment_transactions 等） |
+| meta DDL（代码默认 `database/schema_etl_admin.sql`） | `meta` | `etl_task`（任务注册表）、`etl_cursor`（游标表）、`etl_run`（运行记录表） |
+| ODS DDL（代码默认 `database/schema_ODS_doc.sql`） | `ods` | 20+ 张 ODS 原始表（member_profiles、settlement_records、payment_transactions 等） |
+
+> 注：模块内 `database/` 目录下的旧 DDL 文件已不存在。INIT 任务通过配置参数 `schema.ods_file` / `schema.etl_admin_file` 指定 DDL 路径。
+> 当前 DDL 基线统一维护在 `docs/database/ddl/`（如 `etl_feiqiu__ods.sql`、`etl_feiqiu__meta.sql`），使用时需通过配置参数指向正确路径。
 
 ### ODS DDL 清洗逻辑
 
@@ -75,8 +78,8 @@ ODS DDL 文件可能包含头部说明文本和 `COMMENT ON` 语句（CamelCase
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
-| `schema.ods_file` | `database/schema_ODS_doc.sql` | ODS DDL 文件路径 |
-| `schema.etl_admin_file` | `database/schema_etl_admin.sql` | meta DDL 文件路径 |
+| `schema.ods_file` | `database/schema_ODS_doc.sql`（⚠️ 旧路径，需配置为实际 DDL 位置） | ODS DDL 文件路径 |
+| `schema.etl_admin_file` | `database/schema_etl_admin.sql`（⚠️ 旧路径） | meta DDL 文件路径 |
 | `io.log_root` | — | 日志目录 |
 | `io.export_root` | — | 导出目录 |
 | `pipeline.fetch_root` | — | 抓取数据目录 |
@@ -115,7 +118,9 @@ load()
 
 | DDL 文件 | 创建的 Schema | 主要内容 |
 |----------|--------------|----------|
-| `database/schema_dwd_doc.sql` | `dwd` | 维度表（dim_*，含 SCD2 约束）、事实表（dwd_*、fact_*）、扩展表（*_ex） |
+| DWD DDL（代码默认 `database/schema_dwd_doc.sql`） | `dwd` | 维度表（dim_*，含 SCD2 约束）、事实表（dwd_*、fact_*）、扩展表（*_ex） |
+
+> 注：DDL 基线见 `docs/database/ddl/etl_feiqiu__dwd.sql`，使用时需通过 `schema.dwd_file` 配置参数指向正确路径。
 
 DWD DDL 的特殊处理：
 - 自动为含 `scd2_start_time` 列的表设置 SCD2 默认值（`scd2_start_time=now()`、`scd2_end_time='9999-12-31'`、`scd2_is_current=1`、`scd2_version=1`）
@@ -126,7 +131,7 @@ DWD DDL 的特殊处理：
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
-| `schema.dwd_file` | `database/schema_dwd_doc.sql` | DWD DDL 文件路径 |
+| `schema.dwd_file` | `database/schema_dwd_doc.sql`（⚠️ 旧路径，需配置为实际 DDL 位置） | DWD DDL 文件路径 |
 | `dwd.drop_schema_first` | `False` | 是否先 DROP 再重建（危险操作，会丢失所有 DWD 数据） |
 
 ### CLI 示例
@@ -166,7 +171,9 @@ load()
 
 | DDL 文件 | 创建的 Schema | 主要内容 |
 |----------|--------------|----------|
-| `database/schema_dws.sql` | `dws` | 配置表（5 张 cfg_*）、助教域（5 张）、会员域（2 张）、财务域（7 张）、订单汇总（1 张） |
+| DWS DDL（代码默认 `database/schema_dws.sql`） | `dws` | 配置表（5 张 cfg_*）、助教域（5 张）、会员域（2 张）、财务域（7 张）、订单汇总（1 张） |
+
+> 注：DDL 基线见 `docs/database/ddl/etl_feiqiu__dws.sql`，使用时需通过 `schema.dws_file` 配置参数指向正确路径。
 
 DWS Schema 包含的配置表：
 
@@ -182,7 +189,7 @@ DWS Schema 包含的配置表：
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
-| `schema.dws_file` | `database/schema_dws.sql` | DWS DDL 文件路径 |
+| `schema.dws_file` | `database/schema_dws.sql`（⚠️ 旧路径，需配置为实际 DDL 位置） | DWS DDL 文件路径 |
 | `dws.drop_schema_first` | `False` | 是否先 DROP 再重建（危险操作） |
 
 ### CLI 示例
@@ -231,7 +238,7 @@ load()
 
 | 参数 | 默认值 | 说明 |
 |------|--------|------|
-| `schema.seed_dws_file` | `database/seed_dws_config.sql` | 种子数据 SQL 文件路径 |
+| `schema.seed_dws_file` | `database/seed_dws_config.sql`（⚠️ 旧路径，种子数据现位于 `db/etl_feiqiu/seeds/seed_dws_config.sql`） | 种子数据 SQL 文件路径 |
 
 ### CLI 示例
 
@@ -290,7 +297,6 @@ execute()
 | `platform_coupon_redemption_records` | `ods.platform_coupon_redemption_records` |
 | `group_buy_redemption_records` | `ods.group_buy_redemption_records` |
 | `group_buy_packages` | `ods.group_buy_packages` |
-| `settlement_ticket_details` | `ods.settlement_ticket_details` |
 | `store_goods_master` | `ods.store_goods_master` |
 | `tenant_goods_master` | `ods.tenant_goods_master` |
 | `store_goods_sales_records` | `ods.store_goods_sales_records` |

apps/etl/connectors/feiqiu/docs/operations/environment_setup.md

@@ -51,15 +51,18 @@ uv sync --group test
 在项目根目录创建 `.env` 文件（禁止提交到版本控制）：
 
 ```dotenv
-# 数据库连接
+# 数据库连接（推荐使用 DSN 模式）
 PG_DSN=postgresql://用户名:密码@主机:端口/数据库名
-# 或分别指定
+# 或分离式配置（不使用 DSN 时启用）
 PG_HOST=localhost
 PG_PORT=5432
-PG_NAME=billiards
+PG_NAME=your_database
 PG_USER=your_user
 PG_PASSWORD=your_password
 
+# 业务库 DSN（后端 / 跨模块脚本使用）
+APP_DB_DSN=postgresql://用户名:密码@主机:端口/数据库名
+
 # 门店与 API
 STORE_ID=1
 API_TOKEN=your_bearer_token
@@ -99,19 +102,22 @@ config/defaults.py  →  .env / 环境变量  →  CLI 参数
 初始化步骤：
 
 ```bash
-# 1. 执行 DDL 创建表结构（DDL 文件位于 db/etl_feiqiu/schemas/）
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_etl_admin.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_ODS_doc.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dwd_doc.sql
-psql "$PG_DSN" -f db/etl_feiqiu/schemas/schema_dws.sql
+# 推荐使用 CLI 工具任务初始化（DDL 基线见 docs/database/ddl/）
+python -m cli.main --tasks INIT_ODS_SCHEMA,INIT_DWD_SCHEMA,INIT_DWS_SCHEMA,SEED_DWS_CONFIG --pg-dsn "$PG_DSN"
 
-# 2. 执行种子数据（如有）
+# 或手动执行 DDL（从 docs/database/ddl/ 获取最新基线）
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__meta.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__ods.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dwd.sql
+psql "$PG_DSN" -f docs/database/ddl/etl_feiqiu__dws.sql
+
+# 执行种子数据
 psql "$PG_DSN" -f db/etl_feiqiu/seeds/seed_*.sql
-
-# 3. 执行迁移脚本（按日期前缀顺序）
-ls db/etl_feiqiu/migrations/*.sql | sort | xargs -I {} psql "$PG_DSN" -f {}
 ```
 
+> 注：旧的 `db/etl_feiqiu/schemas/` 和 `db/etl_feiqiu/migrations/` 已归档至 `db/_archived/`。
+> DDL 基线现由 `docs/database/ddl/` 统一管理，可通过 `python scripts/ops/gen_consolidated_ddl.py` 重新生成。
+
 或使用 CLI 工具任务初始化：
 
 ```bash

apps/etl/connectors/feiqiu/docs/requirements/DWS需求与口径.md

@@ -15,7 +15,7 @@
 
 参考路径：
 - DWD schema 文档：`docs/database/`
-- DWS DDL：`db/etl_feiqiu/schemas/`
+- DWS DDL：`docs/database/ddl/etl_feiqiu__dws.sql`
 - DWS 种子数据：`db/etl_feiqiu/seeds/`
 
 ---
@@ -170,7 +170,7 @@ Top3 销冠奖（2026-03-01 起）：第 1 名 1000 元，第 2 名 600 元，
 需求中明确 7/10/15/30/60/90 天窗口，在 `dws_assistant_customer_stats`、`dws_member_consumption_summary` 中直接落多窗口字段。
 
 ### 6.2 DDL 完整性
-所有方案中列出的表需在 `db/etl_feiqiu/schemas/` 中落全 DDL。
+所有方案中列出的表需在 `docs/database/ddl/etl_feiqiu__dws.sql` 中落全 DDL。
 
 ### 6.3 时间分层实现
 UI 需要"最近半年不含本月、上季度"等时间维度，并满足上个周期的环比。DWS 分层仅到 3 个月，可能需要额外聚合层。