Linear migration metadata¶

• Linear issue: TAK-5
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-5/yaml仕様スキーマを定義する
• Linear status: Done
• Linear team: Takayuki Komoda
• Linear project: EPAA Core
• Linear assignee: Takayuki Komoda
• Linear labels:
• Linear created: 2026-05-27T23:03:39.481Z
• Linear updated: 2026-06-08T12:44:43.188Z
• Linear archived:

---

Original description¶

概要¶

EPAAの生成元となるYAML仕様フォーマットを定義する。

対象¶

• テーブル定義
• カラム定義
• バリデーション
• 権限
• 一覧/詳細画面
• ワークフロー
• 通知

完了条件¶

• YAMLサンプル作成
• JSON Schemaまたは定義仕様作成
• 将来拡張方針整理

Linear comments¶

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T19:51:20.544Z)¶

参照項目の説明を現行実装に合わせて修正しました。

修正内容:

• customer.customer_name の例を廃止
• relations.customer を定義し、一覧列・キーワード検索では relation.customer.display を使う形に変更
• 最大サンプルに各設定の意味をコメントで追加
• 特に参照項目について、以下の役割差をコメント化
  • fields.customer_id: 自テーブルに保存する外部キー項目
  • keys.foreign_keys: DB制約
  • relations.customer: 画面表示・候補取得のための関連定義
  • relation.customer.display: 一覧列・検索で使う関連先表示値

確認:

• rg で relation.customer.display / relations.customer の使用を確認
• metadata validation: passed
• git diff --check: exit code 0
• resource-yaml-max-sample.png を再取得

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T18:12:10.061Z)¶

追加要望に対応し、docs/manuals/resource-yaml.html に最大サンプルと画面サンプルを追加しました。

追加内容:

• 最大 resource.yaml
  • permissions / audit / export / import / list.columns / keyword_search / default_sort / keys / fields / relation / validation / normalize / ui / csv
• 最大 i18n.yaml
• 最大 seed.yaml
• 設定から表示される画面サンプル
  • 一覧画面
  • 検索エリア
  • 新規登録画面
  • 更新画面
  • 詳細画面
• 各画面サンプルに、対応するYAML設定の説明を追加

検証:

• HTML主要見出し確認: OK
• metadata validation: passed
• git diff --check: exit code 0
• ブラウザ証跡:
  • resource-yaml-max-sample.png
  • resource-yaml-screen-samples.png
  • resource-yaml-screen-samples-mobile.png

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T14:17:07.412Z)¶

ユーザー指摘により、docs/manuals/resource-yaml.html の検証手順を修正しました。

修正:

• 利用者向けの検証手順をコマンドラインではなく GUI 主導に変更
• Generate タブで Validate metadata を押す手順を明記
• CLI は開発者の自動確認/CI用の補足扱いに変更
• 作成フローのステップも GUIで検証する に変更

確認:

• HTML内の GUIで検証して直す、Generate タブ、Validate metadata 記述を確認
• full-page 証跡 resource-yaml-html-validate-gui.png を保存
• git diff --check: exit code 0

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T14:02:55.202Z)¶

ユーザー指摘に基づき、docs/manuals/resource-yaml.html を AsciiDoc 生成ではなく、直接HTMLマニュアルとして作り直しました。

修正内容:

• 左固定目次を持つ単独HTMLへ変更
• 全体像、作成するファイル、作成手順、resource.yaml、fields の書き方、画面と検索、参照・CSV・seed、検証と直し方、早見表 の構造に再編
• 導線カード、作成フロー、最小サンプル、項目の置き場所、よくあるミスを追加
• モバイルでは本文を先に表示し、目次は後ろに回るよう調整

検証:

• metadata validation: passed
• HTML主要導線確認: OK
• デスクトップスクリーンショット: resource-yaml-html-redesign-top.png
• モバイルスクリーンショット: resource-yaml-html-redesign-mobile.png
• git diff --check: exit code 0

注意:

• adoc/manuals/resource-yaml.adoc は戻さず残しています。
• 直接HTML正本化により、後続で build-docs.ps1 に上書きされない運用整理が必要です。

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:48:19.378Z)¶

追加対応として、docs/manuals/resource-yaml.html を手作業YAML作成者向けのページとして再構成しました。

追加変更:

• adoc/manuals/resource-yaml.adoc のタイトルを EPAA YAML 作成ガイド に変更
• 冒頭に このページの読み方 と 作成するファイルの全体像 を追加
• YAML 作成の進め方 に作業チェックリスト、手作業作成の基本ルール、どのブロックから書くかを追加
• 最小 resource.yaml 例に「この例で重要なのは」の対応表を追加
• docs/manuals/resource-yaml.html を再生成
• resource-yaml.html のブラウザ証跡 resource-yaml-guide-top.png を追加

再検証:

• metadata validation: passed
• build-docs.ps1: exit code 0
• 主要見出し確認: OK
• resource-yaml.html ブラウザ表示: OK
• git diff --check: exit code 0

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:34:35.613Z)¶

実装とテストチェックポイントを完了しました。

変更:

• adoc/manuals/resource-yaml.adoc に YAML 作成手順、最小例、よくあるミス、metadata/実装境界、現行MVP正本スキーマ表を追加
• manuals/modelify-operation-guide.html#prepare に作成内容の決め方と resource.yaml 構成マニュアル へのリンクを追加
• docs/manuals/resource-yaml.html を docs build で生成
• reports/2026-05-29-yaml-schema-baseline/ に development/test/review とブラウザ証跡を記録

検証:

• metadata validation: passed
• build-docs.ps1: exit code 0
• 主要見出し確認: OK
• 操作ガイド #prepare ブラウザ表示: スクリーンショット取得済み
• git diff --check: exit code 0

残リスク:

• JSON Schema は今回作成対象外
• validator の検証項目追加は今回作成対象外

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:23:25.320Z)¶

実装前チェックポイントを作成しました。

対象は既存YAML仕様の整理と作成マニュアル補強です。実装コード、DB、OpenAPI、JSON Schema、サンプルYAMLは今回変更しません。

編集予定:

• adoc/manuals/resource-yaml.adoc
• manuals/modelify-operation-guide.html
• docs/manuals/resource-yaml.html（docs build生成）
• docs/epaa-specification-pdf.html（docs build生成）
• reports/2026-05-29-yaml-schema-baseline/ 配下のレポートと証跡

検証予定:

• 既存メタデータ検証
• build-docs.ps1
• 生成HTMLと操作ガイドの該当セクション確認
• 操作ガイド #prepare のブラウザ表示確認とスクリーンショット取得
• git diff --check

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:12:04.947Z)¶

設計チェックポイントを作成しました。

• Design: reports/2026-05-29-yaml-schema-baseline/design.md
• Review: reports/2026-05-29-yaml-schema-baseline/review.md
• Reviewer: Approved with notes

設計方針:

• manuals/modelify-operation-guide.html#prepare はGUI運用手順の入口として補強する
• YAMLの中身は adoc/manuals/resource-yaml.adoc を正本マニュアルとして厚くする
• 今回PRではJSON Schemaは作らず、現行C# validator + MVP正本スキーマ表で整理する
• 静的HTML変更があるため、ブラウザ表示確認とスクリーンショット証跡を行う

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:04:59.698Z)¶

ユーザー指摘を受けて、TAK-5の要件に「YAML作成用マニュアル整備」を明確に追加しました。

追加内容:

• resource.yaml / i18n.yaml / seed.yaml / app.yaml の作成順
• 1リソース追加の最小手順
• テーブル、フィールド、一覧、詳細、検索、CSV、権限、監査、関連、初期データの書き方
• よくあるミスと validator エラー対応
• YAML作成後の検証コマンド
• metadataへ書くべきものと generator/runtime/fixed/customへ切り出すものの判断

反映先候補:

• adoc/manuals/resource-yaml.adoc

更新ファイル:

• reports/2026-05-29-yaml-schema-baseline/requirements.md
• reports/2026-05-29-yaml-schema-baseline/review.md

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-05-29T13:02:19.801Z)¶

要件チェックポイントを作成しました。

• Branch: version/v0.1/yaml-schema-baseline
• Report: reports/2026-05-29-yaml-schema-baseline/
• 要件: requirements.md
• レビュー: review.md
• Notion 要求: https://www.notion.so/36f8d886122a81f9b90ee92e4dab9ba7

要件レビュー: Approved with notes

方針:

• TAK-5はYAML仕様をゼロから作るのではなく、既存 resource.yaml 仕様・サンプル・MetadataLoader/Validator/Generator実装を正本化/差分整理するタスクとして扱う。

現状確認:

• validate-metadata は examples/resource-schema 4リソース + app.yaml development で成功。

主な残論点:

• 今回PRでJSON Schemaファイルまで追加するか、まずC# validatorを現行正本として差分表を作るか
• 差分表の反映先文書