From 12935a32a9c1f20bf095d69f707c49aa617a2f3e Mon Sep 17 00:00:00 2001 From: Czmirror Date: Sat, 14 Nov 2026 01:57:26 +0900 Subject: [PATCH] =?UTF-8?q?=E7=8F=BE=E8=A1=8CPrisma=E3=82=B9=E3=82=AD?= =?UTF-8?q?=E3=83=BC=E3=83=9E=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B=E3=81=A6?= =?UTF-8?q?ER=E5=9B=B3=E3=82=92=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- docs/ERD.md | 191 +++++++++++++--------------------------------------- 2 files changed, 48 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index c968596..ba4aa7e 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,7 @@ pnpm dev:web - [API仕様](docs/API.md):状態遷移、認証・認可、入力・エラーの契約 - [ローカル運用手順](docs/runbook.md):環境設定、schema適用、初期管理者の作成 - [現行Prismaスキーマ](apps/api/prisma/schema.prisma):実装しているモデルと関連 -- [ER図(現行Prismaへの更新待ち)](docs/ERD.md):旧設計資料。teamsテーブルや外部キーなどに現行実装との差があるため、現行DBの説明には上記スキーマを参照 +- [現行データベースのER図](docs/ERD.md) - [要求仕様](docs/PRD.md)・[非機能要求](docs/NFR.md)・[実装ガイド](docs/IMPLEMENTATION_GUIDE.md):設計資料。現在の実装状況はコードと個別仕様・検証記録も併せて確認 - [全体レビュー記録](docs/work/harness-source-review/review.md):段階的な改善の出発点。対処済みの課題も含む diff --git a/docs/ERD.md b/docs/ERD.md index e19984c..61135f7 100644 --- a/docs/ERD.md +++ b/docs/ERD.md @@ -1,168 +1,71 @@ -# ERD: MiniFlow (v0.1) +# MiniFlowのER図 -## 1. 目的 -MiniFlowのMVPで利用するデータモデルを定義する。\ -本書は `PRD` / `NFR` / `IMPLEMENTATION_GUIDE` と整合するDB設計の基準とする。 +現行のPostgreSQLには `users`、`requests`、`approvals` の3テーブルがあります。 +テーブルと列は [Prismaスキーマ](../apps/api/prisma/schema.prisma)、DBに適用される制約と索引は +[マイグレーション](../apps/api/prisma/migrations) を参照してください。 -## 2. 対象テーブル(MVP) -- `teams` -- `users` -- `requests` -- `approvals` - -## 3. ER図(Mermaid) ```mermaid erDiagram - TEAMS ||--o{ USERS : has - TEAMS ||--o{ REQUESTS : owns - USERS ||--o{ REQUESTS : creates - REQUESTS ||--o{ APPROVALS : records - USERS ||--o{ APPROVALS : acts + requests ||..o{ approvals : "承認履歴を持つ" - TEAMS { + users { uuid id PK - text name - timestamptz created_at - timestamptz updated_at - } - - USERS { - uuid id PK - uuid team_id FK - text email - text display_name + text email UK + integer sessionVersion + text passwordHash + text displayName "NULL可" + text language + text teamId text role - timestamptz created_at - timestamptz updated_at + boolean isActive + timestamp createdAt + timestamp updatedAt } - REQUESTS { + requests { uuid id PK - uuid team_id FK - uuid created_by FK + integer version + text teamId + uuid createdBy text title text body - text status - timestamptz deleted_at - timestamptz created_at - timestamptz updated_at + RequestStatus status + timestamp createdAt + timestamp updatedAt + timestamp deletedAt "NULL可" } - APPROVALS { + approvals { uuid id PK - uuid request_id FK - uuid acted_by FK - text action_type - text reason - timestamptz created_at + uuid requestId FK + uuid actedBy + ApprovalActionType actionType + text reason "NULL可" + timestamp createdAt } ``` -記法メモ: -- `||--o{` は 1対多(1側に必須1、N側は0以上)を示す -- `records` / `acts` はリレーションの説明ラベルで、テーブル名ではない - - `REQUESTS ||--o{ APPROVALS : records` は「1つのRequestが複数Approval履歴を持つ」 - - `USERS ||--o{ APPROVALS : acts` は「1人のUserが複数Approval操作を行う」 - -## 4. テーブル定義 -### 4.1 teams -- `id uuid PK` -- `name text not null` -- `created_at timestamptz not null default now()` -- `updated_at timestamptz not null default now()` +## 関連と制約 -### 4.2 users -- `id uuid PK` -- `team_id uuid not null references teams(id)` -- `email text not null unique` -- `display_name text not null` -- `role text not null`\ - 例: `member`, `approver`, `admin` -- `created_at timestamptz not null default now()` -- `updated_at timestamptz not null default now()` +- `approvals.requestId` は `requests.id` を参照する必須の外部キーです。申請をDBから物理削除すると、対応する承認履歴も連鎖削除されます。 +- `requests.createdBy` と `approvals.actedBy` は利用者IDを保持します。どちらにも `users` への外部キー制約はありません。 +- `users.teamId` と `requests.teamId` はチームの識別子を文字列で保持します。チーム用のテーブルはなく、チーム単位のアクセス制御はアプリケーションが担当します。 +- `requests.status` の値は `Draft`、`Pending`、`Approved`、`Rejected`、`Deleted` です。通常の申請削除は `Deleted` と `deletedAt` による論理削除で、両列の整合性はアプリケーションが管理します。 +- `approvals.actionType` の値は `Approved` と `Rejected` です。差し戻し後に再提出された申請を同じ利用者が再度決裁できるよう、`requestId` と `actedBy` の組に一意制約はありません。 -### 4.3 requests -- `id uuid PK` -- `team_id uuid not null references teams(id)` -- `created_by uuid not null references users(id)` -- `title text not null` -- `body text not null` -- `status text not null`\ - 許容値: `Draft`, `Pending`, `Approved`, `Rejected`, `Deleted` -- `deleted_at timestamptz null` -- `created_at timestamptz not null default now()` -- `updated_at timestamptz not null default now()` - -### 4.4 approvals -- `id uuid PK` -- `request_id uuid not null references requests(id)` -- `acted_by uuid not null references users(id)` -- `action_type text not null`\ - 許容値: `Approved`, `Rejected` -- `reason text null` -- `created_at timestamptz not null default now()` - -## 5. 制約(重要) -### 5.1 status / deleted_at 整合制約 -- `status = 'Deleted' <=> deleted_at IS NOT NULL` -- `status != 'Deleted' <=> deleted_at IS NULL` - -実装例(CHECK): -```sql -CHECK ( - (status = 'Deleted' AND deleted_at IS NOT NULL) - OR - (status <> 'Deleted' AND deleted_at IS NULL) -) -``` - -### 5.2 approvals の履歴制約 -- `approvals` は insert only(更新・削除しない) -- `action_type` は `Approved` / `Rejected` のみ - -### 5.3 重複承認の抑止(MVP) -同一Requestに対する同一actorの重複決裁を禁止する。 -```sql -CREATE UNIQUE INDEX uq_approvals_request_actor - ON approvals (request_id, acted_by); -``` - -## 6. インデックス方針(MVP) -### 6.1 requests -- 一覧検索用: -```sql -CREATE INDEX idx_requests_team_status_created_at - ON requests (team_id, status, created_at DESC); -``` -- 削除除外検索を高速化: -```sql -CREATE INDEX idx_requests_not_deleted - ON requests (team_id, created_at DESC) - WHERE deleted_at IS NULL; -``` - -### 6.2 approvals -- 履歴取得用: -```sql -CREATE INDEX idx_approvals_request_created_at - ON approvals (request_id, created_at ASC); -``` +## 索引 -## 7. 取得ルール(API観点) -- 一覧APIはデフォルトで `deleted_at IS NULL` を適用(Deleted非表示) -- 詳細APIはDeletedを取得可能(監査用途) -- Request詳細取得時はApproval履歴を `created_at ASC` で返す +| テーブル | 列(索引順) | 種類 | +| --- | --- | --- | +| `users` | `email` | 一意 | +| `users` | `teamId`, `role`, `isActive` | 複合 | +| `requests` | `teamId`, `status`, `createdAt` | 複合 | +| `approvals` | `requestId`, `createdAt` | 複合 | -## 8. UUID方針 -- 主キーは全テーブル `uuid` -- 生成方式は `UUIDv7` 推奨 -- 導入難度が高い場合はMVPとして `gen_random_uuid()` で開始可 +各テーブルの主キー `id` にも一意索引があります。 -## 9. 将来拡張メモ -- 多段承認対応時は `approvals` に `step` / `sequence` 追加を検討 -- revise履歴が必要になった場合は `action_type='Revised'` を導入 +## 更新とセッションの世代 -## 10. 関連ドキュメント -- [PRD.md](/Users/admin/WebPortfolio/MiniFlow/docs/PRD.md) -- [NFR.md](/Users/admin/WebPortfolio/MiniFlow/docs/NFR.md) -- [IMPLEMENTATION_GUIDE.md](/Users/admin/WebPortfolio/MiniFlow/docs/IMPLEMENTATION_GUIDE.md) +`requests.version` は申請の競合検出に使う番号です。保存時に読み出し時点の番号と照合します。 +`users.sessionVersion` はログインセッションの失効判定に使う番号です。パスワード変更時に更新されます。 +どちらも初期値は `0` です。APIの振る舞いは [API仕様](API.md) を参照してください。