データモデル

Nolto のデータは Project → Plan → Phase の階層構造で管理されます。すべての変更は Event として記録され、監査ログとして機能します。

エンティティ階層

Project
├── Plan
│   ├── Phase (0〜50件)
│   └── Event (イミュータブルな監査ログ)
├── Member (owner / member / viewer)
└── Contributor (git author マッピング)

Project

プロジェクトは、関連するプランをまとめるグループです。

フィールド	型	説明
`id`	UUID	プロジェクト ID
`name`	string	プロジェクト名
`description`	string?	説明
`repositoryUrl`	string?	リポジトリ URL
`accentColor`	string?	ブランドカラー（`#RRGGBB`）
`createdAt`	datetime	作成日時
`updatedAt`	datetime	更新日時

ロールと権限

権限	owner	member	viewer
プラン閲覧	Yes	Yes	Yes
プラン登録・更新	Yes	Yes	No
メンバー管理	Yes	No	No
プロジェクト設定変更	Yes	No	No
プロジェクト削除	Yes	No	No

Plan

プランは AI 開発ツールが生成した実装計画です。

フィールド	型	説明
`id`	UUID	プラン ID
`projectId`	UUID	所属プロジェクト
`rawTitle`	string	元のタイトル
`rawContent`	string	元の本文（Markdown）
`displayTitle`	string?	LLM 変換後のタイトル
`displaySummary`	string?	LLM 変換後の要約
`displayBody`	object?	LLM 変換後の構造化データ（ReadablePlan）
`status`	enum	ステータス
`sourceKind`	enum	登録元（`file` / `api` / `mcp` / `manual`）
`sourcePath`	string?	ファイルパス
`sourceUrl`	string?	URL
`sourceHash`	string?	コンテンツハッシュ
`assigneeUserId`	UUID?	担当者（ユーザー）
`plannedStartAt`	datetime?	予定開始日時
`plannedEndAt`	datetime?	予定終了日時
`completedAt`	datetime?	完了日時
`discardedAt`	datetime?	破棄日時
`transformStatus`	string?	最新の変換ステータス
`createdAt`	datetime	作成日時
`updatedAt`	datetime	更新日時

Phase

フェーズはプランのサブタスクです。順序付きで管理されます。

フィールド	型	説明
`id`	UUID	フェーズ ID
`planId`	UUID	所属プラン
`orderIndex`	int	表示順（0始まり）
`rawTitle`	string	元のタイトル
`rawContent`	string	元の詳細
`displayTitle`	string?	LLM 変換後のタイトル
`displaySummary`	string?	LLM 変換後の要約
`status`	enum	ステータス
`plannedStartAt`	datetime?	予定開始日時
`plannedEndAt`	datetime?	予定終了日時
`completedAt`	datetime?	完了日時
`discardedAt`	datetime?	破棄日時

ステータス遷移

ステータス値

ステータス	ラベル	説明
`not_started`	未着手	まだ作業を始めていない
`in_progress`	進行中	現在作業中
`done`	完了	完了した
`discarded`	破棄	進めないことにした

許可される遷移

From	To
`not_started`	`in_progress`, `discarded`
`in_progress`	`done`, `discarded`, `not_started`
`done`	`in_progress`
`discarded`	`not_started`

許可されていない遷移をリクエストすると 400 Bad Request が返ります。

フェーズからプランへの自動派生

フェーズのステータスを更新すると、親プランのステータスが以下のルールで自動的に再計算されます:

フェーズが 0 件 → not_started
全フェーズが discarded → discarded
discarded 以外の全フェーズが done → done
いずれかのフェーズが in_progress → in_progress
上記以外 → not_started

Contributor

Git の author 情報をプランに紐づけるエンティティです。

フィールド	型	説明
`id`	UUID	コントリビューター ID
`projectId`	UUID	所属プロジェクト
`gitUserName`	string?	Git ユーザー名
`gitUserEmail`	string?	Git メールアドレス
`matchedUserId`	UUID?	一致した Nolto ユーザー

プラン登録時に git.userEmail を指定すると、同じメールアドレスの Nolto ユーザーが自動的にマッチングされます。

Event（監査ログ）

すべてのプラン・フェーズの変更は不変（イミュータブル）なイベントとして記録されます。

イベントタイプ

イベント	説明
`plan_registered`	プランが登録された
`status_changed`	プランのステータスが変更された
`phase_status_changed`	フェーズのステータスが変更された
`llm_transform_queued`	LLM 変換がキューに追加された
`llm_transform_completed`	LLM 変換が完了した
`llm_transform_failed`	LLM 変換が失敗した
`llm_transform_retry`	LLM 変換がリトライされた
`assignee_changed`	担当者が変更された

イベントの構造

フィールド	型	説明
`id`	UUID	イベント ID
`planId`	UUID	対象プラン
`phaseId`	UUID?	対象フェーズ（フェーズイベントの場合）
`eventType`	enum	イベントタイプ
`fromStatus`	enum?	変更前ステータス
`toStatus`	enum?	変更後ステータス
`message`	string?	メッセージ
`actorUserId`	UUID?	操作者
`createdAt`	datetime	発生日時

ReadablePlan（LLM 変換出力）

LLM が生成する構造化データです。プランの displayBody フィールドに格納されます。

フィールド	型	説明
`displayTitle`	string	ビジネス向けタイトル
`summary`	string	要約（1〜2文）
`background`	string	背景・経緯
`goal`	string	目標
`tasks`	string[]	主要タスク一覧
`impact`	string[]	ビジネスへの影響
`reviewPoints`	string[]	レビュー確認ポイント
`risks`	string[]	リスク・懸念事項
`phases[].displayTitle`	string	フェーズのビジネス向けタイトル
`phases[].summary`	string	フェーズの要約