Add philosophy and wsf directories

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

philosophy/博弈逆向法-软件系统学习方法论.md

@@ -0,0 +1,230 @@
+# 博弈逆向法：从功能反推需求、矛盾与格局
+
+> 一套学习软件系统的方法论。核心假设：**一个功能的形态不是最优设计的产物，而是多方博弈在某个时点的均衡态**。系统当前的样子 = 初始约束 + 一连串外部冲击 + 每次冲击后各方的重新议价。
+>
+> 学习系统 = 把这个过程逆着放一遍。
+
+---
+
+## 0. 适用范围与失效边界
+
+**适用**：有多个利益主体、且这些主体的收益相互影响的地方。用户、付费方、供给侧、平台、监管、竞品、滥用者、内部团队，都是 player。
+
+**失效**：纯技术权衡（CAP、性能 vs 复杂度、内存 vs 吞吐）。这些是约束满足问题，没有对立的利益主体，硬套博弈框架会得出漂亮但错误的结论。识别方法——问"谁因此受损"，如果答案是"没人，只是物理限制"，换个框架。
+
+**最大风险**：**事后叙事**。任何时间线，只要允许自由引入外部事件，都能编出通顺的因果故事。本方法论的一半篇幅都在处理这件事（见第 3 节）。
+
+---
+
+## 1. 核心提问集
+
+对任何一个功能，依次问：
+
+| # | 问题 | 指向 |
+|---|------|------|
+| 1 | 它**限制**了谁？ | 被压制的一方 |
+| 2 | 它给了谁**权力**、撤走了谁的权力？ | 权力再分配 |
+| 3 | 谁**买单**、谁**受益**？两者是同一个人吗？ | 付费方 vs 使用方错位 |
+| 4 | **如果删掉它，谁会立刻开始占便宜？** | 最锋利的一问 |
+| 5 | 它的**默认值**偏向谁？ | 谁赢了那场争论 |
+| 6 | 它**不做**什么？刻意留下的空白是给谁的？ | 未言明的妥协 |
+| 7 | 它是**对抗性**的吗（对手会适应）？ | 决定规则是否透明 |
+
+第 4 问的用法：审批流、配额、冷却期、审计日志、限频——这类"让人不爽"的功能几乎必然对应一个真实存在的、正在占便宜的人。找到那个人，就找到了需求。
+
+第 7 问的用法：非对抗场景下规则应当透明（文档写清楚）；一旦对手会适应，规则必须模糊——限频阈值不公开、灰度不解释、影子封禁不通知。**看到"故意不说清楚"的设计，基本可以断定存在对抗性 player。**
+
+---
+
+## 2. 常见的结构性矛盾（假设生成器）
+
+拿到陌生系统时，先用这张表快速生成一批候选假设，再去验证。
+
+- **增长 vs 风控**：注册/下单要短，但要拦住黑产。表现为渐进式验证、风险分级
+- **使用者 vs 采购者**（B 端最典型）：买单的是老板，用的是员工 → 大量员工讨厌但必须有的管控、报表、审计功能
+- **平台 vs 供给方**：抽成率、流量分配、排序权、是否允许绕过平台成交
+- **体验 vs 变现**：付费墙的位置就是这条线的坐标
+- **平台 vs 滥用者**：唯一真正对抗性的一类，决定了规则的不透明
+- **新用户 vs 老用户**：迁移成本、兼容层、"经典模式"开关
+- **内部团队之间**（康威定律）：并行的两套模型、命名混乱、职责重叠的接口
+- **当下 vs 退出成本**：数据导出能力的强弱，反映了平台对锁定的态度
+
+---
+
+## 3. 证据分级与可证伪性
+
+### 3.1 内部证据的可靠性排序
+
+从高到低：
+
+1. **当年吵架的现场** —— PR/issue 里的反对意见、RFC 下的争论、邮件列表、当时的社区讨论串
+2. RFC / 设计文档 / ADR
+3. commit message、代码注释里的 `// 因为 XX 才这么写`
+4. release note / changelog
+5. 官方博客
+6. 媒体报道
+7. **多年后的创始人访谈** —— 已被重新叙事，因果常被事后合理化，只能当线索不能当证据
+
+> 原则：**优先找异议，而不是找结论**。反对者陈述的理由，通常比发布公告更准确地描述了当时的真实约束。
+
+### 3.2 代码与产品中的"化石"
+
+这些痕迹几乎必然是冲突留下的：
+
+- **配置开关的密度** —— 开关越多说明当年争得越凶（"两边都要，谁也说服不了谁，那就做成可配置"）；**默认值暴露了谁赢了**
+- **字段冗余** —— 同时存 `created_by` 和 `operator`，说明存在代人操作且发生过责任归属争议
+- **白名单 / 硬编码例外** —— 大客户议价权的直接证据
+- **不对称的信息设计** —— 如双盲评价（双方提交后才公开），是为消灭报复性评价的机制设计
+- **命名与措辞的变更** —— 代码没动、只改了文案和默认值，往往是法务介入的签名
+- **deprecated 但迟迟不删的接口** —— 存在无法得罪的依赖方
+
+### 3.3 三个证伪手法
+
+**① 前后顺序检验**
+外部事件 → 内部变化之间应有符合组织反应速度的滞后（通常数周到数个季度）。
+若内部改动**早于**外部事件：要么因果反了，要么两者有共同前因。此条淘汰假设最有效率。
+
+**② 对照组检验**
+同期未受该冲击的竞品做了同样的事吗？
+- 做了 → 更可能是行业时尚或共同前因，不是这个冲击
+- 受冲击程度不同的产品，出现了程度不同的反应 → 强证据
+
+**③ 没叫的狗（幸存者偏差校正）**
+只看 shipped 的功能会严重偏斜。真正高信息密度的是：
+- 被否掉的 RFC / 被关掉的 PR
+- 砍掉的功能、废弃的分支
+- 长期开着没人做的 issue
+
+这些是**输掉的一方**留下的痕迹。一个提案被否的理由，常比十篇发布博客更能说明当时的约束。
+
+---
+
+## 4. 外部冲击清单（联网搜索的检索方向）
+
+按对软件形态的改造力排序。每一类都应带**具体时点**，用于与内部时间线对齐。
+
+| 类别 | 特征 | 典型例 |
+|------|------|--------|
+| **监管** | 有明确生效日，最好对齐 | GDPR、反垄断判决、数据出境、行业牌照 |
+| **平台方政策** | 单方面、不可谈判、影响整条生态 | Apple ATT (2021) 重构广告技术栈；App Store 抽成；Twitter / Reddit API 收费 (2023) 灭掉一代第三方客户端 |
+| **上游许可证变更** | 下游会突然长出抽象层 | Redis / Elastic / HashiCorp → OpenTofu 等分叉 |
+| **资本周期** | 从增长转盈利 | 加息后：免费额度收缩、提价、砍长尾功能 |
+| **技术可得性突变** | 一批原本不成立的功能同时出现 | 某能力突然变便宜（如 LLM） |
+| **安全事故** | 解释"突然变严格"的地方 | 数据泄露、供应链攻击、大规模滥用事件 |
+| **竞品进入 / 退出** | 解释功能对齐与差异化 | 新 player 入场、免费替代品出现 |
+| **人事与并购** | 模块风格突变 ≈ 某个人走了 | 核心维护者离职、被收购后战略换向 |
+
+---
+
+## 5. 执行流程
+
+### Step 1 · 圈定范围
+选一个具体功能或模块，不要一上来分析整个产品。
+
+### Step 2 · 生成假设（廉价）
+用第 1 节提问集 + 第 2 节矛盾表，快速列出 5–10 条候选解释。此阶段不求准，求覆盖面。
+
+### Step 3 · 拉内部时间线
+按时间排：changelog、release note、重大 commit、RFC、issue 讨论。标出**形态发生质变**的节点（不是小修补，是设计换向的那几次）。
+
+### Step 4 · 拉外部时间线
+针对每个质变节点，向前推 1–6 个月，用第 4 节清单搜索该窗口内发生了什么。
+
+### Step 5 · 对齐与证伪
+用 3.3 的三个手法逐条淘汰假设。淘汰不掉的留下，并标注置信度。
+
+### Step 6 · 找"没叫的狗"
+补查被砍掉的、被否掉的、被废弃的东西。这一步经常会推翻前面的结论。
+
+### Step 7 · 识别地层
+把留下的解释按轮次排列成"机制 → 反制 → 反反制"，见第 6 节。
+
+### Step 8 · 输出与留白
+明确写出：哪些是有证据的，哪些是推测，哪些**至今无法解释**。第三类必须保留，它是下次修正的入口。
+
+---
+
+## 6. 地层：多轮博弈的堆积
+
+成熟系统的功能不是一次设计的结果，而是多轮攻防的**地层**。识别地层比识别单个功能重要。
+
+典型序列：
+
+```
+无理由退货（解决买方信息劣势）
+   ↓ 出现职业退货人
+买家风险画像 / 退货次数限制（反制）
+   ↓ 误伤正常用户，投诉与舆情
+申诉通道 + 人工复核（反反制）
+   ↓ 人工成本不可承受
+分级自动化 + 高价值订单才进人工（成本再平衡）
+```
+
+三到四层功能，三到四轮攻防，跨越数年。若只看当前形态，会误以为这是一次性设计的"风控体系"。
+
+**判据**：如果一个模块里的规则彼此打补丁、存在"例外的例外"，几乎必然是多轮堆积，不是一次设计。
+
+---
+
+## 7. 输出模板
+
+```markdown
+## 功能：<名称>
+
+### 当前形态
+（客观描述，不带解释）
+
+### 涉及的 player
+- 主张方：
+- 被限制方：
+- 买单方：
+- 沉默的一方（不在界面上但有影响力）：
+
+### 核心矛盾假设
+1. <假设>｜置信度 高/中/低｜证据：
+2. ...
+
+### 时间线对齐
+| 时间 | 内部变化 | 同期外部事件 | 滞后 | 判断 |
+|------|---------|-------------|------|------|
+
+### 对照组
+| 竞品 | 同期是否有同样变化 | 说明什么 |
+
+### 没叫的狗
+- 被否掉的方案：
+- 砍掉/废弃的功能：
+- 它们说明的约束：
+
+### 地层
+第 1 层（时间/机制）→ 第 2 层（反制）→ 第 3 层（…）
+
+### 已排除的假设
+（写明为什么排除，避免下次重复推演）
+
+### 尚无法解释的部分
+（必须保留）
+```
+
+---
+
+## 8. 自检清单
+
+用完这套方法后，逐条检查：
+
+- [ ] 我的解释是可证伪的吗？能说出"看到什么就说明我错了"吗
+- [ ] 有没有把纯技术权衡硬套成利益冲突
+- [ ] 时间顺序对得上吗（内部变化没有早于外部事件）
+- [ ] 查过对照组吗
+- [ ] 查过被砍掉/被否掉的东西吗
+- [ ] 主要证据来自"当年的争论"还是"事后的总结"
+- [ ] 有没有为了故事完整而强行填补空白
+- [ ] 是否保留了"无法解释"的部分
+
+---
+
+## 9. 一句话总结
+
+> 猜想廉价，验证才是功夫。
+> 博弈框架的价值不在于给出答案，而在于**快速生成大量可检验的猜想**，然后靠时间线对齐、对照组和"没叫的狗"把它们中的大多数淘汰掉。
+> 剩下的那几条，才是这个系统真正的历史。

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)。

wsf/biz/L1-essence.md

@@ -0,0 +1,132 @@
+---
+title: L1 · 万师傅业务本质（根级业务知识）
+source_status: 2026-07-31 业务方访谈确认收入模式、总包/KA 商业关系、核心矛盾表述；仅 §8 状态机一处待补
+level: L1（根级）
+usage: 设计为常驻上下文，可整份放入 system prompt
+---
+
+# 读之前
+
+这是万师傅业务的**世界观层**——从业者视为空气、从不言说，但一旦理解错，
+后面所有推理都会歪掉的那些前提。
+
+**收录标准**：老员工觉得"这还用说？"、新人问了会被当成傻问题，但答错整条推理链错位。
+详细的名词定义在 [L2-concepts.md](L2-concepts.md)，具体规则数值在 [L3-rules-index.md](L3-rules-index.md)。
+
+---
+
+## 1. 双边撮合平台，不是自营服务商
+
+万师傅连接**有家居售后需求的一方**和**有技能的师傅**。平台不雇佣师傅、不持有商品、不直接提供上门服务。
+
+由此：平台对师傅只能**治理**不能**管理**——没有考勤绩效上下级，只有准入、评分、处罚、清退；
+服务质量无法靠"培训员工"保证，只能靠规则 + 评分 + 保障机制兜底。
+
+## 2. 供需匹配有两种范式
+
+- **报价招标**：下单方发单 → 多个师傅竞价 → 下单方挑选并**指派** → 付款。价格由市场竞争形成。
+- **一口价**：价格预先定好 → 师傅直接接单（抢单）。价格由平台/下单方设定。
+
+两种模式下"师傅怎么拿到单"完全不同，涉及派单、报价、抢单的一切推理都必须先分清是哪种。
+
+## 3. 师傅是自主经营的个体，不是员工
+
+师傅**入驻**（不是入职）、被**清出平台**（不是辞退）。收入是服务报价所得，不是工资。
+
+由此：需要**保证金**（没有雇佣关系可约束，只能用经济约束替代）、需要**评分体系**
+（替代绩效考核）、需要**技能验证和实名认证**（替代招聘筛选）。
+
+## 4. 平台怎么赚钱：向师傅抽佣
+
+**主要收入 = 向师傅收取订单佣金，比例按品类而定，大致 15%。** 另有一部分来自保险费提成。
+
+这条是理解平台大量机制的钥匙：
+
+- 平台收入与**师傅成交额**直接挂钩 → 平台和师傅既是利益共同体，又要治理师傅，存在内在张力
+- **师傅每单绕过平台就能省下这 15%** → 线下交易是**结构性风险，不是个别师傅的道德问题**。
+  隐私号码、线下交易风控、引导线下判罚，全部由此而来
+
+## 5. 核心矛盾：非标 + 不可预先验证
+
+平台的大部分机制都是为解决这四个固有难点而存在：
+
+| 难点 | 应对机制 |
+|---|---|
+| **服务品类高度多样且非标** | 服务类目 × 服务类型二维矩阵、履约流程配置化、按品类定佣金与计费 |
+| 服务质量在购买时无法验证 | 评分体系、服务质检、满意后付款 |
+| 履约发生在线下，平台不可见 | 履约节点打卡、完工照、签收码 |
+| 双方都有动机绕过平台 | 隐私号码、线下交易风控、违规处罚（动因见 §4） |
+
+第一条是万师傅区别于多数服务平台的根本难点：家居品类极多、每个品类的服务流程与技能要求都不同，
+**导致"类目/流程变更"成为常态而非例外**——这正是履约流程必须做成可配置、而不能硬编码的原因。
+
+> 治理这些矛盾的手段有其上限，见 §9。
+
+## 6. 资金本质：担保交易
+
+钱不是下单方直接付给师傅，而是**先到平台、服务验收后才结算给师傅**。
+
+由此：平台必然需要清算、结算、钱包、提现整套资金体系；承担资金沉淀与合规责任，
+因此才有资金监管、会计、开票等系统。"满意后付款"不是营销话术，是资金流的真实结构。
+
+## 7. 需求侧有三种结构，付钱的和被服务的可以是不同人
+
+- **TOC（家庭）**：下单方 = 付款方 = 服务对象，都是家庭用户本人
+- **TOB（商家/企业）**：下单方和付款方是商家，**服务对象是商家的终端客户**——终端客户从未在平台下单、也不付钱
+- **总包 / KA**：见下
+
+**KA 用户**（大客户）不直接在平台下单，而是与**总包**签订价格协议。资金与服务链条是三跳：
+
+```
+KA 用户 ──协议价（可月结）──▶ 总包 ──平台价──▶ 平台 ──抽佣后结算──▶ 师傅
+```
+
+**总包的收入 = 协议价 − 平台价的差价。** 注意方向：是**总包付钱给平台**，不是平台付钱给总包——
+总包本质是"买平台服务能力、加价卖给 KA"的中间商，不是平台的外包供应商。
+
+由此：售后纠纷中"客户"指谁必须先分清是哪种结构，否则责任判定、赔付对象、验收方全会认错人；
+KA 月结带来的资金周转压力，也是平台需要向总包提供**授信**的原因。
+
+## 8. 订单生命周期主干
+
+所有品类、所有模式共享同一条主干：
+
+**下单 → 支付 → 派单/接单 → 联系并预约客户 → 上门签到 → 服务履约 → 上传完工凭证 → 客户验收 → 结算**
+
+各品类在"服务履约"环节插入不同节点（验货、检测、测量等），但主干不变。
+具体节点由履约配置系统配置，见 [L2-concepts.md](L2-concepts.md)。
+
+❓ **待补**：订单的正式状态枚举与状态机（上面是行为流程，不等于系统状态定义）。
+
+## 9. 治理的边界：处罚必须留余地
+
+平台靠师傅供给运转，**师傅供给是核心资产**。处罚过重会流失师傅，因此治理机制内建了大量缓冲：
+
+- **免责次数**：每月给师傅固定的容错额度，超出才真正判罚
+- **申诉机制**：系统自动判罚后，师傅可在时限内申诉，达标可自动撤销
+- **新师傅保护**：新师傅前几单的首个售后工单从轻处理
+
+**这些不是执行不严，是设计使然。** 平台与师傅的关系是双向的：
+§4 说的是师傅有绕过平台的动机（利益冲突），本节说的是平台不能过度惩罚师傅（依赖关系）——
+两者共同构成平台治理的张力，任何涉及"要不要加大处罚力度"的判断都必须同时考虑这两面。
+
+由此还可推出：师傅侧的违规判定必须给出申诉通道，纯粹的"检测即处罚"在这个业务里不成立。
+
+---
+
+## 来源
+
+| 内容 | 来源 |
+|---|---|
+| §4 收入模式、§5 非标性、§7 总包/KA 商业关系 | **业务方访谈，2026-07-31** |
+| §9 治理边界 | 客服SOP合集《申诉工单处理流程》（免责次数/申诉机制）+《新师傅0-3单第1个售后工单从轻处理流程》，反推归纳 |
+| §1 双边平台、§3 自主经营 | 官网（"让用户自主选择，让师傅自主经营"）+ 客服SOP《第1章师傅入驻要求》《第12章产品规则说明》 |
+| §2 报价招标 / 一口价 | 官网《如何找师傅》 |
+| §6 担保交易 | 官网"满意后付款" + payment/ai-knowledge 支付系统业务语义 |
+| §7 TOC/TOB | 违规拒单 prompt.txt 业务背景 |
+| §8 生命周期主干 | 违规拒单 prompt.txt §1.4 + 服务履约配置化专项.docx |
+
+## 关联
+
+- [L2-concepts.md](L2-concepts.md) —— 二级概念，每条应能挂到本文件某一节之下
+- [README.md](README.md) —— 分层原则

wsf/biz/L2-concepts.md

@@ -0,0 +1,244 @@
+---
+title: L2 · 万师傅概念体系（二级业务知识）
+source_status: 2026-07-31 由原 platform-entities.md + domain-concepts.md 合并重组，并补入官网抽取与业务方访谈的新概念
+level: L2（二级）
+usage: 按需检索。每节标注它挂靠的 L1 条目
+---
+
+# 读之前
+
+有明确定义、跨场景复用、**容易混淆**的名词与实体。
+每一节都标注了它挂靠在 [L1-essence.md](L1-essence.md) 的哪一条——
+读某个概念读不懂时，先回去读它挂靠的那条 L1。
+
+具体规则数值不在本文件，见 [L3-rules-index.md](L3-rules-index.md)。
+
+---
+
+## 1. 交易与匹配
+
+> 挂靠 **L1 §2（两种匹配范式）**、**L1 §4（抽佣模式）**
+
+| 概念 | 定义 | 容易混淆成什么 |
+|---|---|---|
+| **报价招标** | 下单方发布订单，系统推送给当地合适师傅，多个师傅**竞价报价**，下单方从报价中挑选 | 不是平台定价——价格由市场竞争形成 |
+| **一口价** | 价格预先设定好，师傅直接接单，无竞价环节 | 不是"报价后议价"，是无报价流程 |
+| **指派** | 下单方从多个报价中选定某位师傅承接订单的动作 | 报价招标特有；一口价是师傅主动接单，没有指派环节 |
+| **抢单** | 一口价模式下师傅主动接单 | 与"指派"方向相反：抢单是师傅选订单，指派是下单方选师傅 |
+| **平台价** | 订单在万师傅平台上成交的价格 | 与协议价区分，见下 |
+| **协议价** | KA 用户与总包签订价格协议约定的价格 | 高于平台价；差额是总包的收入 |
+| **佣金** | 平台从师傅的订单收入中抽取的费用，比例**按品类而定**（大致 15%） | 向**师傅**收，不是向下单方加收 |
+
+## 2. 参与方
+
+> 挂靠 **L1 §1（双边平台）**、**L1 §3（师傅自主经营）**、**L1 §7（需求侧三种结构）**
+
+### 2.1 角色
+
+| 角色 | 含义 | 备注 |
+|---|---|---|
+| **师傅**（master） | 平台签约的服务执行者 | 自主经营个体，非员工；评分体系见 §5 |
+| **家庭用户**（family user） | C 端消费者 | TOC 场景下同时是下单方、付款方、服务对象 |
+| **商家 / 企业用户**（merchant / enterprise） | 平台入驻的商品销售方 | **两个词指同一类主体**，只是叫法不同（数仓侧记作 `etp`）；下单是为了给自己的终端客户提供售后履约 |
+| **终端客户** | TOB 场景下实际接受服务的自然人 | **未在平台下单、也不付钱**；不单独建角色，是"家庭用户"在 TOB 下的对应体 |
+| **KA 用户** | 大客户，通过总包而非直接在平台下单 | 与总包签价格协议，可月结 |
+| **总包**（general contractor） | 对接 KA 用户、代其在平台找师傅的中间商 | 官网称"服务商"；分内部（万师傅子公司自营）/外部（合作商）；**收入是协议价与平台价的差价**，方向是总包付钱给平台 |
+| **运营**（operator） | 配置活动/广告的内部角色 | 需运营权限 |
+| **审核员**（auditor） | 活动/广告审批角色 | 独立审批流 |
+
+### 2.2 下单方类型
+
+| 类型 | 说明 |
+|---|---|
+| 家庭订单（TOC） | 家庭用户经 APP / 小程序下单 |
+| 企业订单 / 商家订单（TOB） | **同一回事，两种叫法**。企业/商家经官网后台、APP 等渠道下单。官网按场景细分为：**电商卖家、物流企业、品牌商家、企业维保** |
+| 总包订单 | 总包代 KA 用户下单 |
+
+> ⚠️ "商家订单"和"企业订单"指的是同一类订单，文档和口语中两种叫法混用，不要误当成两种类型。
+
+## 3. 服务与履约
+
+> 挂靠 **L1 §5（非标性）**、**L1 §8（生命周期主干）**
+
+### 3.1 服务矩阵：类目 × 类型（两个正交维度）
+
+这是理解万师傅"非标"的关键结构——**同一个类目下不同服务类型的流程完全不同**。
+
+- **服务类目**（服务对象是什么品类）：家具、灯具、卫浴、浴霸、窗帘、智能锁、健身器材、全屋定制、
+  家电、净水器、墙纸、晾衣架、门、智能家居、地板、广告安装等
+- **服务类型**（对它做什么）：送货、安装、测量、维修、返货、保养（另有清洗、疏通、拆旧、定制等）
+
+### 3.2 履约与配置化
+
+| 概念 | 定义 |
+|---|---|
+| **履约**（fulfillment） | 师傅接单后，按平台要求履行服务责任直到客户验收完成的整个过程 |
+| **履约流程** | 师傅履行订单服务所遵循的一系列步骤，由若干节点组成 |
+| **节点** | 履约流程中的关键点，标志履约进度变化（如预约客户、上门签到、拆包验货、确认完成） |
+| **模块** | 节点内相对独立、可重复管理的内容单元（如"确认完成"节点下的签收单、完工照、签收码） |
+| **属性 / 组件** | 描述节点内容的信息项，及其表现形式（文本输入、图片上传、扫码、签字等） |
+
+**关键事实**：履约流程的节点组合**不是硬编码，而是按服务类型 / 地区 / 用户配置出来的**。
+因此"某品类的履约有哪些节点"没有唯一答案，取决于配置——这是 L1 §5 非标性的直接产物。
+
+### 3.3 特色服务
+
+| 概念 | 定义 |
+|---|---|
+| **尾货处理** | 客户退货后同城转卖回款的服务。平台不参与交易过程，因此风控口径与普通订单不同 |
+| **售后码** | 商家提供给终端客户、用于自助发起售后的凭证 |
+| **专业维修 / 金牌维修师** | 面向维修类目的专项服务与师傅认证 |
+
+## 4. 资金域
+
+> 挂靠 **L1 §6（担保交易）**
+
+这些概念由支付系统定义，被会计、开票、风控、资金监管等多个下游系统共同引用。
+
+| 概念 | 定义 | 容易混淆成什么 |
+|---|---|---|
+| **交易**（Transaction） | 承载一次支付的完整生命周期 | 不是订单——一个订单可能对应多笔交易（部分支付/重试） |
+| **支付**（Payment） | 早期模型里的核心概念 | 不是交易——新业务用"交易"，"支付"是存量兼容 |
+| **渠道**（Channel） | 第三方支付通道（微信、支付宝、银联等） | 不是渠道商户——商户是在渠道下注册的身份 |
+| **清算**（Clearing） | 与渠道方对账、确认资金归属 | 不是结算——清算解决"这笔钱是谁的"，实时性强 |
+| **结算**（Settlement） | 资金按周期到账 | 不是清算——结算解决"钱真的到账" |
+| **钱包**（Wallet） | 用户/师傅的虚拟账户余额 | 不是账户 ID |
+| **授信**（Credit） | 平台给总包/企业客户的月结额度与垫付 | **不是师傅个人信用**；根源是 KA 月结带来的资金周转需求 |
+| **保证金**（Earnest Money） | 师傅/总包**入驻时缴纳**的押金，违约扣 | 不是保障金 |
+| **保障金**（Security Fund） | **平台发放**、用于抵扣服务费的额度 | 不是保证金；一个是交的，一个是发的 |
+
+**结算周期**：师傅侧当前为 **T+1**，且**可由系统配置**，不是固定业务规则。具体配置见 [L3](L3-rules-index.md)。
+
+## 5. 师傅治理
+
+> 挂靠 **L1 §3（自主经营，无雇佣关系）**、**L1 §5（质量不可预验证）**
+
+平台维护**两套独立**的师傅评分，容易混淆：
+
+| 概念 | 定义 | 分数来源 | 周期 |
+|---|---|---|---|
+| **服务质量分** | 服务质量管理体系的核心分数，直接影响**接单资格** | 用户投诉、客服投诉、系统监测；违规成立即扣分 | 1 年一周期，满一年扣分清零 |
+| **综合评分** | 订单完成后下单方给出的星级评价，影响**是否被指派** | 星级评价：低星扣分、主动五星加分 | 无清零周期，持续累加 |
+
+计分来源、清零机制、影响面完全独立，不能互相替代。具体阈值与处置见 [L3](L3-rules-index.md)。
+
+## 6. 保障与售后
+
+> 挂靠 **L1 §5（核心矛盾）**、**L1 §6（担保交易）**
+
+| 概念 | 定义 |
+|---|---|
+| **担保交易** | 平台居中托管订单资金，验收后才结算给师傅 |
+| **服务质检** | 平台对服务过程/结果做质量检查 |
+| **先行赔付** | 纠纷经核实符合保障条件时，平台先行赔付，不必等双方自行了结 |
+| **商业保险** | 客户财产损失、师傅人身意外由合作保险理赔（平台的第二收入来源即来自此项提成） |
+| **仲裁** | 退款申请被师傅拒绝、无法自行解决时，可申请平台仲裁 |
+| **投诉** | 遇到不良师傅或交易纠纷时发起，可导致师傅扣分与处罚 |
+| **售后工单** | 售后问题的承载单据，按业务类型（家庭/企业/总包）走不同处理流程 |
+
+用户侧的三句承诺——"满意后付款""有纠纷找平台""出意外有保险"——分别对应
+担保交易+质检、先行赔付、商业保险。
+
+## 7. 工单与师傅治理体系
+
+> 挂靠 **L1 §5（质量不可预验证）**、**L1 §9（治理必须留余地）**
+
+### 7.1 工单类型（四种，容易混为一谈）
+
+| 类型 | 谁发起 | 针对谁 | 用途 |
+|---|---|---|---|
+| **售后工单** | 用户 或 客服 | 师傅 | 服务出问题后的追责与处理主载体 |
+| **二线工单** | 在线咨询升级而来 | 不定 | 一线在线客服解决不了、需外呼或跨部门协调的问题；也承接 KA 对接 |
+| **申诉工单** | **师傅** | 平台的处罚决定 | 师傅对系统自动判罚提出异议 |
+| **外投工单** | 用户（绕过平台） | 平台 | 用户已投诉到第三方渠道后的应对 |
+
+**方向是关键**：售后工单是"平台追责师傅"，申诉工单是"师傅反驳平台"，
+外投工单是"用户绕过平台投诉平台"。三者的立场完全不同。
+
+### 7.2 售后工单分类体系（三层）
+
+**服务状态（一级）× 投诉项（二级，共 16 项）× 三级分类**
+
+| 服务状态 | 二级分类 |
+|---|---|
+| **服务前**（4 项） | 师傅超过24小时联系不上、指派后拖延或拒绝服务、同意或引导非平台交易、虚假预约 |
+| **服务中**（9 项） | 要求客户帮忙、有不文明行为、未按规范提供服务、虚假上门、向客户泄露服务费用、导致客户对商家差评、不合理加价或虚假增费、威胁骚扰、造成商品或客户家物品损失 |
+| **服务后**（3 项） | 虚假完工、散播谣言、刷单刷数据或使用外挂 |
+
+> ⚠️ **注意主语**：16 个分类项**全部以"师傅"为主语**。这套体系不是中立的"问题分类"，
+> 而是**对师傅的追责分类**——因为平台无法事前管理师傅（L1 §1、§3），只能靠事后追责治理。
+> 理解这一点，才不会误以为它能用来分类"所有售后问题"。
+
+### 7.3 工单来源：用户发起 vs 客服发起
+
+| 来源 | 用户可见性 | 师傅可见性 |
+|---|---|---|
+| **用户发起** | 可查看处理进度、可自主举证 | 可见、可举证 |
+| **客服发起** | **用户无感知**，无法查看进度或自主举证 | 可见、可举证 |
+
+这个差异直接影响沟通策略——客服发起的工单，用户并不知道它存在。
+
+### 7.4 处罚与申诉
+
+| 概念 | 定义 |
+|---|---|
+| **系统自动判罚** | 平台对师傅履约数据自动监控，在**预约、签到、拒单、完工**四个节点自动判定违规 |
+| **处罚单** | 自动判罚生成的处罚单据（数仓侧对应 `penalty_sheet`） |
+| **违约金** | 处罚单对应的罚款，按违规类型分档 |
+| **免责次数** | 每月给师傅的容错额度，额度内的违规不实际处罚 |
+| **申诉** | 师傅对处罚单提出异议；系统先自动过滤，达标自动通过，未达标转人工处理 |
+
+**四个自动判罚节点与数仓罚单枚举对应**：超时预约、超时签到、拒绝服务——
+这解释了 `bd/` 中 `penalty_sheet.business_type` 那几个枚举值的业务来源。
+
+### 7.5 其他相关概念
+
+| 概念 | 定义 |
+|---|---|
+| **外投** | 用户绕过平台，向第三方渠道（12315、黑猫投诉、行政监管、社交媒体舆情）投诉 |
+| **质保 / 质保期** | 服务后的保修期。质保期内师傅需免费上门处理自身原因造成的问题 |
+| **服务确认码** | 完工时由客户提供给师傅的验收凭证，师傅索要确认码但未实际完成服务即"虚假完工" |
+| **普通工单 / 紧急工单** | 按紧急度分级，响应时效不同；涉及人身安全、报警、威胁骚扰等为紧急 |
+| **双向响应** | 时效考核口径：需联系不同的两方（如同时联系用户和师傅），只联系一方不算 |
+
+## 8. 业务域与系统地图
+
+> 技术侧视角，供定位系统归属用
+
+### 8.1 数仓业务域缩写
+
+| 缩写 | 业务域 | 对应 |
+|---|---|---|
+| mst | master（师傅） | §2.1 师傅 |
+| usr | user（用户） | §2.1 家庭用户 |
+| etp | enterprise（企业） | §2.1 商家 / 企业 |
+| order | order（订单） | 订单域 |
+| bas | basic（基础） | 公共基础数据 |
+| fmis | finance（财务） | 财务域 |
+| kf | customer_service（客服） | 客服域 |
+
+### 8.2 资金 / 风控系统域
+
+支付系统（资金流转中枢）、会计系统（记账）、开票系统（税务）、风控系统、
+资金监管、清分结算、收银台、保险系统。
+
+> 两套划分不是同一体系（前者按数仓表名前缀，后者按系统边界），存在交叉但非一一映射。
+
+---
+
+## 来源
+
+| 内容 | 来源 |
+|---|---|
+| §1 一口价/报价招标/指派、§3.1 服务矩阵、§3.3 特色服务、§6 仲裁投诉 | 官网 wanshifu.com（首页 / 如何找师傅 / 商家服务 / 客服中心），2026-07-31 |
+| §1 协议价·平台价·佣金、§2.1 KA 用户与总包关系、§4 结算周期 | 业务方访谈，2026-07-31 |
+| §2.1 角色（商家/师傅/家庭用户/运营/审核员） | dev-knowledge-base `team-conventions/glossary.md` |
+| §2.1 总包、§5 评分体系、§6 售后工单、**§7 工单与治理体系全节** | 客服工单SOP与对外规则合集（企业/家庭售后工单处理流程、申诉工单处理流程、二线工单处理流程、高投外投SOP），2026-08-03 |
+| §3.2 履约配置化 | 服务履约配置化专项.docx |
+| §4 资金域概念 | payment/ai-knowledge 支付系统业务语义 |
+| §8.1 数仓缩写 | `bd/warehouse.md` |
+
+## 关联
+
+- [L1-essence.md](L1-essence.md) —— 各节挂靠的根级前提
+- [L3-rules-index.md](L3-rules-index.md) —— 本层概念对应的具体规则与数值

wsf/biz/L3-rules-index.md

@@ -0,0 +1,124 @@
+---
+title: L3 · 规则与口径索引（三级业务知识）
+source_status: 2026-07-31 建立索引骨架。**本文件只登记规则的存在与权威源，不复制具体数值**
+level: L3（三级）
+usage: 按需检索。回答"有没有这条规则、归谁管、去哪查"，不回答"具体是多少"
+---
+
+# 读之前
+
+**这是索引，不是规则本身。**
+
+L3 内容（费用标准、扣分阈值、赔付金额、佣金比例、时效要求）半衰期只有 1 个月到 1 年，
+一旦在这里抄一份副本，很快就会和权威源不一致——而读者无法分辨哪份是对的，
+最终连带不信整个知识库。所以本文件的约定是：
+
+- ✅ 登记：**这条规则存在、归谁管、权威文档在哪、大致是什么形态**（有分档？有条件？按品类不同？）
+- ❌ 不登记：具体数值、具体阈值、具体金额
+
+模型据此可以知道"这里有规则，需要去查/需要问人"，而不是凭空编一个数字，
+也不是完全不知道有这回事。**"知道自己不知道"本身就是有价值的知识。**
+
+---
+
+## 1. 交易与资金
+
+> 对应 [L2 §1 交易与匹配](L2-concepts.md)、[L2 §4 资金域](L2-concepts.md)
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **佣金比例** | 按**服务类目**不同，大致 15% | ❓ 权威文档待确认（业务方口述） | 需补权威源 |
+| **师傅结算周期** | 当前 T+1，**系统可配置** | 结算系统配置 | 可配置，非固定规则 |
+| **KA / 总包月结账期** | 协议约定，可月结 | 各 KA 与总包签订的价格协议 | 一客一议 |
+| **平台额外费用标准** | 按类目+服务类型分档（拆旧费、空跑费、超区费等） | 《平台费用标准承诺》《平台额外费用标准和家电费用标准服务承诺（内部版）》 | 客服SOP合集 |
+| **提现规则** | —— | 支付/钱包系统 | 待补 |
+
+## 2. 师傅治理与处罚
+
+> 对应 [L2 §5 师傅治理](L2-concepts.md)
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **服务质量分扣分与降分处置** | 按分数分档（触发禁止接单、重新考试、清出平台等） | 客服SOP合集《第12章：产品规则说明》 | 有明确分档 |
+| **综合评分加减分规则** | 按星级加减 | 同上 | —— |
+| **违规处理细则** | 违规类型 × 严重程度 → 处置 | 《违规处理细则》《新违规处理细则》 | 有新旧两版，注意版本 |
+| **平台安全治理规则** | 外挂抢单/围标/刷单/诈骗洗钱/涉黄涉政等，分轻微/严重 | 《平台安全治理规则》 | —— |
+| **师傅入驻要求** | 年龄、实名、技能验证、证书要求 | 《第1章：师傅入驻要求》 | —— |
+| **师傅接单/服务/安全/形象标准** | 行为清单式 | 《第2/4/5章》《服务标准承诺》《行为标准承诺》《安全标准承诺》 | —— |
+| **技能作业标准** | 按类目分册（家具/定制/建材/家庭） | 《第8-11章：技能作业标准》 | 按品类拆分 |
+| **自动判罚违约金标准** | 按违规类型分档（未及时预约分超2h/超24h两档、未及时签到、拒绝服务等） | 《申诉工单处理流程》 | 有具体金额 |
+| **免责次数** | 按违规类型给月度额度，部分需师傅手动申请 | 同上 | 额度制 |
+| **申诉时效与入口** | 处罚单生成后限时申诉；不同违规类型的申诉入口不同（APP自助 / 只能联系人工） | 同上 | 入口按类型而异 |
+| **新师傅从轻处理** | 新师傅前若干单的首个售后工单从轻 | 《新师傅0-3单第1个售后工单从轻处理流程》 | 供给保护，见 [L1 §9](L1-essence.md) |
+
+## 3. 售后与保障
+
+> 对应 [L2 §6 保障与售后](L2-concepts.md)
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **补偿赔偿标准** | 按场景与责任方分档 | 《万师傅客服中心补偿赔偿标准》 | —— |
+| **先行赔付适用条件** | 条件判定 | 同上 + 官网平台保障页 | —— |
+| **售后工单处理流程与时效** | 按业务类型（家庭/企业/总包）分别定义 | 客服SOP合集各部门 SOP | 分业务线 |
+| **工单响应时效** | 普通工单区分会员/非会员；紧急工单另有更短时效；考核口径为"双向响应" | 《家庭售后工单处理流程及标准（新版）》 | 有具体小时数 |
+| **售后工单有效期** | 订单完成后固定天数内用户可自行发起，超期只能由客服发起 | 同上 | 有具体天数 |
+| **外投处理标准** | 按外投渠道（12315/黑猫/舆情等）时效倒推，含逾期升级机制 | 高投工单部各 SOP | 时效驱动 |
+| **判责依据体系** | 以《新违规处理细则》+ 四份师傅服务承诺为准 | 《家庭售后工单处理流程及标准》§三 | **判责的正式依据清单** |
+| **客服质检标准** | 质检得分线 + 通过率目标 + 抽检规则 | 《万师傅客服中心质检标准》 | 面向客服，非面向师傅 |
+| **质保规则** | 按类目 | 《质保》 | —— |
+| **责任判定口径** | 师傅/客户/商家/平台/不可抗力/责任不明 | 客服SOP + 违规拒单分析规则 | 见下 §5 |
+| **保险理赔范围与流程** | —— | 《平台保险处理标准》（内部，严禁对外） | 涉密，注意使用范围 |
+
+## 4. 履约
+
+> 对应 [L2 §3.2 履约与配置化](L2-concepts.md)
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **各服务类型的履约节点组合** | **配置化，非固定** | 履约配置平台 | 查配置，不查文档 |
+| **节点内容（模块/组件）配置** | 按服务、用户、地区配置 | 同上 | 同上 |
+| **预约/完工时效要求** | 接单后 N 小时预约、N 小时完工 | 《服务标准承诺》 | 有具体数值 |
+
+## 5. 风控
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **推单内容风控判罚口径** | 归属方判别 + 风险类别，带版本号迭代频繁 | `base-model-train-platform` 的 `prompts/risk_rerank.md`；生产以 Apollo 配置为准 | **迭代极快，务必查源** |
+| **师傅治理分析规则** | 按分析轨道（关单/线下交易/IM拒单），Apollo 动态配置 | Apollo `masterGovernance.rules.*` | 动态配置 |
+| **线下交易判定** | —— | 同上 | 动因见 [L1 §4](L1-essence.md) |
+
+## 6. 财税
+
+| 规则 | 形态 | 权威源 | 状态 |
+|---|---|---|---|
+| **会计订单打标规则** | 三层打标（业务归属/结算发票/特殊业务），9 级优先级覆盖 | payment/ai-knowledge 会计系统业务语义 | —— |
+| **开票校验与合作开票准入** | 按 applyType 与合作状态分支 | payment/ai-knowledge 开票系统业务语义 | —— |
+
+## 7. 数据口径
+
+> ⚠️ 归 `../bd/` 管，本库只登记指针
+
+| 规则 | 权威源 |
+|---|---|
+| 指标定义与计算口径 | `../bd/business.md` |
+| 数仓选表、分区、层间依赖规则 | `../bd/warehouse.md` |
+| SQL 规范与部署规范 | `../bd/sql-rules.md` |
+| 口径冲突裁决记录 | `../bd/decisions.md` |
+
+**取数类消费方应同时加载 `biz/L1 + biz/L2 + bd/`**：业务概念来自本库，落到表和字段靠 `bd/`。
+
+---
+
+## 已知缺口
+
+| 缺口 | 影响 |
+|---|---|
+| 佣金比例缺权威文档，目前只有口述 | 涉及收入的推理无据可依 |
+| 订单正式状态枚举与状态机未找到 | 见 [L1 §8](L1-essence.md) 待补项 |
+| 提现规则、资金冻结/解冻规则未登记 | 资金侧不完整 |
+| 会员（超级会员）权益规则未登记 | 官网与客服SOP均提及，未找到权威定义 |
+
+## 关联
+
+- [L2-concepts.md](L2-concepts.md) —— 各规则对应的概念定义
+- [README.md](README.md) —— 为什么 L3 只做索引（见"关于腐坏"）

wsf/biz/README.md

@@ -0,0 +1,213 @@
+---
+title: 万师傅业务知识库（biz）— 分层原则与使用说明
+source_status: 2026-07-31 基于三层知识模型完全重写，替代此前按"抽/不抽"二元判断的旧版本
+---
+
+# 这个知识库是什么
+
+给**大模型**用的万师傅业务知识底座。目标是让模型在没有任何人解释的情况下，
+理解万师傅的业务模式、运转逻辑、概念体系和专业术语，从而能正确地取数、答疑、判断、写代码。
+
+人读是附带收益，不是设计目标——**当"给模型用"和"给人读"冲突时，以模型为准**。
+
+---
+
+# 一、核心：知识的三层模型
+
+这是本知识库最重要的组织原则。所有"收不收、放哪、怎么写"的问题，都先回到这三层。
+
+## 三层定义
+
+| 层 | 名称 | 装什么 | 判定标准 |
+|---|---|---|---|
+| **L1** | 业务本质（根级） | 业务的世界观、前提、底层逻辑 | 从业者视为空气、从不言说，但**答错会让整条推理链歪掉** |
+| **L2** | 概念体系（二级） | 有明确定义的名词、术语、实体、关系 | 需要被精确定义、跨场景复用、**容易混淆** |
+| **L3** | 规则与口径（三级） | 有条件、有数值、可执行的判定规则 | 回答"具体怎么算/怎么判"，**有明确的权威归属方** |
+
+**根级的识别测试**：老员工觉得"这还用说？"、新人问了会被当成傻问题，但答错后面全错。
+典型例子——"师傅不是万师傅的员工"。没人会想到要写这句，但模型如果默认师傅是员工，
+就会去问"师傅的绩效考核"，无法理解为什么要收保证金、为什么是"清出平台"而不是"辞退"。
+
+## 三层的三个关键性质
+
+理解这三条，比记住分层本身更重要。
+
+### 性质 1 · 三层是"解释链"，不是重要性排序
+
+向下是展开，向上是溯因。**每条 L2 概念都应能挂到某条 L1 之下，每条 L3 规则都应能挂到某条 L2 之下。**
+
+由此得到两个可操作的推论：
+
+- **挂不上去的知识是可疑的**：要么是孤儿内容该删，要么暴露了一条缺失的 L1/L2
+- **可以用 L3 反向发现 L1**：问"为什么要收保证金？"→ 因为师傅是自主经营个体、平台无法用雇佣关系约束 → 挖出一条 L1
+
+第二条是**补全根级的主要方法**。因为根级知识没法正面问——直接问"你们的商业模式是什么"，
+业务方只会给你一段官网文案。拿一条具体规则追问"为什么"，追问两三层，才能挖到真正的前提。
+
+### 性质 2 · 三层的生产方式完全不同
+
+| 层 | 怎么获得 | 能否靠抽取 |
+|---|---|---|
+| L1 | 访谈、口述 **或从 L3 反向溯因** | ⚠️ 不能直接抽——从来没人正面写过；但能**间接反推** |
+| L2 | 领域文档抽取 + 架构师确认 | ✅ 可以直接抽 |
+| L3 | 指向权威文档 | ⚠️ **不该抽**——该做索引 |
+
+这解释了一个实测结果：从 7 个来源（含两个部门级知识库、87MB 客服资料、官网）做**正面抽取**，
+产出的内容几乎全是 L2——因为只有 L2 被人写下来过。
+
+但 L1 并非完全够不着。**反向溯因是可行路径**：材料里的具体规则（L3）本身不进知识库，
+但追问"为什么会有这条规则"，往往能反推出从没被写下的 L1。
+
+> **实证**：从"免责次数""申诉机制""新师傅从轻处理"三条规则反推，
+> 得到 L1 §9「治理力度受供给留存约束」——这条在任何文档里都找不到正面表述。
+
+所以：**想补 L1 靠访谈或反向溯因，想补 L3 应该做索引，正面抽取只会得到更多 L2。**
+
+### 性质 3 · 三层的加载方式不同（这是必须物理分文件的硬理由）
+
+| 层 | 加载策略 | 体量约束 |
+|---|---|---|
+| L1 | **常驻上下文**（整份进 system prompt） | 必须短，**上限约 2000 字** |
+| L2 | 按需检索（术语表式） | 可以长，但要条目化、便于检索 |
+| L3 | 按需检索，且必须带时效标记和权威链接 | 只存索引，不存副本 |
+
+如果三层混在一个文件里，L1 就无法常驻——不可能为了让模型知道"师傅不是员工"，
+把整个规则库塞进 system prompt。**这是分层必须落到物理文件上的原因，不只是分类整齐。**
+
+**L1 超出字数预算时怎么办**（按顺序判断，不要直接放宽）：
+
+1. 先查是否混进了 L2 —— 有则下沉，这是最常见的原因
+2. 确认全是真 L1 但仍超标 → 逐条重新过"答错会不会让整条推理链歪掉"，删掉只是"重要"但不致命的
+3. 两步之后仍超 → 可放宽至 2500 字，但**硬上限 3000**，再多就失去常驻可行性了
+
+### 性质 4 · 框架是发现工具，不只是整理工具
+
+同一份材料，用不同框架去读，产出可以差一个数量级。
+
+> **实证**：客服 SOP 合集按"抽 / 不抽"的二元标准读，只抽出 3 条；
+> 引入三层模型后重读**同一个压缩包**，抽出一整块 L2（工单与治理体系）加一条 L1（治理边界）。
+
+**推论：框架升级后，应当重扫已经抽取过的来源。**
+"这个源已经抽过了"不构成跳过它的理由——判断标准变了，同一份材料的价值也随之改变。
+
+---
+
+# 二、判定流程
+
+新知识进来时，按顺序走：
+
+```
+Q1: 模型能从代码 / DDL / 官网自己推出来吗？
+    能   → 不收（不要浪费上下文预算）
+    不能 → Q2
+
+Q2: 它是"前提"、"名词"还是"规则"？
+    从业者从不言说的前提，答错整条链歪掉   → L1
+    需要精确定义、容易混淆的名词/实体/关系 → L2
+    有条件、有数值的可执行判定规则         → L3
+
+Q3: 它能挂到上一层的哪一条之下？
+    挂不上 → 停下：要么这条该删，要么上一层缺了东西，先补上一层
+
+Q4（仅 L3）: 数值会变吗？
+    会   → 只登记"有这条规则 + 归谁管 + 权威文档在哪"，不内嵌数值
+    不会 → 可内嵌
+```
+
+## 明确不收的内容
+
+| 不收 | 为什么 |
+|---|---|
+| 工程实现细节（字段枚举、幂等键、分片规则、金额单位） | 属于技术约定，不是公共业务知识；应在技术知识库 |
+| 系统集成模式（MQ 链路、回调、重试） | 同上 |
+| 工作方法论、SOP（怎么澄清需求、怎么处理工单） | 属于协作方式，不描述业务本身 |
+| 具体运营参数的副本（费用标准、扣分阈值） | 会腐坏。**登记它存在，链接到权威源，但不抄数值** |
+| SQL / 表结构 | `../bd/` 的职责 |
+| 运营指标、荣誉、营销文案 | 变化快且无推理价值 |
+
+**关于腐坏**：短半衰期内容的问题不是"不重要"，而是**不能和长半衰期内容混放**——
+读者无法分辨哪部分还有效，就会连带不信整个知识库。这是 L3 只做索引的根本原因。
+
+各层的半衰期参考：L1 约 5-10 年（变了就是公司转型）、L2 约 1-5 年、L3 约 1 月-1 年。
+
+---
+
+# 三、目录结构
+
+```
+wiki/biz/
+├── README.md              本文件 —— 分层原则与判定流程
+├── L1-essence.md          根级：业务本质（常驻上下文，≤2000字）
+├── L2-concepts.md         二级：概念体系（按需检索）
+├── L3-rules-index.md      三级：规则索引（只索引，不内嵌数值）
+└── _golden-questions.md   治理文件：完备性度量清单
+```
+
+`_` 前缀 = 治理文件，不是知识内容本身。
+
+**新增知识前先问**：它能让 [_golden-questions.md](_golden-questions.md) 里的哪个问题
+从答不出变成答得出？答不上来的内容，大概率不该收。
+
+---
+
+# 四、怎么用：加载配方与库间边界
+
+## 各消费场景该加载什么
+
+| 消费场景 | 加载 |
+|---|---|
+| 通用业务问答 / 新人 onboarding | **L1（常驻）** + L2 按需检索 |
+| 取数 / 分析 Agent | **L1** + L2 + `../bd/` 全量 |
+| 客服 / 风控 Agent | **L1** + L2 + L3 索引（据索引再去查权威源拿数值） |
+| 编码 / 架构 Agent | **L1** + L2 + 对应系统的技术知识库 |
+
+**L1 在所有场景都常驻**——它是理解其他一切的前提，不存在"这个场景不需要 L1"的情况。
+
+## 与 `../bd/` 的边界
+
+| 知识库 | 职责 |
+|---|---|
+| `biz/`（本库） | 业务事实：本质、概念、规则索引 |
+| `../bd/` | 数仓、SQL、取数口径、表结构 |
+
+**两库文件间不互相链接**，各自独立演进。但独立 ≠ 不能同时使用——见上面的加载配方。
+
+两库在概念层出现互相印证是**好事**，说明知识是自洽的。例如 `bd/` 中
+`penalty_sheet.business_type` 的枚举值（超时预约/超时签到/拒绝服务），
+正好对应本库 L2 §7.4 记录的四个系统自动判罚节点——这类交叉验证应当记录，但仍不建立文件链接。
+
+---
+
+# 五、来源与维护
+
+## 已抽取来源
+
+| 来源 | 贡献层级 | 说明 |
+|---|---|---|
+| 业务方访谈 | **L1** | 产出根级知识最直接的途径 |
+| 客服工单 SOP 与对外规则合集 | **L1** / L2 / L3 | 工单与治理体系全套概念；治理边界（反向溯因所得）；大量规则进 L3 索引 |
+| 官网 [wanshifu.com](https://www.wanshifu.com/) | L1 / L2 | 交易模式、服务矩阵、保障体系 |
+| 履约配置化 PRD、违规拒单 prompt | L1 / L2 | 履约骨架、非标性、TOC/TOB 结构 |
+| `payment/ai-knowledge`（支付/风控等 8 系统） | L2 | 资金域概念。**⚠️ 按旧标准抽取，值得用三层框架重扫** |
+| `dev-knowledge-base`（营销中台 15 服务） | L2 | 角色术语。**⚠️ 同上，值得重扫** |
+| `../bd/` | L2 | 业务域缩写 |
+
+抽取后即与源脱钩、独立维护，来源仅供溯源。
+
+## 维护约定
+
+- 只维护"当前有效状态"，改了直接覆盖，版本历史交给 git
+- 每条内容标注来源
+- **框架或判定标准变更后，重扫已抽取过的来源**（性质 4）——上表已标注待重扫的源
+- L1 超过预算 → 按"性质 3"里的三步判断，不要直接放宽上限
+- L3 出现具体数值副本 → 检查是否该改成链接
+- 发现某条内容挂不到上一层 → 按性质 1 处理，别硬留
+
+## ❓ 标记的生命周期
+
+推测性内容必须标 ❓ 并注明"待确认"，**未确认前不得当作事实使用**。
+
+- **只能由业务方确认后摘除**——不能因为"看起来合理""和其他材料不矛盾"就自行转正
+- 确认后：去掉 ❓，在来源表注明"业务方访谈 + 日期"
+- **长期无人确认的 ❓ 应保留，不要删**——它标记了一个已知缺口，
+  比假装没这回事强；`_golden-questions.md` 会把它计入缺口统计

wsf/biz/_golden-questions.md

@@ -0,0 +1,138 @@
+---
+title: Golden Questions — biz 知识库完备性度量清单
+source_status: 2026-07-31 首次起草并按三层重构校准；2026-08-03 客服SOP 二次抽取后再次校准
+type: 治理文件（不是知识内容本身）
+---
+
+# 这份清单是什么
+
+`biz/` 知识库的**验收标准与完备性度量**。用法：
+
+1. 把问题连同 `biz/` 全部内容一起交给模型，看它能否答对
+2. 答错/答不出的位置，直接告诉你该补什么、补到哪一层
+3. **新增知识前先问：它能让哪个问题从答不出变成答得出？** 答不上来的内容，大概率不该收
+
+**选题标准**：只收"推不出来"和"推出来会错"的问题。看一眼官网就知道的，不是 golden question。
+
+**标记**：✅ 能答 / ⚠️ 部分能答（概念有、细节需查 L3）/ ❌ 答不出 / ⬜ 已裁定不属本库范围
+
+---
+
+## A. 取数与指标口径
+
+> 消费方：取数 Agent、分析师。失败后果：SQL 跑得出来但数字是错的——**最危险，因为不报错**。
+
+| # | 问题 | 陷阱 | 现状 |
+|---|---|---|---|
+| A1 | "新客销售额"怎么算？ | 首次支付 vs 首次下单，两种都说得通，结果不同 | ❌ |
+| A2 | GMV 扣不扣后续退款？ | 口径分叉点 | ❌ |
+| A3 | "完工率"的分母是什么？ | 派单数/接单数/支付订单数，各部门口径可能不一致 | ❌ |
+| A4 | 统计"师傅数"指哪个师傅？ | 注册/实名/有接单资格/近期活跃，差很远 | ❌ |
+| A5 | 一个订单对应几笔交易？能直接 count 订单当交易数吗？ | 一对多，直接 count 会错 | ✅ L2§4 |
+| A6 | 指标后缀 `cnt`/`num`/`amt` 什么意思？ | 数仓规范与分析师规范说法相反 | ⚠️ L3§7 指向 `bd/` |
+| A7 | 算师傅罚款时罚单按什么去重？ | 一罚单多条状态流水，不去重会重复计数 | ⚠️ L3§7 指向 `bd/` |
+| A8 | 企业订单和商家订单统计时算一类吗？ | 四种下单方类型是否合并需明确 | ⚠️ L2§2.2 有分类，无口径 |
+| A9 | 平台收入怎么算？ | = 师傅成交额 × 品类佣金率，不是下单方付款额 | ✅ L1§4 |
+| A10 | 数仓 `penalty_sheet` 里的罚单是怎么产生的？ | 系统在预约/签到/拒单/完工四节点自动判罚生成 | ✅ L2§7.4 |
+
+## B. 客服与风控判断
+
+> 消费方：客服 Agent、风控。失败后果：答复错误直接产生客诉、资损或误杀。
+
+| # | 问题 | 陷阱 | 现状 |
+|---|---|---|---|
+| B1 | 师傅拒单一定是师傅责任吗？ | 客户/商家/不可抗力都可能是责任方 | ⚠️ L3§3 有索引，无判定细则 |
+| B2 | 订单图片里有手机号就是违规引流吗？ | **归属方**才是决定性维度：商家水印→违规；场所/客户/厂家→正常 | ⚠️ L3§5 指向权威源 |
+| B3 | 什么条件下平台先行赔付？ | 有明确条件，非无条件 | ⚠️ L2§6 有概念，L3§3 有索引 |
+| B4 | 服务质量分扣到多少会被限制接单？ | 有分档阈值 | ⚠️ L2§5 有机制，L3§2 有索引 |
+| B5 | 服务质量分和综合评分是一回事吗？ | 两套独立体系 | ✅ L2§5 |
+| B6 | 总包能直接取消订单吗？ | 不能，只能改派且需原师傅同意 | ❌ |
+| B7 | 商品损坏判师傅责任吗？ | 默认以商家或客户责任为主 | ❌ |
+| B8 | 哪些情况必须转人工、不能自动答复？ | 金额争议/身份异常/到账争议等有红线 | ❌ |
+| B9 | 尾货订单风控口径和普通订单一样吗？ | 平台不参与交易，售卖类关键词不算违规 | ⚠️ L2§3.3 |
+| B10 | 师傅为什么会想引导线下交易？ | 每单省 15% 佣金，是**结构性动机**不是个别道德问题 | ✅ L1§4 |
+| B11 | 售后工单的 16 个分类能用来分类"所有售后问题"吗？ | **不能**——16 项全以"师傅"为主语，是追责分类不是中立分类 | ✅ L2§7.2 |
+| B12 | 售后工单、二线工单、申诉工单、外投工单有什么区别？ | 四者立场相反：追责师傅 / 咨询升级 / 师傅反驳平台 / 用户投诉平台 | ✅ L2§7.1 |
+| B13 | 客服发起的工单，用户能看到吗？ | 看不到，且无法自主举证 | ✅ L2§7.3 |
+| B14 | 师傅被系统判罚了，还有救吗？ | 有申诉通道 + 每月免责次数，**不是检测即处罚** | ✅ L1§9 / L2§7.4 |
+| B15 | 处罚力度是不是越严越好？ | 不是——供给留存约束治理力度，过严会流失师傅 | ✅ L1§9 |
+
+## C. 研发与领域建模
+
+> 消费方：编码 Agent、新系统设计者。失败后果：概念用错、造重复的词。
+
+| # | 问题 | 陷阱 | 现状 |
+|---|---|---|---|
+| C1 | "保证金"和"保障金"分别是什么？ | 一个是入驻方交的，一个是平台发的 | ✅ L2§4 |
+| C2 | "清算"和"结算"的区别？ | 确认钱是谁的 vs 钱真的到账 | ✅ L2§4 |
+| C3 | "授信"给谁的？师傅有授信额度吗？ | 给总包/企业的月结垫付，不是师傅信用 | ✅ L2§4 |
+| C4 | "渠道"和"渠道商户"是一回事吗？ | 商户是渠道下注册的身份 | ✅ L2§4 |
+| C5 | 平台已有哪些"钱"的概念？要加新额度该怎么命名？ | 钱包/保证金/保障金/授信已占位 | ✅ L2§4 |
+| C6 | "任务"（task）指什么？ | 营销触达任务 vs 活动内用户任务，两个子域 | ❌ |
+| C7 | 某品类的履约有哪些节点？ | **没有唯一答案**——节点是配置出来的，须查配置 | ✅ L2§3.2 |
+| C8 | `account_type` 有哪些取值？ | 各服务枚举不同 | ⬜ 已裁定：属技术约定，不入本库 |
+| C9 | 金额字段单位是什么？ | 全链路以分为单位 | ⬜ 同上 |
+| C10 | 幂等能用 MQ messageId 吗？ | 不能，须用业务唯一键 | ⬜ 同上 |
+
+## D. 业务模式与角色
+
+> 消费方：新人、通用业务问答。失败后果：基本理解错位，后续推理全偏。
+
+| # | 问题 | 陷阱 | 现状 |
+|---|---|---|---|
+| D1 | 师傅是万师傅的员工吗？ | 不是，自主经营个体——决定了治理而非管理 | ✅ L1§3 |
+| D2 | 万师傅靠什么赚钱？ | 向**师傅**抽佣（按品类约 15%）+ 保险提成 | ✅ L1§4 |
+| D3 | "总包"是什么？平台付钱给总包吗？ | **反了**——总包付钱给平台，赚协议价与平台价的差价 | ✅ L1§7 |
+| D4 | KA 用户在哪下单？ | 不直接在平台下单，经总包 | ✅ L1§7 |
+| D5 | 一口价和报价招标什么区别？ | 竞价+指派 vs 定价+抢单，师傅获单方式相反 | ✅ L2§1 |
+| D6 | TOB 订单里师傅联系的是谁？ | 商家的终端客户，不是下单的商家 | ✅ L1§7 |
+| D7 | "商家"和"企业用户"是一回事吗？ | 是同一类主体的两种叫法，订单类型亦同 | ✅ L2§2.1 / §2.2 |
+| D8 | 师傅的钱什么时候到账？ | 验收后结算，当前 T+1 且可配置 | ✅ L2§4 |
+| D9 | 师傅履约的标准步骤？ | 跨品类最小骨架 | ✅ L1§8 |
+| D10 | 订单有哪些正式状态？ | 状态机 | ❌ |
+| D11 | 平台做哪些服务品类？ | 类目 × 类型两个维度 | ✅ L2§3.1 |
+| D12 | 平台对用户承诺哪些保障？ | 担保交易/质检/先行赔付/商业保险 | ✅ L2§6 |
+| D13 | 为什么履约流程要做成可配置的？ | 品类非标 + 类目变更是常态 | ✅ L1§5 |
+
+---
+
+## 不该由本库回答的（负面样例）
+
+- "师傅 P123456 的评分是多少" → 实时数据查询
+- "上个月 GMV 多少" → 数据查询（但"GMV 怎么定义"是 A2，属本库）
+- "拆旧费收多少钱" → L3 只登记权威源，具体数值查源文档
+- "这个 SQL 怎么写" → `../bd/`
+- "工单该怎么处理" → 客服 SOP
+
+---
+
+## 现状盘点（2026-08-03）
+
+**在范围内 45 题：✅ 28 / ⚠️ 7 / ❌ 10**，完全命中约 62%，含部分命中约 78%。
+（另有 3 题已裁定不属本库范围）
+
+演进：✅ 12/37（重构前）→ 21/39（三层重构后）→ 28/45（客服SOP 二次抽取后）。
+第一次提升来自 **L1 补全**，第二次提升来自**换用三层视角重读同一份材料**——
+同一个 zip，第一次只抽出 3 条，第二次抽出一整块 L2（工单与治理体系）加一条 L1。
+
+### 剩余缺口，按优先级
+
+| 优先级 | 缺口 | 说明 |
+|---|---|---|
+| **高** | **A 组指标口径几乎全空**（A1-A4） | 若主消费方含取数 Agent，这是最该补的一块。**但它属于 `bd/` 还是 `biz/` 需先定边界** |
+| **高** | **订单状态机**（D10、B6） | L1§8 已标待补。影响所有涉及订单的推理 |
+| 中 | B 组判定细则（B6/B7/B8） | 概念层有了，判定边界缺失，Agent 仍不敢下判断 |
+| 中 | 会员体系 | 官网与客服SOP均提及，未找到权威定义（L3 已登记为缺口） |
+| 低 | C6 task 歧义 | 局部歧义，影响面小 |
+
+### 下一步建议
+
+1. **补订单状态机** —— 单点收益最高，一条知识解锁多个问题
+2. **定 A 组归属** —— 指标口径放 `bd/` 还是 `biz/`？现在两边都没有，是真空地带
+3. **继续用 L3 反向溯因挖 L1** —— 拿 L3 索引里的规则逐条问"为什么"，
+   例如"为什么服务质量分要一年清零""为什么先行赔付要设条件"，可能挖出新的根级前提
+
+## 关联
+
+- [README.md](README.md) —— 分层原则与判定流程
+- [L1-essence.md](L1-essence.md)、[L2-concepts.md](L2-concepts.md)、[L3-rules-index.md](L3-rules-index.md) —— 被度量的内容