KotDiff

KingOfTime の勤怠画面に実績と期待時間の差分列を追加する Chrome / Firefox 拡張。

機能

• 差分列の追加: KingOfTime の月次勤怠一覧テーブルに差分列を自動で追加する
• ダッシュボード: 月次の勤務状況を可視化するダッシュボードを提供する
  • 累積差分チャート（月間の過不足推移）
  • 日次勤務時間チャート
  • 残業ゲージ（月45時間上限に対する進捗）
  • 曜日別平均勤務時間チャート
  • 勤務時間帯チャート
  • 休暇残日数チャート（有休・特別休暇などの残日数）

計算ロジック

用語

用語	説明
実績時間	KOT に記録された実際の勤務時間（ALL_WORK_MINUTE 列）
所定時間	シフト上の所定労働時間（KOT の FIXED_WORK_MINUTE 列）。シフト勤務では 8h 以外の値になる
期待時間	累積差分の基準となる固定値（8h）
残業時間	実績時間が所定時間を超えた分。max(0, 実績 − 所定) で算出する
深夜残業	KOT が集計した深夜帯（22:00〜翌 5:00）の実労働時間（NIGHT_OVERTIME_WORK_MINUTE 列）
時間貯金	累積差分の通称。8h 基準で積み上げた過不足。シフト勤務では大きく乖離することがある
休憩時間	勤務中の休憩合計時間（REST_MINUTE 列）
小数時間	時刻・時間の内部表現。9:30 → 9.5、1時間30分 → 1.5
稼働日	平日かつ公休でなくエラーもない日（working = true）

KOT のデータフォーマット

KOT の画面から取得するデータは次の 2 種類のフォーマットを使用している。

フォーマット	用途	例	パーサ
HH:MM	打刻時刻（出勤・退勤・休憩の開始/終了）	09:00, 18:30	parseTimeRecord
H.MM	勤務時間・残業時間などの時間量	8.00, 9.16, 1.30	parseWorkTime

内部では両形式ともに小数時間に変換して計算する。

"09:30" → 9.5     （HH:MM 時刻）
"8.30"  → 8.5     （H.MM 時間量：8時間30分）
"9.16"  → 9.267   （H.MM 時間量：9時間16分）

H.MM の小数部は分であり、小数ではない。9.16 は 9.16h ではなく 9h16m を意味する。

現在時刻は JST（UTC+9）固定 で取得する。

稼働日の判定

次のすべてを満たす日を稼働日（working = true）とする。

• 土曜日でない（WORK_DAY セルに htBlock-scrollTable_saturday クラスがない）
• 日曜日でない（htBlock-scrollTable_sunday クラスがない）
• 公休でない（SCHEDULE セルのテキストに "公休" を含まない）
• 打刻エラーがない（WORK_DAY セルに specific-uncomplete クラスがない）

差分（1日単位）

稼働日かつ実績がある日に対して計算する。

差分 = 実績時間 − 8h

差分は累積差分チャートおよびテーブルの差分列に表示する。

月次累積

累積差分  = Σ（実績時間 − 8h）                           ※稼働日かつ実績ありの日のみ
残業合計  = Σ max(0, 実績時間 − 所定時間)                ※実績ありの日のみ
            所定時間（FIXED_WORK_MINUTE）が未設定の場合は 8h をフォールバックとして使用する

累積差分は 8h 基準の時間貯金（負になることもある）。残業合計は所定シフト時間を超えた分のみを加算するため、シフト勤務でも正確な残業時間を算出できる。

深夜残業

KOT の NIGHT_OVERTIME_WORK_MINUTE 列に記録された値を優先して使用する。列が空の場合は出退勤・休憩時刻から 22:00〜翌 5:00 の重複時間をローカル計算するフォールバックを行う。稼働日かどうかに関係なく実績ありの全日を集計する。

深夜残業合計 = Σ NIGHT_OVERTIME_WORK_MINUTE（または計算値）（実績ありの全日）

月次サマリー統計

平均勤務時間  = 実績合計 ÷ 実績ありの日数
月末予測合計  = 実績合計 + 残稼働日数 × 平均勤務時間
進捗率        = 実績合計 ÷ 期待合計（稼働日数 × 8h）× 100

進行中勤務の推定

当日勤務中の場合、現時点での推定実労働時間をリアルタイムで計算する。

推定実労働時間 = 経過時間 − 完了済み休憩時間

経過時間（勤務中）  = 現在時刻 − 出勤時刻
経過時間（休憩中）  = 最後の休憩開始 − 出勤時刻  ※休憩中は時間が進まない

日またぎシフトに対応しており、現在時刻が出勤時刻より小さい場合は翌日とみなして +24h する。推定値はバナーおよび差分列にイタリック表示される。

休憩充足判定（労働基準法第34条）

勤務時間	必要な最低休憩
8時間以上	60分以上
6時間以上 8時間未満	45分以上
6時間未満	規定なし

休憩が不足している行は REST_MINUTE セルを視覚的にハイライトする。

公休の表示

SCHEDULE 列に "公休" を含む行は次のように扱う。

• 日次テーブル: 公休行を bg-purple-50/40 の紫背景・ミュートテキストで表示し、実績列は "-" を表示する
• 休暇残日数チャート: "公休" ラベルの残日数エントリを非表示にする

タイムライン表示の座標系

勤務時間帯チャートでは、固定の時間軸 [5, 29]（5:00〜翌 5:00）を 100% として各区間の位置と幅を表現する。各区間は startHour/endHour（小数時間）で保持する。

開始位置 (%) = (startHour − 5) ÷ 24 × 100
幅       (%) = (endHour − startHour) ÷ 24 × 100

区間の種別は work（勤務）と break（休憩）の 2 種類。日またぎシフト（endHour < startHour）は endHour += 24 で補正して表示する。

差分の表示フォーマット

 正の差分（超過）: +H:MM  例: +1:30
 負の差分（不足）: -H:MM  例: -0:45

時間量の一般フォーマット（H:MM）は小数時間から変換し、分の端数は四捨五入する。

参考：月間残業上限

残業ゲージの基準値は 45時間/月。

インストール

Chrome

Chrome Web Store からインストール

Firefox

Firefox Add-ons (AMO) からインストール

Nix (home-manager)

flake.nix の inputs に追加し、home-manager の Firefox 拡張として設定する。

# flake.nix
inputs.kotdiff.url = "github:Xantibody/kotdiff";

# home-manager configuration
programs.firefox.profiles.<profile>.extensions.packages = [
  inputs.kotdiff.packages.${system}.default
];

開発

前提条件

• Node.js 22
• pnpm 10

ビルド

pnpm install
pnpm run build

dist/ ディレクトリにビルド済みファイルが生成される。

コマンド一覧

コマンド	説明
pnpm build	全コンポーネントをビルド
pnpm test	テストをウォッチモードで実行（vitest）
pnpm test:run	テストを1回実行
pnpm lint	src/ を oxlint でチェック
pnpm fmt	src/ を oxfmt でフォーマット
pnpm verify	fmt:check + lint + test:run を一括実行
pnpm package:local	ローカル用 zip / xpi を生成

ローカル検証

pnpm run build

Chrome

1. chrome://extensions を開く
2. 「デベロッパーモード」をオン
3. 「パッケージ化されていない拡張機能を読み込む」→ dist/ フォルダを指定

Firefox

1. about:debugging → 「このFirefox」
2. 「一時的なアドオンを読み込む」→ dist/manifest.json を指定