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

apps/etl/connectors/feiqiu/docs/database/ODS/changes/2026-02-13_ddl_sync_ods.md

@@ -1,96 +0,0 @@
-# ODS 层 DDL 同步修正 — 变更记录
-
-> 结构性变更：修正 4 项差异（删除 2 个冗余字段、修正 1 个字段类型、补充 1 个缺失字段）
-
-## 溯源
-
-- 日期：2026-02-13（Asia/Shanghai）
-- 工具：`scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql`
-- Direct cause：DDL 对比脚本发现 `database/schema_ODS_doc.sql` 与数据库 `ods` schema 实际状态存在 4 项差异，以数据库为准修正 DDL 文件。
-
-## 变更内容
-
-| Schema | 表名 | 操作 | 字段 | DDL 原定义 | 数据库实际 | 说明 |
-|--------|------|------|------|-----------|-----------|------|
-| `ods` | `recharge_settlements` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
-| `ods` | `settlement_records` | DDL 删除字段 | `settlelist` | `jsonb` | — | DDL 中有但数据库中不存在，属冗余定义 |
-| `ods` | `tenant_goods_master` | DDL 修正类型 | `not_sale` | `BOOLEAN` | `INTEGER` | 字段类型不匹配，以数据库为准 |
-| `ods` | `refund_transactions` | DDL 补充字段 | `check_status` | — | `INTEGER` | 数据库中有但 DDL 中未定义 |
-
-## 变更原因
-
-1. `recharge_settlements.settlelist` 和 `settlement_records.settlelist`：DDL 文件中残留的字段定义，数据库中已在先前迁移（`20260214_drop_ods_settlelist.sql`）中删除，DDL 未同步清理
-2. `tenant_goods_master.not_sale`：DDL 定义为 `BOOLEAN`，但数据库实际为 `INTEGER`（0/1 表示是否停售），以数据库为准修正
-3. `refund_transactions.check_status`：数据库中存在的审核状态字段，DDL 文件中遗漏未定义
-
-## 影响范围
-
-| 影响对象 | 影响程度 | 说明 |
-|----------|----------|------|
-| ETL 加载任务 | 无影响 | 本次仅修正 DDL 文档，不涉及数据库结构变更 |
-| 后端 API | 无影响 | DDL 文件为文档性质，不影响运行时 |
-| 小程序字段映射 | 无影响 | 小程序不直接读 ODS 层 |
-| ODS 表级文档 | ⚠️ 需同步 | 后续生成 ODS 表级文档时应以修正后的 DDL 为准 |
-| DWD 加载映射 | 无影响 | `refund_transactions.check_status` 已在 DWD 层有对应映射 |
-
-**注意**：本次变更仅修正 DDL 文件（文档同步），数据库结构未发生任何变更。数据库是"源头"，DDL 文件是"文档"。
-
-## 回滚策略
-
-本次为 DDL 文件修正（文档同步），无需数据库回滚。若需恢复 DDL 文件，使用 Git 回退即可：
-
-```bash
-git checkout HEAD~1 -- database/schema_ODS_doc.sql
-```
-
-若未来需要将数据库结构回退到 DDL 修正前的状态（不推荐）：
-
-```sql
--- 1) 恢复 settlelist 列（数据不可恢复）
-ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist JSONB;
-ALTER TABLE ods.settlement_records ADD COLUMN settlelist JSONB;
-
--- 2) 将 not_sale 改回 BOOLEAN（需数据转换）
-ALTER TABLE ods.tenant_goods_master
-  ALTER COLUMN not_sale TYPE BOOLEAN USING (not_sale::INTEGER != 0);
-
--- 3) 删除 check_status 列
-ALTER TABLE ods.refund_transactions DROP COLUMN check_status;
-```
-
-## 验证 SQL
-
-```sql
--- 1) 确认 settlelist 列在数据库中确实不存在
-SELECT column_name
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name IN ('recharge_settlements', 'settlement_records')
-  AND column_name = 'settlelist';
--- 预期：0 行
-
--- 2) 确认 tenant_goods_master.not_sale 实际类型为 integer
-SELECT column_name, data_type
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name = 'tenant_goods_master'
-  AND column_name = 'not_sale';
--- 预期：data_type = 'integer'
-
--- 3) 确认 refund_transactions.check_status 存在且类型为 integer
-SELECT column_name, data_type, is_nullable
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name = 'refund_transactions'
-  AND column_name = 'check_status';
--- 预期：1 行，data_type = 'integer'
-
--- 4) 确认修正后 DDL 与数据库零差异（通过对比脚本验证）
--- python scripts/compare_ddl_db.py --schema ods --ddl-path database/schema_ODS_doc.sql
--- 预期：0 项差异
-```
-
-## 关联文件
-
-- DDL 文件：`database/schema_ODS_doc.sql`
-- 对比结果：`docs/database/ddl_compare_results.md`

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260213_align_ods_with_api.md

@@ -1,39 +0,0 @@
-# ODS 表与 API JSON 字段对齐 — 变更记录
-
-> 无结构性变更
-
-## 溯源
-
-- 日期：2026-02-13（Asia/Shanghai）
-- Prompt：P20260213-210000 — 用新梳理的 API 返回 JSON 文档比对数据库 ODS 层
-- Direct cause：`scripts/compare_api_ods.py` 自动比对 22 张 ODS 表与 `docs/api-reference/` 文档中的 JSON 字段，结论为全部对齐，无需 ALTER
-
-## 说明
-
-迁移文件 `database/migrations/20260213_align_ods_with_api.sql` 为比对结论记录，不包含任何 DDL 语句。
-
-- 比对范围：`ods` schema 下 22 张表
-- 比对逻辑：camelCase → snake_case 归一化匹配 + 去下划线纯小写兜底
-- 结论：所有 ODS 表列已与 API JSON 响应字段完全对齐
-- `stock_goods_category_tree` 的 `goodsCategoryList`/`total` 为响应包装层字段，ODS 表已正确展开存储数组内的记录级字段，无需额外列
-
-## 验证 SQL
-
-```sql
--- 1) 确认 ods schema 下表数量
-SELECT count(*) FROM information_schema.tables
-WHERE table_schema = 'ods' AND table_type = 'BASE TABLE';
-
--- 2) 确认迁移文件未引入新列（对比前后列数应一致）
-SELECT table_name, count(*) AS col_count
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-GROUP BY table_name
-ORDER BY table_name;
-
--- 3) 确认无待执行的 pending migration（迁移文件为纯注释，不应产生任何变更）
-SELECT column_name, data_type
-FROM information_schema.columns
-WHERE table_schema = 'ods' AND table_name = 'assistant_accounts_master'
-ORDER BY ordinal_position;
-```

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_option_name_able_site_transfer.md

@@ -1,111 +0,0 @@
-# ODS 层删除 option_name / able_site_transfer 冗余列 — 变更记录
-
-> 结构性变更：删除 2 张表各 1 个冗余列（API JSON 中不存在，ODS 全 NULL）
-
-## 溯源
-
-- 日期：2026-02-14（Asia/Shanghai）
-- Prompt：P20260214-070000 — 删除 ODS 层 store_goods_sales_records.option_name 和 member_stored_value_cards.able_site_transfer
-- Direct cause：API vs ODS 比对报告（v3-fixed）中这两列被标注为"ODS 独有"，经查证 API JSON 响应中从未返回这两个字段，ODS 中全部为 NULL（0 条非空数据），属于冗余列，应清理。
-
-## 变更内容
-
-| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
-|--------|------|------|------|--------|------|
-| `ods` | `store_goods_sales_records` | DROP COLUMN | `option_name` | `text` | API 后续版本新增字段，实际从未返回数据，全 NULL |
-| `ods` | `member_stored_value_cards` | DROP COLUMN | `able_site_transfer` | `integer` | API 后续版本新增字段，实际从未返回数据，全 NULL |
-
-### Before / After
-
-**store_goods_sales_records**：
-- Before：52 个业务列 + 5 个 meta 列（含 `option_name text`）
-- After：51 个业务列 + 5 个 meta 列（`option_name` 已移除）
-
-**member_stored_value_cards**：
-- Before：76 个业务列 + 5 个 meta 列（含 `able_site_transfer integer`）
-- After：75 个业务列 + 5 个 meta 列（`able_site_transfer` 已移除）
-
-## 变更原因
-
-1. v3-fixed 比对报告显示 `option_name` 和 `able_site_transfer` 为"ODS 独有"字段
-2. 全量 JSON 刷新审计（100 条/接口）确认 API 响应中从未包含这两个字段
-3. 数据库查询确认两列全部为 NULL，无实际业务数据
-4. 保留全 NULL 的冗余列会误导后续开发和数据分析
-
-## 影响范围
-
-| 影响对象 | 影响程度 | 说明 |
-|----------|----------|------|
-| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库 INSERT/UPSERT 语句中若包含这两列需移除 |
-| DWD 加载任务 | 无影响 | DWD 层未映射这两个字段（全 NULL 无法产生有意义的 DWD 数据） |
-| API 契约 | 无影响 | API 响应结构不变，这两个字段本就不在 API 返回中 |
-| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
-| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3_fixed.md` 中两表的 ODS 独有字段需移除 |
-
-## 回滚策略
-
-```sql
--- 恢复列结构（数据不可恢复，因原始数据全为 NULL）
-ALTER TABLE ods.store_goods_sales_records ADD COLUMN option_name TEXT;
-ALTER TABLE ods.member_stored_value_cards ADD COLUMN able_site_transfer INTEGER;
-```
-
-**注意事项**：
-- 回滚后两列数据均为 NULL（与删除前一致），无数据丢失风险
-- 若未来 API 版本开始返回这两个字段，需重新 ADD COLUMN 并更新 ODS 入库逻辑
-
-## 验证 SQL
-
-```sql
--- 1) 确认 option_name 列已不存在
-SELECT column_name
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name = 'store_goods_sales_records'
-  AND column_name = 'option_name';
--- 预期：0 行
-
--- 2) 确认 able_site_transfer 列已不存在
-SELECT column_name
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name = 'member_stored_value_cards'
-  AND column_name = 'able_site_transfer';
--- 预期：0 行
-
--- 3) 确认两表当前列数
-SELECT table_name, count(*) AS total_columns
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name IN ('store_goods_sales_records', 'member_stored_value_cards')
-GROUP BY table_name;
--- 预期：store_goods_sales_records = 56（51 业务 + 5 meta），member_stored_value_cards = 80（75 业务 + 5 meta）
-
--- 4) 确认删除前数据确实全 NULL（回溯验证，迁移执行前运行）
--- SELECT count(*) FROM ods.store_goods_sales_records WHERE option_name IS NOT NULL;
--- SELECT count(*) FROM ods.member_stored_value_cards WHERE able_site_transfer IS NOT NULL;
--- 预期：均为 0
-```
-
-## 迁移文件
-
-`database/migrations/20260214_drop_ods_option_name_able_site_transfer.sql`
-
-
----
-
-## 补充记录：schema_ODS_doc.sql AI_CHANGELOG 标注
-
-- 日期：2026-02-14（Asia/Shanghai）
-- Prompt：P20260214-070000（同上）
-- 变更内容：在 `database/schema_ODS_doc.sql` 末尾追加 AI_CHANGELOG 注释块，记录 option_name / able_site_transfer 两列在 DDL 文档中的注释化处理
-- 结论：**无结构性变更**（仅追加 SQL 注释，不涉及 DDL 操作）
-
-<!--
-AI_CHANGELOG:
-- 日期: 2026-02-14
-- Prompt: P20260214-070000 — ODS 清理与文档标注（5 项任务）
-- 直接原因: DB schema 变更（删除 2 列）必须同步 BD Manual
-- 变更摘要: 新建 ODS 层变更记录文档，记录 option_name 和 able_site_transfer 的删除原因、影响、回滚策略和验证 SQL
-- 风险与验证: 纯文档；验证：验证 SQL 执行结果与预期一致
--->

apps/etl/connectors/feiqiu/docs/database/ODS/changes/20260214_drop_ods_settlelist.md

@@ -1,102 +0,0 @@
-# ODS 层删除 settlelist 冗余列 — 变更记录
-
-> 结构性变更：删除 2 张表的 1 个 jsonb 列
-
-## 溯源
-
-- 日期：2026-02-14（Asia/Shanghai）
-- Prompt：P20260214-023000 — 删除 ODS 层 settlement_records / recharge_settlements 的 settlelist jsonb 列
-- Direct cause：`settlelist` 列与 `payload` 列数据完全重复（`payload` 存储完整 API 响应 JSON，已包含 `settleList` 对象），属于冗余存储。DWD 加载逻辑已改为从 `payload` 提取 `settleList`，该列不再被任何下游消费。
-
-## 变更内容
-
-| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
-|--------|------|------|------|--------|------|
-| `ods` | `settlement_records` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
-| `ods` | `recharge_settlements` | DROP COLUMN | `settlelist` | `jsonb` | 存储原始 settleList 对象，与 payload 重复 |
-
-### Before / After
-
-**settlement_records**：
-- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
-- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
-
-**recharge_settlements**：
-- Before：67 个业务列 + 5 个 meta 列（含 `settlelist jsonb`）
-- After：66 个业务列 + 5 个 meta 列（`settlelist` 已移除）
-
-## 变更原因
-
-1. `payload` 列（jsonb）已存储完整的 API 响应 JSON，其中包含 `settleList` 对象
-2. `settlelist` 列是 ETL 入库时从 `payload` 中额外提取并单独存储的副本，属于冗余
-3. API vs ODS 比对报告（v3-fixed）中已标注 `settlelist` 为"ODS jsonb 列（存储原始 settleList 对象）"
-4. DWD 加载逻辑已修改为直接从 `payload->'settleList'` 提取数据
-
-## 影响范围
-
-| 影响对象 | 影响程度 | 说明 |
-|----------|----------|------|
-| DWD 加载任务 | ⚠️ 需确认 | DWD 加载必须已改为从 `payload` 提取 settleList，不再读 `settlelist` 列 |
-| ODS 抓取任务 | ⚠️ 需确认 | ODS 入库逻辑需移除对 `settlelist` 列的写入（INSERT/UPSERT 语句） |
-| API 契约 | 无影响 | API 响应结构不变，仅 ODS 存储方式调整 |
-| 小程序 | 无影响 | 小程序不直接读 ODS 层 |
-| 比对报告 | 需更新 | `docs/reports/api_ods_comparison_v3.md` 和 `scripts/ods_columns.json` 中 settlement_records / recharge_settlements 的列清单需移除 `settlelist` |
-| 比对脚本 | 需更新 | `scripts/run_compare_v3_fixed.py` 中 `classify_ods_only()` 对 `settlelist` 的特殊处理可移除 |
-
-## 回滚策略
-
-```sql
--- 1) 恢复列结构
-ALTER TABLE ods.settlement_records ADD COLUMN settlelist jsonb;
-ALTER TABLE ods.recharge_settlements ADD COLUMN settlelist jsonb;
-
--- 2) 从 payload 回填数据（回滚后列为 NULL，需重新提取）
-UPDATE ods.settlement_records
-SET settlelist = payload->'settleList'
-WHERE payload IS NOT NULL;
-
-UPDATE ods.recharge_settlements
-SET settlelist = payload->'settleList'
-WHERE payload IS NOT NULL;
-```
-
-**注意事项**：
-- 回滚后 `settlelist` 列数据为 NULL，必须执行回填 UPDATE
-- 若历史数据中存在 `payload IS NULL` 的行，这些行的 `settlelist` 将永久丢失（无法恢复）
-- 回填前建议先统计 `payload IS NULL` 的行数，评估数据损失范围
-
-## 验证 SQL
-
-```sql
--- 1) 确认 settlelist 列已不存在
-SELECT column_name
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name IN ('settlement_records', 'recharge_settlements')
-  AND column_name = 'settlelist';
--- 预期：0 行
-
--- 2) 确认 payload 列仍存在且包含 settleList 数据
-SELECT count(*)
-FROM ods.settlement_records
-WHERE payload IS NOT NULL AND payload->'settleList' IS NOT NULL;
--- 预期：> 0（确认 payload 中有 settleList 数据可用）
-
--- 3) 确认两表当前列数（排除 meta 列后应为 66）
-SELECT table_name, count(*) AS total_columns
-FROM information_schema.columns
-WHERE table_schema = 'ods'
-  AND table_name IN ('settlement_records', 'recharge_settlements')
-GROUP BY table_name;
--- 预期：settlement_records = 71（66 业务 + 5 meta），recharge_settlements = 71
-
--- 4) 确认 DWD 加载可从 payload 正常提取 settleList
-SELECT id, (payload->'settleList') IS NOT NULL AS has_settle_list
-FROM ods.settlement_records
-LIMIT 5;
--- 预期：has_settle_list = true（至少对 payload 非空的行）
-```
-
-## 迁移文件
-
-`database/migrations/20260214_drop_ods_settlelist.sql`

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

@@ -1,70 +0,0 @@
-# assistant_cancellation_records 助教取消/作废记录
-
-> 生成时间：2026-02-14
-
-## 表信息
-
-| 属性 | 值 |
-|------|-----|
-| Schema | ods |
-| 表名 | assistant_cancellation_records |
-| 主键 | id, content_hash |
-| 数据来源 | export/test-json-doc/assistant_cancellation_records.json |
-| 说明 | 助教作废/取消记录 |
-
-## 字段说明
-
-| 序号 | 字段名 | 类型 | 可空 | 说明 |
-|------|--------|------|------|------|
-| 1 | id | BIGINT | NO | 本表主键 ID，用于唯一标识一条记录 |
-| 2 | siteid | BIGINT | YES | （待补充） |
-| 3 | siteprofile | JSONB | YES | （待补充） |
-| 4 | assistantname | TEXT | YES | （待补充） |
-| 5 | assistantabolishamount | NUMERIC(18,2) | YES | （待补充） |
-| 6 | assistanton | INTEGER | YES | （待补充） |
-| 7 | pdchargeminutes | INTEGER | YES | （待补充） |
-| 8 | tableareaid | BIGINT | YES | （待补充） |
-| 9 | tablearea | TEXT | YES | （待补充） |
-| 10 | tableid | BIGINT | YES | （待补充） |
-| 11 | tablename | TEXT | YES | （待补充） |
-| 12 | trashreason | TEXT | YES | （待补充） |
-| 13 | createtime | TIMESTAMP | YES | （待补充） |
-| 14 | source_file | TEXT | YES | ETL 元数据：原始导出文件名，用于数据追溯 |
-| 15 | source_endpoint | TEXT | YES | ETL 元数据：采集来源（接口/文件路径），用于数据追溯 |
-| 16 | fetched_at | TIMESTAMPTZ | YES | ETL 元数据：采集/入库时间戳，用于口径对齐与增量处理 |
-| 17 | payload | JSONB | NO | ETL 元数据：完整原始 JSON 记录快照，用于回溯与二次解析 |
-| 18 | content_hash | TEXT | NO | ETL 元数据：对业务字段计算 SHA256，用于变更检测与去重 |
-| 19 | tenant_id | BIGINT | YES | 租户ID |
-
-## 使用说明
-
-```sql
--- 查询最新入库的记录
-SELECT * FROM ods.assistant_cancellation_records
-ORDER BY fetched_at DESC
-LIMIT 10;
-```
-
-```sql
--- 按业务主键查询某条记录的所有版本
-SELECT * FROM ods.assistant_cancellation_records
-WHERE id = <value>
-ORDER BY fetched_at DESC;
-```
-
-## ETL 元数据字段
-
-| 字段名 | 类型 | 说明 |
-|--------|------|------|
-| content_hash | TEXT | 对业务字段计算 SHA256，用于变更检测与去重 |
-| source_file | TEXT | 原始导出文件名，用于数据追溯 |
-| source_endpoint | TEXT | 采集来源（接口/文件路径），用于数据追溯 |
-| fetched_at | TIMESTAMPTZ | 采集/入库时间戳，用于口径对齐与增量处理 |
-| payload | JSONB | 完整原始 JSON 记录快照，用于回溯与二次解析 |
-
-## 可回溯性
-
-| 项目 | 说明 |
-|------|------|
-| 可回溯 | ✅ 完全可回溯（保留 payload 原始 JSON） |
-| 数据来源 | export/test-json-doc/assistant_cancellation_records.json |

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_GetAbolitionAssistant_assistant_cancellation_records.md

@@ -1,50 +0,0 @@
-# 助教撤销记录（GetAbolitionAssistant） → assistant_cancellation_records 字段映射
-
-> 生成时间：2026-02-14
-
-## 端点信息
-
-| 属性 | 值 |
-|------|-----|
-| 接口路径 | `AssistantPerformance/GetAbolitionAssistant` |
-| 请求方法 | POST |
-| ODS 对应表 | `ods.assistant_cancellation_records` |
-| JSON 数据路径 | `data.abolitionAssistants` |
-
-## 字段映射
-
-| JSON 字段 | ODS 列名 | 类型转换 | 说明 |
-|-----------|----------|----------|------|
-| id | id | int→BIGINT（`parse_int`） | 本表主键 ID，用于唯一标识一条记录 |
-| siteId | siteId | int→BIGINT（`parse_int`） | 门店 ID，即该废除记录所在门店 |
-| siteProfile | siteProfile | object→JSONB（原样存储） | 门店信息快照 |
-| assistantName | assistantName | string→TEXT（原样） | 助教姓名/对外展示名称 |
-| assistantAbolishAmount | assistantAbolishAmount | float→NUMERIC(18,2)（`parse_decimal`） | 与“助教废除”关联的金额字段 |
-| assistantOn | assistantOn | int→INT（`parse_int`） | 助教编号（工号/序号） |
-| pdChargeMinutes | pdChargeMinutes | int→INT（`parse_int`） | “已发生的计费时长（分钟）”，即这次助教服务在被废除前已经累计了多少分钟 |
-| tableAreaId | tableAreaId | int→BIGINT（`parse_int`） | 台桌所在区域 ID |
-| tableArea | tableArea | string→TEXT（原样） | 台桌所属区域名称 |
-| tableId | tableId | int→BIGINT（`parse_int`） | 球台/桌子的 ID |
-| tableName | tableName | string→TEXT（原样） | 台桌名称/编号，供人阅读 |
-| trashReason | trashReason | string→TEXT（原样） | 用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等 |
-| createTime | createTime | string→TIMESTAMP（`parse_timestamp`） | 这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻 |
-| tenant_id | tenant_id | int→BIGINT（`parse_int`） | 租户/品牌 ID |
-
-## ETL 补充字段
-
-| ODS 列名 | 生成逻辑 |
-|-----------|----------|
-| content_hash | 对业务字段（排除 ETL 元数据列）计算 SHA-256，用于变更检测与去重 |
-| source_file | 固定值：`assistant_cancellation_records.json`，标识原始导出文件 |
-| source_endpoint | API 端点路径，如 `AssistantPerformance/GetAbolitionAssistant` |
-| fetched_at | ETL 入库时间戳（`TIMESTAMPTZ DEFAULT now()`） |
-| payload | 完整原始 JSON 记录快照（`JSONB NOT NULL`），用于回溯与二次解析 |
-
-## 类型转换规则
-
-- **时间戳**：通过 `TypeParser.parse_timestamp()` 转换，支持 ISO 字符串和 Unix 毫秒时间戳，自动处理时区
-- **金额**：通过 `TypeParser.parse_decimal(value, scale=2)` 转换，`ROUND_HALF_UP` 四舍五入
-- **整数**：通过 `TypeParser.parse_int()` 转换，`None` 保持为 `NULL`
-- **字符串**：原样保留，`None` / 空字符串均存为 `NULL` 或空文本
-- **布尔值**：API 返回 `true/false`，ODS 存为 `BOOLEAN` 或 `INT`（0/1）
-- **JSONB**：`siteProfile`、`payload` 等复合对象直接以 `JSONB` 类型存储

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 完整保留 |