TOKIWA — 要件定義書 兼 Claude Code 実装指示書

版数 1.0（DBレス構成 / 記事埋め込み型デモ）／ 作成日 2026-08-24 ／ 発行 ソウゾウ合同会社 用途 SEO記事「【デモで試せる】Claude Codeで勤怠・シフト管理システムを自作する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

このドキュメントの使い方（Claude Code へ）

これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。

• 実装は「12. 実装タスク」の順に進める。フェーズを飛ばさない。
• 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
• 仕様がここに書かれていない場合は、推測で実装せず質問する。
• スコープ外（3章 Won't have）は、思いついても実装しない。
• 「デモだから」を理由に品質を落とす判断はしない。
• この領域だけの特別ルール：計算ロジックを推測で書かない。 割増賃金・休憩・36協定の判定は法令に基づく。仕様が曖昧なまま実装すると、動くが違法な計算が生まれる。曖昧なら必ず質問する（1章）。

姉妹プロジェクトとの関係 HIREBASE（求人）／ RELATE（顧客管理）／ CASTA（動画配信）／ FIELDPIN（位置情報）／ KANADE（音楽）／ MIWAKE（画像認識）／ KAMIWAZA（美容室予約）／ KURA（在庫管理）に続くシリーズ。並べて「同じテンプレ」と思われた時点で失敗。 **特に RELATE / KURA との差別化に注意。**3本とも「白背景・高密度・業務システム」だが、 RELATE＝罫線と等幅数字で表を読ませる（藍）／ KURA＝各行に在庫の水位バーを描く（ティール＋アンバー・縦長数字）／ TOKIWA＝1日を24時間の帯として横に描く。時間の重なりが図で見える（インディゴ＋コーラル・等幅数字＋大きな時刻表示）。 8章のデザイン要件は意図的に別方向に振っている。トークンを流用しないこと。

目次

1. プロジェクト概要
2. アーキテクチャ方針
3. スコープ定義
4. ロールとデモ切替
5. 画面一覧とユーザーフロー
6. 機能要件
7. データ設計
8. デザイン要件
9. 技術要件・ディレクトリ構成
10. 非機能要件・法令
11. 費用設計
12. 実装タスク
13. 受入基準

1. プロジェクト概要

背景と目的

「勤怠・シフト管理を作りたい」という相談の背景は、ほぼ次のいずれか。

• タイムカードとExcelで運用しており、月末の集計に何日もかかる
• シフトをLINEで調整していて、希望の取りまとめと確定の連絡が毎月地獄
• 残業時間の把握が月末までできず、気づいたら上限を超えていた

そして、この領域には他のどのテーマにもない特殊性が3つある。

特殊性①：間違えると法令違反になる

在庫が1個ズレても事故だが、労働時間の計算がズレると未払賃金・36協定違反になる。しかも従業員全員に影響し、遡って修正が必要になる。

勤怠システムは「動けばいい」が最も通用しない領域。 割増賃金の計算式、休憩の付与義務、時間外の上限——これらは設計者の裁量ではなく法令で決まっている。

そして厄介なのは、画面上は正しく動いているように見えること。だから計算ロジックは純粋関数として切り出し、テストで固める。それがこのプロジェクトの中核（2章）。

特殊性②：「打刻」は生データ。「勤務時間」は解釈

打刻を集計すれば勤務時間になる——ならない。間に大量の解釈が挟まる。

打刻（生データ）  9:03 出勤 / 12:01 休憩開始 / 12:58 休憩終了 / 19:47 退勤
        ↓ ①丸め（15分単位？切り捨て？切り上げ？→ 切り捨ては違法になりうる）
        ↓ ②所定労働時間との突き合わせ（9:00-18:00 / 休憩60分）
        ↓ ③休憩の実績と法定休憩の充足チェック
        ↓ ④遅刻・早退の判定
        ↓ ⑤法定内残業と法定外残業の切り分け
        ↓ ⑥深夜（22:00-5:00）の抽出
        ↓ ⑦休日労働（法定休日／所定休日）の判定
        ↓ ⑧割増率の適用と重複（深夜×休日 等）
勤務時間（解釈済み）  所定8h / 法定外残業1.75h / 深夜0h / 休憩57分（法定60分に3分不足）

この①〜⑧のどれか1つを間違えると、給与が変わる。 そして各社で①②⑦のルールが違う。だから設定で切り替えられる構造にしなければならない。

特殊性③：シフトと勤怠は別物だが、繋がっている

多くの失敗は「シフト＝勤怠」と考えて作ること。 シフト通りに働くことは稀で、予定と実績の差分こそが管理対象。TOKIWA はこの2つを別のデータとして持ち、常に並べて見せる。

TOKIWA はこの3つの特殊性を前提に設計する。

プロダクト定義

プロダクトコンセプト

「打刻を書き換えない。解釈を見せる。」

TOKIWA は打刻の生データを一切変更しない。丸めも、残業区分も、割増も、すべて生データからの算出結果として提示する。だから「なぜこの時間になったか」が常に遡れ、設定を変えれば即座に再計算される。

デモとしての成功条件

1. 打刻と解釈が分かれて見える — 生の打刻と、丸め後・区分後の時間が同じ画面に並んでいる
2. 設定を変えると計算が変わる — 丸め単位を「1分」から「15分切り捨て」に変えると、残業時間と割増額が変わる
3. 法令の警告が出る — 法定休憩の不足、36協定の上限接近が具体的な数字で警告される
4. シフトと実績が並ぶ — 予定と実績の差分が1画面で分かる
5. ロールで見え方が変わる — 従業員は自分だけ、管理者はチーム全体。給与額は管理者のみ
6. リセットできる — 誰が触った後でも初期状態に戻せる

2. アーキテクチャ方針

基本方針

バックエンドとデータベースを持たない。すべてブラウザ内で完結させる。

なぜこの構成にするか

• LPデモとして最適 — 訪問者は登録もログインもせずに、全機能を即座に触れる
• 打刻データが外に出ない — 労働時間は従業員の個人情報。データを預からないことが訴求になる
• 開発速度 — 認証・APIの実装が不要になり、計算ロジックとUIの作り込みに全時間を投下できる
• 運用コストゼロ — Vercel の静的配信のみ

計算エンジンの原則（最重要の設計判断）

打刻を書き換えない。すべて生データからの算出結果として持つ。

[ 生打刻 ]  ← 絶対に変更しない（訂正は「訂正申請＋承認」の別レコード）
    ↓
[ 丸め ]           丸め単位・方向を設定で切替
    ↓
[ 休憩の突き合わせ ]  実績休憩 vs 法定休憩の充足判定
    ↓
[ 所定との比較 ]     遅刻・早退・所定内労働
    ↓
[ 残業の区分 ]      法定内残業 / 法定外残業
    ↓
[ 時間帯の抽出 ]    深夜（22:00-5:00）／休日（法定／所定）
    ↓
[ 割増の適用 ]      率の重複を正しく合成
    ↓
[ 日次サマリ ] → [ 月次集計 ] → [ 36協定チェック ]

この設計が、記事の技術パートの中核になる。 「打刻を丸めて保存する」設計との違いを説明できることが専門性になる。

差し替え可能性の担保

データアクセスは必ず lib/repo/ のリポジトリ層を経由すること。 コンポーネントからストアを直接触らない。

[ コンポーネント ]
        ↓  呼ぶのはこの層だけ
[ lib/repo/*.ts ]     ← 全メソッドを async にしておく
        ↓
[ lib/attendance/ ]   ← 労働時間の算出（純粋関数）
[ lib/shift/ ]        ← シフト生成・充足判定（純粋関数）
[ lib/store/*.ts ]    ← Zustand + persist（localStorage）
        ↓
[ lib/seed/*.ts ]     ← 初期データ

リポジトリの各メソッドは、中身が同期処理でも async で定義し、await で呼ぶ。実案件へ転用する際、リポジトリの実装だけをAPI呼び出しに差し替えれば、UI層は一行も変更せずに済む。

記事への組み込み

記事内で見せるのは「設定を変えると計算結果が変わること」だけに絞る。 これが1章の特殊性②そのものであり、スクロール中に一目で伝わる唯一の絵になる。

永続化の範囲

擬似ディレイ は 150〜400ms。ただし打刻・労働時間の再算出・一覧の絞り込みは 100ms以下とし、ディレイを入れない（打刻でもたつくのは致命的な体験）。

3. スコープ定義

打刻・勤怠（従業員）

シフト（従業員）

シフト作成・勤怠管理（管理者）

共通・基盤

対象外（Won't have）

スコープリスク： 勤怠は「うちの就業規則がこうで」が最も多い領域。変形労働時間制・フレックス・みなし残業（固定残業代）・深夜割増の重複・法定休日の特定方法・週40時間の起算曜日は会社ごとに違い、計算の根幹に影響する。後付けは全期間の再計算になるため、要件定義の段階で必ず洗い出す。資料PDFの「就業規則ヒアリングシート」はこの洗い出しのために作る。

4. ロールとデモ切替

ロール設計は、そのまま実案件での権限制御の設計根拠になる。勤怠は個人情報と給与情報を扱うため、権限設計を誤ると事故になる。

ロール定義

データスコープと項目スコープ（デモの見せ場）

勤怠では「見える行」だけでなく「見える列」が権限で厳格に分かれる。 他人の給与額が見えるのは重大な事故。

• 従業員で勤務一覧 → 自分の1ヶ月分のみ。時給・給与額は自分の分だけ
• 管理者に切替 → 自部署8名。時給と人件費が出現する（他部署は見えない）
• 管理部に切替 → 全社42名。就業規則設定と給与CSV出力が出現する

ロールを跨ぐ体験（必ず動くようにする）

1. 従業員で打刻する → 管理者に切替 → 日次の勤務状況にその打刻が反映され、予実比較の実績が動く
2. 管理部が丸め設定を「1分」→「15分切り捨て」に変える → 従業員に切替 → 同じ打刻なのに勤務時間と残業が減っている（過去分も再計算される）
3. 従業員が打刻訂正を申請 → 管理者に切替 → 承認待ちに出る。承認するまで勤務時間は変わらない → 承認 → 勤務時間が訂正後で再計算される
4. 管理者がシフトを組む → 必要人数の不足が赤で表示され、人件費の見込みが更新される → 公開 → 従業員に切替 → 自分のシフトに反映されている
5. 従業員が残業を積む → 管理部に切替 → 36協定モニタリングでその人の残り時間が減り、上限接近が警告される
6. 管理部が月次を確定する → 従業員に切替 → その月の打刻が編集不可（ロック）になっている

2番と3番が、このデモの核心。 1章の特殊性②が体験として成立する瞬間。

デモ切替バー（F-C01）

画面上部に常時表示する固定バー。埋め込みモードでは非表示。

• 現在のロールと氏名・部署の表示、3ロールの切替
• 従業員ロール時：3名から操作主体を選択（残業が多い人／有給未取得の人／新人 を用意）
• デモ内の現在日時（シードが相対日付のため基準を示す）
• 「デモをリセット」ボタン（確認ダイアログ付き）
• 元記事へ戻るリンク
• 「これはデモです。打刻データは送信されません」の明示

デザイン上の扱い： プロダクト本体のUIとは意図的に別扱い（ダークな帯 + 小さめのタイポ）にし、「アプリの外側にある操作パネル」であることを視覚的に区別する。

5. 画面一覧とユーザーフロー

全34画面。画面IDはディレクトリ構成と 1:1 で対応させる。

従業員側

管理者側

管理部（HR）

主要フロー

フローA：記事の読者が「打刻と解釈の違い」を理解する（最重要）

SEO記事を読んでいる
   ↓
記事内の埋め込み（SC-900）
┌──────────────────────────────────────────────────────────┐
│ 2026-08-20（木）  田中さんの1日                            │
│                                                          │
│  0    6      9        12      15      18       21    24   │
│  ├────┼──────┼────────┼───────┼───────┼────────┼─────┤   │
│         ●9:03━━━━━━━━━━▓▓━━━━━━━━━━━━━━━━━━━━●19:47      │
│                     休憩57分                              │
│                                                          │
│  丸め設定  [ 1分単位 ▼ ]                                  │
│                                                          │
│  ┌── 生打刻 ──────────┐  ┌── 解釈後 ──────────────┐      │
│  │ 出勤  9:03          │  │ 所定内      8:00      │      │
│  │ 休憩 12:01-12:58    │  │ 法定外残業  1:47      │      │
│  │ 退勤 19:47          │  │ 深夜        0:00      │      │
│  │ 実働 9:47           │  │ 休憩不足    3分 ⚠     │      │
│  └────────────────────┘  └───────────────────────┘      │
│                                                          │
│  当日の割増賃金相当  ¥2,900                               │
└──────────────────────────────────────────────────────────┘
   ↓
丸め設定を「1分単位」→「15分単位・切り捨て」に変える
   ↓  ★ 同じ打刻なのに、法定外残業が 1:47 → 1:30 に減る
   ★ 割増賃金相当が ¥2,900 → ¥2,450 に減る
   ★ 同時に注意が出る：「切り捨ての丸めは、実労働時間の一部を
      賃金計算から除外することになり、適法性に注意が必要です」
   ↓
「休憩不足 3分 ⚠」にホバー
   ↓  ★「8時間超の労働には60分以上の休憩が必要です（実績57分）」
   ↓
「全画面で試す」→ 別タブ
   ↓
SC-011 勤務日詳細 ── ★ 計算の根拠が全ステップ表示される
   ↓
ロール切替「管理部」→ SC-204 就業規則の設定
   ↓  ★ 丸め単位を変えると、SC-210 で全サンプルの計算結果が変わる
SC-202 36協定モニタリング ── ★ 上限接近者が具体的な残り時間で表示される
   ↓
資料ダウンロード or 元記事に戻る

フローB：打刻訂正の申請と承認（1章の特殊性②の実装を見せる）

【従業員】SC-010 月次勤務一覧
  8月18日：退勤打刻がない（打刻忘れ）→ 行が警告色
   ↓
SC-012 打刻訂正申請
  退勤時刻を「19:30」で申請、理由：「打刻忘れ」
   ↓  ★ 差分プレビューが出る
     現在：退勤なし → 勤務時間 算出不能
     訂正後：退勤 19:30 → 所定内 8:00 / 法定外残業 1:30
   ↓
申請
   ↓  ★ 生打刻は一切変更されていない（PunchCorrection として別レコード）
【管理者】SC-130 打刻訂正の承認
  申請一覧に出る
  ★ 訂正前後の差分と、再計算後の勤務時間が並んで表示される
  ★ 承認するまで勤務時間は変わらない
   ↓
承認
   ↓
【従業員】SC-011 勤務日詳細
  ★ 勤務時間が訂正後で再計算されている
  ★ 「打刻タイムライン」に、生打刻（点線）と訂正後（実線）の両方が描かれる
  ★ 「訂正あり（8/19 管理者が承認）」のバッジが付く
   ↓
【管理部】SC-209 操作ログ
  ★ 誰がいつ何を訂正・承認したかが記録されている
   ↓
★ ここで伝わること：
  「打刻は消さない。訂正は履歴として残す。だから後から検証できる」

フローC：シフトを組んで、実績と比べる

【管理者】SC-112 必要人数の設定
  金曜 17:00-22:00 は 4名必要、平日昼は 2名
   ↓
SC-116 シフト希望の集計 ── 提出8名／未提出2名（催促の通知プレビュー）
   ↓
SC-113 シフト自動生成
  制約：希望・必要人数・スキル（レジ可）・法令（週40h、連続勤務日数）
  ↓  ★ 生成される。ただし「下書き」
  ★ 採用しなかった理由が出る：
    「8/22(金) 17-22時：1名不足。希望提出者の中に配置可能な人がいません」
   ↓
SC-110 シフト表 ── ドラッグで手修正
  ★ 必要人数を満たすと緑、不足すると赤で表示される
  ★ 法令違反になる割当は弾かれる（週40h超、連続7日勤務）
   ↓
SC-111 時間帯別の充足 ── ★ 横軸=時間のヒートマップで穴が一目で分かる
   ↓
SC-114 人件費の見込み
  ★ このシフトだと ¥842,000（予算 ¥800,000 に対し +5.3%）
  ★ 深夜割増が効いている日が強調される
   ↓
SC-115 公開 ── 通知プレビューを確認して公開
   ↓
【従業員】SC-041 確定シフト ── ★ 自分のシフトに反映されている
   ↓
（数日後）実際に働いて打刻が積まれる
   ↓
【管理者】SC-121 予実比較
  ★ シフト（予定）と打刻（実績）が並ぶ
    8/22(金)  予定 17:00-22:00（5.0h） / 実績 16:52-22:34（5.5h）
    → 予定より +0.5h、人件費 予実差 +¥1,200
  ★ 月間：予定 ¥842,000 → 実績 ¥871,300（+3.5%）
   ↓
★ ここで伝わること：
  「シフトは予定、打刻は実績。差分こそが管理対象」

6. 機能要件

各要件はテスト仕様書の項目と1:1で対応する。「〜できること」の粒度で、判定可能な形で記述している。

6.1 労働時間の算出（このデモの心臓部）

6.2 打刻

6.3 訂正・申請・承認

6.4 シフト作成

6.5 シフト希望・交代

6.6 集計・法令モニタリング

6.7 設定・マスタ

6.8 一覧・デモ基盤

7. データ設計

型定義（lib/types/）

// ---- 組織・従業員 ----
type Org = { id: string; name: string; kind: 'department' | 'site'; parentId?: string }

type EmploymentType = 'full_time' | 'part_time' | 'contract' | 'arbeit'
type WageType = 'monthly' | 'hourly'

type Employee = {
  id: string
  code: string
  name: string                  // ★ 架空
  orgId: string
  role: 'employee' | 'manager' | 'hr'
  employmentType: EmploymentType
  joinedAt: string
  // --- 所定労働（★ 法定内/法定外の切り分けに使う）---
  scheduledStartMin: number     // 540 = 9:00
  scheduledEndMin: number       // 1080 = 18:00
  scheduledBreakMin: number     // 60
  scheduledWorkDays: number[]   // [1,2,3,4,5]
  // --- 賃金（★ 権限で出し入れする項目。SCP-03）---
  wageType: WageType
  hourlyWage?: number
  monthlySalary?: number
  // --- シフト ---
  skills: string[]              // 'レジ' 'キッチン' '夜勤可'
  maxWorkDaysPerMonth?: number
  color: string                 // シフト表の識別色
  isActive: boolean
}

// ---- ★★★ 打刻（生データ。絶対に書き換えない）★★★ ----
type PunchKind = 'clock_in' | 'break_start' | 'break_end' | 'clock_out'

type Punch = {
  id: string
  seq: number                   // ★ メモ化の世代管理（CAL-04）
  employeeId: string
  workDate: string              // ★ 労働日の帰属（日跨ぎは始業日に帰属。FR-116）
  kind: PunchKind
  atMin: number                 // ★ workDate の 0:00 からの分数。24:00超で日跨ぎ表現（CAL-05）
  // --- 記録の状況 ---
  device: 'web' | 'mobile' | 'offline_sync'
  coord?: { lat: number; lng: number; accuracyM: number }
  isOutOfRange?: boolean        // 位置が範囲外（FR-207）
  recordedAt: string            // 実際に記録された時刻（ISO）
  cancelledAt?: string          // 直後の自己取消（FR-204）
  syncState: 'synced' | 'pending'
}

// ---- ★ 訂正（打刻を書き換えず、別レコードで持つ。CAL-01）----
type PunchCorrection = {
  id: string
  employeeId: string
  workDate: string
  // --- 訂正内容 ---
  targetPunchId?: string        // 既存打刻の訂正。未指定なら新規追加
  kind: PunchKind
  fromAtMin?: number            // 訂正前（新規追加なら undefined）
  toAtMin: number               // 訂正後
  isDeletion: boolean           // 打刻の取消
  // --- 申請・承認 ---
  reasonCode: 'forgot' | 'mistake' | 'system' | 'other'
  reason: string
  status: 'pending' | 'approved' | 'rejected'
  requestedBy: string
  requestedAt: string
  reviewedBy?: string
  reviewedAt?: string
  rejectReason?: string
}

// ---- 就業規則（★ バージョン管理。FR-702）----
type WorkRule = {
  id: string
  version: number
  effectiveFrom: string         // ★ 適用開始日
  name: string
  // --- 丸め（FR-103）---
  rounding: {
    unitMin: 1 | 5 | 10 | 15 | 30
    inDirection: 'none' | 'up' | 'down' | 'nearest'
    outDirection: 'none' | 'up' | 'down' | 'nearest'
  }
  // --- 法定労働時間 ---
  legalDailyMin: number         // 480 = 8h
  legalWeeklyMin: number        // 2400 = 40h
  weekStartsOn: number          // 週の起算曜日（0=日）
  // --- 休憩（FR-106, FR-107）---
  breakRules: { overWorkMin: number; requiredBreakMin: number }[]  // [{360,45},{480,60}]
  autoDeductScheduledBreak: boolean   // 休憩未打刻時に所定休憩を控除するか
  // --- 深夜 ---
  nightStartMin: number         // 1320 = 22:00
  nightEndMin: number           // 300 = 5:00（翌日）
  // --- 割増率（FR-113）---
  premiums: {
    overtime: number            // 法定外残業（法定下限 0.25）
    overtimeOver60h: number     // 月60時間超（法定下限 0.50）
    night: number               // 深夜（法定下限 0.25）
    legalHoliday: number        // 法定休日（法定下限 0.35）
    scheduledHoliday: number    // 所定休日（法定外。時間外として扱う）
  }
  // --- 変形労働（FR-115）---
  flexibleMonthly: { enabled: boolean; periodStartDay: number; totalFrameMin?: number }
  // --- 日跨ぎ ---
  overnightAttribution: 'start_date' | 'end_date'
}

type HolidayCalendar = {
  year: number
  legalHolidayWeekday?: number  // 法定休日を曜日で特定する場合
  dates: { date: string; kind: 'legal_holiday' | 'scheduled_holiday' | 'national_holiday'; name: string }[]
}

// ---- ★ 日次サマリ（保存しない。常に算出）----
type DailySummary = {
  employeeId: string
  workDate: string
  dayType: 'workday' | 'legal_holiday' | 'scheduled_holiday'
  // --- 生打刻（丸め前）---
  rawPunches: { kind: PunchKind; atMin: number }[]
  rawWorkMin: number
  rawBreakMin: number
  // --- 丸め後 ---
  roundedInMin?: number
  roundedOutMin?: number
  // --- 区分ごとの時間（★ ここが給与に直結）---
  scheduledWorkMin: number      // 所定内労働
  legalInsideOtMin: number      // 法定内残業（所定超〜法定内）
  legalOutsideOtMin: number     // 法定外残業（法定超）
  over60hOtMin: number          // 月60時間超の部分
  nightMin: number              // 深夜
  legalHolidayMin: number       // 法定休日労働
  scheduledHolidayMin: number   // 所定休日労働
  lateMin: number               // 遅刻
  earlyLeaveMin: number         // 早退
  breakActualMin: number
  breakRequiredMin: number
  breakShortageMin: number      // ★ 法定休憩の不足（FR-106）
  // --- 休暇 ---
  leaveKind?: LeaveKind
  leaveUnit?: 'full' | 'half' | 'hourly'
  leaveHours?: number
  // --- 金額（★ 権限がない場合は含めない。SCP-03）---
  basePay?: number
  premiumPay?: number
  totalPay?: number
  // --- ★ 計算の根拠（CAL-06, FR-117）---
  breakdown: CalcBreakdown
  // --- 状態 ---
  hasCorrection: boolean
  anomalies: Anomaly[]
  isLocked: boolean             // 月次確定済み
}

type CalcBreakdown = {
  appliedRuleVersion: number
  steps: {
    step: 'rounding' | 'break_check' | 'scheduled_compare' | 'ot_split'
        | 'night_extract' | 'holiday_judge' | 'premium_apply' | 'weekly_40h'
    input: string               // 人が読める入力の説明
    output: string              // 人が読める結果
    note?: string               // 適用した設定・根拠
  }[]
  appliedPremiums: { kind: string; rate: number; minutes: number; amount?: number }[]
}

type Anomaly = {
  kind: 'missing_punch' | 'no_clock_out' | 'break_shortage' | 'over_limit'
      | 'out_of_range' | 'pending_correction' | 'late' | 'early_leave'
  severity: 'info' | 'warn' | 'error'
  message: string
}

// ---- 月次集計（算出値）----
type MonthlySummary = {
  employeeId: string
  yearMonth: string             // '2026-08'
  workDays: number
  totalWorkMin: number
  scheduledWorkMin: number
  legalInsideOtMin: number
  legalOutsideOtMin: number
  nightMin: number
  legalHolidayMin: number
  scheduledHolidayMin: number
  lateMin: number
  earlyLeaveMin: number
  paidLeaveDays: number
  absenceDays: number
  // --- 金額（権限依存）---
  basePay?: number
  premiumPay?: number
  totalPay?: number
  // --- 状態 ---
  anomalyCount: number
  pendingApprovals: number
  status: 'open' | 'confirmed'
  confirmedBy?: string
  confirmedAt?: string
}

// ---- 36協定（算出値。FR-605）----
type ComplianceStatus = {
  employeeId: string
  yearMonth: string
  monthlyOtMin: number          // 当月の時間外（法定外＋休日）
  monthlyLimitMin: number       // 45h = 2700
  yearlyOtMin: number           // 年度累計
  yearlyLimitMin: number        // 360h = 21600
  multiMonthAvgMin: number      // 直近2〜6ヶ月の平均
  multiMonthLimitMin: number    // 80h = 4800
  singleMonthLimitMin: number   // 100h = 6000
  specialClauseUsedCount: number // 特別条項の適用回数（年6回）
  alerts: { kind: string; usageRatio: number; remainingMin: number; severity: 'warn' | 'error' }[]
}

// ---- 休暇 ----
type LeaveKind = 'paid' | 'special' | 'absence' | 'compensatory'
type LeaveRequest = {
  id: string
  employeeId: string
  kind: LeaveKind
  unit: 'full' | 'half_am' | 'half_pm' | 'hourly'
  dates: string[]
  hours?: number
  reason: string
  status: 'pending' | 'approved' | 'rejected'
  requestedAt: string
  reviewedBy?: string
  reviewedAt?: string
}
type PaidLeaveGrant = {
  id: string
  employeeId: string
  grantedAt: string
  days: number
  expiresAt: string             // ★ 失効予定（FR-609）
  usedDays: number
  usedHours: number             // 時間単位有給
}

// ---- シフト ----
type ShiftPattern = {
  id: string
  name: string                  // 早番 / 遅番 / 夜勤 / 休
  startMin: number
  endMin: number                // 24:00超で日跨ぎ
  breakMin: number
  color: string
  requiredSkills: string[]
  isDayOff: boolean
}
type ShiftAssignment = {
  id: string
  employeeId: string
  date: string
  patternId: string
  startMin?: number             // パターンから変更する場合
  endMin?: number
  status: 'draft' | 'published'
  createdVia: 'manual' | 'auto_generated' | 'swap'
  note: string
}
type ShiftRequest = {            // 従業員の希望（FR-501）
  id: string
  employeeId: string
  periodId: string
  entries: { date: string; availability: 'available' | 'unavailable' | 'partial'; fromMin?: number; toMin?: number }[]
  maxWorkDays?: number
  submittedAt?: string
}
type ShiftPeriod = {
  id: string
  yearMonth: string
  requestDeadline: string       // ★ 希望提出の締切
  status: 'collecting' | 'drafting' | 'published'
  publishedAt?: string
}
type StaffingDemand = {          // 必要人数（FR-403）
  id: string
  orgId: string
  weekday: number
  fromMin: number
  toMin: number
  requiredCount: number
  requiredSkills: string[]
}
type SwapRequest = {
  id: string
  fromEmployeeId: string
  toEmployeeId: string
  assignmentId: string
  status: 'pending_peer' | 'pending_manager' | 'approved' | 'rejected'
  requestedAt: string
}

// ---- 監査・通知 ----
type AuditLog = {
  id: string
  actorId: string
  action: 'approve_correction' | 'reject_correction' | 'confirm_month' | 'unconfirm_month'
        | 'update_work_rule' | 'publish_shift' | 'approve_leave' | 'export_csv'
  targetType: string
  targetId: string
  changes: { field: string; before: unknown; after: unknown }[]
  createdAt: string
}
type Notification = {
  id: string
  targetEmployeeId: string
  kind: 'shift_published' | 'shift_changed' | 'approval_result' | 'punch_forgotten'
      | 'limit_approaching' | 'request_deadline'
  title: string
  body: string
  emailPreview?: { subject: string; body: string }   // ★ 送信しない。プレビューのみ
  readAt?: string
  createdAt: string
}

労働時間算出の実装（7章の中核）

// lib/attendance/daily.ts
export function calcDaily(input: DailyCalcInput): DailySummary {
  const { employee, workDate, punches, corrections, rule, calendar } = input
  const steps: CalcBreakdown['steps'] = []

  // ① 訂正を適用した「有効な打刻列」を作る（★ 生打刻は変更しない。CAL-01）
  const effective = applyCorrections(punches, corrections.filter(c => c.status === 'approved'))

  // ② 丸め（FR-103）
  const { inMin, outMin } = applyRounding(effective, rule.rounding)
  steps.push({
    step: 'rounding',
    input: `出勤 ${fmt(rawIn)} / 退勤 ${fmt(rawOut)}`,
    output: `出勤 ${fmt(inMin)} / 退勤 ${fmt(outMin)}`,
    note: `${rule.rounding.unitMin}分単位・出勤${dirLabel(rule.rounding.inDirection)}・退勤${dirLabel(rule.rounding.outDirection)}`,
  })

  // ③ 休憩の充足判定（FR-106）
  const grossMin = outMin - inMin
  const breakActual = sumBreaks(effective)
  const breakRequired = requiredBreak(grossMin - breakActual, rule.breakRules)
  const breakShortage = Math.max(0, breakRequired - breakActual)
  steps.push({
    step: 'break_check',
    input: `実働見込 ${fmtMin(grossMin - breakActual)} / 休憩実績 ${breakActual}分`,
    output: breakShortage > 0 ? `不足 ${breakShortage}分` : '充足',
    note: `労働${breakRequired === 60 ? '8時間超' : '6時間超'}のため${breakRequired}分以上が必要`,
  })

  // ④ 休日判定（FR-111）→ ⑤ 所定との比較 → ⑥ 残業区分（FR-109）
  //   → ⑦ 深夜抽出（FR-110）→ ⑧ 週40h（FR-114）→ ⑨ 割増合成（FR-112）
  //   ※ 各ステップで steps.push() し、根拠を必ず残す（CAL-06）

  return { /* ... */ breakdown: { appliedRuleVersion: rule.version, steps, appliedPremiums } }
}

シードデータ（lib/seed/）

シード作成のルール（品質を左右する）

• 実在企業名・実在人名を使わない。 架空の従業員名・店舗名で構成する
• 氏名を「従業員A」のようなダミーにしない。 実在しそうな架空名にする。ここが手抜きだとデモ全体が安っぽくなる
• 打刻を「9:00 きっかり」にしない。 9:03、8:57、19:47 のように丸めが意味を持つ端数を持たせる。これが最重要
• 休憩不足の日を作る（実働8時間超で休憩57分など）。法定休憩の警告が動いて見えること
• 退勤打刻がない日を1〜2件作る（打刻忘れの検出とフローBの実演用）
• 深夜勤務・日跨ぎ勤務を含める（夜勤者を数名、22:00超の退勤を複数）
• 法定休日・所定休日に出勤している日を作る（休日割増が計算に出ること）
• 36協定の上限に接近している人を2名、超えそうな人を1名作る。 全員余裕だとモニタリングが動いて見えない
• 有給の年5日未達者を3名、失効間近の人を1名作る
• シフトの予定と実績にズレを持たせる（予定17:00-22:00 → 実績16:52-22:34 等）。予実比較が意味を持つこと
• 必要人数が不足している日を数日作る（シフト表の赤表示とフローCの実演用）
• 就業規則のバージョンを2つ持ち、3ヶ月前に丸め設定が変わった状態にする（FR-702 の実演用）
• 日付は現在日時からの相対で生成する。固定日付を埋め込まない
• 打刻列は時系列に矛盾がないこと（休憩終了が休憩開始より前にならない、等）

ストアとリポジトリ

lib/
├── types/  seed/
├── attendance/                 # ★ 労働時間の算出。純粋関数のみ
│   ├── daily.ts                # ★ 日次サマリ（7章のコード参照）
│   ├── rounding.ts             # 丸め（FR-103, FR-105）
│   ├── breaks.ts               # 法定休憩の充足（FR-106, FR-107）
│   ├── overtime.ts             # 法定内/法定外の切り分け、週40h（FR-109, FR-114）
│   ├── night.ts                # 深夜の抽出（FR-110）
│   ├── holiday.ts             # 休日判定（FR-111）
│   ├── premium.ts              # 割増率の合成（FR-112）
│   ├── flexible.ts             # 1ヶ月単位変形労働（FR-115）
│   ├── monthly.ts              # 月次集計（FR-601）
│   ├── compliance.ts           # ★ 36協定（FR-605〜607）
│   ├── paidLeave.ts            # 有給の付与・残・年5日義務（FR-608〜610）
│   └── corrections.ts          # 訂正の適用（CAL-01）
├── shift/                      # ★ シフト。純粋関数のみ
│   ├── coverage.ts             # 必要人数の充足判定（FR-403, FR-404）
│   ├── constraints.ts          # ★ 法令制約の検証（FR-405）
│   ├── generate.ts             # 自動生成（FR-406, FR-407）
│   ├── cost.ts                 # 人件費の見込み（FR-409）
│   └── variance.ts             # 予実比較（FR-611）
├── time/                       # 分数⇔時刻、24:00超の扱い（CAL-05）
├── csv/                        # 給与CSV出力
├── query/                      # 絞り込み・ソート・ビュー
├── store/  { session, data, rules, sync, ui }
└── repo/                       # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts
    ├── _scope.ts               # ★ データスコープ + 項目スコープ（SCP-01）
    ├── punches.ts  attendance.ts  corrections.ts  leave.ts
    ├── shift.ts  shiftRequests.ts  demand.ts
    ├── monthly.ts  compliance.ts  employees.ts  rules.ts  logs.ts

リポジトリ層の規約（厳守）

• 全メソッドを async で定義する。中身が同期でも例外なく
• 戻り値は { ok: true; data: T } | { ok: false; error: string } に統一する
• コンポーネントから Zustand ストアを直接参照しない。 読み取りも書き込みもリポジトリ経由
• 労働時間の算出を lib/attendance/ の外に書かない（CAL-02）
• 法令に関わる判定をコンポーネントに書かない（CAL-07）
• 打刻レコードを更新・削除するコードを書かない（CAL-01）
• スコープ適用（_scope.ts）を全メソッドが必ず通す。 ここが実案件で権限制御に置き換わる箇所
• 時給・給与額・人件費は、権限がない場合オブジェクトから除外して返す（SCP-03）
• 派生値（労働時間・月次集計・36協定・人件費）はストアに保存せず算出する
• 打刻と労働時間の再算出に擬似ディレイを入れない

8. デザイン要件

アートディレクション

「1日を、24時間の帯として横に描く」

勤怠システムが扱うのは「時刻」と「長さ」である。9:03 という点と、8時間という幅。数字の羅列では、どこが所定でどこが残業か、どこが深夜に食い込んでいるかが分からない。

TOKIWA は1日を横1本の24時間帯として描き、その上に打刻の点、労働の帯、休憩の抜け、深夜のゾーン、残業の色分けを重ねる。時間の重なりを図として読ませる。

• 横軸は常に時間。 日次も、シフト表も、充足ヒートマップも、横軸を時間で統一する
• 色は区分のためだけにある。 所定内・法定内残業・法定外残業・深夜・休日。それ以外に色を使わない
• 時刻は大きく、等幅で。 9:03 19:47 は読み間違えると事故になる
• 警告は数字で。「休憩不足」ではなく「休憩不足 3分」

RELATE / KURA との差別化（最重要） 3本とも「白背景・高密度・業務システム」だが、方向を分ける。 RELATE：罫線と等幅数字で表を読ませる。藍。 KURA：各行に在庫の水位バーを描く。ティール＋アンバー。縦長数字。 TOKIWA：各行に1日の24時間帯を描く。インディゴ＋コーラル。等幅数字＋大きな時刻表示。 KURA の水位バーは「量」、TOKIWA の時間帯は「位置と長さ」。 見た目が似ないよう、TOKIWA の帯は必ず時刻目盛りを伴うこと。

カラートークン

:root {
  /* ニュートラル（わずかに青みのある事務的な白） */
  --bg:        #F4F5F8;   /* ページ背景 */
  --panel:     #FFFFFF;   /* テーブル・カード */
  --panel-alt: #EDEFF4;   /* 縞・ヘッダー */
  --line:      #DCDFE7;   /* 罫線 */
  --line-hi:   #B7BCC9;   /* テーブルヘッダー下、時刻目盛り */

  --ink-900:   #131722;   /* 見出し・本文・時刻 */
  --ink-600:   #4C5464;   /* 補助テキスト */
  --ink-400:   #8A92A3;   /* ラベル・非活性 */

  --primary:   #3A4CAD;   /* 主要CTA・選択状態（インディゴ） */
  --primary-d: #2C3A87;
  --primary-50:#E8EAF7;

  /* ★ 労働時間の区分。これ以外の色を帯に使わない */
  --seg-scheduled:  #3A4CAD;   /* 所定内労働（インディゴ） */
  --seg-ot-inside:  #6F7ECB;   /* 法定内残業（薄いインディゴ） */
  --seg-ot-outside: #E4633F;   /* 法定外残業（コーラル） */
  --seg-night:      repeating-linear-gradient(  /* ★ 深夜はゾーンとして重ねる */
      45deg, transparent 0 5px, rgba(58,76,173,.28) 5px 10px);
  --seg-holiday:    #B0459A;   /* 休日労働（マゼンタ寄り） */
  --seg-break:      #DCDFE7;   /* 休憩（抜き） */
  --seg-leave:      #4C9A7A;   /* 有給・休暇 */

  /* 時間帯の地 */
  --band-track:     #EDEFF4;
  --band-night-bg:  #E4E7F2;   /* 22:00-5:00 の背景 */
  --band-scheduled: #F7F8FB;   /* 所定時間帯の背景 */

  /* ★ 異常・法令警告 */
  --alert-error: #C2382C;   /* 上限超過・休憩不足 */
  --alert-warn:  #C08320;   /* 上限接近・未打刻 */
  --alert-info:  #3A6FA8;   /* 承認待ち */

  /* シフトの充足 */
  --cov-short:  #C2382C;   /* 不足 */
  --cov-exact:  #4C9A7A;   /* ちょうど */
  --cov-over:   #6F7ECB;   /* 過剰 */
}

配色ルール

• 通常の勤務日に色を持たせない。 色がついている行は「対応が必要な行」だけ
• 深夜は塗りではなく斜線ゾーンで重ねる。 「別の区分」ではなく「別の軸の属性」だから、塗りを奪わない
• 法定外残業だけがコーラル（暖色）。 ここが給与と法令に最も効く区分だから、唯一の暖色を割り当てる
• 上限超過を赤、上限接近を琥珀にする。 逆にしない
• 部署にも雇用形態にも固有色を割り当てない。バッジが色だらけの画面にしない

タイポグラフィ

RELATE も Roboto Mono を使うが、TOKIWA は punch-lg（36px）という極端に大きい時刻表示を持つ点が違う。 打刻画面では時刻が主役になる。

レイアウトとスペーシング

主要コンポーネント仕様

インタラクション要件（業務システムの肝）

モーション

prefers-reduced-motion: reduce 時は全アニメーションを無効化する。

アクセシビリティ（WCAG 2.1 AA）

ライティング規約

9. 技術要件・ディレクトリ構成

技術スタック（固定・勝手に変更しない）

上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特に給与計算・労務計算系のライブラリ、最適化ソルバ、重量級チャートライブラリの導入は禁止。

ディレクトリ構成

/
├── CLAUDE.md
├── app/
│   ├── layout.tsx                  # アプリシェル（ロール別ナビ・デモ切替バー）
│   ├── page.tsx                    # SC-001 打刻 / SC-900（?embed=1）
│   ├── attendance/                 # SC-010〜013
│   ├── overtime/  leave/           # SC-020, 030, 031
│   ├── shift/                      # SC-040〜042
│   ├── notifications/              # SC-050
│   ├── admin/                      # SC-100〜140
│   ├── hr/                         # SC-200〜210
│   └── dev/components/
├── components/
│   ├── timeband/                   # ★ 最重要
│   │   ├── DayBand.tsx             # 24時間帯（行内・詳細の2サイズ）
│   │   ├── BandRuler.tsx           # 時刻目盛り
│   │   ├── PunchMarker.tsx         # 生打刻／訂正後の点
│   │   ├── SegmentLegend.tsx       # 区分の凡例
│   │   └── BandTooltip.tsx
│   ├── punch/                      # PunchButton, PunchClock（punch-lg）, PunchResult
│   ├── shift/                      # ShiftGrid, ShiftCell, CoverageHeatmap, CostCard, useShiftDnd
│   ├── compliance/                 # ComplianceGauge, LimitBadge
│   ├── domain/                     # CalcBreakdownPanel, RoundingToggle, AnomalyBadge, CorrectionDiff, VarianceRow
│   ├── table/                      # DataTable, FilterBar, ViewSidebar
│   ├── demo/                       # RoleSwitcher, ResetButton, GuideTour, BackToArticle
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── attendance/                 # ★ 労働時間の算出。純粋関数のみ
│   ├── shift/                      # ★ シフト。純粋関数のみ
│   ├── time/ csv/ query/ validation/ utils/
├── docs/
│   └── work-rule-checklist.md      # 資料PDFの元原稿（就業規則ヒアリングシート）
├── e2e/
└── public/

コーディング規約

• TypeScript strict。any 禁止。やむを得ない場合は unknown + 型ガード
• ファイル名は kebab-case、コンポーネントは PascalCase
• 1ファイル300行を超えたら分割を検討する
• コンポーネントから Zustand ストアを直接参照しない。必ず lib/repo/ 経由
• 労働時間の算出を lib/attendance/ の外に書かない（CAL-02）
• 法令に関わる判定をコンポーネントに書かない（CAL-07）
• 打刻レコードを更新・削除するコードを書かない（CAL-01）
• lib/attendance/ lib/shift/ lib/time/ は純粋関数のみ。 ストア・DOM に依存させず、new Date() を内部で呼ばない（CAL-03）
• 時刻は分数で扱い、日跨ぎは 24:00 超で表現する。 文字列の切り貼りで時刻計算をしない（CAL-05）
• タイムゾーンは Asia/Tokyo 固定（実案件では要検討である旨をコメントに残す）
• 派生値（労働時間・月次集計・36協定・人件費）をストアに保存しない
• 賃金計算に浮動小数点の累積誤差を持ち込まない（円単位の整数演算で扱い、端数処理の方針をコメントに明記する）
• コミットは1タスクごと。メッセージに要件IDを含める 例：feat(attendance): 深夜と法定外残業の割増重複を合成 (FR-112)

10. 非機能要件・法令

性能要件

セキュリティ・プライバシー

法令に関する取り扱い（この領域の最重要事項）

本デモは労働時間計算の実装例であり、法令解釈の保証をするものではない。 この立場を明確にする。

実案件への転用時の注意（デモ本体の要件ではない。商談で聞かれた際に説明できるよう記録）

① 勤怠システムは「作って終わり」にならない。 法改正・就業規則変更のたびに計算ロジックの見直しが必要。保守を前提とした契約設計が必須

② 労働時間の記録は法定の保存義務がある。 保存期間（賃金台帳等は原則5年、当面3年）と、改ざんできない記録の保持が求められる。打刻を書き換えない設計（CAL-01）はこの要求に直結する

③ 客観的な記録による把握が求められる。 自己申告のみの運用にはリスクがあり、打刻・PCログ等の客観記録が望ましい

④ 打刻データは個人情報。 位置情報を取得する場合は特に、利用目的の明示と同意、取得時間帯の制限が論点になる（従業員監視との線引き）

⑤ 給与計算との接続点で端数処理が問題になる。 時間の端数、賃金額の端数の処理方法は就業規則で定め、システムと一致させる必要がある

⑥ 未払賃金の遡及リスク。 計算誤りが見つかった場合、過去に遡って再計算・追加支払が発生する。だから計算ロジックのテストが他システム以上に重要

本デモはデータをサーバーに送信しないため、②〜④の義務は発生しない。「デモである」旨と LAW-01 の注記を画面上に常時明示する

11. 費用設計

記事の主題の半分は「費用」。この章は実装要件であると同時に、記事本文の原稿素材でもある。

勤怠システムだけの特殊事情：人数課金 × 保守が続く

⑤を見積もらずに始めると、「法改正のたびに追加費用で揉める」ことになる。 記事ではここを明示する。

①の分岐：既製の勤怠サービスがあるのに、なぜ自作するのか

この問いに答えられない案件は、受けるべきではない。 勤怠は既製サービスが極めて充実しており、法改正対応も含まれる。正直にそう書くことが信頼を生む。

逆に、①〜⑤のどれにも当てはまらないなら、既製サービスを使うべき。 特に法改正対応が標準で付いてくることは、自作にはない大きな価値。

損益分岐の計算式

既製サービスの年間コスト
  = 月額単価 × 従業員数 × 12
  + 初期設定費
  ( + オプション：シフト機能・有給管理・API連携 )

回収年数 = （開発費 + ハード費）÷（既製サービス年間コスト − 自作の年間運用費 − 年間保守費）

ここで重要なのは、分母から「年間保守費」を引くこと。 法改正対応を自社で持つなら、その費用を計算に入れないと損益分岐が実態と合わない。

③の分岐：打刻の手段（現場を左右する判断）

判断の目安：

• オフィスワーク中心／直行直帰がある → Web打刻（スマホ）＋位置情報
• 店舗・工場で同時刻に多人数が出勤 → タブレット共有だと行列になる。ICカードが有利
• なりすまし防止が重要（労務トラブルの実績がある）→ ICカード／生体認証

TOKIWA が Web打刻を基本にしているのは、デモとして最速で体験できるため。 実案件では上表で選定する。

②の分岐：見落とされやすい「就業規則の整理」工数

勤怠システムの導入で最も工数を食うのは、実装ではなく就業規則の言語化。

• 丸めのルール（実は明文化されていない／部署でバラバラ）
• 法定休日の特定方法（就業規則に書いていない）
• 休憩の扱い（実績を取っていない、所定控除で運用している）
• 残業の申請フロー（事前申請なのか事後承認なのか）
• 「運用と就業規則が一致していない」ことが判明する

この整理が終わらないと、計算ロジックを実装できない。 資料PDFの「就業規則ヒアリングシート」は、この工数を前倒しするために作る。資料請求が有効なリードになる設計。

Webで足りるか、ネイティブが必要か

勤怠は、Webで足りる領域。

判断の目安： 打刻忘れのプッシュ通知を重視するなら、LINE公式アカウントでの通知が現実的な代替になる（アプリ開発より安い）。NFC を使うなら専用端末かネイティブ。

デモ自体の運用コストを実測して記事に載せる

12. 実装タスク

この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。

Phase 0 — 基盤と労働時間算出エンジン（5日）

0-1. 初期化

• Next.js 15 / TypeScript strict / App Router / Tailwind で初期化
• ESLint / Prettier / husky（pre-commit で lint + typecheck）
• 9章のディレクトリ構成を作成

0-2. lib/time/（純粋関数。最初に固める）

• 分数⇔時刻文字列の相互変換、24:00超の表現（CAL-05）
• 時間帯の重なり・差分・分割（深夜抽出の土台）
• 週の起算曜日を考慮した週の生成
• 単体テストを書く。特に日跨ぎと時間帯の分割は境界条件を網羅

0-3. lib/attendance/（このプロジェクトの心臓部。ここに最も時間をかける）

• rounding.ts：丸め（単位 × 方向、出勤/退勤別）(FR-103, FR-105)
• breaks.ts：法定休憩の充足判定、所定休憩の自動控除（FR-106, FR-107）
• holiday.ts：法定休日／所定休日の判定（FR-111）
• overtime.ts：法定内／法定外の切り分け、週40時間（FR-109, FR-114）
• night.ts：深夜の抽出。日跨ぎ対応（FR-110, FR-116）
• premium.ts：割増率の合成（重複の正しい処理）（FR-112）
• flexible.ts：1ヶ月単位変形労働（FR-115）
• corrections.ts：訂正の適用。生打刻は変更しない（CAL-01）
• daily.ts：日次サマリと CalcBreakdown の生成（7章のコード参照）(FR-117)
• monthly.ts：月次集計（FR-601）
• compliance.ts：36協定の4上限（FR-605〜607）
• paidLeave.ts：有給の付与・残・年5日義務・失効（FR-608〜610）
• new Date() を内部で呼ばない。現在時刻と就業規則を引数で受け取る（CAL-03）
• メモ化と、打刻の追加・設定変更の両方での無効化（CAL-04, FR-120）
• 単体テストを網羅的に書く。以下を必ず含めること：
  • 丸め単位・方向を変えると勤務時間と残業時間が変わること（最重要）
  • 切り捨ての丸めで実労働時間より短くなること（そしてそれが警告対象であること）
  • 法定休憩の判定（6時間超45分／8時間超60分／ちょうど6時間・8時間の境界）
  • 所定7時間の会社で7〜8時間が法定内残業、8時間超が法定外残業になること
  • 深夜（22:00-5:00）の抽出。日跨ぎ勤務で正しく計算されること
  • 法定休日労働と所定休日労働の割増率が異なること
  • 深夜×法定外残業、深夜×法定休日 の割増重複が正しく合成されること
  • 週40時間超の判定（起算曜日を変えると結果が変わること）
  • 遅刻・早退の算出
  • 訂正を承認すると勤務時間が変わり、生打刻は変わっていないこと
  • 就業規則のバージョンにより、過去の期間は当時の設定で計算されること（FR-702）
  • 36協定の4上限（月45／年360／複数月平均80／単月100）が正しく判定されること
  • 有給の年5日義務と失効予定の算出
  • CalcBreakdown に全ステップの根拠が入っていること（FR-117）
• 42名 × 3ヶ月分で月次集計が 200ms以下をベンチマークで確認（NFR-03）

0-4. lib/shift/（純粋関数）

• coverage.ts：必要人数の充足判定（FR-403, FR-404）
• constraints.ts：法令制約の検証（週40h、連続勤務日数、勤務間インターバル）(FR-405)
• generate.ts：貪欲法での自動生成 + 埋められない理由の記録（FR-406, FR-407）
• cost.ts：人件費の見込み（割増込み）(FR-409)
• variance.ts：予実比較（FR-611）
• 単体テストを書く。特に制約違反の割当が弾かれること

0-5. 型とシード

• lib/types/ に7章の型定義をすべて実装
• lib/seed/ の全ファイル
• 打刻を「9:00きっかり」にしない。9:03・8:57・19:47 の端数を持たせる（最重要）
• 休憩不足の日、退勤打刻がない日、深夜・日跨ぎ勤務、休日出勤を含める
• 36協定の上限に接近2名・超えそう1名、有給年5日未達3名、失効間近1名を作る
• シフトの予定と実績にズレを持たせる。必要人数が不足している日を数日作る
• 就業規則のバージョンを2つ持ち、3ヶ月前に丸め設定が変わった状態にする
• 打刻列の時系列に矛盾がないこと
• 日付は現在日時からの相対で生成する

0-6. ストアとリポジトリ

• lib/store/{session,data,rules,sync,ui}.ts を Zustand + persist で実装
• lib/repo/_scope.ts を最初に実装する（データスコープ + 項目スコープ）(SCP-01〜04, FR-805〜807)
• lib/repo/ の全モジュール。全メソッド async、Result型、スコープ適用
• 打刻レコードを更新・削除するコードを書かない（CAL-01）
• スコープの単体テストをこの時点で書く（従業員が他人の打刻を取得できないこと、時給が含まれないこと）
• 打刻と労働時間の再算出に擬似ディレイを入れない

0-7. デザインシステム

• app/globals.css にカラートークンを CSS 変数で定義（区分色 + 深夜の斜線 + 充足色）
• tailwind.config.ts から CSS 変数を参照するよう theme を拡張
• フォント（Noto Sans JP / Roboto Mono）を next/font で最適化。時刻に tabular-nums
• shadcn/ui を導入し、トークンに合わせて上書き
• DayBand.tsx：24時間帯（行内10px / 詳細32pxの2サイズ）+ BandRuler.tsx 時刻目盛り
• PunchMarker.tsx：生打刻（中空・点線）／訂正後（塗り・実線）の描き分け（FR-306）
• 帯の aria-label と、区分ごとの数値併記（A11Y-05, A11Y-06）
• 共通コンポーネント：AnomalyBadge（数字を必ず含む）／SegmentLegend / EmptyState（2種の出し分け）／Skeleton（帯の位置も確保）
• prefers-reduced-motion の対応
• /dev/components にコンポーネントカタログを作成

0-8. デモ基盤

• RoleSwitcher（3ロール + 従業員の3ペルソナ選択）(FR-804)
• デモ切替バー（ダークな帯）+ 「これはデモです。打刻データは送信されません」（SEC-02）
• LAW-01 の注記コンポーネント（設定画面・月次集計画面に常設）
• 「デモをリセット」(FR-808)／ロール権限外アクセス時の案内画面（FR-811）
• 元記事リンク・資料ダウンロード（FR-813）

Phase 0 完了チェック

• lib/attendance/ のテストが全パターン通る
• 「丸め設定を変えると残業時間が変わる」がテストで検証済み
• 「深夜×法定外残業の割増重複」がテストで検証済み
• 「訂正の承認で勤務時間が変わり、生打刻は変わらない」がテストで検証済み
• 従業員ロールで他人の打刻が取得できず、時給が含まれないことがテストで検証済み
• 42名 × 3ヶ月の月次集計が200ms以下
• /dev/components で24時間帯が全パターン正しく描画される

Phase 1 — 打刻と勤務照会（4日）

1-1. 打刻

• SC-001 打刻画面：状態別に1つのボタン（FR-201）
• 1タップ完了、確認ダイアログなし、100ms以下（FR-202, IX-01, NFR-01）
• 打刻直後に時刻を punch-lg で表示、aria-live で通知（FR-203, A11Y-10）
• 直後の自己取消（3分以内）(FR-204)／二重打刻の防止（FR-205）
• 位置情報の任意付与（拒否しても打刻できる）(FR-206, FR-207, SEC-06)
• 退勤忘れの検出と翌日の通知（FR-208）
• 本日の勤務時間・休憩残り・退勤予定・今月の残業累計（F-P03）
• 月次確定後はロックされ、理由を表示すること（FR-210）
• 全打刻に端末種別・位置・記録日時を残す（FR-211）

1-2. 勤務照会

• SC-010 月次勤務一覧：日別の24時間帯 + 丸め前後の両方 + 合計行（FR-104 相当の可視化）
• 異常の強調（未打刻・休憩不足・承認待ち。数字を含むバッジ）(A11Y-07)
• SC-011 勤務日詳細：24時間帯（詳細サイズ）+ 区分内訳 + 計算の根拠パネル（FR-117）
• CalcBreakdownPanel：全ステップを「入力 → 出力（根拠）」で表示。既定で開く
• SC-020 残業サマリ：当月累計、36協定の上限までの残り時間、月別推移（F-P07）
• ComplianceGauge：4本のバー（月45h／年360h／複数月平均80h／単月100h）

1-3. 埋め込みモード

• SC-900 埋め込みモード：24時間帯 + 丸め設定トグル + 生打刻/解釈後の並列表示（FR-815, 2章）
• 丸め設定を変えると 50ms以下で再計算され、帯と数値が変わること（IX-02, EMB-06）
• 切り捨て選択時に適法性の注意が出現すること（FR-104, LAW-04）
• 位置情報を呼ばない・打刻させない（EMB-04）／アプリ内遷移をしない（EMB-05）
• 初期バンドル 60KB以下を実測（NFR-11）

Phase 1 完了チェック

• フローAが完走する（埋め込みで丸めを変えると計算が変わる → 全画面 → 根拠が全ステップ見える）
• 4章「ロールを跨ぐ体験」の1と2が動作する
• 打刻が100ms以下、丸め変更が50ms以下
• 従業員ロールで他人のデータが一切見えない

Phase 2 — 訂正・申請・承認（3日）

• SC-012 打刻訂正申請：訂正前後の差分と再計算結果のプレビュー（FR-301）
• 理由コードの必須化（FR-302）
• 申請中は勤務時間を変えないこと（FR-303）
• SC-130 打刻訂正の承認：差分と再計算結果を並べて表示、承認／差戻し（FR-304）
• 連続処理（A 承認／R 差戻し／→ 次）（IX-06）
• 取り消し可能なトースト（IX-08）
• 承認後の「訂正あり」バッジと承認者の表示（FR-305）
• 勤務日詳細のタイムラインに、生打刻と訂正後の両方を描画（FR-306）
• SC-030 休暇申請（有給／特別／欠勤、全日／半休／時間単位）(FR-307)
• 残日数の表示と不足時の警告（FR-308）
• SC-131 休暇申請の承認：シフトへの影響表示（FR-309）
• SC-031 有給残日数：付与履歴、残、失効予定、年5日義務の進捗（FR-609, FR-608）
• SC-013 申請状況／SC-050 通知センター
• 承認・差戻し・訂正を操作ログに記録（FR-311）

Phase 2 完了チェック

• フローBが完走する（打刻忘れ → 訂正申請 → 差分確認 → 承認 → 再計算 → 生打刻は残る）
• 4章「ロールを跨ぐ体験」の3が動作する
• 承認前に勤務時間が変わっていないことを確認

Phase 3 — シフト（5日）

3-1. シフト希望

• SC-040 シフト希望の提出：期間内の希望入力、締切カウントダウン（FR-501）
• 締切後の提出不可、未提出者への催促プレビュー（FR-502）
• SC-116 希望の集計：提出状況、未提出者、希望の可視化（FR-503）
• 上限勤務日数・週の希望時間（FR-504）

3-2. シフト表

• SC-112 必要人数の設定（曜日別・時間帯別、テンプレート）(FR-403)
• SC-110 シフト表：従業員×日付グリッド、パターン割当（FR-401）
• dnd-kit でのドラッグ割当・コピー・移動（FR-402）
• キーボード操作（矢印移動、数字キーで割当、Delete で解除）(IX-05, A11Y-03)
• 必要人数の過不足を色表示（FR-403）
• 法令違反の割当を弾き、理由を表示（FR-405）
• SC-111 時間帯別の充足ヒートマップ（横軸=時間、縦軸=日付）(FR-404)
• SC-113 シフト自動生成 + 埋められなかった理由の提示（FR-406, FR-407）
• 生成結果は必ず下書き。自動確定しない（FR-408）
• SC-114 人件費の見込み（割増込み、予算差分、深夜/休日の強調）(FR-409, FR-410)
• SC-115 公開：通知プレビュー、公開履歴（FR-411, FR-412）
• シフトパターンのマスタ（FR-413）／前月複製（FR-414）
• SC-041 確定シフト（従業員側、月／週表示、ics）(FR-507)
• SC-042 / SC-132 シフト交代（相手の承諾 → 管理者承認の2段階）(FR-505, FR-506)

Phase 3 完了チェック

• フローCの前半が完走する（必要人数 → 希望集計 → 自動生成 → 手修正 → 人件費 → 公開 → 従業員に反映）
• 4章「ロールを跨ぐ体験」の4が動作する
• シフト表がキーボードのみで操作完遂できる
• 法令違反の割当が弾かれ、理由が表示される

Phase 4 — 集計・法令モニタリング・設定（4日）

4-1. 管理者の日次・予実

• SC-100 日次ダッシュボード（未打刻者・遅刻・退勤忘れ・承認待ち）(FR-613)
• SC-120 勤怠一覧（部署）：メンバー×日付、異常の強調
• SC-121 予実比較：予定と実績の24時間帯を上下2段で重ねて描画、時間差分・人件費差分（FR-611）
• SC-140 従業員一覧（当月残業、有給残、スキル）

4-2. 月次と法令

• SC-200 月次集計：従業員別の全区分、異常の一覧（FR-601, FR-602）
• 月次確定とロック。確定解除は管理部のみ + 操作ログ（FR-603）
• SC-201 給与CSV出力 + 出力項目のプレビュー（FR-604）
• SC-202 36協定モニタリング：4上限の進捗、上限接近者の抽出と残り時間（FR-605, FR-606）
• 特別条項の適用回数（FR-607）
• SC-203 有給の取得義務管理：年5日の進捗、未達者、失効予定（FR-608, FR-609）
• 時間単位有給の上限管理（FR-610）
• 部署別・月別の残業推移グラフ（FR-612、Recharts 動的import）

4-3. 設定

• SC-204 就業規則の設定（丸め・所定・休憩・割増率・法定休日・週起算・変形労働）(FR-701)
• 設定のバージョン管理と適用開始日。過去は当時の設定で計算（FR-702）
• 設定変更時に影響を受ける従業員数と期間を事前表示（FR-703）
• SC-210 計算ルールの検証画面：サンプル打刻への計算結果一覧。設定変更で即座に変わる（FR-704）
• 法定を下回る設定・切り捨ての丸めに警告（FR-705, LAW-03, LAW-04）
• SC-205 従業員マスタ（FR-706）／SC-207 休日カレンダー（FR-707）
• SC-206 部署・拠点（FR-708）／SC-208 通知文面（FR-709）
• SC-209 操作ログ（FR-710）
• LAW-01 の注記が設定画面と月次集計画面に常設されていること

Phase 4 完了チェック

• 4章「ロールを跨ぐ体験」の5と6が動作する
• 就業規則の丸め設定を変えると、過去分も含めて再計算される
• 36協定モニタリングに意味のある警告が出ている（シードの品質確認）
• 月次確定後に打刻・訂正申請ができない

Phase 5 — オフライン・記事統合・仕上げ（3日）

5-1. オフライン

• Service Worker / PWA マニフェスト／オフライン検知とバナー
• オフライン打刻と未同期バッジ（FR-209）
• オンライン復帰時の自動同期と進捗表示
• localStorage 上限時の圧縮処理（NFR-15）

5-2. 記事統合

• 記事側の埋め込みコードを作成し、実際の記事ページで動作確認（EMB-01〜06）
• 埋め込みで「丸め設定を変えると計算が変わる」が伝わることを確認
• 記事の Core Web Vitals を埋め込み前後で比較検証
• 「全画面で試す」カードの設置
• 資料PDF（就業規則ヒアリングシート・損益分岐計算シート）の作成とダウンロード導線
• 元記事リンク・問い合わせ導線
• GA4 イベント設定。rounding_changed を必ず含める（EMB-07, EMB-08）
• GA4 に氏名・打刻データ・給与額を送っていないことを確認（EMB-09, SEC-03）
• ?embed=1 を noindex に、デモ本体の title / description / OGP（EMB-10）
• 記事内に LAW-02 の注記を明示

5-3. 体験の総点検

• 4章「ロールを跨ぐ体験」の6パターンをすべて手動で確認
• 全34画面を開き、空の画面が1つもないことを確認
• 空状態（データ0件／絞り込み0件）の出し分けを確認
• ガイドツアーを実装（FR-814）

5-4. アクセシビリティ監査

• axe-core を全画面に実行し、Critical / Serious を0件に
• 13px本文のコントラスト比を実測（A11Y-01）
• 24時間帯の aria-label と区分の数値併記を確認（A11Y-05, A11Y-06）
• 警告が色のみで伝わっていないことを確認（数字とアイコンの併記）(A11Y-07)
• キーボードのみで全画面・打刻・シフト表・承認を完遂
• 打刻ボタンのタップ領域56px以上を確認（A11Y-13）
• フォントサイズ200%での確認（A11Y-14）

5-5. パフォーマンス

• グラフを動的import に切り出し、初期バンドルを250KB以下に（NFR-12）
• 打刻100ms以下、丸め変更50ms以下、月次集計200ms以下を実測（NFR-01〜03）
• シフト自動生成2秒以下、ドラッグ60fpsを実測（NFR-05, NFR-10）
• Lighthouse で Performance 90 / Accessibility 95（NFR-13）

5-6. 公開と記録

• Playwright で フローA・B・C の E2E
• Vitest：lib/attendance lib/shift lib/time _scope のカバレッジ 90%以上（他テーマより高く設定する。計算誤りが未払賃金に直結するため）
• /dev/components を本番で非公開に
• Vercel へデプロイ
• 打刻数・rounding_changed 発生率の記録を開始（COST-01, COST-02）
• 解説動画（3分）の収録：打刻 → 丸め設定を変えると残業が変わる → 計算の根拠 → 打刻訂正の承認 → シフト作成と人件費 → 36協定の警告
• 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

合計 24営業日（約5週間）／1名専任 + レビュー体制。

工数配分の意図： Phase 0 に5日、うち lib/attendance/ のテストに3日を充てる。労働時間の算出はこのプロジェクトの価値そのものであり、かつ間違っていても画面上は正しく動いているように見える。そして間違いは未払賃金の遡及という形で表面化する。他テーマよりテストカバレッジの目標を高く（90%）設定しているのはこの理由。 Phase 3（シフト）に5日を割いているのは、シフト表のグリッドとD&D、充足ヒートマップ、自動生成、人件費試算がそれぞれ独立した実装量を持つため。

13. 受入基準

1. 6章の優先度 P1 の要件がすべて実装され、テストで合格していること
2. 5章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 4章「ロールを跨ぐ体験」の6パターンがすべて動作すること
4. 打刻レコードが編集・削除されておらず、訂正が別レコードとして保持されていること
5. 労働時間が保存されておらず、常に生打刻と就業規則設定から算出されていること
6. 丸め設定（単位・方向）を変更すると、勤務時間・残業区分・割増額が変わること。かつ 50ms以下で反映されること
7. 就業規則にバージョンがあり、過去の期間が当時の設定で計算されること
8. 法定休憩の不足が、具体的な分数で警告されること
9. 法定内残業と法定外残業が正しく切り分けられること（所定 < 法定 の会社で検証）
10. 深夜（22:00-5:00）が日跨ぎ勤務でも正しく抽出され、割増の重複が正しく合成されること
11. 法定休日労働と所定休日労働の割増率が異なること
12. CalcBreakdown に全ステップの入力・出力・根拠が入っており、画面に表示されていること
13. 訂正申請中は勤務時間が変わらず、承認時に初めて反映されること。かつ生打刻が変わっていないこと
14. 36協定の4上限（月45h／年360h／複数月平均80h／単月100h）が判定され、残り時間が明示されること
15. 有給の年5日取得義務の進捗と未達者、失効予定が表示されること
16. シフト表で法令違反になる割当が弾かれ、理由が表示されること
17. シフト自動生成の結果が下書きであり、埋められなかった理由が提示されること
18. 人件費の見込みがシフト確定前に試算され、予算との差分が表示されること
19. 予実比較で、シフト（予定）と打刻（実績）が同じ時間軸上で並んで表示されること
20. 月次確定後、打刻と訂正申請がロックされること
21. ロールを切り替えると、見える行と見える列（時給・給与額・人件費）の両方が変わること。従業員は他人の打刻を一切取得できないこと（CSSで隠していない）
22. 打刻が100ms以下、月次集計（42名×3ヶ月）が200ms以下であること
23. 24時間帯が aria-label を持ち、区分ごとの時間が数値としても表示されていること
24. 警告が色のみで伝えられておらず、具体的な数字を含んでいること
25. LAW-01 の注記（専門家確認の推奨）が設定画面と月次集計画面に常設されていること
26. 切り捨ての丸め・法定を下回る割増率に警告が表示されること
27. 打刻データ・氏名・給与額が外部に一切送信されていないこと（DevTools と GA4 のイベントで確認）
28. 全34画面のいずれにも空の状態がなく、リアルなデータが表示されていること
29. lib/attendance lib/shift lib/time のテストカバレッジが 90%以上であること
30. axe-core で Critical / Serious の指摘が0件であること
31. データアクセスがすべて lib/repo/ を経由し、労働時間の算出が lib/attendance/ の外に存在しないこと
32. RELATE / KURA と並べたときに、明確に別のプロダクトとして見えること（24時間帯と時刻目盛りが効いていること）

判断に迷ったときのルール

1. 計算ロジックを推測で書かない。 割増賃金・休憩・36協定は法令に基づく。曖昧なら必ず質問する。 これがこのプロジェクトで最も重要なルール
2. 打刻を書き換えない。 訂正は別レコード + 承認。これがこのプロジェクトの存在理由
3. 労働時間を保存しない。 生打刻と設定から常に算出する
4. 労働時間の算出を lib/attendance/ の外に書かない。 法令判定をコンポーネントに書かない
5. lib/attendance/ lib/shift/ lib/time/ を純粋関数に保つ。 現在時刻と設定は必ず引数で受け取る
6. 時刻は分数で扱う。 日跨ぎは 24:00超。文字列の切り貼りで時刻計算をしない
7. 計算の根拠（CalcBreakdown）を必ず返す。 「なぜこの時間か」が説明できない実装をしない
8. 警告に必ず数字を入れる。「不足しています」ではなく「3分不足しています」
9. 時給・給与額は権限がなければデータに含めない。 CSSで隠すのは実装ミス。従業員が他人の打刻を取得できてはならない
10. 法令解釈を断定しない。 LAW-01 の注記を削らない。設定は警告するがブロックしない
11. 自動生成を自動確定にしない。 シフトは必ず人が確認して公開する
12. スコープ外（3章 Won't have）は実装しない。特にフレックス・1年単位変形労働・みなし残業は要件定義段階で洗い出す
13. 「デモだから」を理由に品質を落とす判断はしない
14. RELATE / KURA のトークン・コンポーネントをコピーしない。 TOKIWA の帯は必ず時刻目盛りを伴う