數據模型文檔目錄

本目錄包含所有 Entity 的詳細數據模型定義。

Entity 列表

Entity	文檔	說明	狀態
User	user-role.md	用戶與角色	🟡 規劃中
Product	product.md	產品與商品	🟡 規劃中
Order	order.md	訂單	🟡 規劃中
OrderItem	order-item.md	訂單項目	🟡 規劃中
Customer	customer.md	客戶	🟡 規劃中
Payment	payment.md	支付記錄	🟡 規劃中
Invoice	invoice.md	發票	🟡 規劃中

---

Entity Relationship Diagram (ER圖)

（待補充：使用 Mermaid 或其他工具生成 ER 圖）

---

數據模型設計原則

1. 多租戶隔離

• 所有主要 Entity 都必須包含 tenant_id 欄位
• tenant_id 必須建立索引
• 所有查詢都必須包含 tenant_id 過濾條件

2. 審計追蹤

所有主要 Entity 應包含以下欄位：

{
  createdAt: timestamp,    // 創建時間
  createdBy: string,       // 創建者 ID
  updatedAt: timestamp,    // 最後更新時間
  updatedBy: string,       // 最後更新者 ID
  version: integer         // 樂觀鎖版本號（可選）
}

3. 軟刪除

重要的 Entity 使用軟刪除（而非物理刪除）：

{
  deletedAt: timestamp | null,  // 刪除時間（null 表示未刪除）
  deletedBy: string | null       // 刪除者 ID
}

4. 命名規範

• 表名：使用複數形式（如 orders、customers）
• 欄位名：使用 camelCase（如 firstName、createdAt）
• 外鍵：使用 {entity}Id 格式（如 customerId、tenantId）

---

Entity 文檔模板

# {Entity 名稱}

## 概述
（簡述此 Entity 的業務用途）

---

## 表名
\`{table_name}\`

---

## 欄位定義

| 欄位名 | 類型 | 必填 | 說明 | 預設值 | 索引 |
|--------|------|------|------|--------|------|
| id | UUID | Yes | 主鍵 | auto | PK |
| tenantId | UUID | Yes | 租戶 ID | - | FK, Index |
| field1 | string | Yes | 欄位說明 | - | - |
| field2 | integer | No | 欄位說明 | 0 | - |
| createdAt | timestamp | Yes | 創建時間 | now() | Index |
| createdBy | UUID | Yes | 創建者 ID | - | FK |
| updatedAt | timestamp | Yes | 更新時間 | now() | - |
| updatedBy | UUID | Yes | 更新者 ID | - | FK |
| deletedAt | timestamp | No | 刪除時間 | null | Index |
| deletedBy | UUID | No | 刪除者 ID | null | FK |

---

## 關聯關係

### 一對多 (One-to-Many)
- **父實體**: `ParentEntity` (一)
- **關聯欄位**: `parentId`
- **說明**: 一個父實體可以有多個此實體

### 多對一 (Many-to-One)
- **子實體**: `ChildEntity` (多)
- **關聯欄位**: `childId`
- **說明**: 多個此實體屬於一個子實體

### 多對多 (Many-to-Many)
- **關聯表**: `entity_relation`
- **說明**: 透過中間表關聯

---

## 約束條件

### Unique 約束
- `(tenantId, field1)`: 同一租戶內 field1 不可重複

### Check 約束
- `field2 >= 0`: field2 必須大於等於 0

### Foreign Key 約束
- `tenantId` references `tenants(id)` ON DELETE CASCADE
- `createdBy` references `users(id)` ON DELETE SET NULL

---

## 索引策略

| 索引名稱 | 欄位 | 類型 | 用途 |
|----------|------|------|------|
| idx_tenant | tenantId | B-tree | 多租戶過濾 |
| idx_created_at | createdAt | B-tree | 日期範圍查詢 |
| idx_status | status | B-tree | 狀態過濾 |
| idx_composite | (tenantId, status, createdAt) | Composite | 複合查詢優化 |

---

## TypeScript 類型定義

\`\`\`typescript
export interface Entity {
  id: string;
  tenantId: string;
  field1: string;
  field2?: number;
  createdAt: Date;
  createdBy: string;
  updatedAt: Date;
  updatedBy: string;
  deletedAt?: Date | null;
  deletedBy?: string | null;
}

export interface CreateEntityDto {
  field1: string;
  field2?: number;
}

export interface UpdateEntityDto {
  field1?: string;
  field2?: number;
}
\`\`\`

---

## 範例數據

### 正常記錄
\`\`\`json
{
  "id": "entity-001",
  "tenantId": "tenant-abc",
  "field1": "value1",
  "field2": 100,
  "createdAt": "2025-10-31T10:30:00Z",
  "createdBy": "user-001",
  "updatedAt": "2025-10-31T10:30:00Z",
  "updatedBy": "user-001",
  "deletedAt": null,
  "deletedBy": null
}
\`\`\`

### 已刪除記錄
\`\`\`json
{
  "id": "entity-002",
  "tenantId": "tenant-abc",
  "field1": "value2",
  "field2": 50,
  "createdAt": "2025-10-30T10:00:00Z",
  "createdBy": "user-001",
  "updatedAt": "2025-10-31T09:00:00Z",
  "updatedBy": "user-002",
  "deletedAt": "2025-10-31T12:00:00Z",
  "deletedBy": "user-002"
}
\`\`\`

---

## 多租戶隔離策略

### 資料表層級
- 每筆記錄都包含 `tenantId`
- 使用 Row-Level Security (RLS) 或 ORM 自動過濾

### 應用層級
\`\`\`typescript
// ✅ 正確：自動附加 tenantId 過濾
const entities = await db.entity.findMany({
  where: {
    tenantId: currentUser.tenantId,
    status: 'active'
  }
});

// ❌ 錯誤：缺少 tenantId 過濾
const entities = await db.entity.findMany({
  where: { status: 'active' }
});
\`\`\`

---

## 效能考量

### 查詢優化
- 使用複合索引覆蓋常見查詢模式
- 避免 SELECT * （僅選擇需要的欄位）
- 使用分頁減少大量數據查詢

### 寫入優化
- 批量插入使用 Batch Insert
- 更新使用樂觀鎖避免並發衝突

---

## 相關文檔

- [API 規格](../api-specs/{domain}.md)
- [User Stories](../user-stories/epic-N/)
- [ER 圖](entity-relationship-diagram.md)

---

審查檢查清單

提交數據模型文檔前，請確認：

• 包含 tenantId 欄位且建立索引
• 包含審計欄位（createdAt, createdBy, updatedAt, updatedBy）
• 重要 Entity 支援軟刪除（deletedAt, deletedBy）
• 所有關聯關係已明確定義
• 索引策略已規劃
• 約束條件已定義
• TypeScript 類型定義完整
• 提供範例數據
• 多租戶隔離策略已說明

---

最後更新: 2025-10-31