Yoko Shiina

画面仕様設計書のサンプル:架空の店舗の「1日分のシフトをアップロードする画面」

このページでは、架空の店舗のシフト管理を題材に、画面仕様設計書のサンプルを紹介しています。元になった実案件についてはケーススタディをご覧ください。

保存済み.

現在の画面状態

右側の画面を操作すると更新されます

状態

保存済みSAVED

保存済みの勤務表を確認できます。有効なアップロードで、選択日の勤務表全体を置き換えます。

状態図の現在位置

通常処理中処理が中断された状態CSVアップロード200200+警告ファイル・日付の確認422タイムアウト409予定なし / EMPTY予定なしEMPTY保存済み / SAVED保存済みSAVED公開済み / PUBLISHED公開済みPUBLISHED閲覧のみ / READ_ONLY閲覧のみREAD_ONLY検証・更新中 / VALIDATING検証・更新中VALIDATINGアップロードを中止 / REJECTED_BLOCKINGアップロードを中止REJECTED_BLOCKING修正が必要 / REJECTED_ERRORS修正が必要REJECTED_ERRORS警告付きで更新済み / APPLIED_WITH_WARNINGS警告付きで更新済みAPPLIED_WITH_WARNINGS更新結果が不明 / REQUEST_FAILED更新結果が不明REQUEST_FAILED更新の競合 / STALE_DATA更新の競合STALE_DATA

印のある状態は、この操作例で到達できます。この例では検証と反映をまとめて示し、独立した実装では分けています。HTTPの表記はAPI案に対応するもので、このページが送信する通信ではありません。

この操作に関係する仕様

この操作で表示する検証項目はありません。右側でCSVの操作例を選ぶと、該当するルールがここに表示されます。

画面仕様設計書の全体は、この下に続きます。

CSVの操作例を選ぶと、結果とその判断理由を確認できます。用意されたデータを、この仕様のルールで検証します。

シフト/日別シフト

2026-10-15

SAVED

スタッフ9-1010-1111-1212-1313-1414-1515-1616-17
st_001 Anna勤務勤務勤務勤務非勤務非勤務非勤務非勤務
st_002 Ben非勤務勤務勤務勤務勤務非勤務非勤務非勤務
st_003 Clara非勤務非勤務非勤務非勤務勤務勤務勤務勤務
st_004 David非勤務非勤務非勤務非勤務非勤務非勤務非勤務非勤務
st_005 Elena勤務勤務勤務非勤務非勤務非勤務非勤務非勤務
st_006 Felix非勤務非勤務非勤務勤務勤務勤務勤務勤務
st_007 Grace非勤務非勤務勤務勤務勤務勤務非勤務非勤務
st_008 Hugo非勤務非勤務非勤務非勤務非勤務勤務勤務勤務

スタッフ8人×8枠(各1時間、09:00–17:00)。有効なアップロードで1日分を置き換えます。ファイルが拒否された場合、保存済みの勤務表は変わりません。

この画面仕様設計書には、2種類の注記があります。

システムの視点:データと実装上の制約から、なぜこの形にしているか。

ユーザーの視点
ユーザーの視点:どこでつまずきやすく、画面でどう対処するべきか。

この画面の目的

店舗の1日分のシフトを、CSVファイルから登録・更新する画面。

有効なアップロードで、その日全体のデータを置き換えます。非勤務の人も含め、現在のスタッフ全員の行が必要。行の欠落や無効な値があれば更新せず、保存済みの勤務表を維持します。

編集はExcelなど、この画面の外で行います。この画面が担うのは検証と反映。

もう一つ、設計の軸にしたことがあります。エラーを見ても、何を直せばよいかわからない状態にしません。自分で直せるエラーなら、どこをどう直すかを示します。自分では直せないなら、助けを求めるのに必要な情報を渡します。どちらもなければ、ユーザーは再試行しなくなります。

最初に「1日分を丸ごと置き換える」と明示しています。この仕様の判断のほとんどは、そこから来ています。これがなければ、検証項目が多すぎるように見えます。

ユーザーの視点
「エラーが発生しました。担当者にお問い合わせください」としか出ない画面では、ユーザーは先に進めません。毎回問い合わせるのが負担になれば、以前のやり方に戻ってしまいます。苦情が出るとは限りません。ただ、機能が使われなくなります。ここの検証は、それを防ぐためにあります。

画面の構成

表はスタッフ8人と、09:00〜17:00の1時間枠×8で構成します。各セルは勤務・非勤務を表します。

検証結果は表の上に置きます。CSVの修正は画面外で行うため、横に長い表の下にエラーを置くと、見つけづらくなります。

スタッフを行、コマを列にしました。8人から50人に増えても行が増えるだけで、構造は変わりません。逆にすると、スタッフが増えるたびに表が横に広がります。

削除と公開はダウンロード・アップロードとは離して配置します。ただし、アップロードも無害ではありません。1日分のデータを置き換える操作だからです。操作ごとに影響が異なるため、それぞれに必要な防止策を仕様で決めています。

ユーザーフロー

主な操作は9ステップ。そのうち1つはこの画面の外で行います。各ステップについて、つまずきやすい点と、その対処を対にして示します。

月表示で対象日を確認

つまずくところ
月全体が見えないと、どの日に予定が入っているかわかりにくい。
どう対処するか
月表示には、日付ごとのシフトの有無だけを表示する。詳細は日表示で見る。(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)

日表示を開く

つまずくところ
どの日を編集しているのか見失いやすい。
どう対処するか
選択した日付を画面上部に大きく表示し、その後の操作をすべてその日付に紐づける。

保存済みの勤務表をCSVでダウンロード

つまずくところ
どんなファイルを準備すればいいかわからない。
どう対処するか
CSVには選択日・現在の全スタッフ・8時間枠の保存済みの値を含める。CSVの説明で入力値と勤務ルールを確認できる。

Excelなどで編集画面外の操作

つまずくところ
保存するとファイル形式が変わることがある。不要に見える行を削除してしまうこともある。
どう対処するか
全スタッフの行と8つの時間フィールドを残す。行番号・スタッフ・時間帯で示された箇所を修正する。

CSVをアップロード

つまずくところ
どの画面からアップロードできるのか、なぜボタンを押せないのかわからない。
どう対処するか
アップロードできるのは日表示だけ。月表示にはボタンを置かない。権限がなければ無効にして理由も表示する。

ファイルを検証

つまずくところ
エラーが出ても、自分で直せる問題なのか判断できない。
どう対処するか
修正できるエラーは、行番号、スタッフ、時間帯、入力値など、問題に応じて対象を特定し、原因を伝える。ユーザーが対処できないサーバー障害には、問い合わせ時に伝えられるコードを付ける。

反映する

つまずくところ
データが反映されたのかどうかわからない。
どう対処するか
拒否時は保存済みの表と更新日時を維持する。成功時は1日分を置き換え、人数の警告があるか示す。

内容を確認

つまずくところ
数値としては有効でも、実際の勤務には適さないシフトかもしれない。
どう対処するか
保存後に、0人・1人の時間帯を警告する。完了した更新を取り消したり、保存を止めたりしない。

公開する

つまずくところ
公開ボタンを押すとスタッフに通知されることを知らない。
どう対処するか
データの反映と公開を分ける。公開前に、何が起きるかを確認画面で知らせる。(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)

ユーザーの視点
昨日のファイルを間違えて選ぶことはあります。アップロードは1日分を丸ごと置き換えるので、そのまま通すと成功したように見え、誰かがシフトを確認するまで間違いが表面化しません。日付の照合はデータを守り、本人がその場で間違いに気づく機会にもなります。

編集はExcelで行います。画面内での編集はこの仕様の対象外。これまでの作業がExcel中心なら、使い慣れた道具を残す方が移行の負担を抑えられます。

ダウンロードとアップロードの間、ユーザーはいったん画面を離れます。その間に別の人が同じ日を編集するかもしれません。画面外での作業があるからこそ、更新の競合を検出する必要があります。

操作できる場所と、できない理由

エラーは操作の後に起こります。でも、その前に「そもそも操作できるか」を伝える設計があります。ここでは、操作できる・今はできない・操作自体を置かない、という3つを使い分けます。

状況表示方法理由
月表示からアップロードしようとするボタンを置かない対象日が決まらなければ操作できない。押せないボタンを置くより、最初から置かない方が混乱が少ない。(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)
編集権限がない無効にして理由を示すボタンを消すと、その機能自体が存在しないように見える。ボタンは残し、使えない理由を添える。(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)
その日のシフトがまだない削除ボタンを無効にする削除するものがない。この操作例ではCSVの選択と再読み込みは引き続きできる。
検証中すべての操作を無効にする二重送信を防ぐ。操作できない状態自体も、処理中であることを示す。
公開済みのシフトを編集する操作できるが、反映前に確認する変更はできる。ただしスタッフに通知が届くので、実行する前に何が起こるかを示す。(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)
CSVの準備方法がわからない検証・反映中を除き利用できる例を選ぶ前に形式を確認できる。処理中は他のCSV操作と同じ条件で利用を止める。

非表示と無効には使い分けのルールがあります。その場面に存在しない操作は置きません。操作は存在するが今は使えない場合、理由を添えて残します。理由のない無効ボタンは、壊れたボタンと区別がつきません。

CSV形式の説明

説明では列と入力ルールを確認できます。検証・反映中は開けません。

  • date、staff_id、8つの時間列。各列が1つずつ必要
  • TRUEは勤務、FALSEと空欄は非勤務。各スタッフは非勤務、または連続3時間以上の1区間で勤務する
  • 全行の日付を、選択中の日付と一致させる
  • 入力済みのサンプル行
  • UTF-8の.csvファイル、上限1 MiB。現在の全スタッフの行を残し、空欄でも8つの時間フィールドを省略しない

ダウンロードするCSVには選択日・現在の全スタッフ・保存済みの勤務値を含めます。この構造を保つことで、行の欠落や日付の誤りを減らします。

ユーザーの視点
押せないボタンに理由がなければ、自分の操作が間違っているのか、権限がないのか、故障なのか判断できません。わからなければ誰かに聞くことになります。問い合わせが負担になると、画面自体が使われなくなります。

画面の状態

状態図は、操作と画面の状態のつながりを示します。この操作例で体験できる状態に加え、公開や権限などの広い設計上の状態も含みます。

状態図はページ上部にあります。右側の画面を操作すると、現在の状態が図の中にも示されます。

この操作例では、CSVを選ぶと検証を開始してから結果を表示します。ファイル・構造・日付の問題は、保存済みの勤務表を置き換える前に処理を止めます。

ファイルや内容のエラーは、修正して選び直します。競合や更新結果不明では、再アップロード前に保存済みの勤務表を読み直します。警告はすでに保存された結果。

独立した実装では、再読み込み中・読み込み失敗・再読み込み成功も区別します。読み込み失敗は、保存済みの勤務表が存在しないことを意味しません。

独立した実装では、更新成功は独立したpolite live regionで通知し、フォーカスを移しません。エラーと復旧結果では見出しへフォーカスを移します。短時間で終わった進行状態が読み上げ待ちに残らないよう、進行通知を遅延します。

ユーザーの視点
選んだ瞬間に出るエラーと、待たされた後に返ってくるエラーでは、受け止め方が違います。最初に検出できた問題を待たせてから伝えると、やり直す気力を削ぎます。フロントエンドで確認できることは、送信前に返します。

10の状態と識別子

通常

  • 1予定なしEMPTYこのデモで動作
  • 2保存済みSAVEDこのデモで動作
  • 3公開済みPUBLISHED
  • 10閲覧のみREAD_ONLY
  • 7警告付きで更新済みAPPLIED_WITH_WARNINGSこのデモで動作

処理中

  • 4検証・更新中VALIDATINGこのデモで動作

処理が中断された状態

  • 5アップロードを中止REJECTED_BLOCKINGこのデモで動作
  • 6修正が必要REJECTED_ERRORSこのデモで動作
  • 8更新結果が不明REQUEST_FAILED
  • 9更新の競合STALE_DATA

エッジケース

対処は3種類。処理を止める、修正を求める、確認だけを促す。右側でCSVの操作例を選ぶと、該当する項目が左上の「この操作に関係する仕様」に表示されます。

各項目の右側には、そのエラーコードをどちらの側で定義するかを示します。フロントエンドで完結する検証はフロントエンドで、サーバー側の検証はバックエンドが返すコードに従います。どちらの場合も画面に出す文言はフロントエンドで定義します。

「ユーザーの視点」には、なぜそのエラーが起こり、なぜこの返し方にするのかを記しています。すべての項目に付くわけではありません。システム上の制約だけで決まる項目には付けていません。

処理を止めるエラー13件

最初の該当項目で検証を止め、その先のエラーは収集しない。この問題を直すまでファイル全体を使えないため、後続の検証は行わない。赤の塗りつぶしで示す。

全13項目の詳細
B1

CSV形式のファイルではない

フロントエンドで定義
表示内容
拡張子が.csvのCSVファイルを選択してください。
挙動
ファイル選択時に確認。読み込みは開始しない。
理由
読み込んだ後に失敗させず、ファイルを選んだ時点で伝える。
B2

ファイルが1 MiBを超えている

フロントエンドで定義
表示内容
このファイルは1 MiBを超えています。より小さい日別シフトのCSVを選択してください。
挙動
デコード前に止める。
理由
8人分の行を扱うため、極端に大きなファイルは誤選択の可能性が高い。
B3

ファイルが空

フロントエンドで定義
表示内容
ファイルに勤務表のデータがありません。現在のCSVをダウンロードして、もう一度お試しください。
挙動
解析結果が0行なら中止
理由
空ファイルを受け付けると、その日全体のシフトが削除されてしまう。アップロードが1日分のデータを丸ごと置き換えるため、特に危険な入力。
ユーザーの視点
本人は空ファイルを選んだことに気づいていないかもしれない。そのまま通ると1日分が消え、消えたことにさえ気づけない。
B4

必須列の欠落・重複、または余分な列がある

フロントエンドで定義
表示内容
必須の列がありません。現在のCSVをもう一度ダウンロードして、お試しください。
挙動
スタッフの内容より先にヘッダーを確認する。
理由
各値がどの時間帯を示すか確定しないと、内容を検証できない。
B5

UTF-8形式ではない

フロントエンドで定義
表示内容
このファイルをUTF-8として読み取れませんでした。UTF-8のCSVとして書き出して、もう一度お試しください。
挙動
デコードできなければ中止
理由
Excelは地域設定によって異なる文字コードでCSVを保存することがある。MüllerやŁukaszのような名前は文字化けする。
ユーザーの視点
Excelから保存したファイルで起こりやすい。入力内容は正しいので、「値を修正してください」では何を直せばよいかわからない。ファイル形式の問題だと伝える。
B6

ファイルの日付と画面で選んだ日付が一致しない

共同で定義
表示内容
ファイルの日付が選択中の日付と一致しません。
挙動
全行の日付を照合し、不一致なら中止
理由
アップロードは1日分を丸ごと置き換える。日付違いを許すと別の日のシフトを上書きし、元に戻せなくなる。
ユーザーの視点
昨日のファイルを間違えて選ぶことはある。そのまま通ると、本人は成功したと思い、別の人が予定を見るまで誤りに気づかない。ここで止めれば、その場で気づける。
B7

ファイルに複数の日付が混在している

共同で定義
表示内容
1つのファイルに指定できるのは1日分だけです
挙動
日付が1種類か確認して中止(現行実装では、選択日と一致しない最初の行をDATE_MISMATCHとして返す。複数日専用コードは返さない)
理由
複数日を一度に置き換えると、何がどこまで変わったのかをユーザーが把握しにくい。
B8

対象範囲外の日付(過去)

共同で定義
表示内容
過去のシフトは変更できません
挙動
中止(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
すでに働いた時間を書き換えることになる。
ユーザーの視点
過去の日付を開いて編集してしまうことはある。勤務済みの時間が書き換わっても、給与計算のときまで気づかないかもしれない。
B9

対象範囲外の日付(3か月より先)

共同で定義
表示内容
3か月より先のシフトは登録できません
挙動
中止(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
範囲の制限がなければ、年を間違えても検出できない。
B10

想定より大幅に行数が多い

フロントエンドで定義
表示内容
ファイルの行数が多すぎます
挙動
解析時に行数で判定して中止(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
通常は192行。桁違いに多ければ、別のファイルを選んだ可能性が高い。
ユーザーの視点
行数が桁違いなら、個々の値ではなくファイルの選択を疑うべき。エラーを1件ずつ並べても役に立たない。
B11

区切り文字がセミコロン、または小数点がカンマになっている

フロントエンドで定義
表示内容
列の区切りにセミコロンが使われています。「CSV UTF-8(コンマ区切り)」で保存し直してアップロードしてください
挙動
ヘッダー行から検出して中止(現行実装では必須列を認識できないためHEADER_INVALIDとして返す。区切り専用エラーは追加の設計案)
理由
地域設定によって、Excelがこの形式でCSVを保存することがある。入力した値自体は正しいので、値の誤りとして扱わない。
ユーザーの視点
小数点にカンマを使う地域ではよく起こる。内容を間違えたわけではないので、入力値ではなく保存方法を案内する。
B12

ファイルを読み取れない

フロントエンドで定義
表示内容
ファイルを読み取れませんでした。もう一度選択してください。
挙動
デコード前に止める。
理由
ファイルの内容を一切確認できないため、選び直してもらう。
B13

CSVの構造が壊れている(引用符・フィールド数)

フロントエンドで定義
表示内容
どの行も、空欄を含めて8つの時間フィールドを残してください。
挙動
最初に壊れている行で止め、行番号を示す。
理由
欠けたフィールドは空欄とは違う。空欄として読むと、黙って非勤務にしてしまう。

修正が必要なエラー(まとめて表示)15件

全行を検証し、問題をまとめて表示する。修正して再アップロードできる。処理を止めるエラーと同じ赤を使うが、重要度の違いを示すため塗りつぶさず枠線で表す。

全15項目の詳細
A1

IDが現在のスタッフ一覧にない

バックエンドで定義
表示内容
このIDは現在のスタッフ一覧にありません。現在のCSVをダウンロードして、スタッフIDを確認してください。
挙動
行番号と入力されたIDを示す。
理由
現在の一覧だけでは、未知のIDか退職者のIDか断定できない。原因を推測しない。
ユーザーの視点
行番号と入力されたIDを示すことで、CSV内の問題箇所を探せる。
A2

staff_idが退職済みのスタッフを指している

バックエンドで定義
表示内容
7行目:スタッフID「st_007」は現在無効です
挙動
A1と同じ。現行実装では現在の一覧外のIDをSTAFF_NOT_ACTIVEとし、不明なIDと退職者を区別しない。
理由
A1とは原因が異なり、古いテンプレートを使っている可能性を示す。
ユーザーの視点
存在しないIDとは別の問題。古いテンプレートの再利用が原因とわかれば、次から新しいものをダウンロードできる。
A3

slot_noが1〜24の範囲外

バックエンドで定義
表示内容
12行目:コマ番号は1〜24で指定してください
挙動
同上(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
番号が0から始まるのか1から始まるのか、迷わないよう範囲を示す。
A4

現在のスタッフの行がない

バックエンドで定義
表示内容
ファイルに行がありません。非勤務の人も含め、現在のスタッフ全員の行が必要です。
挙動
スタッフ名とIDを示し、1日分の置換を行わない。
理由
行の欠落によって、スタッフが黙って勤務表から除かれないようにする。
ユーザーの視点
不要に見えた行を削除している可能性がある。非勤務の人にも行が必要だと伝える。
A5

スタッフIDが複数行にある

バックエンドで定義
表示内容
スタッフID「st_002」が複数の行にあります。スタッフ1人につき1行にしてください。
挙動
同じIDの行番号をまとめて1件で示す。
理由
一方の行を勝手に採用すると、入力の矛盾が隠れる。
ユーザーの視点
重複した片方の行だけでは判断できない。すべての行番号を見せ、どれを残すかはユーザーが決める。
A6

hoursが数値ではない

バックエンドで定義
表示内容
9行目:hoursには数値を入力してください
挙動
同上(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
入力された値をそのまま表示する。本人が何を入力したか覚えていない場合もある。
A7

hoursが0〜0.5の範囲外

バックエンドで定義
表示内容
14行目:hoursは0〜0.5の範囲で指定してください
挙動
同上(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
1コマは30分なので、上限は0.5。単位の取り違えで1.0と入力することは十分考えられる。
ユーザーの視点
30分のコマに1.0と入力するのは、単位の取り違え。入力値を表示すれば、何を入力したか自分で確認できる。
A8

hoursが小数第3位以下を含む

バックエンドで定義
表示内容
21行目:hoursは小数第2位までで指定してください
挙動
同上(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
表示値と保存値を揃えるため。丸めると記録に食い違いが生じる。
A9

1日の合計が会社の上限を超える

バックエンドで定義
表示内容
スタッフ「st_005」の合計が1日の上限を超えています(8.5/上限8)
挙動
スタッフごとに合計(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
行単位ではわからず、合計して初めて見つかる問題。
ユーザーの視点
1コマずつ入力していると、合計時間までは意識しにくい。各行は有効でも合計では問題になるので、そこを明示する。
A10

休憩なしの連続勤務が6時間を超える

バックエンドで定義
表示内容
スタッフ「st_002」:休憩なしで6時間を超えて勤務しています
挙動
スタッフごとに、連続して勤務が入っているコマのhoursを合計し、会社の基準値と比較する(このサンプルでは6時間)。空欄・0時間のコマで連続勤務を区切る。(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
CSVからはコマ内の休憩時刻を特定できない。架空の業務ルールとして空欄・0時間のコマを休憩とみなし、入力された勤務時間を合計する。休憩をどこに入れるかはユーザーが決める。
ユーザーの視点
休憩の入れ方は店舗の事情による。システムが勝手に決めれば、実態に合わない可能性がある。違反する区間を示し、調整はユーザーに任せる。
A11

営業時間外に勤務時間を入力

バックエンドで定義
表示内容
11行目:コマ24は営業時間外です
挙動
同上(追加要件、または以前の数値勤務時間モデルのルール。このページで扱うTRUE/FALSE形式のCSVには適用しない)
理由
営業時間が変わると有効なコマも変わる。更新されていないテンプレートを検出できる。
A14

スタッフIDが空欄

バックエンドで定義
表示内容
スタッフIDが必要です。
挙動
IDが必要な行を示す。
理由
IDがなければ、誰の勤務か確定できない。
A15

時間セルに無効な値がある

バックエンドで定義
表示内容
無効な値です。TRUE、FALSE、または空欄にしてください。
挙動
行・時間帯・入力値を示す。
理由
入力値を残せば誤りを探せる。FALSEへ勝手に変換すると誤りが隠れる。
A16

勤務区間が3時間未満

共同で定義
表示内容
勤務が3時間未満です。この店舗では、勤務する日は連続3時間以上が必要です。
挙動
スタッフと勤務区間を示す。
理由
この店舗では、勤務する日は連続3時間以上を必要とする。
A17

勤務が複数の区間に分かれている

共同で定義
表示内容
分割勤務はできません。連続3時間以上の1区間にしてください。
挙動
スタッフと勤務区間を示す。
理由
合計時間が足りていても、連続した1区間というルールを満たさない。

要確認(警告)2件

値は有効だが、運用上は確認が必要。データは反映され、アップロードも完了する。エラーではないので赤にはせず、何も問題がない成功でもないため緑にもせず、警告の黄色で示す。

全2項目の詳細
A12

勤務予定者がいない時間帯

バックエンドで定義
表示内容
勤務予定者がいません。
挙動
保存後に警告し、隣接する0人の枠をまとめる。
理由
入力が有効でも、勤務者がいない時間帯は発生する。
ユーザーの視点
意図的に人を配置しない時間帯もある。すべて誤りとして中止すると、正しい操作を妨げてしまう。
A13

勤務予定者が1人だけの時間帯

バックエンドで定義
表示内容
勤務予定者が1人だけです。
挙動
保存後に警告し、隣接する1人の枠をまとめる。
理由
更新は有効でも、人数として確認する必要がある。

通信と権限5件

画面外の状態に依存するもの。サーバー側で判断した結果を受け取り、表示する。

全5項目の詳細
S1

アップロード中に通信が切れた

共同で定義
表示内容
通信が切れたため、反映されたか確認できません。シフトを再読み込みして内容を確認し、必要な場合だけ再アップロードしてください。
挙動
自動再送はしない。次のアップロードを許可する前に、その日のシフトとrevisionを再取得する。再取得に失敗した場合は、最新状態を確認できるまでアップロードを無効にする。サーバー側の置換は一括で成功か失敗だが、画面ではどちらだったかわからない場合がある。
理由
サーバーで反映が完了しても、応答だけ届かなかった可能性がある。再取得によってユーザーが最新の内容を確認でき、revisionの照合によって古い状態からの上書きを防ぐ。再取得後に元の処理が完了した場合は409になることもある。
ユーザーの視点
通信が切れた後に「何も変更されていない」と伝えるのは不正確。次に何を確認すればよいかを示す。
S2

サーバー側の検証で失敗

バックエンドで定義
表示内容
フロントエンドのエラーと同じ形式で表示
挙動
レスポンスのエラーコードを画面表示用の文言に変換
理由
フロントエンドの検証を通ってもサーバーで拒否されることはある。表示形式は揃える。
ユーザーの視点
フロントでは通った同じファイルがサーバーで拒否されると、別の種類のエラーに見えやすい。同じ形式で示して混乱を避ける。
S3

編集権限がない

バックエンドで定義
表示内容
アップロードボタンを無効にし、理由を表示
挙動
画面読み込み時に権限を確認(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)
理由
押してから拒否するより、最初から押せない理由を示す方がわかりやすい。
S4

画面を開いた後に、この日のシフトが更新された

バックエンドで定義
表示内容
この日のシフトは画面を開いた後に更新されています。再読み込みして最新の内容を確認してください。
挙動
保存時に読み込んだrevisionを照合し、一致しなければ反映せずに止める
理由
別のユーザーによる更新だけでなく、応答が届かなかった本人の先のアップロードで更新されている場合もある。古い状態からの上書きを防ぐ。
ユーザーの視点
通信が切れた直後に「別のユーザーが変更した」と言われると誤解を招く。本人の先の操作が反映された可能性もある。
S5

公開済みのシフトを変更する

バックエンドで定義
表示内容
このシフトは公開済みです。変更するとスタッフに再度通知されます
挙動
実行前に確認を表示(サービス全体を想定した設計。独立した日別ダッシュボードには未実装)
理由
スタッフにも影響する操作だから、画面の外で何が起きるのかを事前に伝える。

エラーコードとメッセージ

コードをどちらで定義するかは、検証をどこで行うかによります。一方、表示するメッセージはすべてフロントエンドで定義します。サーバーから文言そのものを返すと、言葉の修正や言語の追加のたびにバックエンドの改修が必要になります。

コードと文言の対応表を先に作っておけば、実装時にはその表を参照すればいいです。メッセージを実装者がその場で考える必要はありません。

B・A・Sの番号は、この仕様書内の参照番号。実装では対応表に記載した結果・問題コードを使います。異なる2組の検証ルールを意味するものではありません。

コードとメッセージの対応表(24件)
コード定義する側jaen
FILE_TYPE (B1)フロントエンドで定義拡張子が.csvのCSVファイルを選択してください。Choose a CSV file with a .csv extension.
FILE_TOO_LARGE (B2)フロントエンドで定義このファイルは1 MiBを超えています。より小さい日別シフトのCSVを選択してください。This file is larger than 1 MiB. Choose a smaller daily schedule CSV.
FILE_EMPTY (B3)フロントエンドで定義ファイルに勤務表のデータがありません。現在のCSVをダウンロードして、もう一度お試しください。No schedule data was found in this file. Download the current CSV and try again.
HEADER_INVALID (B4)フロントエンドで定義必須の列がありません:{columns}。現在のCSVをもう一度ダウンロードして、お試しください。The CSV is missing required columns: {columns}. Download the current CSV again and try again.
FILE_ENCODING (B5)フロントエンドで定義このファイルをUTF-8として読み取れませんでした。UTF-8のCSVとして書き出して、もう一度お試しください。This file could not be read as UTF-8. Export it as a UTF-8 CSV and try again.
DATE_MISMATCH (B6)共同で定義このファイルは{found}のものですが、選択中の日付は{expected}です。{expected}のファイルを選択してください。This file is for {found}, but the selected day is {expected}. Choose a file for {expected}.
FILE_UNREADABLE (B12)フロントエンドで定義ファイルを読み取れませんでした。もう一度選択してください。This file could not be read. Choose the file again.
CSV_MALFORMED (B13)フロントエンドで定義この行は{actual}フィールドですが、{expected}フィールド必要です。空欄も含め、8つの時間フィールドを残してください。This row has {actual} fields; {expected} are required. Keep all eight time fields, including blank fields.
STAFF_NOT_ACTIVE (A1)バックエンドで定義{row}行目 · {value}:このIDは現在のスタッフ一覧にありません。現在のCSVをダウンロードして、スタッフIDを確認してください。Row {row} · {value}: This ID is not in the current active staff list. Download the current CSV and check the staff ID.
STAFF_ROW_MISSING (A4)バックエンドで定義{name}({staffId}):ファイルに行がありません。非勤務の人も含め、現在のスタッフ全員の行が必要です。{name} ({staffId}): No row in the file. Every current staff member needs a row, even when off duty.
STAFF_ROW_DUPLICATE (A5)バックエンドで定義{rows}行目:スタッフID「{value}」が複数の行にあります。スタッフ1人につき1行にしてください。Rows {rows}: Staff ID “{value}” appears more than once. Keep one row for each staff member.
STAFF_ID_MISSING (A14)バックエンドで定義{row}行目:スタッフIDが必要です。Row {row}: A staff ID is required.
SCHEDULE_VALUE_INVALID (A15)バックエンドで定義{row}行目 · {time}:無効な値です。TRUE、FALSE、または空欄にしてください。(入力値: {value})Row {row} · {time}: Not a valid value. Enter TRUE, FALSE, or leave the cell blank. (Entered: {value})
SHIFT_TOO_SHORT (A16)共同で定義{name} · {period}:勤務は{hours}時間です。この店舗では、勤務する日は連続3時間以上が必要です。{name} · {period}: Scheduled for {hours} hours. This shop requires at least 3 consecutive hours per scheduled day.
SPLIT_SHIFT (A17)共同で定義{name} · {periods}:分割勤務はできません。連続3時間以上の1区間にしてください。{name} · {periods}: Split shifts are not allowed. Use one continuous period of at least 3 hours.
STALE_DATA (S4, result: conflict)バックエンドで定義この日の勤務表は読み込んだ後に変更されています。再アップロードする前に、再読み込みして最新の内容を確認してください。This day’s schedule has changed since it was loaded. Reload to review the latest version before uploading again.
FILE_EMPTY (B3; no staff rows)フロントエンドで定義ファイルにスタッフの行がありません。現在のCSVをダウンロードして、もう一度お試しください。No staff rows were found in this file. Download the current CSV and try again.
HEADER_INVALID (B4; duplicate columns)フロントエンドで定義各列は1回だけ必要です。重複している列見出しを削除してください。Each CSV column must appear exactly once. Remove duplicate column headings.
HEADER_INVALID (B4; unexpected columns)フロントエンドで定義想定外の列があります:{columns}。ダウンロードしたCSVの列を使ってください。Unexpected columns: {columns}. Use the columns in the downloaded CSV.
DATE_MISMATCH (B6; invalid date)共同で定義すべての日付欄に{expected}を入力してください。日付は選択中の日と一致している必要があります。Use {expected} in every date field. The date must match the selected day.
CSV_MALFORMED (B13; text after closing quote)フロントエンドで定義閉じ引用符の後に余分な文字があります。Unexpected text after a closing quote.
CSV_MALFORMED (B13; misplaced quote)フロントエンドで定義引用符はフィールドの先頭に置くか、引用符で囲んだフィールド内でエスケープしてください。A quote must begin a CSV field or be escaped inside a quoted field.
CSV_MALFORMED (B13; unclosed quoted field)フロントエンドで定義引用符で囲んだフィールドが閉じていません。A quoted field was not closed.
SERVER_ERROR (proposed API)バックエンドで定義処理に失敗しました。担当者にお問い合わせください(コード:{code})Something went wrong. Contact your administrator (code: {code}).

各メッセージは何が起きたかと、次に何をするかを伝えます。「値が不正です」だけでは、何も直せません。

サーバー障害(API案のSERVER_ERROR)は、ユーザーには直せません。この場合だけコードをメッセージに含め、問い合わせを受ける側が調べる手がかりにします。

ユーザーの視点
ユーザー自身が直せるエラーと、直せないエラーでは、次の行動が違います。修正して再試行するか、助けを求めるか。どちらかわからないメッセージは、そのどちらにもつながりません。読んだ瞬間に次の一手が決まるようにします。

APIの仕様

以下の5つはサービス接続時のAPI仕様案。独立したダッシュボードはメモリ上のゲートウェイを使い、このHTTP APIを実装していません。削除と公開は、より広いサービス機能の設計にあたります。

まずフロントエンドが、各画面でいつどんなデータが必要かを示します。担当エンジニアがDBの構造と照らし合わせ、返せる形を提案します。それを受けて、フロントエンドでどう扱うかを決めます。各エンドポイントには、このやり取りを記しています。

1フロントエンドから求めたこと

2バックエンドからの回答

3それを受けて決めたこと

1. その日のシフトを取得

GET /api/shifts/daily?date=2026-10-15
1

現在のスタッフごとに、8つの時間枠それぞれの勤務の有無と、店舗の勤務区間のルールが必要。名前は表示用で、照合にはIDを使いたい。

2

DBにはコマがまばらに保存されており、そのまま返すと欠けのある配列になる。すべての枠を埋めて返すことも可能。

3

現在のスタッフごとに8つの勤務有無をbooleanで返す。非勤務、または連続3時間以上の1区間で勤務する。

リクエストとレスポンスの形式
{
  "date": "2026-10-15",
  "status": "draft",
  "revision": 0,
  "updatedAt": "2026-10-14T17:42:00Z",
  "businessHours": { "start": "09:00", "end": "17:00", "slotCount": 8 },
  "workRules": { "minConsecutiveHours": 3, "allowSplitShifts": false },
  "staff": [
    {
      "staffId": "st_001",
      "name": "Anna",
      "active": true,
      "slots": [true, true, true, true, false, false, false, false]
    }
  ],
  "permissions": { "canEdit": true, "canPublish": false }
}

保存済み勤務表とrevisionを一緒に返す。変更時はexpectedRevisionを送り、サーバーが一括保存の直前に照合する。updatedAtは表示用の日時とする。

businessHoursとworkRulesを画面用のレスポンスに含める。営業時間と勤務区間のルールはバックエンドから渡し、フロントエンドでは固定しない。

permissionsもレスポンスに含める。フロントエンドは権限のルールを持たず、サーバーの判定結果を使う。ルール変更時にフロントを変えずに済む。この形はバックエンド側からの提案。permissionsと公開状態は、サービス全体の設計にあたる。

nameは表示用だけに使う。CSVの照合はstaffIdで行う。同姓同名や改姓があるので、名前では照合しない。

2. 保存済み勤務表のCSVを取得

GET /api/shifts/daily/csv?date=2026-10-15
→ text/csv

date,staff_id,09:00-10:00,10:00-11:00,11:00-12:00,12:00-13:00,13:00-14:00,14:00-15:00,15:00-16:00,16:00-17:00
2026-10-15,st_001,TRUE,TRUE,TRUE,TRUE,FALSE,FALSE,FALSE,FALSE
...

CSVには日付をあらかじめ入れる。手入力させるとB6が起きやすい。

現在の全スタッフを、非勤務の人も含め8つの時間フィールドとともに入れる。行を手作業で作らせると、A4が起きやすい。

現在のスタッフだけを入れる。A1が起こるのは主に古いファイルを再利用した場合。

空のテンプレートではなく保存済みの勤務表を返す。競合・結果不明から復旧した後は、新しいCSVを取得し、古いファイルに加えた変更を移す。

3. アップロード(検証と置換)

POST /api/shifts/daily/upload
Content-Type: multipart/form-data

date:             2026-10-15
expectedRevision: 0
file:             (CSV)
1

画面には、どの行のどの値が問題かを示したい。ただし行番号のあるエラーと、スタッフや時間帯に紐づくエラーがある。すべてを同じ形式に押し込まないでほしい。

2

検証はサーバーで行うので、コードもここで定義する。全エラーを返すとレスポンスが大きくなるため、返す件数に上限を設け、超えた分は件数だけ返す。

3

エラーコードはバックエンド側で定義し、対応する文言をフロントエンド側で用意する。エラーの単位によってレスポンスの形を変える。行番号が必要なものも、スタッフIDと時間帯が必要なものもある。このAPI案では、上限を超えた件数をtruncated.omittedで返し、画面には「ほかにn件の問題」と表示する。独立したダッシュボードは、検出した問題をすべて返す。

レスポンスの形式(200/422/409)

200 — 反映済み

{
  "result": "applied",
  "revision": 1,
  "updatedAt": "2026-10-14T17:43:00Z",
  "warnings": [
    { "start": 0, "end": 1, "count": 1 },
    { "start": 7, "end": 8, "count": 0 }
  ]
}

422 — 処理中止

{
  "result": "rejected",
  "blocking": [
    { "code": "DATE_MISMATCH", "row": 2, "expected": "2026-10-15", "found": "2026-10-16" }
  ],
  "errors": [],
  "truncated": { "omitted": 0 }
}

422 — 修正が必要

{
  "result": "rejected",
  "blocking": [],
  "errors": [
    { "code": "SHIFT_TOO_SHORT", "staffId": "st_001", "start": 0, "end": 2 },
    { "code": "SPLIT_SHIFT", "staffId": "st_003", "periods": [{ "start": 0, "end": 3 }, { "start": 4, "end": 7 }] },
    { "code": "SCHEDULE_VALUE_INVALID", "row": 4, "slot": 2, "value": "yes" },
    { "code": "STAFF_ROW_MISSING", "staffId": "st_002" }
  ],
  "truncated": { "omitted": 0 }
}

409 — 更新の競合

{
  "result": "conflict",
  "code": "STALE_DATA",
  "revision": 1,
  "updatedAt": "2026-10-14T17:43:00Z"
}

blockingとerrorsは別々の配列。処理を止めるエラーは最初の1件で止まるため、通常blockingは1件だけ。ただし配列にしておけば、将来複数返す場合にも仕様を変えずに済む。warningsの期間はstartとendの枠番号で示す。startは含み、endは含まない。0が09:00。

エラーの形は項目によって異なる。rowを持つものも、staffIdと時間帯を持つものもある。すべて同じ形にすると、画面側で「行番号がない場合」を分岐させることになる。報告する単位に合わせて形式を分ける。

置換は1つのトランザクションで実行し、全件反映か全件未反映のどちらかになる。ただし、応答が失われると画面側では結果を確認できない。S1ではその日のシフトとrevisionを再取得してから再アップロードする。古いrevisionによる書き込みはS4で拒否する。

4. 削除

DELETE /api/shifts/daily?date=2026-10-15
expectedRevision: 0

削除にもexpectedRevisionを必要とする。置換と同じくらい影響が大きいので、競合の確認も同じ仕組みを使う。削除はサービス全体の設計にあたる。

この仕様で扱う削除は1日単位だけ。複数日をまとめて削除するAPIは別にあり、ここでは扱わない。影響範囲の違う操作を1つのエンドポイントにまとめると、権限制御が複雑になる。

5. 公開状態を変更

PATCH /api/shifts/daily/status

{ "date": "2026-10-15", "status": "published", "expectedRevision": 1 }

状態の変更はアップロードと分ける。アップロードと同時に公開してしまうと、公開前に内容を確認できない。公開はサービス全体の設計にあたる。

スタッフへの通知はサーバー側で起動する。フロントから通知APIを別に呼ぶと、公開だけ成功して通知は失敗することがあり得る。

フロントエンドとバックエンドの分担

何をどちらで検証するかは、担当エンジニアと合意しました。同じ検証を両側に置くか、片方だけで行うか。両側から見える情報を突き合わせて決めた、その記録。

片方だけが担当する項目や、相手側の判定結果に依存せず独立して確認する項目は、濃い色で示します。

20項目の分担
検証項目フロントエンドバックエンド
ファイル形式B1選択時に確認。送信しない—
ファイルサイズB2解析前に確認。送信しない受信時にも確認。直接POSTされた場合に備える
空ファイルB3解析結果が0行なら中止最後の防止策。空ファイルは1日分を丸ごと削除してしまう
文字コードB5デコードに失敗したら検出—
区切り文字(追加要件。このCSVには適用しない)B11ヘッダー行で検出—
必須の列B4ヘッダー行で最初に確認最後の防止策
日付の一致B6選択中の日付と照合し、すぐに中止独立して再確認。フロントエンドの判定には依存しない
日付の範囲(追加要件。このCSVには適用しない)B8 B9ユーザーの端末時刻で目安を確認サーバー時刻で最終判定
staff_idの存在A1 A14取得済みの一覧と照合し、行番号も示す最終判定。一覧は取得時点の情報
在籍状態(追加要件。このCSVには適用しない)A2取得時点の状態で事前確認最終判定。取得後に変わる可能性がある
時間列とスタッフ行B4 B13 A48つの時間列と現在の全スタッフの行を要求する保存前に同じ構造を再検証する
スタッフ行の重複A5重複IDの行番号をまとめて示す置換前に、スタッフ行が一意であることを確認する
勤務の有無A15TRUE・FALSE・空欄を受け付け、不正な入力値は修正用に残す保存前にboolean以外の勤務値を拒否する
連続3時間以上の1区間A16 A17分割勤務と3枠未満の勤務区間を検出する保存前に同じ勤務区間のルールを再検証する
1日の上限(追加要件。このCSVには適用しない)A9dailyLimitHoursを使いスタッフ単位で合計最終判定。上限値を提供する
連続勤務と休憩(追加要件。このCSVには適用しない)A10workRules.maxContinuousWorkHoursを使い、連続する勤務コマの入力時間を合計最終判定。会社の基準値をworkRulesで提供する
営業時間外(追加要件。このCSVには適用しない)A11businessHoursと照合最終判定。営業時間の情報源
人数の警告A12 A13独立したダッシュボードでは、保存成功後の勤務表から0人・1人の時間帯を算出して表示する。このAPI案では、成功応答のwarningsを表示する。このAPI案では、保存した勤務表から0人・1人の時間帯を算出し、warningsとして返す。
更新の競合S4読み込んだrevisionを保持しexpectedRevisionとして渡す保存済みの1日分を置換する前に古い版を拒否する
権限(サービス全体の設計)S3受け取った権限に応じてUIを制御ここで判定。権限のルールはサーバーが持つ

型・範囲・必須項目・重複などの構造的な検証は、両側で同じルールを持ちます。フロントエンドは修正点をすぐに返し、バックエンドは直接POSTされた場合やフロントエンドの実装漏れを補います。ルールを二重に保つコストは受け入れます。

在籍状態や日付の範囲など、両側の判断が食い違う可能性があるものは、フロントエンドを案内、バックエンド側を最終判定とします。フロントを通ってもサーバーで拒否される可能性は、最初から想定しています。S2は例外扱いではなく通常の経路として扱い、フロントエンドで収集するエラーと同じ形式で示します。

バックエンドは、保存前に日付と勤務データを再検証します。B6の日付照合も、フロントの判定に依存せず行います。アップロードは1日分を丸ごと置き換えるため、日付違いによる誤更新を防ぎます。

現在の操作例は、1時間枠×8のboolean値を使います。非勤務、または連続3時間以上の1区間であることを確認します。1日の上限と休憩の基準は広い設計案に属し、このCSV形式には適用しません。

現在の実装では、保存成功後の勤務表から人数の警告を算出します。保存前の拒否条件ではなく、保存失敗を意味しません。

画面仕様設計書がエンジニアに任せること

この画面仕様設計書で決めるのは、何をいつ表示するか、データをどこに置くか、検証をどう分担するか、メッセージに何を書くか。

どう実装するかはエンジニアに任せます。条件分岐、何をstateにするか、コンポーネントとpropsの構成、既存のコードベースに合う、読みやすく拡張しやすいコードの書き方など。

何をいつ、なぜ表示するかを決めないままにすると、その判断は実装中に行われます。先に合意しておけば、エンジニアは定義された挙動をもとに、実装方法の判断に集中できます。

この画面仕様設計書と右側の画面について

右側の動く画面は、紙の仕様だけでは判断しづらい挙動を試すために私が作ったもの。普段の案件でも、必要に応じてプロトタイプで挙動を確かめ、実装前の仕様を詰めています。

操作例を選ぶと、用意されたCSVデータを解析・検証します。ファイルの選択とダウンロードは操作例として扱い、端末のファイルやサーバーへの送信は必要ありません。

案件で必要なときは、Figmaと動くコードを問いに応じて使い分け、行き来します。設計しながら実現可能性も試すことで、仕様が紙の上だけで終わりません。

このデモは検証用で、本番用のコードではありません。実際の製品に組み込むには、状態管理やエラー境界、テストなどの作り直しが必要。動かして検証することと、本番に出すことは別として扱っています。

このページで使用

React / TypeScript / Next.js / Tailwind CSS

設計で使用

Figma(Variables、コンポーネントのバリアントとプロパティ)

実装サンプルで使用

Next.js / React / TypeScript / Tailwind CSS / Radix Primitives

この画面仕様設計書は、何を作るかが決まった後の段階から始まります。実際のプロジェクトでは、その前から関わることも多く、そこで何を決めるかも仕事の一部。

その前の段階で何が未決定で、どんな案を出し、何を決めたのかは、ケーススタディで実案件をもとに紹介しています。

ケーススタディを読む

このサンプルの元になった実案件。何が決まっていなかったのか、どう合意し、その決定をどう本番実装まで届けたのか。

読む