設計書と動作確認手順の整備

データの形、API の仕様、ブラウザで同じ手順を確認する一式です。データの関係は図にし、API は仕様の画面でたどれます。ブラウザでは、その仕様に沿った手順を自動で通して確認します。図を見て項目の関係を確かめ、仕様で入出力を読み、ブラウザの手順で画面の流れを確認する、という順で使えるようにしています。

図でデータの関係を見て、OpenAPI で入出力を読み、Playwright でブラウザの手順を確認します。三つの記述は同じ置き場にあり、項目を変えたときにどこを更新するかを追いやすくしています。口頭の確認手順だけに頼らず、同じ操作をあとから再現できるようにしています。同じ操作を、あとから再現できるようにしています。

データの形、API、確認手順が別々のメモになっていました。項目を一つ変えたとき、図のどこが変わり、API のどの入出力が変わり、ブラウザではどの操作を見ればよいかを、メモの間で探していました。仕様を書いた人と、画面を確認する人で、見ている版が違うこともありました。確認手順が会話や断片的なメモのままだと、同じ操作をあとから再現できませんでした。

図を更新しても API の仕様が古いまま残ったり、仕様は新しくてもブラウザの確認手順が以前の画面のままだったりしました。確認する人がメモの版を取り違えると、同じ項目を別の意味で見ていました。手順が会話の中だけにあると、次の人が同じ操作を再現できませんでした。

データの関係は図にして、項目のつながりを画面とは別に残します。API は仕様の画面で項目と入出力をたどれます。ブラウザでは、その仕様に沿った手順を自動で通し、同じ確認を繰り返せるようにしています。図、仕様、確認手順を同じ置き場に置き、項目を変えたときに三つのどれを更新するかを追いやすくしています。確認はブラウザ上の操作として残し、口頭の手順だけに依存しないようにしています。

項目の追加や名前の変更は、図の関係、API の入出力、ブラウザの手順の三方に反映する前提で残しています。仕様の画面では項目をたどり、ブラウザの自動確認ではその手順を実行します。確認に失敗した場合は、図か仕様か画面の操作のどこがずれたかを見比べられます。メモを横断して手順を組み立て直す作業を、この一式に集めています。

データの図は Mermaid、API の仕様は OpenAPI です。仕様はブラウザで開いて項目をたどれます。ブラウザでの確認は Playwright で、同じ手順を繰り返し実行できます。言語は PHP と JavaScript です。図はデータの関係、OpenAPI は入出力、Playwright は画面の操作、という役割に分けています。三つの記述を同じ置き場に置き、項目の変更が図と仕様と確認手順のどこに効くかを追えるようにしています。

Mermaid は項目のつながり、OpenAPI はリクエストとレスポンス、Playwright は画面上の操作をそれぞれ固定します。PHP と JavaScript は、仕様や確認の実装を置く言語です。図を見てから仕様を読み、その後にブラウザを動かす、という参照の順を崩さないように、三つの成果物を並べています。