架构体检

找出值得加深的模块：接口几乎和实现一样复杂、理解一个概念要在许多小文件间来回跳、bug 藏在调用方式里的地方。目标是改一处就够、测试只打一个入口。

1. 圈范围

用户指了模块、子系统或痛点就只看那里。否则沿较长一段 git log --oneline 找反复改动的热点，优先看它们；改动分散时再扩大。按 fan-out 中档按热点拆片，交回摩擦点及证据（文件、调用方）。

判断一个模块是不是透传层，用删除测试：想象删掉它，复杂度随之消失的是透传层；复杂度散回 N 个调用方的，它在干活。

2. 呈现

按 eli5 把候选画成图解，文件放 $TMPDIR，不进仓库。每个候选讲清：涉及文件、问题、改法、收益（用行为说：改价格规则只动一个文件，不写「更易维护」）、改前改后对比图、推荐强度（值得做 / 值得探索 / 推测）、依赖类别（见下）。最后说最先做哪一个及原因。此时不提接口方案，问用户想展开哪一个。

3. 设计接口

用户选定后，先写一段约束说明（新接口必须满足什么、依赖属于哪一类、一段粗略代码示意）给用户看，同时按 fan-out 高档并行出 3 个以上截然不同的接口：

• 最小接口：1–3 个入口，每个入口承担尽量多的行为。
• 最大灵活：支持多种用例与扩展。
• 为最常见的调用方优化：默认情况最简单。
• （跨进程依赖时）围绕端口与适配器设计。

每份方案交回：接口（类型、不变量、调用顺序、错误形态）、调用示例、藏在接口后面的东西、依赖与适配器、强弱处。逐个展示后比较：调用方学一个接口能用到多少行为、改动会不会集中在一处、接口放在哪。给出明确推荐，能取长补短就提混合方案。需要逐项和用户对齐决策时用 grilling。

依赖类别

类别决定加深后怎么测：

1. 进程内（纯计算、内存状态）：直接合并，经新接口测试。
2. 可本地替代（PGLite 代 Postgres、内存文件系统）：用替代物测，不在接口上开端口。
3. 自有远程服务：接口处定义端口，生产用 HTTP/队列适配器，测试用内存适配器。
4. 第三方服务（Stripe 等）：作为注入的端口，测试给模拟适配器。

判断规则

• 只有一个适配器的端口是假设，两个（通常是生产 + 测试）才是真的；不够两个就别开端口，那只是多一层间接。
• 内部接缝可以给自己的测试用，不为此暴露到接口上。
• 加深后，浅模块上的旧单元测试删掉；改动从新接口的真实入口验证。