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

docs/database/BD_Manual_dws_goods_stock_summary.md

@@ -0,0 +1,80 @@
+# BD_Manual：DWS 库存汇总（日/周/月）
+
+> DWS 表：`dws.dws_goods_stock_daily_summary`、`dws.dws_goods_stock_weekly_summary`、`dws.dws_goods_stock_monthly_summary`
+> DWD 数据源：`dwd.dwd_goods_stock_summary`
+> 任务代码：`DWS_GOODS_STOCK_DAILY`、`DWS_GOODS_STOCK_WEEKLY`、`DWS_GOODS_STOCK_MONTHLY`
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dws/goods_stock_daily_task.py`、`goods_stock_weekly_task.py`、`goods_stock_monthly_task.py`
+> DDL 位置：`docs/database/ddl/etl_feiqiu__dws.sql`
+> 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__create_dws_goods_stock_summary.sql`（已归档）
+
+---
+
+## 1. 表结构（三张表结构相同）
+
+| DWS 列名 | 类型 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|-------------|
+| `site_id` | BIGINT | 门店 ID（PK 之一） | 飞球门店 ID |
+| `tenant_id` | BIGINT | 租户 ID | 飞球租户 ID |
+| `stat_date` | DATE | 统计日期（PK 之一）。日度=当天日期，周度=ISO 周一日期，月度=月首日期 | 如 `2026-01-15`、`2026-01-13`（周一）、`2026-01-01`（月首） |
+| `site_goods_id` | BIGINT | 门店商品 ID（PK 之一），关联 `dim_store_goods.site_goods_id` | 飞球商品 ID |
+| `goods_name` | TEXT | 商品名称 | 如 `百威啤酒` |
+| `goods_unit` | TEXT | 计量单位 | 如 `瓶`、`包` |
+| `goods_category_id` | BIGINT | 一级商品分类 ID | 飞球分类 ID |
+| `goods_category_second_id` | BIGINT | 二级商品分类 ID | 飞球分类 ID |
+| `category_name` | TEXT | 一级分类名称 | 如 `酒水` |
+| `range_start_stock` | NUMERIC | 期初库存（统计周期起点的库存量） | 数值 |
+| `range_end_stock` | NUMERIC | 期末库存（统计周期终点的库存量） | 数值 |
+| `range_in` | NUMERIC | 入库数量（统计周期内的采购/调拨入库总量） | 数值 |
+| `range_out` | NUMERIC | 出库数量（统计周期内的调拨出库/报损总量） | 数值 |
+| `range_sale` | NUMERIC | 销售数量（统计周期内的销售出库总量） | 数值 |
+| `range_sale_money` | NUMERIC(12,2) | 销售金额（元），统计周期内的销售总金额 | 金额值 |
+| `range_inventory` | NUMERIC | 盘点调整量（统计周期内的盘盈/盘亏净量） | 正/负数值 |
+| `current_stock` | NUMERIC | 当前库存（统计周期末的实时库存量） | 数值 |
+| `stat_period` | TEXT | 汇总粒度标识 | `'daily'` / `'weekly'` / `'monthly'` |
+| `created_at` | TIMESTAMPTZ | 记录创建时间 | 自动填充 `now()` |
+| `updated_at` | TIMESTAMPTZ | 记录最后更新时间 | 自动填充 `now()` |
+
+---
+
+## 2. 主键
+
+`(site_id, stat_date, site_goods_id)` — 按门店、日期、商品维度唯一。
+
+---
+
+## 3. 粒度说明
+
+| 表名 | 粒度 | stat_date 规则 | stat_period |
+|------|------|---------------|-------------|
+| `dws_goods_stock_daily_summary` | 日 | 当天日期 | `'daily'` |
+| `dws_goods_stock_weekly_summary` | 周 | ISO 周一日期 | `'weekly'` |
+| `dws_goods_stock_monthly_summary` | 月 | 月首日期（如 `2026-01-01`） | `'monthly'` |
+
+---
+
+## 4. 聚合逻辑
+
+- extract：从 `dwd.dwd_goods_stock_summary` 按时间范围查询
+- transform：按粒度对 `fetched_at` 进行分组聚合
+  - `range_start_stock`：取周期内最早记录的 `range_start_stock`
+  - `range_end_stock`：取周期内最晚记录的 `range_end_stock`
+  - `range_in` / `range_out` / `range_sale` / `range_inventory`：SUM 汇总
+  - `range_sale_money`：SUM 汇总
+  - `current_stock`：取周期内最晚记录的 `current_stock`
+  - `goods_name` / `goods_unit` / `category_name`：取最晚记录的值
+- load：upsert 写入目标表，主键冲突时更新
+
+---
+
+## 5. 前置依赖
+
+- `dwd.dwd_goods_stock_summary` 表必须已创建并有数据
+- ODS 任务配置 `requires_window=True` 必须已生效并重新采集
+
+---
+
+## 6. 代码引用
+
+- 任务代码：`tasks/dws/goods_stock_daily_task.py`、`goods_stock_weekly_task.py`、`goods_stock_monthly_task.py`
+- 继承：`BaseDwsTask`（`tasks/dws/base_dws_task.py`）
+- 任务注册：`DWS_GOODS_STOCK_DAILY`、`DWS_GOODS_STOCK_WEEKLY`、`DWS_GOODS_STOCK_MONTHLY`