Add philosophy and wsf directories

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

wsf/bd/README.md

@@ -0,0 +1,49 @@
+---
+title: 万师傅大数据知识库（wiki 索引）
+source_status: 汇编自 sql-agent-demo 项目的 knowledge/、skills/、docs/、data/、queries/
+updated_at: 2026-07-30
+---
+
+# 万师傅大数据知识库
+
+这是从 [sql-agent-demo](../sql-agent-demo) 项目中提炼出的人类可读知识库。
+`sql-agent-demo/knowledge/*.json` 是给 Agent 运行时读的机器规则（强约束、字段固定），本 wiki 是同一批知识的说明版，
+补充背景和取舍理由，供人阅读、评审和向新成员讲解。两边内容应保持一致；改规则先改 JSON（或先在这里达成一致再回填 JSON），
+不要让两处各说各话。
+
+## 文件索引
+
+| 文件 | 内容 |
+|---|---|
+| [warehouse.md](warehouse.md) | 数仓分层架构、选表规则、分区语义、层间依赖边界 |
+| [sql-rules.md](sql-rules.md) | SQL 查询安全规范、只读执行边界、分析师取数脚本部署规范 |
+| [business.md](business.md) | 指标口径、业务枚举、已知歧义点、真实业务 SQL 案例 |
+| [decisions.md](decisions.md) | 冲突裁决记录、已确认/待确认问题（只追加，不改历史条目） |
+| [tables/](tables/README.md) | `wanshifu_dw` 表目录：ODS/DWD/DWS/DIM/ADS/MID 约5579张表的表名、字段和中文注释（元数据快照，非 DDL） |
+| [biz/](biz/README.md) | 万师傅平台级通用业务知识（角色定义、跨域事件链路），抽取自 dev-knowledge-base，不含 SQL/表结构 |
+
+## 知识优先级（对应 `knowledge/index.json`）
+
+当不同来源的说法冲突时，按以下顺序取高优先级来源，并在 [decisions.md](decisions.md) 里保留冲突记录：
+
+1. 用户为本 Agent 确认的规则（`user_confirmed_agent_rule`）
+2. 分析师/商业分析师数仓开发规范（`analyst_development_standard`）
+3. 已验证的表级知识（`verified_table_level_knowledge`）
+4. 万师傅数仓开发规范（`warehouse_development_standard`）——仅作设计学习参考
+5. 已验证的加工代码（`verified_job_code`）
+6. DDL 元数据（`ddl_metadata`）
+7. 表名推断（`table_name_inference`）——最低优先级，仅在无其他证据时使用
+
+## 原始规范文档指针
+
+以下文档目前只在 [decisions.md](decisions.md) 中被引用，本 wiki 未内嵌其原文，需要时向对应负责人获取：
+
+- 《数据分析师_商业分析师数仓开发规范.md》v2.0.0（2026-06-02 生效）—— 分析师主规范
+- 《万师傅数仓开发规范.md》v1.5.0（2026-06-01 生效）—— 数仓设计学习参考
+- 《万师傅数仓现状_订单数据架构.md》—— 订单域参考
+
+## 维护约定
+
+- 新增知识前先判断属于哪个优先级层，写清 `source_status` 和确认日期。
+- 只有 [decisions.md](decisions.md) 允许追加式记录历史；其余文件维护"当前有效状态"，改了直接覆盖旧内容，版本历史交给 git。
+- 中文写解释和背景，表名、字段名、状态码、枚举值等机器接口标识符保留原文（不翻译、不改写大小写）。

wsf/bd/business.md

@@ -0,0 +1,51 @@
+---
+title: 业务口径与真实案例
+source_status: 混合——枚举为 user_confirmed；catalog 指标定义来自 sql-agent-demo 演示数据，非生产正式口径
+---
+
+# 业务口径与真实案例
+
+## 1. 罚单业务（`penalty_sheet`，已用户确认，2026-07-22）
+
+`business_type` 枚举：
+
+| 值 | 含义 |
+|---|---|
+| `not_timely_sign_in` | 超时签到 |
+| `master_refused_service` | 拒绝服务 |
+| `not_timely_reserve` | 超时预约 |
+
+来源表：`wanshifu_dw.dwd_iop_penalty_sheet_base_handle_v`。
+
+**已验证的取数模式（见 [queries/](../sql-agent-demo/queries)）：**
+
+- 判定"最新一条罚单处理记录"：按 `penalty_sheet_id, object_id` 分组，`ROW_NUMBER() OVER (PARTITION BY penalty_sheet_id, object_id ORDER BY update_time DESC, callback_time DESC, penalty_handle_id DESC)` 取 `row_num = 1`。
+- 有效罚单过滤：`NVL(is_delete, 0) = 0`、`object_type = 'master'`、`master_source_type = 'tob'`、`strategy_type = 'punish'`、`strategy = 'cash'`，且 `extra_status IN ('wait_pay', 'paid')`。
+- 日报/周报/月报（[penalty_daily_report.sql](../sql-agent-demo/queries/penalty_daily_report.sql)、[penalty_weekly.sql](../sql-agent-demo/queries/penalty_weekly.sql)、[penalty_monthly_report.sql](../sql-agent-demo/queries/penalty_monthly_report.sql)）核心指标：去重扣款师傅数（`COUNT(DISTINCT master_id)`）、去重罚单数（`COUNT(DISTINCT penalty_sheet_id)`）、已实际支付的师傅数（`extra_status = 'paid'` 时再去重）。
+- 师傅扣款月报（[penalty_master_deduction_monthly_report.sql](../sql-agent-demo/queries/penalty_master_deduction_monthly_report.sql)）在此基础上按师傅维度展开扣款明细。
+
+这一组 SQL 是"分区+口径+去重"写法的可复用范本：判定最新状态用窗口函数去重、有效性过滤在 CTE 里显式列出、汇总指标全部基于去重后的 `_valid` CTE 计算，避免同一罚单多条状态记录重复计数。
+
+## 2. 指标定义示例（来自演示数据 `data/catalog.json`，非正式生产口径，仅作口径记录格式参考）
+
+| 指标 | 别名 | 定义 | 表达式 | 来源表 | 过滤条件 |
+|---|---|---|---|---|---|
+| 销售额 | GMV、成交金额 | 已支付且非测试订单的商品成交金额，不扣除后续退款 | `SUM(pay_amount)` | `fact_orders` | `pay_status='PAID'`、`is_test=0` |
+| 订单量 | 支付订单数 | 已支付且非测试订单去重数 | `COUNT(DISTINCT order_id)` | `fact_orders` | 同上 |
+| 新客销售额 | — | **存在歧义**：候选定义为"用户首次支付发生在统计期内"或"用户首次下单发生在统计期内" | 需先选定新客定义 | — | — |
+
+> "新客销售额"是一个真实会卡住 Agent/分析师的典型歧义案例：两种候选定义会得到不同结果，必须先向业务方确认口径，不能自行假设。遇到类似"首次 X"型指标，先检查是否也存在这种候选定义分叉。
+
+## 3. Agent 工作流对业务口径的处理原则
+
+来自 [sql-requirement-review](../sql-agent-demo/skills/sql-requirement-review/SKILL.md) 等 Skill 协议，是通用的取数口径澄清方法论，不局限于本项目：
+
+- 需求信息分三类：`CONFIRMED`（用户明确给出或已批准口径）、`DERIVED`（可直接推导且不改变指标含义）、`UNKNOWN`（缺失后会导致不同结果，必须确认）。
+- 迭代需求要先区分 `NEW`/`EXISTING`/`UNCLEAR` 范围；存在历史模块时优先要历史 SQL 或已部署任务，历史实现只能作证据，不能自动升级为正确口径。
+- 只问真正影响结果的问题，并合并相关问题一起问；能靠 DDL/表元数据自己查到的信息不要求用户回答。
+- 检查聚合和重复计算风险：明确一行代表什么、什么去重、是否有一对多关联、是否混淆累计值与期间值。
+
+## 相关
+
+- 数仓表选型和分区规则见 [warehouse.md](warehouse.md)。
+- SQL 写法规范见 [sql-rules.md](sql-rules.md)。

wsf/bd/decisions.md

@@ -0,0 +1,55 @@
+---
+title: 冲突裁决与决策记录（只追加，不改历史条目）
+source_status: 汇编自 knowledge/governance/conflicts-and-open-questions.json 与 docs/sql-agent-design.md 决策记录
+---
+
+# 冲突裁决与决策记录
+
+本文件只追加。新增决策写在对应表格末尾并带日期；已确认的历史条目不得回改或删除，
+后续如果推翻旧决策，新增一条记录说明"取代了哪条"，而不是编辑旧条目。
+
+## 已裁决冲突
+
+| 主题 | 数仓开发规范说法 | 分析师/Agent 规则 | 裁决 |
+|---|---|---|---|
+| ADS 前缀 | `ads_ds_`、`ads_bi_`、`ads_iBigdata_` | `ads_analyze_` + `ds`/`bi`/`ibigdata` | 本 Agent 场景用分析师规则 |
+| MID 前缀 | `mid_` | `mid_analyze_` | 本 Agent 场景用分析师规则 |
+| 计数后缀语义 | `times`=非去重，`cnt`=去重 | `cnt`=非去重，`num`=去重 | 分析师产出统一用分析师标准 |
+| 分区谓词范围 | 文档字面写"禁止全表扫描" | 用户确认：只有分区表需要分区谓词，非分区表允许全表扫描 | 用用户确认规则 |
+
+## 已确认问题（带日期）
+
+| 日期 | 主题 | 结论 |
+|---|---|---|
+| 2026-07-21 | 生产 SQL 自动执行 | 第一阶段不自动执行，由用户在 WeData 人工运行 |
+| 2026-07-21 | 元数据采集范围 | 按需逐表查询，不做全量 DDL 采集 |
+| 2026-07-21 | 数据库范围 | 只用 `wanshifu_dw`，排除 `wanshifu_enterprise` |
+| 2026-07-21 | ODS 新旧套选择 | 新旧套同时存在时优先 `_v` |
+| 2026-07-22 | 周表 `stat_date` 语义 | 不设默认值；生成部署脚本前必须询问用户是周起始/周结束/其他业务日期 |
+| 2026-07-22 | MID 依赖 | MID 不能依赖另一个 MID |
+| 2026-07-22 | 业务时间分区缺少范围 | 必须询问用户，不自动查近三年 |
+| 2026-07-24 | 元数据访问权限 | 改用受限专用密钥，正式环境只开放所需只读元数据接口；提示词/Skill 层禁止规则不作为权限边界 |
+| 2026-07-24 | 表字段就绪校验范围 | 必须同时检查普通字段和 `PARTITIONED BY` 分区字段，禁止把已存在的分区字段误报为待接入 |
+| 2026-07-27 | 中文 SQL 常量编码故障 | 两次真实查询证明 JDBC/Kyuubi 链路可能使中文常量失真；诊断和降级规则见 [sql-rules.md](sql-rules.md) |
+
+## 待确认问题
+
+- 分区语义证据优先级的建议顺序（`verified_table_level_knowledge` > `verified_job_code` > DDL 分区定义和注释 > 表名推断 > 询问用户）尚待正式确认。
+- 是否每个物理临时表在成功和重跑两种场景下都必须执行 DROP 清理，尚待确认。
+- 公司 Agent 平台的 Skill/Tool/状态存储协议尚未定稿。
+- SQL 开发规范的正式内容（除已提炼部分外）尚未完整获取。
+- 指标口径来源和版本管理方式尚未定稿。
+- 多轮会话状态保存周期尚未定稿。
+- 未来 WeData 只读执行器的权限、审批和资源限制尚未定稿。
+
+## 原始规范文档指针（未内嵌全文）
+
+| 文档 | 版本 | 生效日期 | 角色 |
+|---|---|---|---|
+| 数据分析师_商业分析师数仓开发规范.md | 2.0.0 | 2026-06-02 | 分析师主规范 |
+| 万师傅数仓开发规范.md | 1.5.0 | 2026-06-01 | 数仓设计学习参考 |
+| 万师傅数仓现状_订单数据架构.md | — | — | 订单域参考 |
+
+## 相关
+
+- 规则本体见 [warehouse.md](warehouse.md)、[sql-rules.md](sql-rules.md)、[business.md](business.md)。

wsf/bd/sql-rules.md

@@ -0,0 +1,70 @@
+---
+title: SQL 查询规范、只读执行边界与部署脚本规范
+source_status: user_confirmed_agent_rule
+---
+
+# SQL 查询规范、只读执行边界与部署脚本规范
+
+## 1. 交互式查询规范（临时取数）
+
+- 只允许一条只读 `SELECT`、`WITH` 或 `EXPLAIN`；禁止 DDL、DML、管理命令、多语句、注释。
+- 禁止 `SELECT *`；使用显式字段和全限定表名（`wanshifu_dw.<table>`）。
+- JOIN 必须写明确关联条件，禁止笛卡尔积；写 JOIN 前先确认两侧粒度和唯一键，防止行数放大。
+- 分区表做分区裁剪，非分区表允许全表扫描（不要为非分区表编造分区条件）。
+- 按指标定义要求显式加业务时间过滤。
+- 默认不暴露敏感明细字段。
+- 超时上限：1800 秒。
+
+**格式约定：**关键字大写；表名字段名小写；缩进 4 空格；SELECT 列表一行一个字段、逗号前置；复杂逻辑在生成脚本中加业务注释，只有在安全执行器要求时才删除注释。
+
+**指标后缀语义（分析师标准，优先于数仓开发规范里的旧例子）：**
+
+| 后缀 | 含义 |
+|---|---|
+| `cnt` | 非去重的事件/人次计数 |
+| `num` | 去重后的实体计数 |
+| `amt` | 金额 |
+
+> 注意：数仓开发规范里的示例是反过来的（`times`=非去重，`cnt`=去重）。分析师产出统一使用上表，冲突已裁决，见 [decisions.md](decisions.md)。
+
+## 2. 只读执行边界（JDBC / Kyuubi-Hive）
+
+- 默认关闭，需经安全评审后显式开启。
+- 只放行单条 `SELECT`、`WITH`、`EXPLAIN`；要求全限定 `wanshifu_dw` 表名和时间/分区谓词；拒绝注释、`SELECT *`、DDL、DML、管理命令和高危函数。
+- `Connection.setReadOnly(true)` 只是辅助信号，**不是安全边界**——Kyuubi 明确不支持它，真正边界是数据库只读权限 + Python 策略层与 Java JDBC 层的双重校验。
+- 执行器只用 `executeQuery`，同时限制超时（120s 登录超时 / 30s 及以上按配置）和结果行数（默认导出上限 100,000 行且 100MB；聊天展示默认 100 行）。
+- 普通查询不留文件；只有用户明确要求导出才保留最终文件，且需清理中间文件。
+- **中文常量编码降级（重要坑点）：**JDBC/Kyuubi 链路可能让中文字符串常量失真，导致中文显示为问号或精确过滤误返回 0 行。
+  - 默认继续提交原始 UTF-8 SQL，不预先改写中文条件。
+  - 出现空结果或异常结果时，先用同分区/时间范围内的纯 ASCII 条件 + `HEX(ENCODE(TRIM(field), 'UTF-8'))` 诊断，证明目标中文值确实存在且原条件未命中，才能判定是编码问题而非业务无数据。
+  - 只对已证明等价的精确 `=`/`IN` 条件做十六进制降级；`LIKE`、正则、范围、排序等依赖字符归一化的条件禁止自动转换，必须退回审查。
+  - 降级 SQL 必须重新走安全校验；执行记录要保留 `ENCODING_FALLBACK_APPLIED`、原始/实际 SQL 哈希及字面量映射。
+  - 十六进制过滤可能影响谓词下推，只作临时兜底；长期应修复链路的字符编码配置。
+
+## 3. 分析师取数脚本部署规范（ADS/MID）
+
+**触发条件：**只有用户在查询结果验证通过后明确要求生成部署脚本才执行；本环节只生成 SQL，**不执行、不建 WeData 任务、不部署、不提交审批**。
+
+**命名：**
+
+| 层 | 前缀 | 分区表后缀 | 非分区表后缀 |
+|---|---|---|---|
+| ADS | `ads_analyze_` + 子类型（`ds`/`bi`/`ibigdata`） | `_d_v` | `_v` |
+| MID | `mid_analyze_` | `_d_v` | `_v` |
+
+> 注意：这套前缀是"分析师 Agent 规则"，跟数仓开发规范里的 `ads_ds_`/`ads_bi_`/`ads_iBigdata_`、`mid_` 不同。本 Agent 场景一律用分析师规则，冲突已裁决，见 [decisions.md](decisions.md)。
+
+**依赖：**只能依赖 DWD/DWS/DWM/DIM/MID；禁止依赖 ODS、ADS、其他脚本的临时表。
+
+**分区字段：**统一用 `stat_date`；日表 `yyyyMMdd`、月表 `yyyyMM`、年表 `yyyy`；**周表的 `stat_date` 语义（周起始/周结束/其他业务日期）没有默认值，生成脚本前必须询问用户**。
+
+**生命周期天数：**`bi`=365 天；`ibigdata`=90 天；`mid`=与下游一致；`ds`=需向需求方确认。
+
+**输出内容：**每个任务只对应一张正式目标表；允许脚本内使用物理临时表但必须清理（命名 `tmp_{table}_{bizdate}_{sequence}`）；产出应包含建表 SQL、写入 SQL、验证 SQL 和部署检查清单；默认不生成删除目标表的语句。
+
+**运行时长上限：**1800 秒。
+
+## 相关
+
+- 数仓分层、选表、分区规则见 [warehouse.md](warehouse.md)。
+- 冲突裁决细节见 [decisions.md](decisions.md)。

wsf/bd/tables/README.md

@@ -0,0 +1,95 @@
+---
+title: wanshifu_dw 表目录（元数据索引，非 DDL）
+source_status: ddl_metadata（来自 WeData `DescribeTableMetas` 接口的表/字段元数据，非人工确认口径）
+fetched_at: 2026-07-30
+---
+
+# `wanshifu_dw` 表目录
+
+通过腾讯云 WeData API 的 `DescribeTableMetas`（表清单接口）批量抓取生成，**没有调用 `DescribeTableDdl`**——
+按用户要求，这一步只建索引，不批量拉 DDL。但 `DescribeTableMetas` 本身已经返回了字段名、字段类型、
+字段中文注释和分区信息，覆盖率相当高（见下表），对大多数表已经够用；真正需要完整 DDL（含建表属性、
+存储格式等）时再针对单张表调用 `scripts/get_wedata_ddl.py` 或 `skills/wedata-table-readiness`。
+
+## 抓取范围与覆盖率
+
+`wanshifu_dw` 库总共 24,360 张表（含大量测试/临时表，如 `abc_1`），本次只抓取核心数仓分层前缀，
+按用户选择跳过了 ODS 之外无法识别命名规律的表：
+
+| 文件 | 前缀 | 表数 | 有字段注释 | 分区表数 | 新套 `_v` 表数 |
+|---|---|---|---|---|---|
+| [ods.json](ods.json) | `ods_` | 2194 | 2182（99%） | 2045 | 487 |
+| [dwd.json](dwd.json) | `dwd_` | 2445 | 2396（98%） | 1755 | 221 |
+| [dws.json](dws.json) | `dws_` | 638 | 573（90%） | 189 | 48 |
+| [dim.json](dim.json) | `dim_` | 277 | 239（86%） | 22 | 85 |
+| [ads_analyze.json](ads_analyze.json) | `ads_analyze_` | 25 | 17（68%） | 0 | 5 |
+| [mid_analyze.json](mid_analyze.json) | `mid_analyze_` | 0 | — | — | — |
+
+合计约 **5579 张表**。`mid_analyze_` 前缀当前一张表都没有——说明分析师规范里定义的 `mid_analyze_` 命名规则
+还没有实际落地的表，需要时应先跟数仓侧确认这一层是否已启用。
+
+未抓取：`wanshifu_enterprise` 库（项目规则明确排除）；`wanshifu_dw` 里不匹配 `ods_/dwd_/dws_/dim_/ads_analyze_/mid_analyze_`
+前缀的表（含大量无法识别层级的历史/测试表，以及数量极少的 `ads_` 非 analyze 子类型表）。
+
+## 数据结构
+
+每个 JSON 文件结构：
+
+```json
+{
+  "database": "wanshifu_dw",
+  "prefix": "ods_",
+  "count": 2194,
+  "source": "DescribeTableMetas (list + column comments, no DDL fetched)",
+  "fetched_at": "2026-07-30 10:53:xx",
+  "tables": [
+    {
+      "table_id": "...",
+      "database": "wanshifu_dw",
+      "table": "ods_account_info_n",
+      "project": "...",
+      "technology_type": "HIVE",
+      "is_view": false,
+      "is_partition_table": true,
+      "partition_columns": ["etl_date"],
+      "create_time": "...",
+      "modify_time": "...",
+      "columns": [
+        {"name": "...", "type": "...", "comment": "...", "is_partition": false}
+      ],
+      "layer": "ODS",
+      "suite": "new_v",
+      "incremental_name": false,
+      "full_snapshot_name": true
+    }
+  ]
+}
+```
+
+`layer`/`suite`/`incremental_name`/`full_snapshot_name` 是按 [../warehouse.md](../warehouse.md) 里的选表规则
+从表名推断出来的（`table_name_inference`，知识优先级里最低一档，仅供参考，实际选表仍要看字段是否满足需求）。
+
+出于脱敏考虑，**没有保留** `TableProperties`（存储路径、SerDe 等实现细节，含 COS 路径，等同于 DDL 里会被脱敏的 `LOCATION` 属性）。
+
+## 已知局限
+
+- 字段注释是数仓开发时手工填的，不是每张表都填了（尤其 `dim`/`ads_analyze` 层覆盖率明显更低）；空注释不代表字段没有业务含义，只代表没人补录。
+- 这只是元数据快照（抓取于 2026-07-30），表结构可能已变化；正式写 SQL 前仍应走 `wedata-table-readiness` 重新核实。
+- 分区语义（`full_snapshot_name` 等）是按表名规则推断的粗略标注，不是"已验证的表级知识"；具体到某张表要不要按 `T-1` 过滤，仍按 [../warehouse.md](../warehouse.md) 里的规则最终核实。
+- 未抓取字段级血缘、上下游依赖——这依然需要 `DescribeLineageInfo`，按需单表查询。
+
+## 下一步：单表 DDL 按需获取
+
+需要某张表完整 DDL（建表语句、存储属性等）时，不要重跑本目录的批量抓取，改用现有单表工具：
+
+```bash
+python scripts/get_wedata_ddl.py <table_id>
+```
+
+或走完整就绪检查（含血缘、字段满足度判断）：
+
+```bash
+python skills/wedata-table-readiness/scripts/readiness.py --input request.json
+```
+
+`table_id` 可以直接从本目录对应 JSON 文件里的 `table_id` 字段查到，不用再调 `DescribeTableMetas` 按名字反查一次。

wsf/bd/tables/_summary.json

@@ -0,0 +1,8 @@
+{
+  "ods": 2194,
+  "dwd": 2445,
+  "dws": 638,
+  "dim": 277,
+  "ads_analyze": 25,
+  "mid_analyze": 0
+}

wsf/bd/tables/mid_analyze.json

@@ -0,0 +1,8 @@
+{
+  "database": "wanshifu_dw",
+  "prefix": "mid_analyze_",
+  "count": 0,
+  "source": "DescribeTableMetas (list + column comments, no DDL fetched)",
+  "fetched_at": "2026-07-30 10:54:15",
+  "tables": []
+}

wsf/bd/warehouse.md

@@ -0,0 +1,67 @@
+---
+title: 数仓架构与选表规则
+source_status: warehouse_standard_learning_reference（分层定义）+ user_confirmed_agent_rule（选表/分区/依赖规则）
+---
+
+# 数仓架构与选表规则
+
+范围：`wanshifu_dw` 库。`wanshifu_enterprise` 库被明确排除——不查询、不作为血缘起点、不作为 SQL 来源。
+
+## 1. 分层定义
+
+| 层 | 作用 | 设计要点 |
+|---|---|---|
+| ODS | 源对齐的接入数据，保留源系统粒度和字段 | 新套增量：`ods_*_inc_v`（每日变化）+ `ods_*_v`（合并后全量最新）；新套全量：`ods_*_d_v`（按 `etl_date` 分区的每日全量快照） |
+| DWD | 清洗整合后的原子事实或宽表属性 | 保持原子粒度、不做聚合、保留业务时间、补齐统一维度 |
+| DWS | 可复用的主题级汇总和通用基础指标 | 从明细/公共层聚合；存基础指标，不存场景化衍生指标 |
+| DIM | 可复用的业务维度和代码映射 | — |
+| ADS | 场景化的数据服务、报表、抽数 | — |
+| MID | 供多个分析师 ADS 输出共享的中间指标结果 | MID 不能依赖 MID（见下文层间依赖） |
+
+业务域缩写：`mst`=master（师傅）、`usr`=user（用户）、`etp`=enterprise（企业）、`order`=order（订单）、`bas`=basic（基础）、`fmis`=finance（财务）、`kf`=customer_service（客服）。
+
+> 分层定义仅作数仓设计理解，用于对候选表做优先级排序，不能替代 DDL 和表级已验证知识；与分析师规则冲突时以分析师规则为准。
+
+## 2. 选表规则
+
+**总体优先级：**满足所需字段和业务粒度 > 数据质量和成熟度已验证 > （临时查询）优先用完整新套合并/全量 ODS，排在新旧套 DWD 之前 > （调度脚本）拒绝 ODS，用允许的公共层 > 优先新套公共层。
+
+| 场景 | 典型链路 | 分析师应选 | 避免 |
+|---|---|---|---|
+| 旧套增量源 | `ods_*_inc` → `dwd_*_inc_d` → `dwd_*` | 下游全量非增量 DWD 表 | `ods_*_inc`、`dwd_*_inc_d` |
+| 新套增量源 | `ods_*_inc_v` → `ods_*_v` | 直接用合并后的全量 `ods_*_v`（临时分析不必再走到 DWD） | `ods_*_inc_v` |
+| 新套全量快照 | `ods_*_d_v` | 直接用该 ODS 的最新快照分区（通常 T-1） | — |
+
+- 新套表缺所需字段时，才回退选用完整的旧套表。
+- 同优先级出现多个同样合适的 `_v` 候选时，必须人工确认，不能自动选一个。
+- 表名后缀优先级只是候选启发式，不是最终选表依据——最终仍要核对字段和已验证的表级知识。
+
+## 3. 分区语义
+
+| 语义 | 典型表 | 典型分区 | 查询规则 |
+|---|---|---|---|
+| 每日全量快照 | `ods_*_d_v` | `etl_date` | 取最新分区，通常 `etl_date = T-1`；一个分区是当天的完整快照 |
+| 业务时间分区 | 如下单日期、活跃日期 | 业务日期 | 按需求要求的业务时间范围过滤，不能只取 T-1 当全量快照；需求未指定范围时必须询问用户，**不得默认查近三年** |
+| 历史遗留分桶 | 部分数仓模型 | `20171231` | 2017 年及以前的记录可能被塞进这一个分区；查询范围涉及 2017 年及以前时，先查表级模型再写 SQL |
+
+**强制规则：**
+
+- 每张物理分区表都要过滤真实的分区字段。
+- 非分区表允许全表扫描，不能为它虚构分区或时间条件。
+- 业务时间过滤和分区过滤是两件事，要分别落实，不能互相替代。
+
+## 4. 层间依赖边界
+
+| 场景 | 允许的来源层 | 禁止的来源层 |
+|---|---|---|
+| 分析师临时查询 | DWD、DWS、DWM、DIM、ODS（兜底可用） | — |
+| 分析师调度脚本（ADS/MID） | DWD、DWS、DWM、DIM、MID | ODS、ADS、其他脚本的临时表（无例外） |
+| 数仓设计参考（非当前 Skill 强约束） | DWD←ODS/DIM；DWS←DWD/DWM/DIM/DWS；DIM←ODS/MySQL | — |
+
+- **MID 不能依赖另一个 MID**（已用户确认）。
+- 数仓设计参考里的依赖关系仅作学习背景，不是当前 Agent 规则的强约束来源。
+
+## 相关
+
+- SQL 层面的安全和格式规范见 [sql-rules.md](sql-rules.md)。
+- 上述规则的冲突裁决和历史确认记录见 [decisions.md](decisions.md)。