id: "01_customer_service_ai" title: "1. 接客対応システム（契約・重説AI＆チャット・ナレッジRAG）仕様" category: "system" packages: - "packages/resident-portal" - "packages/inquiry-service" - "packages/common" cloud_run: - "real-estate-chatbot" - "sorai-customer-portal" - "sorai-inquiry-service" endpoints: - "POST /api/chat" - "GET /api/chat/history" - "POST /api/inquiry/draft" - "POST /api/transfer/generate" - "GET /api/documents/proxy" secrets: - "GEMINI_API_KEY" - "HUBSPOT_ACCESS_TOKEN" - "ENCRYPTION_KEY" - "JWT_SECRET" databases: - "contracts" - "users" - "chat_sessions" - "transfers" - "inquiries"#

1. 接客対応システム（契約・重説AI＆チャット・ナレッジRAG）仕様#

1.1 システム全体構成 (Architecture Overview)#

システム全体構成図 (System Architecture Diagram)#

graph TB
    %% スタイル定義
    classDef client fill:#eef6ff,stroke:#1b2a47,stroke-width:2px,color:#06152b;
    classDef frontend fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#06152b;
    classDef backend fill:#fefce8,stroke:#ca8a04,stroke-width:2px,color:#06152b;
    classDef ai fill:#faf5ff,stroke:#9333ea,stroke-width:2px,color:#06152b;
    classDef data fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#06152b;
    classDef ext fill:#fff1f2,stroke:#e11d48,stroke-width:2px,color:#06152b;

    %% 1. ユーザー接点
    subgraph CH ["① ユーザー接点・顧客チャネル"]
        U_WEB["Webサイト来訪者 (PC/スマホ)"]
        U_LINE["LINE公式 友だち (入居検討・契約者)"]
        U_TEL["AI電話 03-6161-8484 (問合せ・内見)"]
        U_STAFF["不動産オペレーター (HubSpot管理者)"]
    end

    %% 2. フロントエンド & CMS
    subgraph FE ["② フロントエンドおよびCMS基盤"]
        WEB_HP["HubSpot CMS (ソライ東京公式HP)<br/>・5言語ブログ / エリアガイド<br/>・特設LP (プレジオ北綾瀬ASIAN)<br/>・LINE最優先問い合わせフォーム<br/>・初期費用シミュレーター(/quote)"]
        LINE_APP["LINE LIFF アプリ<br/>(契約書閲覧・本人確認・自動ログイン)"]
        HS_CARD["HubSpot UI Extension<br/>(sorai-lease-bot 管理カード)"]
        RES_PORTAL["入居者ポータル (React/Vite)<br/>(重説PDF閲覧・AIチャット)"]
        EST_TOOL["見積書メーカー (Next.js)<br/>(初期費用計算・PDF生成)"]
    end

    %% 3. バックエンド & バッチ
    subgraph BE ["③ バックエンドおよびAPI (Cloud Run)"]
        API_GW["Express.js Monorepo API<br/>・packages/resident-portal (重説API)<br/>・packages/line-bot (LINE制御)<br/>・packages/deal-service (並列OCR図面解析)<br/>・packages/apply-portal (申込API)<br/>・共通認証 / PIIログマスク"]
        BATCH_JOB["Cloud Run Job: sorai-auto-editorial<br/>・日次/週次自律執筆 (15〜20 URL/日)<br/>・重複チェック・5言語自動翻訳<br/>・Push-Live・GSC即時送信"]
        IVR_SVC["AI電話自動応答 IVR (Node.js)<br/>(リアルタイム双方向音声処理)"]
        SPEC_VIEWER["Cloud Run: sorai-system-spec<br/>(仕様書ポータル / OAuth・Basic認証)"]
    end

    %% 4. AI & コグニティブ基盤
    subgraph AI ["④ AIおよびインテリジェンス基盤 (Vertex AI)"]
        LLM_TEXT["Gemini 3.8 Flash<br/>(契約QA・長文執筆・LINE自動応答・5言語翻訳)"]
        LLM_LITE["Gemini 3.5 Flash Lite<br/>(初期費用シミュレーター・超低コスト並列OCR)"]
        LLM_LIVE["Gemini 3.1 Live API<br/>(超低遅延リアルタイム音声対話)"]
        LLM_VISION["Gemini Multimodal Vision<br/>(CAD図面自動クロッピング・OCR)"]
    end

    %% 5. データストア & 外部サービス
    subgraph DATA ["⑤ データストアおよび外部連携"]
        DB_FS["Cloud Firestore (顧客・セッション)"]
        DB_BQ["Google BigQuery (需要ログ・キュー・GA4)"]
        EXT_HS["HubSpot CRM API v3/v4"]
        EXT_LINE["LINE Messaging API Platform"]
        EXT_DRIVE["Google Drive and GCS (PDF・図面)"]
        EXT_GSC["Google Search Console API"]
    end

    %% 接続関係
    U_WEB --> WEB_HP
    U_LINE --> EXT_LINE
    U_TEL --> IVR_SVC
    U_STAFF --> HS_CARD

    WEB_HP -.->|LINE誘導| U_LINE
    EXT_LINE --> API_GW
    LINE_APP --> API_GW
    RES_PORTAL --> API_GW
    HS_CARD --> API_GW

    API_GW --> LLM_TEXT
    API_GW --> LLM_LITE
    API_GW --> LLM_VISION
    IVR_SVC <--> LLM_LIVE
    BATCH_JOB --> LLM_TEXT

    API_GW <--> DB_FS
    API_GW <--> EXT_HS
    API_GW <--> EXT_DRIVE
    BATCH_JOB <--> DB_BQ
    BATCH_JOB --> EXT_HS
    BATCH_JOB --> EXT_GSC

    class U_WEB,U_LINE,U_TEL,U_STAFF client;
    class WEB_HP,LINE_APP,HS_CARD,RES_PORTAL,EST_TOOL frontend;
    class API_GW,BATCH_JOB,IVR_SVC,SPEC_VIEWER backend;
    class LLM_TEXT,LLM_LITE,LLM_LIVE,LLM_VISION ai;
    class DB_FS,DB_BQ data;
    class EXT_HS,EXT_LINE,EXT_DRIVE,EXT_GSC ext;

ディレクトリ構造と主要ファイル#

本システムは npm workspaces を用いたモノレポ構成（real-estate-chatbot）を採用している。

• packages/common/: バックエンド共通ロジック・ミドルウェア
  • config/logger.js: PIIログマスク、GCP構造化ログ設定
  • middleware/auth.js: 各種署名検証 (LINE/Facebook/HubSpot)・JWT認証
  • services/botStatus.js: 有人モード・自動応答判定キャッシュ層
  • services/chatHistory.js: 会話履歴アペンド・上限トリム・Firestore chat_history 同期
  • services/googleChat.js: オペレーター向け Google Chat 通知
  • services/hubspot.js: HubSpot 連携ファサード
  • services/quota.js: チャット利用上限 (顧客別1日50回・グローバル日次100回 checkAndUpdateGlobalQuota) 制御
  • services/security.js: プロンプトインジェクション防御・署名サニタイズ
  • services/knowledgeService.js: 500記事多言語RAG検索基盤
• packages/inquiry-service/: 問い合わせ受付・AIドラフトメール生成サービス
• packages/resident-portal/: Web入居者ポータル (フロント&バックエンドAPI)
• packages/operator-portal/: 有人チャット・オペレーター用管理画面 (フロント&バックエンドAPI)

1.2 主要機能仕様 (Core Functionality)#

1.2.1 入居者ポータル (Resident Portal)#

• 2ペイン構成のUI: 画面左側にはGoogle Driveから動的にストリーミングロードされる契約関連書類（重要事項説明書、紛争防止条例説明書、賃貸住宅契約書）のPDFビューアと、「ご契約概要」を確認できるサブタブを配置。画面右側にはAIへの質問を行えるチャットエリアを配置。
• 契約書類 OCR 結果の Firestore 永続キャッシュ化 (ocr_cache):
  • Google Drive上に保管された重説・契約書等のPDF書類テキスト抽出（pdf-parse / Gemini OCR）結果を、プロセス内メモリキャッシュ（parsedDocsCache）に加えて Cloud Firestore の ocr_cache コレクション（キー: fileId）へ非同期で永続保存。
  • 次回アクセス時やCloud Runインスタンス再起動後も、Google Driveからのバイナリ再ダウンロードおよびGemini OCRの再実行を完全スキップし、Firestoreキャッシュからミリ秒単位で即時応答（0ms/低コスト化）。
• LINE LIFF パスワードレス自動ログイン: LINEアプリ内からLIFFで起動した際、LIFF SDKを介してLINEの「IDトークン」を取得し、バックエンドへ送信。IDトークンをデコードし、取得した line_user_id でHubSpotコンタクトを検索。紐付いている場合は即座に自動ログインを完了する。未連携の場合は、IDトークン内のメールアドレスからコンタクトを検索し、自動で連携処理を行う。
• モバイル表示とソフトウェアキーボード対策: iOS/Androidのソフトウェアキーボード起動時にスクロール領域や入力欄が隠れる現象を防止するため、window.visualViewport の resize および scroll イベントを監視。表示されている実際の高さ（window.visualViewport.height）を動的に算出してCSSカスタムプロパティ --visual-viewport-height にセットし、入力エリアがキーボードの直上に追従するようCSS Flexboxで高さを制限する。

1.2.2 インバウンドAI (Inbound AI)#

• 構造化出力 (Structured Output): Vertex AI SDK を用いた呼び出し時、レスポンスの JSON スキーマを固定指定。回答テキスト（replyText / Markdown形式対応）と、質問カテゴリを分類する意図判定結果（intent / ["screening", "cost", "location", "procedure", "room", "other"]）を一度のAPIコールで同時に構造化取得する。
• マルチAI冗長化 (Failover): プライマリモデル（例: Gemini 3.8 Flash）の呼び出しがAPIリミットやサーバーエラー等で失敗した場合、即座に例外をキャッチし、セカンダリモデル（例: Gemini 3.5 Flash Lite）に自動フォールバックする。
• 1日のチャット利用上限（クォータ制限）: APIトークン消費と不正利用の抑制のため、顧客コンタクト単位で1日あたり最大50回までのAIチャット制限を実装。Firestoreを用いて日付単位の利用数をカウントし、超過時は有人サポートへ案内する定型文を即時返却する。
• チャットペイロード文字数バリデーション（DoS・異常課金多重防御）:
  • ユーザー入力文（userMessage）: 最大 1,000文字（超過時: 400 Bad Request「質問文の文字数が上限（1,000文字）を超えています。」）
  • 契約書コンテキスト等を含むプロンプト全体（prompt）: 最大 30,000文字（超過時: 400 Bad Request「プロンプトの文字数が上限（30,000文字）を超えています。」）
  • システム指示（systemInstruction）: 最大 5,000文字（超過時: 400 Bad Request「システム指示の文字数が上限（5,000文字）を超えています。」）

1.3 500記事RAGナレッジ連携（LINE: 3.8 Flash Thinking Medium / HP: 3.5 Flash Lite）#

• 背景とアーキテクチャ: ソライ東京が蓄積・公開している500本超の自社高品質コラム記事（北千住・綾瀬・北綾瀬をはじめとする千代田線・常磐線・足立区・葛飾区・荒川区のエリアガイド、初期費用、入居審査、保証人なし対策、外国籍サポート、SUUMO/REINSリアルタイム解説など）を、顧客の問い合わせ・お部屋探し相談にリアルタイムで推薦・リンク提供するRAG（Retrieval-Augmented Generation）基盤を構築。

• 共通ナレッジサービス (packages/common/services/knowledgeService.js):

  • 2層キャッシュアーキテクチャ（ゼロ遅延＆自動更新）:
    • 第1層（起動時静的ロード）: packages/common/data/knowledge_articles.json を起動時にメモリ展開し、I/O遅延ゼロ・API障害ゼロで即座に待受開始。
    • 第2層（HubSpot API 動的自動同期）: 起動1秒後および以降24時間周期で、HubSpot CMS API（cms/v3/blogs/posts）から5言語（JA, EN, VI, RU, ID）の最新公開記事を自動フェッチしてインメモリキャッシュを動的リフレッシュ。新しい記事を公開した際も、サーバーの再起動不要で完全自動でRAG検索対象に組み込まれる。
  • 多言語（JA, EN, VI, RU, ID）にネイティブ対応。
  • クエリ内のエリア名・駅名（北千住、綾瀬、北綾瀬、町屋、千住大橋、亀有、金町、日暮里、西日暮里、南千住、千代田線、常磐線、足立区、荒川区、葛飾区等）および賃貸テーマキーワード（初期費用、敷金・礼金、治安、相場、審査、保証人、フリーランス、外国籍、SUUMO、内見、間取り等）を検出して重み付けスコアリング。
  • 関数 findRelevantArticles(query, lang, limit) により、上位適合記事を抽出してプロンプトへ注入。

• LINE公式アカウントボット連携 (packages/line-bot/services/line/responder.js):

  • モデル: gemini-3.8-flash
  • 思考レベル: thinkingConfig: { thinkingLevel: 'medium' } を適用し、高精度な深い思考・文脈把握・専門記事推薦とスムーズな対話を両立。
  • トークン安全上限 (maxOutputTokens: 2500): 詳しい物件説明や複数質問への丁寧な回答でも文末が途中で途切れることのない十分な長さを確保しつつ、無限生成攻撃や異常出力による多重課金を確実に防止。
  • スライディングウィンドウ ＆ ローリング会話要約（Summary Memory）アーキテクチャ:
    • 直近対話のスライディングウィンドウ: Gemini API の contents に渡す生の対話履歴は直近 8 件（4往復）に限定。直前の文脈や指示代名詞（「さっきの物件」等）のニュアンスは100%保持。
    • 構造化ローリング会話要約（Structured Rolling Summary）: 会話が 4 往復（8 メッセージ）以上進んだ場合、バックグラウンド非同期（updateRollingSummaryAsync）で Gemini モデルがお客様の情報を3大カテゴリ（【希望条件】エリア・予算・間取り・時期・設備、【顧客背景・審査状況】属性・ビザ・保証人・初期費用要望、【検討履歴・現在の状況】関心物件URL・重要質問・検討フェーズ）に構造化分類し、合計 400〜600 文字程度（最大 800 文字・maxOutputTokens: 800・thinkingConfig: { thinkingBudget: 0 } による高速・最小トークン消費）のリッチな箇条書き要約として Firestore chat_history/{cacheKey} の summary フィールドに自動生成・保存。
    • システムプロンプトへの圧縮注入: Firestore から取得した summary を 【これまでの対話要約・顧客の希望情報・状況】 としてシステムプロンプトに注入。何十往復会話が継続しても 1 リクエストあたりの入力トークン数が常に数百トークンで一定（定額化）に保たれ、コンテキスト肥大化による指示忘れ（Lost in the Middle）と異常課金を恒久防止。
  • お部屋探し中のお客様や、エリア・賃貸手続きに関する質問に対して、プロンプトのコンテキストに【関連するソライ東京の専門記事（参考ナレッジ）】としてタイトル・URLを注入。回答文の中で自然なマークダウンリンク [記事タイトル](URL) 形式で提案するよう指示。
  • AI自動アシスタント署名の重複防止・サニタイズ (cleanAiSignature):
    • 共通サニタイズ関数 packages/common/services/security.js の cleanAiSignature(text) により、日本語・英語・ベトナム語・ロシア語・インドネシア語の各種表記揺れ（全角半角括弧、アスタリスク、句点等）を正規表現で自動検知・除去。
    • システムプロンプトのフォーマット規則で署名生成を明示的に禁止するとともに、Gemini出力時・会話履歴読み込み時・Web引き継ぎ処理時の各フェーズでサニタイズを多層適用し、常に末尾に1つのみの統一された署名フッターを付与する。

• HPチャットエージェント (real-estate-cms-operations/column-search-agent/index.js):

  • プライバシーファースト（個人情報・ニックネーム要求の完全禁止）: Webチャット上でお名前、ニックネーム、仮名、電話番号、年収、勤務先などの個人情報を要求・聞き出そうとする挙動を厳格に禁止。完全匿名で安心してお部屋探しの悩みや疑問を相談できる窓口として機能。
  • お悩みの傾聴とプロのアドバイス: 予算と相場のギャップ、治安、入居審査の不安、外国籍サポート等の悩みに親身に共感・整理し、客観的・実践的なアドバイスを提示。
  • LINE・メールへの自然な誘導＆会話履歴引き継ぎ（引き継ぎコード）:
    • 詳細な物件提案・空室確認・相見積もりを希望するユーザーに対して、「公式LINE（URL送信で無料診断）」や「お問い合わせフォーム（メール）」をご案内。
    • Webチャットでの相談履歴をそのまま公式LINEに引き継ぎたい場合、ワンクリックで6桁の「引き継ぎコード」を発行（POST /api/transfer/generate 経由で Firestore transfers に保存）。LINE友だち追加後にそのコードを送信することで、LINEボット（packages/line-bot）側が過去のWebチャット履歴を読み込んで文脈を途切れさせずシームレスにお部屋探しを継続できる。
  • 記事推薦・リンク捏造防止: 拡張されたキーワード辞書とスコアリングアルゴリズム、リンク捏造防止セーフガード（fixHallucinatedLinks）により、実在する500記事から安全かつ高精度なマークダウンリンク案内を提供。
  • テスト完全性・レートリミッター隔離 (packages/resident-portal/tests/transfer.test.js): NODE_ENV=test の明示設定およびプロキシ環境変数非依存設計により、複数テスト連続実行時でも引き継ぎコード生成レートリミッター（15回/15分）に干渉されず、100% 決定論的な単体テストを保証。

• 未加工会話履歴（rawHistory）永続化 ＆ Gemini API 呼び出し時限定サニタイズ (packages/resident-portal/server/services/chat/geminiAdapter.js, line/responder.js, facebook/responder.js):

  • Firestore chat_history 保存時は sanitizeHistory によるメッセージの間引き・圧縮を行わず、未加工の全ターン（rawHistory / rawMessages）をそのまま完全永続化。
  • Gemini API 呼び出し用の contents（user / model 交互配列）を構築する直前にのみ sanitizeHistory を適用し、オペレーター発言（role: 'operator'）を安全にマージ。これにより、有人対応ログや連続発言がDBから消失する問題を恒久的に防止。

• システムヘルスチェック ＆ ステータスエンドポイント (packages/resident-portal/server/routes/system.js, operator-portal/server/routes/system.js):

  • GET /api/system/status および GET /api/system/health により、Gemini API 接続状況、Firestore 疎通、Secret Manager 連携、メモリ使用量をミリ秒単位でヘルスチェック可能。
  • GCE 死活監視デーモンおよび Cloud Run Warmup ヘルスチェックからの定期プローブに対応。

1.4 HubSpot CRM リアルタイム同期・有人切り替え#

• セッショングループ化 (Session Grouping): チャットの往復ごとに新規のタイムラインオブジェクト（CommunicationまたはNote）を作成するとCRMの視認性が下がるため、30分間の同一セッションキャッシュを保持。30分以内の連続した対話は、既存のタイムラインオブジェクトの本文（hs_communication_body または hs_note_body）に対して改行区切りでアペンド（PATCH）する。
• スタッフ引継ぎの例外 (Handoff Exemption): ユーザーのメッセージに「スタッフ」「オペレーター」「担当者」などの有人連携を求めるキーワードが含まれている場合は、キャッシュを強制クリアし、独立した新しいコミュニケーションノートを起票してスタッフの視認性を高める。
• 有人モードへの自動切り替えとLINEプッシュ連携: HubSpot上のコンタクトプロパティ（ai_bot_active、line_reply_message）の変更をWebhookでリアルタイム監視。スタッフがHubSpot管理画面から line_reply_message に返信を入力すると、Webhookが起動して LINE Messaging API 経由で入居者のLINEへ即座にプッシュ送信される。同時に、該当チャネルのAI自動応答フラグ ai_bot_active_channels から LINE を除外し、有人対応モードへと安全に移行させる。
• オペレーター送信メッセージの chat_history 同期（有人対応文脈のAI引き継ぎ）:
  • オペレーターが「統合チャット管理画面（Operator Portal）」または「HubSpot CRM（line_reply_message プロパティ）」から返信したメッセージは、各チャネルの送信処理およびタイムライン保存完了後、共通サービス packages/common/services/chatHistory.js（appendChatMessage）を介して Firestore の chat_history/{cacheKey} コレクションへ { role: 'operator', text: '...' } として自動同期される。
  • ロール整合性: オペレーター発言は role: 'operator' として記録。ボット側の sanitizeHistory により、Gemini API の対話ターン仕様（user / model）へ安全に正規化されてプロンプトに供給される。
  • AI自動応答再開時の文脈保持: 有人対応後にボット自動応答を再開した場合でも、AI（Gemini）はオペレーターが過去に案内した見積もり金額や内見日程、注意事項などの文脈を 100% 把握した上で自然かつ正確な回答を継続生成できる。
  • 履歴上限管理: 会話履歴が maxMessages（デフォルト100件）を超過した場合は、古いメッセージから自動的にトリムされ、トークン消費と Firestore ドキュメントサイズの肥大化を防止する。
• 取引（Deal）へのアクティブ自動関連付け（失注・成約除外）:
  • LINEやポータルで送受信されたメッセージを HubSpot の Note（メモ）/ Communication として保存する際、コンタクト（Contact）への関連付けに加え、該当コンタクトに紐付く 進行中（Open / 未クローズ）の取引（Deal） を fetchActiveAssociatedDeal で自動探索し、取引レコードのアクティビティ（/crm/v4/objects/notes/{noteId}/associations/default/deals/{dealId}）にも同時に自動関連付け。
  • 失注・受注済みの除外フィルタ (isDealActive): hs_is_closed: true、hs_is_closed_won: true、またはステージ名が closedwon / closedlost / 成約 / 失注 / 終了 等に該当する取引は自動的に除外し、過去の成約や失注案件に新しい会話履歴が混入することを防止。進行中の案件にのみ正確に会話ログを連携する。
  • 進行中の取引が存在しない場合は、コンタクトのみに記録して安全にフォールバックする。

1.5 入居者専用ポータル（Resident Portal）アーキテクチャ ＆ TypeScript/TSX 型安全仕様#

賃貸借契約締結後の入居者・契約者様専用ポータル（packages/resident-portal）における、TypeScript / TSX 型安全設計、バックエンド・レイヤードサービス分離、および React コンポーネント分割仕様。

1.5.1 TypeScript 型基盤設計 (types/*.ts)#

• 契約者・物件型定義 (types/resident.ts):
  • ResidentProfile: 契約者属性（氏名・カナ・生年月日・電話・メール）、入居物件名・号室、賃料、契約期間（lease_start_date, lease_end_date）
  • ResidentDocument: 賃貸借契約書、重要事項説明書、保証委託契約書、鍵受領書、平面図 PDF メタデータ
  • ResidentSession: JWT セッショントークン、LIFF 認証情報、同居人共有セッション（ShareRecord）
• チャット＆引継ぎ型定義 (types/chat.ts):
  • ResidentChatMessage: 発言ロール（user / assistant / operator / system）、メッセージ本文、添付書類、タイムスタンプ
  • TransferCodePayload: Web ➔ 公式 LINE 引継ぎコード発行・照合オブジェクト

1.5.2 サーバーサイド・サービス層分離 (server/services/)#

• server/services/residentAuthService.js:
  • 認証コード正規化（SORAI-XXX 大文字・接頭辞補正）、ワンタイムパスコード（OTP）生成・検証、LINE ID アカウント連携、契約有効期限判定（3ヶ月未満ブロック）
• server/services/residentDocumentService.js:
  • 契約書・重説 PDF 一時署名付き URL 生成（15分TTL）、Google Drive / GCS ドキュメント一覧の安全取得
• server/services/share.js:
  • CSPRNG による同居人共有トークン生成、5回連続失敗による 403 Forbidden ロックアウト、個人情報・年収マスキング処理

1.5.3 フロントエンド（React 19 + Vite）コンポーネント分割 (src/components/)#

• src/components/Contract/ContractViewerModal.tsx: 契約書・重要事項説明書 PDF インラインビューア ＆ 安全ダウンロード
• src/components/Chat/ResidentChatSpace.tsx: AI チャット（Dialogflow/Gemini）＆ 有人サポート切替、自動スクロール、メッセージ送信
• src/components/Header/ResidentHeaderControls.tsx: 5言語切り替え（JA / EN / VI / ZH / KO）、LINE 連携バッジ、引継ぎコードモーダル起動
• src/components/Dashboard/ResidentHeroBanner.tsx: 契約物件情報（号室）、ゴミ出しカレンダー、設備取扱説明書リンク
• src/App.jsx: 約100行のスリムなメインオーケストレーター

1.6 問い合わせ自動下書き作成サービス（Inquiry Service）＆ TypeScript 型安全仕様#

ソライ東京の問い合わせフォーム（Webサイト・HP）における、Vertex AI Gemini による多言語お問い合わせメール本文自動生成マイクロサービス（packages/inquiry-service）の設計・型安全仕様。

1.6.1 サービス概要と多層防御セキュリティ#

• 役割: ユーザーが入力した「問い合わせ目的（お部屋探し・費用相談・一般）」と「キーワード」から、プロフェッショナルで丁寧なメール本文を 5 言語（日本語・英語・ベトナム語・ロシア語・インドネシア語）で自動下書き作成。
• ボット攻撃・トークン浪費の多層防御:
  • ハニーポット検証 (honeyPot): 不可視入力フィールドへのボット自動書き込みを即座に 400 Bad Request で遮断。
  • 提出時間検証 (timeElapsed): 人間による入力所要時間（3秒以上）を下回る機械的超高速リクエストを遮断。
  • IPレート制限 (express-rate-limit): IP あたり 15 分間に 15 回までの生成制限。
  • グローバル日次クォータガード (checkAndUpdateGlobalQuota): Firestore quotas コレクションを用い、システム全体で 1 日最大 200 回までの生成上限を設定し、悪意ある LLM トークン枯渇攻撃を恒久防止。
  • AI 縮退運転・サーキットブレーカー (isAiFeatureAllowed('inquiry_draft')): packages/common/services/degradationService.js と連動し、縮退モード時やクォータ枯渇時でもエラー画面にせず、高品質な定型相談文ドラフト（多言語対応 generateStaticDraft）を即座に 200 OK で返却。

1.6.2 TypeScript 型定義 ＆ 静的検査環境 (types/inquiry.ts, tsconfig.json)#

• ドメイン型定義 (packages/common/types/inquiry.ts):
  • InquiryDraftRequest: keywords, purpose ('room' | 'cost' | 'general' | string), lang ('ja' | 'en' | 'vi' | 'ru' | 'id' | string), honeyPot?, timeElapsed?
  • InquiryDraftResponse: draft?: string, error?: string
  • InquiryHealthResponse: status: string, target: string, vertexAI: string
• 型検証環境 (packages/inquiry-service/tsconfig.json):
  • NodeNext / ESNext / strict: true / allowJs: true / checkJs: false / noEmit: true
  • ルート package.json の "typecheck" スクリプトに統合し、モノレポ全 7 パッケージの並行静的型検査を確立。
• JSDoc / TS 型注釈:
  • app.js（Express app、CORS 許可リスト、/api/health、/api/inquiry/generate-draft、Vertex AI モデルフォールバック callDraftModel）および server.js に型注釈を配備。

1.7 HubSpot CRM 連携ステータス専用カスタムプロパティ仕様 (line_integration_status / facebook_integration_status)#

従来 HubSpot コンタクトの「姓（lastname）」に埋め込まれていた連携状態文字列（（未連携）、（連携済）、（手動照合中））を完全廃止し、専用のカスタム列挙プロパティへ移行。

1.7.1 プロパティ定義 (packages/common/services/hubspot/properties.js)#

1.7.2 状態遷移とライフサイクル#

1. 初回友だち追加 / メッセージ受信時:
   • createTemporaryHubSpotContact: lastname: '', line_integration_status: 'unlinked'（手動照合が必要な場合は manual_verification）で作成。
   • createTemporaryHubSpotContactForFacebook: lastname: '', facebook_integration_status: 'unlinked' で作成。
2. マジックリンク認証完了時 (verifyMagicLink / verifyFacebookMagicLink):
   • メール認証が完了した時点で、line_integration_status: 'linked'（Facebookは facebook_integration_status: 'linked'）に自動更新。
   • 不要なタグ文字列を lastname に混入させず、本来のユーザー氏名のみを保持。
3. Webシミュレーター引き継ぎ完了時 (validateAndProcessTransferCode):
   • 6桁コード検証成功時に line_integration_status: 'linked' / facebook_integration_status: 'linked' を更新。
4. 後方互換性とフォールバック:
   • ボット判定（isLinked / isUnlinked）およびオペレーター表示において、カスタムプロパティが未設定の旧データに対してもレガシー文字列（lastname === '（未連携）' 等）を自動フォールバック判定。

1.8 入居者ポータル 双方向チャットパイプライン仕様 (Candidate 2)#

1.8.1 チャット履歴取得エンドポイント (GET /api/chat/history)#

• JWT 認証 (verifyCustomerToken): リクエストヘッダー（Authorization: Bearer <token>）に含まれる顧客認証 JWT を検証し、トークン内の customerId に紐づく会話履歴のみをセキュアに取得。
• ロール正規化マッピング:
  • role === 'operator' || role === 'staff' || role === 'human' ➔ operator
  • role === 'user' ➔ user
  • それ以外（model, assistant 等） ➔ assistant
• データソース（LINE チャット完全分離設計）:
  • 申込ポータル（apply_history_${customerId}）と同等に、入居者ポータル専用キー portal_history_${customerId} を採用。
  • common/services/chatHistory.js の getChatHistory('portal_history_' + customerId) を経由して Firestore chat_history/portal_history_${customerId} から取得。
  • 他チャネル混入防止ガード: 万が一ドキュメントに channel === 'line' 等が設定されている場合は空配列を返却。さらにメッセージ各件に対して m.channel === 'portal' のもののみを抽出し、LINE や他チャネルからのデータ混入を多層防御で 100% 遮断。

1.8.2 フロントエンド履歴マージ ＆ リアルタイム同期待ち受け (useChat.js / useCustomer.js)#

• 正規エンドポイント一本化 (useCustomer.js):
  • 顧客セッション確立時（setupCustomerSession）において、オペレーターポータル用 API への依存を廃止し、正規の GET /api/chat/history（JWT 認証）からポータル履歴を取得して初期化。
• 初回ロード時のマージ (mergeHistoryMessages):
  • localStorage キャッシュとサーバー側 /api/chat/history を取得し、1分以内の同一テキスト重複を排除しながら完全マージして時系列昇順にソート。
• Page Visibility API 連動の 10秒定期ポーリング:
  • ブラウザタブが表示状態（document.visibilityState === 'visible'）の間、10秒間隔でサーバー履歴を定期同期。オペレーターからの返信をリアルタイムに自動反映。タブ非表示時はタイマーを破棄して不要な通信を完全抑制。

1.8.3 有人サポート返信の視覚的識別 (ChatMessage.tsx ＆ chat.css)#

• msg.sender === 'operator' のメッセージに対し、lucide-react の Headset アイコン、多言語「サポート担当」バッジ（ja, en, vi, ru, id）をレンダリング。
• .message-operator .avatar: ブルーグラデーション（#2563EB〜#1D4ED8）。
• .message-operator .message-bubble: 淡いブルー系グラスモーフィズム背景（rgba(239, 246, 255, 0.95)）とボーダー。AI 自動応答とスタッフ有人返信を視覚的に一目で区別可能。

1.8.4 入居者ポータル Full TypeScript アーキテクチャ (packages/resident-portal)#

• サーバー層（Node.js / Express API）:
  • app.ts, server.ts, server/middleware/auth.ts, server/routes/*.ts, server/services/*.ts, server/utils/*.ts による完全 TypeScript 化。
  • Cloud Run 本番コンテナ環境（Node 22 LTS）のネイティブ型除去実行（NODE_OPTIONS="--experimental-strip-types --no-warnings"）により、トランスパイル不要で直接 .ts 実行。
  • 各元の .js に export * from './*.ts'; export { default } from './*.ts'; の後方互換再エクスポートスタブを配備し、ゼロダウンタイムと既存テストランナー互換性を完全保証。
• クライアント層（React 19 / Vite SPA）:
  • main.tsx, App.tsx, hooks/*.ts, components/**/*.tsx, locales/*.ts, utils/*.ts, vite.config.ts による完全型安全化。
  • types/ ディレクトリ（auth.ts, customer.ts, chat.ts, document.ts, share.ts, transfer.ts, index.ts）を SSOT として定義し、顧客モデル・JWT ペイロード・契約情報・チャットメッセージの型整合性を 100% 保証。

id: "02_line_facebook_bots" title: "2. LINE / Facebook Bot オンボーディング＆本人確認フロー仕様" category: "system" packages: - "packages/line-bot" - "packages/facebook-bot" - "packages/common" cloud_run: - "real-estate-chatbot-line-bot" - "real-estate-chatbot-facebook-bot" endpoints: - "POST /api/line/webhook" - "POST /api/facebook/webhook" - "GET /api/line/verify-link" - "GET /api/facebook/verify-link" - "GET /api/liff/auth" secrets: - "LINE_CHANNEL_SECRET" - "LINE_CHANNEL_ACCESS_TOKEN" - "FACEBOOK_APP_SECRET" - "FACEBOOK_PAGE_ACCESS_TOKEN" - "FACEBOOK_VERIFY_TOKEN" databases: - "line_states" - "facebook_states" - "webhook_events" - "chat_sessions" - "transfers"#

2. LINE / Facebook Bot オンボーディング＆本人確認フロー仕様#

本モジュールでは、LINE公式アカウントおよびFacebook Messengerボットにおけるユーザーオンボーディング、本人確認、セキュリティ認証、およびWebアクセス追跡の技術仕様を定義する。

2.1 オンボーディング状態遷移管理 (onboardingService.js)#

新規ユーザー追加時、または未連携ユーザーからの発信時、LINEユーザーIDまたはFacebookユーザーIDとHubSpotコンタクトを安全に紐付けるためのフロー。実装は verification.js および共通 onboardingService.js が担う。

LINE公式アカウントおよびFacebook Messengerのチャットボットでは、同一の状態遷移ロジック（State Machine）を用いてユーザー登録をコントロールする。

• AWAITING_EMAIL (メールアドレス入力待ち): 未連携のユーザーにメールアドレスの入力を促す。
  • ユーザーがメールアドレスを入力した場合、onboardingService.js は検証用の「マジックリンク・トークン」を発行し、状態を AWAITING_LINK へ遷移させるとともに、登録されたメール宛てにマジックリンクを送信する。
  • ユーザーが6桁の引継ぎコード（後述）を入力した場合は、その場でシミュレーション結果の紐付け処理を行う。
  • それ以外のフリー入力（挨拶、お部屋探しの相談、ポータルURL送信など）に対しては、メールアドレスの入力を強制せず、直ちに状態ドキュメントをクリアして標準AI自動応答（Gemini 3.8 Flash）へ直通させ、親身に回答を行う（「メールアドレスが確認できませんでした」というエラーでユーザーをブロックする挙動は完全撤廃）。
• AWAITING_LINK (リンク確認待ち): ユーザーがマジックリンクをクリックするのを待つ状態。
  • 10分以内にマジックリンクがクリックされた場合、リンク処理が成功し、Firestoreの状態ドキュメントは即座に削除されてオンボーディングは完了する。
  • ユーザーが別のメールアドレスを入力した場合は新しいマジックリンクを発行・再送し、引継ぎコードを入力した場合は引継ぎ処理を実行する。
  • それ以外のフリー入力（挨拶、お部屋探しの相談、物件URL送信、質問など）を送信した場合、またはリンク有効期限切れ時においても、認証催促や期限切れ警告の再返信を行わず、直ちにFirestoreの状態ドキュメントを削除・クリアして標準AI自動応答（Gemini 3.8 Flash）へシームレスに直通させる（ユーザーが認証を中断してそのまま相談を続行できる完全非ブロック設計）。

2.2 メール・マジックリンク検証 (Email Magic-Link Verification) フロー#

1. トークン生成と有効期限: ユーザーから取得したメールアドレスに基づき、crypto.randomBytes(32).toString('hex') を用いて一意のマジックリンク・トークンを生成。有効期限は生成から10分間 (expiredAt: Date.now() + 10 * 60 * 1000) に制限し、Firestore の facebook_states または line_states にトークン情報を紐づけて永続化。
2. マジックリンク送信: ${appUrl}/api/[line|facebook]/verify-link?token=${token} を埋め込んだHTMLメールを sendMagicLinkEmail 経由で送信。
3. コンタクトの検索とマージロジック:
   • マジックリンクがクリックされると、トークン内のメールアドレスをもとに HubSpot CRM のコンタクトを検索。
   • すでにそのメールアドレスで登録されたコンタクト（本登録顧客）が存在する場合、LINE/Facebook のユーザーIDをそのコンタクトのカスタムプロパティ（line_user_id / facebook_user_id）に同期。
   • チャット初回接触時に自動生成された一時的な仮コンタクト（line_user_id等しか持たないレコード）が存在する場合は、本登録コンタクトに対して mergeHubSpotContacts を実行し、タイムライン履歴やプロパティの重複を統合する。
4. 再利用防止 (Replay Protection): リンク確認に成功したタイミングで、Firestore内の状態ドキュメント（マジックリンク・トークン情報）を即時に物理削除する。これにより、ブラウザの「再読み込み」やメールの「二重クリック」による再処理ループやトークンの再利用を完全に防止する。
5. 期限切れ自動リセット: マジックリンクをクリックした時点で有効期限を過ぎていた場合、または無効なトークンである場合は、Firestore上の状態レコードを削除または初期状態へクリアし、ボット側で再度メールアドレスの入力を促すメッセージ（AWAITING_EMAIL）へと自動リセットする。
6. HubSpot トラッキングCookie・コンタクト自動紐付け (Identity Resolution):
   • マジックリンク検証成功時にブラウザへ返却される認証完了HTML画面（getSuccessHtml）内に、HubSpot トラッキングコード（//js-na2.hs-scripts.com/246269021.js）および _hsq.push(["identify", { email: userEmail }]) スクリプトを自動埋め込み。
   • ユーザーがマジックリンクをクリックした瞬間、アクセスしたブラウザの1st Party Cookie（hubspotutk）と HubSpot CRM のコンタクト（メールアドレス）が確実にバインドされ、過去の匿名閲覧履歴を含めた Web サイト閲覧行動ログ（ページビュー・セッション・滞在時間）がコンタクト詳細タイムラインへリアルタイムに統合・同期される。

2.3 Facebook Messenger Webhook 検証とセキュリティ仕様#

Facebookボット（packages/facebook-bot）は、Metaのサーバーから受信するリクエストに対して以下の検証を義務付けている。

1. WebhookのURL確認 (GET /api/facebook/webhook):
   • Metaからのアプリ設定時、hub.mode === 'subscribe' およびクエリの hub.verify_token を環境変数 FACEBOOK_VERIFY_TOKEN と比較検証する。
   • 一致した場合はクエリパラメータの hub.challenge をステータス200で応答し、疎通確認を成立させる。
2. 署名チェックによる偽装防止 (verifyFacebookSignature):
   • POST Webhook受信時、リクエストの x-hub-signature-256 ヘッダーから sha256= プレフィックス of シグネチャを抽出。
   • 受信したリクエストの生ボディバッファ (req.rawBody) に対し、環境変数 FACEBOOK_APP_SECRET を秘密鍵とした HMAC-SHA256 署名を生成。
   • タイミング攻撃（サイドチャネル攻撃）による鍵推測を防ぐため、crypto.timingSafeEqual を用いて、計算されたハッシュとヘッダーのハッシュを定数時間で比較する。
3. プロフィール情報の自動同期 (Profile Sync):
   • オンボーディング開始時、Metaの Graph API エンドポイント https://graph.facebook.com/v19.0/${facebookUserId}?fields=first_name,last_name に対し、システムアクセストークンを用いて GET リクエストを送信。
   • 取得したユーザーの実名（ファーストネーム・ラストネーム）を HubSpot コンタクトの姓名プロパティへ自動で反映し、オペレータポータルやCRM上の顧客表示を整える。
4. Webhook リプレイ攻撃防御＆重複排除 (Deduplication via Firestore Transaction):
   • ネットワーク再送や悪意あるリプレイ攻撃によるイベントの多重実行を防止するため、イベントの一意キー（event.message?.mid または ${senderId}_${event.timestamp}）を生成。
   • Firestore webhook_events コレクションに対するトランザクション（runTransaction）により、同一キーのドキュメントが存在するかをアトミックに確認。未処理時のみドキュメントを作成（24時間TTL付き）して処理を継続し、重複時は安全にスキップ（200 OK応答）。

2.4 Meta App Review スクリーンキャスト録画・審査申請仕様 (Meta App Review Recorder & Submission Spec)#

Facebook Messenger ボットの本番利用に必要な Meta アプリレビュー（App Review）の通過を確実にするため、専用のスクリーンキャスト自動収録ツールおよび申請書式群（scripts/meta-review-recorder/）を備えている。

1. 申請対象情報＆権限 (Target Meta Configuration & Permissions):
   • App ID: 1955908915055441（Sorai Tokyo Chatbot）
   • Official Page: 株式会社ソライ東京（Page ID: 1168140463045963 / https://m.me/1168140463045963）
   • Production Endpoint: https://real-estate-chatbot-facebook-bot-rvciwqyqga-uc.a.run.app/api/facebook/webhook
   • pages_messaging: ユーザーからの賃貸問い合わせ受信・初期費用自動見積もり・ポータルURL空室確認・多言語接客の即時応答。
   • pages_show_list: 管理対象の公式Facebookページ（株式会社ソライ東京 1168140463045963）の自動検出およびルーティング検証。
   • pages_manage_metadata: Messenger Webhook（messages, messaging_postbacks）の自動登録・購読ライフサイクル管理。
2. スプリットスクリーン自動録画システム (scripts/meta-review-recorder/ui/index.html):
   • 画面解像度: 1920x1080 Full HD 60fps（左右分割レイアウト）。
   • 左画面（Facebook Messenger クライアント）: 認証済み公式ページバッジ（Verified Check）、アバター、リアルタイムタイピングインジケータ、見積もり内訳テーブル表示、SUUMO/HOME'Sリンク相談。
   • 右画面（Cloud Run バックエンド＆Gemini AI）: HMAC-SHA256署名検証ログ（X-Hub-Signature-256）、Vertex AI Gemini 3.8 Flash による賃貸RAG抽出、Graph API 送信ペイロード、Firestore/HubSpot CRM同期。
   • 下部英語ナレーション: Meta 審査基準に完全準拠したステップ解説字幕（Step 1〜Step 5）。
3. 自動実行ランナー (scripts/meta-review-recorder/live_facebook_recorder.js / record.js):
   • Headless Google Chrome を起動し、HTML5 Canvas + MediaRecorder（VP9 / 8Mbps）により動画を自動生成して meta_app_review_screencast.webm に保存。
4. 審査員向けガイド (scripts/meta-review-recorder/SUBMISSION_GUIDE.md):
   • Meta 審査フォーム提出用の英文・日本語利用理由、テスト手順、再現メッセージ、データ保護・GDPR/個人情報保護法コンプライアンスを完備。

2.5 Webポータルからの「シミュレーション結果引継ぎ」フロー#

1. 引継ぎコード生成 (POST /api/transfer/generate):
   • Webポータル上で匿名シミュレーションを行ったユーザーが「LINEで結果を受け取る」を選択した際、6桁の使い捨て「引継ぎコード」を発行し、有効期限（30分）付きでFirestoreの transfers コレクションへ保存。
   • レートリミット保護: createRateLimiter により、同一IPからのコード生成リクエストを「15分間に15回」に制限。
   • 入力バリデーションガード: messages 配列の要素数を最大30件に制限し、各メッセージの文字数を最大1,000文字に制限（超過時は 400 Bad Request）。長大なペイロードによる Firestore 容量圧迫やリソース枯渇攻撃を防止。
2. LINE入力照合: ユーザーがLINE上でこのコードを送信すると、バックエンドがFirestore内の有効コードと照合。
3. ブルートフォース保護: 同一LINE IDからの入力ミスをFirestore line_verify_attempts でカウント。5回連続で失敗した場合、該当ユーザーを15分間ロックアウトする。
4. 同期処理: 認証成功後、Webでの会話履歴をLINEチャット履歴（Firestore chat_history）に移行。HubSpotの line_user_id を同期し、使い捨てコードを即時削除する。

2.6 手動照合フォールバックフロー#

1. 手動移行: 連絡先情報が一致しない場合、対話ステータスを AWAITING_MANUAL_DETAILS に変更し、「お名前・電話・メール」の入力を促す。
2. AI属性抽出: 送信されたフリーテキストから Vertex AI (Gemini) の extractDetailsWithGemini を介して、各属性を構造化抽出。
3. タスク起票: HubSpot上に「【要対応】LINE公式アカウント手動照合依頼」という高優先度タスクを自動起票。仮のコンタクト（名前末尾に （手動照合中））を作成し、スタッフへ手動紐付けをエスカレーションする。

2.7 LINE CTA クリック追跡＆HubSpot 流入元アクセスログ自動記録仕様#

Webサイト（5言語ブログ・エリアガイド・特設LP・シミュレーター等）からLINE公式アカウントへ友だち追加された際、ユーザーが閲覧していた記事URLや参照元（Google Organic等）、アクセス地域（国・都市）、UTMパラメータを自動でHubSpotコンタクトおよびタイムラインNoteへ記録する機能。

1. Webクライアント側ビーコン送信 (theme/js/main.js):
   • サイト内の全LINE追加リンク（page.line.me, lin.ee 等）のクリックをイベントリスナーで捕捉。
   • navigator.sendBeacon または fetch(keepalive: true) を用いて /api/line/track-click へアクセス情報（閲覧URL、document.referrer、UTMパラメータ、端末言語、User-Agent）を非同期送信。
2. セキュリティ保護 & クリック追跡一時保存 (packages/common/services/tracking/clickTracker.js & packages/line-bot/server/routes/line.js):
   • Origin & Referer 検証 (validateTrackClickOrigin): soraitokyo.jp ドメイン以外からの不正・スパムリクエストを 403 遮断。
   • レートリミッター (rateLimiters.trackClick): IP単位で 1分あたり最大10回に制限。
   • PII保護（IPハッシュ化）: クライアントIPは SHA-256（+Salt）でハッシュ化し ipHash として保存。生のIPアドレスは Firestore に一切保存しない。
   • 入力サニタイズ: 全パラメータの文字列長制限（URL: 2048文字、UTM: 128文字等）および危険な制御文字のサニタイズ。
   • 受信したアクセス情報を Firestore の line_click_tracks コレクションに一時保存（保持期間: 24時間TTL）。
   • Cloud Run リクエストヘッダー（x-forwarded-for, x-client-geo-country, x-client-geo-city 等）からアクセス地域（国・都市）を自動補完し、リファラから流入元チャネル（Google Organic / Facebook / Direct 等）を自動判定。
3. LINE Webhook 高精度マッチング & HubSpot 自動記録 (packages/line-bot/services/line/orchestrator.js):
   • LINEの友だち追加（follow）または初回メッセージ受信時、matchRecentLineClick を実行。
   • 誤紐付け防止（Anti-Misattribution）設計:
     • マッチング許容時間枠を「直近5分以内」に限定。
     • IPハッシュが一致するログを最優先で照合。
     • IPなしの場合は、直近2分以内の「単一候補（Single Candidate）」のみを高信頼度でマッチング。複数候補が存在して曖昧な場合は他人の閲覧履歴が誤紐付くリスクを排除するためマッチングを行わず null を返却。
   • 照合成功時、HubSpot コンタクトのカスタムプロパティ（first_landing_url, first_referrer, acquisition_source, access_location, utm_*, access_language）に値をセットしてコンタクトを作成・更新。
   • 同時に createHubSpotAccessLogNote を介して、オペレーター向けの構造化されたリッチな「📍 流入元アクセスログ」をHubSpotタイムライン（Note）に自動投稿。

2.8 初回メッセージ・挨拶・認証履歴の完全同期仕様#

LINE公式アカウントおよびFacebookボットでは、初回接触から認証完了までのすべてのやり取りを chat_history（Firestore）および HubSpot CRM タイムラインに漏れなく記録する。

1. 友だち追加（Followイベント）:
   • handleLineFollow 実行時、送信されたウェルカムメッセージ（AI挨拶文）を role: 'model' として記録。
2. 未連携ユーザーの初手発信:
   • handleLineMessage / handleFacebookMessage において、ユーザーの初回入力文（role: 'user'）およびボット初期応答（role: 'model'）を即座に chat_history と HubSpot Note タイムラインへ同期。
3. メールアドレス入力とマジックリンク案内:
   • processOnboarding において、ユーザーが入力したメールアドレスおよびシステムが送信したマジックリンク案内メッセージを記録。
   • 認証完了時（verifyMagicLink）のウェルカムメッセージも同様に記録し、管理ポータルの統合チャット（operator-portal）から初手〜現在のやり取りを完全に可視化。

2.9 会話履歴の完全永続化（rawHistory）と Gemini API 呼び出し時限定サニタイズ仕様#

LINE および Facebook ボットの応答生成エンジン（line/responder.js, facebook/responder.js）において、Firestore chat_history と Gemini API の履歴要件を明確に分離して処理する。

1. 未加工履歴（rawHistory）の完全保持:
   • Firestore から取得した会話履歴は rawHistory として未加工のまま保持。
   • オペレーター発言（role: 'operator' / 'staff'）やユーザー・ボットの複数連続発言を一切間引かずに Firestore chat_history へ追記・永続化。
2. Gemini API 呼び出し直前サニタイズ（On-demand Sanitization）:
   • Gemini API が要求する user ➔ model ➔ user ➔ model の厳格な交互ロール制約を満たすため、API 送信用ペイロード（contents）を構築する直前にのみ sanitizeHistory を適用。
   • role === 'operator' の発言は AI 側視点ではモデル応答（model）として自然に結合・要約され、Gemini API エラーを防止しつつ完全な文脈理解を実現。

2.10 LINEボット バックエンドの TypeScript 完全移行と型構成仕様#

packages/line-bot パッケージは、Node.js 26 のネイティブ TypeScript 実行（--experimental-strip-types）および先行移行済みの他パッケージと整合する Re-export Bridge Pattern に基づき、全レイヤーを 100% 型安全な TypeScript 実装へ完全移行した。

1. 型定義構成 (packages/line-bot/types/line.ts):

   • LineStateStep / LineStateData: Firestore line_states に永続化されるセッション状態（AWAITING_EMAIL, AWAITING_LINK）の厳密な型定義。
   • ExtractedContactDetails: Gemini 3.8 Structured Outputs および正規表現フォールバックによる顧客属性抽出結果の型。
   • LineClickTrackPayload: Web サイトからの LINE CTA クリックビーコン受信時のアクセス解析・流入元ペイロード型。
   • LineAdapter: packages/common/services/onboardingService.js の ChatPlatformAdapter に適合する LINE プラットフォームアダプター型。
   • SupportedLanguage: 多言語チャット応答判定におけるサポート言語ユニオン型（'ja' | 'en' | 'vi' | 'ru' | 'id'）。

2. Re-export Bridge アーキテクチャ:

   • 既存のテストスクリプト（tests/*.test.js）やルートエントリーポイント（server.js）のインポート互換性を完全に保つため、実体を .ts で構築し、同名 .js から export * from './xxx.ts'; または export { default } from './xxx.ts'; を行うブリッジ構造を採用。
   • services/line/extractor.ts ➔ extractor.js
   • services/line/verification.ts ➔ verification.js
   • services/line/responder.ts ➔ responder.js
   • services/line/orchestrator.ts ➔ orchestrator.js
   • server/routes/line.ts ➔ server/routes/line.js
   • app.ts ➔ app.js

3. コンパイラ設定 (packages/line-bot/tsconfig.json):

   • "allowImportingTsExtensions": true を有効化し、NodeNext モジュール解決における明示的な .ts 拡張子インポートを安全にサポート。

4. CI/CD 自動デプロイパイプライン (.github/workflows/deploy.yml):

   • packages/line-bot/** の変更を検知する line フィルターを定義。
   • git push によるメインブランチ反映時、Cloud Run サービス real-estate-chatbot-line-bot（本番）および real-estate-chatbot-staging-line-bot（ステージング）へ自動ビルド＆自動デプロイが安全に実行される。

2.11 LINEボット AI エンジンの Gemini 3.8 Flash 昇格 ＆ 推論設定（Thinking Config）仕様#

LINE公式アカウント自動応答ボットの中核 AI エンジン（対話生成・属性抽出）は、最新の Gemini 3.8 Flash（gemini-3.8-flash）へと明示的に昇格・固定化された。

1. モデル解決階層 (Configuration Hierarchy):
   • env.line.modelName: process.env.LINE_BOT_MODEL ➔ process.env.VERTEX_AI_MODEL ➔ デフォルト値 'gemini-3.8-flash' の優先順位で解決。
   • Cloud Run デプロイ時（.github/workflows/deploy.yml）には、VERTEX_AI_MODEL=gemini-3.8-flash,LINE_BOT_MODEL=gemini-3.8-flash を環境変数として明示注入。
2. 推論レベル制御 (Thinking Config):
   • services/line/responder.ts では対話応答生成時に thinkingConfig: { thinkingLevel: 'medium' }（推論レベル Medium）を指定。
   • 千代田線沿線や北綾瀬周辺の家賃相場、初期費用査定、入居審査要件、ハザード診断などの複雑な不動産問い合わせに対して深い文脈理解と高精度な回答を実現。
   • services/line/extractor.ts では属性抽出時に thinkingConfig: { thinkingBudget: 0 } を指定し、最小レイテンシで高速 JSON 構造化を実行。
3. 自動フォールバック冗長化 (Failover):
   • プライマリ（gemini-3.8-flash）の API 障害・クォータ枯渇時には、共通ラッパー common/services/gemini.js を介してセカンダリモデル（gemini-3.5-flash-lite / thinkingLevel: 'medium'）へ自動フォールバック。
4. Context Caching ＆ RAG 連動:
   • common/services/contextCacheManager.js と連動し、120本以上のソライ東京専門記事ナレッジベースをキャッシュ（TTL 7200s）として再利用することで、初回応答レイテンシと入力トークン消費を大幅に削減。

2.12 無料オンライン個別相談（/consultation）AI案内ガイドライン ＆ 多言語URLルーティング仕様#

LINE公式アカウント自動応答ボットにおいて、来店不要の無料オンライン相談予約ページ（https://soraitokyo.jp/consultation）を適切な顧客文脈に合わせて自然に案内するシステムプロンプトおよびURLルーティングロジックを配備。

1. AIの最大ミッション（心理的ハードルの徹底的な排除）:
   • Webサイト・記事・シミュレーター等のCTAから流入したユーザーが抱く「いきなり不動産会社に問い合わせると営業電話が来そうで不安」「まだ引っ越し時期が決まっていないのに質問していいのか」という心理的ハードルを極限まで下げることをAIコンシェルジュの根本ミッションとして定義。
   • 相手がAIだからこそ「24時間いつでも、どんな初歩的・些細な疑問でも気兼ねなく聞ける」安心感を提供し、「時期・予算未定」「相場・治安だけ知りたい」「SUUMOで見つけた物件の空室・見積もりだけ確認したい」といったライトな相談もすべて大歓迎する。
2. 最重要原則：回答ファースト原則（LINE上での回答を絶対に省略しないこと）:
   • LINEでの疑問解消が最優先: 「初期費用を抑えるコツ」「部屋探しの時期」「審査の不安」などの相談があった場合、必ずまずこのLINE上でAIが専門知識を活かして具体的かつ分かりやすく丁寧に回答する。質問の答えを言わずに相談予約へ丸投げ・パスする案内は厳禁。
   • オンライン相談はプラスアルファの選択肢: LINE上で疑問をしっかり解消した上で、「もしテキストだけでなく、画面共有しながらプロとじっくり条件整理をしたい場合や、気になるお部屋をリアルタイム調査したい場合は、このような無料オンライン相談（1時間）もご用意していますよ」と、回答末尾に自然な選択肢として添える。
3. ミーティングのコアコンセプト（ヒアリング＆疑問解消ファースト）:
   • 営業・大量紹介の排除: 不動産会社側から物件を一方的に次々と押し売り・提案する場ではないことを明確にし、お客様の警戒心を解く。
   • お部屋探しの疑問解消 ＆ 進め方のご案内: 「探し始める時期」「初期費用を安く抑えるコツ」「審査の通過ポイント」「希望エリアや条件の整理」など、お部屋探しの進め方を体系的にアドバイスする時間として設計。
   • お客様の気になるお部屋のリアルタイム調査: お客様側で「気になっているお部屋」「確認してほしい物件（SUUMOやHOME'S等のポータルURL）」がある場合、ミーティング時間内（60分）に画面共有を交えてリアルタイムに空室状況や募集条件を確認・調査。
4. 多言語URL動的ルーティング (CONSULTATION_URLS):
   • チャット入力文の言語判定結果（detectedLang）に基づき、各言語専用の予約ページURLを動的に展開：
     • 日本語 (JA): https://soraitokyo.jp/consultation
     • 英語 (EN): https://soraitokyo.jp/en/consultation
     • ベトナム語 (VI): https://soraitokyo.jp/vi/consultation
     • ロシア語 (RU): https://soraitokyo.jp/ru/consultation
     • インドネシア語 (ID): https://soraitokyo.jp/id/consultation
5. 「必要に応じた」案内トリガー ＆ スパム防止ルール:
   • 直接の対面・通話・相談希望、進め方やお悩みの相談（LINE回答後の発展的選択肢）、物件の画面共有確認希望という3大トリガーを定義。
   • Google Meet（スマホ・PC両対応、アプリ不要、URLを開くだけ）、カメラOFF・音声のみ参加歓迎、しつこい営業電話なし。
   • 一問一答の単純な問い合わせ（ゴミ出し日等）では無理にURLを貼り付けず、会話の流れに寄り添って自然に添える。
   • オンラインビデオ面談対応言語: 【日本語】【英語】【ベトナム語】の3言語に対応（ロシア語・インドネシア語のお客様にはLINEテキストで手厚く専任対応する旨を案内）。

id: "03_ivr_voice_system" title: "3. AI電話自動応答（IVR）システム仕様" category: "system" packages: - "packages/common" - "clocall-gemini-phone" cloud_run: - "clocall-phone-tokyo-vm" - "gemini-orchestrator" endpoints: - "POST /api/ivr/webhook" secrets: - "GEMINI_API_KEY" - "HUBSPOT_ACCESS_TOKEN" - "GOOGLE_CHAT_WEBHOOK_URL" databases: - "call_logs" - "transcripts" - "system_config"#

3. AI電話自動応答（IVR）システム仕様#

本モジュールでは、電話問い合わせをリアルタイムに自動処理し、HubSpot CRM・Google Chat・BigQueryとリアルタイム連携する音声エージェント基盤（clocall-gemini-phone）の技術仕様を定義する。

3.1 基本アーキテクチャ#

• 電話番号: 03-6161-8484 (ソライ東京 AI電話窓口)
• インフラ基盤: GCE VM（clocall-phone-tokyo-vm / asia-northeast1-a / sorai-indexing-30323）上で稼働する Asterisk PBX（clocall-asterisk）および Node.js オーケストレーター（gemini-orchestrator）。
• AIモデル & 音声: Gemini 3.1 Live API（gemini-3.1-flash-live-preview）、音声モデル Zephyr（軽快・ナチュラル・親しみやすいクリアボイス・アナウンサー明瞭発声最適化プロンプト適用）。
• 通信プロトコル: Asterisk Audiosocket（TCP 9092, 16-bit 8kHz Linear PCM）と Gemini Multimodal Live API（WebSocket, 24kHz PCM）間のリアルタイム双方向ストリーミング変換。
• AI 縮退運転・最優先保護ポリシー: packages/common/services/degradationService.js によるサーキットブレーカー発動時（mode: 'degraded'）でも、AI電話窓口（03-6161-8484）は isAiFeatureAllowed('ivr') === true として 最優先で 100% 稼働継続（電話窓口保護ルール） される。

3.2 動的システムプロンプト & 多言語自動切替・名乗り最適化設計#

入電時に発信者番号から HubSpot CRM を非同期検索（600msタイムアウトガード付き）し、顧客属性に応じた動的システムプロンプト（buildSystemInstruction）を生成・適用。

graph TD
    A["📞 入電 (Asterisk AudioSocket)"] --> B["発信者番号デコード & HubSpot CRM 検索"]
    B -->|新規発信者| C["【Pattern 4: 新規顧客】<br/>「お電話ありがとうございます、ソライ東京です！AI担当がお伺いします。お部屋探しや空室確認のご相談でしょうか？」"]
    B -->|登録済み顧客| D["【Pattern 1: 既存顧客】<br/>初回挨拶統一（氏名呼び出し禁止・社内参照用コンテキスト保持）<br/>「お電話ありがとうございます、ソライ東京です！AI担当がお伺いします。お部屋探しや空室確認のご相談でしょうか？」"]
    B -->|営業・勧誘履歴| E["【Pattern 2: 営業電話】<br/>早期お断り・公式HP問い合わせ窓口への誘導"]
    B -->|無言履歴あり| F["【Pattern 3: 過去無音履歴】<br/>過去履歴を無視しフラットな新規対応開始"]
    B -->|アウトバウンド発信| G["【Outbound Mode】<br/>完全ミュート（サイレント）・自動音声聞き取りモード"]
    C & D --> H["🌐 多言語自動切替 (EN / VI / RU / ID)<br/>外国人サポート案内（保証人不要・多言語契約・ビザ対応）"]

• 初回第一声の統一（新規・既存共通）:
  • 初回第一声発話: 「お電話ありがとうございます、ソライ東京です！AI担当がお伺いします。お部屋探しや空室確認のご相談でしょうか？」
  • 設計背景: 電話接続の瞬間に名乗る前にAIから名前を呼ばれる心理的警戒感・不気味さの解消、および家族や同居人・仕事用携帯など登録者本人以外からの代理発信への配慮。
• アナウンサー明瞭発声＆トーン死守プロンプト（Zephyr最適化）:
  • プロのアナウンサーや親切なアドバイザーのように、息混じりや囁き声を抑え、一音一音をお腹からハキハキと明瞭に通るトーンで発声するよう指示。
  • ユーザー割り込み時（Barge-in）にも、初期設定された軽やかで滑らかな女性音声（Zephyr）のキャラクター・ピッチ・トーンを完全に維持するルールを強制。
• 多言語自動切替＆外国人入居サポート（Multilingual Auto-Switching）:
  • 相手が英語（EN）、ベトナム語（VI）、ロシア語（RU）、インドネシア語（ID）など日本語以外の言語で発話した場合、AI（Gemini Live API）がリアルタイムに検知し、即座に該当言語へ自動切替してネイティブ対話を開始。
  • 「保証人不要（No guarantor needed）」「多言語契約サポート」「ビザ審査ノウハウ」の強みを案内し、希望エリア・予算・入居時期・連絡先をスムーズにヒアリング。
• 既存顧客（Pattern 1: Existing Customer）:
  • CRMコンテキストの扱い: HubSpot に登録された氏名（姓・名）や過去履歴は、第一声で呼びかけるためではなく、相手が自ら名乗った際や特定の物件・契約に関する相談を切り出した際の「社内参照用コンテキスト（背景情報）」としてバックグラウンドで保持。
  • 発話禁止ルール: 発信者側が自ら名乗る前にAI側から氏名を決め打ちして呼ぶことはプロンプトレベルで厳格に禁止。
• 新規発信者（Pattern 4: New Caller）:
  • 対応: 初回統一挨拶から用件（お部屋探し・空室確認）のヒアリングへとスムーズに進行。
• 営業・勧誘電話（Pattern 2: Sales Caller）:
  • 対応: 人材紹介・広告・不動産買取提案などの営業電話に対し、無駄なヒアリングを行わず、ホームページのお問い合わせ窓口への誘導と丁寧な早期切断を実施。
• 過去無言履歴（Pattern 3: Silent Caller）:
  • 対応: 過去の「ムゴン様」記録を無視し、完全にフラットな新規顧客として初期応対を開始。
• アウトバウンド発信（Outbound Mode）:
  • UUIDヘッダー（10000000...）検知により、AI発話を完全ミュート。相手の音声ガイダンス聞き取り・文字起こしのみに徹する。

3.3 音声認識・リスニング＆動的ノイズ判定 (Adaptive VAD)#

• 動的ノイズ判定 Adaptive VAD (Voice Activity Detection):
  • 通話開始初期（500ms〜2000ms）の環境音サンプルから baselineNoise（背景ノイズ平均値）を自動計測。
  • 動的しきい値 dynamicThreshold = Math.min(Math.max(baselineNoise + 2000, 3500), 7500) を算出して適用。
  • 静かな室内（3,500）での小声を聞き逃さず、街中・駅ホーム・車内（〜7,500）での環境ノイズやクラクション等によるAI音声の誤割り込み（強制カット）を完全防止。
• 回線ノイズ無視ガード: 接続直後の2秒間（Date.now() - callStartTime < 2000）は、初期クリック音や回線ノイズを破棄し環境音サンプリングに充当。
• 初回挨拶割り込み防止ガード: 受電後最初の3.5秒間は、AIの初期挨拶がバックグラウンドノイズやエコー等で強制カットされるのを防止。
• 無音検知タイムアウト: 双方が無音の状態が30秒（SILENCE_TIMEOUT_LIMIT_MS = 30000）継続した場合、通話を自動切断してリソースを解放。
• 双方向サンプリング変換 & アンチエイリアシング FIR LPF: 8kHz PCM ↔ 24kHz PCM をリアルタイムで相互アップサンプリング・ダウンサンプリング。24kHzから8kHzへのダウンサンプリング時には、7タップ加重平均 FIR 低域通過フィルタ（アンチエイリアシングフィルタ）を適用し、折り返し歪みや声のザラつきを完全除去。

3.4 音声ストリーム完全スムーズ化・エコー抑制＆ジッターバッファ設計 (Audio Streaming Engine)#

AI音声電話における「音声ぶつ切れ・カクつき・音飛び・無音混入・エコーによる自己中断」を完全に解消するため、オーケストレーターに以下の高精度音声バッファリング＆エコー抑制機構を実装。

• TCP NoDelay & KeepAlive の適用:
  • Audiosocket 接続直後に socket.setNoDelay(true) および socket.setKeepAlive(true, 10000) を設定。
  • OSレベルのパケット集約遅延（Nagleアルゴリズム）を無効化し、Asterisk ↔ オーケストレーター間の20msフレームの即時送受信を保証。
• 24kHz サンプル境界の完全保持 (residualAudio24k):
  • Gemini Live API（24kHz 16-bit PCM）から受信した音声データを 8kHz へダウンサンプリングする際、6バイト（16-bit 3サンプル＝8kHzの1サンプル）の完全な境界を維持。
  • Buffer.concat([residualAudio24k, rawAudio24k]) により、6バイト未満の端数を residualAudio24k に繰り越して次回パケットと結合。
  • ダウンサンプリング処理に常に正確な3サンプル単位の倍数データを渡すことで、波形の位相飛びやプチプチ音（クリックノイズ）を完全解消。
• 8kHz 端数データの繰り越しバッファ (residualAudio8k):
  • 8kHz 16-bit PCM へダウンサンプリング後、Asterisk AudioSocket のフレーム仕様（20ms = 320バイト）でチャンク分割する際、端数（< 320 バイト）をゼロパディングせず次回パケットへ繰り越し。
  • Buffer.concat([residualAudio8k, audio8k]) により隙間なく結合し、320バイト単位で audioQueue に格納。音声ストリーム中間への微小な無音混入を100%防止。
• 160ms ジッターバッファ（8チャンク プリバッファリング）＆ 安全停止制御 (emptyQueueCount):
  • 再生ステート isAudioPlaying を管理。
  • 音声キューが空の状態から発話が始まった際、audioQueue.length >= 8（160ms分 = 2,560バイト）が蓄積されるまで待機してから連続再生を開始。
  • 再生中にキューが一時的に空になった場合でも即座に再生ステートを落とさず、emptyQueueCount で 200ms（10フレーム連続空）継続した場合のみ isAudioPlaying = false に遷移。AI発話途中の微小な隙間で再生ステートがバタつくのを防止し、滑らかな連続発話を実現。
• AI発話中のエコー抑制（Soft Ducking / Echo Suppression）:
  • isAudioPlaying === true の間、電話回線・受話器からの跳ね返りエコー（maxAmp <= Math.max(dynamicThreshold * 1.6, 6000)）時は Gemini Live API に 20ms の無音PCM（silence24k = 960バイト）を送信。
  • これにより、Geminiが自身の音声エコーを聞き取って発話を躊躇・息継ぎ中断（自己中断）する現象を完全に防止。
  • 相手が本当に声を出して割り込んだ場合（maxAmp > Math.max(dynamicThreshold * 1.6, 6000)）のみ実音声を送信し、自然な割り込み（Barge-in）を許可。
  • AIが聞き手側（isAudioPlaying === false）の時は、通常通り全音声を高感度にGeminiへ送信。
• 発話割り込み（interrupted）および切断時の完全バッファクリア:
  • ユーザーの発話割り込み検知時およびソケット切断・エラー時、audioQueue.length = 0; residualAudio8k = Buffer.alloc(0); residualAudio24k = Buffer.alloc(0); isAudioPlaying = false; emptyQueueCount = 0; を確実に実行し、再生待ちバッファおよび端数バッファを瞬時に破棄してユーザー音声への聞き取りに即応。
• 初回発話トリガーの最適化:
  • 初期トリガープロンプトを "もしもし" から "電話が接続されました。発信者に対して、ハキハキと第一声の挨拶を行ってください。" へ最適化し、AI冒頭の独り言や相槌漏れを防止。

3.5 通話後自動化パイプライン & 6段階トリアージ即時通知 (Post-Call Automation)#

通話終了後、以下の全自動パイプラインが非同期実行される。

1. 通話文字起こし & スマート校正 (transcribeRecordedAudio / cleanAndFormatTranscript):
   • コスト極小化モード（デフォルト: USE_GEMINI_TRANSCRIBE=false）: 通話中の Live API から得られる無料のリアルタイム文字起こしテキスト（inputTranscription）を活用し、超軽量・低コストな Gemini 3.5 Flash-Lite（gemini-3.5-flash-lite）でフィラー除去・人名カタカナ化・数字統一を即座に実行（通話後文字起こし費用 0円）。
   • 高精度音声直接認識モード（オプション: USE_GEMINI_TRANSCRIBE=true）: 録音 WAV ファイルを最新の Gemini 3.5 Transcribe（gemini-3.5-transcribe）に投入し、スマート文字起こし（フィラー自動除去・文脈自己訂正・不動産用語補正）を実行。
   • API障害時やファイル不在時も安全にテキスト整形へフォールバックする多重安全設計。
2. 6段階トリアージ構造化分析 (analyzeCallData): 会話ログから以下の6つの明確なカテゴリに厳密分類し、判定理由（reason）、姓名抽出（lastName, firstName）、検知言語（detectedLanguage）を出力：
   • EMERGENCY（🚨緊急トラブル）: 水漏れ、鍵紛失・締め出し、漏電・停電、給湯器故障、火災・ガス漏れ、設備障害、重大クレーム、事故・事件など即時対応が必要なトラブル。
   • CALLBACK_REQUIRED（📞要折り返し）: お部屋探し相談、希望条件ヒアリング、空室確認・内見希望、管理会社からの業務連絡など、人間のスタッフによる折り返しや確認が必要な通話。
   • RESOLVED（🟢対応完了）: 営業時間、店舗場所、LINE案内、WEBサイト案内などAIの回答で顧客が納得・解決し通話が終了したもの。
   • SALES（🟡営業・勧誘）: 人材紹介、不動産投資、広告掲載、不動産買取業者（例：「ホテルハウス」など）からの営業・勧誘・スパム。
   • SILENT（⚪️無言・即切り）: 発言なし、または「はい」「もしもし」等の短い言葉のみで切れた実質的な用件のない通話。
   • ATTACK（⚠️不適切・攻撃）: プロンプトインジェクション、システム指示の上書き、AIの挙動操作を試みる不正な通話。
3. 3行要約生成: オペレーター確認用の「会話の3行要約」を自動生成。
4. BigQuery ストリーミング記録: sorai_call_logs テーブルへ全メタデータ・要約・文字起こしを即時挿入。
5. Google Drive 連携: 通話テキストログおよび録音 WAV ファイルを Google Drive へ自動アップロード。
6. HubSpot CRM 最適化同期:
   • コンタクト自動作成・更新（営業電話・攻撃電話は UNQUALIFIED 自動分類）。
   • 通話アクティビティ（Call Object）を作成し、トリアージ判定ステータスをタイトルに明記して紐付け。
   • タスク起票の厳密化: 不要な過剰アラートを防止するため、タスク作成は EMERGENCY（High Priority）と CALLBACK_REQUIRED（Medium Priority）のみに限定し、RESOLVED, SALES, SILENT, ATTACK ではタスク起票をスキップ。
7. Google Chat 最適化通知:
   • 通知先スペース（AAQAPNgyVuQ）へ6段階トリアージに応じた視認性の高いヘッダーおよびステータスバッジ（🚨緊急トラブル / 📞折り返し受付完了 / 🟢案内完了 / 🟡営業 / ⚪️無言 / ⚠️不適切）を付与して送信。

3.6 OCR & IVR 連携フロー#

• 賃貸借契約書が Google Drive 等にアップロードされた際、document.js の extractContractInfoWithGemini（OCR）が動作し、以下の電話番号を抽出してHubSpotの対応プロパティへ自動同期。
  • private_area_mgmt_company_phone (専有部管理会社電話番号 - 例: 03-1234-5678)
  • shared_area_mgmt_company_phone (共用部管理会社電話番号 - 例: 03-8765-4321)
• 電話入電時、発信者番号からコンタクトを特定。入居者が「共用部のエレベーターが止まっている」と発話した場合、AIは該当物件の shared_area_mgmt_company_phone を自動で検索し、入居者に対して「共用部管理会社の 03-8765-4321 へお繋ぎします」と案内して自動転送、またはその番号をSMSで送信する。

id: "04a_apply_portal" title: "4a. 入居申込ポータル (Apply Portal) ＆ eKYC ＆ 国交省API連携仕様" category: "system" packages: - "packages/apply-portal" cloud_run: - "real-estate-chatbot-apply" endpoints: - "POST /api/contacts/apply" - "POST /api/contacts/verify-otp" - "GET /api/contacts/:contactId" - "POST /api/contacts/:contactId/upload-urls" - "GET /api/mlit/city-planning" - "GET /api/mlit/hazard-diagnosis" secrets: - "HUBSPOT_ACCESS_TOKEN" - "MLIT_API_KEY" - "JWT_SECRET" databases: - "apply_records" - "apply_shares"#

4a. 入居申込ポータル (Apply Portal) ＆ eKYC ＆ 国交省API連携仕様#

本仕様書は、入居検討者・賃貸借契約申込者がスマートフォンやPCからオンラインで入居申込・本人確認（eKYC書類提出）を完結させる専用ポータル（packages/apply-portal）および国土交通省『不動産情報ライブラリ』API連携機能のアーキテクチャ・データフロー・実装仕様を定義します。

4a.1 申込ポータル 業務実務フロー概要#

flowchart TD
    subgraph S1 ["ステップ①〜③: 申込受付・書類回収"]
        A1["1. メールOTP認証 (JWT発行)"] --> A2["2. eKYC身分証提出 (Gemini OCR)"]
        A2 --> A3["3. 入居形態確認 (単身/同居/代理契約)"]
        A3 --> A4["4. 入居申込フォーム入力・送信"]
    end

    subgraph S2 ["ステップ④〜⑤: 一番手確保 ＆ 審査フェーズ"]
        A4 --> B1["5. 管理会社へ一番手申込提出"]
        B1 -.->|タイミング①: 一番手前追加要請| B1_DYN["動的追加確認 (在留資格・日本人緊急連絡先等)"]
        B1_DYN -.-> B1
        B1 --> B2["6. 一番手確保確定 (メール/LINE通知)"]
        B2 --> B3["7. 本人確認電話アナウンス<br/>『管理会社・保証会社から電話が入る場合があります』"]
        B3 --> B4["8. 入居審査開始 (保証会社・オーナー審査)"]
        B4 -.->|タイミング②: 審査中追加要請| B4_DYN["裏付け書類要請 (給与明細3ヶ月分・源泉徴収票)"]
        B4_DYN -.-> B4
    end

    subgraph S3 ["ステップ⑥〜⑧: 審査承認 ＆ 並行クロージングトラック"]
        B4 --> C1["9. 審査承認 ➜ 契約開始日(賃料発生日)の合意・確定"]
        
        C1 --> D_TRACKS{"並行クロージングトラック"}
        
        subgraph TRACK_A ["トラックA: 契約・重説"]
            D1["HubSpot Meetings 予約 (Google Meet自動発行)"] --> D2["重要事項説明書 PDF確認"]
            D2 --> D3["電子賃貸借契約書 同意・締結"]
        end
        
        subgraph TRACK_B ["トラックB: 請求・着金"]
            E1["初期費用 請求書発行"] --> E2["お客様 銀行お振込み"]
            E2 --> E3["着金確認完了 ステータス"]
        end
        
        D_TRACKS --> TRACK_A
        D_TRACKS --> TRACK_B
        
        TRACK_A --> F_MERGE["双方完了判定"]
        TRACK_B --> F_MERGE
        
        F_MERGE --> G1["10. 鍵渡し ＆ ライフライン開通 ＆ Resident Portal案内"]
    end

4a.2 主要設計思想と実務適合ルール#

1. 動的追加要請・ハイブリッド受付設計 (Universal Dynamic Request Architecture):
   • タイミング①（一番手確保前）: 管理会社ごとに受付基準が異なり、提出前に追加確認（テキスト：雇用形態、勤務開始日、同居関係等）や追加書類（在留カード、内定通知書、車検証等）が求められる場合に対応。
   • タイミング②（審査中）: 保証会社およびオーナー審査の裏付け確認として、直近3ヶ月分の給与明細（複数枚）、源泉徴収票、確定申告書等の追加提出要請に対応。
   • テキスト回答 ＆ 複数書類（マルチファイル）追加アップロードの自由併用: ユーザー側でテキスト回答のみ、1枚〜複数枚の書類追加添付、またはテキスト＋複数書類の同時送信を柔軟に行えるステージング・マルチアップロード機構を完備。
2. 本人確認電話アナウンスの親切設計:
   • 必ずしも全件で本人確認電話が入るわけではないため、「管理会社、及び保証会社から本人確認の電話が入る場合があります。その場合はご対応をお願いします。」と明記し、心理的不安を解消。
3. 並行クロージングトラック（柔軟な前後関係の許容）＆ HubSpot Meetings 連動:
   • トラックA（契約・IT重説）: HubSpot Meetings カレンダーと連携し、顧客のお名前・メールアドレスを自動プレフィル。Google カレンダーとリアルタイムに同期して空き枠から即座に予約を確定し、Google Meet 接続URLを自動発行。
   • トラックB（請求・着金）: 請求書発行 ➜ お振込 ➜ 着金確認完了。
   • 物件や顧客都合によって契約と着金の順序が前後する実務に完全対応し、両方のトラックが完了した時点で、自動的に最終ステップ「鍵渡し・ライフライン開通・入居者ポータル案内」へとアンロック移行。
4. CRM ＆ シミュレーター完全連動:
   • HubSpot Contact Properties（payment_status, contract_status, it_explanation_time, dynamic_request 等）とリアルタイム同期。
   • オペレーター画面から各ステップを即座にシミュレート・検証可能。
5. オペレーター向け定型テンプレート ＆ 送信安全確認ダイアログ (Operator Request Composer & Safety Modal):
   • 定型テンプレート選択: 収入証明書（定番）、在職証明書・内定通知書、住民票・在留カード、勤務詳細確認、連帯保証人情報、車検証、ペット飼育書類等の実務定番テンプレートを完備。選択時にタイトル・本文・種別・推奨タイミングが自動入力。
   • 自由入力・柔軟カスタマイズ: オペレーターが必要に応じてタイトルやメッセージ内容、種別（書類提出 / テキスト情報 / ハイブリッド）を自由に編集可能。
   • 誤送信防止の安全確認ダイアログ: 送信ボタン押下時に「本当にこの内容でお客さまの画面へ追加要請を送信しますか？」という警告付き確認モーダルを起動。要請内容のプレビューと「送信するとお客さまの進行が一時停止する」旨の注意喚起を表示し、不用意な誤送信を100%防止。
6. オペレーターによる追加要請の取り下げ・送信キャンセル (Operator Request Withdrawal & Undo):
   • 要請が発信されている間、管理パネルに「【要請取消】発信中の追加要請を取り下げる」ボタンを動的表示。
   • オペレーターが取り下げを実行すると、CRMプロパティ（dynamic_request）がクリアされ、顧客ポータルから即時に要請カードが消去され、顧客は元の手続き画面へ自動復帰。
7. お申込者の入居形態・人数の再選択・戻るナビゲーション (Occupancy Reselection & Back Navigation):
   • 単身・同居人数選択後の各ステップ（同居人書類アップロード、セッション共有画面、申込フォーム）に「◀ 入居形態・人数を再選択する」ナビゲーションを配置。
   • 誤って選択した場合でも、最初からやり直すことなくワンタップで入居構成（単身 / 2〜4人 / 5人以上 / 代理契約）を再選択可能。
8. 顧客側での追加要請カードのアコーディオン折りたたみ機能 (Customer Collapsible Request Card):
   • 要請カード（#card-dynamic-request）のヘッダーに「折りたたむ / 開く」トグルボタンおよび状態バッジ（⚠️ 要対応（タップして開く））を配置。
   • お客さまが過去のメッセージ履歴や他の確認事項を見返したい際、カードをコンパクトなバナーへ一時的に折りたたむことができ、画面専有を防止。
9. 要請タイミングの全自動ステージ判定 (Auto-determined Request Timing Engine):
   • オペレーターの手動選択を廃止し、お申込者の現在ステージ（一番手確保前 ➔ timing1 / 一番手確保済み・審査中 ➔ timing2）からシステムが自動判定。
   • オペレーターパネルに「自動判定タイミング」バッジを常時表示し、送信確認ダイアログでも自動判定結果を明示。
10. 審査承認後の契約開始日・お申込時希望日ワンタップ確定 ＆ 管理会社期日指定連携 (Lease Start Date Confirmation & Deadline Management):
    • お申込時希望日の1クリック確定: お申込時に指定された希望日（desired_move_in_date）をカード上部に配置。「お申込時の希望日（YYYY年MM月DD日）で確定する」ボタンの1タップで、カレンダー再選択の手間なく即時確定。
    • 管理会社からの期日指定・連絡事項バナー: 管理会社やオーナー様から「◯月◯日までに契約開始」等の期日指定（lease_start_deadline）や連絡事項（lease_start_operator_note）がある場合、顧客画面に警告バナーを表示し、カレンダーの上限日（max属性）を連動制限。
    • 別日程の指定・変更: お申込時と別の日程を希望する場合も、カレンダーから柔軟に指定・変更して確定可能。
11. 5言語完全対応（日本語・英語・ベトナム語・ロシア語・インドネシア語 / 5-Language Multilingual Architecture):
    • 外国人居住者や外国人エクスパットの入居手続きを円滑化するため、全オンボーディングメッセージ、eKYC書類ガイド、入居形態選択、動的要請、進捗トラッカー、契約開始日確定、Google Meet IT重説案内において、5言語（ja, en, vi, ru, id）を完全サポート。
12. WCAG 2.1 AA 準拠 ＆ フォームアクセシビリティ完全最適化 (WCAG 2.1 AA Form Accessibility):
    • 全56箇所以上の入力フォーム（氏名、生年月日、住所、勤務先、年収、緊急連絡先、同居人情報等）において、すべての <input>, <select>, <textarea> に対する <label for="..."> および aria-label 関連付けを100%徹底。スクリーンリーダーや自動入力支援に完全対応。
13. モバイル・レスポンシブ UI/UX ＆ グラスモーフィズム・フォーカスリング (Mobile Ergonomics & Design System):
    • スマートフォン（横幅 375px〜520px）における eKYC 身分証明書スロット（.slots-grid）の1カラム最適化、タップ領域拡大、フォーカス時のディープエメラルド＆ゴールド発光シャドウ（box-shadow: 0 0 0 3px rgba(46, 92, 85, 0.22)）、背景オーブのはみ出し防止（overflow: hidden）を実装。Lighthouse Accessibility スコア 92+ / Best Practices 96+ を達成。

4a.3 お申込者ポータルとオペレーター管理画面の完全分離アーキテクチャ (Decoupled Portal & Backoffice)#

1. お申込者専用ポータル (GET / / http://localhost:3005/?contactId=XXX):
   • 開発者パネルや管理用ドロワーを完全に排除。
   • ソライ東京の洗練されたブランドアイデンティティ（ディープスレートグリーン＆サンセットゴールド）に基づく、顧客手続き専用の100%クリーンなワンカラム・チャット＆進捗バーUI。
   • 8段階進捗バー、eKYC身分証提出、動的入居申込フォーム、動的追加要請対応、契約開始日確定、Google Meet IT重説＆請求書着金確認、鍵渡し案内を迷いなく進行。
2. オペレーター専用管理コンソール (GET /operator / http://localhost:3005/operator):
   • 仲介エージェントおよび管理会社スタッフ専用の3カラム統合ダッシュボード。
   • 左カラム: お申込者キュー（リアルタイム検索・フィルタリング・ステータスバッジ一覧）。
   • 中央カラム: 選択中のお申込者のCRMプロパティ詳細、定型追加要請コンポーザー（自動タイミング判定・安全確認・Undo取消）、契約開始日期日・メモ管理、パイプライン進行操作ボタン（一番手確保、審査承認、請求書発行、着金確認、契約完了、リセット）。
   • 右カラム: お申込者画面のリアルタイムiframeプレビュー枠 ＆ 別タブ起動リンク。

4a.4 Apply Portal REST API エンドポイント一覧#

4a.5 国土交通省 不動産情報ライブラリ（MLIT API）連携：『物件カルテ・周辺環境AI診断』仕様#

LINE公式アカウントおよび初期費用シミュレーターにおいて、ユーザーが共有したポータルURL（SUUMO/LIFULL HOME'S/at home等）やテキスト内の住所から、国土交通省の公的オープンデータ（不動産情報ライブラリ API）をリアルタイムに自動取得し、安全面・住環境・生活利便性を客観的なファクトに基づいてAIが診断・回答する機能である。

sequenceDiagram
    autonumber
    actor User as ユーザー (LINE / Web)
    participant LB as LINE Bot / Quote API
    participant GEO as 国土地理院 ジオコーダー API
    participant MLIT as 国交省 不動産情報ライブラリ API
    participant AI as Vertex AI (Gemini 3.7 Flash)

    User->>LB: 物件URL (SUUMO等) または 住所・エリア名 送信
    LB->>GEO: 住所 ➔ 緯度・経度 (lat, lon) ジオコーディング
    GEO-->>LB: 座標返却 (キャッシュ TTL 7日)
    LB->>LB: Web Mercator タイル座標 (Zoom 15: x, y) 算定
    
    par 7系統の国交省公的データを並列取得 (Promise.allSettled)
        LB->>MLIT: 1. 用途地域・建ぺい・容積率 (/XKT002)
        LB->>MLIT: 2. 地価公示・地価調査 (/XPT002)
        LB->>MLIT: 3. 洪水浸水想定区域 (/XKT026)
        LB->>MLIT: 4. 土砂災害警戒区域 (/XKT029)
        LB->>MLIT: 5. 医療機関・救急病院 (/XKT010)
        LB->>MLIT: 6. 小学校区・中学校区 (/XKT004, /XKT005)
        LB->>MLIT: 7. 保育園・幼稚園 (/XKT007)
    end
    MLIT-->>LB: GeoJSON レスポンス群 (キャッシュ TTL 24h)

    LB->>LB: 物件カルテ要約生成 (formatLocationDiagnosisForPrompt)
    LB->>AI: プロンプト注入 (ユーザー質問 ＋ 国交省公的データカルテ)
    AI-->>LB: 客観的ファクトに基づく安心・具体的な回答文
    LB-->>User: LINE / チャット返答

4.5.1 連携エンドポイント仕様#

4.5.2 高速化・耐障害性・セキュリティアーキテクチャ#

1. 国土地理院 ジオコーダー連携 (packages/common/services/mlit/geocoding.js):
   • https://msearch.gsi.go.jp/address-search/AddressSearch を利用し、完全無料・APIキー不要で住所文字列を正規化し [lon, lat] へ高精度変換。
   • インメモリ LRU キャッシュ（TTL: 7日間、最大1,000件）により、同一住所の重複リクエストを即座に解決。
2. Web Mercator タイル座標計算 (packages/common/services/mlit/tileConverter.js):
   • 国交省 API のタイル分割仕様（標準 Zoom レベル 15）に準拠した $(x, y)$ 変換式を実装。
   • タイル境界付近の施設検索漏れを防ぐため、四分円判定による周辺 4 タイル自動検出および Haversine 式球面三角法によるメートル単位の直線距離ソートを実装。
3. 並列フェッチ・タイムアウト保護 ＆ In-Memory キャッシュ (packages/common/services/mlit/mlitClient.js):
   • 7 系統のリクエストを Promise.allSettled で完全並列実行（平均応答時間 800ms 未満）。
   • 各リクエストに 4.5 秒の AbortController タイムアウトを設定し、外部 API 遅延時でも LINE / Web のメイン対話処理をブロックしない。
   • レスポンスは 24 時間インメモリキャッシュ（最大 2,000 エントリ）に保持。
4. シークレット管理:
   • サブスクリプションキーは MLIT_API_KEY として GCP Secret Manager / 環境変数で厳格に管理され、クライアントへの露出はゼロ。
5. テスト決定論・MFAモック分離 (apply.test.js / deactivate.test.js):
   • テストスイート実行時における固定検証コード（000000）の活用とプロキシ環境変数の自動パージにより、非同期並列実行や長時間テストラン時でもローカル環境差分に影響されない安定したCI/CD検証を実現。

4a.6 セキュリティ強化 ＆ ワンクリック開始（OTP自動検証） ＆ GCS署名付きURL仕様#

4.10.1 CSPRNG暗号学的乱数 ＆ 5回失敗ロックアウト設計#

1. CSPRNG OTP ＆ トークン生成 (otpService.js / shares.js):
   • 従来の Math.random() を完全廃止し、Node.js 標準 crypto モジュールの crypto.randomInt(100000, 1000000).toString() による暗号学的に安全な疑似乱数（CSPRNG）を用いた 6 桁 OTP 生成を実装。
   • ゲスト共有トークンは crypto.randomBytes(16).toString('hex') により予測不可能な高エントロピー 32 桁 16 進数文字列として生成。
2. 5分TTL ＆ 5回失敗ロックアウト・共有リンク無効化:
   • お申込者本人認証 OTP は 5 分間の有効期限（TTL）を維持。
   • ゲスト共有認証（POST /api/shares/verify）において試行回数（attempts）を記録し、5 回連続で失敗（メールアドレス不一致、OTP不一致、代表者氏名不一致）した場合は即座に Firestore およびメモリから共有レコードを物理削除して共有トークンを無効化し、403 Forbidden を返却してブルートフォース攻撃を完全に遮断。
3. デバッグエンドポイントの厳格制限 (GET /api/shares/:token/otp):
   • process.env.NODE_ENV === 'test' 以外（本番環境・ステージング環境・開発環境）からのアクセス時は即座に 403 Forbidden で拒否。

4.10.2 GCS署名付きURL（Direct Upload） ＆ アップロード完了通知（v2）#

1. 署名付きURL発行 (GET /api/contacts/:contactId/upload-urls):
   • @google-cloud/storage を用いて、クライアントが Google Cloud Storage バケットへ直接 PUT アップロード可能な 15 分間有効（15 min TTL）の V4 Signed URL を発行。
   • テスト環境・モック環境・未設定時は安全なモックURL（/api/contacts/:contactId/mock-upload）を返却し、ローカル環境でも一切エラーなくシームレスに動作。
2. MIME / 拡張子ホワイトリスト厳格検証:
   • 許可 MIME タイプ: image/jpeg, image/png, image/webp, image/heic, application/pdf
   • 許可拡張子: .jpg, .jpeg, .png, .webp, .heic, .pdf
   • 危険なスクリプトファイル（.sh, .exe, .php, .js 等）や未許可 MIME のアップロード試行時は即座に 400 Bad Request で遮断。
3. アップロード完了通知エンドポイント (POST /api/contacts/:contactId/documents-v2):
   • GCS URI、ファイル名、書類種別（id, co_occupant_id, income, custom_document 等）を受領し、HubSpot CRM プロパティ（document_id_status, document_income_status 等）のステータスを即時同期。
   • 共同入力者（ゲスト）によるアップロード時はゲスト専用タイムラインタスク、申込者本人の場合は通常タイムラインタスクを自動記録。

4.10.3 オペレーター管理画面 ＆ 顧客一覧APIの特権ガード#

• GET /operator（管理画面HTML）および GET /api/contacts（全顧客一覧JSON取得API）に対し、verifyOperatorSession ミドルウェアによるセッション保護を適用。
• 有効なオペレーター権限 JWT クッキー（operator_token）を持たないアクセスに対しては 401 Unauthorized を返却し、未認証アクセスを強固に防御。

4.10.4 ワンクリック開始（OTP手動入力スキップ）UX ＆ サンドボックス・バイパス#

• お申込者ポータル初回アクセス時、「手続きを開始する」ボタンを押した際、apiSendOtp ➔ apiVerifyOtp を内部で即時自動実行。
• 煩雑な 6 桁コードの手動入力をスキップし、即座に「認証完了」としてステップ2（身分証提出カード）へスムーズに遷移させるゼロフリクション・オンボーディングを実現。
• ゲスト共有フローでもワンタップ認証・検証アシストを提供。
• サンドボックス・ステージング検証バイパス (otpService.js):
  • サンドボックス顧客ID（101, 102, 103, 104, 493822720761 等）およびステージング・開発環境では sendOtp 時に OTP コードをレスポンスボディに含めて即時返却。
  • 同様に verifyOtp において 000000 または 123456 による検証バイパスを許可し、自動 E2E テストやステージング検証でのスムーズな導線テストを完全サポート。

4a.7 TypeScript型定義基盤 ＆ レイヤードアーキテクチャ ＆ フロントエンドモジュール分割仕様#

4.11.1 TypeScript 型基盤設計 (types/*.ts)#

• HubSpot Contact & Application 型定義 (types/contact.ts):
  • Contact: お申込者属性、8段階ステータス、動的要請、同居人・保証人・緊急連絡先データ
  • Application: 個別申込物件オブジェクト、審査ステータス、契約開始日期日
  • DynamicRequest: 管理会社からの追加要請オブジェクト（Timing 1 / Timing 2）
• API 契約型定義 (types/api.ts):
  • UploadUrlsResponse, VerifyOtpPayload, MfaVerifyResponse, DynamicRequestPayload
• 共有・MFA セッション型定義 (types/share.ts):
  • ShareRecord: トークン、有効期限、試行回数（attempts）、公開範囲フラグ

4.11.2 バックエンド・レイヤードアーキテクチャ#

• サービス層の完全分離:
  • services/workflowService.js: ステータス遷移、動的要請生成・回答、申込形態更新、AIチャット応答生成
  • services/documentService.js: GCS署名URL発行、MIMEホワイトリスト検証、アップロード完了通知処理
  • services/shareService.js: 共有トークン生成、5回失敗ロックアウト、代表者名マッチング
  • data/mockRepository.js: モックデータアクセスのカプセル化（リポジトリパターン）
• ルート層のスリム化:
  • routes/contacts.js, routes/documents.js, routes/shares.js はルーティング定義とリクエスト/レスポンスハンドリングに特化。

4.11.3 フロントエンド・モジュール分割 (public/js/controllers/, ui/, utils/)#

• 4,358行の単一モノリス main.js を単一責任原則（SRP）に基づき以下の独立モジュールへ分割：
  • controllers/flowController.js: 8段階進捗同期（syncProgressTracker）、次ステップ自動判定（determineNextStep）、オンボーディング開始
  • controllers/authController.js: OTP送信・自動検証、ゲスト共有リンク発行・名義確認
  • controllers/documentUploadController.js: 身分証・給与明細スロット管理、プレビュー、GCS直接アップロード
  • controllers/leaseFormController.js: 4ステップ申込フォーム、郵便番号自動入力、バリデーション、送信
  • controllers/closingController.js: 契約開始日選択カレンダー、Google Meet IT重説、着金確認、契約締結
  • controllers/dynamicRequestController.js: 追加要請カード表示・ファイル添付・回答送信
  • controllers/simulatorController.js & controllers/realtimeSyncController.js: シミュレーター操作 ＆ リアルタイム同期
  • ui/domElements.js: DOM要素セレクターの一元化
  • ui/notificationToast.js: メール/LINE通知シミュレーターおよびトースト表示
  • ui/progressTracker.js: 8段階進捗バーDOM操作
  • main.js: 各モジュールの初期化とイベント登録を行うスリムなオーケストレーター（~150行）

4a.8 フルスタック E2E 自動検証スイート仕様 (All 7 Scenarios / packages/apply-portal/tests/apply_e2e.test.js)#

申込手続きのライフサイクル全般およびセキュリティ機構を包括的に自動検証するフルスタック E2E テストスイート（実行時間 100ms 未満、完全決定論的）。

4.13.1 E2E テストシナリオ一覧#

1. E2E-01: 認証・ワンクリック開始（OTP自動検証）:
   • POST /api/contacts/:contactId/send-otp ➔ POST /api/contacts/:contactId/verify-otp ➔ JWT セッショントークン発行 ➔ Bearer 認証による GET /api/contacts/:contactId 取得。
2. E2E-02: 本人確認書類（eKYC）アップロード ＆ Vertex AI Gemini OCR解析:
   • GET /api/contacts/:contactId/upload-urls で GCS 署名付き URL 取得 ➔ PUT /api/contacts/:contactId/mock-upload でバイナリアップロード ➔ POST /api/contacts/:contactId/documents-v2 で GCS 完了通知 ➔ POST /api/contacts/:contactId/documents で OCR 解析実行 ➔ 氏名（鈴木 陽子）、カナ、生年月日、性別、住所の CRM 自動反映検証。
3. E2E-03: 4ステップ入居申込フォーム全入力 ＆ 郵便番号検索 ＆ 一番手確保待ち遷移:
   • GET /api/zipcode/1200005 で住所自動補完 ➔ POST /api/contacts/:contactId/application-form で勤務先、年収、緊急連絡先、入居形態を送信 ➔ application_order_status: 'pending' 遷移検証。
4. E2E-04: オペレーター連携・一番手確保 ＆ 動的追加要請（Dynamic Request）:
   • POST /api/contacts/:contactId/set-priority で一番手確保 ➔ POST /api/contacts/:contactId/trigger-request で管理会社からの追加書類（給与明細）要請をトリガー ➔ POST /api/contacts/:contactId/dynamic-request で回答送信 ➔ 要請解除・application_status: 'screening' 遷移検証。

4a.9 お申込みポータル バックエンド TypeScript 化 ＆ Firestore-First 永続化 ＆ 統合チャット連携仕様#

4.18.1 アーキテクチャ概要 ＆ 設計思想#

お申込みポータル（packages/apply-portal）のバックエンド層を完全 TypeScript 化し、メモリキャッシュ依存から Firestore-First（SSOT: Single Source of Truth）データベース永続化 へ抜本移行。さらに、統合チャット（Unified Chat）との双方向同期、5言語対応のメール配信基盤、および GCS 直接アップロード（v2）時の Gemini OCR 自動解析を完備。

sequenceDiagram
    autonumber
    actor User as お申込者 / ゲスト
    participant Portal as Apply Portal Backend
    participant Repo as applyRepository.ts
    participant FS as Cloud Firestore
    participant Mail as mailService.ts (SMTP)
    participant OCR as ocrService.ts (Vertex AI)
    participant HS as HubSpot CRM API
    participant UC as Unified Chat (Operator)

    Note over User,Portal: 1. OTP 認証 & メール配信
    User->>Portal: POST /api/auth/send-otp
    Portal->>Repo: saveOtp(contactId, otp, 5min TTL)
    Repo->>FS: db.collection('apply_otps').doc(contactId).set(...)
    Portal->>Mail: sendApplicantOtpEmail (5言語対応)
    Mail-->>User: 認証コードメール送信

    Note over User,Portal: 2. GCS v2 アップロード ＆ Gemini OCR
    User->>Portal: POST /api/documents-v2 (gcsUri, documentType: 'id')
    Portal->>OCR: processDocumentOcr(gcsUri, mimeType)
    OCR->>OCR: Vertex AI Gemini (fileData: { fileUri, mimeType })
    OCR-->>Portal: 抽出データ (氏名、生年月日、性別、住所)
    Portal->>Repo: saveApplyRecord(contactId, updates)
    Repo->>FS: db.collection('apply_records').doc(contactId).set(...)
    Portal->>HS: updateHubSpotContact (JSONサニタイズ済)

    Note over User,Portal: 3. AI 対話 ＆ 統合チャット同期
    User->>Portal: POST /api/contacts/:id/chat (message)
    Portal->>FS: appendChatMessage('apply_history_' + id, 'user', message, 100, 'apply')
    Portal->>Portal: callModel (Gemini 3.8 Flash)
    Portal->>FS: appendChatMessage('apply_history_' + id, 'model', reply, 100, 'apply')
    FS-->>UC: Operator Portal Unified Chat にリアルタイム反映

4.18.2 TypeScript 型定義（types/）#

• types/contact.ts: ApplyRecord ドキュメント型（Firestore apply_records コレクションのスキーマ）、HubSpotContact、OccupantType、ContactUpdateProperties の厳格な型定義。
• types/workflow.ts: 8段階ワークフローステップ（WorkflowStepId）、申込ステータス（ApplicationStatus）、書類ステータス（DocumentUploadStatus）、管理会社提出（ManagementSubmissionStatus）、動的要請（DynamicRequest）の型定義。
• types/share.ts: ゲスト共有セッション（ShareRecord）の型定義。
• types/api.ts: API リクエスト・レスポンスの統合型定義。

4.18.3 Firestore-First リポジトリ層（services/applyRepository.ts）#

• apply_records コレクション:
  • お申込者の全属性（氏名、生年月日、現住所、年収、勤務先、同居人情報、緊急連絡先、動的要請、契約・決済進捗）をアトミックに永続化。
  • getApplyRecord(contactId), saveApplyRecord(contactId, updates), listAllApplyRecords() を提供。
• apply_otps コレクション:
  • 認証用 6 桁ワンタイムパスワードを 5 分間の有効期限付きで Firestore に保存。
  • 最大 5 回の失敗試行で自動失効（ブルートフォース攻撃遮断）。
• apply_shares コレクション:
  • 同居人・連帯保証人向けゲスト共有セッションを 24 時間の TTL 付きで Firestore に保存。
  • 5 回以上の認証失敗でトークンを即時削除・無効化するロックアウト機構を実装。

4.18.4 5言語メール配信基盤（services/mailService.ts）#

• packages/common/services/mail.js の Nodemailer コネクションプールを活用し、以下のメール配信を実装：
  • お申込者向け OTP メール送信 (sendApplicantOtpEmail):
    • 日本語 (ja)、英語 (en)、ベトナム語 (vi)、ロシア語 (ru)、インドネシア語 (id) の 5 言語テンプレートを配備。
    • 5分間の有効期限表示とブランド HTML テンプレートによる高品質なメール配信。
  • ゲスト共有・同居人招待メール送信 (sendGuestInviteEmail):
    • 招待 URL と専用の 6 桁ゲスト認証コード、契約者氏名を動的埋め込みして配信。

4.18.5 統合チャット（Unified Chat）完全同期#

• services/workflowService.ts の generateChatResponse において、common/services/chatHistory.js の appendChatMessage を呼び出し：
  • キャッシュキー: apply_history_${contactId}
  • チャンネル識別子: 'apply'
• ユーザーの発言および Gemini AI サポートの回答を Firestore chat_history に逐次記録。
• オペレーター管理画面（operator-portal）の Unified Chat が apply_history_${contactId} をダイレクトに並列取得し、LINE や Web ポータルと同一の統合タイムライン上でシームレスに監視・有人割り込み可能。

4.18.6 Vertex AI Gemini OCR による GCS v2 直接アップロード自動解析#

• services/ocrService.ts において、Base64 インラインデータ（v1）に加え、Google Cloud Storage の URI（gs://...）を受け取る gcsUri モードをサポート。
• documentService.ts の handleDocumentUploadV2 から本人確認書類アップロード時に自動で OCR 解析を起動し、氏名・生年月日・性別・住所を自動抽出して CRM および Firestore に即座に自動反映。

4.18.7 HubSpot CRM 連携の堅牢化 ＆ N+1 解消#

• services/hubspotService.ts において、dynamic_request などのオブジェクト型プロパティを JSON.stringify でシリアライズして送信し、HubSpot API の 400 Bad Request を防止。
• 更新後の重複 GET リクエスト（N+1 ラウンドトリップ）を撤廃し、ローカル状態と Firestore を直接マージして即座にレスポンスを返却。
• lease_start_deadline などの欠落プロパティをクエリに追加し、完全な顧客ステータスを一括取得。

4.18.8 郵便番号 API の動的フォールバック ＆ レートリミット適正化#

• routes/system.js: Zipcloud API へのタイムアウト付き動的フォールバックを実装し、モックに登録されていない全国 7 桁郵便番号の自動補完に対応。
• server.js: 本番レートリミッターを 150 から 600 req / 15 min に緩和し、フロントエンドの定期ポーリング（3.5 秒間隔）による 429 エラー発生を防止。
• routes/contacts.js: 重複していた /api/contacts/:contactId/chat ルートハンドラーを削除。

4a.10 お申込みポータル スマート・アダプティブ・ポーリング ＆ フォーム自動一時保存（Auto-Save）＆ マルチチャネル自動通知 ＆ ITANDI BB 連携仕様#

4.20.1 完全0円運用のスマート・アダプティブ・ポーリング (realtimeSyncController.js)#

• Cloud Run 従量課金モデルに最適化された0円通信設計:
  • Cloud Run では、常時接続型 SSE（Server-Sent Events）を採用するとコネクション維持時間すべてが CPU 稼働時間として積算され、タブ放置時に無料枠（180,000 vCPU秒/月）を超過するコストリスクがある。
  • 本設計では、リクエスト処理時間が 20〜30ms で即完了する軽量ポーリングをベースに、以下の「スマート・アダプティブ・ポーリング」を実装：
    1. タブ非表示時の完全停止 (Page Visibility API):
       • ユーザーが別アプリや別タブを開いている間（document.visibilityState === 'hidden'）は、ポーリングタイマーを完全停止（通信回数 0 回）。
       • タブ復帰時（visibilityState === 'visible'）に即時ブースト同期を実行。
    2. 入力中のフォーカス干渉防止:
       • 申込者がフォーム入力中（input, textarea, select フォーカス時）は、状態同期による入力中断を防ぐためポーリングをスキップ。
    3. アダプティブ指数バックオフ減速:
       • ユーザーのアクション（クリック・入力・書類アップロード）直後 1 分間は 3.5 秒間隔（高速ブースト）。
       • 1 分〜5 分間は 15 秒間隔 に減速。
       • 5 分以上無操作時は 30 秒間隔 に自動減速。
    4. DOM 再描画スキップ:
       • 取得したステータススナップショットが直前と完全一致する場合は、DOM 更新およびステップ再計算を 100% スキップし、クライアント・サーバー双方の負荷を極小化。

4.20.2 フォーム自動一時保存（Auto-Save）＆ 離脱防止・復元機能 (draftController.js)#

• スマートフォンでの離脱・カゴ落ち防止:
  • 全フォーム（基本情報・同居人・緊急連絡先・勤務先・希望入居日）の input / change イベントを 400ms デバウンスで監視。
  • localStorage の sorai_apply_draft_${contactId} に入力中の全フィールド値、ステップID、保存日時をアトミック保存。
  • 画面上部に控えめなインジケーター（✓ 自動保存済み (HH:mm)）を表示し、安心感を提供。
• 復元モーダル:
  • 画面読み込み時にローカル下書きが存在し、かつ 7 日以内に保存されたデータがある場合、「前回の入力途中データ（○月○日 保存）が見つかりました。復元しますか？」ダイアログを表示してワンタップ復元。
  • 復元選択時は該当ステップへジャンプし、全項目を自動プレフィル。
• 自動消去:
  • 本申込みフォーム送信完了時（apply_completed: true）にローカル下書きを安全に自動削除。

4.20.3 4大マイルストーン更新時の自動プッシュ通知 (notificationService.ts)#

• マルチチャネル自動通知アーキテクチャ:
  • 申込者のライフサイクルにおける重要ステータス変更時に、Email（Nodemailer）および LINE Push（LINE連携済みユーザー）を同時配信：
    1. 追加要請時 (request_created): 管理会社からの追加書類・確認事項提出依頼通知。
    2. 入居審査通過時 (screening_approved): 審査通過お祝い ＆ 次ステップ（IT重説・契約）案内。
    3. IT重説日程確定時 (it_explanation_scheduled): IT重説開始日時 ＆ Google Meet 接続 URL 案内。
    4. 初期費用着金確認時 (payment_confirmed): 初期費用入金確認 ＆ 鍵受渡準備案内。
  • 日・英・越・露・尼の 5 言語完全対応。
  • 同時に Unified Chat 履歴（chat_history/apply_history_${contactId}）へシステム自動通知メッセージを記録し、オペレーター画面と完全同期。

4.20.4 24時間未完了申込者フォロー・リマインダー (reminderService.ts)#

• 自動フォロー＆重複送信防止:
  • Firestore apply_records を走査し、作成後 24 時間以上経過しても本申込み（書類提出または完了フラグ）に至っていない申込者を自動抽出。
  • 丁寧なフォローメール（5言語対応）および LINE Push を配信。
  • reminder_sent_at タイムスタンプを Firestore に記録し、2 回目以降のスキャンでの重複送信を完全防止。
• 定期実行エンドポイント:
  • POST /api/tasks/check-reminders: Cloud Scheduler / LaunchAgent から呼び出し可能（CRON_SECRET 認可保護）。

4.20.5 （将来構想）ITANDI BB 入力自動化 Chrome 拡張機能向けエクスポートAPI#

• GET /api/contacts/:contactId/export-application:
  • 管理会社へのWeb申込み（ITANDI BB 等）における手動転記コストをゼロ化するため、Firestore apply_records および HubSpot から抽出したデータを ITANDI BB のフォーム構造（氏名・カナ・生年月日・現住所・勤務先情報・緊急連絡先）に合わせてフラットに整理した JSON を出力。
  • 将来提供予定の Chrome 拡張機能（Manifest V3）から 1 クリックで ITANDI BB の各入力欄に自動ペースト・ディスパッチ可能とする基盤を先行整備。

id: "04b_operator_portal" title: "4b. オペレーター管理画面 (Operator Portal) ＆ 統合チャットスペース (Chat Space) 仕様" category: "system" packages: - "packages/operator-portal" cloud_run: - "real-estate-chatbot-operator" endpoints: - "GET /api/messages" - "POST /api/messages" - "GET /api/deals/:dealId/status" - "POST /api/ai/draft-reply" - "GET /api/customers/unified" secrets: - "HUBSPOT_ACCESS_TOKEN" - "HUBSPOT_CLIENT_SECRET" - "LINE_CHANNEL_ACCESS_TOKEN" - "FACEBOOK_PAGE_ACCESS_TOKEN" - "JWT_SECRET" databases: - "chat_messages" - "customers" - "deals" - "ai_drafts"#

4b. オペレーター管理画面 (Operator Portal) ＆ 統合チャットスペース (Chat Space) 仕様#

本仕様書は、ソライ東京のオペレーターおよびエージェントが利用する統合管理バックオフィス（packages/operator-portal）および複数顧客・マルチチャネル（LINE・Facebook・Web）メッセージを一元管理する統合チャットスペース（Chat Space）のアーキテクチャ・UI/UX・通信プロトコル・AI返信アシスト仕様を定義します。

4b.1 Firestore-First Pure Chat Store アーキテクチャおよび統合チャット（Unified Chat）仕様#

オペレーター管理画面（operator-portal / Unified Chat / Chat Space）における会話履歴取得アーキテクチャは、Firestore-First（Pure Chat Store）へ完全移行されている。HubSpot CRM Notes（メモ）からの逆パース（parseMessage）と都度フィルター処理を完全撤廃し、Firestore chat_history に保存されている純粋なチャットログ（{ role, text, timestamp }）をダイレクトに並列取得・マージする仕組みへと抜本改修された。

sequenceDiagram
    autonumber
    actor Op as オペレーター
    participant Portal as Operator Portal (UI)
    participant Svc as chatMessageService.js
    participant FS as Cloud Firestore (chat_history)
    participant HS as HubSpot CRM (Contact / Deals)

    Op->>Portal: 顧客チャット画面を開く (customerId)
    Portal->>Svc: GET /api/hubspot/unified-chat/messages?customerId=...
    par 顧客プロパティ・ディール取得
        Svc->>HS: fetchContactById & getContactDeals
        HS-->>Svc: lineUserId, facebookUserId, activationCode, deals
    end

    Note over Svc: buildHistoryQueriesMap で関連キー抽出<br/>(lineUserId, unlinked_*, facebookUserId, portal_history_*, apply_history_*, customerId)

    par Firestore-First 並列ダイレクト取得 (Promise.all)
        Svc->>FS: db.collection('chat_history').doc(lineUserId).get()
        Svc->>FS: db.collection('chat_history').doc(unlinked_lineId).get()
        Svc->>FS: db.collection('chat_history').doc(facebookUserId).get()
        Svc->>FS: db.collection('chat_history').doc(portal_history_customerId).get()
        Svc->>FS: db.collection('chat_history').doc(apply_history_customerId).get()
        Svc->>FS: db.collection('chat_history').doc(customerId).get()
    end
    FS-->>Svc: 純粋な会話ログ ({ role, text, timestamp, quoteToken, file })

    Note over Svc: ロールから直接 sender 決定 (正規表現フィルター撤廃)<br/>各チャネルへ振り分け・ミリ秒時系列昇順ソート
    Note over Svc: portal_history_* は入居者ポータル、apply_history_* は申込に完全分離

    Svc-->>Portal: channels (LINE / Facebook / Portal / Apply) + contact + deals
    Portal-->>Op: 高速・高精度な統合チャットUI表示 (誤認・混入ゼロ)

1. Firestore-First Pure Chat Store アーキテクチャへの完全移行:
   • HubSpot CRM Notes（メモ）からの逆パース（parseMessage）と都度フィルター処理を完全撤廃。
   • 会話履歴のマスターデータストアとして Firestore chat_history コレクションをダイレクトに読み込む仕組みへ抜本改修。
   • fetchUnifiedChatMessages(customerId, contactInfo, channelsStatus) により、顧客に関連するすべてのキー（LINE: lineUserId, unlinked_${lineId} / Facebook: facebookUserId / Portal: portal_history_${customerId} / Apply: apply_history_${customerId} / Contact ID: customerId / Email / LIFFコード）から Firestore chat_history ドキュメントを Promise.all で完全並列取得。
2. 純粋なメッセージオブジェクト構築とゼロフィルター・直接ロールマッピング:
   • Firestore chat_history に保存されている構造化データ { role, text, timestamp, quoteToken, file } を直接評価。
   • 文字列正規表現やヘッダーパース（HEADER_TAG_REGEX や AI署名判定）に依存せず、Firestore 内の role フィールドから送信者（sender）を直接決定：
     • role === 'operator' / 'staff' / 'human' ➔ sender: 'operator'（オペレーター・有人スタッフ手動返信）
     • role === 'model' / 'assistant' / 'bot' ➔ sender: 'bot'（Gemini AI 自動応答）
     • role === 'user' またはその他 ➔ sender: 'user'（顧客バブル）
   • これにより、HubSpot 上に生成されるシステム業務ノート（Breeze AI 顧客カルテ分析・要約・図面照合・帯替え・見積書・OCR結果等）の逆パース・除外フィルタリング処理が不要となり、システムノート混入や誤分割リスクを根本からゼロ化。
3. ミリ秒精度による厳格な時系列昇順ソート:
   • 各チャネル（LINE, Facebook, Portal, Apply）にメッセージを振り分け、ミリ秒単位のタイムスタンプに基づいて (a, b) => (a.timestamp || 0) - (b.timestamp || 0) で厳格に昇順ソートして表示。
4. チャネル別の複数ID・未連携履歴（unlinked）統合:
   • 複数 LINE アカウントや Facebook アカウントのカンマ区切り ID、および連携前に unlinked_${lineId} に蓄積された過去の会話履歴をシームレスに該当チャネルへ統合・表示。
5. Firestore 検索キーの拡張（email / liffActivationCode）:
   • historyQueriesMap に contactInfo.lineUserId、customerId、facebookUserId に加え、contactInfo.email および contactInfo.liffActivationCode を検索キーとして追加。
   • LINE連携前のユーザーや認証コード・メールアドレスで chat_history に保存されている会話履歴の取りこぼしを完全に解消。
6. LINE / Facebook ID 保持顧客への厳格絞り込み (LINE / Facebook Chat Space Target):
   • searchActiveContactsForChatSpace および customer.js において、line_user_id または facebook_user_id を有するアクティブ顧客のみを検索・取得対象として厳格化。
   • Emailのみの問い合わせ等は顧客一覧から除外し、LINE公式アカウントまたはFacebookメッセンジャーで対話可能なユーザーのみをスッキリと一覧表示。
7. 初回挨拶・オンボーディング・マジックリンク履歴の完全同期:
   • LINE / Facebook の友だち追加時（handleLineFollow）、未連携ユーザー初手メッセージ（handleLineMessage / handleFacebookMessage）、マジックリンク送信・再試行・完了案内（processOnboarding / verifyMagicLink）、Webシミュレーション引き継ぎ（validateAndProcessTransferCode）の全メッセージを漏れなく chat_history に記録。
8. フロントエンド描画のクリーン化 (chat-common.js):
   • renderMessageTextHTML において、ヘッダータグや注記をバブル描画時に動的に strip し、LINE風の洗練されたクリーンなメッセージ吹き出しを提供。
9. ルートURL・ショートカット自動リダイレクト (app.js):
   • GET /、GET /chat、GET /chat-space へのアクセス時に、自動的に /api/hubspot/chat-space へリダイレクトするルーティングを配備。直接アクセス時も 404 にならず、即座にオペレーターチャットスペースが開くようナビゲーションを最適化。
10. 未連携ユーザー向け本人確認・認証リクエスト機構 (authRequestController.js / chat-space.html / unified-chat.html):
    • LINE / Facebook 未連携状態（line_integration_status !== 'linked'）のユーザーに対し、チャット上部に「未連携アカウント警告バナー（#unlinked-alert-banner）」および顧客カルテサイドバーに「[🔐 認証案内を送信]」ボタンを配置。
    • オペレーターがボタンを押下すると、顧客名を動的プレフィルした安全確認モーダル（#request-auth-modal）が起動。案内本文を事前確認・編集した上でワンタップ送信でき、メールアドレスの送信を促してマジックリンク認証へとスムーズに誘導。
11. LINE / Facebook 顧客プロフィール画像（アイコン）連携 ＆ 統合チャットアバター表示:
    • LINE Bot Webhook（友だち追加時 handleLineFollow / 初手メッセージ受信時 handleLineMessage / 本人確認時 verification.js）において、LINE Messaging API から取得した profile.pictureUrl を HubSpot カスタムプロパティ line_picture_url（および facebook_picture_url）へ自動保存・同期。
    • オペレーター管理画面（/api/customer/list および getUnifiedChatMessages）にて avatarUrl を連携し、顧客一覧キュー、ヘッダーアバター、チャットタイムライン吹き出しの丸型アイコンへリアルタイム反映。読み込みエラー時のイニシャルフォールバックも完備。
12. 顧客一覧キュー（左サイドバー）の LINE公式アカウント風レイアウト ＆ 純粋な直近会話日時降順ソート仕様 (customer.js / customerQueueController.js):
    • /api/customer/list エンドポイントにおいて、各コンタクトに関連するキー（line_user_id の各ID、facebook_user_id の各ID、id、unlinked_${lineId}、email、liff_activation_code 等）から Firestore chat_history ドキュメントを Promise.all で並列参照。
    • chat_history ドキュメントの timestamp または messages 配列から最新の会話タイムスタンプ（lastMessageTime）および最新メッセージ本文プレビュー（lastMessageText）を抽出。
    • AI自動応答状態による上下分割を撤廃し、LINE公式アカウントと同様に 純粋な直近会話日時の降順（b.lastMessageTime - a.lastMessageTime）に一本化 して整列。
    • クライアント側（customerQueueController.js）において、LINE公式アカウント管理画面に準拠した3カラムレイアウト（左: 丸型アバター、中央: 顧客名太字＋最新メッセージ抜粋 lastMessageText、右: 日時ラベル上段＋AIステータスバッジ下段）をレンダリング。
    • 日時ラベル（formatCustomerTime）は「今日: HH:mm」「昨日: 昨日」「今年: M/D」「過去年: YYYY/M/D」でスマート表示。
13. Firestore トランザクション保護・単一プラットフォームID集約・チャネル完全分離ルーティング (chatHistory.js / chatMessageService.js):
    • Firestore トランザクション保護 (appendChatMessage): db.runTransaction により同時多発するメッセージ書き込み（ユーザーの連続送信やAI・オペレーターの同時応答）におけるレースコンディション・上書き消失をアトミックに防止。
    • デュアルライト撤廃（単一IDマスター化）: LINE / Facebook メッセージ受信・返信時における contact.id や tempContactId への重複保存を完全廃止し、プラットフォーム固有のキー（lineUserId / facebookUserId）のみに集約。
    • チャネル完全分離ルーティング (chatMessageService.js): メッセージオブジェクト上の明示的 m.channel（m.channel.toLowerCase()）を最優先で評価し、item.channel にフォールバック。万一 contact.id 経由のドキュメントに LINE メッセージが存在した場合でも、厳格に channels.line にのみルーティングされ、ポータル等の他タブへの混入・相互汚染を恒久根絶。

4b.2 統合チャット基盤のモジュール分割・リファクタリング仕様#

肥大化していた unifiedChatController.js（約780行）および timeline.js（約470行）への過度な責務集中を解消し、修正スピードと保守性を劇的に向上させるためのモジュール分割・クリーンアーキテクチャ。

1. chatMessageService.js (packages/operator-portal/server/services/chatMessageService.js) ＆ draftGenerator.js の Pure Chat Store SSOT 統合:
   • Firestore-First Pure Chat Store アーキテクチャに基づき、Firestore chat_history コレクションからの純粋な会話ログ並列取得、クオートトークン紐付け、重複排除、時系列昇順ソート処理を担当。HubSpot Notes 逆パースを完全撤廃。
   • AI 下書き生成サービス（draftGenerator.js）においても、旧 HubSpot タイムライン逆パースおよび複数キャッシュキーの重複ポーリングループを完全廃止し、fetchUnifiedChatMessages を通じて Pure Chat Store からチャネル別会話履歴を直接取得・サニタイズして Gemini プロンプトを生成。
2. channelDispatcher.js (packages/operator-portal/server/services/channelDispatcher.js):
   • LINE / Facebook / WhatsApp / Portal / Apply へのチャネル別メッセージ送信、HubSpot Inbox 記録、Firestore operator ロール保存、Bot 自動 OFF 制御を集約。
3. timeline.js の純粋関数化 (packages/common/services/hubspot/timeline.js):
   • parseMessage を detectChannelFromTag、detectSenderFromTagAndText、extractTimestampFromText の純粋関数群に整理し、可読性とテスタビリティを向上。
4. unifiedChatController.js のスリム化 ＆ 未使用エンドポイント完全撤廃:
   • クリーンな薄い HTTP コントローラー層へと再編。旧来の未マウント関数 generateDraft（draftController.js 側で新版 generateDraftSuggestion が稼働中）を完全除去し、コードの保守性と型安全性を向上。
5. 統合チャット バックエンドサービスの TypeScript（.ts）完全移行 ＆ ゼロダウンタイム再エクスポート構造:
   • packages/common/services/chatHistory.ts, botStatus.ts, hubspot_oauth.ts および packages/operator-portal/server/services/chatMessageService.ts, draftGenerator.ts, channelDispatcher.ts を TypeScript へ完全移行。
   • packages/common/types/ および packages/operator-portal/public/js/types/ の厳格なドメイン型（ChatMessage, ChannelsMap, BotStatusCacheEntry, HubSpotTokenData, DraftSuggestPayload, SendMessagePayload 等）を完全適用し、100% 型安全性を担保。
   • 既存の .js 呼び出し元（line-bot, facebook-bot, resident-portal 等）との完全な後方互換性と無停止稼働を担保するため、各サービスに export * from './<service>.ts'; 再エクスポートスタブを配備。
   • Node 22（Cloud Run 本番コンテナ）および Node 26（ローカル開発環境）のネイティブ型除去実行（ENV NODE_OPTIONS="--experimental-strip-types --no-warnings"）により、ビルドステップ不要の堅牢かつ高速なランタイム実行を実現。

4b.3 オペレーター応答時のAI誤応答完全防止 ＆ 送信者高精度識別 ＆ 直近オペレーター返信自動ガード#

1. AI署名・手動返信キーワードに基づく送信者高精度識別 (timeline.js / unifiedChatController.js):
   • メッセージ解析において、AI署名（※このメッセージはAI... 等）の有無や手動返信キーワード（ソライ東京の、担当の、ご連絡ありがとうございます 等）を精緻に解析。人間が手動で送ったメッセージがAI応答バッジで表示される問題を根本解消し、確実に sender: 'operator' として識別。
2. 直近オペレーター返信自動ガード (orchestrator.js):
   • LINE Bot および Facebook Bot において、直近チャット履歴で最後に発言したのがオペレーター（operator）である場合、AI 自動応答を自動停止（有人対応モードを維持）し、Gemini 応答をスキップして Google Chat に「有人対応中・ユーザー返信」として通知。
3. Firestore SSOT 厳格化 ＆ 多重ID・HubSpot プロパティ同期 (botStatus.js / unifiedChatController.js):
   • isBotActiveForContact において Firestore bot_status を Single Source of Truth (SSOT) として厳格化。
     • Step 1: プロセス内キャッシュ（TTL: 5秒）判定: 直近キャッシュがあれば外部呼出 0 で高速返却。
     • Step 2: Firestore bot_status（contactId または altId）判定: ドキュメントが存在する場合は expired_at 契約満了確認および channels[normalizedChannel] の真偽値を最優先適用（HubSpot 側のプロパティ値に左右されず Firestore が絶対的正）。
     • Step 3: Firestore 未登録時の HubSpot プロパティフォールバック: Firestore ドキュメントが存在しない新規顧客に限り、HubSpot Contact プロパティ（ai_bot_active / ai_bot_active_channels）を参照して初期状態を判定し、キャッシュに保存。
   • 有人対応切替・オペレーターメッセージ送信時には全関連ID（contactId, lineUserId, facebookUserId）へ同時に書き込み。
4. 入居者ポータル（resident-portal）チャットログのチャネル明示化 (packages/resident-portal/server/routes/chat.js):
   • 入居者発言および Gemini 応答の Firestore chat_history 保存時（appendChatMessage）に 100, 'portal' を明示的に渡すことで、Pure Chat Store 内で channel: 'portal' として正確に分類・取得可能に最適化。
5. 顧客一覧API（/api/customer/list）のブラウザ304キャッシュ完全無効化 ＆ モック顧客フォールバック完全撤廃:
   • Cache-Control: no-cache, no-store, must-revalidate ヘッダーを明示付与し、ブラウザの304キャッシュによる古いモック表示を根絶。
   • HubSpot API エラー時もモック顧客ではなく空配列を返すよう修正し、テストデータの混入を恒久防止。

4b.4 クラウド実行基盤（GCP Cloud Run）＆ リアルタイム双方向同期 ＆ 本人確認書類UI仕様#

4.9.1 Cloud Run サービス構成 ＆ 公開URL#

入居申込ポータルおよびオペレーター管理画面は、Google Cloud Run 上のコンテナマイクロサービスとして稼働し、0スケール従量課金と高スケーラビリティを両立している。

• 本番環境 (Production):
  • サービス名: real-estate-chatbot-apply
  • 公開URL: https://real-estate-chatbot-apply-902297816152.us-central1.run.app/
  • お申込者専用画面: https://real-estate-chatbot-apply-902297816152.us-central1.run.app/?contactId=101
  • オペレーター管理コンソール: https://real-estate-chatbot-apply-902297816152.us-central1.run.app/operator
• ステージング環境 (Staging):
  • サービス名: real-estate-chatbot-staging-apply
  • 公開URL: https://real-estate-chatbot-staging-apply-902297816152.us-central1.run.app/
• コンテナイメージ ＆ セキュリティ:
  • Artifact Registry: us-central1-docker.pkg.dev/sorai-indexing-30323/cloud-run-source-deploy/real-estate-chatbot:latest
  • 非rootユーザー USER appuser、メモリ 512MiB、CPU 1、タイムアウト 300秒。

4.9.2 リアルタイム双方向同期（BroadcastChannel ＆ Storage Event ＆ バックグラウンドポーリング）#

• 同一オリジン 0ms 即時連動 (BroadcastChannel('sorai_portal_sync_channel')):
  • 同一ブラウザの別タブや iframe でオペレーター画面と顧客画面を操作した場合、追加要請発信/取り下げ、期日設定、パイプライン進行、書類提出が 0ms で相互反映。
• 別ウィンドウ・別端末間ストレージ連動 (localStorage.setItem('sorai_sync_...')):
  • storage イベントをトリガーとし、別ブラウザウィンドウ間でも即座に状態同期。
• バックグラウンド定期ポーリング (3.5秒間隔):
  • スマホ実機や外部回線からの接続時でも、バックグラウンドで CRM プロパティ（dynamic_request、application_status、payment_status 等）の差分を検知して UI を自動更新。

4.9.3 本人確認書類（顔写真付き身分証必須・健康保険証任意化）UI/UX仕様#

• 必須書類の明確化:
  • 一番手確保および審査受付に必須となる「顔写真付き身分証明書（運転免許証、マイナンバーカード、在留カード、パスポート）」の案内ボックスとバッジを設置。
• 健康保険証の任意提出化（マイナ保険証対応）:
  • マイナンバーカードが健康保険証を兼ねているケースや一番手申込の実務要件に即し、健康保険証（表・裏）を「任意提出」へ変更。
  • 顔写真付き身分証の表裏2面が揃った時点で送信ボタンを活性化（身分証明書（2枚）を送信する）。保険証も選択された場合は枚数（3枚・4枚）に応じて動的にラベル表示を更新。
• AIチャットエンドポイント (POST /api/contacts/:contactId/chat):
  • Vertex AI（Gemini 3.7 Flash）による実務対応AIチャットエンドポイントを配備し、英語・日本語・ベトナム語で入居手続きに関する質問に即座に回答。

4b.5 統合チャット（Unified Chat）TypeScript 型安全化 ＆ モジュールアーキテクチャ刷新仕様#

4.12.1 共通型定義基盤との統合 (packages/common/types/)#

• マルチチャネルメッセージ型 (types/chat.ts):
  • ChannelType ('line' | 'facebook' | 'portal' | 'apply')
  • SenderRole ('user' | 'agent' | 'bot' | 'system')
  • ChatMessage: id, sender, role, channel, text, attachments, createdAt, rawTimestamp, isAgent, isRead, isStreaming, status, metadata
  • BotStatusMap: チャネル別の AI 自動応答フラグ管理
• API 契約型定義 (types/api.ts):
  • UnifiedChatMessagesResponse, ToggleBotPayload, ToggleBotResponse, SendMessagePayload, DraftSuggestPayload, DraftSuggestResponse
• HubSpot CRM 統合型定義 (types/hubspot.ts):
  • HubSpotContactProperties, HubSpotDealProperties, CrmCardResponse

4.12.3 フロントエンド ES Modules 分割 ＆ 型安全化仕様 (packages/operator-portal/public/js/modules/)#

• 3,046行のモノリス（chat-common.js, chat-space.js, unified-chat.js）を単一責任原則（SRP）に基づき以下の ES Modules へ分割：
  • modules/apiClient.js: fetchUnifiedChatMessages, sendOperatorMessage, toggleBotStatus, fetchDraftSuggestion, uploadChatMedia, fetchCustomersList 等の API 通信を一元化
  • modules/chatRenderer.js: LINE / Facebook / Portal / Apply チャネル別の吹き出し描画、Markdown レンダリング、添付プレビュー、日時整形
  • modules/drawerController.js: HubSpot Breeze AI スライドインドロワー、顧客情報ドロワー、画像ライトボックスの開閉制御
  • modules/draftAssistController.js: Gemini 3.7 Flash AI 返信アシストパネル、クイックプロンプト適用、下書きプレビュー＆入力欄挿入
  • modules/fileUploadController.js: 添付ファイルドラッグ＆ドロップ、クリップボード画像貼り付け、プレビュー表示・添付解除
  • modules/customerQueueController.js: 顧客キュー取得、リアルタイム検索・フィルタリング、未読バッジ、アクティブ顧客切り替え
  • chat-common.js / chat-space.js / unified-chat.js: 各約150行のスリムなオーケストレーターに刷新
• packages/operator-portal/tsconfig.json の型チェック対象に public/js/**/*.js を統合。
• アセット・キャッシュバスティング仕様 (?v=2.1.0):
  • ブラウザや HubSpot CRM Iframe 側での古い JavaScript / CSS キャッシュ保持を根本防止するため、server/templates/chat-space.html, server/templates/unified-chat.html 内の <link rel="stylesheet"> および <script type="module">、さらにオーケストレーター（chat-space.js, unified-chat.js, chat-common.js）からの内部 ESM インポート（./modules/*.js?v=2.1.0）に一貫したキャッシュバスティングバージョンパラメータを付与。

4b.6 モダン・エルゴノミック チャット入力ドック仕様（自動伸縮テキストエリア・IME確定誤送信防止・アクション分離）#

4.14.1 UI/UX 設計方針 ＆ 人間工学（Ergonomics）#

1. 自動伸縮テキストエリア（Auto-expanding <textarea>）:
   • 従来の単一行 <input type="text"> を廃止し、入力文字数・改行に応じて最小高さ（24px / 1行）から最大高さ（120px / 約5行）までスムーズに追従・伸縮する <textarea id="chat-text-input"> を採用。
   • 長文の質問（転職理由、同居人情報、必要書類の確認等）を入力する際でも、文章全体を一覧しながらストレスなく推敲可能。
2. 直感的なキーボード操作 ＆ 日本語 IME 確定誤送信の完全防止:
   • 通常 Enter: メッセージを即座に送信（!e.isComposing による IME 変換確定キーとの厳密な区別）。
   • Shift + Enter: 改行を挿入（テキストエリア高さもリアルタイム自動拡張）。
   • 日本語入力時の漢字変換確定で誤って Enter を押しても、compositionstart / compositionend イベントリスナーにより誤送信を 100% 防止。
3. ボタン分離 ＆ ダイナミック発光インタラクション:
   • 誤タップの原因となっていた送信ボタン隣の「共有ボタン」を、入力欄左側の独立アクションアイコン（.dock-action-btn）へ配置転換。
   • 入力文字が存在する場合にのみ送信ボタン（.send-btn）がディープエメラルド（#2E5C55）に発光・活性化（.active）し、送信完了時は即座に 1 行の最小サイズへ自動リセット。
4. 5言語プレースホルダー同期:
   • 言語切り替え時に translations.js から各言語に応じたキー操作ヒント付きプレースホルダーを動的注入（JA: メッセージを入力... (Enterで送信, Shift+Enterで改行), EN: Type a message... (Enter to send, Shift+Enter for new line), VI, RU, ID）。

4b.7 統合チャット（Chat Space）顧客一覧・表示名の正規化と連携ステータス分離仕様#

4.15.1 顧客一覧 API (/api/customer/list / customer.js)#

• 姓名クリーンアップと正規化:
  • lastname / firstname からレガシーな連携状態タグ（（未連携）、（連携済）、（手動照合中））を正規表現により完全除去（strip）し、純粋な氏名（fullName / displayName）を生成。
  • レスポンスに lineIntegrationStatus (line_integration_status) および facebookIntegrationStatus (facebook_integration_status) を追加。
• 純粋な実会話履歴降順ソート ＆ 最新メッセージ抜粋（lastMessageText）返却仕様:
  • 第1キー（直近会話日時）: AI応答状態による上下分割を廃止し、Firestore chat_history の最新タイムスタンプ（lastMessageTime）の降順（新しい順）に純粋ソート（LINE公式アカウントと同じ対話順整列）。会話実績のない顧客は 0 として最下部に配置（HubSpot lastmodifieddate へのフォールバックは完全廃止）。
  • 第2キー（安定ソート）: 日時が同一の場合は名前順（localeCompare）で安定ソート。
  • 最新メッセージ抜粋抽出: Firestore chat_history の messages 配列から最新テキストを lastMessageText として抽出し、空の場合は物件名（propertyName）にフォールバック。
• 顧客キュー一覧での LINE 公式アカウント風 3 カラム表示 (customerQueueController.js / chat-space.css / unified-chat.css):
  • 各顧客アイテムを LINE 公式アカウント管理画面風の 3 カラム構造に刷新：
    • 左カラム: 46px 丸型アバター（.customer-item-avatar / プロフィール画像またはイニシャル）
    • 中央カラム: 顧客名（.customer-item-name / 太字）＋ 最新メッセージの抜粋プレビュー（.customer-last-message / 1行省略表示）
    • 右カラム: 上段にスマート日時（.customer-item-time / 今日は HH:mm、昨日は 昨日、今年以前は M/D、過去年は YYYY/M/D） ＋ 下段にステータスバッジ（.bot-status-pill.ai：🤖 AI応答 / .bot-status-pill.manual：👤 有人）
• 統合チャットメッセージ API (/api/operator/unified-chat / unifiedChatController.js):
  • contactInfo 内の name から不要な状態タグを除去し、lineIntegrationStatus / facebookIntegrationStatus を明示的に構造化返却。
  • CRM Card（renderCrmCard）において、line_integration_status === 'linked' または line_user_id の存在有無から正確な連携ステータス（連携済み ✅ / 未連携 ⚠️）をレンダリング。

4b.8 統合チャット（Chat Space）UI/UX ＆ CSP セキュリティ強化仕様#

4.16.1 右側顧客カルテ常時表示レイアウト（3カラム・人間工学最適化）#

• 3カラム・エルゴノミクス構造:
  • 左カラム: 顧客キュー（リアルタイム検索・会話日時降順一覧）
  • 中央カラム: チャットメインコンテンツ（main-content-area / 会話ログ、引用返信、ファイル添付、AI返信アシスト、メッセージ入力ドック）
  • 右カラム: HubSpot 顧客カルテサイドバー（hubspot-info-sidebar / 基本情報、Breeze AI カルテ分析、契約・取引情報）
• デスクトップ常時表示 ＆ スタイリング:
  • PC（幅 900px 以上）において、顧客選択時に右側顧客カルテを初期状態で常時展開表示（border-left: 1px solid var(--border-color); border-right: none;）。
  • モバイル・タブレット（幅 900px 未満）ではドロワーボタン（openCustomerInfoDrawer()）経由でのスライドアップ表示へレスポンシブ自動切り替え。

4.16.2 未連携アカウント警告バナーの完全撤去#

• 画面上部を圧迫していた #unlinked-alert-banner を完全撤去。
• アカウント認証・本人確認の案内送信（🔐 認証案内を送信）は、顧客カルテの連携状況バッジ横ボタンおよびヘッダーアクションからスムーズに起動可能。

4.16.3 CSP (Content Security Policy) マルチチャネル画像ホワイトリスト仕様#

• packages/common/middleware/security.js の createHelmet において、portal および deal プリセットの imgSrc ディレクティブを拡張：
  • "https://*.line-scdn.net": LINE プロフィール画像・アセット（個別ドメイン指定からワイルドカードへ統一）
  • "https://*.fbcdn.net": Facebook プロフィール画像・CDN アセット
  • "https://*.cdninstagram.com": Instagram / Meta CDN アセット
  • "https://*.line-apps.com": LINE アプリ・スタンプアセット
• 外部 SNS アイコンおよびメディア画像の安全な直接描画を保証し、ブラウザコンソールにおける CSP 違反警告を 100% 根絶。

4b.9 統合チャット送信堅牢化・多重送信ガード・リカバリ ＆ Enter送信仕様#

4.17.1 多重送信・連打完全防止（isSending フラグ ＆ ボタン disabled 化）#

• unified-chat.js および chat-space.js の sendMessage において、送信開始と同時に isSending = true を設定し、送信ボタン（#send-btn）を disabled 化してローディングスピナー（.send-spinner）を表示。
• 通信完了まで追加入力や Enter 連打を 100% 遮断し、同一メッセージの多重送信を完全に防止。

4.17.2 送信失敗時サイレント握りつぶし解消 ＆ 入力テキスト自動復元 ＆ エラーバッジ表示#

• 通信エラーや LINE API エラー等で送信失敗した場合、入力欄に送信しようとしていた下書きテキスト（backupText）を即座に復元し、オペレーターが再入力する手間を完全に排除。
• フィード上の該当メッセージ吹き出しに「⚠️ 送信失敗」エラーバッジを付与し、トースト通知（#chat-toast.toast-error）で具体的な失敗原因を明示。

4.17.3 Enterキー送信・改行・IME確定の操作性改善（Option A 実装）#

• PC作業時の快適なチャット操作のため、「Enterキーで即時送信」「Shift+Enterで改行」を標準採用。
• Mac/Windows両対応として「Cmd+Enter」「Ctrl+Enter」での送信も完全サポート。
• 日本語入力時のIME確定 Enter（e.isComposing || e.keyCode === 229）を厳格に除外し、文字変換中の誤送信を 100% 遮断。
• プレースホルダー（メッセージを入力... (Enterで送信 / Shift+Enterで改行)）で操作ガイドを明示。

4.17.4 チャネル送信ハンドラ堅牢化 ＆ LINE未連携事前バリデーション#

• channelSendHandlers において、line_user_id が未登録または無効な顧客に対して LINE 送信を試みた場合、400 Bad Request と適切な日本語エラー（LINEが未連携の顧客です。先に認証案内を送信して連携を完了してください。）を返却。不要な Bot OFF 処理の先行実行を防止。
• sendLinePush / sendLineImagePush / sendLineFilePush の結果を厳格にチェックし、LINE API 側でトークン失効や通信エラーが発生した場合は即座に例外をスローしてオペレーターへフィードバック。
• portal および apply チャネルの送信ハンドラを明示的に登録。

4.17.5 包括的 E2E テストスイート（e2e-operator-chat.test.js）#

• LINE正常送信、未連携バリデーション、必須パラメータ検証、未知チャネル検証、添付ファイル送信・プロキシURL正規化、LINE APIエラーハンドリングの全6シナリオを網羅する自動テストを整備。

4b.10 オペレーターポータル ポーリング最適化 ＆ HubSpot 429 抑制仕様 (Candidate 1)#

4.19.1 インメモリキャッシュ機構 (contactInfoCache / dealsCache / TTL: 20s)#

• 背景と課題: オペレーター画面（unified-chat.js / chat-space.js）は 3 秒間隔でメッセージ取得 API（GET /api/hubspot/unified-chat/messages）をポーリングするため、画面を開いているだけで HubSpot API（fetchContactById, getContactDeals）が短期間に集中し、CRM 側のレートリミット超過（HTTP 429 Too Many Requests）を誘発していた。
• インメモリキャッシュの配備:
  • packages/operator-portal/server/controllers/unifiedChatController.js 内に contactInfoCache および dealsCache（TTL: 20,000ms = 20秒）を設置。
  • customerId をキーとして、有効期限内のキャッシュが存在する場合は HubSpot API への通信をスキップし、キャッシュデータを即座に再利用。
  • チャットメッセージ履歴（chatMessageService.fetchUnifiedChatMessages）は毎リクエスト直接 Firestore から取得し、0 秒ラグのリアルタイム性を完全担保。
• キャッシュ強制無効化 (Cache Invalidation):
  • オペレーターがメッセージを送信した際（sendUnifiedChatMessage）、および AI Bot の有効/無効状態をトグル切り替えした際（toggleBotState）には、直ちに該当 customerId のキャッシュを破棄し、最新状態との不整合を完全防止。
  • テスト用の初期化関数 _clearUnifiedChatCacheForTesting() を公開。

4.19.2 GET ポーリング時の副作用完全排除 (LIFF Activation Code 自動生成ループ解消)#

• 従来 getUnifiedChatMessages 内で、liff_activation_code が未設定の顧客に対して毎回 HubSpot 検索・更新ループ（generateUniqueActivationCode()）を実行していた副作用コードを完全撤去。
• LIFF アクティベーションコードの発行はウェルカムシート表示時などの明示的アクションに限定し、定期ポーリング時の HubSpot 負荷をゼロ化。

4.19.3 Page Visibility API によるバックグラウンドポーリング完全停止#

• unified-chat.js ＆ chat-space.js の省電力・省通信制御:
  • document.addEventListener('visibilitychange') を導入。
  • オペレーターが別タブに切り替えた場合やブラウザを最小化した場合（document.visibilityState !== 'visible'）、メッセージポーリング（3秒間隔）および顧客キュー一覧ポーリング（6秒間隔）を即座に破棄（clearInterval）。
  • 再度タブを表示した瞬間（document.visibilityState === 'visible'）に最新データを即座に取得（loadMessages(false) / loadCustomers()）し、定期ポーリングタイマーを自動再開。無駄なリクエストと HubSpot サーバー負荷を 100% 根絶。

4b.11 統合チャット送信レイテンシ極小化（300ms）＆ 楽観的UIちらつき完全防止仕様#

4.21.1 送信クリティカルパスの最適化 (channelDispatcher.ts / cachedContact)#

• 背景と課題:
  • オペレーター画面から顧客へのメッセージ送信時、従来は dispatchOutboundMessage 内で都度 HubSpot API（fetchContactById）を同期実行し、送信後も HubSpot タイムライン同期（syncMessageToHubSpotInbox）が同期待ちとなっていたため、API レスポンスに 1,500〜2,500ms を要し、オペレーターの体感待ち時間と UI ブロックが発生していた。
• インメモリキャッシュ経由の非同期高速化:
  • sendUnifiedChatMessage（packages/operator-portal/server/controllers/unifiedChatController.js）において、既存のインメモリキャッシュ contactInfoCache.get(customerId)?.contact を cachedContact として dispatchOutboundMessage へ渡すパスを新設。キャッシュが存在する場合は HubSpot API への通信を完全スキップ。
  • チャネル送信ハンドラー（channelSendHandlers[channel]）実行直後に、Firestore appendChatMessage と setBotActiveForContact を並列（Promise.all）で実行。
  • 全ての appendChatMessage 呼び出しに明示的チャネル識別子を指定（LINE: 'line', Facebook: 'facebook', Portal: 'portal', Apply: 'apply'）。
  • 最も時間のかかる HubSpot CRM タイムライン同期（syncMessageToHubSpotInbox）および HubSpot コンタクトプロパティ更新（updateHubSpotContactProperties）をバックグラウンド実行（.catch(...) による非ブロッキング処理）へ完全移行。
  • これにより、送信 API のクリティカルパス応答時間を 従来の約2,000msから約300ms（約85%短縮）へと極小化。

4.21.2 チャット履歴重複判定ウィンドウの適正化 (chatMessageService.ts / 3,000ms)#

• 短文・定型返信の欠落防止:
  • addMessageToChannel におけるメッセージ重複除外（Deduplication）のタイムスタンプ許容範囲を、従来の 10分間（600,000ms） から 3秒間（3,000ms） に短縮。
  • 同一送信者による「承知いたしました。」「ありがとうございます。」などの定型挨拶や連続短文が、10分以内という過剰なウィンドウによって誤って破棄される不具合を恒久解消。

4.21.3 楽観的UIの一時行永続化・ちらつき完全防止 (chatRenderer.js / renderFeed)#

• 楽観的UI（Optimistic Update）の安定描画:
  • unified-chat.js および chat-space.js において、オペレーターが送信ボタンを押下した瞬間に temp-msg-${timestamp} を DOM に即時追加（送信中... バッジ表示）。
  • 直後の定期ポーリング（3秒間隔）や loadMessages(false) の呼び出しでフィードが再描画（feedEl.innerHTML = ''）された際、サーバー側に未反映の一時行が瞬間的に消滅し、サーバーからデータが返ったタイミングで再出現する「ちらつき・消失問題」を解消。
  • renderFeed 内で既存の一時行（.message-row[id^="temp-msg-"]）を保持し、サーバー履歴中に直近30秒以内に送信された一致メッセージが存在しない場合は、フィード末尾に一時行を再配置（Re-append）。サーバー反映が確認された時点で自動破棄。
  • フィード再描画時のスクロール位置（scrollTop）を一時行再配置後に復元・制御することで、視覚的なガタつき（Layout Shift）を完全に根絶。

4.21.4 過去メッセージの確定タイムスタンプ付与 ＆ 時間逆転・割り込み防止仕様 (chatHistory.ts / chatMessageService.ts)#

• 背景と課題:
  • 過去のバックフィルや一部の自動メッセージ生成において、Firestore chat_history 内のメッセージ要素（m）に timestamp プロパティが欠落しているドキュメントが存在していた。
  • chatMessageService.ts において、m.timestamp が未定義のメッセージに対して histData.timestamp - (messages.length - idx) * 2000 でフォールバック計算を行っていたが、histData.timestamp はオペレーターが新規メッセージを送信（appendChatMessage）するたびに最新時刻（Date.now()）へ更新されていた。
  • このため、本来数時間〜数日前の AI 挨拶メッセージ（タイムスタンプ欠落）が、新メッセージ送信のたびに「現在時刻マイナス数十秒」へ時刻が前進（タイムシフト）してしまい、オペレーターが連続して送ったメッセージの間に AI 応答が割り込んで直前メッセージが押し上げられ、画面上「上書きされた」ように見える現象が発生していた。
• 恒久的解決策:
  1. 全ドキュメントの確定タイムスタンプ一括付与（バックフィル完了）:
     • Firestore chat_history の全 141 ドキュメントをスキャンし、タイムスタンプが欠落していた 62 ドキュメント（計 1,154 メッセージ）に対して、会話の前後関係に基づいた不変の確定タイムスタンプを書き込み完了。
  2. appendChatMessage での不変タイムスタンプ自動担保:
     • chatHistory.ts 内のトランザクション実行時、読み込んだ既存メッセージに timestamp が存在しない場合は、その場で不変のタイムスタンプを付与して保存。将来にわたり時刻欠落メッセージが残存することを完全防止。
  3. chatMessageService.ts のフォールバック時刻アンカー固定:
     • 万が一タイムスタンプ未設定メッセージが存在した場合でも、更新日時（histData.timestamp）ではなくドキュメント作成日時（docCreateTime）または過去時刻にアンカーを固定し、新着メッセージ送信によって過去メッセージの時刻が前進・割り込みを起こすリスクを恒久根絶。
  4. 楽観的UIの完全一致照合:
     • chatRenderer.js における一時行（temp-msg-*）のサーバー照合を、部分一致（includes）から完全一致（===）に厳格化し、短い単語の誤検知・誤消滅を根絶。

4.21.5 「既読」ステータス表示の適正化（未読時の誤表示防止 ＆ LINE 仕様準拠）(chatRenderer.js)#

• 背景と課題:
  • LINE 公式アカウントの Messaging API では、セキュリティおよびプライバシー保護の仕様上、ユーザーが端末でメッセージを開封した（既読になった）事実を外部サーバーへ通知する Webhook イベントは提供されていない。
  • 従来、オペレーター管理画面の chatRenderer.js（renderFeed）において、オペレーター送信メッセージ（msg.sender === 'operator'）に対して <span class="read-status">既読</span> がハードコードされていた。
  • このため、メッセージ送信完了直後や相手がまだ LINE を開いていない未読状態であるにもかかわらず、画面上に「既読」と即時表示されてしまい、オペレーターに「相手がすでに閲覧した」という誤解を与える課題があった。
• 是正仕様:
  • 未返信状態のオペレーターメッセージに対しては、LINE 公式アプリのネイティブ挙動に準拠し、「既読」ラベルを表示せず送信時刻（例: 03:26）のみをすっきりと表示。
  • 顧客がそのメッセージ以降に会話・返信を送信したことが確認できた場合（other.sender === 'user' && other.timestamp > msg.timestamp）、または明示的フラグ（msg.isRead === true）が存在する場合にのみ「既読」バッジを表示。
  • これにより、未読時の虚偽の既読表示を完全に排除し、顧客の実際のリアクションに基づいた直感的かつ正確なステータス表示を実現。

4b.12 スマート・アダプティブ・ポーリング ＆ chatRenderer コンポーネント分割アーキテクチャ#

4.22.1 スマート・アダプティブ・ポーリング (unified-chat.js / chat-space.js)#

• 目的と概要:
  • オペレーター管理画面を開いたまま席を外した際や、チャットの動きがない待機時間帯におけるサーバー負荷（Cloud Run / Firestore 読み取りクォータ）を最大 70% 削減しつつ、アクティブ操作時の 0 秒ラグ感を両立。
• 適応型減速（Adaptive Decay）仕様:
  • FAST_POLL_INTERVAL: 3.5 秒（直近アクション後 1分以内の高速同期間隔）
  • MEDIUM_POLL_INTERVAL: 15 秒（1分〜5分間アイドル時の緩やかな同期間隔）
  • SLOW_POLL_INTERVAL: 30 秒（5分以上動きがない非アクティブ時の省エネ間隔）
• 即時ブースト (triggerAdaptiveBoost):
  • ユーザーによるクリック（click）、文字入力（keydown）、スマホタップ（touchstart）、メッセージ送信、顧客選択、チャネル切り替え時に即座にポーリングタイマーをリセットし、3.5 秒の超高速ポーリングへ復帰。
• Page Visibility API 連動:
  • タブが非表示（document.visibilityState === 'hidden'）になった瞬間、タイマーを完全停止（通信 0 回）。
  • 再度タブがアクティブになった瞬間に即座に最新データをフェッチし、3.5 秒ポーリングを再開。

4.22.2 フロントエンド描画モジュールの単一責任分割 (public/js/modules/chat/)#

• 分割構成: 従来の約 1,200 行モノリスであった chatRenderer.js を、関心事の分離（Separation of Concerns）に基づき 4 つのサブモジュールへ細分化：
  1. modules/chat/chatUtils.js: HTML エスケープ（XSS防止）、テキストエリア自動伸縮、日付境界線フォーマッター、書類引用ピル描画、アバターバッジ描画。
  2. modules/chat/messageParser.js: Markdown 解析、強調・箇条書き・見出し変換、画像/PDF/各種添付ファイルカード化、引用リプライボックス生成。
  3. modules/chat/crmCardRenderer.js: HubSpot 顧客カルテ描画、関連ディール一覧、Breeze AI プロファイルサマリー、重要契約項目ハイライト。
  4. modules/chat/feedRenderer.js: タイムライン描画（renderFeed）、楽観的UI一時行永続化、スクロール位置自動制御、チャットワークスペース HTML 生成。
• 完全な後方互換性の担保:
  • public/js/modules/chatRenderer.js は上記 4 モジュールを再エクスポート（Re-export Barrel）するエントリーポイントとして機能。
  • unified-chat.js や chat-space.js、既存のテストコードなどの呼び出し側は一切のパス変更なしで動作。

4b.13 統合チャット AI 返信アシスト（AI下書き作成）UI 不具合解消 ＆ 操作性・アクセシビリティ仕様#

4.23.1 CSS変数未定義によるボタン不可視化バグの是正#

• 根本原因:
  • packages/operator-portal/public/css/unified-chat.css および chat-space.css において、.ai-primary-btn が background: var(--primary-gradient) を参照していたが、:root スコープ内に --primary-gradient が未定義だった。
  • これにより、白背景の AI アシストパネル上でボタン背景が透明化し、文字色（#FFFFFF）と白背景が同化して「下書き作成ボタン」が完全に不可視化していた。
• 恒久対策:
  1. トークン定義の配備: :root に --primary-gradient: linear-gradient(135deg, #183832 0%, #1E463E 100%); を追加。
  2. 二重防護フォールバック: .ai-primary-btn に background: var(--primary-gradient, linear-gradient(135deg, #183832 0%, #1E463E 100%)); を設定し、万一トークンが欠落しても確実に視認可能。
  3. 下書き反映ボタンスタイル統一: chat-space.css に .ai-primary-btn.apply-btn { background: linear-gradient(135deg, #059669 0%, #10B981 100%); } を追加し、エメラルドグリーンのグラデーションで統一。

4.23.2 ボタン文言 ＆ アクセシビリティ・ツールチップの統一#

• 文言の標準化:
  • 生成アクション: 従来の「生成する」「提案を生成」を <span>下書きを作成</span> へ統一（feedRenderer.js および unified-chat.html）。
  • 反映アクション: 従来の「適用」を <span>この下書きを入力欄に反映</span>（クラス apply-btn）へ統一し、操作結果の予見性を向上。
• アクセシビリティ改善:
  • ツールバーの AI ボタン（#suggest-btn）に title="AI下書き作成（AI返信アシスト）" および aria-label="AI下書き作成" を設定し、スクリーンリーダーやツールチップでの認識性を向上。

4b.14 統合チャットスペース（Chat Space）顧客切り替え爆速化 ＆ 初期スクロール瞬時固定仕様#

4.24.1 課題と背景#

従来の Chat Space 実装では以下の 2 点の重大な UX 課題が存在していた：

1. 顧客切り替えラグ: 顧客キューで別のお客さまをクリックした際、chat-main-panel の DOM を毎回 innerHTML = buildChatWorkspaceHTML() で完全に破棄・再生成し、API レスポンスを待ってからレンダリングしていたため、切り替えに顕著な読み込み待ち（スピナー表示・ラグ）が発生していた。
2. スクロールアニメーションの違和感: チャット表示時に .chat-feed の CSS に scroll-behavior: smooth; が設定されていたため、チャット履歴を描画した直後に画面上部から最下部へとスクロールされる様子が見えてしまい、直近メッセージが即座に読めないストレスとなっていた。

4.24.2 スクロールアニメーションの完全撤廃と直近メッセージ瞬時固定#

• CSS scroll-behavior: auto; への統一:
  • packages/operator-portal/public/css/chat-space.css および unified-chat.css の .chat-feed において、scroll-behavior: smooth; を廃止し scroll-behavior: auto; を適用。
• feedRenderer における瞬時最下部固定 (modules/chat/feedRenderer.js):
  • 初回描画時または最下部付近にいる場合（isInitial || isNearBottom）：

    feedEl.style.scrollBehavior = 'auto';
    feedEl.scrollTop = feedEl.scrollHeight;
    requestAnimationFrame(() => {
      feedEl.scrollTop = feedEl.scrollHeight;
    });
    

  • requestAnimationFrame を併用することで、DOM のレイアウト・ペイント完了後もアニメーションなしで確実に最下部に瞬時固定。

4.24.3 DOM 破壊防止 ＆ SWR クライアントメモリキャッシュ (chat-space.js)#

• インメモリ SWR キャッシュ (customerChatCache):
  • const customerChatCache = new Map(); を配備（キー: customerId, 値: { channels, contact, deals, timestamp }）。
  • API からメッセージおよび CRM 顧客情報を取得するたびに customerChatCache に保存し、最新状態を維持。
• ワークスペース DOM の再利用（DOM 破壊防止）:
  • selectCustomer(id) 実行時、document.getElementById('chat-feed') が既に存在する場合は buildChatWorkspaceHTML() による DOM 破棄・再生成をスキップ。既存の入力バーやワークスペースを破棄せず再利用し、イベントリスナーの無駄な再バインドを防止。
• 0ms 即時ヘッダー・チャット描画:
  • 顧客一覧キュー（customersList）の情報を用いて、クリックと同時に 0ms で updateCustomerHeader を実行。
  • キャッシュが存在する場合（customerChatCache.has(id)）： キャッシュデータから 0ms で即座に renderTabs および renderFeed を実行し、直近チャット履歴を瞬時に表示。
  • キャッシュが存在しない初回のみ： ワークスペースを壊さず #chat-feed のみローダー表示。
• バックグラウンド非同期更新 ＆ レースコンディション対策:
  • キャッシュ描画後、バックグラウンドで loadActiveMessages(true) を非同期実行して最新の差分を取得・キャッシュ更新。
  • 連続クリック時のレースコンディションを防ぐため、リクエスト開始時の targetId と完了時の activeCustomerId の一致検証ガードを配備。

id: "05_quote_maker" title: "5. Gemini 見積書メーカー（HubSpot Projects & UI Extensions 連携版）技術仕様" category: "system" packages: - "packages/portal-quote-prototype" - "gemini-quote-generator" cloud_run: - "gemini-quote-generator" - "sorai-quote-maker" endpoints: - "POST /api/analyze-quote" - "POST /api/generate-quote" - "GET /q/[token]" - "GET /api/properties/fetch-details" - "POST /api/properties/create-deal-note" secrets: - "GEMINI_API_KEY" - "HUBSPOT_ACCESS_TOKEN" - "HUBSPOT_REFRESH_TOKEN" - "HUBSPOT_CLIENT_SECRET" - "HUBSPOT_CLIENT_ID" - "gemini-quote-hubspot-client-id" - "gemini-quote-hubspot-client-secret" - "hubspot-refresh-token" databases: - "quote_simulations" - "quote_tokens" - "property_inquiries"#

5. Gemini 見積書メーカー（HubSpot Projects & UI Extensions 連携版）技術仕様#

5.1 Next.js アプリケーションの全体構成#

アプリケーションは Next.js (App Router) をベースに構築され、HubSpotのローカル開発モデルである HubSpot Projects (UI Extensions) のフロントエンドカード用コードを内包している。

ディレクトリ構造と主要ファイル#

• src/app/api/deal-info/: 取引・顧客情報事前取得API (HubSpot CRM Deals/Contacts連携)
• src/app/api/analyze-quote/: 書類解析API (Gemini連携・取引情報フォールバック)
• src/app/api/generate-quote/: PDF生成＆HubSpot・GCS登録API
• src/app/q/[token]/: 見積書スマート短縮共有URL ＆ HubSpot CDNリダイレクト (Zero GCP Egress Cost)
• src/app/api/share/: PDF安全共有用リダイレクトAPI (レガシー/GCSフォールバック)
• src/app/api/properties/fetch-details/: ポータル物件情報・空室詳細自動取得API
• src/app/api/properties/create-deal-note/: 物件調査タイムラインNote自動起票API
• src/app/api/properties/export-csv/: 調査物件CSVエクスポートAPI
• src/assets/logo.png: PDF用コーポレートロゴ
• src/constants/brand.ts: ブランドカラー・会社情報等の定数
• src/fonts/NotoSansJP-Regular.otf / NotoSansJP-Bold.otf: PDF用日本語フォント
• src/lib/gemini.ts: Gemini API クライアント＆抽出プロンプト
• src/lib/hubspot.ts: HubSpot API クライアント＆OAuth処理
• src/lib/quoteToken.ts: 見積書共有トークン生成＆検証 (Base64URL)
• src/lib/pdfGenerator.ts: pdfmakeによるPDF生成ロジック
• src/lib/secrets.ts: GCP Secret Manager 連携＆キャッシュ
• src/lib/storage.ts: GCSアップロード＆署名付きURL生成
• hubspot-project/: HubSpot UI Extensions プロジェクト
• Dockerfile: アプリデプロイ用 (Cloud Run対応)

主要技術スタック#

• フレームワーク: Next.js 15+ (App Router, TypeScript)
• AI 連携: Google GenAI SDK (@google/genai)
• PDF 生成: pdfmake
• ストレージ連携: Google Cloud Storage (@google-cloud/storage)
• シークレット管理: Google Cloud Secret Manager (@google-cloud/secret-manager)
• CRM 連携: HubSpot API Client (@hubspot/api-client)

シークレットの動的解決と管理 (src/lib/secrets.ts)#

• 機密情報（APIキーやトークン）は、Google Cloud Secret Manager から動的に解決する構成となっている。
• toGcpSecretName 関数により、アプリ内のシークレット名をGCP側のリソース名にマッピング。
  • GEMINI_API_KEY ➔ gemini-api-key
  • HUBSPOT_ACCESS_TOKEN ➔ hubspot-access-token
  • HUBSPOT_REFRESH_TOKEN ➔ hubspot-refresh-token
  • HUBSPOT_CLIENT_SECRET ➔ gemini-quote-hubspot-client-secret
  • HUBSPOT_CLIENT_ID ➔ gemini-quote-hubspot-client-id
• HMRによる再初期化を防ぐため、global オブジェクト上にキャッシュ用 Map を保持し、無駄な API コールによる遅延を抑制。

5.2 PDF生成機能の仕様#

pdfmake 統合とバンドラー回避策#

Next.js (Webpack / Turbopack) で pdfmake をサーバーサイドで動作させる際、ファイル読み込みやモジュール解決のエラーが発生するのを防ぐため、eval(require(...)) を用いて絶対パスで動的ロードする特殊なワークアラウンドを採用している。

const printerPath = path.join(process.cwd(), 'node_modules/pdfmake/js/Printer.js');
const printerModule = eval(`require('${printerPath.replace(/\\/g, '\\\\')}')`);
const PdfPrinter = printerModule.default || printerModule;

日本語フォント設定と文字化け対策#

PDF上の日本語が文字化けするのを防ぐため、Noto Sans JP フォントをアセットとして内包し、defaultStyle として設定している。

• フォント定義: Normal: src/fonts/NotoSansJP-Regular.otf / Bold: src/fonts/NotoSansJP-Bold.otf
• pdfmake設定: Roboto というキーに対して NotoSansJP フォントを割り当て、defaultStyle: { font: 'Roboto' } と指定することでドキュメント全体の標準フォントを日本語対応させている。

ブランドアセットの埋め込み#

• ロゴ画像の埋め込み: src/assets/logo.png を起動時に fs.readFileSync で読み込み、Base64 Data URI に変換した上でドキュメント定義の image プロパティへ設定。
• ブランドカラーの統一: src/constants/brand.ts で定義されたコーポレートカラーを用いて統一感のあるデザインを構築している。
  • ゴールド (主色): #d4af37 (御見積書タイトル下線、お見積金額背景枠、テーブル罫線、合計金額表示など)
  • スレートグレー (ヘッダー/タイトル): #4c5a67
  • クリーム (背景): #f9f7f2
  • ダークテキスト / グレーテキスト: #2d353e / #6b7785

特殊なフォーマット・ビジネスロジック#

• 金額表記: ¥X,XXX- の形式で統一フォーマットされる。
• 月額固定費用（賃料・管理費）の別枠表示:
  • 見積書上部の御見積金額枠の下に、専用の【月額固定費用】枠（monthlyBaseLabel / monthlyBaseValue）を新設。
  • 「月額賃料 (家賃)」および「月額管理費・共益費」を初期費用明細とは独立した別枠としてハイライト表示（例: 賃料: ¥142,000 / 管理費・共益費: ¥4,000 (月額合計: ¥146,000)）。
  • 見積書下部の備考欄（remarksRows）にも「月額基本費用」の明細行を自動付記。
• 日割り家賃・前家賃と1ヶ月分通常家賃の重複防止＆切替制御:
  • 日割り計算なし（通常契約）: 明細に「賃料（1ヶ月分）」「管理費（1ヶ月分）」を計上。
  • 日割り計算あり: 日割り計算アシスタント適用時に、元の1ヶ月分賃料・管理費を明細から自動除外し、「日割り賃料（期間）」「日割り管理費（期間）」および「前家賃（翌月分）」「前管理費（翌月分）」へと安全に置換（賃料が+1ヶ月過剰計上されるバグを100%防止）。
  • 日割り解除機能: 「日割りを解除して1ヶ月分に戻す」ボタンにより、ワンクリックで通常の1ヶ月分明細構成（賃料・管理費）へと即座に復元可能。
• 明細テーブルのリアルタイム計算 ＆ 小計・合計表示:
  • 手動手直し画面の明細テーブルに「金額（小計）」列を新設し、各品目行の 数量 × 単価 をリアルタイム算出表示。
  • テーブルフッター（tfoot）に「御見積合計金額」行を新設し、品目行の追加・削除・単価変更・数量変更が即座に合計へ反映されることを視覚的に保証。
  • 日割り計算アシスタント内に「①日割り分小計」「②前家賃分小計」「明細に反映される賃料計」の完全な内訳プレビューを表示し、日割り分と翌月前家賃がどのように合算・展開されるかを1円単位で可視化。
• 宛名（お客様名）の完全任意化 ＆ 物件名主タイトル表示（ミス防止）:
  • 初期費用見積書における氏名漢字や名義不一致のトラブルを防ぐため、宛名（customerName）の自動プリロード・自動補完を完全廃止。
  • 宛名未入力時は「関係者 御中」やダミー名を一切描画せず、「物件名: ○○」を最上部に品格ある主見出しとしてレイアウト配置。
  • 宛名が明示的に手動入力された場合のみ「○○ 様」として描画。
• 合計金額の自動再計算: 手動調整や品目の追加による計算ミスを防ぐため、PDF生成直前に data.items.reduce((sum, item) => sum + item.price * item.quantity, 0) により、サーバーサイドで厳密に合計金額を再計算する。
• 「敷金償却」の金額非表示ロジック: 不動産特有の商習慣への対応として、品名に「敷金」を含み、かつ「償却」「償金」「敷引き」のいずれかを含む品目について、単価 (price) が 0円である場合、数量・単価・金額欄の表示を空欄にする。

5.3 HubSpot ＆ データ連携フロー#

全体連携アーキテクチャ#

1. 取引・顧客情報の事前解決: ユーザーが HubSpot 取引詳細画面の UI Extension カードから「見積書を作成する」をクリックすると iframe 内に Next.js 画面をロード。URLパラメータの dealId に基づき /api/deal-info がバックグラウンドで Deal/Contact 情報を先行取得（物件名、契約者名、月額賃料、共益費）。
2. 見積書原案のアップロード＆解析: アップロードされた書類画像/PDFまたはポータルURLを /api/analyze-quote API へ送信し、Gemini 3.8 Flash（gemini-3.8-flash, Thinking Level: High）で構造化データ（PropertyName, 品目リスト、日割り賃料等）を高精度に抽出。書類上で物件名・顧客名が未記載・不鮮明な場合でも、Dealの取得値へ自動フォールバック。
3. 元図面プレビュー＆手動修正: 画面左側でアップロードされた元図面（PDF/画像）を高精細Canvasまたはブラウザ標準PDFビューアーでプレビュー・拡大縮小しながら、右側のフォームで見積明細や日割り計算結果を手動手直し。
4. PDFの生成と登録: ユーザーが確認・修正したデータをもとに /api/generate-quote API を実行。サーバーサイドで PDF を生成。

HubSpot Files CDN ＆ スマート短縮共有URL (/q/[token]) による完全0円エグレス設計 (Approach A)#

• HubSpot Files アップロード (access: 'PUBLIC_NOT_INDEXABLE'):
  • PDF生成時に HubSpot Files API v3 へ access: 'PUBLIC_NOT_INDEXABLE'（検索エンジンにインデックスされない安全な公開CDN設定）でアップロード。
  • APIレスポンスから fileId および HubSpot グローバルCDN直結URL（fileUrl: https://<portalId>.fs1.hubspotusercontent-na1.net/...）を取得。
• スマート短縮URL生成 (/q/[token]) ＆ Base64URL トークン設計 (src/lib/quoteToken.ts):
  • 取引ID・ファイルID・ファイル名・発行日時・有効期限・HubSpot CDN URL を内包したURLセーフな Base64URL トークンを生成。
  • 共有URLとして短く美しい ${baseUrl}/q/${encodedToken} を発行し、HubSpot 取引タイムラインNoteおよび完了画面へ記録。
• GCP Egress 帯域費用 0円アーキテクチャ (src/app/q/[token]/route.ts):
  1. トークン高速デコード＆有効期限検証: Base64URL トークンを即座にデコードし、指定日数（デフォルト30日間）を超過している場合はフレンドリーな日本語HTML通知画面（「見積書の共有有効期限が切れています。必要な場合は担当者へ再発行をご依頼ください。」）を返却。
  2. HubSpot CDN 302 リダイレクト: トークン内の CDN URL または getHubSpotFileUrl(fileId) / getHubSpotSignedUrl(fileId) 経由で取得した HubSpot CDN URL へ HTTP 302 リダイレクト。
  3. 帯域コストの完全オフロード: PDFバイナリのダウンロードストリームが HubSpot CDN（Cloudflare/AWS CloudFront基盤）からエンドユーザーへ直接配信されるため、Cloud Run / GCP 側のネットワーク下り（Egress）データ転送費用が 0円（完全無料） となる。
  4. 多重フォールバック設計: HubSpot CDN 取得失敗時でも GCS（Google Cloud Storage）の一時署名付きURL（getShortLivedSignedUrl）へと自動フォールバック。

Google Cloud Storage によるバックアップ保存#

• GCSバケット保存: バケット（デフォルト: sorai-quote-pdfs）内の quotes/quote_[dealId]_[timestamp].pdf にPDFバックアップを保存。
• レガシー共有エンドポイント (src/app/api/share/route.ts): 過去に発行されたリンクへの後方互換性として、ファイル名パラメータによる GCS 署名付き URL リダイレクトも継続保持。

5.4 初期費用シミュレーター (/quote) 技術仕様#

5.4.1 概要・システム構成#

• URL/図面スクショ連動型解析エンジン:
  • ポータルサイト（SUUMO, HOME'S, at home 等）の物件詳細URL、または募集図面・初期費用見積書のスクリーンショット画像をアップロードすることで、物件名・住所・賃料・管理費・敷金・礼金・仲介手数料・その他付帯項目を自動抽出。
  • フロントエンドは直感的なステップUIとレスポンシブデザイン（モバイル最優先）を採用し、面倒な手入力なしで即座に初期費用の総額・内訳・適正相場を算出。
• 推論モデル & 抽出最適化 (gemini-3.8-flash / gemini-3.5-flash-lite):
  • 画像・URLからの抽出には gemini-3.5-flash-lite（Structured Outputs ＆ 思考オフ）を採用し、0.2〜0.5秒の超爆速応答と高精度な分解を両立。
• 5言語完全ローカライズ (JA / EN / VI / RU / ID):
  • 日本語（JA）：初期費用の透明化、不要な付帯費用の精査、初期費用節約ノウハウを前面に提示。
  • 外国語（EN / VI / RU / ID）：多言語LINEサポート、ビザ種別に応じた審査サポート、保証人不要プラン、多言語対応の施設情報などを提供。

5.4.2 データ蓄積・BigQuery需要データ連携・分散クォータ安全制御#

• グローバル日次クォータ制限（Firestore トランザクション分散共有）:
  • APIコールの過剰課金を恒久防止するため、1日最大 100回/日（DAILY_API_LIMIT = 100）の安全上限を設定。
  • common/services/quota.js の checkAndUpdateGlobalQuota('global_quote', 100) により、Firestore トランザクションを用いてアトミックに制御。
• 非同期ストリーミング登録 (sorai_analytics.quote_logs):
  • PII を除外（サニタイズ）した上で、物件所在地、希望エリア、家賃帯、敷金礼金の条件、他社付帯費用の構成データを BigQuery へ非同期ストリーミング登録。
• Cloud Logging 完全構造化 JSON ログ同期:
  • Cloud Run / Google Cloud Logging 向けの完全構造化 JSON ログを出力。

5.4.3 LINE/相見積もり誘導動線 ＆ HubSpot公式HP統合#

• LINE公式へのシームレスなワンタップ遷移:
  • シミュレーション結果画面に「この条件で相見積もり・空室確認をLINEで依頼する」ボタンを配置。
• HubSpot公式HPヘッダー・トップ全面統合:
  • 全5言語の共通ヘッダーおよびHPトップのファーストビュー直下にシミュレーターへの誘導バナーを統合。

5.4.4 ポータル諸費用・内訳テキスト抽出＆動的計算仕様 (diagnoseService.js / priceParser.js)#

• 付帯費用・内訳テキストの分解抽出 (parseIncidentalsBreakdown / otherFees):
  • スラッシュ区切り・カッコ内訳付き付帯費用を自動展開・分解して抽出。
• 保証会社初回保証料のピンポイント抽出と月額保証料の峻別:
  • 初回 や 契約時 に紐づくパーセンテージ（例: 50%）を最優先特定し、月額保証料との混同を防止。
• 日本語文字列＆価格パーサー強化 (normalizeJapaneseString / parsePriceToNumber):
  • 全角英数記号の完全正規化。
• 初期費用（一時金）と月額固定費用の峻別:
  • 契約時一時金のみを初期費用合計に加算し、月額費用は分離管理。

5.4.5 5層階層型ハイブリッド抽出エンジン ＆ TypeScript完全移行 (diagnoseService.ts)#

• TypeScript 完全移行と後方互換リダイレクト (diagnoseService.ts / diagnoseService.js):
  • packages/portal-quote-prototype/services/diagnoseService.js を diagnoseService.ts へ完全リファクタリング。common/types/quote.ts のドメイン型を 100% 適用し、引数・戻り値・内部状態の型安全性を確立（npm run typecheck 0 errors）。
  • diagnoseService.js に export * from './diagnoseService.ts'; を配置し、既存の呼び出し元（server.js や line-bot）への破壊的変更をゼロ化。
• 5層階層型ハイブリッド抽出パイプライン (Tiered Hybrid Extraction):
  • Tier 1 (高速キャッシュ): LRU キャッシュ（URLハッシュ）による重複アクセスの 0ms・0円レスポンス。
  • Tier 2 (JSON-LD 構造化データ抽出 - jsonLdExtractor.ts): HTML 内の <script type="application/ld+json">（SingleFamilyResidence, Product, RealEstateListing）を高速パースし、物件名・住所・賃料・面積・間取りを 5ms・0円・100%精度で先行抽出。
  • Tier 3 (ポータル別 DOM アダプター - portalAdapters.ts): cheerio を活用し、SUUMO、LIFULL HOME'S、at home の専用セレクタから賃料・管理費・敷金・礼金・保証料・鍵交換代・火災保険・付帯費用を展開抽出。
  • Tier 4 (汎用テーブルパーサー): 未知のポータルサイトや提携サイト（賃貸スモッカ、いい部屋ネット、エイブル等）でも、th/td のテキスト見出し（「賃料」「敷金」「礼金」「管理費」等）を自動走査して抽出。
  • Tier 5 (Gemini 3.5 Flash-Lite スマートフォールバック): ルールベース（Tier 2〜4）で賃料等の主要項目が欠落している場合のみ、クリーンアップ済み HTML を gemini-3.5-flash-lite（Structured Outputs, Thinking Budget 0）に渡して補完。
• 主要ポータル対応ドメインの拡充 (validatePortalUrl):
  • ALLOWED_PORTAL_HOST_SUFFIXES に「賃貸スモッカ（smocca.jp）」「Yahoo!不動産（realestate.yahoo.co.jp）」「goo住宅・不動産（house.goo.ne.jp）」「CHINTAI（chintai.com）」を追加。
• 大幅な高速化とAPIコスト削減効果:
  • 主要ポータルの標準掲載物件であれば、Gemini API を呼ばずに 0.05〜0.2秒の超爆速レスポンス（体感10倍速） で完了。
  • API呼び出しコストを 80〜90% 削減 し、日次API制限（DAILY_API_LIMIT = 100）を消費しないため、大量のユーザー利用にも耐えうる高耐久アーキテクチャを実現。

5.5 HubSpot 取引連携 SUUMO物件一括調査・空室確認メモ自動記録機能 (hubspot-quote-generator)#

5.5.1 機能概要#

• HubSpot 取引（Deal）詳細画面の専用拡張カード（PropertyCard.tsx）から、複数のSUUMO物件URLを一括抽出・空室確認メモとしてHubSpot Noteへ自動起票。

5.5.2 アーキテクチャと実装構成#

• フロントエンド (PropertyInvestigationView.tsx): 3ステップUI、募集状況トグル、主要設備タグ。
• 高速DOMスクレイピング & AIハイブリッド (suumoPropertyScraper.ts): cheerio + Gemini フォールバック。
• HubSpot CRM Notes 連携 (hubspot.ts, create-deal-note/route.ts): レスポンシブHTMLテーブル生成。

5.5.3 図面自動マッチング重複判定エンジン (propertyDuplicationMatcher.ts)#

• 過去Note本文から物件名・住所・URLを自動抽出し、今回のSUUMO調査物件と突合して ⚠️ 提案済（重複） バッジを表示。

5.5.4 HTML軽量化と文字数制限（65,536文字）超過防止ガード#

• インラインCSS軽量化および55,000文字超過時の緊急ミニフィケーションフェイルセーフ。

5.5.5 12列標準表フォーマット（Excel・スプレッドシート完全対応）#

• 全12列の標準出力項目およびTSVクリップボードコピー機能。

5.6 見積書ジェネレーター フロントエンド・マルチプレビュー仕様 (DocumentPreview.tsx, SuccessStep.tsx)#

5.6.1 ハイブリッドレンダリング＆フォールバック設計 (DocumentPreview.tsx)#

• PDF.js 高精細Canvasモードとブラウザ標準ネイティブ埋め込みモードの自動フォールバック。

5.6.2 見積作成後の元図面＆生成見積書マルチプレビュー (SuccessStep.tsx)#

• スプリットレイアウト、タブ切替型プレビュー（生成見積書 / アップロード元図面）、Blob URL 自動破棄。

5.7 Gemini Context Caching（コンテキストキャッシュ）アーキテクチャ#

5.7.1 概要とコスト・レイテンシ最適化#

• 静的ナレッジコンテキストを事前キャッシュ化し、入力トークン費用を最大 75%〜90% 削減、TTFT短縮。

5.7.2 キャッシュマネージャー仕様 (packages/common/services/contextCacheManager.js)#

• TTL 2時間、自動無効化リスナー、高耐障害性フォールバック。

5.8 Gemini Structured Outputs（型定義JSON出力）＆ Thinking Budget 最適化仕様#

• responseMimeType: 'application/json'、JSON Schema、情報抽出タスクでの thinkingBudget: 0（思考オフ）適用。

5.9 初期費用シミュレーター Structured Outputs ＆ Gemini 3.5 Flash-Lite 最適化仕様#

• quoteDiagnosticSchema（17項目 JSON Schema）、parseIncidentalsBreakdown による空白区切り付帯費用分解。

5.10 国土交通省 物件所在地・公的データAI診断（locationDiagnosis）連携仕様#

• 住所抽出時に国交省公的データ（用途地域・地価公示・浸水想定・土砂災害・生活インフラ）を自動付加。

5.11 帯替え図面・PDF・ポータルURL入力による見積書自動作成仕様 (hubspot-quote-generator)#

5.11.1 機能概要・背景#

• 概要: 担当者が deal-service 等で生成した「帯替え図面PDFのURL（HubSpot Files / GCS）」や「Google ドライブ共有URL」「SUUMO等ポータル物件URL」を入力するだけで、サーバーサイドで自動フェッチ・MIME判定を行い、Gemini 3.7 Flash により初期費用明細書データを自動構造化抽出する機能。
• メリット: ローカルPCにPDFを保存・ドラッグ＆ドロップする手間を削減し、帯替え図面作成フローからURLをコピー＆ペーストするだけで即座に見積書作成が可能。

5.11.2 URL解決・フェッチ・MIME判定アーキテクチャ (src/app/api/analyze-quote/route.ts)#

1. Google ドライブ共有リンク正規化:
   • drive.google.com/file/d/FILE_ID/view ➔ drive.google.com/uc?export=download&id=FILE_ID へ自動変換。
2. HubSpot Files 認証トークン自動付与:
   • api.hubapi.com/files/... 等の内部URLに対しては HUBSPOT_ACCESS_TOKEN を付与してセキュアに取得。
3. MIMEタイプ自動判定:
   • Content-Type ヘッダーおよび URL 拡張子・マジックバイト（%PDF）から PDF / 画像（PNG, JPEG, WebP）/ HTML を自動判定。
4. Gemini 解析エンジンの動的分岐:
   • PDF / 画像バイナリ: analyzeDocumentForQuote(fileBuffer, mimeType, additionalInstructions) で Gemini 3.7 Flash Vision により図面を解析。
   • HTML / ポータルページ: analyzeHtmlForQuote(htmlContent, url, additionalInstructions) で物件情報から初期費用内訳（前家賃、前共益費、敷礼、仲介手数料、初回保証料、火災保険等）を自動算定。
5. プレビュー連携:
   • 解析成功後、入力URLを previewUrl として返却し、編集画面（EditFormStep / DocumentPreview）の左側パネルで図面をそのまま表示。

5.11.3 フロントエンド UI / UX 仕様 (UploadStep.tsx, useQuoteGenerator.ts)#

• URL入力 / ファイル添付 セグメントタブ:
  • 「🔗 URLを入力（帯替え図面・ポータル）」と「📁 ファイルを添付」をワンタップで直感的に切り替え。
• リアルタイム入力バリデーション ＆ 追加指示対応:
  • 有効なURLまたはファイルが存在する場合に「見積データを解析する」ボタンが活性化。
  • ペット敷金追加や仲介手数料割引などの追加指示（プロンプト上書き）も両モードでシームレスに指定可能。

5.12 ポータル初期費用相見積もりプロトタイプ（Portal Quote Prototype）＆ TypeScript 型安全仕様#

ポータル物件URL（SUUMO・LIFULL HOME'S・at home 等）や図面スクリーンショット画像から初期費用を即座に試算し、他社請求とソライ東京の仲介手数料・付帯費用ゼロプランを対比するシミュレーションサービス（packages/portal-quote-prototype）の設計・型安全仕様。

5.12.1 アーキテクチャと多重セキュリティ#

• SSRF ＆ 不正リクエスト防御 (validatePortalUrl):
  • GCE メタデータサーバー IP（169.254.169.254）、ローカルホスト（127.0.0.1, localhost）、プライベート IP（10.0.0.0/8, 192.168.0.0/16）、ファイルプロトコル（file://, gopher://）の完全遮断。
  • 許可ポータルドメイン（suumo.jp, homes.co.jp, athome.co.jp, chintai.net, mynavi.jp, minimini.jp 等）の厳格な検証。
• 軽量 HTML クリーニング ＆ トークン削減:
  • 不要タグ（<script>, <style>, <svg>, <nav>, <footer>, <header>, コメント、Base64 画像データ）を自動除去し、最大 30,000 文字以内に正規化して Gemini に供給。
• BigQuery 非同期分析ロギング (logQuoteDiagnosis):
  • setImmediate による 0ms 非同期実行。物件名、賃料、他社総額、ソライ総額、削減額、削減率、不要オプション総額、SHA-256 ソルトハッシュ化 IP を sorai_analytics.quote_logs へストリーミングインサート。

5.12.2 TypeScript 型定義 ＆ 静的検査環境 (types/quote.ts, tsconfig.json)#

• ドメイン型定義 (packages/common/types/quote.ts):
  • QuoteOtherFeeItem: その他諸費用項目（名称・金額・一時金/月額種別）。
  • QuoteExtractedPropertyData: ポータル・画像から抽出された物件諸条件（賃料・共益費・敷礼・保証料・鍵交換代・火災保険・付帯費用リスト）。
  • QuoteBreakdownItem & QuoteSideComparison: 費用内訳明細および他社/ソライ東京比較オブジェクト。
  • QuoteComparisonResult: 物件サマリー、相見積もり比較（削減額・削減率・日割り家賃）、国交省公的データAI診断結果。
  • QuoteDiagnoseRequest, QuoteRecalculateRequest, QuoteAnalyticsLogPayload の完全型定義。
• 型検証環境 (packages/portal-quote-prototype/tsconfig.json):
  • NodeNext / ESNext / strict: true / allowJs: true / checkJs: false / noEmit: true
  • ルート package.json の "typecheck" スクリプトに統合し、モノレポ全 9 パッケージの並行静的型検査を確立。
• JSDoc / TS 型注釈 ＆ 実装ファイル:
  • server.js（Express app、/api/diagnose、/api/recalculate、/api/health）
  • services/diagnoseService.ts / diagnoseService.js（TypeScript 完全移行・型注釈、parsePriceToNumber, validatePortalUrl, diagnoseFromUrl, diagnoseFromImage, calculateQuoteComparison, キャッシュ管理）
  • services/extractors/jsonLdExtractor.ts（<script type="application/ld+json"> 不動産構造化データ抽出）
  • services/extractors/portalAdapters.ts（SUUMO, HOME'S, at home, スモッカ, 汎用ポータルテーブルDOMアダプター）
  • services/analyticsService.js（logQuoteDiagnosis, BigQuery クライアント、IP ハッシュ化）
• 単体テストスイート (tests/quote.test.js):
  • 価格パース（数値・小数・万・漢数字・全角文字・異常値）、SSRF防御、許可ドメイン判定（スモッカ/Yahoo!/goo対応）、JSON-LD抽出、マルチポータルDOM抽出、相見積もり計算ロジックを包括検証（全31テスト）。

id: "06_deal_extractor" title: "6. Deal Extractor サービス（deal-service）仕様" category: "system" packages: - "packages/deal-service" - "packages/common" cloud_run: - "real-estate-chatbot-deal-service" - "sorai-deal-service" endpoints: - "POST /api/auth/iframe-token" - "POST /api/deals/:dealId/extract" - "POST /api/deals/:dealId/match-floorplans-stream" - "GET /api/deals/modal/:dealId" - "GET /api/health" secrets: - "GEMINI_API_KEY" - "HUBSPOT_ACCESS_TOKEN" - "GOOGLE_APPLICATION_CREDENTIALS" databases: - "floor_plan_history" - "deal_extractions"#

6. Deal Extractor サービス（deal-service）仕様#

6.1 サービス概要・全体フロー (Overview & Flow)#

• 役割: HubSpot CRM上の不動産取引（Deals）に関連付けられた Google ドライブ内の各種契約書類（重要事項説明書、紛争防止条例説明書、賃貸住宅契約書など）や、担当者がアップロードした多様な形式の間取り図面・物件チラシから、重要取引条件や物件スペックを生成AI（Vertex AI / Gemini API）を用いて自動抽出・照合し、HubSpot CRM および Firestore に構造化データとして同期・永続化する独立したマイクロサービス。
• 全体データフロー:
  1. トリガー: HubSpotカスタムカード（UI Extension）の「書類解析を実行」ボタン、またはIframe埋め込みモーダルからのファイルアップロードによって /api/deals/:dealId/extract または /api/deals/:dealId/match-floorplans-stream にリクエストが送信される。
  2. 書類URLロードとキャッシュ検証: 対象の取引に紐付く Google ドライブのファイル情報またはアップロードバイナリを取得。SHA-256ハッシュを用いて同一ファイルの重複解析をチェック。
  3. PDF/画像ストリーム＆インメモリ変換: Google API 経由またはマルチパートフォームで受信したバイナリを処理。画像フォーマット（WebP/HEIC/TIFF/BMP/GIF/AVIF等）は sharp で PNG 透過変換し pdf-lib でインメモリ結合。
  4. SSE リアルタイムストリーミング ＆ Heartbeat: 進捗（解析中、PDF結合、HubSpotアップロード等）を SSE (Server-Sent Events) で逐次フロントエンドへ配信。Gemini呼び出し等の長時間非同期処理中は 15秒間隔の keep-alive コメントを送信しタイムアウトを防止。
  5. Vertex AI Gemini 呼び出し: 抽出テキスト・画像を Vertex AI SDK 経由で Gemini モデル（Gemini 3.5 Flash Lite / Gemini 3.7 Flash）へ送信。JSON Schema に沿って契約条件や間取り情報を構造化抽出。正確なトークン使用量（usageMetadata）を Cloud Logging に記録。
  6. CRM / DB同期 ＆ 重複トラッキング:
     • 抽出データを HubSpot 取引プロパティへ書き込み（PATCH）。
     • 紐付く連絡先（Contacts）のカスタムプロパティを同期更新。
     • Firestore floor_plan_history コレクションに解析履歴（SHA-256、日時、回数）を記録。
     • HubSpot タイムラインにスタッフ確認用ノート（重複警告バナー付き）および顧客提案用ノートを自動起票。

6.2 主要モジュール構成 (Directory & Modules)#

モノレポ内の独立ワークスペース packages/deal-service として構成されている。

• packages/deal-service/package.json: 依存パッケージ管理。express, sharp, pdf-lib, google-auth-library, googleapis, @google-cloud/vertexai, @google-cloud/firestore を利用。
• packages/deal-service/server.js: Webサーバーのスタートアップエントリーポイント。Port 3008 で起動。
• packages/deal-service/app.js: Webhooks 認証、Helmet CSP (frameAncestors 拡張)、共通エラーハンドラ、IPレートリミットミドルウェア、Iframeトークン生成（/api/auth/iframe-token）、メインルーティング（/api/deals/...）を定義。
• packages/deal-service/controllers/matchingController.js: バッチ照合および SSE リアルタイム進捗ストリーミングの HTTP ハンドラー。
• packages/deal-service/services/dealService.js: Google ドライブ連携、Vertex AI / Gemini クライアント初期化、トークン使用量ロギング、HubSpot API連携、データ保存ロジックを含む中核。
• packages/deal-service/services/fontCache.js: Noto Sans JP フォントおよびソライ東京ロゴのインメモリ/ファイルキャッシュ管理、Sharp による画像透過変換。
• packages/deal-service/services/hubspotFileService.js: HubSpot Files API アップロード機能（sheetsService.js との循環参照を完全解消）。
• packages/deal-service/services/floorPlanHistory.js: Firestore floor_plan_history コレクションへの SHA-256 照合履歴記録・重複チェック。
• packages/deal-service/services/noteFormatter.js: 物件名クレンジング、顧客送信用テキスト整形、HubSpot タイムライン用 HTML レンダリング。
• packages/deal-service/services/hubspotNoteService.js: HubSpot タイムライン個別ノートおよび全物件まとめサマリーノート起票サービス。
• packages/deal-service/services/matchingOrchestrator.js: Vertex AI Gemini による間取り図面 AI マッチング、帯消し・ソライ東京帯載せ合成、並列オーケストレーション。
• packages/deal-service/services/sheetsService.js: 全照合結果の UTF-8 BOM CSV / Google スプレッドシート生成・HubSpot Files 連携。
• packages/deal-service/services/matchingService.js: 後方互換性を担保するファサードモジュール（全サブサービスを Re-export）。
• packages/deal-service/views/uploadModal.js: HubSpot Sandboxed Iframe対応の透明ファイル入力オーバーレイ、リアルタイムプログレスバー、SSE受信・フォールバック機構、重複警告バッジ、Iframe JWTトークン (ift) 伝搬を備えたフロントエンドモーダルビュー。
• packages/deal-service/tests/*.test.js: テスト用ダミーデータを用いた抽出精度、PDF処理、ストリーミング、JSONパースの検証テストスイート。

6.3 HubSpot Iframe 埋め込み UI/UX 設計とファイル選択信頼性の確立#

• 短期 JWT トークンによる Sandboxed Iframe 認証 (iframeAuth.js):
  • HubSpot UI Extensions（React）から POST /api/auth/iframe-token を呼び出して 5分間有効な短命 JWT トークン（ift）を発行。
  • Iframe モーダル URL（?ift=...）およびモーダル内の全 API リクエスト（SSE ストリーム / フォールバック POST）に ift パラメータと X-Iframe-Token ヘッダーを自動付与。
  • サードパーティ Cookie 制限のある Sandboxed Iframe 環境下でも 100% 確実な認証・認可を担保。
• 透明ファイル入力オーバーレイ（100% クリック信頼性）:
  • ドロップエリアおよび選択ボタンの全面に opacity: 0 かつ position: absolute; inset: 0; width: 100%; height: 100%; cursor: pointer; を適用した <input type="file"> を配置し、ネイティブ input 要素への直接クリックを保証。
• Helmet CSP & レートリミット最適化:
  • Helmet の frameAncestors に HubSpot のページビルダーおよび *.hs-sites.com を明示的に許可。
  • モーダルHTML配信エンドポイントをレート制限から除外し、429 エラーを防止。

6.4 SSE (Server-Sent Events) リアルタイム進捗ストリーミング ＆ 4段階パイプラインステッパー#

• 4段階パイプラインステッパー & リアルタイム経過時間タイマー:
  • 「1. 受信」➔「2. AI解析」➔「3. 帯消し・合成」➔「4. CRM同期」の4段階パイプラインインジケーター（pipeline-stepper）および経過秒数タイマー（⏱️ 処理中: X秒）を表示。
• きめ細やかなフェーズ進捗イベント:
  • gemini_analyzing ➔ gemini_completed ➔ processing_page / completed_page ➔ saving_timeline ➔ complete。
• リアルタイム順次ポップイン表示 (Live Feed):
  • 完了したページから順次「⚡ 解析完了物件」にカードがポップインし、即時ダウンロード可能。
• 15秒 Keep-Alive Heartbeat:
  • 15秒ごとの SSE コメント（: keep-alive\n\n）によるタイムアウト防止。

6.5 画像フォーマット自動変換エンジン (Sharp) ＆ 多様フォーマット対応#

• WebP, HEIC/HEIF, TIFF, BMP, GIF, AVIF, PDF, PNG, JPG の全面サポート。
• sharp によるインメモリ PNG 透過変換および pdf-lib への埋め込み合成。

6.6 間取り図・書類の SHA-256 重複排除チェック ＆ 履歴トラッキング#

• バイナリ SHA-256 ハッシュを算出し、Firestore floor_plan_history で重複判定。
• 重複検出時に HubSpot ノートおよびモーダル画面へ「⚠️ 過去出力済み」バッジを表示。

6.7 Vertex AI Gemini トークンロギング ＆ コスト監査基盤#

• API レスポンスの usageMetadata（入力・出力・合計トークン）を Cloud Logging に構造化出力し、BigQuery 課金監査と連動。

6.8 並列ストリーミングOCR高速化アーキテクチャ#

• Promise.allSettled による並列処理:
  • 複数ページ・複数画像に対して独立した Gemini OCR リクエストを並列ディスパッチし、処理時間を約 60〜70% 短縮。
• 耐障害性とレートリミット対策:
  • 指数バックオフ自動リトライおよび部分成功時の統合結果返却。

6.9 インフラ・セキュリティ設計 (Cloud Run & Limits)#

• Cloud Run 設定: --timeout=300, --memory=2Gi, --concurrency=10, --max-instances=2。
• アップロード制限: Multer 50MB/50ファイル（複数ページ図面・チラシ一括対応）、AI推論専用レートリミッター（15分20回）。
• HubSpot 署名検証: verifyHubSpotSignature による不正アクセス遮断。

6.10 AI図面マッチング JSONパース多層防御 (safeParseAiJson & Structured Outputs)#

• safeParseAiJson() による Markdown フェンス除去、波括弧抽出、不正カンマ補正、安全フォールバック。
• Gemini API responseMimeType: 'application/json'（Structured Outputs）の適用。

6.11 深層セキュリティ硬化（オペレーター認証/HubSpot署名二重防壁・モーダルCSP保護・非インデックス化）#

• 二重防壁認証: HubSpot UI Extension からは X-HubSpot-Signature-v3、ブラウザからは operator_token（JWT Cookie）。
• IDOR / 不正文字列対策 (validateDealId): 正規表現バリデーション。
• PDF爆弾対策 (MAX_ALLOWED_FLOORPLAN_PAGES): 最大50ページ制限。
• HubSpot Files 非インデックス化: access: PUBLIC_NOT_INDEXABLE。
• XML インジェクション防止: <contract_documents> タグの事前エスケープ。

6.12 帯替え専用図面生成機能（HubSpotタイムライン自動保存）#

• 希望条件マッチングを省略した専用軽量プロンプトによる帯消し・ソライ東京帯合成の高速実行。
• 原本PDFと帯替え済PDFのデュアル保存および HubSpot タイムラインノート起票。

6.13 リアルタイム・ストリーミングUI ＆ ライブフィード#

• SSE によるリアルタイム進捗とライブフィード表示（uploadModal.js）。

6.14 図面解析 Structured Outputs & 帯替え Thinking Budget 0 & 重複物件AD客付条件比較#

• Structured Outputs 完全適用（floorPlanMatchResponseSchema / floorPlanBannerResponseSchema）。
• 帯替え専用処理での思考オフ（thinkingBudget: 0）によるコスト無料化・高速化。
• 重複物件（同一建物・号室）の自動名寄せ ＆ AD（広告料）スコアリング比較（🏆 重複中最高AD バッジ付与）。

6.15 Deal Service の TypeScript 型安全化 ＆ tsconfig 配備 ＆ ドメイン型定義 (types/deal.ts)#

• 独立型検査環境 (packages/deal-service/tsconfig.json):
  • target: ESNext, module: NodeNext, moduleResolution: NodeNext, strict: true, allowJs: true, checkJs: false, noEmit: true を設定。
  • ルート package.json の "typecheck" スクリプトに統合し、全6パッケージ一括型検査を確立。
• 取引・図面解析ドメイン型定義 (packages/common/types/deal.ts):
  • FloorPlanExtractedPropertyDetails: 賃料、管理費、間取り、専有面積、築年、管理会社、電話番号、取引態様、AD、バックの完全型定義。
  • FloorPlanBoundingBox: 図面下部帯のバウンディングボックス座標（ymin, xmin, ymax, xmax）。
  • FloorPlanMatchResultItem & FloorPlanMatchResponse: 物件判定結果、適合スコア、適合ポイント、不足条件、ファイルURL、ADスコア、重複判定。
  • FloorPlanBannerItem & FloorPlanBannerResponse: 帯替え専用解析レスポンス。
  • FloorPlanProcessingProgressEvent: SSE リアルタイム進捗ストリーミングイベント。
  • FloorPlanFileResult & FloorPlanHistoryEntry: 処理済みファイル結果および Firestore 照合履歴エントリ。
  • ContractExtractionResult: 契約書類からの重要取引条件抽出データ型。
• サービス層 JSDoc / TS 型注釈:
  • dealService.js, matchingOrchestrator.js, matchingService.js, hubspotFileService.js, hubspotNoteService.js, floorPlanHistory.js, noteFormatter.js, sheetsService.js, fontCache.js, matchingController.js, app.js の全公開関数およびハンドラーに JSDoc 型注釈を配備。

6.16 Deal Service コアサービス層の TypeScript（.ts）完全移行#

• 移行対象モジュール:
  • packages/deal-service/services/matchingOrchestrator.ts: Gemini 解析、帯消し・ソライ東京帯オーバーレイ、SSE ストリーミング中核。
  • packages/deal-service/services/noteFormatter.ts: タイムライン HTML カード描画および送信用テキスト生成。
  • packages/deal-service/services/hubspotNoteService.ts: HubSpot タイムライン個別・まとめノート起票。
  • packages/deal-service/services/floorPlanHistory.ts: Firestore floor_plan_history の照合履歴記録・重複判定。
  • packages/deal-service/services/fontCache.ts: フォント・ロゴキャッシュおよび画像透過変換。
  • packages/deal-service/services/hubspotFileService.ts: HubSpot Files API アップロード機能。
  • packages/deal-service/services/sheetsService.ts: UTF-8 BOM CSV / Google スプレッドシート連携。
• 後方互換性と型安全性の両立:
  • allowImportingTsExtensions を活用し、Node 22 --experimental-strip-types 環境下でのビルドステップゼロ実行と厳格な型推論を実現。

6.17 帯替え図面作成時の顧客希望条件連動 ＆ オススメポイント自動抽出 ＆ お客様送信用テキスト生成#

• 顧客希望条件とLINE履歴の自動鑑み:
  • replaceFloorPlanBannersStream 実行時、HubSpot Deal の desired_conditions_memo / description に加え、Contact の最新 LINE チャット履歴（getChatHistory）を自動フェッチし、combinedConditions を構築。
• Gemini 3.8 Flash によるオススメポイント (keyMatches) 構造化抽出:
  • floorPlanBannerResponseSchema に keyMatches: ARRAY<STRING> を追加し Structured Outputs を強化。
  • 顧客の希望条件に照らしたオススメポイント（2〜4点箇条書き）または図面自体の魅力的な特徴（駅徒歩・設備・日当たり等）を必ず抽出。
  • FloorPlanBannerItem 型定義に keyMatches?: string[] を追加し、型安全性を確保。
• HubSpot タイムラインノート ＆ モーダル UI での一括共有:
  • noteFormatter.ts: renderBannerReplacementCardsHtml に「✨ おすすめポイント」ブロック（ブルーバッジ・箇条書き）を描画し、generateCustomerCopyText で LINE 送信用フォーマットを出力。

6.18 図面照合スプレッドシート・CSV出力のCloudflareエッジ最適化＆0-Egress高速化#

• 課題と発生原因:
  • 図面照合後のCSV出力時、ブラウザが別タブで開こうとしてプラグインエラー（「プラグインを読み込めませんでした / net::ERR_ABORTED」）が発生していた。
  • 原因は、HubSpot Files CDN配信時に Content-Disposition: attachment が付与されず、Chrome等のPDF/Officeプラグインが誤って起動・クラッシュしていたことによる。
• Cloudflare エッジ最適化（GCP Egress コスト完全0円）:
  • soraitokyo.jp の Cloudflare エッジルール（http_response_headers_transform）に、/hubfs/floor-plan-matching/*.csv リクエスト時に Content-Disposition: attachment; filename="matching_results.csv" を自動注入するルールを追加。
  • これにより、過去に発行されたHubSpotノートも含め、外部リンククリック時に即座にブラウザの標準ダウンロードが起動し、プラグインエラーが根本根絶。Cloudflareエッジキャッシュから配信されるためGCP Egressコストは完全0円。
• モーダル画面（uploadModal.js）の通信量 0 Byte 出力UI:
  • 「📋 スプレッドシート用にコピー」: タブ区切り（TSV）形式でクリップボードに瞬時にコピー。GoogleスプレッドシートやExcelを開いて Cmd+V で19列の整然とした表が一発で完成。
  • 「📥 CSVダウンロード」: クライアントサイド JavaScript Blob から直接ダウンロードを発火（通信量 0 Byte・待機時間 0 秒）。
  • 「📊 表プレビュー」: モーダル内で全物件の比較表をポップアップ閲覧できるビューアを新設。
• HubSpot 取引ノート＆サイドバー連携最適化:
  • hubspotNoteService.ts: タイムラインノートのボタン表記を「📥 比較一覧CSVを保存 ↗」へ最適化。
  • MatchCard.tsx: サイドバーカードのボタン表記を「📥 照合結果CSVを保存 ↗」へ更新。

id: "07_crm_extensions" title: "7. HubSpot CRM UI拡張 (カスタムカード仕様)" category: "system" packages: - "real-estate-crm-extensions/sorai-lease-bot" - "real-estate-crm-extensions/hubspot-quote-generator" - "real-estate-crm-extensions/contract-extractor" - "packages/operator-portal" cloud_run: - "real-estate-chatbot-operator-portal" - "gemini-quote-generator" endpoints: - "GET /api/deals/:dealId/status" - "POST /api/deals/:dealId/activate-portal" - "GET /api/hubspot/unified-chat" - "GET /api/public/files/:fileId" secrets: - "HUBSPOT_ACCESS_TOKEN" - "HUBSPOT_FILES_TOKEN" - "HUBSPOT_CLIENT_SECRET" - "JWT_SECRET" - "gemini-quote-hubspot-client-id" - "gemini-quote-hubspot-client-secret" - "hubspot-refresh-token" - "hubspot-developer-project-key" databases: - "contracts" - "uploaded_chat_files" - "chat_sessions" - "operator_notes"#

7. HubSpot CRM UI拡張 (カスタムカード仕様)#

本モジュールでは、@hubspot/ui-extensions React SDKを使用して開発された、HubSpot CRMレコード（Contacts / Deals）のサイドバーに表示されるカスタムUI拡張カード（sorai-lease-bot）および統合チャットコンソールの技術仕様を定義する。

7.1 契約者専用チャット管理カード (Tenant Chat Management Card)#

• 対象画面: HubSpot 取引（Deals）レコードの右側サイドバー (NewCard.tsx)
• 主要機能:
  1. ステータス表示: API (/api/deals/:dealId/status) を呼び出し、現在の取引のチャットボット有効化ステータス (ai_bot_active)、アクティベーションコード、および有効期限（契約終了から3ヶ月後まで）を表示。
  2. ポータル有効化: 「ポータル有効化」ボタンを押すことで POST /api/deals/:dealId/activate-portal を実行。Firestore上に一意の英数字混合8文字（例: 4k82m193）のLIFFアクティベーションコード (liff_activation_code) を生成。
  3. 関連コンタクト一括取得 (N+1解消): 取引に紐付く全コンタクト情報を fetchContactsBatch（POST /crm/v3/objects/contacts/batch/read）で一括ロードし、逐次N+1クエリを完全排除。顧客名、メールアドレス、電話番号、コンタクトコードを高速表示。
  4. ウェルカムシート作成: ドロップダウンから言語（日本語/ロシア語）を選択し、個別のPDF/HTMLウェルカムシート生成リンク (/api/hubspot/welcome-sheet?customerId=:id&lang=:lang) を起動。

7.2 統合チャット埋め込みカード (Unified Chat Sidebar Card)#

• 対象画面: HubSpot コンタクト（Contacts）および 取引（Deals）レコードの右側サイドバー (ChatCard.tsx)
• 主要機能:
  1. チャットコンソールの動的読込: HubSpotのポータルID（本番環境 246269021 またはステージング環境）に応じて、接続先となるバックエンドAPIのベースURLを動的に判定。
  2. コンタクト/取引ハイブリッド対応: コンタクト画面からの起動時は customerId を渡し、取引画面からの起動時は dealId を渡してバックエンド（/api/hubspot/unified-chat）で関連コンタクトを自動解決。
  3. Iframeモーダル制御: 担当者が取引画面・コンタクト画面のどちらからでも、AIと顧客のLINE・ポータル会話履歴を確認し、有人返信やAI切り替えを行えるIframeモーダル（/api/hubspot/unified-chat）を即座に展開。

7.3 パブリックファイルプロキシの 302 Redirect 最適化 (File Proxy Optimization)#

• エンドポイント: GET /api/public/files/:fileId (packages/operator-portal/server/services/fileService.js)
• 動作仕様:
  1. Firestore の uploaded_chat_files コレクション、または HubSpot Files API（GET /files/v3/files/${fileId}）から、該当ファイルのパブリック CDN URL を取得。
  2. クライアントに対して HTTP 302 Found（res.redirect(302, cdnUrl)）を発行し、ブラウザを直接 HubSpot CDN へリダイレクト。
  3. 効果: 従来の Node.js サーバー側でのバイナリ全量メモリバッファリングおよび中継（arrayBuffer() / res.send(buffer)）を完全撤廃。Cloud Run コンテナのメモリ負荷・帯域消費・レイテンシを極小化し、超軽量・高速なファイル配信を実現。

7.4 添付ファイル送信時の日本語ファイル名 UTF-8 デコードおよび文字化け防止 (File Upload Encoding Protection)#

• 対象モジュール: packages/operator-portal/server/services/fileService.js, packages/deal-service/services/hubspotFileService.js, packages/resident-portal/server/routes/customer/base.js
• 動作仕様:
  1. Multer / Busboy Latin-1 パースの UTF-8 復元: ブラウザが multipart/form-data で送信した日本語ファイル名を Multer が latin1 としてパースした際、Buffer.from(rawName, 'latin1').toString('utf8') による sanitizeOriginalFilename を実行して元の正確な UTF-8 日本語ファイル名を復元。
  2. マルチチャネル配信における文字化け防止: 復元されたファイル名を Firestore (uploaded_chat_files) およびクライアントへのレスポンス JSON に返却することで、LINE（sendLineFilePush）、Facebook（sendFacebookAttachment）、HubSpot タイムライン Note、チャット UI（file-attachment-card）の全チャネルで日本語ファイル名が正常表示・ダウンロードされる。
  3. 図面マッチングサービスにおける Unicode 名保持: deal-service のファイル名サニタイズにおいて、[^\p{L}\p{N}_\-] 正規表現を採用し、日本語（漢字・ひらがな・カタカナ）がアンダースコア _ に置換されて消失する不具合を解消。
  4. RFC 5987 / RFC 6266 準拠ヘッダー: resident-portal のドキュメントダウンロードにおいて、Content-Disposition: inline; filename="fallback.pdf"; filename*=UTF-8''${encodeURIComponent(fileName)} を設定し、安全な日本語ダウンロードを実現。
  5. HubSpot Files API トークン自動リフレッシュ＆401リトライ (requestHubSpotFilesApi): HUBSPOT_FILES_TOKEN や OAuth トークンが失効（401 Unauthorized）した場合に、refreshAccessToken() による自動トークンリフレッシュおよび Private App Token へのフォールバックリトライを自動実行し、トークン有効期限切れによるアップロード失敗を完全防止。

7.5 統合チャットUI/UX刷新・LINEネイティブUI化とスマートフォン最適化 (Unified Chat Responsive Redesign & LINE Native UI)#

• 対象画面:
  1. HubSpot CRM 埋め込みカードモーダル (/api/hubspot/unified-chat)
  2. オペレーターポータル統合チャットスペース (/api/hubspot/chat-space)
• 主要機能・仕様:
  1. LINE ネイティブ・アイコニック UI/UX 設計:
     • 壁紙背景: LINE 公式の親しみやすいソフトスカイブルー（#7494B0 / --bg-feed: #7494B0）を採用し、吹き出しのコントラストと可読性を劇的に向上。
     • 入居者メッセージ（左側）:
       • 相手アバター（36px、LINE/FB/ポータル識別バッジ付き）。
       • 吹き出し上部に相手の氏名（0.72rem、白太字、ドロップシャドウ）。
       • 吹き出しはピュアホワイト #FFFFFF（黒文字 #0F172A）＋左上しっぽ。
       • タイムスタンプ（14:23）および「返信」ボタンを吹き出しの「右下」に横並び配置。
     • スタッフメッセージ（右側）:
       • 吹き出しは LINE 公式鮮やかグリーン #06C755（視認性抜群の濃色テキスト #0B291A）＋右上しっぽ。
       • 「既読」ステータスとタイムスタンプ（既読 14:25）を吹き出しの「左下」に縦積み配置。
     • AI自動応答メッセージ（右側）:
       • 吹き出しは上品なクリーム/ゴールド #FFFDF5（ゴールド枠線 1px solid rgba(245,158,11,0.4)、文字 #1E293B）＋右上しっぽ。
       • 左下に「AI応答」バッジとタイムスタンプを配置。
  2. ヘッダー折りたたみメニュー（ハンバーガーボタン展開）による画面領域の極大化:
     • チャネル切替タブ（LINE / ポータル / 申込 / FB）および AI 自動応答トグルスイッチ、情報パネル切り替えボタンをヘッダーの「ハンバーガーメニューボタン（#header-menu-btn）」内に集約。
     • デフォルト状態ではこれらのサブバーを折りたたんで非表示化し、チャットフィード領域の縦幅を 100% 確保（LINE 公式アプリ同様の圧倒的なスッキリ感と視認性を実現）。
     • ハンバーガーボタンをタップすると上部からスムーズにスライドダウン（slideDownMenu）展開され、チャネル切り替えや AI 応答の ON/OFF を即座に操作可能。
  3. ヘッダーワンタップ電話発信リンク (#header-phone-btn):
     • 顧客カルテに電話番号が存在する場合、ヘッダーにエメラルドグリーンの電話発信ボタン（tel:...）を自動表示。緊急時や直接通話したい場合に1タップで電話発信が可能。
  4. モバイル・レスポンシブ最適化:
     • スマートフォン表示時に画面下部からスライドアップするボトムシートドロワー（#info-drawer）を導入。PCの2ペイン/3ペインレイアウトと同等の顧客・取引情報をモバイルでも1タップで完全閲覧可能。
     • iOS Safariの入力フォーカス時に画面が勝手にズームインする事象を防ぐため、メッセージ入力フィールドのフォントサイズを 16px（1rem）以上に固定。
     • 動的アドレスバーに対応する 100dvh および env(safe-area-inset-bottom) / env(safe-area-inset-top) セーフエリア余白を完全適用。
     • すべての操作ボタン（送信、添付、AIアシスト、ドロワー開閉）に 44px 以上のタッチターゲット領域を確保。
  5. 顧客・取引情報のワンタップ操作とリッチ表示:
     • ワンタップ発信・メール作成: 電話番号（tel:）およびメールアドレス（mailto:）リンクにより、スマホから直接通話・メール起動が可能。
     • アクティベーションコード: ワンタップでクリップボードへコピーし、トースト通知（#chat-toast）を表示。
     • 案内用紙・重説書類リンク: 日本語・ロシア語のウェルカムシート発行リンク、およびGoogleドライブ上の重要事項説明書・紛争防止条例・賃貸契約書リンクを即時閲覧。
  6. LINE 連携ユーザー限定フィルタリングとハイブリッド会話ロード:
     • LINE ID 保有者限定表示: オペレーターポータルの顧客一覧（/api/customer/list）において、line_user_id プロパティが存在するアクティブユーザーのみを厳格に抽出・表示。LINE未連携の一般リードや無関係なコンタクトが混入するのを完全に防ぎ、オペレーターがLINEチャット可能な対象者のみを迷わず管理可能。
     • HubSpot / Firestore ハイブリッド会話ロード: 会話履歴の取得（/api/hubspot/unified-chat/messages）において、HubSpot タイムラインの Note / Communication 取得に加え、Firestore chat_history/{lineUserId} コレクションとの自動フォールバック・マージを実行。HubSpotの同期遅延やタグ形式の揺らぎが発生した場合でも、過去のチャットやり取りを 100% 確実に即時描画。
     • アクティブチャネル自動選択: 顧客選択時に、メッセージが存在するチャネル（LINE等）を自動判定して即座にフィードを展開。
  7. HubSpot Breeze AI ネイティブ連携（画面内スライドイン・Plan A 完結構成）:
     • 画面内スライドイン Breeze パネル (#breeze-drawer): 画面遷移やタブ切り替え、ページリロードを一切行わず、統合チャット画面内の「⚡ Breeze AI」ボタンを押すだけで、画面右端からスムーズに HubSpot Breeze Copilot パネルがスライド展開。
     • ネイティブ Breeze 100% 完結: 外部 LLM（Gemini）を経由せず、当チャットシステムがリアルタイム同期した LINE タイムライン Note を HubSpot 側の Breeze AI が直接読み取って自動要約・質問回答・顧客調査を完全自律実行。
     • レスポンシブ・マルチデバイス対応: デスクトップでは 560px のスライドインドロワー、モバイルでは 85vh のボトムシートドロワーとして展開され、スマホからでも画面を離れずに Breeze Copilot を利用可能。
     • 外部タブ同時展開リンク (#breeze-external-link): 必要に応じていつでも別タブで HubSpot CRM レコード画面を展開可能。
  8. 対話UIの視認性向上:
     • 日付セパレーター (formatDateDivider): 日付境界ごとに半透明ダークピル（rgba(0,0,0,0.22)、白太字）による「今日 (8月30日)」「昨日」「8月28日 (金)」などの視認しやすい日付ピルを行間に自動挿入。
     • アバターシステム (renderAvatarHTML): 入居者（チャネルバッジ付きイニシャルアバター）、AI（スパークルアイコン）、スタッフ（ブランドアイコン）を視覚的に識別。
     • 画像ライトボックス (openImageLightbox): チャット内の添付画像を全画面モーダルで安全に拡大閲覧。

7.6 リアルタイム対話同期 ＆ HubSpot / Firestore ハイブリッド履歴マージ (Real-Time Hybrid Chat History Synchronization)#

• 背景と課題:
  • 従来のフォールバック構成では、HubSpot タイムライン（Notes/Communications）に1件でも過去履歴が存在する場合、Firestore chat_history の読み込みがスキップされ、タイムライン未反映の最新メッセージや有人対応モード（AI Bot OFF）時の受信メッセージが統合チャット画面および Breeze AI / AI 下書き生成に読み込まれない課題が存在した。
  • また、HubSpot CRM の Deal（取引）レコードから統合チャットカードを開いた際（?dealId=...）、フロントエンドでの顧客ID解決が漏れてメッセージ取得が 400 エラーとなる不具合があった。
• 設計と解決仕様:
  1. 全チャネル受信時 Firestore リアルタイム書き込み:
     • LINE (packages/line-bot/services/line/orchestrator.js)、ポータル (packages/resident-portal/server/routes/chat.js)、Facebook (packages/facebook-bot/services/facebook/orchestrator.js) の各受信エンドポイントにおいて、メッセージ着信と同時に appendChatMessage を即時実行。
     • AI Bot が有人対応モード（OFF）の場合や、HubSpot へのタイムライン同期遅延時でも、顧客が送信した最新メッセージが Firestore chat_history に即時永続化される。
  2. HubSpot Timeline ＋ Firestore 完全ハイブリッドマージ ＆ 重複排除 (normalizeMessageTextForDedup):
     • /api/hubspot/unified-chat/messages、generateBreezeCustomerProfile、askBreezeCustomerQuestion、generateDraftSuggestion において、HubSpot タイムライン履歴と Firestore chat_history（line_user_id, customer_id, facebook_user_id）の双方を無条件に取得。
     • HTMLタグ、AI署名フッター、ボタン表記、空白文字を正規化したテキスト比較（normalizeMessageTextForDedup）により、同一メッセージの重複描画を完全に排除しつつ、タイムスタンプ順（昇順）に結合してフィードを構築。
  3. Deal ID / Contact ID 相互フォールバック解決:
     • 統合チャット（unified-chat.js）およびチャットスペース（chat-space.js）において、URLパラメータから customerId, associatedObjectId, dealId を網羅的にパース。
     • バックエンド側でも fetchContactById が失敗した場合に自動で fetchDealById を実行し、紐付く関連コンタクトをシームレスに解決。

7.7 見積書メーカー＆物件一括調査拡張 (Quote Generator & Property Investigation Suite)#

• 対象画面: HubSpot 取引（Deals）サイドバーカスタムカード (/Users/adachishuuhei/real-estate-crm-extensions/hubspot-quote-generator)
• 主要機能・仕様:
  1. 宛名（Customer Name）任意化・自動プリロード抑止（名前誤記載・不一致防止設計）:
     • 初期費用見積書作成において、宛名 (customerName) は完全任意入力（未入力可）。
     • HubSpot Deal（取引）情報の契約者名やコンタクト名を自動で宛名欄にプリロードせず、デフォルトは空文字 ("") を保持。
     • Gemini 解析時（analyzeDocumentForQuote / analyzeHtmlForQuote）も明示的な宛名指定がない限り customerName = "" を抽出。
     • PDF 生成（pdfGenerator.ts）において、宛名が入力されている場合は { text: ${data.customerName.trim()} 様, style: 'customerName' } を描画し、未入力の場合は「関係者 御中」等のダミー表記を行わず、物件名（物件名: ${data.propertyName}）を最上部に美しくレイアウト。
  2. 短期署名JWTトークン発行＆デュアル認証機構 (/api/auth/iframe-token & verifyRequestAuth):
     • UI拡張カード側（QuoteCard.tsx / PropertyCard.tsx）から hubspot.fetch 経由で Next.js バックエンドの /api/auth/iframe-token を呼び出し、GCP Secret Manager の JWT_SECRET（または SORAI_API_TOKEN フォールバック）で署名された有効期限1時間の短期JWTトークンを取得。
     • IframeモーダルURLに token=${token}&ift=${token} を動的に付加して展開。
     • Next.js APIルート群（/api/deal-info, /api/analyze-quote, /api/generate-quote, /api/properties/fetch-details, /api/properties/create-deal-note）で verifyRequestAuth によるJWT検証および静的トークン比較（timingSafeEqual によるタイミング攻撃防御）のデュアル認証を一元適用。
     • app-hsmeta.json の permittedUrls.fetch に Cloud Run サービス URL を登録し、HubSpot サンドボックスからの安全なフェッチを保証。
  3. 初期費用自動解析＆手直しUI (Gemini Flash & Next.js):
     • 帯替え図面PDFまたはポータルURLから、家賃・管理費・敷金・礼金・保証料・鍵交換費・火災保険等を自動抽出。
     • 日割り家賃計算機（実日数/30日固定・翌月分同時請求切替）と二重計上防止サニタイズ（sanitizeQuoteItems）を内包。
  4. PDF生成・HubSpot ファイル登録・タイムライン記録:
     • pdfmake によるブランド統一（Sorai Tokyo ゴールド/スレートグレー）PDF生成。
     • HubSpot Files API および Cloud Storage へのアップロード、Deal タイムラインへの Note 登録を完全自動化。

7.8 統合チャット TypeScript 型同期 ＆ API 契約堅牢化 (Unified Chat TypeScript Contract)#

• 対象画面・モジュール:
  • HubSpot UI Extensions: real-estate-crm-extensions/sorai-lease-bot/src/app/cards/ChatCard.tsx
  • バックエンド: packages/operator-portal/server/controllers/unifiedChatController.js
  • 共通型定義: packages/common/types/api.ts, packages/common/types/chat.ts, packages/common/types/hubspot.ts
• 仕様と効果:
  1. API 契約の静的整合性保証:
     • ChatCard.tsx が発行する Iframe URL パラメータ（customerId, dealId, portalId）および API レスポンス（CrmCardResponse, UnifiedChatMessagesResponse）の型を共通化。
     • HubSpot CRM 側と Cloud Run サーバー間のプロパティ名の乖離やパースエラーを静的型チェック（tsc --noEmit）で 100% 事前検知。
  2. マルチチャネルメッセージ契約の一元化:
     • ChatMessage 型（sender, role, channel, attachments, createdAt）の厳格化により、LINE・Facebook・ポータル・申込の各メッセージが CRM 側でも同一スキーマで安全に解釈されることを保証。

7.9 CRM Card / UI Extension における連携ステータス表示・姓名クリーンアップ仕様#

7.9.1 CRM Card レンダリング仕様 (unifiedChatController.js / renderCrmCard)#

• 姓名クリーンアップ:
  • lastname / firstname からレガシーなタグ文字列（（未連携）、（連携済）、（手動照合中））を除去した上でカードタイトル（${name} 様 (${property})）を生成。
• 連携ステータス表示の専用プロパティ連動:
  • contact.properties.line_integration_status === 'linked' または line_user_id の存在有無から、プロパティ「LINE連携ステータス」に 連携済み ✅ または 未連携 ⚠️ を動的に出力。
  • レガシーな lastname 依存を廃止し、専用プロパティによる正確な状態表示を保証。

7.10 統合チャット送信信頼性強化・多重送信防止・リカバリ ＆ UX向上仕様 (Unified Chat Send Reliability & UX)#

• 対象モジュール:
  • バックエンド: packages/operator-portal/server/services/channelDispatcher.js, packages/operator-portal/server/controllers/unifiedChatController.js
  • フロントエンド: packages/operator-portal/public/js/unified-chat.js, packages/operator-portal/public/js/chat-space.js, packages/operator-portal/public/js/modules/apiClient.js, packages/operator-portal/public/js/modules/chatRenderer.js, packages/operator-portal/public/js/chat-common.js
  • スタイル: packages/operator-portal/public/css/unified-chat.css, packages/operator-portal/public/css/chat-space.css
  • E2Eテスト: packages/operator-portal/tests/e2e-operator-chat.test.js
• 仕様と効果:
  1. 多重送信・連打完全防止（isSending ガード ＆ ボタン disabled 化）:
     • オペレーターが送信ボタンを押下、または Enter キーでメッセージ送信を開始した瞬間、即座に isSending = true を設定し、送信ボタンを disabled 化してローディングスピナー（.send-spinner）を表示。
     • 通信完了（成功またはエラー）まで追加入力や Enter 連打を 100% 遮断し、同一メッセージの多重送信を完全に防止。
  2. 送信失敗時のサイレント握りつぶし解消 ＆ 入力テキスト自動復元 ＆ エラーバッジ:
     • 従来は通信エラーや LINE API エラー時に console.error のみで画面上は「送信中...」のまま残り、入力テキストが消失していた不具合を抜本解消。
     • 送信失敗時は、入力欄に送信しようとしていた下書きテキスト（backupText）を即座に復元し、オペレーターの労力を保護。
     • フィード上のメッセージに「⚠️ 送信失敗」エラーバッジを付与し、トースト通知（#chat-toast.toast-error）で具体的な失敗原因を明示。
  3. Enterキー送信・改行・IME変換の操作性改善（Option A 実装）:
     • PC作業時の自然なチャット体験を実現するため、「Enterキーで即時送信」「Shift+Enterで改行」を標準採用。
     • Mac/Windows両対応として「Cmd+Enter」「Ctrl+Enter」での送信も完全サポート。
     • 日本語入力時のIME確定 Enter（e.isComposing || e.keyCode === 229）を厳格に除外し、文字変換中の誤送信を 100% 遮断。
     • プレースホルダー（メッセージを入力... (Enterで送信 / Shift+Enterで改行)）およびツールチップで操作ガイドを明示。
  4. チャネル送信ハンドラ堅牢化 ＆ LINE未連携事前バリデーション:
     • channelSendHandlers において、line_user_id が未登録または無効な顧客に対して LINE 送信を試みた場合、400 Bad Request と適切な日本語エラー（LINEが未連携の顧客です。先に認証案内を送信して連携を完了してください。）を返却。不要な Bot OFF 処理の先行実行を防止。
     • sendLinePush / sendLineImagePush / sendLineFilePush の結果を厳格にチェックし、LINE API 側でトークン失効やエラーが発生した場合は即座に例外をスローしてオペレーターへフィードバック。
     • portal および apply チャネルの送信ハンドラを明示的に登録。
  5. 包括的 E2E テストスイート（e2e-operator-chat.test.js）:
     • LINE正常送信、未連携バリデーション、必須パラメータ検証、未知チャネル検証、添付ファイル送信・プロキシURL正規化、LINE APIエラーハンドリングの全6シナリオを網羅する自動テストを整備。

7.11 見積書メーカー OAuth 2.0 認可および動的トークンリフレッシュ仕様 (Quote Generator OAuth 2.0 & Token Refresh Architecture)#

• 対象パッケージ: real-estate-crm-extensions/hubspot-quote-generator, gemini-quote-generator
• 認証・認可フロー:
  1. HubSpot UI Extension とバックエンド連携: HubSpot 取引（Deals）詳細画面の UI Extension カードから Next.js バックエンド (gemini-quote-generator) を呼び出す際、HubSpot アプリケーション認証として OAuth 2.0 認可コードグラントを採用。
  2. 認可コードコールバック (/oauth-callback): HubSpot 認可サーバーからのリダイレクトを受け取り、HUBSPOT_CLIENT_ID (gemini-quote-hubspot-client-id) および HUBSPOT_CLIENT_SECRET (gemini-quote-hubspot-client-secret) を用いて https://api.hubapi.com/oauth/v1/token でトークン交換を実行。
  3. Secret Manager 動的更新 (setSecret): 取得した access_token および refresh_token (hubspot-refresh-token) を Google Cloud Secret Manager へ即座に書き込み・バージョニング保存。古い有効バージョンは自動的にプルーニング (destroySecretVersion) して最新 2 バージョンのみを保持。
  4. 動的トークンリフレッシュ ＆ キャッシュ整合性 (clearSecretsCache): トークン失効（401 Unauthorized）時、メモリ内キャッシュをクリアした上で Secret Manager の hubspot-refresh-token を用いて自動リフレッシュを行い、HubSpot Files API（PDFアップロード）および CRM Deals/Contacts API 呼び出しの無停止稼働を担保。
  5. HubSpot CLI / Projects 開発キー (hubspot-developer-project-key): ローカル開発環境 (hs project dev) および CI/CD デプロイ環境 (hs project upload) における HubSpot 開発者アカウント認証を保護。

7.12 AIエージェント開発ガイドライン・単一信頼源（SSOT）統合仕様 (AI Agent Unified Guidelines & SSOT Architecture)#

• 対象リソース: real-estate-crm-extensions/.agents/AGENTS.md, contract-extractor/CLAUDE.md, hubspot-quote-generator/CLAUDE.md, CLAUDE.md
• アーキテクチャ設計・運用方針:
  1. 単一信頼源（SSOT）の一元化:
     • Claude Code の設定ファイル（CLAUDE.md）と Antigravity の設定ファイル（.agents/AGENTS.md）の二重管理を廃止。
     • 各サブパッケージ（contract-extractor/, hubspot-quote-generator/）およびルートの CLAUDE.md は @../.agents/AGENTS.md をインポートする 1 行構成に統一。
     • これにより、コンテキスト消費量を従来の 240行（約4,000トークン）から 99% 削減し、重要ルールの指示遵守率（Instruction Following）を最大化。
  2. 静的暗記型から Tool/MCP 主導の行動規範型への移行:
     • HubSpot CLI コマンドや Hooks/Actions の網羅的辞書をプロンプトから全廃。
     • スキーマやコマンド仕様の調査は hubspot MCP ツールおよび hs --help の動的実行に委譲。
  3. 仕様書駆動開発（SDD）ポータル連動:
     • UI拡張のデータ構造、バックエンド連携（deal-service, inquiry-service）、認証仕様は本仕様書（07_crm_extensions.md）を正本とする。
  4. サブエージェント委譲（Subagent-First）と型ガードレール:
     • Webpack / Next.js の重いビルドや全量検証は self サブエージェントに隔離実行し、親エージェントのコンテキスト汚染を防止。
     • 作業完了条件として hs project validate および型エラーゼロ（npm run typecheck）を義務化。

id: "08_cms_editorial_pipeline" title: "8. 開発・運用自動化スクリプトおよびエージェントスキル仕様" category: "system" packages: - "real-estate-cms-operations/automation/" - "pipeline/*" cloud_run: - "sorai-auto-editorial" endpoints: secrets: - "HUBSPOT_ACCESS_TOKEN" - "MLIT_API_KEY" - "LIBRARY_API_KEY" - "GEMINI_API_KEY" - "GCP_PROJECT_ID" - "sorai-hubspot-access-token" - "sorai-mlit-api-key" databases: - "editorial_queue" - "knowledge_articles"#

8. 開発・運用自動化スクリプトおよびエージェントスキル仕様#

8.1 自動化パイプラインスクリプト (real-estate-cms-operations/automation/)#

run_auto_editorial_pipeline.py (自律執筆メインオーケストレーター ＆ pipeline/ パッケージ)#

• 目的: キュー管理・重複チェック・国土交通省一次データ（MLIT）事前注入・長文日本語生成・リズム校正・ファクトチェック・4言語並列翻訳・HubSpotデプロイ・GSC送信・RAGナレッジ同期を一貫して自動実行。
• モジュール分離アーキテクチャ (pipeline/): 単一責任の原則に基づき、巨大単一ファイルを以下の責務別サブパッケージへ分割スリム化：
  • pipeline.config: 定数（BLOG_IDS, TAG_IDS, FEATURED_IMAGES, AUTHOR_INFO）、Pydanticスキーマ（ArticleSchema, MultilingualArticleSchema, RhythmFixPlan）、日本語判定ガード。
  • pipeline.ogp_generator: 1200×630px の高解像度 OGP / アイキャッチ画像の動的自動生成エンジン（Pillow / ヒラギノ角ゴ / ブランドネイビー #1b2a47 / テラコッタ #c57e5f / カテゴリバッジ / 駅名ハイライト / タイトル自動折り返し）。完全ゼロコストで全記事固有のアイキャッチを描画。
  • pipeline.html_formatters: FAQPage / BlogPosting JSON-LD 機械生成、著者カード、Quick Answer ボックス、レスポンシブ表整形、末尾CTAパージ。
  • pipeline.svg_processor: SVG プレースホルダーマスク（トークン削減）および翻訳後テキスト再注入エンジン。
  • pipeline.queue_manager: BigQuery / ローカル JSON キュー制御、週次配分判定（is_weekly_tips_due）、セマンティック重複チェック、RAG同期。
  • pipeline.article_generator: 事前グラウンディング（collect_pre_retrieval_facts）による駅前最新施設・深夜スーパー・所要時間・家賃相場・最新助成金の自動注入、国交省MLIT一次データ自動取得、Pydantic構造化執筆（sorai_schema ➔ sorai_renderer による出力トークン35%削減）、プロンプトFew-Shot模範例による文末リズム初段改善、apply_rule_based_rhythm_fixes（非AI定型置換）とGeminiフォールバックのハイブリッド校正。
  • pipeline.article_translator: Gemini Context Caching（sorai_common.create_or_get_context_cache / TTL 15分）による入力トークン75%割引適用、3.5 Flash-Lite による H2 セクション分割（Chunking）1:1 翻訳エンジン、メタデータ（Title/Meta/SVGTexts）独立局所翻訳、ThreadPoolExecutor 4言語並列実行、多言語構造保持・薄肉化防止 Structural Guard。
  • pipeline.hubspot_deployer: HubSpot CMS API通信、動的OGP画像のFiles API（POST /files/v3/files）自動アップロード・featuredImage紐付け、多言語バリエーション作成・グループ結合（attach-to-lang-group）、Push-Live、Visual QA監査、GSC送信。
• 国交省MCP連携 ＆ 生活メリット解説ストーリー化（E-E-A-Tグラウンディング）: Step 3（日本語執筆）および事前RAGにおいて mlit_data_fetcher.py を自動呼び出し、対象駅の地価公示、実取引価格、用途地域（建蔽率/容積率）、駅乗降客数、液状化・洪水ハザード、認可保育園・医療機関数をプロンプトへ自動注入。数値を無機質に並べるのではなく「なぜ隣駅より家賃が2万円安いのか」「用途地域（第一種住居地域等）から見る静けさと日当たりの良さ」など、宅建士が語りかける自然な生活メリット解説カード（mlit_insight_box）として記事に融和。生成AI特有の相場・用途地域ハルシネーションを完全撲滅。
• 主要引数: --batch-daily（日次配分スロット実行）、--id <queue_id>（特定記事実行）、--group <name>、--dry-run、--force。
• 安全ガード ＆ フォールトトレラント設計:
  • 多言語デプロイのフォールトトレランス: 4言語（EN, VI, RU, ID）のバリエーション作成・グループ結合・Push-Live を個別の try-except で保護し、万が一1言語で一時的エラーが発生しても他言語の公開を道連れに中断させず、可能な限り全言語を公開する耐障害性を担保。
  • GSC Indexing API の ADC 対応: サービスアカウントファイルが存在しない Cloud Run 環境でも Google Cloud の Application Default Credentials (ADC: google.auth.default(scopes=['https://www.googleapis.com/auth/indexing'])) を使用して正常に GSC へ即時送信。
  • HubSpot API 204/空レスポンス安全ハンドリング: call_hubspot_api において 204 No Content や空ボディ受信時に安全に {} を返し、JSONDecodeError を完全防止。
  • 重複無限ループ遮断: seen_item_ids 追跡および MAX_ATTEMPTS_PER_SLOT = 10 による重複スキップ時の無限ループ防止・トークン消費完全遮断ガードを内包。
  • AI 縮退運転・サーキットブレーカー連携 (check_ai_degradation_mode()): バッチ実行冒頭で Firestore system_config/ai_degradation を参照し、degraded または emergency_stop モード時に LLM 生成処理を即座に安全スキップしてトークン消費を 100% カット。
• 3.5 Flash-Lite H2 セクション分割翻訳アーキテクチャ (H2 Chunking Translation Architecture):
  1. セクション分割（Chunking）: split_html_into_sections(body_html) により、日本語記事の冒頭（リード文＋AEOクイックアンサーボックス）および各 <h2> 見出し境界で正確に HTML チャンクへ分割。SVG プレースホルダー（<!-- SVG_PLACEHOLDER_X -->）を正確に維持。
  2. メタデータ＆SVGテキスト独立翻訳: 記事タイトル・メタディスクリプション・SVG内テキスト配列を ArticleMetadataTranslation Pydantic スキーマで先行翻訳。SVGカード見出し（最大20文字）・本文（最大35文字）の文字数バジェットを厳守しレイアウト破綻を防止。
  3. セクション別 1:1 完全忠実翻訳: 各セクション（1,000〜1,500文字）を gemini-3.5-flash-lite に渡し、「要約・短縮・箇条書き化を一切禁止し、全HTMLタグ・全クラス・全H3・全段落P・全テーブル・全リストを100%忠実翻訳」をプロンプト制約で強制。単一プロンプトによる長文圧縮バイアスを根本根絶。
  4. セクション結合と Structural Guard 検証: 翻訳された全セクションを順序通り結合し、翻訳済み SVG を再注入。機械アサーション（H2一致率 >= 90%、H3保持率 >= 80%、段落P保持率 >= 70%、SVG 100%保持、日本語残存ゼロ検証）を実行。
  5. 4言語並列パイプライン: EN, VI, RU, ID を ThreadPoolExecutor(max_workers=4) で並行実行し、各言語 40,000〜55,000文字相当（HTML本文含む）の完全長文多言語記事を高速生成。スロット2記事（queue-057: 防音・遮音性ガイド / JA ID: 389991139009）において EN, VI, RU, ID の全言語で H2: 7 (100%), H3: 15 (100%), P: 41 (100%), SVG: 1 の完全再現を実証。
• 多言語執筆・デプロイ 4重防御アーキテクチャ (4-Layer Defense Architecture):
  1. 第1防衛線: プロンプト制約 ＆ Pydantic スキーマ強制 (Structured Output): 多言語翻訳プロンプトにおける文字数バジェット制約、<text> XML構文保持、および ArticleMetadataTranslation による型安全な構造化出力を強制。
  2. 第2防衛線: 多言語構造保持・薄肉化防止ガード (Structural Guard): 日本語元記事と多言語翻訳版の H2/H3/P/SVG/Table/FAQ 数を機械照合。H3一致率 >= 80%（0個圧縮はFATAL）、P一致率 >= 70%、SVG/表/FAQ 100% 保持を検証。
  3. 第3防衛線: デプロイ直前 日本語残存・構文破損ハードゲート (Pre-Deploy Integrity Hard Gate): is_japanese_content(text: str) -> bool（ひらがな・カタカナ >= 5文字判定）により、EN/VI/RU/ID のタイトル・本文に日本語が残存している場合はデプロイを即座にブロック。あわせて validate_svg_syntax_integrity() により構文破損・文字消失を遮断。
  4. 第4防衛線: デプロイ直後 整合性アサーション ＆ 常時自己修復 (Post-Deploy Integrity Assertion & Self-Healing Guard): デプロイ直後に HubSpot API で親記事を再取得し、translations プロパティに全多言語バリエーションが 100% 紐付いているか、およびタイトルに日本語が残存していないかを検証（未紐付けや残存時は即座にアタッチ・修復）。さらに audit_and_heal_multilang_integrity.py が全記事を巡回監査し、未翻訳・未作成・未紐付け記事を自律修復。
• テキスト主体カードのHTML/CSS化 ＆ SVGのグラフ特化アーキテクチャ:
  • 手順ステップ・比較カードのHTML/CSSコンポーネント化 (.step-process-grid): 手順ステップ（1, 2, 3, 4）や内見チェックフローは、SVGではなくレスポンシブな HTML/CSS グリッドコンポーネントとして出力。英語・多言語化時にも自動折り返し（リフロー）およびカード高さ追従が働き、文字溢れや文字被りを100%根本根絶。
  • SVGの役割を数値・幾何学チャート（棒グラフ・推移グラフ・路線図）に特化: 文字主体の狭小4カラムSVG出力を完全禁止し、SVGは家賃相場バーチャートや費用累積グラフなどの幾何図形描画に限定。
  • 既存記事の自動自己修復 (convert_step_svg_to_html_cards): 万が一狭小4カラムSVGが含まれる場合でも、editorial_design_system.py および pipeline.html_formatters が自動的に検知して美しい .step-process-grid HTMLコンポーネントへ冪等に置換・修復。
• SVG 5重防御アーキテクチャ ＆ プロンプト制約:
  • 幾何チャート標準化: バーチャートや費用シミュレーション等の数値グラフィックに特化し、適切なバー高さ（height >= 30px）と余白を確保。
  • 多言語文字数バジェット（Character Budget）: 多言語翻訳時のテキスト長膨張（EN/VI/RU/IDで最大1.5〜2.5倍化）を想定し、プロンプト制約としてカード内タイトル最大15〜20文字、説明文最大30〜35文字、バッジ最大3〜5文字の文字数上限と <text> XML構文保持を明示強制。
  • デプロイ前幾何修復の強制実行（Pre-deploy Geometric Repair Enforcement）: 日本語および多言語バリエーションのデプロイ直前に svg_comprehensive_linter.py を通過させ、幾何境界逸脱や文字はみ出しをゼロコストで自動修復。
  • デプロイ直前「SVG ゼロディフェクト・ハードゲート」: 日本語親記事および各多言語バリエーションをHubSpotへPOST/PATCHする直前に validate_svg_syntax_integrity() を実行。1件でも構文破損や文字消失があれば RuntimeError で即時中断し破損記事の公開を完全遮断。

editorial_design_system.py (エディトリアルデザインシステム・DOM自動整形エンジン)#

• 目的: 執筆・翻訳されたHTMLに対し、公式著者・監修者ボックス（ことりアイコン editorial_avatar_birds.jpg ＋ 宅建士監修 author-profile-box）、Q/Aバッジ付きFAQカード（faq-card）、中間CTA（c-cta-box）、レスポンシブ表（table-responsive-wrapper）を冪等に自動整形・修復。
• マークダウン構文自動サニタイズ (sanitize_markdown_syntax): HTML本文内の **太字** を <strong>太字</strong> に変換し、インラインSVG内のアスタリスクを完全除去することで、生マークダウンの残存を100%防止。
• 仕様: 言語に応じた監修者情報（宅建士監修）の自動挿入、ネイビー #1b2a47 Qバッジ ＋ テラコッタ #c57e5f Aバッジ ＋ border-radius: 12px ＋ box-shadow のデザインシステム完全準拠。

visual_qa_auditor.py (DOM・ビジュアル品質厳格監査 ＆ 自己修復ゲート)#

• 目的: 公開前後のHTMLまたはLive URLをヘッドレス監査し、Author Box欠落（[FATAL]）、FAQ Q/Aバッジ欠落（[ERROR]）、表ラッパー欠落（[ERROR]）、白紙・文字数不足（[FATAL]）、SVGテキストはみ出し・境界逸脱（[ERROR]）、SVGテキスト0個/裸属性タグ（[FATAL]）を検知。不合格時はデプロイを即座にブロックし自己修復を実行。
• CDN伝播待ちバックオフ＆誤自己修復防止（CDN Propagation Exponential Backoff）:
  • Push-Live 直後のエッジ伝播遅延による一時的な 404 / 接続エラーに対し、3s -> 5s -> 8s -> 12s の Exponential Backoff リトライを実行して正常伝播を待機。
  • 404/未伝播を「コンテンツ破損」と混同しないよう厳格に峻別し、404 時の再PATCH・再Push-Live（伝播タイマーリセットを引き起こす無駄な再デプロイ）を完全遮断。heal_post_body による自己修復は、HTTP 200 で HTML が取得でき、かつ実際の DOM 構造エラーが存在する場合にのみ限定発動。
• SVGテキストオーバーフロー ＆ 構文完全性アサーション: インラインSVG内の全 <text> / <tspan> を走査し、viewBox（幅800px）境界外へのはみ出し、内包カード矩形（<rect>）境界オーバーフロー、同一座標でのテキスト重複・上下衝突を厳格検知。<rect> 内の <text> 0個検知および裸属性タグ検知時はスコア -60（即座に passed=False かつ [FATAL]）として自己修復を強制起動。

sorai_schema.py (Pydantic 構造化エディトリアルデータモデル)#

• 目的: 記事全体（ArticleStructuredDraft）、章（H2Section）、小見出し（H3SubSection）、比較表（TableData）、FAQ（FaqItem）、AEO要約、Critic査読結果（CriticAuditResult）の厳格な型定義とバリデーション。
• 効果: LLMに出力トークンを浪費するHTMLタグを書かせず純粋JSONのみを出力させることで、最も高単価な出力トークンを約40%削減し、閉じタグ忘れや構文破損を根本撲滅。

sorai_renderer.py (型安全 HTML & JSON-LD 完全機械レンダリングエンジン)#

• 目的: Pydantic構造化データ（sorai_schema.py）から、Sorai Tokyoデザインシステム（グラフィカル比較表、MLIT生活実感解説カード、キーインサイトカード、暮らしやすさ比較カード、Author Box、ネイビーQ/テラコッタAバッジ付きFAQ、中間CTA、同期JSON-LD）に100%準拠したHTMLを機械生成。
• グラフィカル比較表 (render_table):
  • ネイビーグラデーションヘッダー: background: linear-gradient(135deg, #131f37 0%, #1b2a47 100%)、白文字・太字。
  • 暮らしやすさハイライト: 列名に対象駅や注目の特徴を含む列に対し、テラコッタ #c57e5f の上品なアクセント枠と淡いハイライト背景、「👑 おすすめ」「総合バランス◎」等の暮らしやすさ基準のバッジを自動付与（過度な安売り・最安表記を完全排除し、信頼感を最優先）。
  • モバイル最適化＆ソフトシャドウ: border-radius: 12px、box-shadow: 0 4px 20px rgba(0,0,0,0.06)、偶数行ストライプ。
• MLIT生活実感解説カード (render_mlit_insight_box):
  • 単なる生データの数値羅列を廃止し、「💡 宅建士のエリアデータ解説（国土交通省 不動産情報ライブラリより）」として、用途地域（第一種住居地域等の閑静さ・日当たり保証）や地価推移を、読者が安心して長く暮らせる住環境の客観的エビデンスとして自然に解説。
• キーインサイトカード ＆ ライフスタイル比較カード (render_key_insight_card, render_lifestyle_card):
  • 各H2章冒頭にアイコンバッジ（💡, ⚖️, 🌿）付きの要約インサイトカードを配置し、長文記事（9,000字超）のモバイル斜め読み性を飛躍的に向上。
  • 街の雰囲気、通勤のリアル、買い物利便性、休日の過ごしやすさなど、ライフスタイル別のメリット・デメリットを視覚的な比較カードで明快に提示。
• HTML5 アコーディオン FAQ (render_faq_card):
  • 従来の静的カードから、HTML5標準の <details class="faq-accordion"> と <summary> によるクリック開閉式アコーディオンへ進化。1問目をデフォルト open とすることで読者のインタラクションを誘導し、2問目以降を折りたたむことで 9,000字長文の末尾スクロール圧迫感を完全解消。JavaScript不要で軽量かつアクセシブル、FAQPage JSON-LD と完全同期。
• 関連記事自動インラインカード (render_related_articles_card):
  • column-search-agent/articles.json から、現在の記事と重複しない同一カテゴリ・同一沿線の関連記事を2〜3件ルールベースで自動選定。まとめ章直前に「📖 あわせて読みたい関連記事」カードとして自動挿入し、追加AIコスト0円・待機時間0秒でサイト内回遊率（PV/セッション）とドメインオーソリティを最大化。
• 多言語専用 外国人居住インサイトカード (c-expat-insight-card):
  • 日本語記事から外国人訴求を完全に排除したことと対をなし、多言語版（EN, VI, RU, ID）専用に「外国籍歓迎保証会社（GTN・エポス等）」「ビザ書類対応」「敷金礼金の透明解説」をまとめた独自インサイトカードを第2章直後に自動注入。完全なペルソナ分離と多言語成約率を最大化。
• 効果: 生成と表現の完全分離により、LLMに出力トークンを浪費するHTML/CSSを書かせず純粋JSONのみを出力させることで、最も高単価な出力トークンを約35%削減し、無人Cloud Run Jobs実行時でも DOM崩れ・スキーマ不整合・表示エラー率0% を恒久保証。

svg_comprehensive_linter.py (統合SVG幾何・構文完全性 ＆ 多言語オーバーフロー自動修復リンター)#

• 目的: インラインSVGの幾何配置（幅780px境界・はみ出し防止・カード枠内シングルライン維持・動的フォントスケーリング）、構文完全性検証（validate_svg_syntax_integrity）、および色彩コントラスト（WCAG AAA準拠・背景色同色化防止）を単一モジュールで自動修復（--fix）。
• SVG構文完全性バリデーション (validate_svg_syntax_integrity):
  • 裸の属性タグ検知: <text 接頭辞が脱落した不正な属性タグ（x="..." y="...">...</text>）を正規表現で検知。
  • 空SVG・テキスト消失検知: <rect> カード枠が存在するにもかかわらず <text> が0個の破損SVGを即座に検知。
  • タグペア整合性機械検証: <text> / </text> および <tspan> / </tspan> の開始・終了タグ数が完全一致しているかを機械照合。
• 多言語テキスト折り返し＆幾何修復エンジン:
  • 最小内包矩形探索（Minimal Enclosing Rect Search）: テキスト要素の中心座標（text_center_x, text_center_y）および絶対座標から、親・近接する最も内側の <rect> / <circle> を自動特定し、許容最大描画幅（max_allowed_x）を動的算出。
  • 単語境界 <tspan> 複数行自動折り返し (wrap_svg_text): 多言語翻訳によってカード幅（300〜340px）を超える長文テキストを、英語・ベトナム語・ロシア語・インドネシア語の単語境界（スペース・ハイフン）および日本語・CJKの文字単位で自然に分割し、行間（dy="1.2em"）を維持した <tspan> 複数行要素へと安全に自動変換。
  • text-anchor="middle" 境界安全性（Bounds Safety）: 中央揃えテキスト（text-anchor="middle"）において、左端（abs_x - est_w / 2）および右端（abs_x + est_w / 2）がカード枠やviewBoxを逸脱しないよう幾何境界を精密補正。
  • 動的フォントスケーリング・フォールバック（Font Scaling Fallback）: 複数行折り返し後もカード高さや境界に収まらない極端な長文テキストに対し、font-size を 10.5px〜11.5px（最小 9.0px）まで段階的に自動精密縮小。
  • 色彩コントラスト自動反転: 濃紺・暗色背景上の文字を #ffffff（白）、白・明色背景上の文字を #1b2a47（濃紺）へ自動反転し、WCAG AAA 準拠の視認性を恒久担保。

auto_link_injector.py (動的内部リンク自動挿入)#

• 目的: 公開済み523記事以上（全93カタログ）のナレッジベースから本文テーマ・駅名を走査し、最も関連性の高い過去記事カード（.related-article-card）を中盤に1〜2箇所自動埋め込み。

google_fact_checker.py (Google検索ファクトチェッカー)#

• 目的: 6大ドメイン（不動産法令・賃貸実務・鉄道・商業・行政制度・外国人居住）のファクトクレームを抽出し、Google Search Grounding で公的機関の一次情報と照合・安全置換（--fix）。

topic_queue_planner.py (Multi-Source BigQuery AI自律テーマプランナー)#

• 目的: GSC検索急上昇クエリ、GA4読了率・高エンゲージメントページ、Facebook反響ログ、および過去公開済み543記事の分布バランスをBigQueryから自動抽出し、Gemini 3.7 Flash（Dynamic Thinking） により「今最も検索流入・反響を獲得できる未開拓テーマ」を黄金比率（コア駅 33% / 千代田線沿線 33〜50% / 実務TIPS 週1〜2本）に基づいて自律生成・選定。
• カニバリゼーション完全防御: 生成されたテーマは duplicate_checker を通じて全543記事とセマンティック照合され、類似度スコア < 0.65 の完全新規切り口のみを採用。

mlit_data_fetcher.py (国土交通省 不動産情報ライブラリ 公式一次データ自動抽出エンジン)#

• 目的: 国土交通省の「不動産情報ライブラリAPI（mlit-geospatial-mcp）」と連携し、対象駅・エリアの公的基準地価、直近成約・取引価格、都市計画・用途地域、駅別乗降客数、液状化発生傾向、洪水浸水想定区域、認可保育園・医療機関データを自動取得・要約（SQLite 30日間TTLキャッシュ）。

audit_and_heal_multilang_integrity.py (多言語整合性監査 ＆ 自己修復ガード)#

• 目的: HubSpot CMS上の全ブログ記事（全121トピック・全593記事）を巡回監査し、① 5言語完全性（JA, EN, VI, RU, ID）、② 多言語親子バリエーション紐付け（attach-to-lang-group）、③ タイトル・本文の日本語残存検知（is_japanese_content）と Gemini による自動再翻訳修復、④ 公開ステータス（PUBLISHED）と公開日（publishDate）の同期修復、⑤ Push-Live による即時公開・CDNパージを全自動実行。

multilang_structural_guard.py (多言語構造保持・薄肉化防止ガードリンター)#

• 目的: 日本語元記事に対する多言語翻訳版（EN, VI, RU, ID）の構造整合性を機械監査し、LLMの要約バイアスによる情報脱落（H3見出し欠落・段落削減・SVG図解脱落）を完全防御。
• 判定基準: H3見出し一致率 >= 80%（0個への圧縮はFATAL判定）、段落P一致率 >= 70%、SVG図解完全保持（100%）、比較テーブル完全保持（100%）、FAQ完全保持（100%）。デプロイ前に自動アサーションを実行し、基準を満たさない低品質な翻訳版の混入を即時ブロック。

8.2 ワークスペース内追加システム・自動化スイート#

8.2.1 SASH (Sorai Tokyo Autonomous Site Health & SEO Suite)#

• 配置: soraitokyo-cms-theme/tools/sash/
• 構成: sash_orchestrator.py が各モジュールを統括。
  1. auto_healer.py: URLルーティング自動修正。
  2. visual_linter.py: Playwright ビジュアル QA。
  3. web_vitals_logger.py: Lighthouse 自動監査ロガー ＆ BigQuery 蓄積。
  4. competitor_gap_analyzer.py: SEOコンテンツドラフト自動生成。

8.2.2 Facebook Posting Automation & Closed-Loop Engine (Facebook 自動投稿・完全クラウド運用システム)#

• 配置: real-estate-cms-operations/theme/tools/facebook-poster/
• Cloud Run Jobs 構成: facebook-poster-ja (毎日 10:00 & 21:00 JST), facebook-poster-en (毎日 14:00 & 18:00 JST), facebook-insights-sync (毎日 23:00 JST)。
• 閉ループデータフロー: trend_extractor.py (需要検知) ➔ rag_retriever.py (ナレッジ照合) ➔ gemini_generator.py (Gemini 3.5 Flash-Lite 推論) ➔ facebook_api.py (Meta Graph API 投稿) ➔ state_manager.py / insights.py (BigQuery 蓄積)。

8.2.3 Google Site Verification Automation (GSCドメイン所有権自動確認)#

• auto_gsc_verification.py: Google Site Verification API と連携し、メタタグ自動埋め込み・CMSアップロード・所有権確認を完遂。

8.2.4 GTM Manager (Googleタグマネージャー自動デプロイツール)#

• gtm_manager.py: GA4ベースタグ・LINEクリック計測トリガーをプログラムから直接作成・パブリッシュ。

8.2.5 Zero-Cost Static Blog Deployer (静的ブログパブリッシャー)#

• sorai_editorial_agent.py: ローカルHTML/JSONからHubSpot CMSへの安全なデプロイ・多言語親子グループ結合・公開日保護。

8.3 エージェントスキル仕様 (.agents/skills)#

sorai-editorial (エディトリアル・校正・長文執筆)#

• 主要機能: 重複チェック（duplicate_checker.py）、文末リズム校正（sentence_rhythm_linter.py）、Google検索ファクトチェック（google_fact_checker.py）、RAGナレッジ即時同期（sync_knowledge_articles）、二重CTA防止（strip_trailing_cta_boxes）、長文構造化執筆（9,000〜10,000字）、多言語ローカライズ分離。

sorai-internal-links (文脈埋め込み内部リンク推薦)#

• 新記事と既存記事（510記事以上）の双方向内部リンク推薦。ロケール分離を厳格適用。

sorai-link-integrity (リンク整合性・GSCインデックス登録)#

• リンク切れ自動検出および Google Search Console Indexing API (URL_UPDATED) への自動送信。

sorai-lpo-insights (LPO改善・トレンド・クリエイティブ)#

• GA4 アクセス解析に基づく CVR 改善提案、Google Search Grounding によるトレンド収集、解説用 SVG 自動生成。

sorai-mf-etax-csv (Money Forward ＆ e-Tax CSV自動生成)#

• Money Forward 会計データから国税庁 e-Tax 仕様準拠の内訳明細書 CSV（HOI010〜HOI160）を自動生成。

sorai-security-hardening (インフラ・セキュリティ硬化)#

• Dockerfile 非root化、WIF ＆ Secret Manager 保護、Artifact Registry 自動パージ。

sorai-article-classification (記事自動カテゴリ分類)#

• 未分類記事の自動カテゴリ判定・タグ付与・Push-Live。

8.4 執筆パイプライン運用 ＆ データドリブン自律プランニング仕様#

• 日次配信スロット（毎日 03:00 JST / 18:00 UTC 実行）:
  • Slot 1 (core_stations / 毎日1本): 北千住・綾瀬・北綾瀬。
  • Slot 2 (other_chiyoda / 毎日1本): 千代田線主要駅。
  • Slot 3 (other_chiyoda / 毎日1本): 千代田線沿線比較・アクセス。
  • Slot 4 (general_tips / 週2本): 都内賃貸ノウハウ・初期費用削減・審査対策。
• 月間配信目標: 月間 約 98〜100 記事（全記事 9,000〜10,000字 ＋ 4言語翻訳 ＋ インラインSVG ＋ 完全一致FAQ ＆ JSON-LD）。
• 実行トリガー基盤 (Dual Execution Architecture):
  • Primary (Cloud Run Jobs): Cloud Scheduler（sorai-auto-editorial-trigger / 毎日 03:00 JST）から OIDC 認証（roles/run.developer を付与された Compute SA 902297816152-compute@developer.gserviceaccount.com）経由で Cloud Run Job（sorai-auto-editorial）を自動起動。
  • Fallback / Local (macOS LaunchAgent): com.soraitokyo.auto_editorial（~/Library/LaunchAgents/com.soraitokyo.auto_editorial.plist）により、仮想環境 Python（/Users/adachishuuhei/real-estate-cms-operations/.venv/bin/python3）を用いて 48時間周期で自律フォールバック実行。

8.5 不動産売買（購入・売却・住宅ローン・外国人購入）エディトリアル基盤仕様#

賃貸記事（Leasing）に加えて、将来的な実需購入・マンション売却・住宅ローン・外国人不動産取得の自律執筆に即時対応するための売買特化マスター基盤。

8.5.1 売買マスターエディトリアルガイド (BUY_SELL_EDITORIAL_GUIDE.md)#

• 配置: real-estate-cms-operations/docs/editorial/BUY_SELL_EDITORIAL_GUIDE.md
• 読者ペルソナ4類型:
  1. ペルソナA: 初めてのマイホーム一次取得層（30〜40代ファミリー・単身、諸費用内訳、修繕積立金・新耐震見極め）
  2. ペルソナB: 共働きパワーカップル（世帯年収1,200万〜1,800万円、ペアローン出口戦略、2026年最新住宅ローン減税・省エネ基準適合）
  3. ペルソナC: 在留外国人・海外投資家（永住権なしローン、海外送金・外為法届出、源泉徴収10.21%、多言語サポート）
  4. ペルソナD: マンション売却・住み替えオーナー（囲い込みゼロ・レインズ即時公開、3,000万円特別控除、譲渡所得税シミュレーション）
• コンプライアンス ＆ トーン: 街の親切な宅建士目線。断定的判断の提供禁止（宅建業法47条の2）および誇大広告排除（景表法）の厳格遵守。

8.5.2 売買専用 5大記事パターン ＆ 構造化テンプレート (buy_sell_templates.py)#

• 配置: real-estate-cms-operations/automation/pipeline/buy_sell_templates.py
• 5大パターン体系:
  1. Pattern A: 【購入完全ガイド型】（中古・新築マンション購入手順、諸費用6〜8%内訳、管理状態・ハザード診断）
  2. Pattern B: 【住宅ローン・資金計画型】（変動vs固定金利シミュレーション、ペアローンリスク、2026年住宅ローン控除）
  3. Pattern C: 【外国人向け日本不動産購入型】（所有権無制限、永住権なしローン、海外送金・外為法、納税管理人）
  4. Pattern D: 【不動産売却・住み替え型】（囲い込みゼロ透明売却、適正査定、3,000万円控除、媒介契約比較）
  5. Pattern E: 【エリア資産価値・相場分析型】（国交省MLIT取引価格推移、再開発・駅別相場、利回り比較）

8.5.3 売買専用 インラインSVG図解ブループリント (buy_sell_svg_templates.py)#

• 配置: real-estate-cms-operations/automation/pipeline/buy_sell_svg_templates.py
• 売買グラフィック生成関数:
  • generate_purchase_cost_breakdown_svg: 物件本体価格（例: 5,000万円）＋ 諸費用（約350万円: 仲介手数料・登記・ローン・保険・清算金）スタックバー。
  • generate_mortgage_comparison_svg: 借入4,500万円・35年返済における変動金利（0.5%） vs 固定金利（1.65%）の月額・総返済差額比較チャート。
  • generate_transaction_timeline_svg: 資金計画から残金決済・鍵引渡しまでの7ステップタイムライン。
  • generate_foreigner_purchase_flow_svg: 外国人購入・海外送金・外為法報告・登記・納税管理人選任の6ステップフロー。
• 品質保証: 780pxレスポンシブ、WCAG AAA白文字コントラスト保証（fill="#ffffff"）、シングルラインテキスト維持。

8.5.4 売買専用 CTA ＆ HubSpot CMS タグ体系#

• 購入用CTA: 「気になる物件のURLをLINEに送るだけで、仲介手数料・諸費用見積もり＆修繕積立金・ハザード無料診断」。
• 外国人用CTA: 「多言語バイリンガル宅建士によるビザ別住宅ローン診断＆海外送金サポート」。
• 売却用CTA: 「囲い込みなし！レインズ即時登録＆グローバル買主マッチング無料査定」。
• CMSタグ: BUY_GUIDE, MORTGAGE_LOANS, FOREIGNER_PROPERTY, SELL_GUIDE, ASSET_VALUE, REAL_ESTATE_TAX。

id: "09_common_architecture" title: "9. 共通モジュールおよび設計ベストプラクティス" category: "system" packages: - "packages/common" - ".agents/skills/sorai_common.py" cloud_run: endpoints: secrets: - "JWT_SECRET" - "ENCRYPTION_KEY" - "GOOGLE_CHAT_WEBHOOK_URL" - "GCP_PROJECT_ID" databases: - "system_config" - "webhook_events" - "backfill_logs"#

9. 共通モジュールおよび設計ベストプラクティス#

9.1 共通モジュール sorai_common.py#

.agents/skills/sorai_common.py は、各自動化スクリプトやエージェントスキルが依存するコアユーティリティ。

• 環境変数管理 (load_env_vars()): /Users/adachishuuhei/.gemini/antigravity/scratch/.env を動的にパースして HUBSPOT_ACCESS_TOKEN の値を返却。
• HubSpot API クライアント: 標準 urllib をラップし、トークン付与、エラーハンドリング、JSONデコードを行い、複数ページにまたがる API データをページネーションリンクをたどって自動でループ取得・結合。
• HTML テキストクレンジング (clean_html_to_text()): BeautifulSoup を使用して HTML から不要なタグ（script, style, nav など）を除外し、プレーンテキストに変換。
• SQLite キャッシュ管理: APIのクォータ消費を抑えるため、ブログ記事とサイトページのメタデータを SQLite データベース /Users/adachishuuhei/.gemini/antigravity/scratch/sorai_cache.db に保存し、24時間のキャッシュ有効期限を適用。
• Google Chat 通知送信 (send_google_chat()): GOOGLE_CHAT_WEBHOOK_URL 宛てに POST リクエストを送り、異常検知や処理結果レポートを管理者に通知。

9.2 共通の動作仕様とベストプラクティス#

Node.js モノレポ共通設定 (packages/common)#

バックエンドマイクロサービス群（line-bot, facebook-bot, deal-service, inquiry-service, resident-portal, operator-portal, apply-portal, portal-quote-prototype 等）で共有される共通モジュール。

• 環境変数ローダー (packages/common/config/env.js):
  • 本番環境（GCP Cloud Run）とローカル開発環境の環境変数を自動識別・統合。
  • Secret Manager からのシークレット動的注入、必須環境変数（PROJECT_ID, FIREBASE_PROJECT_ID 等）のバリデーションを実行。
• 構造化ロガー (packages/common/config/logger.js):
  • GCP Cloud Logging に最適化された JSON 構造化ログを出力。
  • PII（メール、電話番号、住所等）の自動マスキング（maskPII）および長文クリッピングを強制適用。
• 暗号化ユーティリティ (packages/common/utils/crypto.js):
  • 保存時（At-Rest）暗号化のための AES-256-GCM 実装。IV（初期化ベクトル）および Auth Tag による暗号論的安全性の確保。
• 認証コード正規化 (packages/common/utils/codeNormalizer.js):
  • 全角・半角英数字の相互変換、ハイフン・スペースの自動除去、大文字統一。resident-portal や operator-portal の招待・認証コード入力で共通利用。
• Cookie パースユーティリティ (packages/common/utils/cookieHelper.js):
  • decodeURIComponent の例外安全性を保証する try/catch 内包パーサー。不正な % エンコード文字を含む Cookie による 500 エラーを防止。
• 高精度価格パーサー (packages/common/utils/priceParser.js):
  • 「万円」「円」、範囲表記（〜）、全角半角混在文字列から数値を安全かつ高精度に抽出・パース。
• メール送信基盤 (packages/common/services/mail.js):
  • nodemailer.createTransport() のシングルトン化および接続プール（pool: true, maxConnections: 5, maxMessages: 100）による SMTP ソケットの枯渇防止と配信高速化。
• 共通セキュリティミドルウェア (packages/common/middleware/security.js):
  • Helmet プリセット (createHelmet):
    • 'portal': 一般Web/PWA向け標準設定（厳格なCSP、XSS保護、Clickjacking防止）。
    • 'deal': HubSpot CRM カード内 iframe 埋め込みに対応するため、frameguard: false および frame-ancestors に app.hubspot.com を許可。
    • 'api': ヘッドレスAPI/Webhook向け最小構成。
  • 動的 CORS オリジンマッチャー (createCors):
    • soraitokyo.jp 各種サブドメイン（resident, operator, line-bot, facebook-bot 等）および sorai.tokyo のホワイトリスト完全一致。
    • 自社特定FQDN（sorai-indexing-30323.web.app, sorai-indexing-30323.firebaseapp.com）および明示的HubSpotサービスURL（app.hubspot.com, app-eu1.hubspot.com, app-na2.hubspot.com）、自社Cloud RunサービスURLのみに限定登録。
    • 開発・テスト環境における localhost 自動許可および credentials: true 対応。
  • 細分化レートリミッター (rateLimiters, createRateLimiter):
    • apiLimiter（15分100回）、authLimiter（15分15回）、webhookLimiter（1分100回）、strictAiLimiter（1分10回）の共通提供。
• Vertex AI 共通クライアント (packages/common/config/vertex.js):
  • プライマリモデルとセカンダリモデルの自動フォールバック基盤。
  • トークン使用量（usageMetadata）の自動計測とロギング。
• 認証テンプレート外出し (packages/common/templates/login.html):
  • packages/common/middleware/auth.js 内に埋め込まれていたオペレーターログイン画面 HTML を独立ファイルとして分離し、メモリキャッシュ化。
• オペレーターポータル静的アセット分離 (packages/operator-portal):
  • 巨大な unified-chat.html からスタイル（public/css/unified-chat.css）とスクリプト（public/js/unified-chat.js）を完全分離。
• Google Chat 通知送信・テスト環境安全ガード (packages/common/services/googleChat.js):
  • sendGoogleChatNotification による LINE / Facebook / ポータル問い合わせの Google Chat 自動通知基盤。
  • テスト時通知完全抑止ガード: NODE_ENV === 'test' の環境下では、本番の Webhook スペース URL への実リクエストを 100% 自動遮断。モック Webhook URL（/spaces/mock/, /spaces/test/, DUMMY_）が設定されている単体テスト時のみ安全にインターセプトを許可。
  • テストユーザー検知: test_, mock_, unlinked_test_, dummy 等のテスト用コンタクト ID やテストフラグを持つユーザーの通知送信を自動スキップ。
• エラーレスポンス標準化と情報漏洩防御:
  • 500 内部サーバーエラー発生時、生の例外オブジェクトや err.message、スタックトレースの外部露出を禁止し、固定メッセージを一律返却。
• オペレーターJWTセッション有効期限ポリシー (24時間短縮):
  • 管理者・オペレーター用JWT（operator_token）の有効期限を 24h（Cookie Max-Age: 86400）に短縮。

HubSpot CRM タイムライン過去チャット履歴バックフィル基盤 (packages/common/scripts/backfill_chat_history.js)#

• HubSpot CRM 上に蓄積された顧客・入居者とのチャット履歴（Note/Communication）を走査し、Firestore chat_history コレクションへ一括同期（バックフィル）。

HubSpot 公開記事更新時の安全な再公開フロー#

1. API (GET) で現在の公開日時（publishDate）を取得・変数保持する。
2. 一時的に記事の状態を下書き（state: "DRAFT"）に PATCH 変更する。
3. postBody（本文）や tagIds（タグ）などの本体データを PATCH 更新する。
4. 保持しておいた元の publishDate をパラメータに含め、状態を PUBLISHED に戻す（PATCH）。これによって、公開日バグを防ぐと同時に、Edge キャッシュのパージ（CDN 再構築）を安全にトリガーする。

• クォータ制限と異常課金防止・フェイルセーフ設計 (packages/common/services/quota.js):
  • Firestore トランザクション日次クォータ（顧客50回/日、グローバル200回/日）および障害時の In-Memory フォールバック（memoryQuotaCache）。
  • テスト・CI自動化用の安全なクォータ初期化ヘルパー（resetQuotaForTesting）を完備。
• 会話履歴スライディングウィンドウ ＆ 要約メモリ ＆ 多言語署名重複排除 (packages/common/services/chatHistory.js & packages/common/services/hubspot/timeline.js):
  • 直近8件（4往復）のスライディングウィンドウと、Gemini Flash-Lite によるローリング要約（summary）永続化。
  • cleanAiSignature による日本語・英語・ベトナム語・ロシア語・インドネシア語のAI注記およびシステムタグの自動クレンジング・正規化（normalizeMessageTextForDedup）によるタイムライン重複完全排除。
  • timeline.js の parseMessage において、タグ除去前にブロック要素閉じタグ（</p>, </div>, </li>, </tr>, </h1-6>）および <hr>, <br> を \n に置換し、HTMLメールやNote追記時のテキスト連結・改行欠落を恒久的に防止。
• マルチチャネルアクティブ顧客検索 (packages/common/services/hubspot/contact.js):
  • searchActiveContactsForChatSpace において line_user_id / facebook_user_id / email の HAS_PROPERTY フィルターグループ（OR結合）により、LINE連携済み顧客だけでなく Facebook や Web/Email のアクティブ顧客を一括取得。
• オンボーディング＆本人確認共通サービス (packages/common/services/onboardingService.js):
  • LINE・Facebook 共通のプラットフォームアダプター構造（platformAdapter）によるステートマシン、マジックリンク生成・検証、Webシミュレーション引き継ぎコード（validateAndProcessTransferCode）の統合処理。
• 契約書パーサーの XML インジェクション防御 (packages/common/services/documentParser.js):
  • <contract_documents> タグの事前エスケープ。
• HubSpot Files API アップロードセキュリティ:
  • access: PUBLIC_NOT_INDEXABLE の統一。
• LINE CTA クリック追跡＆高信頼アトリビューション基盤 (packages/common/services/tracking/clickTracker.js):
  • Webビーコン、Origin検証、IPハッシュ化（SHA-256）、24h TTL一時保存、5分時間枠照合。
• 国土交通省 地理空間公的データ連携基盤 (packages/common/services/mlit/):
  • tileConverter.js, geocoding.js, mlitClient.js, index.js による並列フェッチ・キャッシュ・プロンプトフォーマッター。
• 共通 TypeScript 型定義基盤 (packages/common/types/):
  • chat.ts: ChannelType ('line' | 'facebook' | 'portal' | 'apply' | 'whatsapp'), SenderRole ('user' | 'agent' | 'bot' | 'operator' | 'system'), ChatMessage, AttachmentItem, BotStatusMap。
  • hubspot.ts: HubSpotContactProperties, HubSpotDealProperties, CrmCardResponse, HubSpotSearchFilter, HubSpotFilterGroup, HubSpotSearchRequest, HubSpotSearchResponse<T>, HubSpotBatchReadRequest, HubSpotBatchReadResponse<T>。
  • api.ts: UnifiedChatMessagesResponse, ToggleBotPayload, SendMessagePayload（cachedContact オプショナル型対応）, DraftSuggestPayload, DraftSuggestResponse, FileUploadResponse。
  • services.ts: BotStatusCacheEntry, BotStatusOptions, ChatHistoryEntry, FirestoreChatHistoryDoc, LinePushPayload, LineReplyPayload, FacebookMessagePayload, ContactSearchParams。
  • index.ts: 各種ドメイン型・サービス型の一括エクスポート。
  • tsconfig.json: NodeNext モジュール解決、allowJs: true、noEmit: true によるモノレポ型安全性検証。
• Bot オーケストレーター層の型安全化 (packages/line-bot/ & packages/facebook-bot/):
  • packages/line-bot/tsconfig.json & packages/facebook-bot/tsconfig.json: NodeNext モジュール解決、allowJs: true、strict: true、noEmit: true による独立型検証基盤。
  • LINE Messaging API Webhook イベント（LineWebhookBody, LineMessageEvent）および Facebook Meta Graph API Webhook（FacebookWebhookBody, FacebookMessagingEvent）の厳密な型定義。
  • services/line/orchestrator.js & services/facebook/orchestrator.js: メッセージ振り分け、6桁引き継ぎコード、Magic Link 認証、Gemini 3.8 Flash 自動応答、HubSpot 顧客同期フローの完全な型整合性。
  • ルート npm run typecheck による全パッケージ（common, operator-portal, apply-portal, line-bot, facebook-bot）一括静的解析。
• 統合チャット コアサービス層の TypeScript（.ts）移行 ＆ ゼロダウンタイム再エクスポート (packages/common/services/ & packages/operator-portal/server/services/):
  • chatHistory.ts: appendChatMessage, getChatHistory, clearChatHistory, updateRollingSummaryAsync, normalizeMessageTextForDedup を完全 TypeScript 化。Firestore トランザクション保護、最大履歴長トリム、チャネル分離タグ（'line' | 'facebook' | 'portal' | 'apply'）を厳格型付け。updateRollingSummaryAsync では要約プロンプトを3大カテゴリ（【希望条件】【顧客背景・審査状況】【検討履歴・現在の状況】）に構造化し、文字数枠を 400〜600文字（最大800文字・maxOutputTokens: 800・thinkingConfig: { thinkingBudget: 0 }）へ拡張。既存呼出元向けに chatHistory.js から export * from './chatHistory.ts' で無停止再エクスポート。
  • contextCacheManager.js: Gemini 3.8 Flash コンテキストキャッシュ（TTL 7200s）の構築ロジック（buildCachePayloadText）に、来店不要の無料オンライン個別相談（Google Meet / 60分 / カメラOFF歓迎）のコアサービス定義を同期。
  • botStatus.ts: isBotActiveForContact, setBotActiveForContact を完全 TypeScript 化。Firestore SSOT 3段階判定（①5sメモリキャッシュ ➔ ②Firestore bot_status ➔ ③未作成時 HubSpot フォールバック）および契約満了判定（expired_at）を厳密型付け。既存呼出元向けに botStatus.js から再エクスポート。
  • hubspot_oauth.ts: getAccessToken, refreshAccessToken, loadTokens, saveTokens, exchangeCodeForTokens を完全 TypeScript 化。Single-Flight Promise ミューテックス（refreshPromise）およびメモリキャッシュ（memoryTokens）の厳格型付け。既存呼出元向けに hubspot_oauth.js から再エクスポート。
  • chatMessageService.ts: fetchUnifiedChatMessages, buildHistoryQueriesMap を完全 TypeScript 化。Pure Chat Store SSOT による直接取得、クオートトークン紐付け、重複排除ウィンドウ短縮（10分 ➔ 3秒）、時系列昇順ソート処理を厳密型付け。既存呼出元向けに chatMessageService.js から再エクスポート。
  • draftGenerator.ts: generateDraftSuggestion を完全 TypeScript 化。Pure Chat Store 履歴サニタイズ（sanitizeHistory）と Gemini 3.8 Flash プロンプト生成・コンテキストキャッシュ連携を厳格型付け。既存呼出元向けに draftGenerator.js から再エクスポート。
• 入居者ポータル コア層およびフロントエンドの Full TypeScript（.ts / .tsx）移行 (packages/resident-portal/):
  • types/: ResidentTokenPayload, ResidentCustomer, ContractDetail, PortalMessage, ResidentDocument, PortalShareRecord, TransferCodeRecord の厳密な型定義 SSOT を配備。
  • server/: app.ts, server.ts, server/middleware/auth.ts, server/routes/*.ts, server/services/*.ts, server/utils/*.ts を完全 TypeScript 化。Cloud Run（Node 22 LTS）ネイティブ型除去実行（--experimental-strip-types）によりトランスパイル不要で直接実行。既存呼出元向けに各 .js より export * from './*.ts' で無停止再エクスポート。
  • src/: main.tsx, App.tsx, hooks/*.ts, components/**/*.tsx, locales/*.ts, utils/*.ts, vite.config.ts によるフロントエンド完全型安全化。Vite ビルド（React 19 / JSX ➔ TSX）による高速バンドル。

9.3 モノレポ全領域における型安全アーキテクチャ ＆ ルート・スクリプト・spec-viewer 仕様#

real-estate-chatbot モノレポでは、個別のマイクロサービスパッケージだけでなく、ルート直下のエントリーポイント、運用スクリプト群、および仕様書ビューア・MCP サーバーに至るまで、すべての JavaScript / TypeScript コードが 100% 静的型検査の保護下に置かれています。

real-estate-chatbot/ (Monorepo Root)
├── tsconfig.json                       # ルート直下 (server.js, eslint.config.js, scripts/**/*.js)
├── server.js                           # 共通マルチサービスディスパッチャー
├── eslint.config.js                    # ESLint Flat Config (Node / Browser / React)
├── scripts/                            # 運用・初期化・同期スクリプト群
│   ├── sync-line-webhook.js            # LINE Webhook 自動同期スクリプト
│   ├── init_quote_bigquery_table.js    # BigQuery quote_logs パーティションテーブル初期化
│   └── test_bigquery_quote_log.js      # BigQuery ログ記録テスト
├── spec-viewer/                        # 仕様書ビューア ＆ MCP サーバー
│   ├── tsconfig.json                   # spec-viewer 独立型検証設定 (checkJs: true)
│   ├── types/                          # 型定義ディレクトリ
│   │   ├── spec-viewer.d.ts            # ドメイン型 (SpecHeading, SpecSection, Catalog等) & セッション拡張
│   │   └── cookie-session.d.ts         # cookie-session アンビエント型定義
│   ├── server.js                       # 仕様書 Web サーバー (Express + Marked)
│   ├── mcp-server.js                   # sorai-spec MCP サーバー (Stdio)
│   ├── test-mcp.js                     # MCP 疎通テスト
│   ├── lib/auth.js                     # Google OAuth 2.0 認証ミドルウェア
│   ├── lib/parser.js                   # 仕様書 Markdown パーサー & TOC/検索インデックス生成
│   └── routes/api.js                   # 仕様書 REST API エンドポイント
└── packages/ (全8マイクロサービス + 共通パッケージ)
    ├── common/tsconfig.json            # 共通型定義 (types/*.ts) & 共有ユーティリティ
    ├── line-bot/tsconfig.json          # LINE Messaging Bot
    ├── facebook-bot/tsconfig.json      # Facebook Messenger Bot
    ├── resident-portal/tsconfig.json   # 入居者向けチャットポータル (React / Vite)
    ├── operator-portal/tsconfig.json   # オペレーターポータル (Express / ESM modules)
    ├── apply-portal/tsconfig.json      # 入居申込・審査ポータル
    ├── deal-service/tsconfig.json      # 図面OCR・帯替え・重複検知サービス
    ├── inquiry-service/tsconfig.json   # 問い合わせ下書き生成サービス
    └── portal-quote-prototype/tsconfig.json # 初期費用相見積もりシミュレーター

① 一括静的型検査コマンド (npm run typecheck)#

ルート package.json に定義された "typecheck" スクリプトにより、モノレポ全11ターゲットの一括静的型検査（tsc --noEmit）が瞬時に実行されます：

"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p packages/common/tsconfig.json --noEmit && tsc -p packages/operator-portal/tsconfig.json --noEmit && tsc -p packages/apply-portal/tsconfig.json --noEmit && tsc -p packages/line-bot/tsconfig.json --noEmit && tsc -p packages/facebook-bot/tsconfig.json --noEmit && tsc -p packages/deal-service/tsconfig.json --noEmit && tsc -p packages/inquiry-service/tsconfig.json --noEmit && tsc -p packages/portal-quote-prototype/tsconfig.json --noEmit && tsc -p packages/resident-portal/tsconfig.json --noEmit && tsc -p spec-viewer/tsconfig.json --noEmit"

② 型安全化の設計原則#

1. NodeNext モジュール解決の統一: すべての tsconfig.json で target: ESNext、module: NodeNext、moduleResolution: NodeNext を統一採用し、ES Modules（.js 拡張子付きインポート）の完全互換を維持。
2. No-Build 厳格型安全性（アプローチ A）: spec-viewer/ ではビルドステップを一切追加せず、Node.js 実行環境をそのまま保った状態で checkJs: true ＋ 型定義ファイル（types/spec-viewer.d.ts, types/cookie-session.d.ts）＋ 完全な JSDoc 注釈により 100% 型安全化を実現。
3. ゼロ型エラー保証: CI/CD パイプラインおよびローカル開発において、全パッケージ・スクリプトで型エラー 0 件（0 warnings/errors）をコミット条件とする。

9.4 入居者ポータル 双方向チャットパイプライン仕様 (Candidate 2)#

9.4.1 チャット履歴取得 API (GET /api/chat/history / packages/resident-portal)#

• 認証と認可: verifyCustomerToken ミドルウェアにより、リクエストヘッダー（Authorization: Bearer <token>）の顧客 JWT トークンを検証。customerId の存在と整合性を担保。
• メッセージロール正規化マッピング:
  • role === 'operator' || role === 'staff' || role === 'human' ➔ operator
  • role === 'user' ➔ user
  • それ以外（model, assistant 等） ➔ assistant
• データ取得元: common/services/chatHistory.js の getChatHistory(customerId) を使用し、Firestore chat_history/${customerId} から履歴を一元取得。

9.4.2 オペレーター送信メッセージのポータル永続化 (packages/operator-portal)#

• packages/operator-portal/server/services/channelDispatcher.ts:
  • channelSendHandlers.portal: ポータル送信時のハンドラーを定義。
  • dispatchOutboundMessage: オペレーターがポータルチャネル宛てに送信したテキストおよび添付ファイルを、await appendChatMessage(customerId, 'operator', messageToSync, 100, 'portal') により chat_history/${customerId} に確実に追記（channel: 'portal'）。

9.4.3 フロントエンド履歴マージ ＆ リアルタイム同期待ち受け (packages/resident-portal)#

• packages/resident-portal/src/hooks/useChat.js:
  • ローカル ＆ サーバー履歴のマージ: mergeHistoryMessages ヘルパーにより、ローカル（localStorage）とサーバー側（/api/chat/history）のメッセージを照合。1分以内の同一テキスト重複を排除しつつマージし、時系列（昇順）に整列。
  • Page Visibility API 連動の 10 秒ポーリング: ブラウザタブが表示状態（document.visibilityState === 'visible'）の間、10秒間隔でサーバー履歴を定期同期。オペレーターからの返信メッセージをリアルタイムに自動反映。非表示状態ではタイマーを停止して通信を完全抑制。

9.4.4 有人サポートメッセージの視覚的識別 (ChatMessage.jsx ＆ chat.css)#

• packages/resident-portal/src/components/Chat/ChatMessage.jsx:
  • msg.sender === 'operator' のメッセージに対し、lucide-react の Headset アイコン、多言語「サポート担当」バッジ（ja, en, vi, ru, id）をレンダリング。
• packages/resident-portal/src/styles/chat.css:
  • .message-operator .avatar: ブルーグラデーション背景（linear-gradient(135deg, #2563EB, #1D4ED8)）とシャドウ。
  • .message-operator .message-bubble: 淡いブルー系グラスモーフィズム背景（rgba(239, 246, 255, 0.95)）とボーダー。AI 自動応答と有人スタッフからのメッセージをユーザーが一目で識別可能。

9.5 過去会話ログ確定タイムスタンプ付与 ＆ 不変日時保証仕様 (chatHistory.ts)#

9.5.1 不変タイムスタンプの担保と時系列破綻防止#

• 課題: 過去のレガシーメッセージや初期バックフィルデータにおいて、Firestore chat_history 内のメッセージ要素（ChatHistoryEntry）に timestamp が存在しないレコードが存在していた。
• 恒久的解決策:
  • appendChatMessage トランザクション処理において、取得した doc.data().messages 内に timestamp が未定義の要素が存在する場合、その場で前後関係を保持した不変タイムスタンプ（now - (len - idx) * 10000）を補完して Firestore へ永続化。
  • これにより、新着メッセージ追加時にドキュメント更新日時（histData.timestamp）の更新によって古いメッセージの計算時刻が現在時刻付近へタイムシフトし、連続送信メッセージの間に過去メッセージが割り込む時間逆転現象を恒久的に根絶。

9.6 HubSpot OAuth 分散ロック ＆ 複数インスタンス間スピンウェイト仕様 (hubspot_oauth.ts)#

9.6.1 複数コンテナ間競合の課題とリスク#

• Cloud Run のオートスケール等で複数インスタンス（例: 2〜3台）が同時に稼働している環境において、アクセストークン期限（30分）を迎えた際、全コンテナが同時に HubSpot API へ refresh_token を送信してしまう競合リスクが存在していた。
• HubSpot の OAuth 仕様によっては、一度リフレッシュされた古いリフレッシュトークンが即座に無効化され、片方のインスタンスで invalid_grant が発生する危険性があった。

9.6.2 Firestore 分散ロック ＆ スピンウェイト機構#

• ロックの獲得と検査 (refreshAccessToken):
  • トークン更新前に Firestore system_config/hubspot_oauth を確認。
  • refreshing_at が記録されており、かつ 30 秒以内（now - refreshing_at < 30000）である場合、別コンテナが現在更新中と判断して HubSpot への追加リクエストを行わず、最大 10 秒間（1秒間隔）のスピンウェイト（待機） に入る。
  • 先行インスタンスが更新を完了して新トークンを保存（created_at > refreshing_at）した時点で即座にループを抜け、復号した最新トークンをメモリキャッシュにロードして返却。
• ロックの保持と解放:
  • 自インスタンスがリフレッシュを行う場合、refreshing_at: Date.now() を書き込んでロックを獲得し、HubSpot API へ 1 度だけリフレッシュ要求を送信。
  • saveTokens 実行時、新トークンとともに refreshing_at: null を書き込んでロックを明示的かつ確実に解放。
  • エラー発生時も catch 節で refreshing_at: null をリセット。万が一インスタンスが突然死した場合でも 30 秒で自動失効（TTL）するフェイルセーフを完備。
• 単一インスタンス内 Single-Flight Mutex との協調:
  • 同一インスタンス内の複数並行リクエストは refreshPromise による Single-Flight Mutex で共有され、インスタンス間は Firestore 分散ロックで制御される 2 層防御体制を確立。

9.7 オンボーディング時のチャネル別保存キー集約仕様 (onboardingService.js)#

• LINE 友だち追加・マジックリンク認証時のキー分離:
  • packages/common/services/onboardingService.js において、contact.id への重複保存を完全撤廃し、LINE チャットは lineUserId のみに集約。
  • 入居者ポータルの portal_history_${customerId} との混信を防止。

id: "10_gcp_infrastructure" title: "10. Google Cloud Platform (GCP) 全体構成・インフラ・APIクォータ・リミット仕様" category: "system" packages: - "packages/*" cloud_run: - "real-estate-chatbot" - "real-estate-chatbot-operator" - "real-estate-chatbot-line-bot" - "real-estate-chatbot-facebook-bot" - "real-estate-chatbot-apply" - "real-estate-chatbot-deal" - "real-estate-chatbot-quote" - "gemini-quote-generator" - "real-estate-chatbot-api" - "sorai-system-spec" - "sorai-auto-editorial" endpoints: secrets: - "GOOGLE_APPLICATION_CREDENTIALS" - "GCP_PROJECT_ID" - "FIREBASE_PROJECT_ID" databases: - "system_config/ai_degradation" - "backup_schedules"#

10. Google Cloud Platform (GCP) 全体構成・インフラ・APIクォータ・リミット仕様#

本セクションは、ソライ東京（Sorai Tokyo）の全社PropTechエコシステムを支える Google Cloud Platform (GCP) インフラ基盤の全体像、各マネージドサービス（Cloud Run, Cloud Run Jobs, Vertex AI, Cloud Firestore, BigQuery, Secret Manager, Cloud Scheduler, Cloud Logging / Monitoring）の設計仕様、APIクォータ、レートリミット、無料枠活用状況、およびコスト・セキュリティ安全ガード（Safety Guardrails）を網羅した包括的な技術リファレンスである。

10.1 プロジェクト全体構成と役割分担 (Project Landscape & Roles)#

1. プロジェクト基本情報#

• 本番 GCP プロジェクト ID: sorai-indexing-30323
• プロジェクト番号 (Project Number): 902297816152
• デフォルトFQDNドメイン: sorai-indexing-30323.web.app / *.run.app
• 独自カスタムドメイン群 (Cloudflare エッジプロキシ保護 / 🟠 Proxied):
  • 入居者・契約者ポータル: https://resident.soraitokyo.jp
  • 管理者・オペレーターポータル: https://operator.soraitokyo.jp
  • 申込ポータル: https://apply.soraitokyo.jp
  • 初期費用シミュレーター: https://quote.soraitokyo.jp
  • 公式Webサイト・CMS: https://soraitokyo.jp / https://www.soraitokyo.jp
• DNS 権威サーバー ＆ エッジ WAF:
  • Cloudflare Anycast DNS (amanda.ns.cloudflare.com, micah.ns.cloudflare.com)
  • 全サブドメインにエッジ WAF / DDoS 自動緩和 / Bot 検知 / TLS 1.3 を常時適用

2. リージョン配置戦略 (Multi-Region & Latency Optimization)#

3. IAM & サービスアカウント最小権限設計 (Least Privilege Architecture)#

• 1. Cloud Run ランタイムサービスアカウント:
  • SA名: real-estate-chatbot-sa@sorai-indexing-30323.iam.gserviceaccount.com
  • 付与ロール (Role Bindings): roles/datastore.user, roles/aiplatform.user, roles/bigquery.dataEditor, roles/bigquery.jobUser, roles/secretmanager.secretAccessor, roles/logging.logWriter
• 2. GitHub Actions CI/CD デプロイヤーサービスアカウント:
  • SA名: github-deployer@sorai-indexing-30323.iam.gserviceaccount.com
  • 付与ロール: roles/run.admin, roles/iam.serviceAccountUser, roles/artifactregistry.writer
• 3. Cloud Scheduler / Compute サービスアカウント:
  • SA名: 902297816152-compute@developer.gserviceaccount.com
  • 付与ロール: roles/run.developer, roles/secretmanager.secretAccessor, roles/storage.objectViewer, roles/logging.logWriter, roles/iam.serviceAccountTokenCreator
  • 用途: Cloud Scheduler（sorai-auto-editorial-trigger）から Cloud Run Job（sorai-auto-editorial）を OIDC 認証経由で実行トリガーする起動権限。
• 4. デフォルト Compute / App Engine サービスアカウントの最小権限化:
  • roles/editor などの広範権限を剥奪し、Cloud Run Job 実行に必要な最小権限（roles/run.developer）に絞り込んでセキュリティ侵害経路を遮断。

10.2 Cloud Run / Cloud Run Jobs 全サービス一覧・設定・無料枠消化状況#

1. Cloud Run サービス一覧（本番・ステージング全マトリクス）#

2. Cloud Run Jobs（バッチ自動化パイプライン）#

3. GCP 無料枠 (Free Tier) と消化状況・コストゼロ最適化#

• Cloud Run 無料利用枠（月次）: 2,000,000 リクエスト/月、360,000 vCPU秒/月、180,000 GiB秒/月。
• ゼロ待機コスト戦略 (min-instances = 0): 全サービスで最小インスタンス数を 0 に固定。
• Artifact Registry 自動クリーンアップポリシー: 最新3世代保持、タグなし7日経過で自動削除。

10.3 Vertex AI & Gemini API クォータ・レートリミット・安全ガード#

1. 利用モデル・用途マトリクス#