root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Neo
2026-02-23 23:02:20 +08:00
parent 254ccb1e77
commit fafc95e64c
1142 changed files with 10366960 additions and 36957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
apps/etl/connectors/feiqiu/docs/database/DWD/Ex/BD_manual_dwd_assistant_trash_event_ex.md
View File

@@ -1,62 +0,0 @@
# dwd_assistant_trash_event_ex 助教服务作废扩展表
> 生成时间：2026-01-28
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | dwd |
| 表名 | dwd_assistant_trash_event_ex |
| 主键 | assistant_trash_event_id |
| 主表 | dwd_assistant_trash_event |
| 记录数 | 98 |
| 说明 | 助教服务作废扩展表，记录台桌和台区名称 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | assistant_trash_event_id | BIGINT | NO | PK | 作废事件 ID → dwd_assistant_trash_event |
| 2 | table_name | VARCHAR(64) | YES | | 台桌名称。**热门值**: "888"(14), "发财"(8), "C1"(7), "M7"(6) |
| 3 | table_area_name | VARCHAR(64) | YES | | 台区名称。**枚举值**: "C区"(16), "K包"(14), "A区"(11), "发财"(8), "B区"(7), "麻将房"(7), "补时长"(7), "VIP包厢"(6) |
## 台区作废分布
| 台区名称 | 作废次数 | 占比 |
|----------|----------|------|
| C区 | 16 | 16.3% |
| K包 | 14 | 14.3% |
| A区 | 11 | 11.2% |
| 发财 | 8 | 8.2% |
| B区 | 7 | 7.1% |
| 麻将房 | 7 | 7.1% |
| 补时长 | 7 | 7.1% |
| VIP包厢 | 6 | 6.1% |
## 样本数据
| table_name | table_area_name |
|------------|-----------------|
| C1 | C区 |
| 补时长5 | 补时长 |
| VIP1 | VIP包厢 |
| 888 | K包 |
## 使用说明
**版本与最新值**
本表为事实表，无 SCD2 版本字段。
- 主表可用时间字段：create_time
```sql
-- 取最新一条（按主表时间字段）
SELECT e.*
FROM dwd.dwd_assistant_trash_event m
JOIN dwd.dwd_assistant_trash_event_ex e ON m.assistant_trash_event_id = e.assistant_trash_event_id
ORDER BY m.create_time DESC NULLS LAST
LIMIT 1;
```
**使用示例**
与主表 `dwd_assistant_trash_event` 通过 `assistant_trash_event_id` 关联，提供台桌和台区名称信息。

0
apps/etl/connectors/feiqiu/docs/database/DWD/changes/.gitkeep Normal file
View File

85
apps/etl/connectors/feiqiu/docs/database/DWD/changes/2026-02-13_ddl_sync_dwd.md
View File

@@ -1,85 +0,0 @@
# DWD 层 DDL 同步修正 — 变更记录
> 结构性变更：修正 1 项差异（补充 1 个缺失字段定义）
## 溯源
- 日期：2026-02-13（Asia/Shanghai）
- 工具：`scripts/compare_ddl_db.py --schema dwd --ddl-path database/schema_dwd_doc.sql`
- Direct cause：DDL 对比脚本发现 `database/schema_dwd_doc.sql` 与数据库 `dwd` schema 实际状态存在 1 项差异，以数据库为准修正 DDL 文件。
## 变更内容
| Schema | 表名 | 操作 | 字段 | DDL 原定义 | 数据库实际 | 说明 |
|--------|------|------|------|-----------|-----------|------|
| `dwd` | `dwd_refund_ex` | DDL 补充字段 | `check_status` | — | `INTEGER` | 数据库中有但 DDL 中未定义（解析器 bug 导致遗漏，已修复） |
## 变更原因
1. `dwd_refund_ex.check_status`：该字段实际已存在于数据库中，对应 ODS 层 `refund_transactions.check_status`（退款审核状态）
2. DDL 解析器存在 bug 导致该字段在先前对比中被遗漏，修复解析器后重新对比发现此差异
3. 该字段由 DWD 加载任务从 ODS 层 `refund_transactions` 映射而来
## 影响范围
| 影响对象 | 影响程度 | 说明 |
|----------|----------|------|
| ETL 加载任务 | 无影响 | 本次仅修正 DDL 文档，不涉及数据库结构变更 |
| 后端 API | 无影响 | DDL 文件为文档性质，不影响运行时 |
| 小程序字段映射 | 无影响 | 小程序不直接读 DWD 层 |
| DWD 表级文档 | ⚠️ 需同步 | `BD_manual_dwd_refund_ex.md` 字段列表应包含 `check_status` |
| ODS→DWD 映射 | 无影响 | `check_status` 已在 DWD 加载映射中正确配置 |
**注意**：本次变更仅修正 DDL 文件（文档同步），数据库结构未发生任何变更。
## 回滚策略
本次为 DDL 文件修正（文档同步），无需数据库回滚。若需恢复 DDL 文件，使用 Git 回退即可：
```bash
git checkout HEAD~1 -- database/schema_dwd_doc.sql
```
若未来需要将数据库结构回退（不推荐）：
```sql
-- 删除 check_status 列（会丢失已有数据）
ALTER TABLE dwd.dwd_refund_ex DROP COLUMN check_status;
```
## 验证 SQL
```sql
-- 1) 确认 dwd_refund_ex.check_status 存在且类型为 integer
SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_schema = 'dwd'
AND table_name = 'dwd_refund_ex'
AND column_name = 'check_status';
-- 预期：1 行，data_type = 'integer'
-- 2) 确认 ODS 层对应字段也存在（数据来源一致性）
SELECT column_name, data_type
FROM information_schema.columns
WHERE table_schema = 'ods'
AND table_name = 'refund_transactions'
AND column_name = 'check_status';
-- 预期：1 行，data_type = 'integer'
-- 3) 确认 dwd_refund_ex 表当前总列数
SELECT count(*) AS total_columns
FROM information_schema.columns
WHERE table_schema = 'dwd'
AND table_name = 'dwd_refund_ex';
-- 预期：列数包含 check_status
-- 4) 确认修正后 DDL 与数据库零差异（通过对比脚本验证）
-- python scripts/compare_ddl_db.py --schema dwd --ddl-path database/schema_dwd_doc.sql
-- 预期：0 项差异
```
## 关联变更
- ODS 层同步修正：`docs/database/ODS/changes/2026-02-13_ddl_sync_ods.md`（`refund_transactions.check_status` 同步补充）
- DDL 文件：`database/schema_dwd_doc.sql`
- 对比结果：`docs/database/ddl_compare_results.md`

94
apps/etl/connectors/feiqiu/docs/database/DWD/changes/20260214_drop_dwd_settle_list.md
View File

@@ -1,94 +0,0 @@
# DWD 层删除 dwd_settlement_head_ex.settle_list 冗余列 — 变更记录
> 结构性变更：删除 1 张表的 1 个 JSONB 列
## 溯源
- 日期：2026-02-14（Asia/Shanghai）
- Prompt：P20260214-040000 — 删除 DWD 层 dwd_settlement_head_ex 的 settle_list JSONB 列
- Direct cause：`settle_list` 列存储结算明细 JSON，与 ODS 层 `payload` 中的 `settleList` 对象完全重复。ODS 层 `settlelist` 列已在 `20260214_drop_ods_settlelist.sql` 中删除，DWD 层该列同样冗余。结算明细可随时从 ODS `payload->'settleList'` 按需提取。
## 变更内容
| Schema | 表名 | 操作 | 列名 | 原类型 | 说明 |
|--------|------|------|------|--------|------|
| `dwd` | `dwd_settlement_head_ex` | DROP COLUMN | `settle_list` | `JSONB` | 结算明细 JSON，与 ODS payload 中 settleList 重复 |
### Before / After
- Before：31 个字段（order_settle_id PK + 29 个业务字段 + settle_list JSONB）
- After：30 个字段（order_settle_id PK + 29 个业务字段）
## 变更原因
1. ODS 层 `settlement_records.payload`（jsonb）已存储完整 API 响应，其中包含 `settleList` 对象
2. ODS 层 `settlelist` 列已在同日迁移 `20260214_drop_ods_settlelist.sql` 中删除
3. DWD 层 `settle_list` 是从 ODS `settlelist` 映射而来的副本，上游已删除，DWD 层同步清理
4. DWD 加载映射（`dwd_load_task.py` FACT_MAPPINGS）中 `settle_list` 映射已移除
## 影响范围
| 影响对象 | 影响程度 | 说明 |
|----------|----------|------|
| DWD 加载任务 | ✅ 已处理 | `dwd_load_task.py` FACT_MAPPINGS 中 `dwd_settlement_head_ex` 的 `settle_list` 映射已移除 |
| DWS 汇总层 | 无影响 | DWS 层不消费 `settle_list` 列 |
| API 契约 | 无影响 | API 响应结构不变 |
| 小程序 | 无影响 | 小程序不直接读 DWD 层 |
| BD 手册 | ✅ 已处理 | `BD_manual_dwd_settlement_head_ex.md` 字段列表已不含 `settle_list` |
## 回滚策略
```sql
-- 1) 恢复列结构
ALTER TABLE dwd.dwd_settlement_head_ex ADD COLUMN settle_list JSONB;
-- 2) 从 ODS payload 回填数据
UPDATE dwd.dwd_settlement_head_ex e
SET settle_list = o.payload->'settleList'
FROM ods.settlement_records o
WHERE e.order_settle_id = o.id;
```
**注意事项**：
- 回滚后 `settle_list` 列数据为 NULL，必须执行回填 UPDATE
- 若 ODS 中 `payload IS NULL` 的行，对应 DWD 行的 `settle_list` 将为 NULL（无法恢复）
## 验证 SQL
```sql
-- 1) 确认 settle_list 列已不存在
SELECT column_name
FROM information_schema.columns
WHERE table_schema = 'dwd'
AND table_name = 'dwd_settlement_head_ex'
AND column_name = 'settle_list';
-- 预期：0 行
-- 2) 确认表当前列数
SELECT count(*) AS total_columns
FROM information_schema.columns
WHERE table_schema = 'dwd'
AND table_name = 'dwd_settlement_head_ex';
-- 预期：30（order_settle_id + 29 个业务字段）
-- 3) 确认 ODS payload 中 settleList 仍可按需提取
SELECT count(*)
FROM ods.settlement_records
WHERE payload IS NOT NULL AND payload->'settleList' IS NOT NULL;
-- 预期：> 0（结算明细数据仍可从 ODS 获取）
-- 4) 确认 DWD 表数据完整性（主表-扩展表行数一致）
SELECT
(SELECT count(*) FROM dwd.dwd_settlement_head) AS main_count,
(SELECT count(*) FROM dwd.dwd_settlement_head_ex) AS ex_count;
-- 预期：两个计数相等
```
## 迁移文件
`database/migrations/20260214_drop_dwd_settle_list.sql`
## 关联变更
- ODS 层同日变更：`database/migrations/20260214_drop_ods_settlelist.sql`（删除 `settlement_records.settlelist` 和 `recharge_settlements.settlelist`）
- BD 手册 ODS 变更记录：`docs/database/ODS/changes/20260214_drop_ods_settlelist.md`

44
apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff.md Normal file
View File

@@ -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`）是完全独立的实体

51
apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dim_staff_ex.md Normal file
View File

@@ -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 | | 版本号 |

56
apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dwd_assistant_trash_event.md
View File

@@ -1,56 +0,0 @@
# dwd_assistant_trash_event 助教服务作废主表
> 生成时间：2026-01-28
## 表信息
| 属性 | 值 |
|------|-----|
| Schema | dwd |
| 表名 | dwd_assistant_trash_event |
| 主键 | assistant_trash_event_id |
| 扩展表 | dwd_assistant_trash_event_ex |
| 记录数 | 98 |
| 说明 | 助教服务作废事实表，记录被取消/作废的助教服务记录 |
## 字段说明
| 序号 | 字段名 | 类型 | 可空 | 主键 | 说明 |
|------|--------|------|------|------|------|
| 1 | assistant_trash_event_id | BIGINT | NO | PK | 作废事件 ID |
| 2 | site_id | BIGINT | YES | | 门店 ID |
| 3 | table_id | BIGINT | YES | | 台桌 ID → dim_table |
| 4 | table_area_id | BIGINT | YES | | 台区 ID |
| 5 | assistant_no | VARCHAR(32) | YES | | 助教工号/昵称。**样本值**: "七七", "乔西", "球球"等 |
| 6 | assistant_name | VARCHAR(64) | YES | | 助教名称，与 assistant_no 相同 |
| 7 | charge_minutes_raw | INTEGER | YES | | 原计费时长（秒）。**样本值**: 0, 3600=1h, 10800=3h 等 |
| 8 | abolish_amount | NUMERIC(18,2) | YES | | 作废金额（元）。**样本值**: 0.00, 190.00, 570.00 等 |
| 9 | trash_reason | VARCHAR(255) | YES | | 作废原因（当前数据全为 NULL） |
| 10 | create_time | TIMESTAMPTZ | YES | | 创建时间 |
| 11 | tenant_id | BIGINT | YES | | 租户 ID |
## 使用说明
**版本与最新值**
本表为事实表，无 SCD2 版本字段。
- 可用时间字段：create_time
```sql
-- 取最新一条（按时间字段倒序）
SELECT *
FROM dwd.dwd_assistant_trash_event
ORDER BY create_time DESC NULLS LAST
LIMIT 1;
```
**使用示例**
```sql
-- 助教作废金额统计
SELECT
assistant_name,
COUNT(*) AS trash_count,
SUM(abolish_amount) AS total_abolished
FROM dwd.dwd_assistant_trash_event
GROUP BY assistant_name
ORDER BY total_abolished DESC;
```