記述ルール
文書単位
コンポーネント文書は 1 コンポーネント 1 文書を原則とします。
コンポーネントに関する以下の内容は、分割せず同一文書にまとめます。
- 表示項目
- パラメータ
- フィールド
- ボタン
- イベント
- 状態
- データ源
- 連動先
- 異常系
- 対応する backend ドメイン
- 読取 API
- 更新 API
- 実 API 置換点
ページ文書は、コンポーネントの並び順とページ全体の導線のみを保持します。
必須記述項目
各コンポーネント文書には以下の項目を含めます。
- 基本情報
- 責務
- 表示構造または表示規則
- 表示フィールド表
- frontend 入力パラメータ表
- frontend 状態 / 出力イベント表
- backend データ要求
- 想定 API 一覧
- API フィールド対応表
- 書込 / 更新 API
- 例外条件表
- 実装メモまたは移行メモ
文体ルール
各文書は表だけで構成しません。最低でも以下の説明段落を含めます。
- このコンポーネントが何を担当するか
- このコンポーネントが何を担当しないか、または読み取り専用であること
- どのページフローの中で使われるか
- ボタン押下や状態変化がどこへ連動するか
- demo 実装では未存在でも、正式版で backend / API が必要になる理由
表は項目の一覧化に使用し、役割説明、判断条件、backend 要求、API の責務は説明文でも記述します。
ID ルール
- ページ ID:
PAGE-* - 共有コンポーネント ID:
CMP-SHARED-* - 首页コンポーネント ID:
CMP-HOME-*
フィールド表記ルール
フィールドは表形式で記述します。表示項目が少ない場合でも、表の前後に「何を表示するためのフィールドか」を文章で補足します。
- 表示名
- キー
- 型
- 必須 여부
- 例
- データ元
- 空値時挙動
- 連動先
操作記述ルール
各ボタン、各押下可能領域について以下を表形式で必ず記述します。押下後に画面内だけで終わるのか、別ページや別 state に連動するのかも文章で補足します。
- 表示文言
- イベント名
- 発火条件
- 無効条件
- 押下後の処理
- 更新される状態
- 遷移先
backend / API 記述ルール
demo 実装が local state や mock で動いている場合でも、正式版で必要になる backend / API を逆算して記述します。
最低限、以下を含めます。
- このコンポーネントが参照する backend エンティティ
- 一覧取得か詳細取得か
- 書込が必要なら作成 / 更新 / 既読化 / 申込 / 決済などの API
- request path params / query params / body
- response から画面フィールドへの対応
- frontend ローカル state が backend に置き換わる箇所
現在の前提
現在の miniapp では以下の層が存在します。
mock/store/services/pages/
コンポーネント文書では、データ源の記述をこの層に必ず接続します。
ただし正式版想定では、mock/ や store/ だけで完結させず、backend / API の責務まで必ず記述します。