Vibe Coding 表单状态合同：验证、提交与异步结果不互相覆盖

让 Agent 生成一个“带校验的提交表单”，默认产物通常只有必填判断、isLoading 布尔值和成功 toast。真实流程还会遇到字段依赖、服务端规则变化、连续两次提交、请求超时但服务已写入、用户修改输入后旧响应迟到，以及错误提示无法被读屏感知。若没有状态合同，修一个分支常会破坏另一个分支。

React 表单最佳实践介绍常用实现方式；本文不绑定表单库，而是定义任何框架都必须保持的验证与异步语义。

先让 HTML 承担原生合同

每个字段使用正确的 label、name、输入类型和 autocomplete token，相关帮助与错误通过可访问关系连接。按钮使用真实 button，提交动作放在 form 语义内，使键盘 Enter 和渐进增强有明确行为。HTML 表单规范与约束验证 API 能提供 required、pattern、范围等基础能力，不需要用点击处理器重新模拟。

原生验证适合即时、确定且不涉及秘密的规则，例如格式和长度。客户端 schema 可以改善反馈，但不是授权边界；服务端必须重新解析与验证全部输入，检查当前身份、资源权限、唯一性和并发版本。不要共享一段只能在浏览器运行的验证代码后宣称前后端同源，真正共享的是版本化规则和测试样例。

错误分三类：字段错误关联具体输入；表单错误说明跨字段或业务规则；系统错误说明暂时无法完成。WCAG Error Identification 要求识别错误项并用文本描述，不能只把边框染红。错误建议仅在安全且已知时给出；登录失败不应泄露账号是否存在。

用状态机替代多个互相矛盾的布尔值

至少区分 editing、client-invalid、submitting、field-error、form-error、success 和 unknown-outcome。应用可以增加自动保存或多步骤状态，但每个状态只允许明确事件转换。isLoading && isSuccess 这类非法组合应在类型或 reducer 层不可表达。

提交时创建 request ID，冻结本次规范化输入摘要。响应返回后只更新仍匹配当前活动请求的状态；如果用户已修改字段或发起新请求，旧响应进入诊断而不覆盖新输入。取消浏览器请求可以停止等待，却不能证明服务端没有执行，因此写操作不能把 AbortError 一律显示成“未提交”。

服务支持幂等键时，重试沿用同一业务操作键，并由服务端保证等价结果；新建另一笔操作才生成新键。服务不支持时，对未知结果提供查询状态或人工恢复路径，不能自动重发可能扣款、发信或创建记录的请求。接口语义应经过Agent API 契约兼容门，确保错误码与字段路径没有在前后端共同漂移。

异步验证必须处理竞争

用户名可用性、优惠码或远程地址校验会在输入期间触发请求。只对格式已通过且稳定一段时间的值发起验证，缓存键包含规则版本和相关字段。新值出现时取消旧读取并增加 generation；只有 generation 与当前值都匹配的结果才能落地。防抖减少请求，不提供正确性，迟到结果围栏仍然必需。

远程验证结果只能作为提示或提交前证据，服务端提交仍再次判断，因为可用性会在两次请求之间变化。失败时不要把“无法验证”映射为“可用”，根据业务风险阻止提交或允许服务端最终裁决。依赖多个字段的规则在任何相关字段变化时作废旧结果。

状态消息使用适合的 live region 或语义，让读屏在不移动焦点时知道提交结果；频繁输入提示不要每个字符都播报。提交失败后焦点移动策略按任务决定：通常聚焦错误摘要或首个无效字段，同时保留用户输入。打开 modal 错误会引入额外焦点管理，除非错误确需阻断，不应作为默认模式。React 组件可访问性提供焦点和控件语义基线。

浏览器导航与恢复也属于状态合同。用户提交后返回上一页、刷新、在两个标签页编辑同一记录，或由密码管理器和 autofill 修改字段时，界面不能依赖只触发过某个 React handler 的假设。草稿若需要持久化，要明确存储范围、过期时间、敏感字段排除和 schema 版本；恢复旧草稿时重新验证，不能把历史“valid”标记一并恢复。多标签页冲突通过服务端版本或明确的最后写入策略处理，不在客户端静默覆盖。

成功后的导航只在服务确认业务结果后发生。若响应丢失而结果未知，保留操作标识并提供状态查询；不要先乐观跳转再把失败藏在下个页面的 toast。对可撤销、低风险操作可以采用乐观更新，但必须有回滚视图、迟到响应围栏和服务端最终裁决。

用对抗样例验证，而非只测成功路径

测试表覆盖空值、空白、Unicode、最大长度、条件字段、服务端新增错误、离线、慢响应、两次快速提交、旧响应迟到、刷新恢复、权限撤销和未知结果。使用AI 生成代码的属性测试生成边界数据，但业务不变量由人定义，例如无效请求不产生副作用、同一幂等键最多对应一个业务结果、旧 generation 不覆盖新输入。

组件测试验证 label、错误关联、状态转换和按钮行为；契约测试验证请求序列化与错误映射；端到端测试用隔离 sink 验证一次真实副作用。不要通过 mock 同一 reducer 的返回值证明 reducer 正确，也不要为通过测试删除服务端未知错误分支。

发布证据列出 schema 版本、状态图、请求策略、服务端错误样例、键盘与读屏检查、故障用例和当前提交，并经过编程 Agent 的改动验证门。

表单真正的完成标准，是用户在成功、输入错误、暂时失败和结果未知时都知道发生了什么、下一步能做什么，系统也不会因重复或迟到消息制造第二次副作用。把这些写成状态合同后，Vibe Coding 才能加速实现而不省略关键分支。