CPOS 連携（開発者・管理者向け）

加算マネージャは CPOS の App Platform アプリ（appId=kasan） として動作します。ログイン・ユーザー管理・データ保存はすべて CPOS 側に集約され、加算マネージャ独自の保存はありません。利用者向けの手順は CPOS_TOKEN.md、追加が必要な CPOS API は ref/KASAN_APP_API_ADDITIONS.md を参照してください。

1. アーキテクチャ

Browser (/pro)
  └─ 「CPOS でログイン」→ /api/auth/cpos/start
       【gateway（既定）】→ CPOS /api/auth/login?next=<callback?state> → Google ログイン
            → CPOS が cpos_session を .care-planning.co.jp に発行 → 加算マネージャ callback
            → 加算マネージャが cpos_session を CPOS /api/auth/me に転送して本人確認
       【connect（旧/任意）】→ CPOS /api/apps/kasan/connect?redirect_uri=<callback> → code 交換
       → いずれも 加算マネージャが kasan_session cookie(AES-GCM, HttpOnly) を発行
  └─ 以降の API は kasan_session で認証（req.user に organizationId/role/allowedFacilityIds）
        │
        ▼
加算マネージャ サーバ (Express)
  └─ s2s は CPOS の App Token（KASAN_CPOS_APP_TOKEN）で CPOS API を呼ぶ
  └─ 保存は CPOS app-data:kasan/*（organizationId で隔離）。保存前に匿名化
        │  Authorization: Bearer <App Token>
        ▼
CPOS API
  - /api/app-data/kasan/{analyses,reviews,facility-profiles,staff-rosters,drafts,entitlements,...}
  - /api/platform/facilities, /api/platform/users
  - /api/kasan/v1/analysis-source（CPOS 請求/体制データの集計）
  - /api/kasan/v1/facilities/:id/monthly-status（整備状況サマリ・加算一覧の入口で使用）
  - /api/platform/kasan/export（analysis-source が無い場合の fallback）
  - [PROPOSED] /api/apps/kasan/session/exchange, /api/platform/organizations …

2. 設定（サーバ環境変数）

変数	必須	用途
`KASAN_SESSION_SECRET`	必須	ログインセッション cookie の暗号鍵（32 文字以上）。`openssl rand -hex 32`
`KASAN_DEFAULT_CPOS_BASE_URL`	必須	CPOS のベース URL（例 `https://cpos.example.jp`）
`KASAN_CPOS_APP_TOKEN`	必須	CPOS `/app-tokens` で発行したアプリ用 App Token
`KASAN_CPOS_APP_CLIENT_ID`	任意	ログ突合用のアプリ識別（既定 `kasan`）
`KASAN_PUBLIC_BASE_URL`	任意	OAuth コールバックの公開 URL（未指定は host 推定）
`KASAN_CPOS_AUTH_FLOW`	任意	`gateway`（既定, `/api/auth/login?next=...`）か `connect`（旧 `/api/apps/kasan/connect`）。gateway は CPOS 側の `redirect_uri` 許可登録が不要
`KASAN_CPOS_SESSION_COOKIE_NAME`	任意	CPOS のセッション cookie 名（既定 `cpos_session`）。gateway で `/api/auth/me` 確認に転送
`KASAN_ADMIN_EMAILS`	任意	管理者 email（CPOS `role=admin` への override）
`KASAN_CPOS_FAKE`	任意	`1` で開発用 Fake CPOS（本番は未設定）
`KASAN_COOKIE_SECURE` / `KASAN_COOKIE_SAMESITE`	任意	本番は `true` / `Lax`
`CPOS_TIMEOUT_MS`	任意	CPOS への HTTP タイムアウト（既定 30000）

App Token の推奨 scope: app-data:kasan:read app-data:kasan:write users:read facilities:read （CPOS 実データ活用なら master-users:read / facility-staff:read / care-*:read も）。

3. App 登録手順（CPOS 側）

3.0 推奨: URL だけで登録（cpos.manifest.json）

CPOS の最新の登録方式に合わせ、加算マネージャは アプリ URL 直下に cpos.manifest.json を配信します（app/public/cpos.manifest.json／ GET /cpos.manifest.json・GET /.well-known/cpos-manifest.json）。このマニフェストが appId=kasan・名称・種別・許可スコープを宣言するため、 CPOS 管理者は手入力なしで登録できます。

加算マネージャをデプロイ（シークレット未設定でも manifest は配信されます）。
CPOS 管理コンソール「アプリ管理」(/apps) の 「🔗 URL から登録」 に加算マネージャの公開 URL（例 https://kasan.care-planning.co.jp）を入力。 CPOS が cpos.manifest.json を取得し AppRegistration を draft 作成します。 manifest 内の ${PUBLIC_URL} は登録 URL の origin で解決されます。
通常のワークフロー（draft → 申請 → 承認 → 公開）で公開。
/app-tokens でアプリ（kasan）を選ぶと manifest 由来スコープが自動で一覧表示・既定選択されるので、その App Token を発行 → KASAN_CPOS_APP_TOKEN に設定。

旧来どおり、CPOS 管理コンソールで手動登録 → /app-tokens で scope を選んで発行、でも構いません（下記 3.1）。マニフェストの仕様は CPOS 側 docs/APP_MANIFEST.md を参照。

3.1 手動登録（従来手順）

CPOS 管理コンソールで加算マネージャをアプリ（appId=kasan）として登録。
/app-tokens で上記 scope を持つ App Token を発行 → KASAN_CPOS_APP_TOKEN に設定。
ユーザーログイン:
- gateway（既定・推奨）: CPOS 側の追加実装は不要。CPOS 共通ログインゲートウェイ /api/auth/login?next=... と、CPOS env の ALLOWED_ORIGIN_SUFFIXES=.care-planning.co.jp / AUTH_COOKIE_DOMAIN=.care-planning.co.jp を利用する。アプリ個別の redirect_uri 許可登録は不要 （invalid_redirect_uri を回避）。加算マネージャは next で戻った後、cpos_session を /api/auth/me に転送して本人確認する。加算マネージャは同じ親ドメイン配下（例 kasan.care-planning.co.jp）に置くこと（cookie 共有のため）。
- connect（旧・任意）: KASAN_CPOS_AUTH_FLOW=connect のときのみ。CPOS 側に B1 受け渡し API （ref/KASAN_APP_API_ADDITIONS.md B1）と、redirect_uri の完全一致許可が必要。
- 未実装/未接続の間は KASAN_CPOS_FAKE=1 で動作確認できます。

4. 主なエンドポイント（加算マネージャ側）

メソッド	パス	説明
GET	`/api/auth/cpos/start`	CPOS 同意画面へ 302
GET	`/api/auth/cpos/callback`	code 交換 → セッション cookie 発行 → `/pro`
POST	`/api/auth/logout`	セッション破棄
GET	`/api/me`	ログイン状態（uid/organizationId/role/plan）
GET/POST/PUT/DELETE	`/api/profiles/facilities`・`/api/profiles/staff-rosters`	施設・名簿（CPOS app-data）
GET/POST/DELETE	`/api/drafts`（`/:id/merge`・`/:id/analyze`）	ドラフト
GET	`/api/analyses`・`/api/analyses/:id`	履歴（有料）
POST	`/api/analyses/:id/review`	レビュー記録（有料）
POST	`/api/analyze/from-cpos`	App Token で CPOS 集計を取得 → 判定（要ログイン）
GET	`/api/cpos/facilities`	App Token で事業所一覧（allowedFacilityIds で絞込）
GET	`/api/services/:serviceKey/kasan-catalog`	サービス種別ごとの加算一覧（公開・マスタ由来）。事業所全体／利用者個別／その他に分類
GET	`/api/cpos/facility/kasan-overview`	事業所の加算一覧＋「現在算定中／取得余地」＋整備状況＋CPOS から自動取得した職員/利用者集計（`dataSource`）。`facilityId`（必須）・`serviceMonth`・`serviceKey`（省略時は事業所のサービス種別から推定）
GET	`/facility`	CPOS 専用モード画面。ログイン→事業所選択→事業所タイプの加算一覧（職員情報は自動取得）。管理機能・ユーザー一覧・手入力は出さない
GET	`/api/auth/cpos/start?next=/facility`	ログイン後に `next`（同一オリジンの相対パスのみ）へ戻す。専用モードの入口

kasan-overview は CPOS の /api/kasan/v1/facilities/:id/monthly-status（整備状況）と /api/kasan/v1/analysis-source（claimSummary.currentAddOnCounts）を併用し、 regulatory_master/mapping/cpos_addon_mapping.json で算定中加算を kasan_key に対応づけます。重い AI 解析を回す前の「まず関係加算を一覧で見る」入口です。 | GET/POST | /api/admin/users・/api/admin/stats・/api/admin/users/:uid・/api/admin/users/:uid/plan | 管理（管理者のみ） |

CSRF: 変更系 /api/* は X-CSRF-Token（/api/health の csrf.token）が必要。

5. ログとセキュリティ

ログ禁止: App Token 平文 / Authorization ヘッダ / Cookie 本文 / 個人情報。
保存禁止: 氏名・被保険者番号等。保存前に anonymize.js で除去・要約し、assertStorageSafe で最終チェック。
組織隔離: すべての保存は organizationId 名前空間。

6. ローカル/結合テスト

# 純ロジック + 匿名化 + CPOS store（Fake）
npm run test:smoke

# サーバ起動 + Fake CPOS でルートを実 HTTP 検証
npm run test:integration

# 手動: Fake CPOS でサーバ起動
KASAN_CPOS_FAKE=1 KASAN_SESSION_SECRET=$(openssl rand -hex 32) \
  KASAN_DEFAULT_CPOS_BASE_URL=https://cpos.example.jp npm start

7. 関連ドキュメント

CPOS_TOKEN.md — 利用者向けログイン手順
AUTH_AND_PLANS.md — ログイン・プラン
DATA_SAFETY.md — データ取扱方針
ref/KASAN_APP_API_ADDITIONS.md — CPOS に追加すべき API（提案）

このドキュメントはリポジトリ docs/ 配下の Markdown を配信しています。