@bovinphang/frontend-craft 2.8.0 → 2.9.0

package/localized/zh-CN/skills/fec-refactoring-data/references/data-refactorings.md

@@ -0,0 +1,248 @@
+# 数据重组类重构
+
+这些卡片以用户提供的标准重构目录为知识基线，转换为面向前端 Agent 的操作指南。保留标准 ID/中英文名称，框架适配和示例为项目原创内容。
+
+## RF-SPLIT-VARIABLE — 拆分变量（Split Variable）
+
+### 意图
+当同一个变量先后承载不同含义时，为不同角色建立不同变量。
+
+### 典型信号
+- 当前结构出现与本手法目标一致的重复、耦合、命名、职责、数据所有权或控制流问题，并有具体代码证据。
+
+### 不适用条件
+- 当前结构已经清晰，或该变换会制造更强耦合、隐藏依赖、破坏公共契约且没有兼容方案时，不使用。
+
+### 前置条件
+- 已明确当前可观察行为、受影响调用者和公共契约。
+- 目标位于声明的差异预算内，并且这个单一主要变换完成后能够立即验证。
+
+### 操作步骤
+1. 确认当前行为、调用者和边界，并锁定本步骤只处理这一项主要结构意图。
+2. 创建最小的新结构/位置/接口，让旧行为可以逐步迁移而不是一次性大改。
+3. 一次迁移一个调用点或职责片段，并保持兼容边界。
+4. 运行窄范围验证；若变红，先回滚本步骤，再缩小变换。
+
+### 行为保持检查点
+- 对比输入、输出、异常、副作用、执行顺序和公共契约。
+- 前端还要核对 UI 状态、事件、焦点、网络请求、生命周期/状态迁移，以及相关对象身份语义。
+
+### 相关坏味道
+- `SMELL-MUTABLE-DATA`
+
+### 常见组合
+- 不建立固定流水线；下一步必须重新依据证据选择。
+
+### JavaScript 注意事项
+- 保持相等性、对象身份、修改时机、序列化和属性访问语义。
+
+### TypeScript 注意事项
+- 用 `readonly`、窄领域类型和显式 DTO adapter 表达 reference/value 意图。
+
+### React 注意事项
+- 对象身份会影响 state 更新、memoization、dependency array、selector 和 reconciliation。
+
+### Vue 注意事项
+- 代理/引用身份会影响 `reactive`、`ref`、`computed`、`watch`、Pinia 订阅和模板更新。
+
+### Frontend-Craft 前端适配
+- 前端状态身份属于可观察行为，reference/value 选择必须有意为之。
+
+### 原创前端变换示例
+- 把“Split Variable”应用到一个局部组件/Hook/Composable/Service 范围内，先记录行为契约，只迁移一个职责片段，并立即验证输出、事件与状态变化保持不变。
+
+## RF-RENAME-FIELD — 字段改名（Rename Field）
+
+### 意图
+用准确领域词汇重命名字段，并显式处理 DTO、持久化、URL 和后端契约。
+
+### 典型信号
+- 当前结构出现与本手法目标一致的重复、耦合、命名、职责、数据所有权或控制流问题，并有具体代码证据。
+
+### 不适用条件
+- 当前结构已经清晰，或该变换会制造更强耦合、隐藏依赖、破坏公共契约且没有兼容方案时，不使用。
+
+### 前置条件
+- 已明确当前可观察行为、受影响调用者和公共契约。
+- 目标位于声明的差异预算内，并且这个单一主要变换完成后能够立即验证。
+
+### 操作步骤
+1. 确认当前行为、调用者和边界，并锁定本步骤只处理这一项主要结构意图。
+2. 创建最小的新结构/位置/接口，让旧行为可以逐步迁移而不是一次性大改。
+3. 一次迁移一个调用点或职责片段，并保持兼容边界。
+4. 运行窄范围验证；若变红，先回滚本步骤，再缩小变换。
+
+### 行为保持检查点
+- 对比输入、输出、异常、副作用、执行顺序和公共契约。
+- 前端还要核对 UI 状态、事件、焦点、网络请求、生命周期/状态迁移，以及相关对象身份语义。
+
+### 相关坏味道
+- `SMELL-MYSTERIOUS-NAME`
+
+### 常见组合
+- 不建立固定流水线；下一步必须重新依据证据选择。
+
+### JavaScript 注意事项
+- 保持相等性、对象身份、修改时机、序列化和属性访问语义。
+
+### TypeScript 注意事项
+- 用 `readonly`、窄领域类型和显式 DTO adapter 表达 reference/value 意图。
+
+### React 注意事项
+- 对象身份会影响 state 更新、memoization、dependency array、selector 和 reconciliation。
+
+### Vue 注意事项
+- 代理/引用身份会影响 `reactive`、`ref`、`computed`、`watch`、Pinia 订阅和模板更新。
+
+### Frontend-Craft 前端适配
+- 前端状态身份属于可观察行为，reference/value 选择必须有意为之。
+
+### 原创前端变换示例
+- 内部 `mailId` 实际表达 threadId，可在内部改名为 `threadId`，同时在 API adapter 保留后端仍要求的 `mailId` 字段。
+
+## RF-REPLACE-DERIVED-VARIABLE-WITH-QUERY — 以查询取代派生变量（Replace Derived Variable with Query）
+
+### 意图
+从源数据实时/按需推导值，消除需要手工同步的派生状态。
+
+### 典型信号
+- 当前结构出现与本手法目标一致的重复、耦合、命名、职责、数据所有权或控制流问题，并有具体代码证据。
+
+### 不适用条件
+- 当前结构已经清晰，或该变换会制造更强耦合、隐藏依赖、破坏公共契约且没有兼容方案时，不使用。
+
+### 前置条件
+- 已明确当前可观察行为、受影响调用者和公共契约。
+- 目标位于声明的差异预算内，并且这个单一主要变换完成后能够立即验证。
+
+### 操作步骤
+1. 确认当前行为、调用者和边界，并锁定本步骤只处理这一项主要结构意图。
+2. 创建最小的新结构/位置/接口，让旧行为可以逐步迁移而不是一次性大改。
+3. 一次迁移一个调用点或职责片段，并保持兼容边界。
+4. 运行窄范围验证；若变红，先回滚本步骤，再缩小变换。
+
+### 行为保持检查点
+- 对比输入、输出、异常、副作用、执行顺序和公共契约。
+- 前端还要核对 UI 状态、事件、焦点、网络请求、生命周期/状态迁移，以及相关对象身份语义。
+
+### 相关坏味道
+- `SMELL-MUTABLE-DATA`
+
+### 常见组合
+- 不建立固定流水线；下一步必须重新依据证据选择。
+
+### JavaScript 注意事项
+- 保持相等性、对象身份、修改时机、序列化和属性访问语义。
+
+### TypeScript 注意事项
+- 用 `readonly`、窄领域类型和显式 DTO adapter 表达 reference/value 意图。
+
+### React 注意事项
+- 对象身份会影响 state 更新、memoization、dependency array、selector 和 reconciliation。
+
+### Vue 注意事项
+- 代理/引用身份会影响 `reactive`、`ref`、`computed`、`watch`、Pinia 订阅和模板更新。
+
+### Frontend-Craft 前端适配
+- 前端状态身份属于可观察行为，reference/value 选择必须有意为之。
+
+### 原创前端变换示例
+- React 同时保存 `items` 和 `totalCount = items.length` 时，可直接从 items 推导；只有计算昂贵时才讨论 memoization。
+
+## RF-CHANGE-REFERENCE-TO-VALUE — 将引用对象改为值对象（Change Reference to Value）
+
+### 意图
+当共享身份没有意义时，采用不可变值语义并通过替换而非共享修改来更新。
+
+### 典型信号
+- 对象没有独立身份价值，按内容相等且不可变替换更符合模型。
+
+### 不适用条件
+- 当前结构已经清晰，或该变换会制造更强耦合、隐藏依赖、破坏公共契约且没有兼容方案时，不使用。
+
+### 前置条件
+- 已明确当前可观察行为、受影响调用者和公共契约。
+- 目标位于声明的差异预算内，并且这个单一主要变换完成后能够立即验证。
+
+### 操作步骤
+1. 确认当前行为、调用者和边界，并锁定本步骤只处理这一项主要结构意图。
+2. 创建最小的新结构/位置/接口，让旧行为可以逐步迁移而不是一次性大改。
+3. 一次迁移一个调用点或职责片段，并保持兼容边界。
+4. 运行窄范围验证；若变红，先回滚本步骤，再缩小变换。
+
+### 行为保持检查点
+- 对比输入、输出、异常、副作用、执行顺序和公共契约。
+- 前端还要核对 UI 状态、事件、焦点、网络请求、生命周期/状态迁移，以及相关对象身份语义。
+
+### 相关坏味道
+- `SMELL-MUTABLE-DATA`
+
+### 常见组合
+- 不建立固定流水线；下一步必须重新依据证据选择。
+
+### JavaScript 注意事项
+- 保持相等性、对象身份、修改时机、序列化和属性访问语义。
+
+### TypeScript 注意事项
+- 用 `readonly`、窄领域类型和显式 DTO adapter 表达 reference/value 意图。
+
+### React 注意事项
+- 对象身份会影响 state 更新、memoization、dependency array、selector 和 reconciliation。
+
+### Vue 注意事项
+- 代理/引用身份会影响 `reactive`、`ref`、`computed`、`watch`、Pinia 订阅和模板更新。
+
+### Frontend-Craft 前端适配
+- 前端状态身份属于可观察行为，reference/value 选择必须有意为之。
+
+### 原创前端变换示例
+- 把“Change Reference to Value”应用到一个局部组件/Hook/Composable/Service 范围内，先记录行为契约，只迁移一个职责片段，并立即验证输出、事件与状态变化保持不变。
+
+## RF-CHANGE-VALUE-TO-REFERENCE — 将值对象改为引用对象（Change Value to Reference）
+
+### 意图
+当多个副本代表同一实体并需要统一更新时，使用规范化的共享引用。
+
+### 典型信号
+- 多个副本代表同一实体，并且更新应该由统一身份协调。
+
+### 不适用条件
+- 当前结构已经清晰，或该变换会制造更强耦合、隐藏依赖、破坏公共契约且没有兼容方案时，不使用。
+
+### 前置条件
+- 已明确当前可观察行为、受影响调用者和公共契约。
+- 目标位于声明的差异预算内，并且这个单一主要变换完成后能够立即验证。
+
+### 操作步骤
+1. 确认当前行为、调用者和边界，并锁定本步骤只处理这一项主要结构意图。
+2. 创建最小的新结构/位置/接口，让旧行为可以逐步迁移而不是一次性大改。
+3. 一次迁移一个调用点或职责片段，并保持兼容边界。
+4. 运行窄范围验证；若变红，先回滚本步骤，再缩小变换。
+
+### 行为保持检查点
+- 对比输入、输出、异常、副作用、执行顺序和公共契约。
+- 前端还要核对 UI 状态、事件、焦点、网络请求、生命周期/状态迁移，以及相关对象身份语义。
+
+### 相关坏味道
+- 不要求先存在某一种固定坏味道；以具体结构证据为准。
+
+### 常见组合
+- 不建立固定流水线；下一步必须重新依据证据选择。
+
+### JavaScript 注意事项
+- 保持相等性、对象身份、修改时机、序列化和属性访问语义。
+
+### TypeScript 注意事项
+- 用 `readonly`、窄领域类型和显式 DTO adapter 表达 reference/value 意图。
+
+### React 注意事项
+- 对象身份会影响 state 更新、memoization、dependency array、selector 和 reconciliation。
+
+### Vue 注意事项
+- 代理/引用身份会影响 `reactive`、`ref`、`computed`、`watch`、Pinia 订阅和模板更新。
+
+### Frontend-Craft 前端适配
+- 前端状态身份属于可观察行为，reference/value 选择必须有意为之。
+
+### 原创前端变换示例
+- 把“Change Value to Reference”应用到一个局部组件/Hook/Composable/Service 范围内，先记录行为契约，只迁移一个职责片段，并立即验证输出、事件与状态变化保持不变。

package/localized/zh-CN/skills/fec-refactoring-encapsulation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: fec-refactoring-encapsulation
+description: 保持行为的前端重构主要涉及封装类重构，已经选定或正在评估对应手法，需要查询该 family 的操作步骤、风险与 JavaScript/TypeScript/React/Vue 适配时。
+---
+
+# 封装类重构
+
+## 概览
+只有在证据和前置条件支持时才使用对应手法。一次只执行一个主要结构变换，并在完成后立即验证。
+
+## 执行流程
+1. 在[封装类重构详细卡片](references/encapsulation-refactorings.md)确认手法和前置条件。
+2. 记录受影响行为与差异预算。
+3. 只执行该手法最小可行的一步。
+4. 在组合下一手法之前验证当前步骤。
+5. 公共契约、生命周期、状态身份或实际范围超出预期时停止并重新评估。
+
+## 快速索引
+详细 Reference 包含本 family 的 9 个标准手法，每项均包括意图、信号、不适用条件、操作步骤、行为保持检查、相关坏味道、组合关系、JS/TS/React/Vue 注意事项、前端适配和原创示例。
+
+## 常见错误
+- 只根据手法名称套用，不核对前置条件。
+- 一个 diff 同时混入多个结构目标。
+- 把经典 class 形式机械套进现代 React/Vue。
+- 相关行为没有覆盖时，仅凭“测试通过”就声称行为已得到证明。