--- id: "00_index" title: "ソライ東京 システム総合仕様書 (Sorai Tokyo System Specification)" category: "system" packages: - "packages/*" - "real-estate-cms-operations" - "soraitokyo-cms-theme" - "real-estate-crm-extensions" cloud_run: - "real-estate-chatbot" - "real-estate-chatbot-apply" - "real-estate-chatbot-operator" - "sorai-auto-editorial" - "sorai-system-spec" endpoints: secrets: - "GEMINI_API_KEY" - "HUBSPOT_ACCESS_TOKEN" - "LINE_CHANNEL_SECRET" - "GCP_PROJECT_ID" databases: - "contracts" - "users" - "chat_sessions" - "apply_records" - "quote_simulations" - "system_config" --- # ソライ東京 システム総合仕様書 (Sorai Tokyo System Specification) | 項目 | 定義・対象リソース | | :--- | :--- | | **対象パッケージ** | `packages/*` (全モノレポパッケージ), `real-estate-cms-operations`, `soraitokyo-cms-theme`, `real-estate-crm-extensions` | | **Cloud Run サービス** | `real-estate-chatbot`, `real-estate-chatbot-operator`, `sorai-auto-editorial` (Job), `sorai-system-spec` | | **主要エンドポイント** | 全体アーキテクチャ・ルーティング集約 (`/api/*`, `/webhook/*`, `/quote/*`, `/apply/*`) | | **依存 Secret** | 全社共有 Secret群 (`GEMINI_API_KEY`, `HUBSPOT_ACCESS_TOKEN`, `LINE_CHANNEL_SECRET`, `GCP_PROJECT_ID` 等) | | **Firestore コレクション** | `contracts`, `users`, `chat_sessions`, `apply_records`, `quote_simulations`, `system_config` 等 | 本ドキュメントは、ソライ東京（Sorai Tokyo）の不動産テック（PropTech）エコシステムの全体構成、データフロー、主要モジュール仕様、開発履歴を網羅した総合技術仕様書です。 ## 概要とシステムアーキテクチャ (System Architecture) ソライ東京システムは、不動産賃貸・売買業務における「契約・重要事項説明の自動化」「LINE/Web/電話IVRによる多言語接客」「Deal Extractorによる物件資料・間取り図の高速並列解析」「Gemini初期費用シミュレーター＆見積書自動生成」「自律型エディトリアルパイプラインによるSEO記事自動執筆・配信」を統合した次世代PropTechプラットフォームです。 ### 全体アーキテクチャトポロジー図 (System Infrastructure Topology) ```mermaid 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 sec 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)
・5言語ブログ / エリアガイド
・特設LP (プレジオ北綾瀬ASIAN)
・LINE最優先問い合わせフォーム
・初期費用シミュレーター(/quote)"] LINE_APP["LINE LIFF アプリ
(契約書閲覧・本人確認・自動ログイン)"] HS_CARD["HubSpot UI Extension
(sorai-lease-bot 管理カード)"] RES_PORTAL["入居者ポータル (React/Vite)
(重説PDF閲覧・AIチャット)"] EST_TOOL["見積書メーカー (Next.js)
(初期費用計算・PDF生成)"] end %% 3. バックエンド & バッチ subgraph BE ["③ バックエンドおよびAPI (Cloud Run)"] API_GW["Express.js Monorepo API
・packages/resident-portal (重説API)
・packages/operator-portal (管理API)
・packages/line-bot (LINE制御)
・packages/deal-service (並列OCR図面解析)
・packages/apply-portal (申込API)
・共通認証 / PIIログマスク"] BATCH_JOB["Cloud Run Job: sorai-auto-editorial
・日次/週次自律執筆 (15〜20 URL/日)
・重複チェック・5言語自動翻訳
・Push-Live・GSC即時送信"] IVR_SVC["AI電話自動応答 IVR (Node.js)
(リアルタイム双方向音声処理)"] SPEC_VIEWER["Cloud Run: sorai-system-spec
(仕様書ポータル / OAuth・Basic認証)"] end %% 4. AI & コグニティブ基盤 subgraph AI ["④ AIおよびインテリジェンス基盤 (Vertex AI)"] GEMINI_38["Gemini 3.8 Flash
(契約書・重説対話 / LINE自動応答 / 有人下書き / 複雑推論)"] GEMINI_35["Gemini 3.5 Flash Lite
(初期費用シミュレーター / 高速OCR / 自動翻訳)"] GEMINI_LIVE["Gemini 3.1 Live API
(リアルタイム音声対話 IVR)"] end %% 5. データベース & 永続化 subgraph DB ["⑤ データベースおよびデータ連携"] FS["Cloud Firestore (完全閉鎖型)
・契約情報 / チャット履歴 / OTP
・AES-256-GCM 暗号化保存"] BQ["BigQuery (データレイク/分析)
・quote_logs (シミュレーションログ)
・editorial_queue (トピックキュー)
・token_usage_audit (コスト監査)"] HS_CRM["HubSpot CRM
(Deals / Contacts / Tickets)"] GCS["Cloud Storage
(PDF図面 / 契約書原本 / 添付ファイル)"] end %% 6. セキュリティ・認証 subgraph SEC ["⑥ セキュリティ & 監視"] SM["Secret Manager (環境変数・APIキー)"] WIF["Workload Identity Federation (CI/CD 鍵レス)"] MON["Cloud Monitoring & 課金キルスイッチ"] end %% 接続関係 U_WEB --> WEB_HP U_LINE --> LINE_APP U_LINE --> API_GW U_TEL --> IVR_SVC U_STAFF --> HS_CRM U_STAFF --> HS_CARD WEB_HP --> API_GW LINE_APP --> API_GW HS_CARD --> API_GW RES_PORTAL --> API_GW EST_TOOL --> API_GW API_GW --> GEMINI_38 API_GW --> GEMINI_35 BATCH_JOB --> GEMINI_38 BATCH_JOB --> GEMINI_35 IVR_SVC <--> GEMINI_LIVE API_GW --> FS API_GW --> BQ API_GW --> HS_CRM API_GW --> GCS BATCH_JOB --> HS_CRM BATCH_JOB --> BQ API_GW --> SM API_GW --> MON CI_CD --> WIF ``` --- ## 仕様書モジュール一覧 (Modular Specifications) 本システム仕様書は、マイクロモジュール化設計に基づき以下の13章構成に分割管理されています。 | No. | ドキュメントファイル | 分野・モジュール名 | 主な収録内容 | |:---:|:---|:---|:---| | **00** | [`00_index.md`](00_index.md) | **全体概要・マスタ目次** | システム概要、アーキテクチャトポロジー、モジュール一覧 | | **01** | [`01_customer_service_ai.md`](01_customer_service_ai.md) | **接客対応・契約重説AI仕様** | 入居者ポータル、500記事RAGナレッジ連携、HubSpot CRM同期、有人切り替え | | **02** | [`02_line_facebook_bots.md`](02_line_facebook_bots.md) | **LINE / FB Bot 仕様** | オンボーディングFSM、マジックリンク認証、Meta審査仕様、LINE CTA追跡 | | **03** | [`03_ivr_voice_system.md`](03_ivr_voice_system.md) | **AI電話自動応答 IVR 仕様** | 03-6161-8484、Gemini Live API、動的VAD、ジッターバッファ、6段階トリアージ | | **04a** | [`04a_apply_portal.md`](04a_apply_portal.md) | **入居申込ポータル＆eKYC＆国交省API仕様** | 8段階申込フロー、動的追加要請、OTP検証、国交省API物件カルテ診断 | | **04b** | [`04b_operator_portal.md`](04b_operator_portal.md) | **オペレーター管理画面＆統合チャット仕様** | 統合チャットスペース (Chat Space)、リアルタイム同期、AI返信アシスト、ポーリング最適化 | | **05** | [`05_quote_maker.md`](05_quote_maker.md) | **Gemini 見積書メーカー仕様** | Next.js構成、PDFKit生成、HubSpot双方向連携、初期費用シミュレーター (/quote) | | **06** | [`06_deal_extractor.md`](06_deal_extractor.md) | **Deal Extractor 仕様** | SSEストリーミング、Sharp画像変換、SHA-256重複排除、並列OCR高速化 | | **07** | [`07_crm_extensions.md`](07_crm_extensions.md) | **HubSpot CRM UI拡張仕様** | カスタムカード、統合チャット埋め込み、Breeze AI連携、ファイルプロキシ302最適化 | | **08** | [`08_cms_editorial_pipeline.md`](08_cms_editorial_pipeline.md) | **自律型エディトリアル仕様** | 自動化スクリプト、エージェントスキル体系、Cloud Run Jobs 自律執筆 | | **09** | [`09_common_architecture.md`](09_common_architecture.md) | **共通モジュール・設計規約** | `sorai_common.py`、`env.js`、Monorepo共通設定、エラーハンドリング | | **10** | [`10_gcp_infrastructure.md`](10_gcp_infrastructure.md) | **GCP インフラ・クォータ仕様** | プロジェクト構成、Cloud Run サービス一覧、無料枠最適化、課金キルスイッチ | | **11** | [`11_security_and_secrets.md`](11_security_and_secrets.md) | **セキュリティ・機密管理仕様** | WIF鍵レス認証、Secret Manager、AES-256-GCM、PIIマスキング、Firestore閉鎖ルール | | **12** | [`12_google_antigravity_guide.md`](12_google_antigravity_guide.md) | **Google AGY 運用・MCPガイド** | AGY 2.0 運用術、プロンプト体系、スラッシュコマンド、MCP/ADCトラブルシューティング | | **99** | [`99_history_and_changelogs.md`](99_history_and_changelogs.md) | **直近開発履歴・更新ログ** | 直近の開発実績・改善ログ（過去ログは `docs/archives/` にアーカイブ保管） | --- ## 総合目次 (Master Table of Contents) 1. **[01. 接客対応・契約重説AI仕様](01_customer_service_ai.md)** - [1.1 システム全体構成 (Architecture Overview)](01_customer_service_ai.md#11-システム全体構成-architecture-overview) - [1.2 主要機能仕様 (Core Functionality)](01_customer_service_ai.md#12-主要機能仕様-core-functionality) - [1.3 500記事RAGナレッジ連携](01_customer_service_ai.md#13-500記事ragナレッジ連携line-37-flash-thinking-medium--hp-35-flash-lite) - [1.4 HubSpot CRM リアルタイム同期・有人切り替え](01_customer_service_ai.md#14-hubspot-crm-リアルタイム同期有人切り替え) 2. **[02. LINE / Facebook Bot 仕様](02_line_facebook_bots.md)** - [2.1 オンボーディング状態遷移管理 (onboardingService.js)](02_line_facebook_bots.md#21-オンボーディング状態遷移管理-onboardingservicejs) - [2.2 メール・マジックリンク検証フロー](02_line_facebook_bots.md#22-メールマジックリンク検証-email-magic-link-verification-フロー) - [2.3 Facebook Messenger Webhook 検証とセキュリティ仕様](02_line_facebook_bots.md#23-facebook-messenger-webhook-検証とセキュリティ仕様) - [2.4 Meta App Review スクリーンキャスト録画・審査申請仕様](02_line_facebook_bots.md#24-meta-app-review-スクリーンキャスト録画審査申請仕様-meta-app-review-recorder--submission-spec) - [2.5 Webポータルからのシミュレーション結果引継ぎフロー](02_line_facebook_bots.md#25-webポータルからのシミュレーション結果引継ぎフロー) - [2.6 手動照合フォールバックフロー](02_line_facebook_bots.md#26-手動照合フォールバックフロー) - [2.7 LINE CTA クリック追跡＆HubSpot 流入元アクセスログ自動記録仕様](02_line_facebook_bots.md#27-line-cta-クリック追跡hubspot-流入元アクセスログ自動記録仕様) 3. **[03. AI電話自動応答（IVR）システム仕様](03_ivr_voice_system.md)** - [3.1 基本アーキテクチャ](03_ivr_voice_system.md#31-基本アーキテクチャ) - [3.2 動的システムプロンプト & 多言語自動切替・名乗り最適化設計](03_ivr_voice_system.md#32-動的システムプロンプト--多言語自動切替名乗り最適化設計) - [3.3 音声認識・リスニング＆動的ノイズ判定 (Adaptive VAD)](03_ivr_voice_system.md#33-音声認識リスニング動的ノイズ判定-adaptive-vad) - [3.4 音声ストリーム完全スムーズ化・エコー抑制＆ジッターバッファ設計](03_ivr_voice_system.md#34-音声ストリーム完全スムーズ化エコー抑制ジッターバッファ設計-audio-streaming-engine) - [3.5 通話後自動化パイプライン & 6段階トリアージ即時通知](03_ivr_voice_system.md#35-通話後自動化パイプライン--6段階トリアージ即時通知-post-call-automation) - [3.6 OCR & IVR 連携フロー](03_ivr_voice_system.md#36-ocr--ivr-連携フロー) 4. **[04a. 入居申込ポータル＆eKYC＆国交省API仕様](04a_apply_portal.md)** - [4a.1 申込ポータル 業務実務フロー概要](04a_apply_portal.md#4a1-申込ポータル-業務実務フロー概要) - [4a.2 主要設計思想と実務適合ルール](04a_apply_portal.md#4a2-主要設計思想と実務適合ルール) - [4a.3 Apply Portal REST API エンドポイント一覧](04a_apply_portal.md#4a4-apply-portal-rest-api-エンドポイント一覧) - [4a.4 国土交通省 不動産情報ライブラリ（MLIT API）連携仕様](04a_apply_portal.md#4a5-国土交通省-不動産情報ライブラリmlit-api連携物件カルテ周辺環境ai診断仕様) 5. **[04b. オペレーター管理画面＆統合チャット仕様](04b_operator_portal.md)** - [4b.1 Firestore-First Pure Chat Store アーキテクチャおよび統合チャット仕様](04b_operator_portal.md#4b1-firestore-first-pure-chat-store-アーキテクチャおよび統合チャットunified-chat仕様) - [4b.2 オペレーター応答時のAI誤応答完全防止＆直近オペレーター返信自動ガード](04b_operator_portal.md#4b3-オペレーター応答時のai誤応答完全防止--送信者高精度識別--直近オペレーター返信自動ガード) - [4b.3 統合チャットスペース（Chat Space）UI/UX ＆ リアルタイム同期仕様](04b_operator_portal.md#4b4-クラウド実行基盤gcp-cloud-run--リアルタイム双方向同期--本人確認書類ui仕様) - [4b.4 統合チャット AI 返信アシスト（AI下書き作成）仕様](04b_operator_portal.md#4b13-統合チャット-ai-返信アシストai下書き作成ui-不具合解消--操作性アクセシビリティ仕様) 5. **[05. Gemini 見積書メーカー（HubSpot Projects & UI Extensions 連携版）技術仕様](05_quote_maker.md)** - [5.1 Next.js アプリケーションの全体構成](05_quote_maker.md#51-nextjs-アプリケーションの全体構成) - [5.2 PDF生成機能の仕様](05_quote_maker.md#52-pdf生成機能の仕様) - [5.3 HubSpot ＆ データ連携フロー](05_quote_maker.md#53-hubspot--データ連携フロー) - [5.4 初期費用シミュレーター (/quote) 技術仕様](05_quote_maker.md#54-初期費用シミュレーター-quote-技術仕様) - [5.5 HubSpot 取引連携 SUUMO物件一括調査・空室確認メモ自動記録機能](05_quote_maker.md#55-hubspot-取引連携-suumo物件一括調査空室確認メモ自動記録機能-hubspot-quote-generator) - [5.6 見積書ジェネレーター フロントエンド・マルチプレビュー仕様](05_quote_maker.md#56-見積書ジェネレーター-フロントエンドマルチプレビュー仕様-documentpreviewtsx-successsteptsx) - [5.7 Gemini Context Caching（コンテキストキャッシュ）アーキテクチャ](05_quote_maker.md#57-gemini-context-cachingコンテキストキャッシュアーキテクチャ) - [5.8 Gemini Structured Outputs ＆ Thinking Budget 最適化仕様](05_quote_maker.md#58-gemini-structured-outputs型定義json出力--thinking-budget-最適化仕様) - [5.9 初期費用シミュレーター Structured Outputs ＆ Gemini 3.5 Flash-Lite 最適化仕様](05_quote_maker.md#59-初期費用シミュレーター-structured-outputs--gemini-35-flash-lite-最適化仕様) - [5.10 国土交通省 物件所在地・公的データAI診断連携仕様](05_quote_maker.md#510-国土交通省-物件所在地公的データai診断locationdiagnosis連携仕様) 6. **[06. Deal Extractor サービス（deal-service）仕様](06_deal_extractor.md)** - [6.1 サービス概要・全体フロー (Overview & Flow)](06_deal_extractor.md#61-サービス概要全体フロー-overview--flow) - [6.2 主要モジュール構成 (Directory & Modules)](06_deal_extractor.md#62-主要モジュール構成-directory--modules) - [6.3 HubSpot Iframe 埋め込み UI/UX 設計とファイル選択信頼性の確立](06_deal_extractor.md#63-hubspot-iframe-埋め込み-uiux-設計とファイル選択信頼性の確立) - [6.4 SSE リアルタイム進捗ストリーミング ＆ 4段階パイプラインステッパー](06_deal_extractor.md#64-sse-server-sent-events-リアルタイム進捗ストリーミング--4段階パイプラインステッパー) - [6.5 画像フォーマット自動変換エンジン (Sharp) ＆ 多様フォーマット対応](06_deal_extractor.md#65-画像フォーマット自動変換エンジン-sharp--多様フォーマット対応) - [6.6 間取り図・書類の SHA-256 重複排除チェック ＆ 履歴トラッキング](06_deal_extractor.md#66-間取り図書類の-sha-256-重複排除チェック--履歴トラッキング) - [6.7 Vertex AI Gemini トークンロギング ＆ コスト監査基盤](06_deal_extractor.md#67-vertex-ai-gemini-トークンロギング--コスト監査基盤) - [6.8 並列ストリーミングOCR高速化アーキテクチャ](06_deal_extractor.md#68-並列ストリーミングocr高速化アーキテクチャ) - [6.9 インフラ・セキュリティ設計 (Cloud Run & Limits)](06_deal_extractor.md#69-インフラセキュリティ設計-cloud-run--limits) - [6.10 AI図面マッチング JSONパース多層防御](06_deal_extractor.md#610-ai図面マッチング-jsonパース多層防御-safeparseaijson--structured-outputs) - [6.11 深層セキュリティ硬化仕様](06_deal_extractor.md#611-深層セキュリティ硬化オペレーター認証hubspot署名二重防壁モーダルcsp保護非インデックス化) - [6.12 帯替え専用図面生成機能](06_deal_extractor.md#612-帯替え専用図面生成機能hubspotタイムライン自動保存) - [6.13 リアルタイム・ストリーミングUI ＆ ライブフィード](06_deal_extractor.md#613-リアルタイムストリーミングui--ライブフィード) - [6.14 図面解析 Structured Outputs & 帯替え Thinking Budget 0](06_deal_extractor.md#614-図面解析-structured-outputs--帯替え-thinking-budget-0--重複物件ad客付条件比較) 7. **[07. HubSpot CRM UI拡張 (カスタムカード仕様)](07_crm_extensions.md)** - [7.1 契約者専用チャット管理カード](07_crm_extensions.md#71-契約者専用チャット管理カード-tenant-chat-management-card) - [7.2 統合チャット埋め込みカード](07_crm_extensions.md#72-統合チャット埋め込みカード-unified-chat-sidebar-card) - [7.3 パブリックファイルプロキシの 302 Redirect 最適化](07_crm_extensions.md#73-パブリックファイルプロキシの-302-redirect-最適化-file-proxy-optimization) - [7.4 添付ファイル送信時の日本語ファイル名 UTF-8 デコードおよび文字化け防止](07_crm_extensions.md#74-添付ファイル送信時の日本語ファイル名-utf-8-デコードおよび文字化け防止-file-upload-encoding-protection) - [7.5 統合チャットUI/UX刷新・LINEネイティブUI化とスマートフォン最適化](07_crm_extensions.md#75-統合チャットuiux刷新lineネイティブui化とスマートフォン最適化-unified-chat-responsive-redesign--line-native-ui) - [7.6 リアルタイム対話同期 ＆ HubSpot / Firestore ハイブリッド履歴マージ](07_crm_extensions.md#76-リアルタイム対話同期--hubspot--firestore-ハイブリッド履歴マージ-real-time-hybrid-chat-history-synchronization) 8. **[08. 開発・運用自動化スクリプトおよびエージェントスキル仕様](08_cms_editorial_pipeline.md)** - [8.1 自動化パイプラインスクリプト](08_cms_editorial_pipeline.md#81-自動化パイプラインスクリプト-real-estate-cms-operationsautomation) - [8.2 ワークスペース内追加システム・自動化スイート](08_cms_editorial_pipeline.md#82-ワークスペース内追加システム自動化スイート) - [8.3 エージェントスキル仕様 (.agents/skills)](08_cms_editorial_pipeline.md#83-エージェントスキル仕様-agentsskills) - [8.4 執筆パイプライン運用 ＆ データドリブン自律プランニング仕様](08_cms_editorial_pipeline.md#84-執筆パイプライン運用--データドリブン自律プランニング仕様) 9. **[09. 共通モジュールおよび設計ベストプラクティス](09_common_architecture.md)** - [9.1 共通モジュール `sorai_common.py`](09_common_architecture.md#91-共通モジュール-sorai_commonpy) - [9.2 共通の動作仕様とベストプラクティス](09_common_architecture.md#92-共通の動作仕様とベストプラクティス) 10. **[10. Google Cloud Platform (GCP) 全体構成・インフラ・APIクォータ・リミット仕様](10_gcp_infrastructure.md)** - [10.1 プロジェクト全体構成と役割分担](10_gcp_infrastructure.md#101-プロジェクト全体構成と役割分担-project-landscape--roles) - [10.2 Cloud Run / Cloud Run Jobs 全サービス一覧・設定・無料枠消化状況](10_gcp_infrastructure.md#102-cloud-run--cloud-run-jobs-全サービス一覧設定無料枠消化状況) - [10.3 Vertex AI & Gemini API クォータ・レートリミット・安全ガード](10_gcp_infrastructure.md#103-vertex-ai--gemini-api-クォータレートリミット安全ガード) - [10.4 Cloud Firestore 構成・コレクション設計・セキュリティ](10_gcp_infrastructure.md#104-cloud-firestore-構成コレクション設計セキュリティ) - [10.5 BigQuery データセット・テーブル構造・クエリリミット・最適化](10_gcp_infrastructure.md#105-bigquery-データセットテーブル構造クエリリミット最適化) - [10.6 Secret Manager & 認証・機密情報管理](10_gcp_infrastructure.md#106-secret-manager--認証機密情報管理-least-privilege--wif) - [10.7 Cloud Scheduler & 自動化パイプライン](10_gcp_infrastructure.md#107-cloud-scheduler--自動化パイプライン-cron-architecture) - [10.8 Cloud Logging, Cloud Monitoring & 課金キルスイッチ](10_gcp_infrastructure.md#108-cloud-logging-cloud-monitoring--課金キルスイッチ-safety-guardrails) - [10.9 Google Cloud API クォータ・制限一覧（総合リファレンステーブル）](10_gcp_infrastructure.md#109-google-cloud-api-クォータ制限一覧総合リファレンステーブル) - [10.10 GCE VM 常時稼働インスタンスによるゼロコスト・ウォームアップ＆死活監視・深夜パトロール](10_gcp_infrastructure.md#1010-gce-vm-常時稼働インスタンスによるゼロコストウォームアップ死活監視深夜パトロール) - [10.11 GitHub Actions による Spec Drift Linter ＆ 自動仕様書コンパイル CI/CD パイプライン](10_gcp_infrastructure.md#1011-github-actions-による-spec-drift-linter--自動仕様書コンパイル-cicd-パイプライン) 11. **[11. 全社セキュリティ・認証認可・機密情報管理仕様](11_security_and_secrets.md)** - [11.1 Workload Identity Federation (WIF) CI/CD 鍵レス認証](11_security_and_secrets.md#111-workload-identity-federation-wif-cicd-鍵レス認証) - [11.2 Secret Manager 格納シークレット一覧・最小権限設計](11_security_and_secrets.md#112-secret-manager-格納シークレット一覧最小権限設計) - [11.3 アプリケーション層での AES-256-GCM 暗号化](11_security_and_secrets.md#113-アプリケーション層での-aes-256-gcm-暗号化) - [11.4 PII 個人情報の構造化ログマスキング](11_security_and_secrets.md#114-pii-個人情報の構造化ログマスキング-pii-masking) - [11.5 Cloud Firestore 完全閉鎖型セキュリティルール](11_security_and_secrets.md#115-cloud-firestore-完全閉鎖型セキュリティルール) - [11.6 Webhook 署名検証と早期切断](11_security_and_secrets.md#116-webhook-署名検証と早期切断-early-rejection) - [11.7 細分化レートリミット ＆ DoS 防御](11_security_and_secrets.md#117-細分化レートリミット-rate-limiting--dos-防御) - [11.8 プロンプトインジェクション多層防御](11_security_and_secrets.md#118-プロンプトインジェクション多層防御) - [11.9 オペレーター管理ポータルの認証認可 ＆ 物理パッケージ分離](11_security_and_secrets.md#119-オペレーター管理ポータルの認証認可--物理パッケージ分離) - [11.10 ソフトウェアサプライチェーン保護](11_security_and_secrets.md#1110-ソフトウェアサプライチェーン保護-github-actions-sha-ピン留め) - [11.11 統一セキュリティミドルウェア & タイミング攻撃耐性](11_security_and_secrets.md#1111-統一セキュリティミドルウェア--タイミング攻撃耐性-timingsafeequal) - [11.12 深層セキュリティ硬化仕様](11_security_and_secrets.md#1112-深層セキュリティ硬化仕様-deep-security-hardening) - [11.13 脆弱性スキャナー・機密情報探索攻撃の先回り遮断](11_security_and_secrets.md#1113-脆弱性スキャナー機密情報探索攻撃の先回り遮断security-shield--blockmaliciousprobes) - [11.14 Cloudflare グローバルエッジ WAF ＆ DDoS 多層防御アーキテクチャ](11_security_and_secrets.md#1114-cloudflare-グローバルエッジ-waf--ddos-多層防御アーキテクチャ-cloudflare-edge-protection) - [11.15 セキュリティ突破緊急アラート ＆ 週次生存確認ハートビート仕様](11_security_and_secrets.md#1115-セキュリティ突破緊急アラート--週次生存確認ハートビート仕様-security-breach-alert--weekly-heartbeat) - [11.16 Cloudflare WAF カスタムルールセット仕様](11_security_and_secrets.md#1116-cloudflare-waf-カスタムルールセット仕様-http_request_firewall_custom) - [11.17 Cloudflare Turnstile スマート人間認証仕様](11_security_and_secrets.md#1117-cloudflare-turnstile-スマート人間認証仕様-smart-captcha-integration) - [11.18 マルチチャネル対話ログの改ざん防止・ロール完全性保護](11_security_and_secrets.md#1118-マルチチャネル対話ログの改ざん防止ロール完全性保護-multi-channel-log-integrity) - [11.19 HubSpot 認証トークンの永続 Private App Token（PAT）統一 ＆ データ整合性保護](11_security_and_secrets.md#1119-hubspot-認証トークンの永続-private-app-tokenpat統一--データ整合性保護) - [11.20 全社サービスアカウント完全鍵レス化（100% Keyless）＆ 最小権限 IAM 設計（PoLP）](11_security_and_secrets.md#1120-全社サービスアカウント完全鍵レス化100-keyless--最小権限-iam-設計polp) - [11.21 Cloudflare エッジセキュリティ硬化 ＆ HSTS・Transform Rules 自動注入仕様](11_security_and_secrets.md#1121-cloudflare-エッジセキュリティ硬化--hststransform-rules-自動注入仕様) - [11.22 仕様書ポータル（Spec Viewer）脱ID/PASS ＆ Google OAuth 2.0 SSO 認証アーキテクチャ](11_security_and_secrets.md#1122-仕様書ポータルspec-viewer脱idpass--google-oauth-20-sso-認証アーキテクチャ) - [11.23 レガシー・不要シークレットのライフサイクル管理 ＆ 物理完全削除](11_security_and_secrets.md#1123-レガシー不要シークレットのライフサイクル管理--物理完全削除-secret-decommissioning) 12. **[12. Google Antigravity (AGY) 2.0 運用術 ＆ MCPトラブルシューティング](12_google_antigravity_guide.md)** - [12.1 AGY 2.0 概要と従来型AI（1.0）からの進化](12_google_antigravity_guide.md#121-agy-20-概要と従来型ai10からの進化) - [12.2 企業向け研修カリキュラム・スライド構成](12_google_antigravity_guide.md#122-企業向け研修カリキュラムスライド構成) - [12.3 初期設定プロンプトとセキュリティガード](12_google_antigravity_guide.md#123-初期設定プロンプトとセキュリティガード) - [12.4 スラッシュコマンド・サブエージェント活用法](12_google_antigravity_guide.md#124-スラッシュコマンドサブエージェント活用法) - [12.5 Google Cloud MCP ADC認証エラー対策](12_google_antigravity_guide.md#125-google-cloud-mcp-bigquery--gcs--logging--developer-knowledge-adc認証エラー対策) - [12.6 Python ランタイム環境問題 (`CLOUDSDK_PYTHON`) の解決](12_google_antigravity_guide.md#126-python-ランタイム環境問題-cloudsdk_python-の解決) - [12.7 サンドボックス環境と BypassSandbox の運用基準](12_google_antigravity_guide.md#127-サンドボックス環境-standard-sandbox-と-bypasssandbox-の運用基準) - [12.8 マルチプロジェクト分割アーキテクチャ ＆ ルール最適化規約](12_google_antigravity_guide.md#128-マルチプロジェクト分割アーキテクチャ--ルール最適化規約) - [12.9 仕様書ポータル（sorai-system-spec）AI/MCP 連携 & REST API 規約](12_google_antigravity_guide.md#129-仕様書ポータルsorai-system-specaimcp-連携--rest-api-規約) - [12.10 sorai-spec ローカル MCP サーバー仕様と Antigravity 連携](12_google_antigravity_guide.md#1210-sorai-spec-ローカル-mcp-サーバー仕様と-antigravity-連携) - [12.11 Cloudflare MCP 連携 & セキュリティ・URL監査スキル](12_google_antigravity_guide.md#1211-cloudflare-mcp-連携--セキュリティurl監査スキル-sorai-radar-security) 13. **[99. 開発履歴および改善実績アーカイブ](99_history_and_changelogs.md)** - [開発履歴および改善実績（直近ログ）](99_history_and_changelogs.md#開発履歴および改善実績) - ※ 2026年8月29日以前の過去開発履歴は [`docs/archives/history_2026_h1.md`](archives/history_2026_h1.md) にアーカイブ保管されています。 --- 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）仕様 | 項目 | 定義・対象リソース | | :--- | :--- | | **対象パッケージ** | `packages/resident-portal`, `packages/inquiry-service`, `packages/common` | | **Cloud Run サービス** | `real-estate-chatbot` (`sorai-customer-portal` / `sorai-inquiry-service`) | | **主要エンドポイント** | `POST /api/chat`, `GET /api/chat/history`, `POST /api/inquiry/draft`, `POST /api/transfer/generate`, `GET /api/documents/proxy` | | **依存 Secret** | `GEMINI_API_KEY`, `HUBSPOT_ACCESS_TOKEN`, `ENCRYPTION_KEY`, `JWT_SECRET` | | **Firestore コレクション** | `contracts`, `users`, `chat_sessions`, `transfers`, `inquiries` | ### 1.1 システム全体構成 (Architecture Overview) #### システム全体構成図 (System Architecture Diagram) ```mermaid 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)
・5言語ブログ / エリアガイド
・特設LP (プレジオ北綾瀬ASIAN)
・LINE最優先問い合わせフォーム
・初期費用シミュレーター(/quote)"] LINE_APP["LINE LIFF アプリ
(契約書閲覧・本人確認・自動ログイン)"] HS_CARD["HubSpot UI Extension
(sorai-lease-bot 管理カード)"] RES_PORTAL["入居者ポータル (React/Vite)
(重説PDF閲覧・AIチャット)"] EST_TOOL["見積書メーカー (Next.js)
(初期費用計算・PDF生成)"] end %% 3. バックエンド & バッチ subgraph BE ["③ バックエンドおよびAPI (Cloud Run)"] API_GW["Express.js Monorepo API
・packages/resident-portal (重説API)
・packages/line-bot (LINE制御)
・packages/deal-service (並列OCR図面解析)
・packages/apply-portal (申込API)
・共通認証 / PIIログマスク"] BATCH_JOB["Cloud Run Job: sorai-auto-editorial
・日次/週次自律執筆 (15〜20 URL/日)
・重複チェック・5言語自動翻訳
・Push-Live・GSC即時送信"] IVR_SVC["AI電話自動応答 IVR (Node.js)
(リアルタイム双方向音声処理)"] SPEC_VIEWER["Cloud Run: sorai-system-spec
(仕様書ポータル / OAuth・Basic認証)"] end %% 4. AI & コグニティブ基盤 subgraph AI ["④ AIおよびインテリジェンス基盤 (Vertex AI)"] LLM_TEXT["Gemini 3.8 Flash
(契約QA・長文執筆・LINE自動応答・5言語翻訳)"] LLM_LITE["Gemini 3.5 Flash Lite
(初期費用シミュレーター・超低コスト並列OCR)"] LLM_LIVE["Gemini 3.1 Live API
(超低遅延リアルタイム音声対話)"] LLM_VISION["Gemini Multimodal Vision
(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`) | プロパティ名 | ラベル | 型 | 選択肢 (Options) | 説明 | | :--- | :--- | :--- | :--- | :--- | | `line_integration_status` | LINE連携ステータス | enumeration (select) | `unlinked` (未連携)
`linked` (連携済み)
`manual_verification` (手動照合中) | LINE公式アカウントとHubSpotコンタクトの紐付け状態 | | `facebook_integration_status` | Facebook連携ステータス | enumeration (select) | `unlinked` (未連携)
`linked` (連携済み) | Facebook MessengerとHubSpotコンタクトの紐付け状態 | #### 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 `）に含まれる顧客認証 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 オンボーディング＆本人確認フロー仕様 | 項目 | 定義・対象リソース | | :--- | :--- | | **対象パッケージ** | `packages/line-bot`, `packages/facebook-bot`, `packages/common` | | **Cloud Run サービス** | `real-estate-chatbot-line-bot`, `real-estate-chatbot-facebook-bot` | | **主要エンドポイント** | `POST /api/line/webhook`, `POST /api/facebook/webhook`, `GET /api/line/verify-link`, `GET /api/facebook/verify-link`, `GET /api/liff/auth` | | **依存 Secret** | `LINE_CHANNEL_SECRET`, `LINE_CHANNEL_ACCESS_TOKEN`, `FACEBOOK_APP_SECRET`, `FACEBOOK_PAGE_ACCESS_TOKEN`, `FACEBOOK_VERIFY_TOKEN` | | **Firestore コレクション** | `line_states`, `facebook_states`, `webhook_events`, `chat_sessions`, `transfers` | 本モジュールでは、LINE公式アカウントおよびFacebook Messengerボットにおけるユーザーオンボーディング、本人確認、セキュリティ認証、およびWebアクセス追跡の技術仕様を定義する。 ### 2.1 オンボーディング状態遷移管理 (onboardingService.js) 新規ユーザー追加時、または未連携ユーザーからの発信時、LINEユーザーIDまたはFacebookユーザーIDとHubSpotコンタクトを安全に紐付けるためのフロー。実装は [verification.js](file:///Users/adachishuuhei/real-estate-chatbot/packages/line-bot/services/line/verification.js) および共通 [onboardingService.js](file:///Users/adachishuuhei/real-estate-chatbot/packages/common/services/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](file:///Users/adachishuuhei/real-estate-chatbot/packages/common/services/mail.js#L275) 経由で送信。 3. **コンタクトの検索とマージロジック**: * マジックリンクがクリックされると、トークン内のメールアドレスをもとに HubSpot CRM のコンタクトを検索。 * すでにそのメールアドレスで登録されたコンタクト（本登録顧客）が存在する場合、LINE/Facebook のユーザーIDをそのコンタクトのカスタムプロパティ（`line_user_id` / `facebook_user_id`）に同期。 * チャット初回接触時に自動生成された一時的な仮コンタクト（`line_user_id`等しか持たないレコード）が存在する場合は、本登録コンタクトに対して [mergeHubSpotContacts](file:///Users/adachishuuhei/real-estate-chatbot/packages/common/services/hubspot/contact.js#L13) を実行し、タイムライン履歴やプロパティの重複を統合する。 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](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）システム仕様 | 項目 | 定義・対象リソース | | :--- | :--- | | **対象パッケージ** | `packages/common`, `clocall-gemini-phone` (GCE Asterisk/Node.js Orchestrator) | | **Cloud Run サービス** | N/A (GCE VM: `clocall-phone-tokyo-vm`, Asterisk + `gemini-orchestrator`) | | **主要エンドポイント** | TCP 9092 (Audiosocket), WebSocket (Gemini Multimodal Live API), `POST /api/ivr/webhook` | | **依存 Secret** | `GEMINI_API_KEY`, `HUBSPOT_ACCESS_TOKEN`, `GOOGLE_CHAT_WEBHOOK_URL` | | **Firestore コレクション** | `call_logs`, `transcripts`, `system_config` (AI縮退判定) | 本モジュールでは、電話問い合わせをリアルタイムに自動処理し、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`）を生成・適用。 ```mermaid graph TD A["📞 入電 (Asterisk AudioSocket)"] --> B["発信者番号デコード & HubSpot CRM 検索"] B -->|新規発信者| C["【Pattern 4: 新規顧客】
「お電話ありがとうございます、ソライ東京です！AI担当がお伺いします。お部屋探しや空室確認のご相談でしょうか？」"] B -->|登録済み顧客| D["【Pattern 1: 既存顧客】
初回挨拶統一（氏名呼び出し禁止・社内参照用コンテキスト保持）
「お電話ありがとうございます、ソライ東京です！AI担当がお伺いします。お部屋探しや空室確認のご相談でしょうか？」"] B -->|営業・勧誘履歴| E["【Pattern 2: 営業電話】
早期お断り・公式HP問い合わせ窓口への誘導"] B -->|無言履歴あり| F["【Pattern 3: 過去無音履歴】
過去履歴を無視しフラットな新規対応開始"] B -->|アウトバウンド発信| G["【Outbound Mode】
完全ミュート（サイレント）・自動音声聞き取りモード"] C & D --> H["🌐 多言語自動切替 (EN / VI / RU / ID)
外国人サポート案内（保証人不要・多言語契約・ビザ対応）"] ``` * **初回第一声の統一（新規・既存共通）**: * 初回第一声発話: 「お電話ありがとうございます、ソライ東京です！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](file:///Users/adachishuuhei/real-estate-chatbot/packages/common/services/hubspot/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 申込ポータル 業務実務フロー概要 ```mermaid 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. 本人確認電話アナウンス
『管理会社・保証会社から電話が入る場合があります』"] 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箇所以上の入力フォーム（氏名、生年月日、住所、勤務先、年収、緊急連絡先、同居人情報等）において、すべての ``, `