添加 羽心堂只筛选指定仓库

REFACTOR_PLAN.md

@@ -63,7 +63,7 @@ python3 list_feishu_base_tables.py --action sync-brand
 
 - `feishu`：读取飞书 Base 下的表信息。
 - `postgres`：执行 PostgreSQL 查询并输出结果。
-- `sync-brand`：按照 `BRAND_SYNC_TARGETS` 配置筛选品牌数据并同步到对应飞书表。
+- `sync-brand`：按照 `BRAND_SYNC_TARGETS` 中的品牌和仓库主键组合配置查询数据，并同步到对应飞书表。
 - `all`：依次执行飞书读取、数据库查询和品牌同步。
 
 ### 3.3 配置模块
@@ -102,7 +102,7 @@ FEISHU_APP_TOKEN
 
 职责：
 
-- 定义品牌到目标飞书表的同步配置。
+- 定义品牌、目标飞书表和仓库主键的组合同步配置。
 - 定义主字段名称和来源字段。
 - 定义 SQL 查询结果字段到飞书表字段的映射关系。
 - 定义飞书字段类型和数字格式。
@@ -112,12 +112,18 @@ FEISHU_APP_TOKEN
 
 ```python
 BRAND_SYNC_TARGETS = [
-    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂"),
+    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂", warehouse_keys=(2, 3, 7, 13)),
 ]
 PRIMARY_FIELD_NAME = "货品编码"
 PRIMARY_FIELD_SOURCE = "统一规格编码"
 ```
 
+`BrandSyncTarget` 中三个字段含义：
+
+- `brand_name`：SQL 中用于筛选 `pd."品牌名称"` 的品牌名称。
+- `table_name`：该品牌同步写入的飞书目标表名。
+- `warehouse_keys`：该品牌参与总库存汇总的仓库主键列表。
+
 当前字段映射和展示顺序：
 
 | 飞书字段名 | SQL 来源字段 | 飞书字段类型 | 显示格式 |
@@ -149,10 +155,11 @@ PRIMARY_FIELD_SOURCE = "统一规格编码"
 当前 SQL 逻辑包括：
 
 - 取每个统一规格编码、仓库的最新库存快照。
-- 汇总统一规格编码维度的总库存。
-- 取每个统一规格编码、店铺的最新挂单量快照。
-- 按店铺和统一规格编码汇总本月、上月、上上月销售数量。
+- 按当前品牌配置的 `warehouse_keys` 筛选仓库，并汇总统一规格编码维度的总库存。
+- 取每个统一规格编码、店铺的最新可发库存快照，并排除已失效状态。
+- 按统一规格编码汇总本月、上月、上上月销售数量。
 - 关联商品维表和店铺维表。
+- 按当前品牌配置的 `brand_name` 筛选品牌数据。
 - 输出用于飞书同步的明细结果。
 
 ### 3.6 PostgreSQL 模块
@@ -162,7 +169,7 @@ PRIMARY_FIELD_SOURCE = "统一规格编码"
 职责：
 
 - 使用 `.env` 中的数据库配置连接 PostgreSQL。
-- 执行 `inventory_sync/sql.py` 中定义的 SQL。
+- 根据 `BrandSyncTarget` 中的品牌和仓库主键配置生成并执行 SQL。
 - 将查询结果解析为结构化字典列表。
 - 对外返回统一结构，供 CLI 或同步服务使用。
 
@@ -190,8 +197,8 @@ PRIMARY_FIELD_SOURCE = "统一规格编码"
 职责：
 
 - 编排完整业务流程。
-- 根据配置查询 PostgreSQL。
-- 按 `BRAND_SYNC_TARGETS` 逐个筛选品牌数据。
+- 按 `BRAND_SYNC_TARGETS` 逐个读取品牌和仓库主键配置。
+- 根据每个品牌目标的配置查询 PostgreSQL。
 - 根据 `specs.py` 中的映射表构造飞书记录。
 - 确认目标飞书表字段存在且类型正确。
 - 删除目标表已有记录。
@@ -200,7 +207,7 @@ PRIMARY_FIELD_SOURCE = "统一规格编码"
 当前同步策略是全量覆盖：
 
 ```text
-查询 PostgreSQL -> 遍历品牌同步配置 -> 筛选目标品牌 -> 确认飞书字段 -> 删除目标表已有记录 -> 批量插入新记录
+遍历品牌同步配置 -> 按品牌和仓库主键查询 PostgreSQL -> 确认飞书字段 -> 删除目标表已有记录 -> 批量插入新记录
 ```
 
 ## 4. 执行方式
@@ -273,24 +280,24 @@ FieldSpec("新金额字段", "SQL查询结果金额字段名", 2, "0.00", 2)
 
 ## 7. 新增品牌同步方式
 
-当前版本已经使用 `BRAND_SYNC_TARGETS` 管理品牌和目标飞书表的对应关系，配置位置在 `inventory_sync/specs.py`：
+当前版本使用 `BRAND_SYNC_TARGETS` 管理品牌、目标飞书表和仓库主键的组合关系，配置位置在 `inventory_sync/specs.py`：
 
 ```python
 BRAND_SYNC_TARGETS = [
-    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂"),
+    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂", warehouse_keys=(2, 3, 7, 13)),
 ]
 ```
 
-后续新增品牌时，只需要在列表中增加一行，并确保飞书 Base 中存在同名或指定名称的目标表：
+后续新增品牌时，只需要在列表中增加一行，并确保飞书 Base 中存在同名或指定名称的目标表。每个品牌可以配置自己的仓库主键列表：
 
 ```python
 BRAND_SYNC_TARGETS = [
-    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂"),
-    BrandSyncTarget(brand_name="其他品牌", table_name="其他品牌"),
+    BrandSyncTarget(brand_name="羽心堂", table_name="羽心堂", warehouse_keys=(2, 3, 7, 13)),
+    BrandSyncTarget(brand_name="其他品牌", table_name="其他品牌", warehouse_keys=(9, 10)),
 ]
 ```
 
-执行 `python3 list_feishu_base_tables.py --action sync-brand` 时，程序会先查询一次 PostgreSQL，再按该列表逐个品牌同步。
+执行 `python3 list_feishu_base_tables.py --action sync-brand` 时，程序会遍历该列表。每个目标都会使用自己的 `brand_name` 和 `warehouse_keys` 生成 SQL，再同步到对应的飞书表。
 
 ## 8. 当前设计取舍