Linear migration metadata¶

• Linear issue: TAK-196
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-196/tak-192-b-excel参照関係解析と初期データzip-manifest生成
• Linear status: Done
• Linear team: Takayuki Komoda
• Linear project: EPAA App
• Linear assignee: Takayuki Komoda
• Linear labels:
• Linear created: 2026-07-12T21:49:39.172Z
• Linear updated: 2026-07-13T21:57:05.752Z
• Linear archived:

---

Original description¶

背景¶

Excel参照関係をDB relationとして扱う場合、参照先マスタを先に取り込み、参照元を後から取り込む必要がある。CSVをZIPでまとめて出力する運用では、利用者に手順を覚えさせるより、ZIP内に取込計画 manifest を同梱し、生成アプリ側の初期データ取り込み機能がその計画に従って処理できる形にする方が安全で使いやすい。

目的¶

Excel内の参照関係を解析し、参照マスタ候補、relation候補、初期データ取込順、TRUNCATE対象、CSVファイル対応を initial-data-manifest.json として出力できる中間データを生成する。

対応内容¶

• 別シートの小規模マスタ表を検出する。
• 入力規則リストから参照マスタ候補を検出する。
• VLOOKUP/XLOOKUP/別シート参照を候補として検出する。
• Excel整数ID列はDB主キー id ではなく、初期データ取込時の照合キー候補として扱う。
• Excel整数IDを本テーブルに永続カラムとして残すか、初期取込時だけの一時照合キーとして使うかを候補上で区別できるようにする。
• 取引先ID、取引先名、区分のように同じ参照先行から複数列が取れるケースを検出する。
• 担当者、責任者のように同じ参照先テーブルを複数フィールドで参照する候補を保持する。
• 参照依存関係から推奨取込順を算出し、循環・参照先不明・キー不一致を warning として保持する。
• CSV ZIP に initial-data-manifest.json を同梱する。
• manifest には対象CSV、resource/table、適用順、依存関係、relation解決ルール、TRUNCATE候補、破壊的操作警告文言を含める。
• 解析不能な参照は理由付き警告にし、破綻したYAMLやmanifestを生成しない。

非対象¶

• 生成アプリ側でZIPをアップロードして初期データを取り込む固定API/画面の実装は別タスクで扱う。
• 本番データ移行や既存環境への自動マイグレーションは対象外。
• 複雑な外部ブック参照や全Excel関数の完全解析は対象外。
• DBスキーマ変更、release SQL、OpenAPI変更はこのタスクでは原則行わない。

受入条件¶

• 参照マスタ候補、参照元列、参照先キー列、表示列候補を確認データに保持できる。
• 同一マスタを複数relationとして参照する候補を区別できる。
• Excel整数IDが、永続カラム候補ではなく初期取込照合キー候補として明示される。
• 参照依存関係から推奨取込順を保持できる。
• CSV ZIP に initial-data-manifest.json が含まれる。
• manifest に適用順、CSVファイル、TRUNCATE対象候補、relation解決ルール、警告文言が含まれる。
• 解析不能な参照でYAML/manifest生成が破綻しない。
• 既存のExcel import option / CSV key / YAML proposal動作が回帰しない。

Linear attachments¶

• TAK-196 Excel CSV ZIPに初期データmanifestを同梱する

Linear comments¶

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-13T21:57:35.468Z)¶

PR #107 を develop へマージしました。

Merge commit: 4b5e7ad783dfef4e34149fdcf763078fd4d00442

完了条件を満たしたため、TAK-196 を Done に更新します。後続の生成アプリ側ZIP取込API/UI/検証は TAK-201 / TAK-202 / TAK-203 で継続します。

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-13T21:28:16.483Z)¶

実装完了し、PRを作成しました。

PR: https://github.com/takataka328-max/EPAA/pull/107

主な対応:

• Excelシート間の参照候補を検出し、CSV ZIPに initial-data-manifest.json を同梱
• Excel整数IDをDB主キーではなく temporary な初期取込照合キー候補として manifest に記録
• 初期データZIP manifest の警告、取込順、依存、relation候補をGenerator GUIに表示
• 確認画面でfield名を編集した後も、manifest relationが編集後のfield名を使うよう再解析
• resource-yaml.adoc と生成HTMLへ仕様を追記

検証:

• dotnet test .\tests\generator-gui\EPAA.Generator.Gui.Tests.csproj --no-restore -> 55 passed
• dotnet build .\tools\EPAA.Generator.Gui\EPAA.Generator.Gui.csproj --no-restore -> success
• npm.cmd run build -> success（既存chunk size warningのみ）
• powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\publish-generator-gui.ps1 -> success
• published exe起動ログで WebView2 navigation completed: success=True status=200 を確認

ステータスはPRレビュー待ちとして In Review に更新済みです。

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-12T23:31:09.252Z)¶

スコープ修正とタスク追加を実施しました。

更新したTAK-196

• TAK-192-B Excel参照関係解析と初期データZIP manifest生成
• Excel参照候補解析に加えて、CSV ZIPへ initial-data-manifest.json を同梱する前段タスクに再定義。
• Excel整数IDはDB主キーではなく、初期取込時の一時照合キー候補として扱う。永続カラムにするか一時mappingだけにするかは候補上で区別。
• 生成アプリ側の実取込API/画面は別タスクに分離。

追加タスク

• TAK-201: 初期データZIP取込APIを実装する
• TAK-202: 管理者向け初期データ取り込み画面を実装する
• TAK-203: 初期データ取り込みの検証を整備する

この分割により、TAK-196ではExcel GUI側のmanifest生成までを実装し、破壊的なDB初期化・管理者権限・transaction rollbackなどはTAK-201以降で扱います。

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-12T23:14:00.150Z)¶

要求チェックポイント案

目的

• Excel内の参照関係を解析し、参照マスタ候補とrelation候補を確認画面で扱える中間データとして保持する。
• TAK-195 の方針に沿い、Excel上のID/コード/番号はDB主キー id ではなく、参照先マスタの照合キー候補として扱う。

対象

• 別シートの小規模マスタ表候補を検出する。
• 入力規則リスト、VLOOKUP/XLOOKUP、別シート参照式から参照候補を検出する。
• 参照元列、参照先シート/マスタ候補、参照先キー列、表示列候補を中間データに保持する。
• 取引先ID/取引先名/区分のように、同じ参照先行から複数列が取れる候補をグルーピングできるようにする。
• 担当者/責任者のように同じ参照先テーブルを複数relationで参照する候補を、別のrelation候補として識別できるようにする。
• 解析不能な参照は理由付き warning として保持し、破綻した YAML を生成しない。

非対象

• このタスクでは relation YAML の自動確定までは必須にしない。まず画面・後続処理で扱える中間候補を作る。
• DBスキーマ変更、OpenAPI変更、生成アプリ本体のCSV import仕様変更は対象外。
• 100万行級のストリーミング取込最適化は TAK-195 と同様、将来の temp table/JOIN 境界として扱う。

受入条件

• 参照マスタ候補、参照元列、参照先キー列、表示列候補を ExcelImportAnalysisDocument / ExcelImportConfirmationDocument 系の確認データに保持できる。
• 同一マスタを複数relationとして参照する候補を区別できる。
• Excel整数IDがある場合、ID候補/照合キー候補として明示される。
• 解析不能な参照は warning になり、YAML生成は壊れない。
• 既存の Excel import option / CSV key / YAML proposal 動作が回帰しない。

Reviewer観点

• OpenAPI/DB/release SQL 変更なしの想定で妥当。
• 画面に候補を表示する場合は browser-visible 検証が必要。
• 後続で relation YAML 自動生成まで踏み込む場合は、generated/fixed/custom 境界とドキュメント更新範囲を再確認する。