従業員同期
Lark従業員ディレクトリを基準に、既存のBase更新に加えてDBのemployeesも作成・更新・無効化します。
取得元：Lark従業員API / 従業員Base
Pull Request #494 · Change Guide
Larkマスタ同期を
3つの責務へ分割
従業員・PC・マッピングが混在していた同期処理を独立させ、取得元、DB更新、無効化、通知、エラー方針を明確にしました。
何が変わったか
ひとつの大きな「PCマッピング同期」から、単独実行できる3コマンドへ責務を分離しました。
PC同期
Lark PC一覧を読み込み、pcsを作成・更新・再有効化します。一覧から消えたPCは無効化します。
取得元：LARK_PC_TABLE_ID
マッピング同期
従業員とPCのリンクを読み込み、employee_pc_assignmentsへ履歴を保ちながら割り当てを反映します。
取得元：LARK_PC_MAPPING_TABLE_ID
マスタ同期の実行順序
前段のデータを後段が参照するため、順序を固定しています。途中で失敗した場合は後続処理を止め、完了済みの前段処理は巻き戻しません。
01 従業員employeesを最新化
→
02 PCpcsを最新化
→
03 マッピングassignmentsを反映
→
04 freee従業員IDを同期
排他ロックは実装していません。 処理の複雑化を避け、各コマンドの責務とトランザクション境界を明確にする方針です。
データ更新ルール
| 対象 | 新規・更新 | 一覧から消えた場合 | 再登場した場合 |
|---|---|---|---|
| 従業員 | 社員番号を基準に作成・更新。LarkユーザーIDとBaseレコードIDも保持。 | 従業員と有効な割り当てを無効化。 | 同じ従業員レコードを再有効化。 |
| PC | BaseレコードIDまたはPC識別子で作成・更新。OSも同期。 | PCと有効な割り当てを無効化。 | 同じPCを再有効化。 |
| 割り当て | 完全な従業員・PCリンクから新しい割り当てを作成。 | 従来の有効レコードを無効化し、監査履歴として保持。 | 過去レコードは再利用せず、新しい履歴を作成。 |
入力を緩めない設計
Value Object
PcIdentifier：正規化せず、空文字や前後空白を例外にするPcOsType：Windows/macOSのみ許可- API DTOは実際の全フィールドを厳密な型で受け取る
異常時の扱い
失敗 取得結果0件、重複、複数リンク、参照先なし、無効な参照先
警告して保持 従業員またはPCのどちらか一方が空の不完全マッピング
履歴保持 古い割り当ては削除せず無効化
データベース変更
Migration 013
employees.lark_user_idを追加（nullable / unique）employees.lark_record_idを追加（nullable / unique）pcs.lark_record_idを追加（nullable / unique）pcs.is_activeとインデックスを追加
旧テーブルを削除
employee_pc_mapping は削除し、現在の正規化済みテーブル employee_pc_assignments に一本化します。
割り当ては物理削除せず、無効化によって監査ログの後方互換性を保ちます。
設定・運用の変更
| 旧 | 新 | 用途 |
|---|---|---|
LARK_TABLE_ID | LARK_PC_TABLE_ID | PC一覧の取得先 |
LARK_TABLE_ID | LARK_PC_MAPPING_TABLE_ID | 従業員・PCマッピングの取得先 |
共通Base読取
LarkBaseTableReader を合成し、ページングやAPI呼び出しを共通化。Service継承は採用していません。
Lark通知
変更内容は既存の従業員一覧更新と同じ通知経路でLarkへ送信。失敗ログも既存ハンドラ経由で通知します。
cron
独立したPC・マッピング用エントリポイントを追加し、マスタ同期から順次呼び出します。
実コンテナでの検証
215 testsPHPUnit 全件成功
573 assertions4 tests skipped
0 errorsPHPStan 変更範囲
0 violationsPHPCS 変更範囲