Plan 4-D-2: LINE 連携 User と旧 manual User のマージ管理画面

Plan ID

4-D-2

作成日

2026-05-17

前提

Plan 4-D-1 (LINE セルフ登録) main マージ済

対象

staff-web (Vite + React 19, shadcn/ui), API (Rails 8)

主な利用者

受付スタッフ (staff)、院長 (admin)

ブランチ

feat/plan-4-d-2-line-merge

1. 背景

Plan 4-D-1 で LINE セルフ登録を導入した結果、患者を表す users レコードが 2 経路で作られるようになった。同一人物が DB 上で別レコードになると、以下の運用問題が発生する。

2. 用語

UI 表記は受付向けにわかりやすく、コード/DB/API は技術用語で統一する。

3. 主要シナリオ

マージ画面は 3 つの入口 + undo 履歴 の 4 シナリオで使われる。

4. 照合ロジック (候補検出)

候補は永続化せず 都度 SQL クエリで計算する (MergeCandidateFinder service)。マージ済 (provider=line) や soft_deleted は where 句で自動除外されるため、「一生フラグが残る」問題は構造的に発生しない。

強度ラベルと表示先

phone 正規化

-- manual: '090-1234-5678' → '09012345678'
regexp_replace(m.phone, '[^0-9]', '', 'g') = l.phone

5. データ移植ルール (マージ実行時)

残す側 = manual User、吸収側 = LINE User。snapshot を user_merge_logs.snapshot (JSONB) に保存して undo で逆適用する。

snapshot の中身 (undo 用)

{
  "manual_original_provider": "manual",
  "manual_original_uid": null,
  "manual_original_date_of_birth_was_blank": true,
  "line_original_uid": "U7e9c...",
  "line_original_jti": "<uuid>",
  "line_original_deleted_at": null,
  "line_original_active": true
}

6. データモデル

users テーブルはスキーマ変更なし。新規 1 テーブルのみ追加。

新規テーブル: user_merge_logs

create_table :user_merge_logs do |t|
  t.references :merged_into_user, null: false,
    foreign_key: { to_table: :users }, index: true
  t.references :merged_from_user, null: false,
    foreign_key: { to_table: :users }, index: true
  t.references :executed_by_user, null: false,
    foreign_key: { to_table: :users }, index: true
  t.datetime :executed_at, null: false
  t.datetime :undone_at
  t.references :undone_by_user,
    foreign_key: { to_table: :users }
  t.jsonb :snapshot, null: false, default: {}
  t.timestamps
end

# undo 後は再マージ可能なため partial unique index
# merged_from (LINE) に partial unique: 同時に 1 manual にしか紐付かない
# merged_into (manual) は unique にしない: 過去複数の LINE 紐付け / 取消が可能
add_index :user_merge_logs,
  [:merged_from_user_id],
  unique: true,
  where: "undone_at IS NULL",
  name: "index_user_merge_logs_active_from"

7. API 設計

認可は staff / admin 両方可。React Query は ["merge-candidates", ...] プレフィックスで invalidate を一括化。

エラーコード詳細

8. 認可

Pundit policy 新規追加。Plan 3-B の患者削除と同等の権限レベル。

class UserMergeLogPolicy < ApplicationPolicy
  def index? = staff_or_admin?
  def show?  = staff_or_admin?
  def merge? = staff_or_admin?
  def undo?  = staff_or_admin?
end

9. 競合制御

2 受付が同じ LINE User を同時にマージしようとした場合、後勝ち側は 409 で弾く。DB 層と Service 層の二重防御。

def execute(manual_user_id:, line_user_id:, executed_by:)
  ActiveRecord::Base.transaction do
    manual = User.lock("FOR UPDATE").find(manual_user_id)
    line   = User.lock("FOR UPDATE").find(line_user_id)
    raise Mismatch unless mergeable?(manual:, line:)
    snapshot = build_snapshot(manual:, line:)
    apply_merge!(manual:, line:)
    UserMergeLog.create!(...)
  end
end

10. staff-web 構成

共通コンポーネントを MergeFieldDiff に集約し、モーダル (S1/S2) とページ (S3) で再利用。

ルート & コンポーネント

React Query キー

mergeCandidates: {
  list:    (filters) => ["merge-candidates", "list", filters],
  count:   ()        => ["merge-candidates", "count"],
  forUser: (id)      => ["merge-candidates", "for-user", id],
}
mergeLogs: { list: (page) => ["merge-logs", "list", page] }

マージ / undo 後 invalidate: ["merge-candidates"] 全体、["patients"] 全体、["reservations"] 全体。

11. テスト戦略

12. スコープ

13. 非機能要件

14. リスクと緩和策

15. 実装フェーズ (writing-plans で詳細化予定)