1. このアプリは何?
279の全アプリをつなぐ、データの司令塔。
このマニュアルは管理者・エンジニア向けです。現場職員が直接使うアプリではありません。
1.1 一言で言うと
FirstCare（介護ソフト）のデータを自動で取り込み、CareNote・新規相談アプリ・FAX管理など279の全アプリに共通のデータ基盤を提供するシステムです。
1.2 何ができるか
- 利用者データの自動同期 — 介護ソフト（FirstCare）から利用者・被保険者証・記録を毎2時間自動取込
- 職員データの統合 — 札幌・いわき2拠点の職員を1人1つのIDで統合管理
- 事業所データ管理 — 取引先事業所マスタの自動更新
- 全アプリ共通の権限管理 — どのアプリに誰がアクセスできるかをここで一元管理
- Google Workspace同期 — 社員のメールアカウントと職員データを毎朝自動照合
- freee人事労務連携 — 勤怠・給与データをAPIで取得・配布
- 死活監視・Google Chat通知 — 同期失敗時にアラートを自動送信
1.3 誰のためのアプリか
| 区分 | 立場 | できること |
|---|---|---|
| システム管理者（次田さん等） | 統合DBコンソール管理者 | 全設定・ログ閲覧・手動同期 |
| エンジニア | 開発者 | API経由でデータ取得・連携アプリ開発 |
| 連携アプリ | CareNote / 新規相談 / FAX管理等 | API経由でデータを参照・利用 |
現場の介護職員が直接このアプリを使う場面はありません。
2. 使うとどう変わるか
Before（統合DBなし）
- 各アプリがバラバラに利用者データを持つ → 同期ズレ・重複・矛盾が発生
- 職員の権限を各アプリで個別に設定 → 設定漏れ・管理工数増大
- 介護ソフトのデータをアプリで使うには手動エクスポート・インポートが必要 → 担当者が毎回作業
After（統合DB導入後）
- 利用者データはFirstCare → 統合DB → 全アプリに自動同期（2時間ごと）
- 職員のロール設定は統合DBの1か所で完結 → Firebase Custom Claims経由で全アプリに即時反映
- 介護ソフトのデータ更新が自動でアプリに反映 → 担当者の手作業ゼロ
3. 使い始める前に
管理コンソールURL
- 本番: https://tougou-db-f9f9e.web.app
- API（OpenAPI仕様）: openapi.yaml
必要なもの
@279279.netのGoogleアカウント（ドメイン制限あり）- 管理者権限（
console_adminsコレクションへの登録が必要）
APIキー
Secret Manager MASTER_API_KEY（project: tougou-db-f9f9e）。コードへのハードコード禁止。
# APIキー取得
~/Projects/google-cloud-sdk/bin/gcloud secrets versions access latest \
--secret=MASTER_API_KEY --project=tougou-db-f9f9e4. 日常の使い方
4.1 管理コンソールの使い方
コンソールは https://tougou-db-f9f9e.web.app にアクセスしてGoogleログイン。左サイドバーから各機能を選択します。
| メニュー | 内容 |
|---|---|
| インポートログ | FC自動取込の結果・エラーを確認 |
| 利用者一覧 | 統合後の利用者データ確認 |
| 職員管理 | unified_shokuin の確認・手動上書き |
| 事業所管理 | jigyosho の確認 |
| 権限管理 | app_roles の設定 |
| Workspace同期 | Google Workspace同期状況確認 |
| freee連携 | freee従業員・勤怠・給与データ確認 |
| 管理者設定 | console_admins の管理 |
| 通知設定 | Google Chat Webhook・通知モードの設定 |
4.2 Google Chat通知を設定したい
- 管理コンソール → 管理者設定 → Google Chat通知設定
- 通知モードを選択:
- 投稿しない — 通知なし
- エラー時のみ通知 — 取込失敗・アラートのみ
- 1日1回（朝に前日分）〔推奨〕 — 毎朝8時に前日の札幌・いわき取込サマリーをまとめて投稿
- 常に通知 — 取込成功・エラーすべてをリアルタイムで投稿
- Webhook URLを入力（空欄のまま保存すると既存URLは保持されます）
- 「保存」をクリック
推奨は「1日1回」モードです。 取込のたびに通知が来るとノイズになるため、朝1回のサマリーで状況を把握するのが最も効率的です。
4.3 手動で同期を実行したい
管理コンソール → インポートログ → 「手動同期」ボタン。または直接APIを叩く:
curl -X POST https://asia-northeast1-tougou-db-f9f9e.cloudfunctions.net/manualSync \
-H "x-api-key: <MASTER_API_KEY>"4.4 FCエージェントの状態を確認したい
- 管理コンソール → エージェント管理 でサーバー一覧と最終ハートビート時刻を確認
- 2時間以上更新なし → 自動でGoogle Chatに通知が飛ぶ
4.5 連携アプリからAPIを使いたい（エンジニア向け）
# 利用者一覧
curl "https://asia-northeast1-tougou-db-f9f9e.cloudfunctions.net/getRiyousha" \
-H "x-api-key: <MASTER_API_KEY>"
# 事業所をkouhyouCdで検索
curl "https://getjigyoshobykouhyoucd-sqmzqyty7q-an.a.run.app?code=0160591525" \
-H "x-api-key: <MASTER_API_KEY>"詳細はOpenAPI仕様を参照してください。
4.6 デプロイしたい
# Cloud Functions
cd ~/Projects/279/279-master-db-cloud-sync/functions
npm run deploy
# Firebase Hosting（管理コンソールUI）
PATH="$HOME/.nvm/versions/node/v22.22.2/bin:$PATH" \
npx firebase-tools deploy --only hosting --project=tougou-db-f9f9e5. よくある質問
Q: データがアプリに反映されるまでどのくらいかかる？
最大2時間（Cloud Schedulerの間隔）。緊急の場合は手動同期で即時反映できます。
Q: インポートログに「skipped_no_change」と出ている
ZIPファイルの中身が前回と変わっていないため処理をスキップしました。正常動作です。
Q: 職員が退職したが統合DBのデータはどうなる？
Google Workspace同期が毎朝実行され、アカウント停止を自動検知します。unified_shokuin の active フラグが更新されます。
Q: いわきのデータが2024-04-01以前のものが入っていない
仕様です。いわきDBは2024年に札幌DBのコピーで開始されたため、2024-04-01以前のデータは意図的に除外しています。
Q: APIキーが変わったらどうする？
Secret Manager MASTER_API_KEY を更新 → Cloud Functionsは次回デプロイで自動反映（環境変数ではなくSecret Manager参照のため即時反映も可能）。
6. 困ったときは
既知の注意事項
signInWithRedirectは Firebase Hosting でCookieループが発生するため使用禁止。signInWithPopupを使用git add .は禁止（.env・APIキー誤コミット防止）- Cloud Functions v1 に新機能追加禁止（v2推奨）
障害対応
- Google Chat通知でアラートを確認（エラー時のみ通知モード推奨）
- 管理コンソール → インポートログでエラー詳細を確認
- GCP Console → Cloud Functions → ログで詳細調査
連絡先
担当: 次田 芳尚（y.tsukuda@279279.net）
7. アプリ間連携
| 連携先アプリ | 渡しているデータ | 連携方式 |
|---|---|---|
| CareNote | 利用者・経過記録 | API（MASTER_API_KEY） |
| FAX管理 | ログ書込み（送信記録） | createLog API（MASTER_API_KEY） |
| 新規相談アプリ | 利用者・事業所 | API（Firebase Auth） |
| 279-jigyosho-app | 事業所（kouhyouCdで検索） | getJigyoshoByKouhyouCd API |
| Compass | 職員・freee給与勤怠 | API |
8. 変更履歴
| 日付 | 変更 |
|---|---|
| 2026-04-21 | createLog API 追加（FAXアプリ等の外部アプリが carenote_logs にログ書込み可能に） |
| 2026-04-21 | ZIP取込時の名寄せロジック（primary_kyoten）完全実装・自動適用開始 |
| 2026-04-19 | Google Chat通知に「1日1回（朝に前日分）」モード追加、Drive取込開始通知廃止 |
| 2026-04-18 | MANUAL.md 初版作成 |
| 2026-04-18 | kouhyouCd フィールド追加・getJigyoshoByKouhyouCd API追加 |
| 2026-04-13 | freee人事労務連携実装 |
| 2026-04-13 | ADR-FC-001 Pub/Sub Pull型移行完了 |