state-machine

状态机

此技能会选取一个组件，在临时页面上呈现它可能处于的每种状态。每种状态都由模拟数据驱动，切换器可在状态间切换，完成后只需一步即可删除该页面。

这是一个工作台，而非评审页面。用户调整视觉效果时，页面会一直保留：屏幕上显示一种状态，按一下键即可切换到其他状态。在同一页面上堆叠各种极端场景供一次性查看属于 break；探索备选设计属于 variant；评审已完成的工作属于 interface-review。

1. 确定一个组件的范围

每次只处理一个组件：审计日志表格、网络面板、账单卡片。“设置页面”涵盖多个组件，因此请列出它们并询问要处理哪一个。

用一句话重述：该组件显示什么内容、在生产环境的什么位置呈现，以及数据来源是什么。

2. 在代码中查找状态

状态就是组件中已有的分支。阅读组件及其数据钩子，找出每种状态：

类型	状态
数据	加载中、空、错误、单项、典型数据集、足以滚动或分页的数据集、部分请求已完成而其他请求仍待处理、正在重新获取过时数据
账户	套餐等级、角色和权限检查、所有者与成员
功能	标记、试用、达到限制、已禁用或已锁定的功能

代码无法进入的状态就不算状态。不要添加分支来呈现这种状态。如果设计中展示了代码尚不支持的状态，请将其列为缺失状态并排除在外。

构建前先写下状态集，每种状态一行，并使用产品中的叫法命名，例如：empty、enterprise、member-no-access。按变化内容分组，并使用产品中的说法作为标题。使用 Data 和 Account，或更具体的分组名称，例如 Connection 或 Access。切换器会显示这些分组。用一行说明省略了哪些类型及原因。只有代码确实根据类型组合进行分支时才组合类型，例如 member-empty；不要构造笛卡尔积。

3. 构建临时页面

在应用内创建一个临时路由，承载从项目中导入且未经修改的真实组件。该路由会自动继承应用的布局、字体、全局样式和 Provider。

如果框架将服务端组件与客户端组件分开，页面必须使用客户端代码；在 Next 中就是 "use client"。否则，Fixture 数据跨越边界时可能会悄然消失，页面也会呈现为空。

只渲染一个实例，并将其放在宽度与生产环境中组件宽度一致的容器中。容器、Fixture 和切换器就是页面新增的全部内容，不要添加自己的字体、样式或主题。将页面、Fixture 和切换器放在同一个文件夹中，例如 /states/audit-log，这样只需一次删除操作即可移除它们。

4. 在数据边界提供每种状态的数据

从页面中，在组件接收数据的位置提供数据，不要编辑组件。优先顺序如下：

1. Props：组件通过 props 接收数据时使用。
2. 应用自身的数据接缝：已填充数据的查询缓存、模拟 Provider 或项目的请求模拟。

通过 props 将 Fixture 层层传递五级，会测试一条生产环境根本不会经过的路径。如果唯一可行的方式是编辑组件，请说明这一点并在添加接缝前先征求同意。

数据应贴近产品实际情况。使用真实风格的名称、时间戳、金额和用户实际拥有的项目数量。三行“Test item”会让每种状态看起来都正常。

加载中和待处理状态应保持不变。让它们持续处于待处理状态，直到切换器切换状态，而不是在超时后自动完成。

5. 添加切换器

在组件旁边放置一个分组列表，用于切换 __state 搜索参数，这样每种状态都是一个链接。如果组件旁边没有空间，就将切换器移到组件上方，改用包含相同分组的选择框。双下划线可避免与应用布局读取的参数混淆。switcher.md 中包含规范。

6. 确认每种状态都能渲染，然后交接

如果手边有浏览器，就在浏览器中打开页面，逐一切换查看所有状态。组件应显示模拟数据，而不是真实数据，也不应留下一片空白。模拟数据无法显示是这里最常见的问题。实时同步、覆盖种子数据后重新获取的缓存，或丢弃测试数据的服务端边界都会导致这种情况。交接前先修好数据链路。

如果手边没有浏览器，请说明这一点，并把 URL 交给用户检查。

然后交接 URL、状态列表和切换器按键。到此为止。调整状态的外观是用户的下一个请求，不属于这项工作。

每次更改后重新检查所有状态

进行视觉更改后，再次逐一切换查看所有状态，因为修复一种状态往往会破坏另一种状态。

用户提出要求后，一步删除

删除页面文件夹和用户批准的任何衔接层。然后在代码库中搜索路由和测试数据名称，并检查差异，确保没有改动其他设置内容。

完成前

错误	修复方法
修改组件以接受测试数据	通过 props 或应用的数据衔接层从页面传入数据；添加衔接层前先征求同意
在页面上重建了一个外观相似的组件	从项目中导入真正的组件
页面重新设置组件的样式或主题	保持应用原有的布局、字体和设计令牌
在组件树深处通过 props 传入测试数据	在组件接收数据的位置提供数据
在组件中添加分支以显示某种状态	不显示代码无法达到的状态，并列出缺少的状态
“项目 1”、“测试用户”、三行数据	使用符合产品实际情况的数据和数量
超时后结束加载状态	保持加载状态，直到切换器切换
未逐一加载每种状态就交接	加载所有状态；若出现空白或真实数据，说明数据链路有问题
使用项目的设计令牌设置切换器样式	让切换器明显处于设计系统之外
每种状态对应一个标签，排成一长行	在组件旁放置分组列表，并让列表独立滚动；列表放不下时，在其上方使用下拉选择框
未经请求就更改视觉效果	交接并等待
创建页面的同一轮就将其删除	仅在用户提出要求后删除
遗留路由或测试数据名称	删除后搜索这两者