Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):段階的な改善の出発点。対処済みの課題も含む

Expand Down
191 changes: 47 additions & 144 deletions docs/ERD.md
Original file line number Diff line number Diff line change
@@ -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) を参照してください。
Loading