NexusCore 初回導入フロー設計書

Single Source of Truth for Onboarding Experience

本ドキュメントは、NexusCore の初回導入体験（オンボーディングフロー）の設計資産として固定する。 UI・実装・LP・デモ・価格設計の参照元として機能する。

1. 目的

1.1 なぜこの初回導入フローが必要か

初回導入フローは、ユーザーが本プロダクトの価値を最初の1回の操作で理解できるように設計する。

従来のデータ分析ツールは、データの前処理・形式整備・集計結果の解釈に時間を要し、初回利用時に「何ができるのか」を判断するまでに複数のステップを要する。本フローは、CSV1枚のアップロードから「この数字は説明に使えるか」という判断までを最短経路で提供する。

1.2 この体験でユーザーに何を理解させるか

ユーザーは以下の3点を理解する：

  1. 説明責任の履行可能性: アップロードしたデータから、説明に使える数値が得られるかどうかを判断できる
  2. リスクの可視化: データの不完全性や形式不正が、説明不能リスクとして提示される
  3. 次の行動の明確化: 修正を強制せず、ユーザーが選択できる次の行動（再アップロード・詳細確認・集計結果の利用）が提示される

2. 想定ユーザー

2.1 ユーザー像

本フローは、以下の担当者を想定する：

  • 月次収支データの説明責任を負う担当者
  • 契約・取引データの説明責任を負う担当者
  • 経営層や外部ステークホルダーに対して数値の根拠を説明する必要がある担当者

2.2 ユーザーの役割

重要: ユーザーは「修正者」ではなく「説明者」である。

  • データの修正・前処理を行うことが主目的ではない
  • 既存のデータ（CSV）から説明に使える数値を得ることが主目的である
  • データの不完全性があっても、そのリスクを認識した上で説明に使うかどうかを判断する権限を持つ

3. フロー概要（全体像）

初回導入フローは、以下の8ステップで構成される：

  • Step 0: 入口メッセージ（期待値固定）
  • Step 1: CSVアップロード
  • Step 2: 自動判定（内部処理）
  • Step 3: 判断サマリー表示
  • Step 4: 警告理由の提示（warning_flags翻訳）
  • Step 5: raw / context 内訳提示
  • Step 6: 集計結果表示
  • Step 7: 次の行動選択

各ステップは、前のステップの結果を受けて進行する。ユーザーは任意のステップで中断・再開できる。

4. 各ステップの詳細

Step 0: 入口メッセージ（期待値固定）

表示内容:

  • 「CSVファイルをアップロードしてください。データの形式や列の不足があっても、警告として提示されます。エラーで停止することはありません。」
  • 「アップロード後、このデータが説明に使えるかどうかを判断するための情報が表示されます。」

表示理由:

  • ユーザーが「形式不正でエラーになるのではないか」という不安を解消する
  • 「説明に使えるか」という判断が主目的であることを明示する

禁止事項:

  • 「使いやすい」「簡単」などの抽象表現は使用しない
  • 画面の装飾やUI要素の説明は行わない

Step 1: CSVアップロード

表示内容:

  • ファイル選択UI（ドラッグ&ドロップまたはファイル選択ダイアログ）
  • アップロード中の状態表示（進行状況は表示しない。内部処理中であることのみ表示）

処理内容:

  • CSVファイルをサーバーにアップロード
  • ファイルの存在確認と読み込み可能性の確認
  • ファイルサイズの上限チェック（技術的制約のみ）

エラー処理:

  • ファイルが存在しない、読み込み不可能、サイズ超過の場合はエラーとして停止する
  • それ以外（列不足・形式不正・データ型不一致など）はエラーにせず、Step 2 に進む

Step 2: 自動判定（内部処理）

処理内容:

  • CSVのパース（文字エンコーディングの自動検出を含む）
  • 列の存在確認（期待される列の有無を判定）
  • データ型の検証（数値列が数値として解釈可能か、日付列が日付として解釈可能か）
  • 欠損値の検出
  • 異常値の検出（統計的外れ値の判定は行わない。明らかな形式不正のみ）

出力:

  • warning_flags: 検出された問題の種類と位置（列名・行番号）
  • raw_data_summary: 生データの行数・列数・データ型
  • context_data_summary: 集計可能なデータの行数・列数（欠損値・異常値を除外した後の状態）

ユーザーへの表示:

  • このステップは内部処理のため、ユーザーには進行状況のみ表示する
  • 「データを分析中です」というメッセージを表示する

Step 3: 判断サマリー表示

表示内容:

  • 判断結果: 「説明に使える」/「条件付きで使える」/「説明不能リスクあり」
  • 判断理由: 1行で理由を提示（例：「必須列が不足しています」「日付形式が不正な行が3件あります」）

表示順序:

  • 判断結果を最初に表示する（結果より理由を先に出す原則に従う）
  • 判断理由を次に表示する

判断基準:

  • 「説明に使える」: 必須列が存在し、データ型が正しく、欠損値が許容範囲内
  • 「条件付きで使える」: 必須列は存在するが、一部の行で形式不正や欠損値がある
  • 「説明不能リスクあり」: 必須列が不足している、またはデータ型が正しくない行が多数存在する

禁止事項:

  • 「エラー」という表現は使用しない
  • 「修正が必要」という表現は使用しない（修正を強制しない原則）

Step 4: 警告理由の提示（warning_flags翻訳）

表示内容:

  • 検出された問題の種類ごとに、以下の情報を表示する：
    • 問題の種類: 「列不足」「形式不正」「欠損値」「異常値」など
    • 影響範囲: 該当する行数・列名
    • 説明責任への影響: 「この問題があると、説明時に以下のリスクがあります」という説明

表示形式:

  • リスト形式で、問題の種類ごとにグループ化する
  • 各項目は読み上げ可能な文章で記述する（例：「日付列 ‘date’ が不正な形式の行が3件あります。これらの行は集計から除外されます。」）

表示順序:

  • 説明責任への影響が大きい順に表示する（列不足 > 形式不正 > 欠損値 > 異常値）

禁止事項:

  • 技術的なエラーメッセージをそのまま表示しない
  • 「エラーコード」「例外名」などの実装依存の情報は表示しない

Step 5: raw / context 内訳提示

表示内容:

  • raw_data_summary: アップロードされた生データの状態
    • 行数・列数
    • 各列のデータ型
    • 各列の欠損値数
  • context_data_summary: 集計に使用されるデータの状態
    • 行数・列数（欠損値・異常値を除外した後の状態）
    • 各列のデータ型
    • 除外された行数と理由

表示理由:

  • ユーザーが「どのデータが集計に使われたか」を理解できるようにする
  • 「生データと集計データの差分」を明示することで、説明責任の範囲を明確にする

表示形式:

  • テーブル形式で、raw と context を並列表示する
  • 差分（除外された行数）を強調表示する

Step 6: 集計結果表示

表示内容:

  • 集計可能なデータに基づいた集計結果（合計・平均・最大・最小など）
  • 集計に使用されたデータの行数・列数
  • 集計結果の信頼性指標（欠損値の割合、異常値の割合など）

表示理由:

  • ユーザーが「この数値を説明に使えるか」を判断するための情報を提供する
  • 集計結果そのものが目的ではなく、「説明に使えるか」の判断材料として提示する

表示順序:

  • 集計結果の前に、集計に使用されたデータの状態（Step 5 の context_data_summary）を再表示する
  • 集計結果の後に、信頼性指標を表示する

禁止事項:

  • 「正しい結果」「正確な結果」などの表現は使用しない（データの不完全性を前提とする）

Step 7: 次の行動選択

表示内容:

  • ユーザーが選択できる次の行動を提示する：
    • 再アップロード: データを修正して再アップロードする
    • 詳細確認: 警告の詳細や除外された行の詳細を確認する
    • 集計結果の利用: 現在の集計結果をそのまま利用する（説明に使う）

表示理由:

  • ユーザーに選択権を与える（修正を強制しない原則）
  • 次の行動が明確になることで、フローの完了感を提供する

表示形式:

  • 各行動をボタンまたはリンクとして表示する
  • 各行動の説明を1行で記述する（例：「データを修正して再アップロードする」「警告の詳細を確認する」「現在の集計結果を利用する」）

禁止事項:

  • 「推奨」「おすすめ」などの誘導表現は使用しない
  • デフォルトの選択肢を設定しない（ユーザーの判断に委ねる）

5. 設計原則（必須）

5.1 結果より理由を先に出す

集計結果を表示する前に、必ず以下の順序で情報を提示する：

  1. 判断サマリー（説明に使えるかどうか）
  2. 警告理由（問題の種類と影響範囲）
  3. raw / context 内訳（どのデータが使われたか）
  4. 集計結果（数値そのもの）

この順序により、ユーザーは「数値の信頼性」を理解した上で集計結果を判断できる。

5.2 修正を強制しない

データの不完全性や形式不正があっても、ユーザーに修正を強制しない。

  • エラーで停止しない（警告として提示する）
  • 「修正が必要」という表現は使用しない
  • 修正を促すボタンやリンクを強調表示しない

ユーザーは、警告を理解した上で「このまま説明に使う」か「修正して再アップロードする」かを選択できる。

5.3 エラーではなく説明不能リスクとして提示する

データの問題は「エラー」ではなく「説明不能リスク」として提示する。

  • 「エラー」という表現は使用しない
  • 「この問題があると、説明時に以下のリスクがあります」という形式で提示する
  • リスクの内容を具体的に記述する（例：「日付が不正な行があると、時系列の説明ができません」）

5.4 読み上げ可能な文章を優先する

すべてのメッセージは、読み上げ可能な文章で記述する。

  • 技術的なエラーメッセージをそのまま表示しない
  • 略語や専門用語は避ける（使用する場合は説明を付ける）
  • 文章は簡潔で明確にする（1文は50文字以内を目安とする）

6. 他ドキュメントとの関係

6.1 ARCHITECTURE.md との役割分担

  • ARCHITECTURE.md: アーキテクチャ情報の参照ゲート（Gate / SSOT Entrypoint）
  • 本ドキュメント: 初回導入体験の設計資産（UI・実装・LP・デモ・価格設計の参照元）

本ドキュメントは、ARCHITECTURE.md の「Gate」を通過した後に参照される設計ドキュメントである。実装詳細やAPI仕様は ARCHITECTURE.md が参照する Canonical Architecture に記載され、本ドキュメントには含めない。

6.2 価格ページ・デモ動画との関係

  • 価格ページ: 本ドキュメントの「Step 0: 入口メッセージ」の内容を参照する
  • デモ動画: 本ドキュメントの「Step 1 〜 Step 7」の順序と内容を参照する

価格ページやデモ動画の制作時は、本ドキュメントの内容に従い、ユーザーに提示する情報の順序と内容を統一する。

6.3 実装仕様との関係

本ドキュメントは「何を表示するか」「なぜその順か」を定義するが、「どのように実装するか」は定義しない。

実装仕様（APIエンドポイント・データベーススキーマ・UIコンポーネントなど）は、ARCHITECTURE.md が参照する Canonical Architecture に記載される。

7. 変更ポリシー

本ドキュメントは、初回導入体験の設計資産として固定する。

  • 変更の要否: 初回導入体験の設計が変更された場合のみ更新する
  • 変更の手順:
    1. 本ドキュメントを更新
    2. 関連する実装・UI・LP・デモ・価格ページを更新
    3. Decision Log に記録（変更理由と影響範囲を明記）

End of Onboarding Flow Design Document.

This site uses Just the Docs, a documentation theme for Jekyll.