@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/localized/zh-CN/skills/fec-code-smells/references/smell-catalog.md

@@ -0,0 +1,817 @@
+# 代码坏味道目录
+
+本目录基于用户提供资料第 3 章的 24 种坏味道分类，转换为面向前端工程的证据式诊断卡。标准中英文名称与 ID 保持稳定，说明文字为项目化重写。
+
+## SMELL-MYSTERIOUS-NAME — 神秘命名（Mysterious Name）
+
+### 诊断含义
+命名无法直接说明程序元素的用途或使用方式。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 缩写若是团队明确约定且领域内普遍理解，不应仅因缩写而判定坏味道。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-RENAME-VARIABLE`
+- `RF-RENAME-FIELD`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-DUPLICATED-CODE — 重复代码（Duplicated Code）
+
+### 诊断含义
+相同或近似的代码结构在多个位置重复出现，并需要同步演进。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 外观相似但业务变化原因不同的代码，不应机械合并。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-FUNCTION`
+- `RF-SLIDE-STATEMENTS`
+- `RF-PULL-UP-METHOD`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-LONG-FUNCTION — 过长函数（Long Function）
+
+### 诊断含义
+函数混合了多个意图，必须深入阅读实现细节才能理解其职责。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 不能只凭行数判定；内聚且需要连续阅读的算法可以合理地较长。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-FUNCTION`
+- `RF-REPLACE-TEMP-WITH-QUERY`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-PRESERVE-WHOLE-OBJECT`
+- `RF-REPLACE-FUNCTION-WITH-COMMAND`
+- `RF-DECOMPOSE-CONDITIONAL`
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+- `RF-SPLIT-LOOP`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-LONG-PARAMETER-LIST — 过长参数列表（Long Parameter List）
+
+### 诊断含义
+函数接收大量彼此分散的参数，使参数之间的关系和来源难以理解。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 若边界确实需要多个独立值，参数对象反而掩盖含义，则不应强行包装。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-REPLACE-PARAMETER-WITH-QUERY`
+- `RF-PRESERVE-WHOLE-OBJECT`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-REMOVE-FLAG-ARGUMENT`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-GLOBAL-DATA — 全局数据（Global Data）
+
+### 诊断含义
+可被广泛访问的数据缺少受控的读取和修改边界。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 启动后不可变的全局配置风险较低，但仍可通过封装明确所有权。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-ENCAPSULATE-VARIABLE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-MUTABLE-DATA — 可变数据（Mutable Data）
+
+### 诊断含义
+数据可从多处被修改或同一变量承载多种含义，使状态变化难以推理。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 清晰算法内部、作用域受控的局部可变状态并不自动构成坏味道。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-ENCAPSULATE-VARIABLE`
+- `RF-SPLIT-VARIABLE`
+- `RF-SLIDE-STATEMENTS`
+- `RF-EXTRACT-FUNCTION`
+- `RF-SEPARATE-QUERY-FROM-MODIFIER`
+- `RF-REMOVE-SETTING-METHOD`
+- `RF-REPLACE-DERIVED-VARIABLE-WITH-QUERY`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+- `RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`
+- `RF-CHANGE-REFERENCE-TO-VALUE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-DIVERGENT-CHANGE — 发散式变化（Divergent Change）
+
+### 诊断含义
+一个模块会因为多个彼此无关的原因或上下文而频繁变化。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 小而内聚的模块可以合理响应多个紧密相关的变化。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-SPLIT-PHASE`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-EXTRACT-CLASS`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-SHOTGUN-SURGERY — 霰弹式修改（Shotgun Surgery）
+
+### 诊断含义
+一个概念性变化需要在代码库许多位置进行零散修改。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 遥测等横切关注点可能有意跨边界，需结合基础设施设计判断。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-MOVE-FUNCTION`
+- `RF-MOVE-FIELD`
+- `RF-COMBINE-FUNCTIONS-INTO-CLASS`
+- `RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`
+- `RF-SPLIT-PHASE`
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-FEATURE-ENVY — 依恋情结（Feature Envy）
+
+### 诊断含义
+一个函数对其他模块的数据或行为依赖明显强于对自身模块的依赖。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 编排函数本就可能协调多个所有者，不应仅因跨模块访问而整体搬移。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-DATA-CLUMPS — 数据泥团（Data Clumps）
+
+### 诊断含义
+同一组数据项反复以字段或参数形式成组出现。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 一次性的临时传输结构未必值得建立领域抽象。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+- `RF-PRESERVE-WHOLE-OBJECT`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-PRIMITIVE-OBSESSION — 基本类型偏执（Primitive Obsession）
+
+### 诊断含义
+带有领域规则或不变量的概念仅使用普通字符串、数字或布尔值表达。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 没有领域行为或不变量的普通值无需为了“对象化”而包装。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-REPLACE-PRIMITIVE-WITH-OBJECT`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+- `RF-EXTRACT-CLASS`
+- `RF-INTRODUCE-PARAMETER-OBJECT`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-REPEATED-SWITCHES — 重复的 switch（Repeated Switches）
+
+### 诊断含义
+同一类型或变体判断在多个条件分支中重复出现并需要保持同步。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 单个 switch 不能证明“重复的 switch”；集中且穷尽的分派器可能是合适设计。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-LOOPS — 循环语句（Loops）
+
+### 诊断含义
+命令式循环掩盖了本可更直接表达意图的数据变换过程。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 性能敏感、需要提前退出、带状态或异步控制的循环可能使用循环更清晰。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-REPLACE-LOOP-WITH-PIPELINE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-LAZY-ELEMENT — 冗赘的元素（Lazy Element）
+
+### 诊断含义
+抽象层没有提供足够的命名、行为或变化隔离价值，却增加了间接层。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 很小的命名函数只要能表达意图或提供稳定边界，仍可能有价值。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-COLLAPSE-HIERARCHY`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-SPECULATIVE-GENERALITY — 夸夸其谈通用性（Speculative Generality）
+
+### 诊断含义
+抽象、参数或扩展点主要服务于假设性的未来需求，而当前没有真实用例。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 有明确证据支持的近期兼容需求可以合理保留扩展点。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-COLLAPSE-HIERARCHY`
+- `RF-INLINE-FUNCTION`
+- `RF-INLINE-CLASS`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-REMOVE-DEAD-CODE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-TEMPORARY-FIELD — 临时字段（Temporary Field）
+
+### 诊断含义
+字段只在某个阶段或特殊条件下有意义，使对象在其他时刻处于难解释的半有效状态。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 明确建模的部分状态或异步状态包含可选字段，并不自动构成坏味道。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-CLASS`
+- `RF-MOVE-FUNCTION`
+- `RF-INTRODUCE-SPECIAL-CASE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-MESSAGE-CHAINS — 过长的消息链（Message Chains）
+
+### 诊断含义
+客户端依赖穿过多个对象的导航路径才能取得真正需要的数据或行为。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 函数/数组管道并不自动等于消息链；流式 API 可以是有意且内聚的。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-HIDE-DELEGATE`
+- `RF-EXTRACT-FUNCTION`
+- `RF-MOVE-FUNCTION`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-MIDDLE-MAN — 中间人（Middle Man）
+
+### 诊断含义
+一个抽象的大部分接口只是转发调用，没有增加有价值的策略或保护。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- React/Vue 的声明式组合不自动等于中间人；包装组件可能承担无障碍、样式或兼容策略。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-REMOVE-MIDDLE-MAN`
+- `RF-INLINE-FUNCTION`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-INSIDER-TRADING — 内幕交易（Insider Trading）
+
+### 诊断含义
+模块之间交换过多内部数据或知识，导致边界被侵蚀。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 当职责确实跨模块时，显式且窄的协作是正常的。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-MOVE-FUNCTION`
+- `RF-MOVE-FIELD`
+- `RF-HIDE-DELEGATE`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-LARGE-CLASS — 过大的类（Large Class）
+
+### 诊断含义
+类或等价模块拥有过多字段和职责，容易产生重复与无关变化。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 不能仅凭行数判定过大的类；内聚的数据结构或生成型适配器可能本就较大。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-CLASS`
+- `RF-EXTRACT-SUPERCLASS`
+- `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-ALTERNATIVE-CLASSES-DIFFERENT-INTERFACES — 异曲同工的类（Alternative Classes with Different Interfaces）
+
+### 诊断含义
+两个概念上可替换的实现提供相似能力，却使用不一致的接口。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 若两个概念本就不可替换，则不同接口是合理的。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-SUPERCLASS`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-DATA-CLASS — 纯数据类（Data Class）
+
+### 诊断含义
+数据容器被其他模块细碎操控，而与数据相关的行为散落在外部。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 不可变 DTO、API 响应和中间变换记录可以合理地保持纯数据形态。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-ENCAPSULATE-RECORD`
+- `RF-REMOVE-SETTING-METHOD`
+- `RF-MOVE-FUNCTION`
+- `RF-EXTRACT-FUNCTION`
+- `RF-SPLIT-PHASE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-REFUSED-BEQUEST — 被拒绝的遗赠（Refused Bequest）
+
+### 诊断含义
+子类型继承了与自身真实替换关系或职责不匹配的数据和行为。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 子类不必使用父类每个辅助成员；仅有未使用成员不足以证明被拒绝的遗赠。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-PUSH-DOWN-METHOD`
+- `RF-PUSH-DOWN-FIELD`
+- `RF-REPLACE-SUBCLASS-WITH-DELEGATE`
+- `RF-REPLACE-SUPERCLASS-WITH-DELEGATE`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。
+
+## SMELL-COMMENTS — 注释（Comments）
+
+### 诊断含义
+注释被用来解释本可由代码结构直接表达的复杂意图；注释本身并不是缺陷。
+
+### 强信号
+- 在真实代码中能观察到与上述含义一致的重复依赖、职责混杂、接口不协调或变化耦合。
+- 修改该区域时，需要额外追踪多个位置、隐含状态或实现细节才能保持正确。
+
+### 弱信号
+- 阅读者经常需要跨文件跳转才能解释当前意图。
+- 该区域的结构性修改历史上容易遗漏关联点。
+
+### 误判保护
+- 注释本身不是缺陷；解释原因、约束和非显而易见决策的注释很有价值。
+
+### 必须提供的证据
+- 指出具体文件/符号，并展示实际的重复关系、变化模式或结构负担；不能只依据行数或复杂度指标下结论。
+
+### 可能影响
+- 增加理解成本、变化耦合或结构演进时的回归风险。
+
+### 候选重构
+- `RF-EXTRACT-FUNCTION`
+- `RF-CHANGE-FUNCTION-DECLARATION`
+- `RF-INTRODUCE-ASSERTION`
+
+### 相关坏味道
+- 相关坏味道必须独立取证，不因当前坏味道自动成立。
+
+### 前端常见表现
+- 可出现在 React/Vue 组件、Hook/Composable、Store、API Client、路由、表单或数据转换代码中；判断时优先检查真实数据所有权、生命周期和公共契约。