---
title: "作業時間追跡"
description: "タイマー・手動ログ・工数サマリー"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.koyori.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 作業時間追跡

## 概要

タスクにかけた作業時間を、タイマーと手動ログで記録し、見積との差をサマリーで返す機能である。[コア](https://docs.koyori.app/dev/features/tasks/core)の機能に依存する。作業記録の合計は、[山積み](https://docs.koyori.app/dev/features/tasks/workload)の残工数の計算に使う。タスク詳細は見積（`estimated_minutes`）を表示する。

## 振る舞い

### タイマー

同じ利用者が同じタスクに同時に起動できるタイマーは 1 つである。

タイマーを停止すると `task_timers` の行を消し、経過時間を `time_logs` へ 1 行入れる。この 2 つは同じトランザクションで行う。

- `logged_minutes` は経過秒数を分へ切り上げた値で、最低 1 分である
- `logged_at` は停止時刻を UTC+9 に固定して取った日付である。利用者のタイムゾーンは見ない
- `note` は NULL で入る。停止時にメモを受け取る引数は無いので、後から `PUT` で足す

### 工数サマリー

`actual_minutes` は担当者以外の記録も含むタスク単位の合計である。[スケジュール](https://docs.koyori.app/dev/features/tasks/schedule)の `logged_minutes` も同じ定義にしている。

`estimated_minutes` が無いタスクでは `remaining_minutes` が `null`、`is_over` が `false` になる。`remaining_minutes` は実績が見積を超えると負の値になる。

## データ

### `time_logs`

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `id` | UUID | PK | |
| `task_id` | UUID | NOT NULL, FK→tasks CASCADE | |
| `user_id` | UUID | NOT NULL, FK→users CASCADE | |
| `logged_minutes` | INT | NOT NULL CHECK (> 0) | 分単位で保持し、表示時に h/m へ変換する |
| `logged_at` | DATE | NOT NULL | 作業日 |
| `note` | TEXT | NULLABLE | |
| `created_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

### `task_timers`

動いているタイマーの表である。

| 列 | 型 | 制約 | 説明 |
|---|---|---|---|
| `task_id` | UUID | NOT NULL, FK→tasks CASCADE, PK(task_id, user_id) | |
| `user_id` | UUID | NOT NULL, FK→users CASCADE, PK(task_id, user_id) | |
| `started_at` | TIMESTAMPTZ | NOT NULL DEFAULT now() | |

列の定義は [m20260520000000_initial_schema.rs](https://github.com/koyori-app/task/blob/main/apps/backend/migration/src/m20260520000000_initial_schema.rs) にある。

## API

URL 基底パスは `/v1/tenants/{tenant_id}/projects/{project_id}` である。

| メソッド | パス | 説明 |
|---|---|---|
| `GET` | `/tasks/{id}/time-logs` | ログ一覧（作業日の新しい順） |
| `POST` | `/tasks/{id}/time-logs` | 手動ログ追加 |
| `PUT` | `/tasks/{id}/time-logs/{log_id}` | ログ編集（`clear_note` でメモを消す） |
| `DELETE` | `/tasks/{id}/time-logs/{log_id}` | 削除 |
| `POST` | `/tasks/{id}/timer/start` | タイマー開始。既に動いていれば 409 |
| `POST` | `/tasks/{id}/timer/stop` | タイマー停止とログ生成。生成したログ（`TimeLogResponse`）を返す。動いていなければ 409 |
| `GET` | `/tasks/{id}/timer/status` | 呼び出した本人のタイマー状態 |
| `GET` | `/tasks/{id}/time-logs/summary` | 工数サマリー（`TimeLogSummaryResponse`） |

`GET /tasks/{id}/timer/status` は、タイマーが動いていないとき `is_running` が `false` で、`started_at` と `elapsed_minutes` は `null` である。

## 認可

| 操作 | 誰が | スコープ |
|---|---|---|
| ログ一覧・サマリー・タイマー状態の取得 | プロジェクトに入れる人 | `read:task` |
| 手動ログ追加・タイマーの開始と停止 | プロジェクトに入れる人 | `write:task` |
| ログ編集 | 自分のログのみ | `write:task` |
| ログ削除 | 自分、またはテナントオーナー | `write:task` |

## 未実装と既知の制限

タイマーと作業ログの画面が無い。計画している画面は次のとおりである。

- タスク詳細の右ペインにタイマーのウィジェットを置き、見積・実績と、開始ボタンまたは経過時間つきの停止ボタンを出す
- 起動中はリアルタイムの経過時間を表示する
- 停止時に任意のメモを入力してからログを保存する

Source: https://docs.koyori.app/dev/features/tasks/time-tracking/index.mdx
