エンジニアノート

概要・背景

279の全アプリに共通するデータ基盤。FirstCare（介護ソフト）→ Cloud Storage → Cloud Functions → Firestore の流れでデータを自動同期する。

解決した問題

各アプリがバラバラに利用者データを持ち、同期ズレ・重複・矛盾が発生していた
職員権限の個別設定による設定漏れ・管理工数増大
介護ソフトのデータをアプリで使うための手動エクスポート/インポート作業

技術スタック

レイヤー	技術	備考
フロントエンド	Vanilla HTML + Firebase Auth	Next.js 移行検討中
バックエンド	Cloud Functions v2 (Node.js 22)	v1 は廃止予定・新機能は v2 のみ
DB	Firestore	project: tougou-db-f9f9e
ストレージ	Cloud Storage	FCエージェントが ZIP を PUT
メッセージング	Pub/Sub (Pull型)	ADR-FC-001 参照
スケジューラ	Cloud Scheduler	毎2時間インポート・毎朝 Workspace 同期
ホスティング	Firebase Hosting	管理コンソール UI
シークレット	Secret Manager	MASTER_API_KEY 等
外部連携	freee API / Google Workspace API	人事労務・メールアカウント同期

アーキテクチャ

FCエージェント (Windows Server)
  └─ ZIP を Cloud Storage に PUT (2時間毎)
       └─ Storage trigger → dispatchImport
            ├─ Pub/Sub topic: fc-import-jobs
            └─ importWorker (subscriber)
                 ├─ ZIP 解析 → riyousha / shokuin / jigyosho / records を Firestore に書込
                 └─ import_logs に結果記録

Cloud Scheduler
  ├─ 毎2時間: triggerScheduledImport
  ├─ 毎朝8時: sendDailySummary (Google Chat)
  └─ 毎朝9時: syncWorkspaceUsers

Cloud Functions (API群)
  ├─ getRiyousha / getShokuin / getJigyosho  ← 各アプリが呼ぶ
  ├─ createLog / getLogs                      ← CareNote / FAX管理
  └─ checkAgentHeartbeat                      ← FCエージェント死活監視

データモデル（主要コレクション）

コレクション	内容	主キー
`riyousha`	統合利用者マスタ	統合利用者ID（UUID）
`unified_shokuin`	統合職員マスタ	メールアドレス
`jigyosho`	事業所マスタ	kouhyouCd または内部ID
`records`	支援経過記録	自動ID
`import_logs`	取込ログ	自動ID
`app_roles`	アプリ権限（Custom Claims ソース）	メールアドレス
`console_admins`	管理コンソール管理者	メールアドレス
`agent_heartbeats`	FCエージェント死活	エージェントID
`notification_settings`	Google Chat 通知設定	固定 doc ID

完全な ER 図・フィールド定義は ENGINEERING_NOTES.md §7 を参照。

API一覧

ベースURL: https://asia-northeast1-tougou-db-f9f9e.cloudfunctions.net

エンドポイント	メソッド	認証	説明
`getRiyousha`	GET	API key / IDトークン	利用者一覧・詳細
`getShokuin`	GET	API key / IDトークン	職員一覧（activeOnly / role パラメータあり）
`getJigyosho`	GET	API key / IDトークン	事業所一覧（activeOnly / serviceType パラメータあり）
`createLog`	POST	API key	carenote_logs にログ書込み
`getLogs`	GET	API key / IDトークン	ログ取得
`manualSync`	POST	API key	手動インポートトリガー
`checkAgentHeartbeat`	POST	API key	FCエージェント死活確認

OpenAPI 仕様: openapi.yaml

認証

Firebase Auth（Google OAuth） — ドメイン制限 @279279.net のみ
管理者判定: console_admins コレクション参照
アプリ権限: app_roles → Firebase Custom Claims → 各アプリで参照

必須: signInWithRedirect は Firebase Hosting（.web.app）でCookieループが発生するため禁止。必ず signInWithPopup を使用すること。

デプロイ

# Cloud Functions
cd functions && npm run deploy

# Firebase Hosting
PATH="$HOME/.nvm/versions/node/v22.22.2/bin:$PATH" \
  npx firebase-tools deploy --only hosting --project=tougou-db-f9f9e

--only functions 単独デプロイは禁止。他関数が削除候補になる。
必ず --only "functions:f1,functions:f2" のように関数名を列挙すること。

Cloud Run リビジョン管理

CI/CD（deploy.yml）にリビジョン自動削除ステップを組み込み済み（commit ce04f1f）。週次 cleanup も設定済み。リビジョン数が 100 件超えたら手動確認を推奨。

ハマりポイント・注意事項

FCエージェント死活アラートとデータ流通は別経路

ハートビート: reportAgentResult 経由（quota 超過時は 503 で書込失敗）
インポート: Storage trigger → dispatchImport 経由（quota の影響を受けにくい）
アラートだけで判断せず import_logs を必ず確認すること

getShokuin のデフォルトは activeOnly=false

後方互換のため退職者も返す。activeOnly=true を明示すること。

getJigyosho の activeOnly

有効フラグ=="1" AND 廃止==false の両方をチェック。事業所だけ2フラグある。

getRiyousha の careLevel は全角数字

要介護４（全角）で指定する。要介護4（半角）は不一致になる。

CDN スクリプトはキャッシュ無効化必須

?v=YYYYMMDD クエリを付けること。

NSSMサービス名

FCエージェントのサービス名は FC_Agent_PubSub。復旧コマンド: nssm restart FC_Agent_PubSub

ADR・設計議論

ADR-FC-001: Pub/Sub Pull型移行（2026-04-13 完了）

FCエージェントから Storage への直接 Push を廃止し、Pub/Sub Pull 型に移行。理由: エージェント側のネットワーク障害時にキューが詰まらないよう。

ADR-SHOKUIN-001: employment_status SSOT化（2026-04-28）

在籍判定は FCのみで行う。isVisible = active OR has_assignments の単一ルール。freee・Workspace の値で上書きしない。

riyousha スキーマ確定方針（2026-04-27）

担当ケアマネID正規化・要介護度 denormalize・いわきカットオフ撤廃・元DB_ID参照禁止

詳細: ENGINEERING_NOTES.md #ADR

変更履歴

日付	内容	コミット
2026-05-07	Cloud Run リビジョン自動削除 CI組込み・HelpNav 追加	ce04f1f
2026-05-06	getJigyosho/getRiyousha 有効フラグ統一・serviceType/careLevel パラメータ追加	ffe8a68
2026-04-28	ADR-SHOKUIN-001 employment_status SSOT化	—
2026-04-27	riyousha スキーマ確定・records FK追加	—
2026-04-21	createLog API 追加	—
2026-04-13	ADR-FC-001 Pub/Sub Pull型移行完了・freee連携実装	—