Kenichiro NOGI d745652a00 docs(org-master-sync): ③スコープ縮小完了をREADMEへ反映

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-09-21 17:39:13 +09:00

8.0 KiB

Raw Blame History

org-master-sync

LINEWORKS・プリザンター・Keycloak横断の組織・社員管理データベース構築プロジェクト。設計: docs/superpowers/specs/2026-08-07-org-master-sync-design.md

セッション再開時はまずこのファイルを読むこと。 Node.js版・n8n版2系統が並行して存在し、環境(本番/TEST)の区別も紛らわしいため、経緯を口頭やメモリの断片だけで追わず、このREADMEを都度更新して単一の参照先にする。

重要: 環境の区別(混同注意)

環境	ホスト	備考
本番	`https://nextoffice.next-hd.co.jp/pleasanter/`	co.jp、「2」無し
TEST/staging	`https://nextoffice2.next-hd.net/pleasanter/`	net、「2」あり

Node.js版.env(無印)はTEST環境向け。本番へ向けるには.env.productionを使う(node --env-file=.env.production <script>)
n8n版のworkflow_config_values(n8n Data Table)は_TEST/_PRODのキー接尾辞で区別
過去に「本番反映済み」という記録がどちらの環境を指すか誤認した事故があった(2026-09-21)。確認時は必ずホスト名まで見ること

全体ステータス(2026-09-21時点)

本番504412(社員・組織マスタ管理テーブル)、617件、n8n版③により2026-09-05に反映済み。 Node.js版(.env無印=TEST環境向け)とn8n版(_PROD=本番)は別ホストに対して動いていた別データ。504412にデータが揃っているのはn8n版③の実績。

Node.js版(`src/commands/`) — Keycloak同期の唯一実装として稼働中

①②は現状Node.js版が主で使われているわけではなく、④(Keycloak同期)が実運用上の主機能。下記「現状ステータス」節を参照。

n8n版(production、org-sync①〜④) — 本番実行実績あり、一部未完成

ワークフロー	実装	本番実行実績
① LW→プリザンター(役職/職級/利用権限/Groups箱作り)	済	2026-09-05夜、実行済み
② バックアップ(504412→504407)	済	未実行
③ マージマスターメイン(LW+Pleasanter既存状態→504412 import)	済(2026-09-21、Groups反映機能を除去し504412専念へ変更完了。design doc: 2026-09-21-org-sync-n8n-3-scope-narrowing-design.md)	2026-09-05夜、実行済み(旧版=Groups反映込み)。新版は未実行
④/④-0〜④-3(Pleasanter標準User/Dept/Groupsへの新規登録・更新・無効化)	済だが既知バグあり(Class035がexport APIだとグループ名文字列で返り必ず失敗)。2026-09-21時点、③のスコープ縮小後にここで改めてUser/Dept/Groups反映を担う方針(未着手)	未実行
①へのKeycloakグループ同期(組織階層+フラットグループの箱作り)	済(PUT反映済み)	未実行・未検証(Code node内httpRequestの動作自体未確認)
⑤ Keycloakユーザー同期(Upsert・削除・グループ所属)	未着手、設計のみ	—

詳細経緯: docs/superpowers/plans/2026-09-05-org-master-sync-n8n-production-migration.md

次にやること(優先順、2026-09-21時点)

③のスコープ縮小実装(design doc参照)→本番反映
④系のClass035バグ修正、User/Dept/Groups反映(新規・更新・無効化)の設計・実装
①のKeycloakグループ同期、初回実行検証
⑤(Keycloakユーザー同期)の設計・実装

現状ステータス(Node.js版)

Phase 1完了: LINEWORKS取得（①fetch-lineworks）→ プリザンターマスタテーブル反映（②merge-master）が動作。 Phase 2完了: マスタ→Keycloak完全同期（④sync-keycloak）が動作。マスタの全項目（プリザンターの SiteSettings.Columnsから動的取得）をKeycloakのカスタム属性として同期し、項目の追加・削除の両方に自動追従する。新規作成はClassZ=有のみ、既存ユーザーはCheck062に応じて無効化のみ（削除はしない）、マスタからレコード自体が消えた場合のみKeycloakユーザーを完全削除する。前回同期状態はconfigs/keycloak-sync/で管理。マスタテーブルは.envのPLEASANTER_MASTER_SITE_ID（本番は504412）。 ③sync-pleasanterは本番移行後に着手（別プランで対応）。

【2026-09-06】突合キーをpleasanterResultId（プリザンターのレコードID）からClassA（LINEWORKS 社員ID、UUID）へ変更: プリザンター側マスタテーブルのSiteId移行（フルリストア、2026-09-03）でレコードIDが全件振り直され、旧突合キーのままだと本番Keycloakの既存ユーザーが誤って全削除され重複ユーザーが大量作成される事故を、実機比較（本番マスタ617件 vs 本番Keycloak）で--execute前に検出した。LINEWORKSが正マスタであり、ClassAはプリザンター側のレコード引っ越しの影響を受けないため恒久的な突合キーとして採用。既存KeycloakユーザーのClassA属性値は通常の列同期で既に正しく書き込まれ済みだったため、追加のマイグレーションは不要だった（実機確認済み）。旧突合キーpleasanterResultId属性は削除せず、参考情報として現在のResultId値へ更新し続ける。

セットアップ

cd apps/org-master-sync
npm test   # ユニットテスト実行(node --test)

.envは3システム分の認証情報を含む（gitignore対象、既に設定済み）。 Keycloak側はorg-master-syncクライアントのサービスアカウントにrealm-managementのrealm-adminロールが付与済み（User Profile属性定義の動的追加・削除に必要。Keycloak管理コンソールで1回のみ設定済み）。

コマンド

node src/commands/fetch-lineworks.js   # ① LINEWORKSから全件取得 → data/master-source/lineworks-snapshot.json
node src/commands/merge-master.js      # ② マスタテーブル(SiteId=1)へ突合・反映
node src/commands/sync-keycloak.js [--execute]  # ④ マスタをKeycloak(nexthdレルム)へ完全同期

運用上の注意:

④実行前には必ず①②を先に実行すること。LINEWORKS退職者検知（②）は都度の実行に依存するため、①②を経ずに④だけを実行すると在籍状態が古いままKeycloakへ反映される
④はプリザンター側でカラムが削除されると対応するKeycloak属性も削除し、マスタレコード自体が削除されると対応するKeycloakユーザーも完全削除する（完全同期）。ドライランで「属性削除予定」「delete予定」件数を必ず確認してから--executeすること

Claude Skill経由でも起動可能（.claude/skills/org-fetch-lineworks/ / org-merge-master/ / org-sync-keycloak/）。

ディレクトリ構成

org-master-sync/
  .env           認証情報(git管理対象外)
  keys/          LINEWORKS秘密鍵(git管理対象外)
  src/
    lib/         lineworksAuth.js / lineworksClient.js / pleasanterClient.js / keycloakClient.js / keycloakColumnSync.js
    config/      masterFields.js（マスタ項目→プリザンターフィールドの割当定義）
    commands/    fetch-lineworks.js / merge-master.js / sync-keycloak.js
  scripts/       一回限りの移行・保守スクリプト（本番→テスト環境インポート等）
  test/          node --testによるユニットテスト
  data/          取得データ・スナップショット(git管理対象外)
  pleasanter-saml/  SAML SSO設定一式

他システムから独立したフォルダとして構成。単体で別リポジトリへ切り出す場合もこのフォルダごと移動すればよい。

8.0 KiB Raw Blame History Unescape Escape