kintai 0.1.0

勤怠管理CLIツール

勤怠管理CLIツール開発仕様書

プロジェクト概要

Ubuntu環境で動作する個人用勤怠管理CLIツール「kintai」を開発する。このツールは日本時間（JST）での出退勤時刻の記録、修正、月次サマリーの生成機能を提供する。

技術要件

実行環境

• OS: Ubuntu (20.04 LTS以降)
• 言語: Python 3.10以上
• パッケージマネージャー: uv
• タイムゾーン: Asia/Tokyo (JST)

必要なPythonパッケージ

依存関係は pyproject.toml で管理されています。

click>=8.0.0       # CLIフレームワーク
pytz>=2021.3       # タイムゾーン処理
python-dateutil>=2.8.0  # 日付処理
tabulate>=0.9.0    # テーブル表示
pyperclip>=1.8.0   # クリップボード操作

ディレクトリ構造

kintai/
├── kintai.py          # メインスクリプト
├── pyproject.toml     # プロジェクト設定・依存関係
├── uv.lock            # 依存関係のロックファイル
├── tests/
│   └── test_kintai.py # テストファイル
└── README.md          # 使用方法ドキュメント

勤怠データは ~/.kintai/records.json に保存されます。

機能仕様

1. 勤怠管理機能

1.1 出勤記録 (kintai in)

動作仕様:

• コマンド実行時の現在時刻（JST）を出勤時刻として記録
• 既に当日の出勤記録がある場合は警告を表示し、上書き確認を求める
• 記録形式: YYYY-MM-DD HH:MM:SS (24時間表記)

出力例:

$ kintai in
出勤時刻を記録しました: 2025-01-10 09:00:15

1.2 退勤記録 (kintai out)

動作仕様:

• コマンド実行時の現在時刻（JST）を退勤時刻として記録
• 当日の出勤記録がない場合はエラーメッセージを表示
• 日をまたぐ勤務の場合も適切に処理（翌日の退勤として記録）
• 退勤時に勤務時間を自動計算して表示

出力例:

$ kintai out
退勤時刻を記録しました: 2025-01-10 18:30:45
本日の勤務時間: 9時間30分30秒

日またぎ処理:

• 退勤時刻が翌日以降の場合、適切に日付を記録
• 例: 1月10日 22:00出勤 → 1月11日 07:00退勤 = 9時間勤務

2. 勤怠時刻修正機能

2.1 記録修正 (kintai edit)

動作仕様:

• 指定した日付の出勤・退勤時刻を修正
• 対話形式で修正内容を入力

コマンド形式:

kintai edit --date YYYY-MM-DD [--in HH:MM] [--out HH:MM]

使用例:

# 対話形式での修正
$ kintai edit --date 2025-01-10
現在の記録:
  出勤: 09:00:15
  退勤: 18:30:45
新しい出勤時刻 (HH:MM) [変更しない場合はEnter]: 09:30
新しい退勤時刻 (HH:MM) [変更しない場合はEnter]: 19:00
記録を更新しました。

# 直接指定での修正
$ kintai edit --date 2025-01-10 --in 09:30 --out 19:00
記録を更新しました。

2.2 記録削除 (kintai delete)

動作仕様:

• 指定した日付の勤怠記録を削除
• 削除前に確認プロンプトを表示

コマンド形式:

kintai delete --date YYYY-MM-DD

3. 月別サマリー機能

3.1 月次レポート表示 (kintai summary)

動作仕様:

• 指定月の勤怠記録を表示
• 月の総勤務時間を計算
• デフォルトは現在月を表示

コマンド形式:

kintai summary [--month YYYY-MM]

出力形式（コンソール）:

2025年1月の勤怠記録
=====================================
日付        出勤時刻    退勤時刻    勤務時間
-----------  ----------  ----------  ----------
2025-01-08   09:00:15    18:30:45    9:30:30
2025-01-09   08:45:30    19:15:20    10:29:50
2025-01-10   09:30:00    19:00:00    9:30:00
=====================================
総勤務時間: 29時間30分20秒
勤務日数: 3日
平均勤務時間: 9時間50分6秒

3.2 クリップボードへのコピー (kintai summary --copy)

動作仕様:

• 月次レポートをMarkdown形式でクリップボードにコピー
• コピー成功時にメッセージを表示

Markdown出力形式:

# 2025年1月 勤怠記録

## 勤務詳細

| 日付 | 曜日 | 出勤時刻 | 退勤時刻 | 勤務時間 |
|------|------|----------|----------|----------|
| 2025-01-08 | 水 | 09:00:15 | 18:30:45 | 9:30:30 |
| 2025-01-09 | 木 | 08:45:30 | 19:15:20 | 10:29:50 |
| 2025-01-10 | 金 | 09:30:00 | 19:00:00 | 9:30:00 |

## 月次サマリー

- **総勤務時間**: 29時間30分20秒
- **勤務日数**: 3日
- **平均勤務時間**: 9時間50分6秒

4. その他の機能

4.1 現在の状態確認 (kintai status)

動作仕様:

• 現在の勤務状態（出勤中/退勤済み）を表示
• 出勤中の場合は経過時間を表示

出力例:

$ kintai status
状態: 出勤中
出勤時刻: 2025-01-10 09:00:15
経過時間: 3時間45分23秒

4.2 ヘルプ表示 (kintai --help)

動作仕様:

• 使用可能なコマンドと説明を表示

データ保存仕様

ファイル形式

• JSON形式でローカルに保存
• ファイルパス: ~/.kintai/records.json

データ構造

{
  "records": [
    {
      "date": "2025-01-10",
      "check_in": "2025-01-10T09:00:15+09:00",
      "check_out": "2025-01-10T18:30:45+09:00",
      "duration_seconds": 34230
    }
  ],
  "version": "1.0.0"
}

エラーハンドリング

想定されるエラーケース

1. 重複出勤エラー

   • メッセージ: "既に本日の出勤記録があります。上書きしますか？ [y/N]"

2. 出勤記録なしエラー

   • メッセージ: "本日の出勤記録がありません。先に 'kintai in' を実行してください。"

3. 無効な日付形式エラー

   • メッセージ: "日付の形式が正しくありません。YYYY-MM-DD形式で入力してください。"

4. データファイル破損エラー

   • メッセージ: "データファイルが破損しています。バックアップから復元するか、新規作成してください。"

インストール手順

# 1. リポジトリのクローンまたはファイルの配置
git clone [repository-url] kintai
cd kintai

# 2. uvのインストール（未インストールの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 依存パッケージのインストール
uv sync

# 4. 動作確認
uv run kintai --help

実行方法

# uvを通じて実行
uv run kintai in
uv run kintai out
uv run kintai status
uv run kintai summary

# テストの実行
uv run pytest

エイリアス設定（オプション）

頻繁に使用する場合は、シェルにエイリアスを設定すると便利です。

# ~/.bashrc または ~/.zshrc に追加
alias kintai='uv run --directory /path/to/kintai kintai'

テストケース

基本機能テスト

1. 通常の出退勤記録

   kintai in    # 09:00に実行
   kintai out   # 18:00に実行
   # 期待値: 9時間の勤務時間が記録される
   

2. 日またぎ勤務

   kintai in    # 22:00に実行
   kintai out   # 翌日07:00に実行
   # 期待値: 9時間の勤務時間が記録される
   

3. 記録修正

   kintai edit --date 2025-01-10 --in 09:30 --out 19:00
   # 期待値: 指定日の記録が更新される
   

4. 月次サマリー

   kintai summary --month 2025-01
   # 期待値: 1月の全勤怠記録と統計が表示される
   

拡張機能案（将来実装）

1. 休憩時間の記録

   • kintai break start / kintai break end

2. CSV/Excel出力

   • kintai export --format csv --month 2025-01

3. 勤務パターン設定

   • 定時設定、フレックスタイム設定

4. 統計分析機能

   • 週次レポート、残業時間分析

5. バックアップ/リストア機能

   • kintai backup / kintai restore

注意事項

• タイムゾーンは必ず日本時間（JST）で処理すること
• データファイルは定期的にバックアップを推奨
• クリップボード操作にはX11環境が必要（WSL2の場合は追加設定が必要）

ライセンス

MIT License（個人利用を想定）