Add value-scan and value-dig skills for reverse-engineering value points
- value-scan: read-only breadth inventory of mechanisms in delivered code, stopping at the human selection gate - value-dig: depth write-up of chosen points (feature list, design review, refactor plan) with templates and mechanical checkers - Add skill-workbench design doc for the pair
This commit is contained in:
zhuyongxin
@@ -0,0 +1,206 @@
|
||||
# ⟨主题⟩ · 设计思路与取舍（复盘）（S4 产物 ②）
|
||||
|
||||
> **视角**：第一人称复盘——**我拿到「⟨需求名⟩」这个需求时，是怎么想、怎么设计、怎么取舍、预判会遇到什么问题的**。贴合现有实现，末尾给改进建议与可直接口述的版本。
|
||||
> **配套文档**：功能点见同目录《⟨主题⟩-功能点清单.md》；⟨可选的关联文档⟩
|
||||
> **说明**：文中「我会这样想」是设计时的推理；「实际做法」是代码里的真实实现，**两者不一致处必须标出**。
|
||||
> **路径简写**：`⟨简写⟩/` = `⟨真实路径⟩`
|
||||
|
||||
---
|
||||
|
||||
## 0. 我拿到需求，先不写代码：把问题定义清楚
|
||||
|
||||
**需求的一句话**：⟨…⟩
|
||||
|
||||
**我第一件事是承认 N 个事实**，它们决定了后面所有设计：
|
||||
|
||||
1. **⟨例：对方的回答不是二元的⟩。** ⟨…⟩
|
||||
2. **⟨例：几种失败的"可逆性"不同⟩。** ⟨…⟩
|
||||
3. **⟨例：我没法从"失败"这个现象本身推出可逆性⟩。** ⟨…⟩
|
||||
|
||||
**由此我定下 N 条不变量（当成验收标准）**：
|
||||
|
||||
- **不变量一**：⟨例：只有确定对方没接单才退款⟩——⟨为什么⟩；
|
||||
- **不变量二**：⟨例：不确定的失败不能当成失败处理⟩——⟨为什么⟩；
|
||||
- **不变量三**：⟨例：每一种失败都必须有归属⟩——⟨为什么⟩。
|
||||
|
||||
**再看 N 个我不能改变的前提**：⟨省侧是权威 · 对外调用有副作用 · 没有跨系统事务 · …⟩
|
||||
|
||||
**结论**：⟨这不是"加个 try-catch 再套个重试框架"的需求，而是「把异常翻译成后果」的需求。⟩——**这句是我做取舍时反复回到的锚点。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 我怎么拆这个需求
|
||||
|
||||
**第一刀，我按「⟨拆解维度⟩」拆，不按「⟨被否决的维度⟩」拆。**
|
||||
|
||||
| 为什么否决另一个维度 | ⟨例：按商品类型拆会得到三块，但三种商品的前置动作不同、汇合点却是同一个；各写一套会得到三份可能走偏的代码⟩ |
|
||||
|---|---|
|
||||
|
||||
拆完是 ⟨N⟩ 条路 + ⟨N⟩ 个汇合点：
|
||||
|
||||
| 路径 | ⟨前置动作⟩ | ⟨性质⟩ | 风险 |
|
||||
|---|---|---|---|
|
||||
| ⟨…⟩ | | 异步 / 同步 | |
|
||||
|
||||
**第二刀，我找「⟨关键定位决策⟩」，这是本需求最关键的一个决策。**
|
||||
|
||||
**我的判断是**：⟨…⟩。理由：⟨只有那一层同时拿得到 X 和 Y；再往上一层只能看到一个已被包装过的异常，原始信息已经丢了⟩。
|
||||
|
||||
**实际做法与我的判断是否一致**：⟨是 / 否⟩，证据 `⟨路径:行号⟩`。
|
||||
|
||||
**这个决策的代价**：⟨例：调用层要维护两套调用方式；推广不全会造成覆盖面缺口（实际就漏了）⟩。
|
||||
|
||||
---
|
||||
|
||||
## 2. 我的设计主线：⟨一句话概括主线⟩
|
||||
|
||||
⟨这是我做的最核心的一个决定：不给 A/B/C 各写一套处理，而是让它们沿一条固定的链往下走，每层只做一件事。⟩
|
||||
|
||||
```
|
||||
① ⟨层名（职责）⟩ → ② ⟨层名（职责）⟩ → ③ ⟨层名（职责）⟩ → ④ ⟨层名（职责）⟩
|
||||
```
|
||||
|
||||
**⟨N⟩ 层不是我拍脑袋凑的，是从"上一版为什么会漏"反推出来的**——每层都对着一个旧实现的具体病灶：
|
||||
|
||||
| 层 | 旧实现的病灶 | 我的做法 | 为什么必须在这一层做 |
|
||||
|:-:|---|---|---|
|
||||
| ① | | `⟨路径:行号⟩` | ⟨信息只在最底层存在，越往上越不可恢复⟩ |
|
||||
| ② | | | |
|
||||
| ③ | | | |
|
||||
| ④ | | | |
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["⟨入口⟩"] --> B["① ⟨层⟩"]
|
||||
B --> C{"② ⟨层⟩"}
|
||||
C -->|"⟨…⟩"| D["③ ⟨层⟩"]
|
||||
C -->|"⟨…⟩"| E["③ ⟨层⟩"]
|
||||
D --> F["④ ⟨归集⟩"]
|
||||
E --> F
|
||||
F -->|"⟨可逆⟩"| G["⟨处置⟩"]
|
||||
F -->|"⟨不确定⟩"| H["⟨处置⟩"]
|
||||
```
|
||||
|
||||
### 2.1 ⟨N⟩ 重判断，才是这个设计的真正内容（标题按实际重数写，如「三重判断…」）
|
||||
|
||||
> 比"N 层"更重要的是**层里做的判断**——它们才是经验，层只是载体。
|
||||
|
||||
**判断一：⟨…⟩**
|
||||
|
||||
⟨用收益 × 概率算的：…⟩ **关键点是"不做什么"比"做什么"更难做对**——⟨因为框架默认什么都做⟩。
|
||||
|
||||
**判断二：⟨…⟩**
|
||||
|
||||
⟨…⟩ **代价必须自己扛**：⟨你关掉了 X，就必须自己承担 Y 的责任。⟩
|
||||
|
||||
**判断三：⟨…⟩**
|
||||
|
||||
⟨…⟩ **为什么"⟨反面做法⟩"是错的**：⟨…⟩
|
||||
|
||||
**还有一条我特意保留的例外**：⟨…⟩——因为 ⟨…⟩。
|
||||
|
||||
### 2.2 ⟨独立工具/组件名⟩ 为什么要写成一个独立⟨工具/组件⟩（若无可删本节）
|
||||
|
||||
⟨它看着简单，但它是整个 ⟨机制⟩ 的地基——判错一次，方向就错，后面全走偏。⟩
|
||||
|
||||
1. **精确匹配** ⟨…⟩；
|
||||
2. **兜底模糊匹配** ⟨…⟩；
|
||||
3. **逐层剥 `cause`**——⟨因为异常常被框架层层包装，真实原因往往在第三、四层⟩。
|
||||
|
||||
**这里的取舍我很清楚**：⟨选了"宁可多试一次"——因为重试的成本（多一次调用）远低于漏重试的成本（一单卡死）⟩。
|
||||
|
||||
---
|
||||
|
||||
## 3. 逐环节决策复盘
|
||||
|
||||
| # | 当时的问题 | 我的选择 | 为什么 | 代价 / 风险 |
|
||||
|:-:|---|---|---|---|
|
||||
| 1 | ⟨…⟩ | | | |
|
||||
| 2 | | | | |
|
||||
| 3 | | | | |
|
||||
| … | | | | |
|
||||
|
||||
> **代价/风险列不可空**——只讲选择不讲代价，就等于没做取舍。
|
||||
|
||||
---
|
||||
|
||||
## 4. 我预判会遇到的问题（拿到需求时就能想到的）
|
||||
|
||||
1. **⟨…⟩。** ⟨…⟩
|
||||
2. **⟨…⟩。** ⟨…⟩
|
||||
3. **⟨…⟩。** ⟨这是我设计时预判到了却仍然漏掉的一条⟩
|
||||
|
||||
---
|
||||
|
||||
## 5. 我做对的 ⟨N⟩ 件事 / 承接不住的 ⟨N⟩ 件事
|
||||
|
||||
**做对的**
|
||||
|
||||
1. **⟨…⟩**——⟨为什么它最有价值；它是从业务语义推出来的，不是从技术模式套出来的⟩。
|
||||
2. **⟨…⟩**——⟨…⟩
|
||||
3. **⟨…⟩**——⟨方向是对的，只是推广范围不够⟩
|
||||
|
||||
**承接不住的**
|
||||
|
||||
1. **⟨…（最严重）⟩**——⟨后果；这是"设计对了但落地不完整"的典型案例⟩。
|
||||
2. **⟨…⟩**
|
||||
3. **⟨…⟩**
|
||||
|
||||
---
|
||||
|
||||
## 6. 如果让我重做，我会改什么（按性价比排序）
|
||||
|
||||
> 复盘视角只给**优先级判断**；分阶段展开、验收标准与灰度见《⟨主题⟩-改造方案.md》，此处不重复。
|
||||
|
||||
| 优先级 | 改什么 | 为什么 | 成本 | 收益 |
|
||||
|:-:|---|---|---|---|
|
||||
| **P0** | | ⟨**真金白银 / 会花错钱**⟩ | 低 | |
|
||||
| **P1** | | | 中 | |
|
||||
| **P2** | | | | |
|
||||
| **P3** | | ⟨卫生问题⟩ | | |
|
||||
|
||||
**一句话排序逻辑**：先修**会花错钱和会重复调用外部系统的**（P0/P1），再做**让"不确定"可运营**（P1/P2），最后才是卫生问题（P3）。**因为前两类是"静默地把事情做错"，后者只是"做得不够漂亮"。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 这套设计里可以复用的方法论
|
||||
|
||||
1. **⟨先判"可逆性"，再决定"要不要补偿"。⟩** ⟨任何跨系统写操作都适用…⟩
|
||||
2. **⟨异常分层翻译：真相层 → 重试层 → 履历层 → 归集层。⟩** ⟨每层只做一件事，且必须在能拿到信息的最高层把信息捞住⟩
|
||||
3. **⟨重试责任单点。⟩** ⟨否则是乘法关系，不是加法⟩
|
||||
4. **⟨"不确定"必须是一等状态。⟩** ⟨否则会退化成一行日志，等于不存在⟩
|
||||
5. **⟨分级的上限取决于覆盖面，不是取决于精细度。⟩** ⟨一条路上做四层分级，不如四条路上各做一层⟩
|
||||
|
||||
---
|
||||
|
||||
## 8. 附：面试口述版
|
||||
|
||||
### 8.1 一分钟版（先讲骨架）
|
||||
|
||||
> 「⟨需求一句话⟩。我的判断是：⟨核心判断⟩。所以我不能只写 try-catch，得**把 ⟨X⟩ 翻译成 ⟨Y⟩**。
|
||||
>
|
||||
> 设计上是 N 层：⟨逐层一句话⟩。调用方只做一件事：⟨…⟩。」
|
||||
|
||||
### 8.2 三分钟版（加取舍与代价）
|
||||
|
||||
在上一段基础上补三段：⟨取舍一（最看重的一点）+ 它的代价⟩ · ⟨取舍二 + 难在哪⟩ · ⟨要坦白的一点（覆盖面 / 落地不完整）⟩。
|
||||
|
||||
### 8.3 追问预判（问题 → 一句话答）
|
||||
|
||||
| 追问 | 答 |
|
||||
|---|---|
|
||||
| ⟨为什么…？⟩ | ⟨一句话⟩ |
|
||||
| ⟨既然…，那…？⟩ | ⟨一句话，含"坦白说没有"这类诚实回答⟩ |
|
||||
| ⟨这套设计最大的风险？⟩ | ⟨一句话⟩ |
|
||||
|
||||
---
|
||||
|
||||
## 附：与代码的对照说明
|
||||
|
||||
| 本文的判断 | 代码事实 | 是否一致 |
|
||||
|---|---|---|
|
||||
| ⟨分级放最底层⟩ | `⟨路径:行号⟩` | ✅ 一致，但**未推广** |
|
||||
| ⟨只重超时⟩ | `⟨路径:行号⟩` | ✅ 一致 |
|
||||
| ⟨…⟩ | | ⚠️ 部分一致 |
|
||||
|
||||
> **诚实性要求**：本文的判断与代码事实**不一致处必须逐条列出**——这是这份文档可信度的来源。
|
||||
Reference in New Issue
Block a user