AI名刺整理君（Microsoft 365版）
利用ガイド

内容:
  1. 名刺のアップロード
  2. 処理と結果の見方
  3. 定期的に自動で実行する
  4. 困ったとき
  5. 保守
  6. バージョンアップ
初期設定がまだの場合は、先に「初期設定ガイド.txt」の手順を行ってください。

1. 名刺のアップロード（名刺を登録する方）
======================================================================
・1枚の画像に名刺を1枚だけ写します。文字と名刺の四隅がはっきり写るように
  撮影、またはスキャンします。
・使える画像の形式: JPG、JPEG、PNG、HEIC、HEIF
・表と裏がある名刺は、同じ名前の後ろに _F（表）と _B（裏）を付けます。
    例: tanaka_F.jpg と tanaka_B.jpg
  片面だけの名刺には付けません。
  表と裏は、処理が始まる前に両方ともアップロードしてください。片方だけの
  状態で処理されると、片面の名刺として扱われます。
・SharePointの「未処理」フォルダーに、直接アップロードします。
  「未処理」フォルダーの中に、別のフォルダーは作成しないでください。
・処理が終わるまで、アップロードした画像の名前を変えたり、削除したり
  しないでください。
・処理の結果は、Teamsのお知らせで確認できます。

2. 処理と結果の見方
======================================================================
手動で処理する:
  「2_名刺処理を実行.cmd」をダブルクリックします。表示されたモードと処理の
  上限を確認し、Y を入力して Enter キーを押します。
  テストモード（.env の DRY_RUN=true）では、名刺リスト・画像・Teamsは変更
  されません。

結果の見方（Teamsのお知らせと名刺リスト）:
  成功      名刺リストに1件追加され、画像は「処理済」フォルダーの中の年月
            フォルダーに移動します。
  要確認    名刺リストには追加されません。画像は「要確認」フォルダーの中の年月
            フォルダーに移動します。お知らせに書かれた理由を確認し、撮り直しや
            分割をしてから「未処理」フォルダーに戻すと、次回もう一度処理されます。
  保留      処理の上限、またはGeminiの利用上限に達したため、画像は「未処理」
            フォルダーに残っています。次回の実行で、もう一度処理の対象になります。
  移動待ち  処理は記録済みで、画像の移動だけが残っています（成功の場合は
            名刺リストにも記録済みです）。次回の実行で移動されます。
            名刺リストに手で項目を追加したり、画像を手で動かしたりしないで
            ください。
  重複      以前に処理したものとまったく同じファイルは、もう一度登録されず、
            「処理済」フォルダーに移動されます。
            同じ名刺を撮り直した画像は、別のファイルとして扱われ、もう一度
            登録されます。
移動先の年月フォルダーに同じ名前のファイルがすでにある場合は、名前の後ろに
番号を付けて移動します（例: tanaka_F.jpg → tanaka_F_002.jpg）。

名刺リストに登録される内容は、AIによる読み取りの結果です。必要に応じて、名刺の
画像と見比べて確認してください。
自動で登録されるには、名刺に記載された人の氏名（日本語または英字）に加えて、
会社名・住所・メールアドレス・電話番号・FAX・URLのうち1つ以上が読み取れる
必要があります。
名刺リストは、SharePointのサイトの「サイト コンテンツ」から開けます。Excelで
使う場合は、リストの画面の「Excelにエクスポート」（画面によっては
「エクスポート」の中）を使います。

3. 定期的に自動で実行する（タスク スケジューラ）
======================================================================
1. Windowsのタスクバーの検索欄に「タスク スケジューラ」と入力して開き、
   右側の「タスクの作成」を選択します。
2. 「全般」タブ: 「名前」（例: 名刺AI 定期実行）を入力し、実行する条件を
   選択します。
   ・パソコンにサインインしているときだけ動かす場合:
     「ユーザーがログオンしているときのみ実行する」
   ・サインインしていないときも動かす場合:
     「ユーザーがログオンしているかどうかにかかわらず実行する」
3. 「トリガー」タブ: 「新規」を押し、開始日時と繰り返し（毎日・毎週・毎月）を
   設定します（例: 毎週月曜日の9:00）。
4. 「操作」タブ: 「新規」を押し、「操作」で「プログラムの開始」を選択して、
   次のように入力します。
     プログラム/スクリプト: C:\MeishiAI\MeishiAI.exe
     引数の追加:            --env-file "C:\MeishiAI\.env"
     開始:                  C:\MeishiAI
   変更するのは C:\MeishiAI の部分だけです。実際に置いたフォルダーに合わせます。
   それ以外（MeishiAI.exe、--env-file、.env、.env のパスを囲む "）は、
   そのまま入力します。
     例: D:\Apps\MeishiAI に置いた場合
       プログラム/スクリプト: D:\Apps\MeishiAI\MeishiAI.exe
       引数の追加:            --env-file "D:\Apps\MeishiAI\.env"
       開始:                  D:\Apps\MeishiAI
5. 「設定」タブ: 「タスクが既に実行中の場合に適用される規則」で
   「新しいインスタンスを開始しない」を選択し、「OK」を押して保存します。
6. 保存したタスクを右クリックして「実行する」を選択し、一度試します。
＜確認ポイント＞ Teamsに処理結果のお知らせが届くこと。
実行する時刻には、パソコンの電源が入り、インターネットに接続されている
必要があります。

4. 困ったとき
======================================================================
まず、画面に表示されたエラーの内容を確認します。「動作確認」フォルダーの
ファイルで失敗した場合は、「原因の詳細（認証情報は含みません）：」の行に、
HTTPの番号やエラーの種類などが表示されます。名刺の処理（名刺読み取り
テスト・名刺処理・定期実行）でのトラブルは、「3_ログを開く.cmd」でログ
（meishi-ai.log）も確認します。

起動するときにWindowsの警告画面が表示される
  →「はじめにお読みください.txt」の「起動時に警告が表示された場合」を
    ご覧ください。
「1_設定の確認.cmd」で「設定エラー」と表示される
  → 表示された説明に沿って、.env の項目を確認します。説明の後ろに「（原文: …）」が
    表示された場合は、提供元へお問い合わせいただくときに、その部分もお伝えください。
「2_Microsoft365の接続確認.cmd」が失敗する
  → 「原因の詳細」の行を見ながら、次の順に確認します。
    ・SP_DRIVE_NAME: 「Available drives:」と表示された場合は、その後に表示
      された名前を入力します（通常は「ドキュメント」）
    ・MS_TENANT_ID、MS_CLIENT_ID、シークレットの値と有効期限（「AADSTS」で
      始まる番号が表示された場合は、特にこの3つを確認します）
    ・初期設定ガイド 手順2の(ウ)同意と、(エ)サイトとの結び付けが済んでいるか
    ・SP_SITE_URL の書き方、フォルダーの名前（初期設定ガイド 手順5）
      （「not found:」の後に、見つからないフォルダーが表示されます）
    ・名刺リスト: 「list not found」または「missing columns」と表示された
      場合は、「動作確認」フォルダーの 0 を実行します
「0_名刺リストの作成.cmd」で「名刺リストを作成できませんでした。」と表示される
  → 初期設定ガイド 手順2の(エ)のロールが「manage」になっているかを確認します
    （1.0 からバージョンアップした場合は、「更新内容.txt」の「1回だけ必要な
    作業」をご覧ください）。それ以外は、上の
    「「2_Microsoft365の接続確認.cmd」が失敗する」と同じ順に確認します。
ファイルの移動はできるが、名刺リストへの記録だけが失敗する
  →「動作確認」フォルダーの 2 で名刺リストの列を確認し、足りない場合は 0 を
    実行します。それでも失敗する場合は、権限を広げて試さずに、提供元へ
    ご連絡ください。
「起動できませんでした（…）。インターネット接続と…」と表示される
  → 名刺の処理を始める前に止まりました（Microsoft 365に接続できない場合など）。
    （ ）内に「別の処理が実行中」とある場合は、前の処理が終わってから、もう一度
    実行します（長く続く場合は、下の「「another run appears active」と表示されて
    処理が始まらない」をご覧ください）。
    それ以外の場合は、次の順に確認します。
    ・パソコンがインターネットに接続されているか（社内でプロキシを使っている
      場合は、その設定も確認します）
    ・「動作確認」フォルダーの 2 を実行します。失敗する場合は、上の
      「「2_Microsoft365の接続確認.cmd」が失敗する」に沿って確認します
    パソコンがインターネットに接続されていないときは、Teamsにお知らせは届き
    ません。定期実行でお知らせが届かなかった場合は、「3_ログを開く.cmd」で
    ログを確認します。
Teamsにお知らせが届かない
  → テストモードではお知らせは送られません。「4_Teams通知の確認.cmd」で
    確認し、届かない場合は、ワークフローがオンになっているか、実行履歴、
    TEAMS_WEBHOOK_URL を確認します。初期設定ガイドの手順3と違う
    テンプレートで作成した場合は、作成し直します。
Teamsのお知らせに「中断理由」が表示された
  → 表示された理由ごとに、次のように対応します。
    Gemini日次上限（次回自動再開）
      Geminiの1日の利用上限に達しました。対応は不要です。上限がリセット
      された後の実行で、続きから処理されます。
    Gemini一時障害（再実行してください）
      Google側の一時的な問題、または1分あたりの利用上限です。時間をおいて
      から、もう一度実行します。
    Gemini設定エラー（要確認）
      .env の GEMINI_API_KEY と GEMINI_MODEL、有料プランの設定・残高を確認し、
      「動作確認」フォルダーの 3 で確認します。
    別の処理が実行中（終了を待って再実行）
      前の処理（定期実行など）がまだ動いていたため、始めませんでした。名刺は
      処理されていません。前の処理が終わってから、もう一度実行します。
      長く続く場合は、下の「「another run appears active」と表示されて処理が
      始まらない」をご覧ください。
    起動エラー（要確認）
      処理を始める前の確認で止まりました。名刺は処理されていません。
      ログに「required SharePoint item not found」とある場合は、フォルダーが
      見つかりません。.env のフォルダー名と、SharePointのフォルダーの構成
      （初期設定ガイド 手順1）を確認します。
      ログに「SharePoint list not found」または「missing columns」とある場合は、
      名刺リストがないか、列が足りません。「動作確認」フォルダーの 0 を
      実行します。
      どちらの場合も、最後に「動作確認」フォルダーの 2 で確認します。
    SharePoint・Excel接続エラー（要確認）
      名刺リストへの記録、またはSharePointでのファイルの移動に失敗しました。
      「動作確認」フォルダーの 2 で確認します。失敗する場合は、上の
      「「2_Microsoft365の接続確認.cmd」が失敗する」をご覧ください。
    予期しないエラー（要確認）
      もう一度実行しても続く場合は、日時を添えて提供元へご連絡ください。
Geminiのエラー 429（利用の上限）
  → 1分あたりの上限なら、少し待ってからもう一度実行します。1日の上限なら、
    上限がリセットされるまで待つか、有料プランを設定します。
    リセットは米国太平洋時間の0時で、日本時間では16時（米国の夏時間の期間）
    または17時（それ以外の期間）です。
Geminiのエラー 503（一時的に利用できない）・504（時間内に処理が終わらない）
  → Google側の一時的な問題です。時間をおいてから、もう一度実行します。
    名刺は「未処理」フォルダーに残り、次回の実行で、もう一度処理の対象に
    なります。何度実行しても続く場合は、提供元へご連絡ください。
画像が「未処理」フォルダーに残る
  → テストモード（DRY_RUN=true）では、画像は移動しません。本番モードの場合は、
    Teamsのお知らせまたはログで理由を確認します（処理の上限・利用上限による
    保留、Geminiのエラーによる中断など）。次回の実行で、もう一度処理の対象に
    なります。
名刺が「要確認」になった
  → お知らせの「要確認ファイル」に、ファイル名と理由が表示されます。
    理由ごとに対応してから、画像を「未処理」フォルダーに戻すと、次回もう一度
    処理されます。
    カード未検出
      名刺が写っていません。画像を確認し、撮り直します。
    複数カード
      1枚の画像に複数の名刺があります。1枚ずつ撮り直します。
    氏名なし
      氏名を読み取れませんでした。ぼやけている場合は撮り直します。
    情報不足
      氏名以外（会社名・住所・連絡先など）を読み取れませんでした。
      ぼやけている場合は撮り直します。
    メール形式・電話番号形式・FAX番号形式・URL形式・郵便番号形式
      読み取った値の形式が正しくありません。名刺の原本を確認し、
      ぼやけている場合は撮り直します。
    電話/FAX桁数確認
      電話番号またはFAX番号の桁数が通常と異なります（0で始まる番号が
      10桁・11桁以外の場合など）。名刺の原本を確認します。
    非対応ファイル
      使えない形式のファイルです。JPG、JPEG、PNG、HEIC、HEIFのいずれかで
      保存し直します。
    画像読取不可
      画像を開けませんでした。名前が .jpg などでも、中身がJPG・PNG・HEIC
      以外の形式のファイルは、この理由になります。JPG、PNG、HEICのいずれかで
      保存し直すか、撮り直します。
    画像サイズ超過
      画像のファイルサイズが20MBを超えているか、画素数が6,000万を超えて
      います。小さく保存し直すか、撮り直します。
    出力切れ・AI内容ブロック
      AIの読み取りが完了しませんでした（Geminiがその画像に何も返さなかった
      場合も、AI内容ブロックになります）。そのまま「未処理」フォルダーに
      戻します。何度も続く場合は、撮り直すか、提供元へご連絡ください。
    AI読取の連続失敗
      同じ名刺で処理が2回続けて途中で止まったため、3回目の実行で自動的に
      「要確認」に移されました。画像を確認し、撮り直します。
    その他要確認
      ログで理由を確認します。分からない場合は、提供元へご連絡ください。
「another run appears active」と表示されて処理が始まらない
  → 前の処理が終わるまで待ちます。前の処理が異常終了して run.lock が残った
    場合でも、その処理がもう動いていなければ、次の実行で自動的に解除されます。
    それでも長く続く場合は、運用の担当者に連絡します。
    担当者の対応: 定期実行のタスクを一時的に無効にし、タスクマネージャーの
    「詳細」タブで、どのユーザーでも MeishiAI.exe が動いていないことを確認
    してから、フォルダー内の run.lock を削除します。処理が正常に終わったら、
    タスクを有効に戻します。
「3_ログを開く.cmd」で、ログフォルダーがないと表示される
  → まだ一度も名刺を処理していない場合は、正常です。
シークレットの期限が切れた（401エラー）
  → 初期設定ガイド 手順2の(イ)で新しいシークレットを作成し、.env の
    MS_CLIENT_SECRET を書き換えます。

解決しない場合は、提供元へご連絡ください（「はじめにお読みください.txt」）。
.env・名刺画像・ログは送らずに、画面に表示されたエラーの内容
（パスワードなどの情報は除く）と日時をお伝えください。

5. 保守
======================================================================
・シークレットの有効期限が切れる前に、新しいシークレットを作成して .env を
  更新します。
・state.db（処理の記録）は削除しないでください。同じファイルが二重に登録
  されるのを防ぐための記録です。
・.env、state.db、logs フォルダーには、認証情報や個人情報が含まれます。
  社外に共有しないでください。MeishiAI のフォルダーは、運用の担当者だけが
  アクセスできる場所に置いてください。
・ログは1日ごとに新しいファイルに切り替わります。.env の LOG_RETENTION_DAYS
  で指定した日数（初期値は90日）より古いログファイルは、本アプリの起動時に
  自動で削除されます（週1回の実行では、約13回分のログが残ります）。
・テストモードと「5_名刺読み取りテスト.cmd」で表示される名刺の各項目は、
  画面にだけ表示され、ログファイルには書き込まれません。また、ログには
  TeamsのWebhook URLの署名の部分は書き込まれません。
・Gemini APIの有料プランの残高が0ドルになると、すべてのAPIキーが使えなくなり、
  名刺の処理が止まります。Google AI Studio で、残高を定期的に確認してください。
・Googleがモデルの提供を終了する場合などは、.env の GEMINI_MODEL を変更します。
  提供元で動作を確認したモデル: gemini-3.5-flash、gemini-3.8-flash、
  gemini-3.5-flash-lite。変更後は「動作確認」フォルダーの 3 と 5 で確認します。
・設定を変更する場合（フォルダー名の変更など）:
  1. 名刺の処理が動いていないことを確認します。
  2. 「1_初期設定.cmd」で .env を開き、変更した項目を書き換えて上書き保存します。
  3. 「動作確認」フォルダーの 1 と 2 で確認します。フォルダーを変更した場合は、
     5 も実行します。

6. バージョンアップ
======================================================================
新しいバージョンの本アプリに入れ替えるときは、運用の担当者が次の順に作業します。
1. 定期的な自動実行を設定している場合は、止めます。タスク スケジューラで、
   「3. 定期的に自動で実行する」で作成したタスクを右クリックし、「無効」を
   選択します。
   また、タスクマネージャーの「詳細」タブで、どのユーザーでも MeishiAI.exe が
   動いていないことを確認します（動いている場合は、終わるまで待ちます）。
2. 今の MeishiAI のフォルダー（例: C:\MeishiAI）の名前を、MeishiAI_old などに
   変更します。このフォルダーが、そのままバックアップになります。
   名前を変更できない場合は、そのフォルダーの中のファイル（ログなど）を開いて
   いるアプリやエクスプローラーの画面を閉じてから、もう一度試します。
3. 新しいバージョンのZIPファイルを展開し、中の「MeishiAI」フォルダーを、元と
   同じ場所（例: C:\MeishiAI）に置きます。
   古いファイルに上書きしないのは、新しいバージョンで不要になったプログラムの
   ファイルが残らないようにするためです。
4. 古いフォルダー（MeishiAI_old）から、次の3つを新しいフォルダーにコピーします。
   ・.env（設定ファイル。.env.example で置き換えないでください）
   ・state.db（同じファイルが二重に登録されるのを防ぐための記録です）
   ・logs フォルダー
5. 新しいバージョンの「更新内容.txt」を読みます。「新しい設定」に項目が
   書かれている場合は、「1_初期設定.cmd」で .env を開き、その項目を追加して
   上書き保存します。「1回だけ必要な作業」に作業が書かれている場合は、
   その作業も行います。
6. 「動作確認」フォルダーの 1〜5 を、番号の順に実行します（初期設定ガイドの
   手順6）。「更新内容.txt」に指示がある場合は、先に 0 も実行します。
   新しい MeishiAI.exe を初めて起動するときに警告画面が表示された場合は、
   「はじめにお読みください.txt」の「起動時に警告が表示された場合」を
   ご覧ください。
7. 1 で無効にしたタスクを右クリックし、「有効」を選択します。フォルダーの場所は
   変わらないため、タスクの設定を変更する必要はありません。
8. 新しいバージョンで問題なく処理できたことを確認したら、古いフォルダー
   （MeishiAI_old）を削除します。認証情報や個人情報が含まれるため、しばらく
   残す場合も、運用の担当者だけがアクセスできる場所に置き、社外に共有しない
   でください。
＜確認ポイント＞ タスク スケジューラで、タスクの状態が「準備完了」になって
                いること。
