Linear migration metadata¶

• Linear issue: TAK-195
• Linear URL: https://linear.app/takayuki-komoda/issue/TAK-195/tak-192-a-csv取込前提とexcel整数idの扱いを検証設計する
• Linear status: Done
• Linear team: Takayuki Komoda
• Linear project: EPAA App
• Linear assignee: Takayuki Komoda
• Linear labels:
• Linear created: 2026-07-12T21:49:22.405Z
• Linear updated: 2026-07-12T23:11:17.850Z
• Linear archived:

---

Original description¶

目的¶

TAK-192の参照マスタ自動生成に入る前に、生成アプリのCSV import前提とExcel上の整数ID列の扱いを確定する。

対応内容¶

• 生成アプリCSV importで、新規行のDB id がCSVに不要でSerial/BIGSERIALにより自動採番されることを確認・テスト化する。
• relation項目が xxx_id__code 形式で参照先の code_field から解決できることを確認・テスト化する。
• Excel上にもともと整数IDが振られている場合、その列を参照マスタのID候補として扱えるようにする。
• Excel整数IDをDB主キー id として直接投入する方式と、元ID/業務キー列として保持して code_field にする方式の安全性を比較し、TAK-192で採用する方式を決定する。
• 採用方式に応じて、Excel整数IDを親アプリCSVの参照解決キーとして利用できることを受入条件に含める。

受入条件¶

• 新規CSV取込でDB id が自動採番されることがテストで確認できている。
• Excel整数IDを参照先マスタとの照合キーとして利用する仕様が明文化されている。
• DB主キーへ直接投入する場合は、sequence整合性と既存データ衝突の扱いが明確になっている。
• 直接投入しない場合は、Excel整数IDを保持する項目と code_field としての利用方法が明確になっている。

Linear attachments¶

• TAK-195 CSV relation import uses surrogate key lookup

Linear comments¶

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

PR #106 が develop に merge されたことを確認しました。

• merge commit: 1971a189
• local develop も origin/develop に fast-forward 済み
• ローカル作業ツリー clean

TAK-195 は開発作業として完了扱いで、次タスクへ進めます。

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

Draft PR を作成しました。

• PR: https://github.com/takataka328-max/EPAA/pull/106
• target: develop
• branch: codex/tak-195-csv-import-surrogate-keys
• commit: 06587fe

追加で実施した検証

• start-verification-sample.cmd: 成功（5002 / epaa_verify_5002）
• generate-verification-report.ps1: 成功、settings report エラー 0
• run-verification-matrix.ps1: 成功、passed=125 / failed=0 / skipped=0
• run-verification-browser-smoke.ps1: 成功、代表画面スクリーンショット 7 枚作成
• start-generated-sample.cmd: 成功（5001 / epaa）

Linear は Done にはせず、PRレビュー待ちとして扱います。

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

実装・検証メモ

• DB内部主キー id は手動作成・AIアシスト・Excel取込・CSV取込のいずれでも利用者入力にせず、生成アプリ側で自動採番する方針を Generator / GUI / manual に反映。
• Excel の単独 ID 列は source_id 候補へ正規化し、ID・コード・番号系列には通常カラム扱いの警告を出すように変更。
• relation CSV import は xxx_id__code を参照先 code_field で一括解決し、code_field -> id 辞書を行ループ前に構築。行ごとの SELECT は廃止。
• integer code_field は = ANY(@codes)、string code_field は lower(code_field) = ANY(@codes) でまとめて取得。重複コード時は旧実装の ORDER BY id LIMIT 1 に合わせて最小 id 優先。
• 追加検証: tools/EPAA.Generator.Tests/verify-csv-import-surrogate-keys.ps1 を追加し、生成コードが RETURNING "id" で採番 id を使い、relation resolve helper 内で ExecuteScalar しないことを確認。

検証結果

• verify-csv-import-surrogate-keys.ps1: 成功
• verify-relation-multiple-joins.ps1: 成功
• dotnet build .\tools\EPAA.Generator.Gui\EPAA.Generator.Gui.csproj: 成功
• git diff --check: 成功
• build-docs.ps1: 実行したがタイムアウト。対象の docs/manuals/resource-yaml.html には追記反映済み。

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

設計補足¶

この方針はExcel取込限定ではなく、EPAA生成アプリ全体の標準方針として扱う。

• 手動作成、AIアシスト、Excel取込、CSV取込のいずれでも、DB内部主キー id はEPAA/DB側が自動採番する。
• ユーザーが業務上扱うID、コード、番号、外部システムID、Excel由来IDは通常カラムとして定義する。
• AIアシストは id を業務項目として提案しない。仕様やExcelにID列がある場合は source_id, external_id, xxx_code などの通常カラム候補として扱う。
• relationの内部保存値はDBサロゲートキー xxx_id、CSVや外部入力での解決キーは xxx_id__code / code_field とする。

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

設計チェックポイント案¶

採用方針¶

• DB内部主キー id は全テーブルのサロゲートキーとして自動採番する。CSVでは id を発行・指定しない。
• Excel由来の整数IDは、通常カラムとして保持する。例: source_id, external_id, customer_source_id。
• 参照関係はCSV上の業務キー/元IDを xxx_id__code として表現し、import時に参照先の code_field からDB内部の xxx_id へ変換する。
• code_field が整数型の場合も扱えるよう、生成器のCSV relation解決を型-awareにする。文字列は大小文字非依存、整数は数値parse後に等価比較する。

大量行対応¶

• 現行の行ごとSELECT方式は100万行級に不向きなため、relation解決では行単位SELECTを禁止する。
• import開始時にCSV内の distinct xxx_id__code を抽出し、参照先の code_field -> id を一括取得してメモリ辞書で解決する。
• 参照キー数が多い場合はチャンク取得、将来の超大量取込では一時テーブルJOIN/COPY方式へ拡張できる境界にする。
• 親/参照先マスタを先にimportし、子/参照元テーブルを後続でimportする順序をTAK-192の前提仕様にする。

実装設計候補¶

• tools/EPAA.Generator/Backend/BackendSourceWriter.cs
  • CSV import生成処理で、relation fieldごとの一括lookup辞書を作るコードを生成する。
  • Resolve...CsvCode の行単位SELECTを、事前構築辞書の参照へ置き換える。
  • code_field の型に応じて文字列/整数比較を分ける。
• tools/EPAA.Generator.Gui/Services/ExcelImportService.cs
  • ExcelのID/コード/番号系候補はDB主キーではなく通常フィールドとして扱う既存方針を明文化し、必要なら警告文を補強する。
• adoc/manuals/resource-yaml.adoc
  • Excel整数IDはDB id に投入しない、通常カラム/code_field として扱う、relation解決は一括辞書/JOINで行う、という仕様を追記する。
• テスト
  • 新規CSV importでDB id がCSV不要で自動採番されること。
  • xxx_id__code が参照先 code_field から解決されること。
  • 整数型 code_field でも参照解決できること。
  • 生成コードに行単位SELECTが残らないこと、または一括lookup経路が使われること。

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

要求整理メモ¶

CSV import / Excel整数IDの扱いは次の方針で進める。

• 生成アプリDBの内部主キー id は、各テーブルで自動採番されるサロゲートキーとして扱う。
• CSV上ではDB主キー id を発行・指定しない。CSVにはExcel由来ID、コード、番号などの業務キー/元データキーを保持する。
• Excel由来の整数IDは、DB主キーへ直接投入せず、通常カラムとして保持し、必要に応じて code_field に使う。
• 複数テーブルのリレーションは、CSV上の xxx_id__code などのキーをimport時にDB内部の xxx_id へ解決する。
• 100万行級を想定し、参照解決で行ごとのSELECTは禁止する。参照キーは一括取得、メモリ辞書、または一時テーブルJOINで解決する。
• 親/参照先マスタを先に取り込み、子/参照元テーブルを後続で取り込む順序を設計に含める。