AI名刺整理君（Microsoft 365版）
初期設定ガイド

このガイドは、初期設定を行う担当者向けです。
先に「はじめにお読みください.txt」をお読みください。
画面の表記や配置は、Microsoft・Googleの更新により、本書と異なる場合が
あります。その場合は、最後の「参考資料（公式ドキュメント）」で最新の手順を
ご確認ください。

本アプリのしくみ
======================================================================
・MeishiAI.exe: 名刺を処理するプログラムです。
・SharePoint: 名刺画像を置くフォルダーと、結果を記録するリスト（名刺リスト）
  を使います。名刺リストは、手順6で本アプリが作成します。
・Microsoftのアプリ登録: 本アプリが、人のサインインなしでSharePointに
  接続するための登録です。
・Gemini API（Google）: 名刺画像を読み取るAIです。
・Teamsのワークフロー: 処理結果をTeamsのチャネルにお知らせします。

準備するもの
======================================================================
・手順1: SharePointサイトの編集権限
・手順2: Microsoft 365の管理者アカウント（管理者の同意を与えられる権限）
・手順3: お知らせを受け取るTeamsのチャネル
・手順4: Googleアカウント
・手順5〜7: インターネット接続できる Windows 11（64ビット）のパソコン
  （Windows 10での動作は確認していません）

手順1 SharePointを準備する
  SharePointサイトの所有者（サイトの編集権限がある方）
======================================================================
1. 使用するSharePointサイトを、ブラウザーで開きます。
2. アドレスバーの「https://…/sites/サイト名」までの部分をコピーし、
   メモ帳などに保存します（手順2と手順5で使用）。
     例: https://contoso.sharepoint.com/sites/Cards
3. サイトのドキュメントライブラリ（通常は「ドキュメント」）を開き、名刺用の
   フォルダー（例: 名刺データ）を作成します。その中に、次の3つのフォルダーを
   作成します（フォルダー名は自由です。手順5で使用）。
     ・未処理　名刺画像をアップロードする場所
     ・処理済　読み取りが終わった画像の移動先
     ・要確認　人の確認が必要な画像の移動先
   フォルダーは、メニュー バーの「＋ 新規」→「フォルダー」を選択し、名前を
   入力して「作成」を押すと作成できます。
   結果を記録する名刺リストは、手順6で自動で作成されます。ここで作成する
   必要はありません。
＜確認ポイント＞ 次の構成になっていること。
    ドキュメント
    └ 名刺データ（名刺用のフォルダー）
        ├ 未処理
        ├ 処理済
        └ 要確認

手順2 Microsoftにアプリを登録する
  Microsoft 365の管理者
======================================================================
（(ウ)の管理者の同意と(エ)は、管理者の権限がないと完了できません）
(ア) アプリを登録する
 1. https://entra.microsoft.com にサインインし、左側のメニューの
    「アプリの登録」→「＋ 新規登録」を選択します。
 2. 「名前」に分かりやすい名前（例: 名刺データボット）を入力し、
    「サポートされているアカウントの種類」で「シングルテナントのみ - （自社名）」
    を選択します。「リダイレクト URI」は空欄のままにして、「登録」を押します。
 3. 表示された「概要」の画面で、次の2つをコピーし、メモ帳などに保存します
    （手順5で使用。アプリケーション (クライアント) ID は、13でも使用）。
      ・アプリケーション (クライアント) ID
      ・ディレクトリ (テナント) ID
＜確認ポイント＞ 「アプリの登録」の一覧に、登録したアプリが表示されること
                （表示されない場合は「すべてのアプリケーション」タブを
                確認します）。
(イ) シークレットを作成する
 4. 左側のメニューの「証明書とシークレット」→「クライアント シークレット」→
    「＋ 新しいクライアント シークレット」を選択します。
 5. 右側に表示される画面で「説明」を入力し、「有効期限」（3か月〜24か月）を
    選択して、「追加」を押します。
 6. 一覧に表示された「値」をコピーし、メモ帳などに保存します（手順5で使用）。
    ・「値」は、この画面を離れると二度と表示されません。
      「シークレット ID」ではありません。
    ・有効期限を記録し、期限が切れる前に新しいシークレットを作成して
      .env を更新します。
＜確認ポイント＞ 一覧に、作成したシークレットと有効期限が表示されること。
(ウ) アクセス許可を設定する
 7. 左側のメニューの「API のアクセス許可」→「＋ アクセス許可の追加」→
    「Microsoft Graph」→「アプリケーションの許可」を選択します。
 8. 検索欄に Sites.Selected と入力し、「Sites」を開いて Sites.Selected に
    チェックを入れ、「アクセス許可の追加」を押します。
    （最初から登録されている User.Read は、そのままで構いません）
 9. 「（組織名）に管理者の同意を与えます」を押し、「はい」を押します。
＜確認ポイント＞ Sites.Selected の状態に、緑のチェックが表示されること。
(エ) サイトとアプリを結び付ける（Graph Explorer）
    (ウ)だけでは、まだどのサイトにもアクセスできません。
    （Graph Explorer の画面は、日本語の環境でも英語で表示されます）
 10. https://developer.microsoft.com/graph/graph-explorer を開き、右上の
     アイコンから、管理者のアカウントでサインインします。
 11. 画面上部の左のメソッドを「GET」、その右のバージョンを「v1.0」にして、
     URL欄に次のように入力し、右側の「Run query」を押します。
       https://graph.microsoft.com/v1.0/sites/（サイトのアドレス）
     サイトのアドレスは、手順1-2で保存したアドレスから「https://」を外し、
     「.com」の後に「:」を入れたものです（手順5の SP_SITE_URL と同じ値）。
       例: https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/Cards
     表示された結果の "id" の値を、カンマを含めてすべてコピーします。
       例: contoso.sharepoint.com,xxxxxxxx-...,yyyyyyyy-...
 12. メソッドを「POST」に変えて、URL欄に次のように入力します。
     （{id} の部分は、11でコピーした値全体に置き換えます）
       https://graph.microsoft.com/v1.0/sites/{id}/permissions
 13. URL欄の下の「Request body」タブに次の内容を貼り付け、< > の部分を
     置き換えます。ロールの「manage」は、手順6で名刺リストを作成するために
     必要です。
       {
         "roles": ["manage"],
         "grantedToIdentities": [{
           "application": {
             "id": "<アプリケーション (クライアント) ID>",
             "displayName": "<アプリの名前>"
           }
         }]
       }
 14. URL欄の下の「Modify permissions」タブで「Open the permissions panel」を
     押します。右側の検索欄に Sites.FullControl.All と入力し、「Sites」を
     開いて、Sites.FullControl.All の横にある「Consent」を押し、承認します。
 15. 「Run query」を押します。
＜確認ポイント＞ 「Created - 201」と表示されること。
                「Forbidden - 403」の場合は、管理者のアカウントでサインイン
                しているか、14の承認が済んでいるかを確認します。400の場合は、
                URLのIDと Request body の内容を確認します。
    この権限で名刺リストを作成できることは、手順6の 0 で確認します。
    名刺リストの作成後も、ロールは「manage」のままにします
    （「0_名刺リストの作成.cmd」は、足りない列の追加や、バージョンアップの
    ときにも使います）。

手順3 Teamsのお知らせを設定する
  お知らせを受け取るTeamsチャネルのメンバー
======================================================================
1. Teamsで、お知らせを受け取るチャネルを開き、右上の「…」から
   「ワークフロー」を選択します。
   「ワークフロー」が見つからない場合は、次の順に探します。
   ・Teams左側のバーの「…」アイコンを押し、「ワークフロー」を検索します。
   ・それでも見つからない場合は、左側のバーの「＋」アイコンを押し、
     アプリの一覧または検索欄で「ワークフロー」を探して「追加」を押します。
   ・どこにも見つからない場合は、組織の設定で利用できない可能性があります。
     Microsoft 365の管理者にご相談ください。
2. テンプレート「Webhook アラートを チャネル に送信する」を選択します。
   似た名前で、送信できる人を限定するテンプレート（英語名に "from specific
   people" や "from people in an org" が付くもの）は使いません。
3. 投稿先のチームとチャネルを確認して、保存します。
4. 保存後の詳細画面に表示される「Webhookリンクをコピー」を押し、コピーした
   URLをメモ帳などに保存します（手順5で使用）。
＜注意＞ Webhook URL はパスワードと同等です。メール送信やチャット共有は
        避け、共有フォルダーへ保管しないでください。
＜確認ポイント＞ Webhook URL を保存できたこと（実際に届くかは手順6で
                確認します）。

手順4 Gemini APIのキーを用意する
  Gemini APIを管理する方
======================================================================
（ボタンなどの表記は日本語の画面のものです。英語の画面では（ ）内の表記です）
1. https://aistudio.google.com/api-keys に、Googleアカウントでサインインします。
   APIキーは組織管理下の Google アカウントおよびプロジェクトで作成することを
   推奨します。特定の個人に依存した運用とならないようご注意ください。
2. 右上の「API キーを作成」（Create API key）を押します。キーの名前を入力し、
   プロジェクトの一覧から新しいプロジェクトを作成する項目（Create new project）
   を選択して、プロジェクト名を入力して作成し、キーを作成します。
3. 作成されたAPIキーをコピーし、メモ帳などに保存します（手順5で使用）。
4. 無料プランは1日に処理できる件数が少なく、送信した画像がGoogleのサービス
   改善に利用されるため、業務では有料プランを設定してください。
   「API キー」（API keys）または「プロジェクト」（Projects）の画面で、
   プロジェクトの「課金を設定」（Set up billing）を押し、お支払い方法を登録します。
   5ドル以上の前払いが必要です。前払いした残高は12か月で失効し、返金されません。
   残高が0ドルになると、すべてのAPIキーが使えなくなり、名刺の処理が止まります。
＜確認ポイント＞ APIキーを保存できたこと（実際に使えるかは手順6で
                確認します）。

手順5 設定ファイル（.env）に入力する
  本アプリを使うパソコンの担当者
======================================================================
1. 「1_初期設定.cmd」をダブルクリックします。メモ帳で .env が開きます。
2. 手順1〜4で保存した値を、次の項目に入力して、上書き保存します。
   値は = の後にそのまま入力します（" などで囲む必要はありません）。

  MS_TENANT_ID          手順2-3で保存したディレクトリ (テナント) ID
  MS_CLIENT_ID          手順2-3で保存したアプリケーション (クライアント) ID
  MS_CLIENT_SECRET      手順2-6で保存したシークレットの値
  SP_SITE_URL           手順1-2で保存したサイトのアドレスを、次のように
                        書き換えて入力します。
                          https://contoso.sharepoint.com/sites/Cards
                          ↓
                          contoso.sharepoint.com:/sites/Cards
                        （「https://」を外し、「.com」の後に「:」を入れます）
  SP_DRIVE_NAME         ドキュメントライブラリの名前です。通常は
                        「ドキュメント」です。手順6の 0 または 2 で、「原因の
                        詳細」の行に「Available drives:」と表示された場合は、
                        その後に表示された名前を、そのまま入力します。
  SP_BASE_FOLDER        手順1-3で作成した名刺用のフォルダー（例: 名刺データ）
                        ほかのフォルダーの中にある場合は、SharePointの画面上部
                        に表示される場所（例: ドキュメント > 営業部 > 名刺データ）
                        のうち、ライブラリ名より後ろを「/」でつないで入力します
                        （例: 営業部/名刺データ）。
  SP_INPUT_FOLDER       未処理フォルダーの名前（例: 未処理）
  SP_PROCESSED_FOLDER   処理済フォルダーの名前（例: 処理済）
  SP_REVIEW_FOLDER      要確認フォルダーの名前（例: 要確認）
                        （この3つは、手順1-3で作成したフォルダーの名前だけを
                        入力します）
  GEMINI_API_KEY        手順4-3で保存したAPIキー
  TEAMS_WEBHOOK_URL     手順3-4で保存したWebhook URL
  UI_LANGUAGE           表示言語（日本語は ja、英語は en）

  任意: TEAMS_MENTION_NAMES と TEAMS_MENTION_EMAILS
        お知らせでメンションする人の名前とメールアドレスです。
        複数の場合はカンマ（,）で区切り、同じ数・同じ順番で入力します。
  任意: TEAMS_NOTIFY_TITLE
        お知らせのタイトルを変えたい場合だけ、行の先頭の # を消して入力します。
  任意: LOG_RETENTION_DAYS
        ログを残す日数です（初期値 90）。これより古いログファイルは、本アプリの
        起動時に削除されます。必要な場合は変更できます。
  次の項目は、最初から入力されている値のまま変更しないでください。
        RECORD_DESTINATION=list   記録先（名刺リスト）
        SP_LIST_NAME=名刺マスター  名刺リストの名前（手順6の 0 で作成します）
        MAX_IMAGE_BYTES=20000000  1枚の画像の上限（20MB）
  RECORD_DESTINATION=excel は、Excelファイルに直接記録する旧方式（Microsoftの
  サポート対象外）を以前から使っている環境のためだけに残しているもので、
  通常は使用しません。
  それ以外の項目も変更しないでください。
  DRY_RUN=true（テストモード: 名刺リスト・画像・Teamsを変更しません）と
  MAX_CARDS_PER_RUN=1（1回に処理する名刺の上限。表裏で1枚）は、
  手順7までこのままにします。
＜注意＞ メモ帳などに保存したシークレットの値、APIキー、Webhook URL は、
        .env に入力した後、削除することを推奨します。
＜確認ポイント＞ .env を上書き保存したこと（内容は手順6で確認します）。

手順6 動作を確認する（「動作確認」フォルダー）
  本アプリを使うパソコンの担当者
======================================================================
「動作確認」フォルダーの 0〜5 の .cmd ファイルを、番号の順にダブルクリックします。
失敗した場合は、画面の「原因の詳細（認証情報は含みません）：」の行を確認し、
「利用ガイド.txt」の「4. 困ったとき」をご覧ください。
 0. 0_名刺リストの作成.cmd
    SharePointのサイトに名刺リスト（名刺マスター）を、記録に使う21の列とともに
    作成します。すでにある場合は、足りない列だけを追加します。
    → 次のどれかが表示されること
      「名刺リスト「名刺マスター」を作成しました。」
      「名刺リスト「名刺マスター」に足りない列を追加しました。」
      「名刺リスト「名刺マスター」は作成済みで、必要な列がそろっています。」
    「名刺リストを作成できませんでした。」と表示された場合は、手順2の13の
    ロールが「manage」になっているかを確認します。
    作成された名刺リストは、SharePointのサイトを開き、「サイト コンテンツ」→
    「名刺マスター」で開けます。名刺リストの列は、削除しないでください。
    リストを開いて列が「タイトル」しか表示されていない場合は、列見出しの右端の
    「＋ 列の追加」→「列の表示/非表示」で、すべての列にチェックを入れて
    「適用」を押します（「Excelにエクスポート」では、表示中の列だけが出力されます）。
 1. 1_設定の確認.cmd
    →「設定ファイルの基本チェックに合格しました。」と表示されること
 2. 2_Microsoft365の接続確認.cmd
    SharePointの3つのフォルダー（未処理・処理済・要確認）と、名刺リストの列を
    確認します。
    →「Microsoft 365へのアクセスと記録先（名刺リスト／Excel）の列の確認に
      合格しました。」と表示されること
 3. 3_Geminiの接続確認.cmd（Y を入力して Enter キーを押します）
    →「Geminiから構造化応答を受け取り、解析できました。」と表示されること
 4. 4_Teams通知の確認.cmd（Y を入力して Enter キーを押します）
    → Teamsのチャネルにテストのお知らせが届くこと
 5. 5_名刺読み取りテスト.cmd
    先にSharePointの未処理フォルダーへ名刺画像を1枚入れてから実行し、
    Y を入力して Enter キーを押します。
    読み取り結果（名刺の各項目）は画面にだけ表示され、ログ（meishi-ai.log）
    には書き込まれません。画面を閉じる前に確認します。件数やエラーは、
    「3_ログを開く.cmd」で開くログでも確認できます。
    このテストでは、名刺リストと画像は変更されません。
＜確認ポイント＞ 次の2点を確認します。
                ・0〜5 がすべて成功すること
                ・SharePointのサイトの「サイト コンテンツ」に、0 で作成された
                  名刺リスト「名刺マスター」が表示されること（名刺リストに21の
                  列がそろっていることは、2 で確認されます）

手順7 はじめての本番処理
  本アプリを使うパソコンの担当者
======================================================================
1. .env の DRY_RUN を false に変えて保存します（MAX_CARDS_PER_RUN は 1 のまま）。
2. 未処理フォルダーに名刺画像を1枚入れて、MeishiAI フォルダー（「動作確認」
   フォルダーの一つ上）の「2_名刺処理を実行.cmd」をダブルクリックします。
3. 「本番モード」と表示されていることを確認し、Y を入力して Enter キーを押します。
＜確認ポイント＞ 次の3点を確認します。
                ・名刺リストに1件追加されている
                ・画像が「処理済」フォルダーの中の年月フォルダーに移動している
                ・Teamsに処理結果のお知らせが届いている
3点を確認できたら、MAX_CARDS_PER_RUN を運用に合わせて変更します
（0 にすると上限なし）。
定期的な自動実行は、「利用ガイド.txt」の「3. 定期的に自動で実行する」で設定します。

設定完了のチェックリスト
======================================================================
□ 手順6の確認がすべて成功した
□ はじめての本番処理で、名刺リストに正しい内容が1件追加された
□ 画像が処理済フォルダーへ移動し、Teamsに結果が届いた

参考資料（公式ドキュメント）
======================================================================
手順1 SharePointのフォルダー作成（Microsoft）:
  https://support.microsoft.com/ja-jp/sharepoint/documents-and-library/create-a-folder-in-a-document-library
手順2 アプリの登録（Microsoft）:
  https://learn.microsoft.com/ja-jp/entra/identity-platform/quickstart-register-app
手順2 シークレットの作成（Microsoft）:
  https://learn.microsoft.com/ja-jp/entra/identity-platform/how-to-add-credentials
手順2 アクセス許可と管理者の同意（Microsoft）:
  https://learn.microsoft.com/ja-jp/entra/identity-platform/quickstart-configure-app-access-web-apis
手順2 Sites.Selected（Microsoft）:
  https://learn.microsoft.com/ja-jp/graph/permissions-selected-overview
手順2 Graph Explorer（Microsoft）:
  https://learn.microsoft.com/ja-jp/graph/graph-explorer/graph-explorer-features
手順3 Teamsのワークフロー（Microsoft）:
  https://support.microsoft.com/ja-jp/teams/apps-service/get-started-with-the-workflows-app-in-microsoft-teams
  https://support.microsoft.com/ja-jp/workflows/send-messages-in-teams-using-incoming-webhooks
手順4 Gemini APIのキーと課金（Google）:
  https://ai.google.dev/gemini-api/docs/api-key?hl=ja
  https://ai.google.dev/gemini-api/docs/billing?hl=ja
手順6 名刺リストの作成と記録（Microsoft Graph の Lists API。Microsoft）:
  本アプリは、名刺リストの作成と名刺の記録に、次の操作を使います。
  どちらも、アプリ専用（app-only）のアクセス許可で利用できる方式です。
  https://learn.microsoft.com/ja-jp/graph/api/list-create
  https://learn.microsoft.com/ja-jp/graph/api/listitem-create
