Linear migration metadata¶

• Linear issue: TAK-273
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-273/サンプルアプリ交通費精算
• Linear status: Backlog
• Linear team: Takayuki Komoda
• Linear project: EPAAサンプルアプリ
• Linear assignee:
• Linear labels:
• Linear created: 2026-09-23T06:13:08.459Z
• Linear updated: 2026-09-27T02:51:41.650Z
• Linear archived:

---

Original description¶

要件定義 v1¶

目的¶

交通費の申請、明細入力、承認状況を確認できる標準サンプルアプリを作成し、EPAAのサンプルアプリ配信機能からプロジェクトへ追加できるようにする。

位置付け¶

• TAK-144「サンプルアプリ：経費精算」は経費全般を扱うサンプルとする。
• TAK-146「サンプルアプリ：出張申請」は出張の事前申請を扱うサンプルとする。
• 本Issueは、出張後または日常業務で発生した交通費の精算台帳・明細入力に責務を限定する。
• 初期版ではTAK-144、TAK-146との自動データ連携は行わない。

対象業務¶

• 交通費精算の新規登録
• 1件の精算に対する複数明細の入力
• 交通手段、利用日、出発地、到着地、金額、備考の管理
• 申請、承認、差戻し、承認済み状態の確認
• 一覧検索、詳細確認、更新
• CSV入出力
• サンプルアプリとしてのテンプレートZIP配信

データモデル¶

交通費精算台帳: transport_expenses¶

• expense_code: 精算番号。必須。テナント内で一意。
• request_date: 申請日。必須。
• applicant_login_id: 申請者ログインID。必須。
• applicant_email: 申請者メールアドレス。必須。
• department_group_code: 所属グループコード。必須。
• title: 精算タイトル。必須。
• status: 状態。下書き、差戻し、承認済、申請中。
• 台帳から交通費明細を子テーブルとして編集できる。

交通費明細: transport_expense_lines¶

• line_no: 行番号。必須。
• detail_no: 明細番号。必須。
• transport_expense_id: 親台帳へのrelation。必須。利用者には通常表示しない。
• use_date: 利用日。必須。
• transportation_mode: 交通手段。必須。JR、その他、タクシー、バス、地下鉄、新幹線、航空機。
• departure: 出発地。必須。
• arrival: 到着地。必須。
• amount: 金額。必須。小数対応の数値項目。
• notes: 備考。任意。

画面要件¶

• アプリ一覧から交通費精算を開ける。
• 台帳一覧で精算番号、申請日、申請者、所属、タイトル、状態を表示できる。
• 台帳の登録・編集画面で、交通費明細をeditable gridとして追加・編集・削除できる。
• 台帳詳細で申請情報と明細一覧を確認できる。
• 明細単独の管理画面は表示しない。
• 状態、申請日、申請者、精算番号で一覧を検索・絞り込みできる。
• 台帳と明細をCSV出力でき、必要に応じてCSV取込できる。

権限・承認¶

• 管理者は全データと設定を確認できる。
• 申請者グループは自分の交通費精算を登録・更新できる。
• 経理または承認者グループは一覧確認、詳細確認、承認処理、CSV出力を行える。
• 承認フローは、申請中、差戻し、承認済みの状態遷移を確認できる標準構成とする。
• グループ、権限、ワークフローはYAMLだけを正式な運用管理経路にせず、EPAA Coreの初期設定・アプリ設定GUIから作成・編集・削除できるようにする。
• 具体的な承認者グループコードとデータ範囲は設計フェーズで確定する。

サンプルデータ¶

• 申請者2名分、精算2件以上、各精算に複数明細を用意する。
• 東京・大阪など実在の地名、JR、新幹線、地下鉄、タクシー等の現実的な値を使う。
• サンプルユーザー・グループ・権限は既存の検証用アカウント規約に合わせる。
• 業務データの自動投入はテンプレートインストールと分離する。
• seed.yaml または初期データZIPを使う場合も、既存ユーザー・認証・権限を上書きしない。

サンプル配信¶

• サンプルIDは transport-expense とする。
• 公開タイトルは「交通費精算」。
• テンプレートZIPには manifest.json と、少なくとも次の4ファイルを含める。
  • metadata/transport_expenses/transport_expenses.resource.yaml
  • metadata/transport_expenses/transport_expenses.i18n.yaml
  • metadata/transport_expense_lines/transport_expense_lines.resource.yaml
  • metadata/transport_expense_lines/transport_expense_lines.i18n.yaml
• CoreはZIPのchecksum、manifest、resource/table名重複、依存関係、パスを検証する。
• インストールは即時保存ではなく、metadata下書きのプレビューと承認を経て保存する。
• seedは初期インストール時に自動投入しない。
• カタログ登録・更新はTAK-242のサンプルカタログ管理方針に従う。

非対象¶

• 経費全般、領収書、宿泊費、交際費などの汎用経費機能。
• 出張申請の事前申請機能。
• TAK-144、TAK-146との自動連携。
• クレジットカード明細や会計システムとの連携。
• 支払予定、振込、会計仕訳などの支払管理。
• Coreから生成アプリDBへの業務データ直接投入。
• 既存サンプルの更新・3-way merge・ロールバック機能。
• src/generated の手編集。

受入条件¶

• 交通費精算の台帳一覧、登録、詳細、更新が動作する。
• 1件の台帳に複数の交通費明細を登録・更新・削除できる。
• 必須項目、金額、日付、選択肢の入力検証が動作する。
• 状態が下書き、申請中、差戻し、承認済みとして表示される。
• 権限により申請者、承認者、管理者の操作範囲を分けられる。
• 台帳・明細のCSV出入力が動作する。
• 5002検証環境でログイン、一覧、登録、明細編集、状態確認をブラウザで確認できる。
• サンプルテンプレートZIPのmanifest/checksum検証とCore GUIの追加プレビューが成功する。
• samples.json に登録後、公開カタログから「交通費精算」を選択できる。
• 既存の請求書、Wiki、経費精算、出張申請のサンプルに回帰がない。

影響範囲・管理¶

• Metadata: transport_expenses、transport_expense_lines のresource/i18n。
• Generated: metadataから再生成する出力のみ。生成物の手編集は禁止。
• Fixed/Custom: 標準CRUDと既存承認基盤で実現できる範囲を優先し、個別業務ロジックは必要性を確認してから設計する。
• DB: 既存テーブル定義を再利用できるか設計で確認する。変更する場合はversioned release SQLとrollback/recovery方針が必要。
• OpenAPI: 固定APIを追加する場合は先にOpenAPI契約を作成する。標準生成CRUDだけで完結する場合は追加不要。
• FE/BE: 標準生成画面・APIを優先し、固定実装を増やさない。
• Browser: 5002でのブラウザ確認が必須。必要に応じてdev.epaa.jpへ反映して確認する。
• Docs: 仕様変更があれば関連adocの更新要否を確認する。
• Linear: 本Issueを親要件とし、実装開始時にFE/BE/DB/Test/Docsの子Issue分割を判断する。
• Notion: 本要件はLinearで管理し、Notionへの自動登録は行わない。

次のチェックポイント¶

1. この要件定義を確認する。
2. 承認者グループ、状態遷移、サンプルアカウント、DB再利用可否を設計で確定する。
3. 設計レビュー後に実装計画と対象ファイルを提示する。
4. 実装はユーザー承認後に開始する。

追加要件: 日付入力UI改善（2026-09-26）¶

交通費精算の登録・編集画面では既存のカレンダー選択を維持しつつ、日付欄へ直接入力するときの操作性を改善する。

対象¶

• 台帳の申請日（transport_expenses.request_date）
• 明細の利用日（transport_expense_lines.use_date）
• 日付範囲検索の開始日・終了日
• 台帳編集画面の明細editable grid内の日付入力

方針¶

• 既存のカレンダー選択を維持し、日付欄はキーボードで連続して入力・修正しやすいDatePicker形式へ改善する。
• API・DBへ渡す値は従来どおり日付文字列（YYYY-MM-DD）とし、API/OpenAPI/DB変更は行わない。
• 生成元（FrontendSourceWriterおよび必要なテンプレート）を修正し、生成済みファイルを直接編集しない。
• 5002検証環境でブラウザ操作を確認する。

追加受入条件¶

• 申請日の入力欄からカレンダーを開いて日付を選択できる。
• 既存の申請日を編集でき、保存値が変わらない。
• 明細の利用日をeditable grid内でカレンダー選択できる。
• 日付範囲検索で開始日・終了日をカレンダー選択できる。
• 5002検証環境で上記のブラウザ確認が成功する。

追加要件: 承認ワークフローへの委譲（2026-09-26）¶

交通費精算の承認状態は、サンプルアプリ内の手入力ステータスではなく、インストール後にEPAA Coreで設定するワークフローを正本とする。

方針¶

• サンプルアプリ配信時に特定の承認ルートを固定投入しない。
• アプリをインストールすると、Coreのワークフロー設定画面で交通費精算を対象アプリとして選択できる。
• Coreで承認者グループ、ステップ、状態を設定・変更できるようにする。
• 交通費精算の既存status列は互換性のため保持するが、登録・編集画面では入力させない。
• 一覧・詳細の承認状態は、Coreワークフローの申請中・差戻し・承認済み等の状態表示を正本とする。
• 既存の承認パネルとワークフロー設定画面を利用し、交通費専用の固定承認ロジックは追加しない。

追加受入条件¶

• サンプルアプリのインストール後、Coreのワークフロー設定画面で交通費精算を対象アプリとして選択できる。
• 承認ステップと承認者グループをCoreから設定・変更できる。
• 交通費精算の登録・編集画面に手入力のステータス選択欄が表示されない。
• 申請中、差戻し、承認済み等の状態を既存の承認パネルで確認できる。
• ワークフロー未設定時でも交通費精算の登録・明細入力は壊れない。

追加要件: サンプルアプリ更新対応（2026-09-27）¶

本追加要件は、上記の初期版記述のうち「既存サンプルの更新を非対象」「transport_expense_lines」を上書きする。

確定仕様¶

• 交通手段はテキスト入力（metadata field は transportation_type、string + text widget）。
• 往復は boolean + checkbox。
• 支払方法は画面・metadataから削除する。ただし既存DB列は原則保持し、データを壊さない。DB列削除を行う場合は versioned SQL と rollback/recovery を必須とする。
• 合計金額は明細 amount の合計を親 total_amount に自動計算する。明細の追加・編集・削除・batch保存・明細0件を対象とする。
• 子リソースは transportation_expense_items、テーブルは transportation_expense_items。親は transportation_expenses。

Core側¶

• サンプル取込を追加と更新に分ける。追加時は同名 resource/table を拒否する。
• 更新時は resource 名と table 名で既存アプリを特定し、最新版との差分を表示する。
• 更新は metadata差分確認、承認、更新前バックアップ、YAML管理サービス経由の反映、metadata検証、generated source再生成、必要なDB変更の適用を行う。
• 旧版をインストール済みのdevアプリを、Core画面からサンプルサイト最新版へ更新できることを受入条件とする。

サンプルサイト側¶

• 1.0.0は履歴として保持し、修正版を1.1.0として公開する。
• manifest version、checksum、samples.json、package URL を一致させ、正式な deployment\\deploy.ps1 でデプロイ後に確認する。

検証¶

• Core標準metadata検証、生成、fresh/existing DB、更新/重複拒否、5002ブラウザ確認、サンプルサイト公開URL/checksum/health を確認する。
• Notion登録は行わず、本Issueを管理正本とする。

作業範囲修正: Coreのみ（2026-09-27）¶

今回の実装担当はEPAA Coreのみとする。EPAAサンプルアプリおよびEPAAサンプルサイトのソース変更、パッケージ作成、checksum更新、デプロイは対象外。Coreは公開済みサンプルパッケージを外部入力として、追加・更新・差分確認・バックアップ・metadata検証・generated source再生成・DB release SQLの準備/適用フローを実装・検証する。