Shift Planner

Shift Planner

Overview

従業員リスト（roster）と人員要件（requirements）を入力として、制約充足型 Greedy Assignment で個人別シフトを自動編成するスキル。 production-schedule-optimizer の出力（人員要件）を活用可能だが、単体でも汎用的なシフト計画ツールとして動作する。

Primary language: Japanese (default), English supported Algorithm: Constraint-Satisfaction Greedy Assignment (difficulty-first slot ordering) Output format: Markdown report (shift table, coverage matrix, fairness report, alerts) Dependencies: None (Python standard library only)

When to Use

• 従業員の個人別シフト表を自動生成したい
• 勤務可能曜日・時間帯・資格などの制約を考慮したシフト編成が必要
• production-schedule-optimizer で算出した人員要件に基づくシフト計画を立てたい
• シフトのカバレッジ（時間帯別充足状況）を検証したい
• 従業員間の公平性（労働時間偏差、週末シフト配分）を分析したい
• 監督者配置要件を含むシフト計画が必要

Prerequisites

• Python 3.9+
• 外部依存なし（標準ライブラリのみ: csv, math, argparse, dataclasses）
• 入力CSVはUTF-8エンコーディング

Limitations

• 深夜跨ぎシフト非対応: start_hour >= end_hour のパターンは SFT-E004 で Reject
• 週単位: 月・年単位のスケジューリングは対象外
• 1日1シフト: 同一従業員の同日複数シフトは未対応

Output

• 形式: Markdown レポート（4セクション構成）
• 内容:
  1. シフト割当表（曜日別）
  2. カバレッジマトリクス（30分刻み）
  3. 公平性レポート（従業員別）
  4. アラート一覧

Input Specification

3種類のCSVファイルを入力として受け取る（シフトパターンは任意）。

1. roster.csv — 従業員リスト

2. requirements.csv — 人員要件

3. shift_patterns.csv — シフトパターン定義（任意）

未指定時はビルトインの5パターン（FULL_8H / EARLY_8H / LATE_8H / SHORT_6H / HALF_4H）を使用。

Sample files: assets/sample_roster.csv, assets/sample_requirements.csv, assets/sample_shift_patterns.csv

Workflow 1: Shift Generation

Purpose: 制約充足型 Greedy Assignment で個人別シフトを自動編成する。

Phase 1: Slot Priority Sort

• (day, room) ごとの要件を「充足困難度」でソート
• 困難度 = required_staff / 有資格従業員数（高い=先に割当）
• タイブレーク: DAY_ORDER index → room_code ASC

Phase 2: Greedy Assignment Loop

各スロットについて:

1. 候補フィルタ (is_eligible): ハード制約チェック

   • available_days, qualifications, max_hours, max_days, 連続勤務, 休息時間

2. 優先度スコア (compute_priority_score): 固定重み式

   score = -(remaining_hours * 10)     # 契約残余多い=優先
           + (weekend_shifts * 20)      # 週末バランス
           + (avoid_penalty * 50)       # 回避曜日ペナルティ
           - (supervisor_bonus * 100)   # 監督者ボーナス
           - (speciality * 5)           # 資格専門度
           + (preference_miss * 30)     # 希望パターン不一致
   

   タイブレーク: score ASC → employee_id ASC（完全決定性）

3. パターン選択 (select_pattern): ソートキー = (希望一致, -カバー時間, pattern_id ASC)

4. 割当 + 状態更新: hours_assigned, days_assigned, last_shift_end を更新

5. 監督者チェック: need_supervisor=1 の場合、監督者不在なら SFT-W002

Phase 3: Coverage Verification

• 30分刻みで assigned >= required を検証
• 休憩時間中は on_duty から除外

Phase 4: Fairness Metrics

• 従業員別: 実労働時間, 契約時間差分, 勤務日数, 週末シフト数, 回避曜日違反数
• 全体: 週末シフト標準偏差 → SFT-W009 (>1.0)

Detail: Load references/shift_planning_methodology.md for algorithm details.

Workflow 2: Validation & Alerts

Purpose: 入力データと生成結果の品質検証。

Error (SFT-E): Processing Stops

Warning (SFT-W): Processing Continues

Detail: Load references/labor_constraints_guide.md for labor law considerations.

Scripts

generate_shifts.py

python3 skills/shift-planner/scripts/generate_shifts.py \
  --roster roster.csv \
  --requirements requirements.csv \
  --patterns shift_patterns.csv \
  --week-start 2026-02-23 \
  --max-consecutive-days 6 \
  --min-rest-hours 11 \
  --output shifts.md

Built-in Shift Patterns

Resources

references/

assets/

Best Practices

入力データ準備

1. 従業員ID命名: 部門+連番（EMP-001, SUP-001）で管理性向上
2. 資格コード: production-schedule-optimizer の room_code と一致させる
3. 契約時間: 公平性計算の基準。max_hours_week と異なる場合は明示的に指定

シフト最適化

1. 困難スロット優先: アルゴリズムが自動処理（有資格者少ないスロット=先に割当）
2. 監督者確保: is_supervisor=1 の従業員を十分に配置
3. 週末公平配分: W_WEEKEND 重みで自然に分散、W009 で検知
4. 回避曜日: ソフト制約として考慮、やむを得ない場合は W003 で通知

production-schedule-optimizer との連携

1. estimate_staff.py の recommended 値を requirements.csv の required_staff に転記
2. room_code を一致させる
3. start_hour / end_hour は PSO の稼働時間帯に合わせる