フォーム：ユーザー行動仕様
サーバーをフォームの有効性の権威とし、クライアントは速度のために検証を行い、エラーコードを共有し、最初の無効なフィールドにフォーカスを当て、プライベートレコードの存在を漏らさないようにします。
パッケージの状態: 参照コンテキストは人間によるレビュー準備完了。契約とテストシナリオは完成していますが、採用実装がこれらを通過したという主張はありません。
決定事項
ネットワーク送信前に必須フィールドの空欄や形式ミスを検出するためにクライアントで検証を行います。これらのチェックは暫定的なものとして扱います。サーバーは同じルールに加え認可と一意性を再検証し、そのエラーコードが権威的です。これらを同じフィールドにマッピングします。最初の無効なコントロールにフォーカスを当て、概要をアナウンスします。プライベートレコードが存在するかどうかを示すルックアップでは、欠如と禁止を区別しない一般的な競合エラーを返します。
範囲
- クライアントとサーバーの検証が重複するデータ入力フォーム。
- エラーコード、フォーカス順序、支援的なアナウンス。
- プライベートまたはテナント間の存在を開示してはならないレスポンス。
- 関連しない値を失わずに修正後に再試行。
この範囲外
- フィールドエラーを超えた非同期リストフィードバック。
- CAPTCHAおよびレート制限。
- 保存ドキュメントのスキーマ移行。
契約
- クライアントルールに失敗した送信はリクエストを送らず、最初の無効なコントロールにフォーカスが当たり、そのアクセシブル名とエラー文が表示される。
- サーバーはクライアントと重複するルールの同じコードを使い、
field_errorsを{code, field}のペアで返す。 - クライアントで有効なペイロードでも失敗することがあり、UIはクライアントメッセージをサーバーのリストに置き換え、別の語彙を作らない。
- 送信失敗後、フォーカスは文書順で最初のサーバー無効フィールドに移動し、丁寧なライブリージョンがエラー数を一度だけアナウンスする。
- 存在に敏感なルックアップは、欠如と認可なしの両方に対して
not_availableのような一般的なコードを返す。 - 関連しない変更済みフィールドは値を保持し、パスワードや秘密はHTMLやJSONにエコーされない。
実装
形式と必須チェックのための機械可読なルールリストを共有します。一意性と認可はサーバー側で保持します。エラーはラベル付きコントロールの隣に表示します。存在に敏感な否定は認可スコープ内に折りたたみます。キーボードのみとスクリーンリーダーで最初のエラー時のフォーカスをテストします。
障害処理
サーバーに接続できない場合は値を保持し、フィールドエラーとは異なるリクエストレベルのエラーを表示し、送信は有効のままにします。不明なコードはフィールド関連を保持しつつ一般的なフィールドメッセージを表示します。2つのフィールドが同じコードを共有している場合は両方に表示され、フォーカスは文書順で最初のものに移動します。
検証
重複コードの契約テスト。プライベートスラッグの衝突が予約済みと区別できないことの確認。フォーカスと単一のアナウンスの確認。フォームハーネスでパッケージ化されたシナリオを実行。
このパッケージの実行可能に見える例はフィクスチャおよび受け入れ契約です。コレクションのルートから
python tools/validate.py
を実行してパッケージ構造とメタデータをチェックし、その後ターゲットリポジトリでシナリオを実装・実行してください。
採用にあたっての前提
example.yamlの名前や数値は採用プロファイルであり、普遍的なデフォルトではありません。- 採用チームはアクター、データクラス、エラー語彙、所有権を自システムにマッピングする必要があります。