From a94fb643f7b6a1fe10ed005d99399e5c6ab11f43 Mon Sep 17 00:00:00 2001
From: Junya Ishihara <junya@champierre.com>
Date: Fri, 12 Jun 2026 00:04:53 +0900
Subject: [PATCH] =?UTF-8?q?=E6=AE=B5=E9=9A=8E=E7=9A=84=E3=83=AA=E3=83=95?=
 =?UTF-8?q?=E3=82=A1=E3=82=AF=E3=82=BF=E3=83=AA=E3=83=B3=E3=82=B0=E8=A8=88?=
 =?UTF-8?q?=E7=94=BB=E3=82=92=20docs/refactoring=20=E3=81=AB=E8=BF=BD?=
 =?UTF-8?q?=E5=8A=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

2026-06-11 のコードベース調査に基づき、蓄積した技術的負債を
6 フェーズで解消する詳細計画を文書化。

- README: 負債サマリ・フェーズ依存関係・共通原則・効果測定
- Phase 0: リポジトリ衛生とドキュメント整合（挙動変更なし）
- Phase 1: テスト基盤の再建（実コード未検証テストの解消）
- Phase 2: バックエンド構造（定型重複・CalendarService 分割）
- Phase 3: フロントエンド構造（重複排除・ES modules 化）
- Phase 4: CSS/HTML（埋め込み CSS 約2,700行の外部化・重複解消）
- Phase 5: E2E と CI 品質ゲート

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/refactoring/README.md                  | 82 +++++++++++++++++++
 docs/refactoring/phase-0-hygiene.md         | 59 ++++++++++++++
 docs/refactoring/phase-1-test-foundation.md | 79 ++++++++++++++++++
 docs/refactoring/phase-2-backend.md         | 89 +++++++++++++++++++++
 docs/refactoring/phase-3-frontend.md        | 69 ++++++++++++++++
 docs/refactoring/phase-4-css-html.md        | 50 ++++++++++++
 docs/refactoring/phase-5-e2e-ci.md          | 63 +++++++++++++++
 7 files changed, 491 insertions(+)
 create mode 100644 docs/refactoring/README.md
 create mode 100644 docs/refactoring/phase-0-hygiene.md
 create mode 100644 docs/refactoring/phase-1-test-foundation.md
 create mode 100644 docs/refactoring/phase-2-backend.md
 create mode 100644 docs/refactoring/phase-3-frontend.md
 create mode 100644 docs/refactoring/phase-4-css-html.md
 create mode 100644 docs/refactoring/phase-5-e2e-ci.md

diff --git a/docs/refactoring/README.md b/docs/refactoring/README.md
new file mode 100644
index 0000000..d2a2807
--- /dev/null
+++ b/docs/refactoring/README.md
@@ -0,0 +1,82 @@
+# リファクタリング計画 全体像
+
+最終更新: 2026-06-11
+
+このディレクトリは、shift2 に蓄積した技術的負債を段階的に解消するためのリファクタリング計画です。各フェーズは独立したドキュメントになっており、上から順に着手することを前提に依存関係を設計しています。
+
+## 背景: 現状の負債サマリ（2026-06-11 調査）
+
+| 領域 | 規模 | 主な問題 |
+|------|------|----------|
+| `index.html` | 3,005 行 | 約 9 割（約 2,700 行）が埋め込み CSS。25 以上のクラスが重複定義。インライン `onclick` が 20 箇所 |
+| `js/modules/` | 16 ファイル・約 5,800 行 | ES modules ではなく `<script>` タグ読み込み順依存。`timeToMinutes` 等の重複関数。`api.js` を迂回した直接 `fetch` が 7 箇所。旧 UI のデッドコード |
+| `server/src` | 約 4,000 行 | ルートの try/catch 定型が 37 箇所・`res.status(500)` が 49 箇所。5 モデルにほぼ同一の CRUD が約 48 メソッド。`CalendarService.ts` が 863 行・16 責務 |
+| フロントテスト | 17 ファイル・約 5,100 行 | **実コードを import せず、テスト内に実装のコピーを定義する運用**（CLAUDE.md 公認）。実装との乖離リスクが構造的に存在 |
+| バックテスト | 8 ファイル・約 3,200 行 | 全依存をモック化しモック値を検証するだけのテスト、実装を呼ばないインラインコピーのテストが混在 |
+| E2E | 2 ファイル | 全テストが `test.skip` で無効。CI 未接続。`baseURL` のポートも実態と不一致 |
+| CI / カバレッジ | — | フロントのカバレッジ計測対象が空。閾値 statements 3%。backend-tests ステップは `\|\| echo` で失敗を握りつぶす |
+| ドキュメント | — | CLAUDE.md の「アーキテクチャ」節が旧構成（ポート 8081、Client ID ハードコード等）のまま |
+| リポジトリ衛生 | — | `.serena/` が追跡されている、`help.html` に独立した重複 CSS（約 265 行） |
+
+## フェーズ構成と依存関係
+
+```
+Phase 0: リポジトリ衛生とドキュメント整合   （挙動変更なし・即効）
+   ↓
+Phase 1: テスト基盤の再建                 （以降のフェーズの安全網）
+   ↓
+Phase 2: バックエンド構造                  ┐
+Phase 3: フロントエンド構造                ├ 1 完了後は並行可能
+Phase 4: CSS / HTML                        ┘（ただし同時着手は 2 つまで推奨）
+   ↓
+Phase 5: E2E と CI 品質ゲート              （全フェーズの成果を固定化）
+```
+
+| フェーズ | ドキュメント | 目安規模 |
+|----------|--------------|----------|
+| 0 | [phase-0-hygiene.md](phase-0-hygiene.md) | PR 2〜3 本・小 |
+| 1 | [phase-1-test-foundation.md](phase-1-test-foundation.md) | PR 5〜8 本・大 |
+| 2 | [phase-2-backend.md](phase-2-backend.md) | PR 6〜9 本・大 |
+| 3 | [phase-3-frontend.md](phase-3-frontend.md) | PR 5〜7 本・大 |
+| 4 | [phase-4-css-html.md](phase-4-css-html.md) | PR 3〜4 本・中 |
+| 5 | [phase-5-e2e-ci.md](phase-5-e2e-ci.md) | PR 3〜5 本・中 |
+
+## 全フェーズ共通の原則
+
+1. **挙動を変えない。** リファクタリング PR に機能追加・バグ修正を混ぜない。バグを見つけたら別 PR（TDD: 再現テスト → 修正）で先に直す。
+2. **1 PR = 1 ステップ。** 各フェーズ文書の「作業項目」1 つを 1 PR にする。レビュー可能な差分量（目安 ±400 行以内、機械的な一括置換を除く）を守る。
+3. **テストが先。** 対象コードにテストがなければ、現在の挙動を固定する特性テスト（characterization test。現状の出力をそのまま期待値にするテスト）を先に書いてから動かす。
+4. **CLAUDE.md のブランチ運用に従う。** main 直 push 禁止、feature ブランチ → PR → マージ。
+5. **各 PR で全テスト green + ローカルでの手動スモーク**（ログイン → シフト申請 → 一覧表示 → キャンセル）を確認する。
+6. **計測してから消す。** デッドコード削除は「全ファイル grep で参照ゼロ」を PR 説明に明記する。
+
+## 進捗の付け方
+
+各フェーズ文書内のチェックリストを PR マージ時に更新する（チェック更新はそのリファクタ PR に含めてよい）。フェーズ完了時にこの README の下表を更新する。
+
+| フェーズ | 状態 | 完了日 |
+|----------|------|--------|
+| 0 | 未着手 | — |
+| 1 | 未着手 | — |
+| 2 | 未着手 | — |
+| 3 | 未着手 | — |
+| 4 | 未着手 | — |
+| 5 | 未着手 | — |
+
+## 効果測定（before / after）
+
+フェーズ完了ごとに以下を記録する。
+
+```bash
+# ファイル規模
+wc -l index.html js/modules/*.js | tail -1
+find server/src -name "*.ts" ! -path "*__tests__*" | xargs wc -l | tail -1
+
+# テスト
+npm test 2>&1 | tail -4
+
+# カバレッジ
+npm run test:coverage 2>&1 | tail -10
+```
+
+ベースライン（2026-06-11）: フロント約 8,800 行（index.html 含む）/ バックエンド本体約 4,000 行 / テスト 366 件 green。
diff --git a/docs/refactoring/phase-0-hygiene.md b/docs/refactoring/phase-0-hygiene.md
new file mode 100644
index 0000000..c46f6d1
--- /dev/null
+++ b/docs/refactoring/phase-0-hygiene.md
@@ -0,0 +1,59 @@
+# Phase 0: リポジトリ衛生とドキュメント整合
+
+**ゴール**: 挙動を一切変えずに、誤った情報源・無意味なファイル・設定の矛盾を排除する。以降のフェーズで人（と AI エージェント）が古い情報に騙されない状態を作る。
+
+**前提**: なし（いつでも着手可能）
+
+## 背景
+
+- `CLAUDE.md` の「アーキテクチャ」「Google OAuth 設定」節は初期のスタティック SPA 時代の記述のまま（CLAUDE.md:175-181 の「認可済みオリジン: localhost:8081」「Client ID は index.html と app.js にハードコード」等）。現在は Express がポート 3000 で配信し、Client ID は `/api/config` から実行時取得（js/modules/config.js）であり、事実と異なる。
+- `playwright.config.ts:11` の `baseURL: 'http://localhost:8080'` が開発サーバー（3000）と不一致。
+- `.serena/` （外部 AI ツールの設定）が git 追跡されている。
+- `app.js`・`js/modules/shiftRequest.js` 等に旧 UI のデッドコードが残存。
+
+## 作業項目
+
+### 0-1. CLAUDE.md / README.md の実態同期（PR 1 本）
+
+- [ ] CLAUDE.md の「アーキテクチャ」節（ファイル構成・認証フロー・Google OAuth 設定）を現構成に書き換える
+  - ファイル構成: `index.html` + `js/modules/*.js`（16 ファイル）+ `server/src`（Express + TS）
+  - Client ID: `.env` → `/api/config` → `config.js` の実行時取得フローを記載
+  - ポートは 3000 に統一（8081 への言及を全削除）
+- [ ] 「実装上のポイント」節の `decodeJwtResponse` / `#loginSection` 等の記述が現コードと一致するか検証し、ずれていれば修正
+- [ ] README.md のセットアップ手順を一読し、現在の `npm run dev` フローと一致させる
+- [ ] CLAUDE.md の「フロントエンドテストの慣習」節に「Phase 1 で実コード import 方式へ移行予定」と注記（Phase 1 完了時に節ごと書き換え）
+
+**受け入れ条件**: ドキュメント内の全ポート番号・全ファイルパスが実在のものと一致する。
+
+### 0-2. 設定ファイルの矛盾解消・不要ファイル削除（PR 1 本）
+
+- [ ] `playwright.config.ts` の `baseURL` をサーバー実ポートに合わせる（`webServer` にも `port` を明示）
+- [ ] `.serena/` を git 追跡から外す（`git rm -r --cached .serena` + `.gitignore` 追加）。チームで Serena を使っていないなら削除
+- [ ] `codecov.yml` / `jest.config.ts` のカバレッジ閾値に「現状値は暫定。Phase 5 で引き上げ」のコメントを付ける（数値変更は Phase 5）
+- [ ] `.github/workflows/test.yml` の backend-tests ステップの `|| echo "Backend tests not yet configured"` を削除（バックエンドテストは既に 154 件存在しており、失敗の握りつぶしは危険）
+
+**受け入れ条件**: CI が green のまま。`git ls-files | grep .serena` が空。
+
+### 0-3. 明白なデッドコードの削除（PR 1 本）
+
+削除前に**全ファイル grep で参照ゼロを確認し、その証跡を PR 説明に記載**する。
+
+- [ ] `js/modules/shiftRequest.js` の旧 UI 関数群: `openShiftRequestModal`（:177）、`updateTimeSlotCapacity`（:205）、`generateTimeSlots`（:253）、`shiftRemarks` 参照（:311）— HTML 側に対応要素がないことを確認の上削除
+- [ ] `index.html` の `display:none` で恒久的に隠されているタブ（:2751, :2753 付近）が本当に不要か確認し、不要なら HTML・関連 JS ごと削除
+- [ ] `server/src/services/CalendarService.ts` の後方互換ラッパー: `addShiftToCalendar`（単なる委譲）、`deleteShiftFromCalendar`（コメントに「後方互換性のために残されています」）— 呼び出し元ゼロを確認して削除
+- [ ] 上記削除で参照が消えるテスト（コピー実装をテストしているもの）も同時に削除
+
+**受け入れ条件**: 全テスト green。手動スモーク（ログイン → 申請 → 一覧 → キャンセル）が通る。
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| 「デッドコード」が実は動的参照されている（`onclick="..."` 文字列内など） | grep は関数名の文字列一致で行い、`index.html`・`help.html` の属性値も対象に含める |
+| `.serena` 削除が他メンバーの環境を壊す | 追跡から外すだけにし、ローカルファイルは残す（`--cached`） |
+
+## 完了条件（Definition of Done)
+
+- CLAUDE.md / README.md / 各種設定のポート・パス・手順がすべて実態と一致
+- 旧 UI デッドコードと後方互換ラッパーが削除され、全テスト green
+- CI でバックエンドテストの失敗が正しく fail として扱われる
diff --git a/docs/refactoring/phase-1-test-foundation.md b/docs/refactoring/phase-1-test-foundation.md
new file mode 100644
index 0000000..aacdbc4
--- /dev/null
+++ b/docs/refactoring/phase-1-test-foundation.md
@@ -0,0 +1,79 @@
+# Phase 1: テスト基盤の再建
+
+**ゴール**: 「テストが実コードを検証している」状態を作り、Phase 2〜4 の構造変更を安全に行える安全網を確立する。
+
+**前提**: Phase 0 完了（デッドコードが消えており、消えたコードのテストを書かずに済む）
+
+## 背景
+
+現在のテストは量（フロント約 5,100 行 + バック約 3,200 行、計 366 件）の割に、リファクタリングの安全網としてほとんど機能しない。
+
+1. **フロントテストは実コードを import していない。** CLAUDE.md 公認の運用として、テストファイル内に「期待挙動を表現するインライン関数」を定義してそれをテストしている（例: `test/special-shift-slots.test.js:18-42` に `buildSpecialShiftSlots` のコピー、`test/special-shift-name.test.js:239-296` に `displayMyShifts` 相当の再実装）。実装側を壊してもテストは緑のまま。
+2. **バックテストにも実装を呼ばないテストがある。** `server/src/__tests__/CalendarService.test.ts:56-149` は CalendarService を呼ばず、テスト内のローカル変数やコピー関数を検証している（実質トートロジー）。
+3. **ルートテストは全依存モック**（モデル・CalendarService・db）で、HTTP 層の分岐は検証できているが、SQL を含むモデル層の実挙動は未検証。
+
+## 方針
+
+- フロント `js/modules/*.js` を **挙動を変えずに Jest から require 可能**にする。ブラウザ側は従来どおり `<script>` タグで動くよう、各ファイル末尾に CommonJS ガード付きエクスポートを追加する方式を採る（完全な ES modules 化は Phase 3 末で実施。ここでは最小変更に留める）:
+
+  ```js
+  // ファイル末尾に追加（ブラウザでは無視される）
+  if (typeof module !== 'undefined' && module.exports) {
+      module.exports = { buildSpecialShiftSlots, timeToMinutes, minutesToTime };
+  }
+  ```
+
+- バックエンドは **better-sqlite3 のインメモリ DB（`:memory:`）を使った統合テスト**を導入し、モデル層と「ルート + 実 DB」の縦の検証を可能にする。
+
+## 作業項目
+
+### 1-1. テスト棚卸しと分類（PR 1 本、ドキュメントのみ）
+
+- [ ] 全テストファイルを「A: 実コードを検証」「B: コピー実装を検証（書き換え対象）」「C: トートロジー（削除対象）」に分類し、`docs/refactoring/test-inventory.md` として記録
+- [ ] B のテストごとに、対応する実関数（ファイル・関数名）を対応表にする
+
+### 1-2. js/modules にエクスポートガードを追加（PR 1 本）
+
+- [ ] 純粋ロジックを持つモジュールから着手: `utils.js`、`shiftRequest.js`（`buildSpecialShiftSlots`/`timeToMinutes`/`minutesToTime`）、`specialShifts.js`、`state.js`
+- [ ] ブラウザ挙動が不変であることを手動スモークで確認（`module` 未定義ガードにより no-op）
+- [ ] `jest.config.ts` の frontend プロジェクトで `collectCoverageFrom` に `js/modules/**` を設定（閾値はまだ上げない）
+
+**受け入れ条件**: 既存テスト全 green、ブラウザ動作不変、`require('../js/modules/utils.js')` がテストから成功する。
+
+### 1-3. フロントテストの実コード接続（PR 3〜5 本に分割）
+
+分類 B のテストを 1 ファイル〜数ファイルずつ書き換える。
+
+- [ ] テスト内のコピー実装を削除し、実モジュールの import に置換
+- [ ] **置換時に実装とコピーの差分を必ず確認する。** 乖離が見つかった場合はどちらが正かを判断し、バグなら別 PR で TDD 修正（このフェーズの PR に混ぜない）
+- [ ] DOM 依存の強い関数（`display*` 系）は、jsdom + `test-utils.js` のフィクスチャで実関数を呼ぶ形に書き換える。書き換えコストが高すぎるものは「E2E でカバーする」と判断して削除し、Phase 5 の E2E 対象リストに追記
+- [ ] 分類 C（トートロジー）のテストを削除: `CalendarService.test.ts:56-149` のコピー検証 describe、`test/shift-delete-functions.test.js` の自明 expect 等
+
+**受け入れ条件**: `test/` 配下に実装コピー関数が残っていない（`grep -rn "function buildSpecialShiftSlots\|function mergeConsecutiveTimeSlots" test/` が空）。
+
+### 1-4. バックエンド統合テストの導入（PR 2 本）
+
+- [ ] `server/src/database/db.ts` を「スキーマ定義」と「接続生成」に分離し、テストから `:memory:` DB を注入できるようにする（既存 import 互換の default export は維持）
+- [ ] モデル統合テスト: 5 モデルの CRUD を実 SQL で検証（`server/src/__tests__/integration/models.test.ts`）
+- [ ] ルート統合テスト: supertest + 実 DB（CalendarService のみモック）で、申請 → 取得 → 削除の代表フローを検証
+
+**受け入れ条件**: モデル層の SQL がテストで実行される（カバレッジで models/ が計測される）。
+
+### 1-5. CLAUDE.md の運用ルール更新（PR 1 本）
+
+- [ ] 「フロントエンドテストの慣習」節を削除し、「テストは実コードを import する。エクスポートガード方式」の新ルールに書き換える
+- [ ] 新規テストでコピー実装方式を禁止する旨を明記
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| コピー実装と実装の乖離が「テスト書き換え」で大量に発覚する | 乖離は発見ごとに記録し、修正はバグ修正 PR として分離。書き換え PR は「実装の現挙動」を正としてテストを合わせる |
+| エクスポートガード追加漏れ・タイポでブラウザが壊れる | 追加は機械的な末尾追記のみとし、PR ごとに手動スモーク必須 |
+| `db.ts` 分離が本番 DB パスに影響 | default export の生成ロジック（パス解決）は変更せず、関数抽出のみ行う |
+
+## 完了条件（Definition of Done）
+
+- テスト内の実装コピーがゼロ、トートロジーテストがゼロ
+- フロントの主要ロジック関数・バックエンドのモデル層がカバレッジ計測に乗っている
+- 全テスト green、CI green
diff --git a/docs/refactoring/phase-2-backend.md b/docs/refactoring/phase-2-backend.md
new file mode 100644
index 0000000..a0130dd
--- /dev/null
+++ b/docs/refactoring/phase-2-backend.md
@@ -0,0 +1,89 @@
+# Phase 2: バックエンド構造の整理
+
+**ゴール**: `server/src` の定型重複を排除し、CalendarService を責務単位に分割して、変更コストと不具合混入リスクを下げる。
+
+**前提**: Phase 1 完了（統合テストが安全網として存在する）
+
+## 背景（2026-06-11 調査）
+
+- ルート層: try/catch + `console.error` + `res.status(500).json({success:false, error:'サーバーエラーが発生しました'})` の定型が 37 箇所、`res.status(500)` は 49 箇所。
+- モデル層: 5 クラス約 1,050 行のうち、try/catch → `console.error` → デフォルト値 return の同型メソッドが約 48 個。
+- `CalendarService.ts`（863 行）: 同期・削除・リトライ・表示名・イベント構築・クリーンアップ・直列化キューの 16 責務が同居。`doSyncShiftsForUserAndDate` と `doSyncSpecialShiftApplicationsForUserAndDate` は約 100 行ずつほぼ同一構造。
+- SQL がルート層（shifts.ts:431）と CalendarService（7 箇所）に直書きされ、モデル層を迂回。
+- `"HH:MM-HH:MM"` のパース・組み立てが 16 箇所に散在し、バリデーションなし。
+- `db.ts` のマイグレーションが「try/catch で ALTER TABLE して全エラーを握りつぶす」方式（db.ts:84-102）。
+- `error: any` などの any が約 23 箇所。
+
+## 作業項目
+
+### 2-1. ルート層: エラーハンドリングの一元化（PR 1 本）
+
+- [ ] `asyncHandler`（async ルートの例外を next へ流すラッパー）と、共通エラーミドルウェア（ログ + 500 応答）を導入
+- [ ] 各ルートの try/catch 定型を撤去し、正常系のみ残す（404/400/409 などの業務分岐は残す）
+- [ ] 既存ルートテストが応答仕様（status / body 形状）の不変を保証していることを確認してから着手
+
+**効果目安**: ルート層から重複 catch 約 37 ブロック（300 行前後）を削減。
+
+### 2-2. ルート層: バリデーションヘルパー（PR 1 本）
+
+- [ ] `requireFields(req.body, ['user_id', 'user_name', ...])` 形式の共通ヘルパーで「必須フィールドが不足しています」系の分岐を統一
+- [ ] 日付形式（YYYY-MM-DD）・time_slot 形式の検証を共通化（2-5 の時刻ユーティリティを利用）
+
+### 2-3. モデル層: 共通化（PR 1〜2 本）
+
+- [ ] try/catch + ログ + デフォルト値の定型を `safeQuery(label, fn, fallback)` 的なヘルパー、または基底クラスに抽出
+- [ ] 「ほぼ同一の getAll / getByUuid / delete / deleteMultiple」をテーブル名・型パラメータで共通化できるか検討。**過度な抽象化はしない**（共通化は同型 3 クラス以上に現れるメソッドのみ対象）
+- [ ] shifts.ts:431 の `UPDATE shifts SET calendar_event_id = NULL ...` をモデルメソッド（`ShiftModel.clearCalendarEventId`）へ移動
+
+### 2-4. CalendarService の分割（PR 2〜3 本）
+
+責務を以下に分割する（ファイル名は例）:
+
+| 新ファイル | 持っていくもの |
+|------------|----------------|
+| `services/calendar/CalendarGateway.ts` | Google API 呼び出し（insert/delete/list）、`withRetry`、`deleteCalendarEvent` |
+| `services/calendar/EventBuilder.ts` | `getDisplayName`、`parseTimeSlot`、`buildEventData` |
+| `services/calendar/SyncService.ts` | `runSerialized` キュー、ユーザー×日付の同期（通常/特別） |
+| `services/calendar/MaintenanceService.ts` | `syncAllShifts`、`deleteAllEvents`、`cleanAndResyncDate`、`getSyncStatus` |
+
+- [ ] 分割ステップ 1: 上記クラスへ移動し、既存 `CalendarService` は委譲だけ残す（呼び出し元・テスト不変のまま green を確認）
+- [ ] 分割ステップ 2: `doSyncShiftsForUserAndDate` / `doSyncSpecialShiftApplicationsForUserAndDate` の共通骨格（既存イベント削除 → ID クリア → マージ → 作成 → リンク）を 1 つのテンプレートメソッドに統合し、「対象レコードの取得」「ID クリア SQL」「イベント summary 生成」だけを差し替え可能にする
+- [ ] 分割ステップ 3: 呼び出し元を新クラス直接参照に切り替え、委譲シェルを削除
+- [ ] CalendarService 内の直書き SQL（calendar_event_id クリア 7 箇所）をモデルメソッドへ移動
+
+**注意**: 直列化キュー（orphan イベント防止、`CalendarServiceSyncSerialization.test.ts`）の挙動を壊さないこと。分割の各ステップでこのテストが green であることを必ず確認する。
+
+### 2-5. 時刻ユーティリティの統一（PR 1 本）
+
+- [ ] `utils/timeSlot.ts` を新設: `parseTimeSlot(slot): {start, end}`、`formatTimeSlot(start, end)`、形式バリデーション（`HH:MM-HH:MM` 正規表現）
+- [ ] `timeSlotMerger.ts`・`EventBuilder`・ルート層の `split('-')` 直書き（計 16 箇所）を置換
+- [ ] 不正形式入力時の挙動（throw か null か）をテストで固定
+
+### 2-6. マイグレーション方式の整理（PR 1 本）
+
+- [ ] `PRAGMA user_version` ベースの順次マイグレーションランナーを導入（`migrations/001-add-name.sql` … と適用済みバージョン管理）
+- [ ] 既存の try/catch ALTER TABLE 3 箇所をマイグレーションファイル化。**既存本番 DB に対して冪等であること**（適用済み列があっても壊れない初期バージョン判定）をテストで保証
+- [ ] 本番適用手順（バックアップ → デプロイ → 起動時自動適用）を `docs/VPS_SETUP.md` に追記
+
+### 2-7. 型の整理（PR 1 本）
+
+- [ ] catch 節の `error: any` を `unknown` + 型ガード（または共通の `toErrorMessage(error)`）に置換（約 23 箇所）
+- [ ] ルート・サービス内のインライン行型（`as Array<{...}>`）を `types/` の共有型に寄せる
+- [ ] `tsconfig.json` で `noImplicitAny` 等の厳格化が可能か確認し、可能なら有効化
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| エラーミドルウェア化で応答形状が変わり、フロントが壊れる | 既存ルートテストの応答アサーションを変更しないことを PR レビュー条件にする |
+| CalendarService 分割中に同期の直列化が外れて orphan イベント再発 | 各ステップで `CalendarServiceSyncSerialization.test.ts` green を必須化。委譲を挟む 3 ステップ方式で一度に動かさない |
+| マイグレーションランナーが既存本番 DB と衝突 | 「列が既に存在する DB」を再現した統合テストを先に書く。本番適用前に `scripts/backup-db.sh` 実施を手順化 |
+| モデル共通化のやり過ぎで可読性低下 | 「3 クラス以上に同型」のものだけ共通化。1 箇所でも特殊化が必要ならコピーのまま残してよい |
+
+## 完了条件（Definition of Done）
+
+- ルート層に try/catch 定型が残っていない（業務分岐の早期 return は除く）
+- `CalendarService.ts` 単体が 300 行以下、または責務別ファイルに解体済み
+- SQL がモデル層（およびマイグレーション）以外に存在しない
+- `split('-')` による time_slot 直接パースが `utils/timeSlot.ts` 以外に存在しない
+- 全テスト green、統合テスト含む
diff --git a/docs/refactoring/phase-3-frontend.md b/docs/refactoring/phase-3-frontend.md
new file mode 100644
index 0000000..293c064
--- /dev/null
+++ b/docs/refactoring/phase-3-frontend.md
@@ -0,0 +1,69 @@
+# Phase 3: フロントエンド構造の整理
+
+**ゴール**: `js/modules/` の重複・グローバル依存・API 呼び出しの不統一を解消し、最終的に ES modules へ移行する。
+
+**前提**: Phase 1 完了（フロントテストが実コードを import しており、変更を検知できる）
+
+## 背景（2026-06-11 調査）
+
+- 「モジュール」と言いつつ ES modules ではなく、`index.html:2980-3004` の `<script>` タグ 17 本の読み込み順にすべてが依存。関数・状態はグローバル空間で共有。
+- 重複関数: `timeToMinutes` が `shifts.js:581` と `shiftRequest.js:923`（NaN チェック有無で実装差あり）、`mergeShiftsByPerson` が `utils.js:226` と `calendar.js:529`、日付フォーマット関数が 4 種類分散（`utils.js` に 3 つ + `workRecords.js:49`）。
+- 状態の二重管理: `AppState` オブジェクトと `window.currentUser`（state.js:38）、`window.allShiftsData`（state.js:128）、`window.capacityData`（capacity.js:22）、`window.currentCapacityData`（shiftRequest.js:30）が混在。
+- API 呼び出し: `api.js` に 23 メソッドある一方、`auth.js:31`、`capacity.js:58`（`API.getCapacitySettings` と重複）、`capacity.js:83`、`shiftRequest.js:68`、`config.js:20`、`workRecords.js:152`、`userProfile.js:176` の 7 箇所が直接 `fetch`。
+- `index.html` にインライン `onclick` が 20 箇所。`app.js` は管理者向けカレンダー操作 3 関数 + エントリーポイントが残った状態。
+
+## 作業項目
+
+### 3-1. 重複ヘルパーの統一（PR 1 本）
+
+- [ ] `timeToMinutes` を `utils.js` に一本化（NaN チェック付きの `shiftRequest.js` 版を正とする）。両ファイルのローカル定義を削除
+- [ ] `mergeShiftsByPerson` の 2 実装を diff し、同一なら `utils.js` 版へ統一。差分があれば挙動差をテストで固定してから統一
+- [ ] 日付フォーマット 4 関数を `utils.js` に集約し、`workRecords.js:49` の独自実装を置換
+- [ ] Phase 1 のテストを実コード import に切り替えてあるため、統一後の関数にテストが追随していることを確認
+
+### 3-2. API アクセスの一元化（PR 1〜2 本)
+
+- [ ] 直接 `fetch` 7 箇所を `api.js` のメソッド呼び出しに置換（不足メソッドは `api.js` に追加）
+- [ ] `capacity.js:58` のように既存 API メソッドと重複しているものは単純置換
+- [ ] `api.js` 内のエラーハンドリング（HTTP エラー時の戻り値形状）を 1 パターンに統一し、呼び出し側の分岐を簡素化
+- [ ] 例外: `config.js:20` の初期設定取得は bootstrap 段階のため `api.js` 依存にしない判断もあり得る。判断結果をコードコメントに残す
+
+### 3-3. 状態管理の一元化（PR 1 本）
+
+- [ ] `window.*` 直接代入（4 箇所＋参照側）を `state.js` の getter/setter 経由に統一
+- [ ] `state.js` に存在しない状態（`capacityData` 等）は追加してから移行
+- [ ] 移行後、`grep -rn "window\." js/` で残存を確認（`window.location` 等の正当な利用は除く）
+
+### 3-4. インライン onclick の排除（PR 1 本）
+
+- [ ] `index.html` の `onclick` 20 箇所を `addEventListener` 登録（各モジュールの init 関数内）に移行
+- [ ] これにより関数をグローバル公開する必要がなくなり、3-5 の ES modules 化が可能になる
+
+### 3-5. ES modules への移行（PR 1〜2 本）
+
+- [ ] `js/modules/*.js` に `export` を付け、Phase 1 で入れた CommonJS ガードを削除（Jest 側は ESM 対応設定 or babel 変換に切り替え）
+- [ ] `index.html` の `<script>` タグ 17 本を `<script type="module" src="js/main.js">` 1 本に置換し、`main.js` で import 順を明示
+- [ ] `app.js` の残存関数（`syncAllShiftsToCalendar` 等の管理者カレンダー操作 3 つ）を `js/modules/adminCalendar.js` として移設し、エントリーポイント処理は `main.js` に統合。`app.js` を削除
+- [ ] 読み込み順依存が消えたことを確認（モジュール間依存はすべて import 文で表現）
+
+### 3-6. 大型モジュールの分割（PR 1 本、任意）
+
+- [ ] `shiftRequest.js`（1,044 行）を「日付詳細モーダル」「申請送信」「容量表示」に分割
+- [ ] `shifts.js`（787 行）・`calendar.js`（735 行）も同様に、表示とデータ整形を分離
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| ES modules 化はビッグバンになりやすい | 3-1〜3-4 を先に終わらせ、グローバル依存を減らした最後に 3-5 を実施。3-5 だけは 1 PR で全ファイル一括切り替え（中途半端な混在が最も危険） |
+| `onclick` → listener 移行でイベント登録漏れ | 移行対象 20 箇所をチェックリスト化し、E2E/手動スモークで全ボタンを踏む |
+| 直接 fetch の置換でエラー時の挙動が変わる | 置換前に各呼び出しのエラー分岐（alert 表示等）を確認し、`api.js` メソッドが同じ情報を返すことをテストで確認 |
+| GSI（Google Sign-In）コールバックはグローバル関数前提 | `window.handleCredentialResponse = ...` のような明示的なグローバル公開を 1 箇所だけ残し、コメントで理由を明記 |
+
+## 完了条件（Definition of Done)
+
+- 重複ヘルパー関数ゼロ（同名関数の多重定義が grep で検出されない）
+- `api.js` 以外に `fetch(` が存在しない（許容した例外を除く）
+- `<script>` タグが GSI + エントリーポイントのみ
+- `app.js` が削除されている
+- 全テスト green、全ボタンの手動スモーク済み
diff --git a/docs/refactoring/phase-4-css-html.md b/docs/refactoring/phase-4-css-html.md
new file mode 100644
index 0000000..62f370e
--- /dev/null
+++ b/docs/refactoring/phase-4-css-html.md
@@ -0,0 +1,50 @@
+# Phase 4: CSS / HTML の整理
+
+**ゴール**: `index.html` から CSS を外部化・重複排除し、HTML を見通せるサイズに戻す。
+
+**前提**: Phase 0 完了。Phase 3 と並行可能（ただし同じ箇所を触る PR が重ならないよう調整）
+
+## 背景（2026-06-11 調査）
+
+- `index.html` 3,005 行のうち約 2,700 行（約 9 割）が `<style>` ブロック。HTML 本体は約 330 行。
+- 262 個のクラス定義のうち 25 個以上が**複数回定義**されている（例: `.navbar` が行 25・162・235 の 3 箇所、`.tabs`、`.tab-button`、`.inline-time-slots` 等）。後勝ちの上書きに依存しており、どの定義が効いているか追えない。
+- メディアクエリ（768px / 900px / 1200px）がクラスごとに散在し、同一ブレークポイントのブロックが多数重複。
+- `help.html` が独立した約 265 行の埋め込み CSS を持ち、header・section・button 等の共通スタイルが二重管理。
+
+## 作業項目
+
+### 4-1. CSS の外部ファイル化（PR 1 本、機械的移動のみ）
+
+- [ ] `<style>` の中身をそのまま `css/styles.css` へ移動し、`<link rel="stylesheet">` に置換。**この PR では 1 文字も整理しない**（diff を「移動のみ」にしてレビュー可能にする）
+- [ ] ブラウザで全タブ・全モーダルの表示崩れがないことをスクリーンショット比較で確認
+
+### 4-2. 重複定義の解消（PR 1〜2 本）
+
+- [ ] 重複定義されている 25+ クラスについて、計算後の有効スタイル（カスケード結果）を確認しながら 1 定義に統合
+- [ ] 「後から上書きしている定義」が意図的な差分上書きなのか、コピペ事故なのかを 1 件ずつ判断し、事故由来の死にスタイルを削除
+- [ ] メディアクエリをブレークポイントごとに 1 ブロックへ集約（768px / 900px / 1200px の 3 ブロック）
+- [ ] 確認方法: 主要 5 画面（シフト申請・自分のシフト・シフト一覧・人数設定・勤務記録）× PC/モバイル幅のスクリーンショットを before/after 比較し、PR に添付（CLAUDE.md の PR ルール準拠）
+
+### 4-3. help.html の共通化（PR 1 本）
+
+- [ ] `help.html` の埋め込み CSS のうち `styles.css` と重複するもの（header、ボタン、レイアウト基本）を共通ファイル参照に置換
+- [ ] help 固有のスタイルだけ `css/help.css` として残す
+
+### 4-4. HTML の整理（PR 1 本、任意）
+
+- [ ] `index.html` に残った HTML（約 330 行）のうち、タブごとのセクションにコメント見出しを付与
+- [ ] 未使用 id・class（CSS からも JS からも参照されないもの）を削除（`grep` 証跡付き）
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| カスケード（後勝ち）依存の整理で見た目が静かに変わる | 4-1（移動）と 4-2（整理）を必ず別 PR にする。4-2 はスクリーンショット比較を必須化 |
+| キャッシュで旧 CSS が配信される | `styles.css?v=<hash>` 等のクエリ付与、または Express 側の Cache-Control 確認 |
+| Phase 3 の HTML 変更（onclick 排除）と衝突 | 同一週に index.html を触る PR を 1 本に制限し、着手前に相互確認 |
+
+## 完了条件（Definition of Done）
+
+- `index.html` から `<style>` ブロックが消え、500 行以下になっている
+- 同一クラスの重複定義ゼロ、メディアクエリがブレークポイント単位に集約
+- 主要 5 画面 × 2 幅のスクリーンショット比較で視覚差分なし（意図した修正を除く）
diff --git a/docs/refactoring/phase-5-e2e-ci.md b/docs/refactoring/phase-5-e2e-ci.md
new file mode 100644
index 0000000..843be8f
--- /dev/null
+++ b/docs/refactoring/phase-5-e2e-ci.md
@@ -0,0 +1,63 @@
+# Phase 5: E2E テストと CI 品質ゲート
+
+**ゴール**: リファクタリング成果を回帰から守る自動化を整備し、品質ゲート（カバレッジ・E2E）を実効性のある水準に引き上げる。
+
+**前提**: Phase 1 完了（テストが実コードを検証している）。Phase 2〜4 完了後の実施が理想だが、E2E の整備自体は Phase 2〜4 と並行可能。
+
+## 背景（2026-06-11 調査）
+
+- `e2e/` の 2 スペックは全テストが `test.skip(!process.env.E2E_TEST_ENABLED, ...)` でスキップされるスケルトン。CI にも組み込まれていない。`playwright.config.ts` の `baseURL`（8080）も実サーバーと不一致（Phase 0 で修正済みの想定）。
+- `jest.config.ts` のカバレッジ閾値はフロント statements 3% / branches 1% / functions 0%。フロントは `collectCoverageFrom: []` で計測対象すら空（Phase 1 で計測開始済みの想定）。
+- `.github/workflows/test.yml` の backend-tests は `|| echo` で失敗を握りつぶしていた（Phase 0 で修正済みの想定）。codecov の目標値も 1% と形骸化。
+- E2E がないため、フロントの DOM 操作系（モーダル・タブ切り替え・申請フロー）はリリース前の手動確認に依存している。
+
+## 作業項目
+
+### 5-1. E2E の土台整備（PR 1 本）
+
+- [ ] テスト用のシード戦略を決める: テスト起動時に一時 SQLite（専用 `DATABASE_PATH`）を作成し、シードデータを投入するグローバルセットアップを実装
+- [ ] 認証: `devLogin.js`（開発用ログイン）を E2E から利用できるようにする。本番ビルドに影響しないことを確認
+- [ ] Google Calendar 連携はテスト時に無効化（環境変数未設定なら同期スキップ、または getCalendarClient のスタブ化）し、外部 API に依存しない構成にする
+- [ ] `test.skip` ガードを撤去し、ローカルで `npx playwright test` が素で通る状態にする
+
+### 5-2. 主要フローの E2E 実装（PR 2〜3 本）
+
+優先度順:
+
+- [ ] **シフト申請フロー**: ログイン → 日付選択 → 時間枠選択 → 申請 → 自分のシフトに表示される
+- [ ] **申請キャンセル**: 申請済みシフトの削除 → 一覧から消える → 残り枠が戻る
+- [ ] **特別シフト**: 管理者が特別シフト作成 → 一般ユーザーが 30 分スロット申請 → 一覧表示
+- [ ] **人数設定（管理者）**: 容量変更 → 残り枠表示への即時反映
+- [ ] Phase 1 で「E2E でカバーする」と判断して削除した DOM 系テストの対象がすべて含まれているか、`test-inventory.md` と突き合わせて確認
+
+### 5-3. CI への組み込み（PR 1 本）
+
+- [ ] `.github/workflows/test.yml` に E2E ジョブを追加（Playwright 公式 action、失敗時に trace/screenshot をアーティファクト保存）
+- [ ] E2E は `pull_request` 時に必須チェック化（実行時間が 5 分を超えるようなら main マージ時のみに調整）
+
+### 5-4. カバレッジ閾値の実効化（PR 1 本）
+
+- [ ] 現状のカバレッジ実測値を確認し、「実測値 − 数 %」を新しい閾値として設定（落ちたら即 fail する、形骸化しない値にする）
+  - 目安: バックエンドは現状 95% 設定を維持、フロントは Phase 1〜3 完了後の実測に基づき 60% 以上を目標
+- [ ] `codecov.yml` の target 1% を実測ベースに引き上げ、`patch` カバレッジ（新規変更行）も設定
+- [ ] 以後、閾値はフェーズ完了ごとに実測へ追随させる運用を CLAUDE.md に明記
+
+### 5-5. 仕上げ（PR 1 本）
+
+- [ ] `docs/TESTING.md` を更新: テスト 3 層（unit / integration / E2E）の役割分担、ローカル実行方法、シード戦略
+- [ ] この `docs/refactoring/` 全体の完了状況を README.md の進捗表に反映し、残課題（やらないと決めたことを含む）を `docs/refactoring/leftovers.md` に記録
+
+## リスクと対策
+
+| リスク | 対策 |
+|--------|------|
+| E2E がフレーキーで CI を阻害する | リトライ 1 回 + trace 保存を設定。フレーキーなテストは即 quarantine（skip + issue 化）するルールを決めておく |
+| dev ログインを E2E に使うことで本番に穴が開く | devLogin の有効化条件（NODE_ENV / 環境変数）を確認し、E2E 用フラグが本番で立たないことをテストで保証 |
+| カバレッジ閾値を上げすぎて開発が止まる | 「実測 − 数 %」ルールを厳守。理想値ではなく現実の床として運用 |
+
+## 完了条件（Definition of Done）
+
+- 主要 4 フローの E2E が CI で毎 PR 実行され、green
+- カバレッジ閾値が実測ベースで、下回ると CI が fail する
+- `docs/TESTING.md` が 3 層構成を反映している
+- リファクタリング全体の完了宣言と残課題リストが残っている