Linear migration metadata¶

• Linear issue: TAK-213
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-213/excel単一シートから台帳明細マスタ候補を分割生成する
• Linear status: Done
• Linear team: Takayuki Komoda
• Linear project: EPAA App
• Linear assignee: Takayuki Komoda
• Linear labels:
• Linear created: 2026-07-18T22:39:30.207Z
• Linear updated: 2026-07-19T23:53:13.986Z
• Linear archived:

Original description¶

背景¶

実運用のExcelでは、台帳項目、明細項目、商品などのマスタ項目が1シートの各行に重複して保持されていることが多い。現行のExcel取込は原則として1シートを1リソースとして解析し、複数シート間のrelation／subtable候補を扱うため、1シート内の非正規化データを複数リソースへ分割できない。

目的¶

1シートのExcelを、台帳、明細、参照マスタへ安全に分割する候補を提示し、利用者の確認後に既存の複数シート取込処理へ接続できるようにする。

方針¶

• C#で列統計、候補キー、functional dependency、値の反復性、一意性、競合を決定論的に解析する。
• AIはテーブル名、列の所属先、関係種別、判断理由、曖昧候補の順位を補助する。
• AIへExcel全体を丸投げせず、C#が作成した構造化要約だけを渡す。
• GUIで仮想的な台帳・明細・マスタをタブ表示し、キー、列所属、親子／参照関係を利用者が修正・承認する。
• 承認後に分割済みExcelまたはmanifest付きCSV ZIPを生成し、既存の複数シート取込、YAML生成、preview／commit経路を再利用する。
• AI応答からYAMLやデータを直接反映しない。

対象¶

• 親キーごとに一定の列を台帳候補として抽出する。
• 親キー内で変化する列を明細候補として抽出する。
• 商品コードなどの候補キーに対して属性が一意な列をマスタ候補として抽出する。
• 同じコードに複数の名称・価格などがある場合は競合として表示し、自動マスタ化しない。
• 元Excel行と分割後データの対応を保持し、エラーを元行番号へ関連付ける。
• 分割候補、除外列、重複排除、スナップショット列／マスタ列を確認・編集できるGUIを提供する。

非対象¶

• 利用者確認なしの完全自動正規化。
• Excel上の集計行、小計行、複雑な結合セル、複数ヘッダーを初回から完全自動解決すること。
• 既存本番データの自動移行。

受入条件¶

• 受注台帳・受注明細・商品情報を1シートに持つ固定fixtureから、受注、受注明細、商品マスタの3候補を表示できる。
• 受注番号ごとに一定の列が台帳へ1件ずつ重複排除される。
• 明細行は元の行順と親キーを維持する。
• 商品コードごとに属性が一意なら商品マスタへ重複排除できる。
• 商品属性が競合する場合は元行番号と競合値を表示し、承認前に解決を要求する。
• 利用者が列所属や関係を変更した場合、変更後の分割結果を再プレビューできる。
• 分割済みExcelまたはCSV ZIPを生成し、既存の複数シート取込経路でmetadataと初期データ候補を作成できる。
• 最終承認前にYAMLとDBへ反映されない。

関連¶

• TAK-132: Excel/CSVから業務アプリ定義を生成する
• TAK-192: 複数シート間の参照マスタ／サブテーブル候補
• TAK-134: 取込結果の差分確認・マッピング・承認画面

Linear attachments¶

• TAK-213 単一シートExcel分割取込を追加

Linear comments¶

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

設計チェックポイント¶

• 設計結果: OK
• レビュー: 初回／再レビューの指摘を修正し、最終 OK（重大な欠落・契約矛盾なし）
• 決定事項: C#決定論解析 + AI補助、GUIの不変 TableId / ColumnId / RowId、materialize時lineage + 最終CSV生成時provenance manifest、nullable uniqueの明細 import_key
• 影響: Generator GUI FE、Excel取込bridge/service/models、xlsx/CSV/manifest生成、tests、WebView2、AsciiDoc。DB/OpenAPI/auth/runtime/既存metadata形式は変更なし
• 実装依存: PR #118がdevelopへmergeされた後、更新済みdevelopからcodex/tak-213-excel-single-sheet-normalizationを作成する
• 現在: ユーザーの設計承認待ち。承認後に実装計画を提示する

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

要件レビュー¶

• 最終結果: OK
• Return To: none
• ローカル要件: reports/2026-07-19-excel-single-sheet-normalization/requirements.md
• Notion: https://app.notion.com/p/3a18d886122a8180b519c887afa5710a

確定したMVP境界¶

• 単一親キー、単一マスタキー、親キー＋任意の単一明細キー
• Trim＋NFKC＋英字大小文字非依存でキー比較し、元表記を保持
• 台帳／マスタは重複排除、明細は元行を維持
• FD競合は代表値選択、明細スナップショット移動、マスタ不採用で解消
• 分割済みExcel、metadata候補、CSV ZIP、provenance manifestを同じ仮想分割モデルから生成
• 元Excel行追跡はGenerator GUIとprovenanceファイルで扱い、既存CSV preview UIは変更しない
• TAK-213の正規化AI失敗時はC#候補へフォールバック。既存複数シート名称補正AIの失敗動作は変更しない

設計着手はユーザー要件checkpoint承認待ちです。