AIインポート：列を1つずつ確認する取り込みフロー 実装解説

在庫データを 新規/既存ワークスペースに丸ごと取り込む（オンボーディング・移行）体験の作り直し。

困りごと： 旧フローは「対応表でまとめて聞く」形。列が多いと分かりにくく、特に新規WSでは AI が属性提案を出し切れず、データのある列が無言で ignore に落ちて消える（実例: 40列中20列消失）。

方針： STEP2(列選択)/STEP3(新規属性登録) を「列を1つずつ確認する会話」に一本化。明確な列は自動確定、迷う列だけ1問ずつ。整形もその場で。原則は「AI は理解・提案・リコメンド、確定・適用・最終防衛は決定的コード」。

テンプレートに合わない CSV/Excel を「一括登録」に入れると、シート本体が AiImportThread（会話スレッド）に切り替わる。各ステップに裏で動く関数を併記する。

buildColumnPlans()（src/services/aiImport/columnDecision.ts・純関数）が各列を ColumnKind に分類する。自動確定は控えめに倒す（意図どおりを優先）。

// 分類ルール（優先順）
priceColumns に含む            → 'price'   // 最優先・ignore マッピングでも質問に出す
target ∈ {itemName,stock,nancoId,folder} → 'auto'   // システム列
attributeProposals に提案あり   → 'newAttr'
rescueNeeded に含む（型不一致）  → 'rescue'
既存名一致 && 整形不要 && confidence≥0.7 → 'auto'
それ以外                        → 'ambiguous'
target==='ignore'              → 除外（質問にも出さない）

UI 側（ColumnQuestionView）は kind で質問を出し分け、回答を既存ストアへ書く：

進行管理は useColumnFlow reducer が {plans, queue, mode, cursor, capPrompted} だけを所有し、nextFlowStep(state) が「次に質問/キャップ/レビュー」を導出する純関数。回答データ自体は持たない（reducer は進行のみ・単方向）。COLUMN_FLOW_CAP=5。

AI が出すのは 提案つきの構造化データだけ。それを決定的コードが矯正・救済し、全行適用と最終検証もコードが行う。

AI 出力（AnalyzeResult・zodTextFormat strict）

{
  columnMapping:  []  // 列→target(itemName/stock/nancoId/folder/attribute/ignore)+confidence
  attributeProposals: []  // 新規属性の型付き提案（priceは含めない）
  priceColumns:   []  // 価格列＋suggestedRole(selling/purchase/null)
  transformRules: []  // nfkc/extractNumber/...（カタログのみ）
  confirmations:  []  summary  warnings
}

strict mode は z.record() 非対応 → 表記ゆれ統合は {from,to}[] 配列で表現。store:false 厳守（OpenAI 側に残さない＝委託の扱い）。

決定的コードの矯正（sanitizeAnalyzeResult）

src/services/aiImport/contract.ts。AI 出力を信頼する前に意味的に矯正する“防波堤”：

• 範囲外 sourceIndex・架空の attributeName を除去（→ warnings）
• 救済(S1)： 未登録の attribute 列を columnStats.guessedType から型推定し新規提案に変換（黙って ignore に落とさない）
• nancoID ガード：nanco 発番形式でない管理番号を nancoID 扱いしない（降格して属性化）
• 価格列を attributeProposals から分離（二重 UI 防止）
• フォルダ降格(S4)： folderPlan.demoteColumns を検証つきで folder→attribute 提案に変換（フォルダ列のみ・20字以内・既存衝突はフォルダのまま）
• 説明メモ正規化(S5)： attributeProposals[].description を trim/2000字/空→null に正規化（normalizeProposalDescription）
• PII 列マーク(TM)： piiColumns を範囲検証・dedup。テレメトリ送信時のマスク対象に使う（AI∪ヒューリスティック）

AI決定的コード

温存設計が肝。 回答は attrDecisions/overrides/priceDecisions/rejectedTransforms の4ストアに書き、effectiveResult useMemo が最終 columnMapping を一方向に導出。S2b/S3 の改修でもこの導出（effectiveResult→rescue→trial→handleProceed）と MappingPanel は触らず、置き換えたのは「質問オーケストレーション」だけ。これで巨大ファイル改修の回帰リスクを最小化している。

計画の依存順 S1 → S2 → {S3 / S4 / S5 / TM} → S6 どおりに実装。全スライスがコミット済み（未 push）。

設計原典：~/.claude/plans/ai-import-column-chat-flow.md（仕様）／ai-import-implementation-plan.md（15エージェントのワークフローで精査）。各スライス後に type-check / unit / lint / 実機E2E。E2E は webpack dev（turbopack の next/font バグ回避）＋ claude-in-chrome で実施。S4/S6/レビュー修正は /code-review（codex＋多観点）で本物のバグを捕捉→修正→ライブ確証する運用を徹底した。

1問1問で決めたことを永続化し、会社ごと・形式ごとに学習を貯める。grill-with-docs と同じ思想＝やり取りが「会社の取り込みナレッジ」を育てる。2層に分ける。

B層：形式別 decision（速い再利用キャッシュ）

取り込み確定時に「列の対応・整形・属性/価格の決定」をルールとして保存し、次回同じ形式を1クリック再利用する。実装の核は次の4つ。

① 形式の照合キー＝列名集合の重なり率（実装済み）

djb2 ハッシュ（厳密一致）では列の増減・並び替えで別物になる。そこで順序非依存の集合＋重なり率に変えた（headerFingerprint.ts）。

normalizeHeaderTokens(headers): string[]   // NFC正規化・空除去・dedup・昇順
headerSetOverlap(a, b) = |A∩B| / max(|A|,|B|)
HEADER_OVERLAP_THRESHOLD = 0.8            // 列1つ増減程度なら「同じ系」

確認(③)を安全網にするので、攻めに拾って再利用ヒット率を上げる。

② 永続化スキーマ＝ルールのみ（実装済み）

ReuseDecisions（contract.ts）。列は sourceIndex でなく「正規化した見出し名」をキーにする（並び替え・列増減があっても新データに当てられる）。行の値は一切持たない。

ReuseDecisions = {
  version: 1, mode, headerTokens: string[],       // ↑照合キー
  columns:    [{ header, target, attributeName }] // 見出し名→対応先
  attributes: [{ name, type, options }]           // 作る新規属性（optionsは定義・行値ではない）
  transforms: [{ header, kind }]                  // 適用した整形
  prices:     [{ header, role }]                  // 価格ロール割当
}

組み立ては buildReuseDecisions()（純関数）。確定状態（effectiveResult の columnMapping・採用属性・効く整形・価格ロール）を見出し名キーに変換するだけで、rawBody（行の値）を一切参照しない。ユニットテストで「シリアライズに値が混入しない・キーは7つのみ」を assert。

③ 置き場＝ImportSessionDB（db:push 不要）

既存の ImportSessionDB が status（draft/awaiting_confirm/committed/…）と decisions:Json を既に持つ。S6 はスキーマ変更なしで、確定時に status='committed' ＋ decisions.reuse = ReuseDecisions を書く（manifest に作成した attributeTypeIds も）。

④ 照合・適用・フォールバック（実装済み）

1. lookup：解析前に (companyId, mode) の committed セッションを引き、headerSetOverlap(新, 各) が閾値以上で最大のものを選ぶ（LLM 非呼び出し＝速い・無料）。
2. 提示（確認1クリック）：「前回この形式はこう取り込みました。同じでいいですか？」＋ピル [同じでいく / 見直す]（AiImportThread reusePrompt）。将来 信頼した形式を確認なしで自動適用する「卒業」フラグは v1 では未実装（ReuseDecisions に該当フラグ無し）。
3. 適用：applyReuseDecisions が見出し名で新データの列にマッピングを当て、AnalyzeResult 相当を作る。
4. フォールバック：applyReuseDecisions が新データに当てられない場合（前回に無い列がある／itemName が対応しない）は {ok:false, reason} を返し、確認ピルを出さずそのまま通常の AI 解析へ落ちる（「いつもの形式と違うようなので、AI が内容を読み取ります」）。lookup の例外も同様にAI解析へ。再利用が成立した側でも、整形要否/選択肢追加/文字化け等のデータ整合チェックは導出パイプライン（rescue/trial）で常に走り、checkCsvHeader 失敗は最終レビューで trial.error として表示される（専用の「読み取り直します」メッセージや自動再解析は無い）。

mode 非依存に作るので、入荷/出荷の AI 化時もそのまま効く。出荷の Amazon/楽天/顧客別フォーマットも headerTokens の重なりで自然に分かれる。

A層：属性の意味メモ（description・実装済み・DB反映済）

「この属性は何か」を会社の辞書として持つ。B層が「列→属性の変換」を再現するのに対し、A層は「その属性が何か」を説明する＝別レイヤーで衝突しない。

1. ItemAttributeTypeDB.description 列を追加（nullable・@db.Text・details JSON でなく独立 top-level カラム）。schema.test.prisma は pnpm gen:test-schema で自動生成（手編集禁止）。本番 DB 反映済み。
2. 新規属性を作るとき、AI が列名＋サンプル＋やり取りから説明文を自動下書きして保存（ユーザーはゼロ手間）。例「売価に使う数値。1点あたりの販売単価」。設定/最終レビューで編集可（空→null 正規化）。
3. buildCompanyBlock が description を AI 解析プロンプトに同梱 → 次回以降のマッピング精度が上がる。将来は値の自動補完/算出（登録日＋ルール→賞味期限 等）の素地にも。

AI 解析の精度や離脱を測りたいが、顧客の生データ（氏名・取引先・電話・住所…）を貯めないことが最優先。2層に分けてマスク前提で記録する。

マスクの仕組み（maskTelemetry.ts・サーバー専用）

• detectPiiColumnsHeuristic：氏名/担当/取引先/電話/メール/住所ヘッダー＋「高充填でほぼ一意の text 列」を PII 判定。迷ったら伏せる側に倒す。
• resolvePiiColumns ＝ AI 提案(piiColumns) ∪ ヒューリスティック。どちらかが疑えばマスク。
• maskTelemetryValue：# ＋ sha256 hex 先頭12桁（`#${h}`・決定的・復元不可）。PII 列のみマスクし、型・分布は残す。
• 記録は recordAnalyzeTelemetry/recordCommitTelemetry（append-only・opt-out ガード・例外は握り潰し＝本処理を絶対に止めない・DI）。

opt-out は CompanyDB.aiTelemetryOptOut＋settings API（v1 は UI スイッチ無し）。自動削除は cloudflare/import-telemetry-cleanup（cron 23 4 * * *・90日超を1000件バッチ削除）。設計簡素化として、クライアント会話ログ専用 API は作らず commitHandler でサーバー記録に寄せた。

コードは全スライス完成・コミット済み。ここから先は DB 反映 → worker デプロイ → push/MR という手作業（多くはユーザー操作）。

1. TM の DB 反映： ブランチで pnpm run db:push → PlanetScale Deploy Request → 通過後マージ。S5(description) は反映済みなので、差分は ImportTelemetryDB ＋ CompanyDB.aiTelemetryOptOut のみ。P2022 回避に順序厳守。
2. Cloudflare worker デプロイ： cd cloudflare/import-telemetry-cleanup && npm install && npm run deploy:stg（本番は deploy:prd）＋ wrangler secret put DATABASE_URL（各環境）。
3. push / MR： GitLab・Target は staging。push・MR はユーザー実施。
4. 任意 E2E（DB 反映後）： S5 説明の自動下書き／TM の PII マスク・opt-out 確認／S4 Branch B（全部フォルダ＝revert・LLM 変動で未ライブ）。

既知の弱点（コードでなく AI 出力品質）

• 価格検知のプロンプト品質： 実機で AI が 単価 を priceColumns に入れず無視する例あり（原価 は検知）。お金の列を漏れなく拾うにはプロンプト強化の余地。
• showPrice=false の価格ブロック： ロジック実装済みだが権限なしアカウントでの実機は未確認。

現状は CSV/Excel 前提。だが現場の主流は「箱に入った納品書・出荷表を、フォーマットがバラバラのままスキャン／写真／PDF で投げる」になる見込み。今の構成で耐えるかを実コードで監査した結論を残す。

結論：テーブル前提は“境界の下”に閉じており、vision は配線済み

下流（正規化テーブル→確認→取込）は入力形式に非依存でそのまま再利用できる（CSV由来か画像由来かを問わない）。AIアダプタも画像入力対応済み（AiImageInput/toOpenAiMessage・既定 gpt-4o）。画像を読ませること自体はほぼ追加コストゼロ。本当の山は次の3点で、「テーブルがガチガチだから無理」という直感はむしろ逆。

データの流れ（伝票インテーク）

AI(vision)決定的コード（既存資産）

既存資産で“そのまま使える”もの（監査で確認）

• 伝票の文書フィールド認識：taskDetailCsvParser が既に 取引先/入荷番号・出荷番号/入荷日・出荷日/アイテム名 を解釈（HEADER_CLIENT ほか）。
• 取引先名→clientId 解決：clientImportUtils.resolveImportClient / resolveNewClientsByName（取込時に再検索・既存再利用で二重作成防止）。
• 新規アイテム作成：createImportItemsForNewRows（name/folderPath/attributeCells → itemId マップ）。
• 価格ロール：useImportAttributePricing（入荷 PURCHASE / 出荷 SELLING）。
• タスク永続化：ShippingTaskDB（clientId＋キャッシュ・shipmentNumber・targetAt）＋ tradeTaskCreateSchema。
• vision 土台：AiImageInput / OpenAiClient.toOpenAiMessage（画像→content配列・テスト済み）。
• 画像取り込み基盤：カメラ/スキャン→Firebase Storage（image_repository / SingleImageUpload）。

スライス分解（詳細は plan ドキュメント）

推奨順序：G0（保険・小）→ G1（本丸・大）→ G2 → G3 → G4。vision(G3) は最小、本丸は G1。詳細計画：~/.claude/plans/ai-import-document-intake.md。