Metadata-Version: 2.4
Name: kintai
Version: 0.1.0
Summary: 勤怠管理CLIツール
Project-URL: Repository, https://github.com/taison-tsukada/kintai
Author: TaisonTsukada
License: MIT
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: pyperclip>=1.8.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pytz>=2021.3
Requires-Dist: tabulate>=0.9.0
Description-Content-Type: text/markdown

# 勤怠管理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`)

**動作仕様:**
- 指定した日付の出勤・退勤時刻を修正
- 対話形式で修正内容を入力

**コマンド形式:**
```bash
kintai edit --date YYYY-MM-DD [--in HH:MM] [--out HH:MM]
```

**使用例:**
```bash
# 対話形式での修正
$ 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`)

**動作仕様:**
- 指定した日付の勤怠記録を削除
- 削除前に確認プロンプトを表示

**コマンド形式:**
```bash
kintai delete --date YYYY-MM-DD
```

### 3. 月別サマリー機能

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

**動作仕様:**
- 指定月の勤怠記録を表示
- 月の総勤務時間を計算
- デフォルトは現在月を表示

**コマンド形式:**
```bash
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出力形式:**
```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`

### データ構造
```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. **データファイル破損エラー**
   - メッセージ: "データファイルが破損しています。バックアップから復元するか、新規作成してください。"

## インストール手順

```bash
# 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
```

### 実行方法

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

# テストの実行
uv run pytest
```

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

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

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

## テストケース

### 基本機能テスト

1. **通常の出退勤記録**
   ```bash
   kintai in    # 09:00に実行
   kintai out   # 18:00に実行
   # 期待値: 9時間の勤務時間が記録される
   ```

2. **日またぎ勤務**
   ```bash
   kintai in    # 22:00に実行
   kintai out   # 翌日07:00に実行
   # 期待値: 9時間の勤務時間が記録される
   ```

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

4. **月次サマリー**
   ```bash
   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（個人利用を想定）