本アプリケーションは、Google Apps Script (GAS) と Google Chat API を連携させたサーバーレスアーキテクチャで構成されています。
1. プロジェクト情報 (Project Information)
GCP Project Name: kh-chat-bot
App Architecture: Google Chat API + Google Apps Script + Google Sheets (Datastore)
(※セキュリティ保護のため、ソースコードおよびデータベースの実体へのアクセス経路は非公開とし、社内開発・運用メンバーのみに制限しています)
2. 認証とアクセス制御のロジック (Authentication & Authorization Logic)
セキュリティを担保するため、イベント発火時（onMessage）に以下のアクセス制御（RBAC）を実装しています。
ドメイン認証:
リクエスト元のメールアドレスを判定し、内部ドメイン（@kohnankh.com）からのリクエストを許可します。
ホワイトリスト認証:
外部ドメインユーザーの場合、ユーザーIDをベースにセキュアなバックエンド（Google Sheets）上の許可リストと照合します。
リストに存在しないユーザーからのリクエストは弾かれます。
3. データ取得とキャッシュ戦略 (Data Fetching & Caching Strategy)
ユーザーに提示するアプリ一覧のデータは、バックエンドのデータベースで一元管理されています。
Chat APIのレスポンスタイムアウト（30秒ルール）を回避し、UXを向上させるため、GASの CacheService を使用して取得データをJSON形式でキャッシュし、データベースへの直接のReadオペレーションを最小限に抑える設計としています。
キャッシュミス時のみスプレッドシートへのReadオペレーションが発生する設計です。
4. デプロイメントとバージョン管理 (Deployment & Version Control) 本アプリケーションにおけるGASのコード更新（デプロイ）手順は、システムの稼働において死活的に重要です。 Google Chat APIは、初期設定時に発行された特定の「デプロイID（Deployment ID）」と紐付いてボットのルーティングを行っています。そのため、誤った手順でデプロイを行うとIDが変わり、ボットが一切応答しなくなる致命的な障害（リンク切れ）が発生します。
【厳守】正しいアップデート手順 (Strict Update Procedure) ソースコードを修正し、本番環境に反映させる場合は、絶対に「新しいデプロイ」を作成せず、既存のデプロイの「バージョン」を上げる必要があります。
GASエディタ右上の 「デプロイ (Deploy)」 をクリックし、「デプロイを管理 (Manage deployments)」 を選択します。
左側のリストから、現在アクティブなデプロイ（Chat APIと紐付いているもの）を選択します。
画面右上の 「鉛筆アイコン（編集 / Edit）」 をクリックします。
「バージョン (Version)」のプルダウンメニューを開き、「新バージョン (New version)」 を選択します。
（任意）Descriptionに修正内容をメモし、右下の 「デプロイ (Deploy)」 ボタンをクリックして保存します。
⚠️ 警告 (CRITICAL WARNING): 「新しいデプロイ (New deployment)」の作成禁止 エディタ右上から「新しいデプロイ」を作成してしまうと、全く新しいデプロイIDが発行されてしまいます。これにより Google Cloud Platform (Chat API設定) 側のIDと不一致が生じ、システムが完全に停止します。本番環境の更新において「新しいデプロイ」は絶対に実行しないでください。
本アプリを新規公開、または権限（スコープ）を変更してアップデートする際、GCP (Google Cloud Platform) 上の設定と Google の審査プロセスにおいて、非常に複雑な依存関係と厳格なルールが存在します。以下の要件を満たさないと、審査の申請自体がブロックされるか、即座にリジェクトされます。
5-1. OAuth スコープの「3点完全一致」ルール
アプリが要求する OAuth スコープは、以下の 3箇所で整合している必要があります。
GAS のマニフェスト (appsscript.json): oauthScopes 配列内
Marketplace SDK: 「App Configuration」タブ内の OAuth scopes
OAuth 同意画面 (OAuth Consent Screen): 「Data Access」ステップで要求されるスコープ
これらの設定に不整合がある場合、
不要なスコープが登録されている
実際のコードで使用していない権限が含まれている
と判断され、審査でリジェクトされる可能性が高くなります。
そのため 3箇所のスコープを同一内容に揃えることを強く推奨します。
(※本アプリでは最低限の構成として userinfo.email, userinfo.profile, spreadsheets の3つのみを明示的に指定しています。)
5-2. センシティブ・スコープと OAuth 審査 (OAuth Verification)
本アプリはデータベースとして Google Sheets を使用するため、スプレッドシートへのアクセスという**「センシティブ（機密性が高い）スコープ」**を要求します。
センシティブ・スコープを含むアプリを公開する場合、Marketplace の審査とは別軸で、Google の Trust & Safety チームによる「OAuth Verification（OAuth 審査）」を事前に通過する必要があります。
対応必須事項: OAuth同意画面の設定にて、①「なぜこの権限が必要なのか（Justification）」の英語での説明文と、②「実際にアプリがその権限を使って機能している様子を録画したYouTube動画（限定公開）」のURL提出が必須となります。youtube-demo
5-3. 【重要】「SUBMIT FOR REVIEW」ボタンが押せない罠
GCP コンソールの Marketplace SDK 画面において、「Store Listing」の入力がすべて終わっているにも関わらず 「SUBMIT FOR REVIEW（審査へ提出）」ボタンがグレーアウトして押せない（Currently disabled と表示される） 現象が発生します。
原因: これは Marketplace のエラーではなく、「5-2 の OAuth Verification が『提出済み (In review)』または『承認済み』になっていないため」 です。
回避手順: 1. 先に「API とサービス > OAuth 同意画面」へ行き、センシティブ・スコープの理由とデモ動画URLを入力する。
2. OAuth 同意画面のウィザードを最後まで進め、「確認して提出 (Submit for verification)」 を実行する。
3. OAuth のステータスが "Pending" になったことを確認してから、Marketplace SDK の画面に戻る。
4. これによりロックが解除され、「SUBMIT FOR REVIEW」ボタンが押せるようになります。
1. 背景と目的 (Background)
本アプリケーションの公開にあたり、Google Workspace Marketplace の「ブランド検証（Brand Verification）」を通過させる必要がありました。審査には以下の要件があります。
URLの分離: 「ホームページ（Home）」と「プライバシーポリシー（Privacy）」で完全に異なるURL（パス）を用意すること。
ドメインの信頼性: アプリの公開ドメインが、Google Cloud / Workspaceで所有権証明済みの自社ドメイン（kohnankh.com）と一致していること。
当初の単一ページ構成では「1. URLの分離」が難しかったため、複数ページを簡単に作成・管理できる Google サイト (Google Sites) をバックエンドのホスティングとして採用しました。さらに「2. ドメインの信頼性」を満たすため、MATBAO（ドメインレジストラ）のDNS設定を変更し、Googleサイトにサブドメイン bot.kohnankh.com をマッピング（カスタムドメイン設定）しています。
これにより、審査要件を満たしつつ、ユーザーには自社ブランドの公式URLとして提供できる構成となっています。
2. MATBAO DNS 設定手順 (DNS Configuration via MATBAO)
Googleサイトに独自ドメインを紐付けるため、ドメイン管理者（MATBAO）のコントロールパネルにて以下のDNSレコード（CNAME）を設定しています。
レコードタイプ (Type): CNAME
ホスト名 / レコード名 (Name): bot （※ bot.kohnankh.com となるように設定）
宛先 / ターゲット (Value/Target): ghs.googlehosted.com
TTL: デフォルト値（または 3600 等）
【インフラ連携の仕組み】
ユーザーが https://bot.kohnankh.com/home や https://bot.kohnankh.com/privacy にアクセスすると、MATBAOのDNSルーターが ghs.googlehosted.com（Googleのサーバー）へリクエストを転送し、該当するGoogleサイトのページが表示される仕組みです。