Linear migration metadata¶

• Linear issue: TAK-192
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-192/excel参照関係から参照マスタ候補を自動生成する
• Linear status: Done
• Linear team: Takayuki Komoda
• Linear project: EPAA App
• Linear assignee: Takayuki Komoda
• Linear labels:
• Linear created: 2026-07-11T09:15:18.044Z
• Linear updated: 2026-07-19T02:51:28.547Z
• Linear archived:

---

Original description¶

背景¶

TAK-132のExcel取込MVPでは、VLOOKUP/XLOOKUP、別シート参照、外部参照、入力規則リストなどを検出しても、参照マスタ化までは行わず警告・ヒント扱いとしている。

実運用のExcelでは、区分表、顧客区分、商品マスタ、担当者一覧などを別シートや参照式で管理していることが多く、単純な選択肢として取り込むだけでは、EPAA上の正しい参照マスタ構造にならない。

目的¶

Excel取込時に参照関係を検出し、必要に応じてマスタアプリと元アプリ側のrelation候補を生成できるようにする。

対象¶

• VLOOKUP/XLOOKUP、INDEX/MATCH、別シート参照、名前付き範囲、入力規則リストから参照マスタ候補を検出する。
• 参照元列、参照先範囲、表示列、コード列候補を解析する。
• 参照先データからマスタアプリ候補を作成する。
• 元アプリ側の項目を選択肢ではなくrelation候補として提示する。
• マスタ化する/しないをユーザーが選択できる。
• マスタ化対象はTAK-134の取込確認画面または後続の確認UIでレビューできる。
• 生成するresource.yaml/i18n.yaml/seed.yamlは既存metadata検証に通ること。

非対象¶

• MVP初回での複雑な数式の完全変換。
• 外部ブック参照先ファイルの自動取得。
• 参照関係が曖昧な場合の完全自動決定。
• 既存本番データの自動マイグレーション。

受入条件¶

• VLOOKUPまたは別シート参照を含むExcelから、参照マスタ候補が画面上で確認できる。
• ユーザーがマスタ化を選ぶと、マスタアプリと元アプリのrelation候補が生成される。
• ユーザーがマスタ化しない場合は、通常項目または選択肢候補として扱える。
• 生成結果はmetadata検証に通り、破綻したYAMLは反映できない。
• 参照先が解析不能な場合は、理由を明示した警告またはエラーとして表示する。

関連¶

• TAK-132: Excel/CSVから業務アプリ定義(resource.yaml)を生成する
• TAK-134: 取込結果の差分確認・マッピング・承認画面を実装する

Linear attachments¶

• [TAK-192] Excel参照候補・AI関係種別推奨・サブテーブル取込に対応

Linear comments¶

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-19T02:51:25.558Z)¶

PR #118 を develop へ squash merge しました。

Merge commit: 8529e854307ef39282fc2ec7fad29d432615a6b2
確認:

• PR #118: merged=true
• local develop / origin/develop: 63f1a214442d637edfeb1f93b82943d615edc5b5 まで更新済み
• reports/ 混入なし

注意:

• その後、残PR #113 も develop へmerge済みのため、最終的なdevelop先端は 63f1a214442d637edfeb1f93b82943d615edc5b5 です。

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

追加修正を実施しました。

原因:

• customer_code -> customers が vlookup と value_overlap の2候補として重複し、曖昧扱いになって自動採用されていませんでした。
• そのため確認画面では customer_code / text のまま見えていました。
• さらに起動中の旧 GUI プロセスが publish 成果物をロックしており、更新版が反映されていませんでした。

対応:

• 同一参照候補は value_overlap を補助候補として集約し、明示的な vlookup を優先するよう修正。
• 確認画面で customer_code 由来の参照が customer_id / relation / autocomplete になる回帰テストを追加。
• GUI を再 publish / 再起動済み。

検証:

• dotnet test C:\project\EPAA\tests\generator-gui\EPAA.Generator.Gui.Tests.csproj --filter "ExcelImportServiceTests|ExcelImportReferenceModeSuggestionServiceTests" OK: 35/35
• dotnet test C:\project\EPAA\tests\generator-gui\EPAA.Generator.Gui.Tests.csproj OK: 93/93
• powershell -ExecutionPolicy Bypass -File C:\project\EPAA\publish-generator-gui.ps1 OK

コミット: 1414c93b TAK-192 collapse duplicate excel reference candidates

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-19T01:27:36.428Z)¶

追加補正を push しました（commit a8305bb）。

• AI関係種別推奨から % / 0.7閾値を削除し、relation / subtable と理由だけに整理
• relation/subtable採用時、確認画面の列を customer_id / order_id のような *_id、型 relation、UI autocomplete として同期
• 曖昧候補はAI推奨を表示しても 未採用 と明示
• CSV/YAML/initial-data-manifestで <relation_field>__code と採用済みrelation項目が一致するよう補正

確認:

• Generator GUI対象テスト 34/34 成功
• Generator GUI全体テスト 92/92 成功
• Generator GUI frontend build 成功（既存の500KB超チャンク警告のみ）
• docs再生成 成功
• publish-generator-gui 成功（C#警告0/エラー0）

注意事項: dev.epaa.jp反映は不要（Generator GUIのExcel取込確認画面・ローカルGUI成果物の変更で、DB/OpenAPI/生成済みサンプル定義変更なし）。

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-19T00:37:18.801Z)¶

AI関係種別推奨 追加実装: レビュー待ち¶

• Gemini 2.5が解決済みクロスシート候補を別アプリ（relation）／サブテーブル（subtable）として推奨
• 0.7未満、解析打切り、曖昧候補、参照先キー非完全一意、同一シートsubtableは自動適用しない
• AI推奨・信頼度・理由を確認画面へ表示し、利用者が最終変更可能
• APIキー由来・scope・削除、AI設定の既定値復帰をGUI管理可能にした
• 実Gemini: 顧客=別アプリ90%、受注明細=サブテーブル90%
• Generator GUI 93/93、publish成功、5002 matrix 125/125、browser smoke 7画面、Reviewer最終OK
• commit: b8074d97
• PR #118本文・タイトル更新済み。merge先はdevelop

注意事項: 今回の追加はGenerator GUI変更で、DB/OpenAPI/テーブル定義/devサンプルデータ変更なし。dev再反映は未実施。Geminiの非決定性とprompt injectionはC#安全ゲートと利用者確認で補う。PR merge待ちのためIn Reviewを維持する。

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

AI relation / subtable推奨 設計チェックポイント¶

• ユーザー確認により、AI対象をrelationとsubtableの推奨だけに限定。normal/optionは現行C#判定を維持
• 要件・設計レビュー: 最終 OK、Findingsなし
• C#安全ゲート: 別sheet・参照先解決済み・全行解析・target key完全一意・AI信頼度0.7以上。曖昧候補は表示のみ
• AI送信: 関係判定は統計のみ。既存名称補正の最大3サンプル/20選択肢とはGUI上で分離表示
• GUI管理: APIキー登録/置換/削除、project AI設定の保存/既定へ戻すを追加
• 実装先: 現在のbranchとdraft PR #118を更新。DB/OpenAPI/auth/runtime/metadata形式は変更なし
• 現在: 実装計画のユーザー承認待ち

{"id" => "9aded6b7-dac6-4cf8-920a-d263232a992d", "name" => "Takayuki Komoda"} (2026-07-18T18:07:25.549Z)¶

dev反映・最終確認¶

• アプリ: https://dev.epaa.jp/excel-demo-orders （Excel受注）
• 適用バージョン: 0.0.6
• サンプルデータ: 受注3件 / 受注明細6件 / 親参照解決6件
• 取込用Excel: C:\project\EPAA\reports\2026-07-18-excel-subtable-dev-sample\証跡\excel-demo-orders-subtable.xlsx
• PR: https://github.com/takataka328-max/EPAA/pull/118 （draft、merge先はdevelop）

確認結果¶

• Generator GUI 74/74、Generator 28/28、Fixed backend 75/75
• 5002: 設定Error 0、matrix 125/0/0、browser smoke 7画面
• Excel初期データ: preview 9件、commit 200、親3件・子6件
• 0.0.6: inspect 200、apply 201、verification 14/14、current version 0.0.6
• 大小文字だけ異なる受注番号の重複拒否、複合FKのCASCADE、異なるメールアドレスのユーザー作成201/削除204を確認
• dev画面で一覧3件、詳細のLINE-001 / LINE-002を確認
• 適用後journal error 0
• Reviewer最終結果: OK、重要なFindingsなし、Return To none

注意事項¶

• 0.0.6は不可逆パッケージ。適用前DB backupから復旧可能。
• 外部workbook自動取得、INDIRECT/OFFSET自動解決、複雑式の完全変換は対象外。
• generated app seedは現行リリースZIP外のため、新規サンプル反映時は正式生成物を別途適用する。
• FixedBackend / Generated.Abstractions hash差はTAK-131の既知warning。
• follow-up候補の自動登録はしていません。状態はIn Reviewのままです。

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

PR #118 を作成し、最終Reviewerは OK / Findingsなしです。

• Generator GUIテスト: 65/65
• 実WebView2: 候補表示、subtable、通常項目への解除、relation編集、登録準備、自己subtable disabledを確認
• 5002: settings Error 0、matrix 125/125、browser smoke 7画面
• PR: https://github.com/takataka328-max/EPAA/pull/118
• マージ先: develop

注意事項:

• dev.epaa.jpはデスクトップGenerator GUI変更のため未反映です。
• DB/OpenAPI/認可/既存テーブル定義変更なし、サンプルデータ投入なしです。
• 外部workbook、INDIRECT/OFFSET、複雑式の完全変換は対象外です。
• このworkbook由来の生成metadataを5002へ反映してCSV preview/commitする実環境確認は未実施で、metadata/CSV構造は自動テストで検証しています。
• 実業務Excelを増やした拡張回帰はfollow-up候補ですが、新規issueは作成していません。
• PR作成時点ではDoneにせずIn Reviewを維持します。