@bovinphang/frontend-craft 2.8.0 → 2.9.0

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

@@ -0,0 +1,83 @@
+---
+name: fec-refactoring
+description: 用于在不改变可观察行为的前提下重组既有前端代码，包括职责提炼、模块搬移、条件逻辑简化、API 整理和数据组织。不要用于新增功能、改变行为的缺陷修复、依赖或框架迁移，以及已经证实的死代码清理。
+---
+
+# 技能：保持行为的重构
+
+## 用途
+
+以小步、可验证、可回滚的方式重组仍在使用的前端代码，同时保持用户、调用方、测试、路由和集成能够观察到的行为不变。
+
+## 核心契约
+
+每次执行都遵守以下规则：
+
+1. **行为保持**：纯重构只改变内部结构，不主动改变可观察行为。
+2. **修改前基线**：编辑前先记录当前可用验证结果。
+3. **一次只做一个主要重构**：每一步只有一个主要结构意图。
+4. **每一步都验证**：完成一步后立即运行最小但有效的验证。
+5. **先回滚当前步骤，再讨论修复**：若当前步骤引入回归，先恢复到上一步，再缩小或重排方案。
+6. **重构与功能修改分离**：新增行为或改变行为的缺陷修复不属于纯重构。
+7. **优先最小安全重构**：有局部、可逆方案时，不直接扩大为架构重写。
+8. **遵守差异预算**：实际修改范围明显超出计划时必须停止并重新评估。
+
+纯重构采用 **GREEN → REFACTOR → GREEN**，不为了形式上的 TDD 人为制造失败行为测试。
+
+## 流程
+
+1. 分类请求，确认目标是结构调整且要求行为保持。
+2. 读取项目配置、受影响模块、公开导出、路由、状态边界、测试和当前 diff。
+3. 记录相关可观察契约：输入、输出、异常、副作用、UI 状态、事件、网络请求、状态迁移、路由和公开 API。
+4. 建立修改前基线；既有失败要单独记录，不能算到后续重构头上。
+5. 基于证据诊断结构问题，并检查可能的误判。
+6. 建立安全网：优先复用已有测试，风险较高且覆盖不足时再补当前行为的特征测试。
+7. 把方案拆成有顺序的小步，每步记录手法、原因、前置条件、风险、差异预算、验证和回滚边界。
+8. 每次只执行一个主要结构变换，不夹带无关清理、格式化和重新设计。
+9. 立即验证，并比较实际修改范围与差异预算。
+10. 若出现新回归，先回滚当前步骤，确认基线恢复，再缩小或调整顺序。
+11. 最后按需要运行类型检查、测试、构建、E2E、无障碍或其他专项门禁。
+12. 根据证据给出 PASS、PARTIAL 或 NOT PROVEN，不夸大验证强度。
+
+## 风险分级
+
+| 风险 | 常见范围 | 默认动作 |
+| --- | --- | --- |
+| `SAFE` | 局部私有代码、契约稳定、容易回滚 | 可执行，并逐步验证 |
+| `CAUTION` | 跨模块、共享状态、导入、Hook/Composable、生命周期 | 安全证据充分时执行，否则先规划 |
+| `DANGER` | 公开 API、路由、持久化、网络契约、认证、SSR/水合、大范围状态或继承改造 | 默认先规划并停止等待明确授权 |
+
+风险由上下文决定，不能只凭手法名称判定安全级别。
+
+## 差异预算
+
+每个可执行步骤先写清：
+
+```text
+预期文件数：N
+预期函数/组件数：N
+预期公开 API 变化：0
+预期行为变化：0
+```
+
+如果实际 diff 明显超出预算，停止并重新评估，不能静默扩大成重新设计。
+
+## 参考资料
+
+- 安全规则、证据模型和风险语言见 [principles.md](references/principles.md)。
+- 状态机、基线、回滚和报告契约见 [workflow.md](references/workflow.md)。
+- 判断何时重构或何时延后见 [when-to-refactor.md](references/when-to-refactor.md)。
+- 区分重构、功能、缺陷、清理、迁移和评审见 [refactoring-vs-feature-change.md](references/refactoring-vs-feature-change.md)。
+
+## 约束
+
+- 不修改测试来接受被重构意外改变的业务行为。
+- 未有充分证据时，不把认证、权限、路由、持久化、协议或公开包契约变化标为 `SAFE`。
+- 当前步骤出现新失败后，不继续叠加结构修改。
+- 项目没有测试框架时，不自动安装新框架。
+- 行数、复杂度、注释、一个 switch 或链式调用都不能单独证明存在坏味道。
+- 默认不执行远程 Git 写入。
+
+## 预期输出
+
+输出带证据、风险、差异预算、逐步验证和必要回滚记录的重构方案或实现，并给出 PASS、PARTIAL 或 NOT PROVEN 的行为保持结论。

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

@@ -0,0 +1,43 @@
+# 重构原则
+
+## 定义
+
+重构是在不主动改变可观察行为的前提下调整既有代码内部结构，目标是让后续修改更容易理解、定位、验证和回滚，而不是把新功能偷偷塞进结构修改。
+
+## 八条硬规则
+
+1. **行为保持**：开始重要修改前先明确相关可观察契约。
+2. **修改前基线**：把既有失败与当前步骤新引入的回归区分开。
+3. **一次一个主要重构**：每一步只承担一个结构意图。
+4. **每一步都验证**：完成一步立即运行最小有效反馈。
+5. **先回滚再修复**：当前步骤导致新回归时，先恢复，再缩小或重排。
+6. **功能修改分离**：新增结果、改变规则、改变错误行为都不属于纯重构。
+7. **最小安全重构优先**：优先局部、可逆、证据充分的变换。
+8. **遵守差异预算**：修改范围膨胀是停止信号，不是继续扩张的理由。
+
+## 可观察行为
+
+按实际范围检查：
+
+- 返回值、异常和错误映射；
+- 副作用及有业务意义的顺序；
+- 请求、载荷、重试、取消和认证行为；
+- 状态迁移、持久化、缓存身份和 memoization 依赖的对象身份；
+- DOM、加载/错误/空状态、焦点、键盘和事件；
+- props、emits、slots、Hook/Composable 契约、包导出、路由和 URL。
+
+## 证据模型
+
+优先使用调用点、依赖方向、数据所有权、变更位置、已有测试、公开契约、动态注册点、路由、i18n、Storybook、样式动态引用以及框架生命周期语义。度量值只负责提示“去哪里看”，不能单独下诊断结论。
+
+## 风险模型
+
+- **SAFE**：局部私有范围、契约稳定、容易回滚并有对应验证。
+- **CAUTION**：跨文件/组件、共享辅助模块、状态所有权、生命周期或动态引用，或者行为覆盖不完整。
+- **DANGER**：公开 API、路由、存储结构、后端契约、认证权限、SSR/水合、关键计算、大范围继承或状态架构替换。
+
+同一手法在不同上下文风险可能完全不同，例如局部变量改名可以很安全，而序列化字段改名可能影响外部契约。
+
+## 风险修改前的特征测试
+
+重要行为覆盖不足时，可以先补描述当前实际行为的特征测试。它第一次运行可以直接为绿，因为目的只是锁定既有行为，不是创造新需求。

package/localized/zh-CN/skills/fec-refactoring/references/refactoring-vs-feature-change.md

@@ -0,0 +1,25 @@
+# 重构与相邻工作的边界
+
+## 纯重构
+
+目标是改善职责、命名、封装、位置、条件逻辑、API 形状或数据组织，并明确要求不改变调用方/用户可观察行为时，属于纯重构。验证模型是 **GREEN → REFACTOR → GREEN**。
+
+## 功能或改变行为的缺陷修复
+
+新增能力、改变业务规则、改变接受输入、改变可见输出、改变错误结果或主动改变副作用，都不是纯重构。应先用失败行为测试表达新期望，再实现。
+
+## 调试
+
+故障原因未知时，应先找到根因。后续修复可能包含重构，但不能用“重构一下”代替故障证据。
+
+## 死代码清理
+
+已证实未使用的代码、导出、依赖、路由等需要专门检查动态 import、配置、模板、Storybook、CSS、i18n 和生成内容，不能与活代码的大范围结构改写混做。
+
+## 迁移
+
+框架、依赖、路由、构建系统、状态库或整体架构迁移会主动跨越兼容边界，即使设计因此更好，也应按迁移规划处理。
+
+## 普通评审
+
+合并前评审可以指出结构问题，但默认先输出报告；若要诊断或执行重构，应作为明确的后续动作，而不是评审过程中静默改写源码。

package/localized/zh-CN/skills/fec-refactoring/references/when-to-refactor.md

@@ -0,0 +1,17 @@
+# 何时进行重构
+
+## 现在就重构
+
+当结构问题直接增加当前工作的修改成本或风险，并且能够保持行为稳定时值得立即处理，例如职责纠缠让一个小改动波及多处、同一概念重复编辑且已开始漂移、状态/数据所有权混乱、测试难以隔离目标行为等。
+
+## 记录后延后
+
+坏味道真实存在但与当前目标无关、安全网不足以支撑高风险变换、兼容工作量明显超过即时收益时，记录证据和候选顺序，不进行顺手的大范围重新设计。
+
+## 停止重构
+
+出现以下情况应停止：结构目标已经达成；下一步会改变可观察行为；下一步跨越公开契约但没有兼容方案；差异预算持续扩大；验证无法区分基线与新回归；剩余动机只来自个人审美而非修改成本或正确性风险。
+
+## 实用判断
+
+好的重构应让下一个真实需求更容易理解、局部化、验证或回滚。如果没有改善这些属性，应要求更强证据再继续。

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

@@ -0,0 +1,59 @@
+# 重构执行工作流
+
+## 状态机
+
+```text
+分类请求
+→ 发现上下文
+→ 建立基线
+→ 诊断结构证据
+→ 建立安全网
+→ 构建有序计划
+→ 风险检查
+→ 执行一个重构步骤
+→ 立即验证
+   通过：检查 diff 后进入下一步
+   失败：回滚当前步骤，确认基线，再缩小或重排
+→ 最终验证
+→ 报告
+```
+
+## 上下文发现
+
+按需读取 `package.json`、工作区清单、TypeScript/ESLint 配置、测试脚本、受影响模块和调用点、barrel 导出、路由和注册点、store/持久化边界、生命周期敏感逻辑、异步副作用以及当前 Git diff。
+
+## 基线处理
+
+基线为绿时，当前步骤之后新出现的相关失败应优先视为该步骤可能引入的回归。基线已经为红时，要记录精确失败，不能没有比较证据就把后续失败归因于重构；安全证明不足时不要继续高风险变换。
+
+## 单步计划契约
+
+```text
+目标：
+手法：
+意图：
+前置条件：
+风险：SAFE | CAUTION | DANGER
+预期文件数：
+预期函数/组件数：
+预期公开 API 变化：0
+预期行为变化：0
+验证：
+回滚边界：
+```
+
+## 单步失败协议
+
+修改前为绿、当前步骤后变红时：停止；只回滚当前步骤；重跑相关检查确认基线恢复；判断失败源于行为、身份、生命周期、顺序、类型还是依赖假设；缩小步骤或增加前置重构；证据恢复后才能重试。
+
+不要为了“修绿”把改动扩散到不相关模块。
+
+## 最终验证
+
+按由窄到宽的顺序运行：最近的语法/类型检查、目标单元或组件测试、受影响集成测试、lint + 全量 typecheck、更广测试、构建，以及实际受影响时的 SSR、E2E、视觉、无障碍、性能等门禁。
+
+## 证明结论
+
+- **PASS**：相关可观察契约覆盖充分，要求的检查全部通过。
+- **PARTIAL**：已执行检查通过，但重要行为覆盖仍不完整。
+- **NOT PROVEN**：依赖、环境、基线或安全网不足，无法可信证明行为保持。

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

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