DATABASE_SCHEMA

# 数据库模式速查表

> &#128680; **AI助手开发前必读** - 每次涉及数据库操作时，必须先查阅此文档！

---

## &#128308; 分区表清单（CRITICAL）

**以下表采用 PostgreSQL LIST 分区，按 `company_id` 分区：**

| 基础表名 | 默认分区 | 分区命名规则 | 分区键 |
|----------|----------|--------------|--------|
| `saas_users` | `saas_users_default` | `saas_users_{company_id}` | `company_id` |
| `saas_orders` | `saas_orders_default` | `saas_orders_{company_id}` | `company_id` |
| `salary_slips` | `salary_slips_default` | `salary_slips_{company_id}` | `company_id` |

### 分区表特征识别

```typescript
// 分区表的特征：
// 1. 表名带有 _default 后缀的默认分区
// 2. 主键是复合主键：PRIMARY KEY (id, company_id)
// 3. 存在以 company_id 命名的分区表

// 示例：salary_slips 分区表结构
export const salarySlipsDefault = pgTable("salary_slips_default", {
  id: varchar().notNull(),
  companyId: varchar("company_id").notNull(),  // 分区键
  // ... 其他字段
}, (table) => [
  primaryKey({ columns: [table.id, table.companyId] }),  // 复合主键
]);
```

---

## ⚠️ 分区表开发约束

### 1. 查询约束
```typescript
// ✅ 正确 - 带 company_id 过滤，触发分区裁剪
await db.select()
  .from(salarySlips)
  .where(and(
    eq(salarySlips.companyId, companyId),  // 必须带分区键
    eq(salarySlips.status, 'PUBLISHED')
  ));

// ❌ 错误 - 不带 company_id，全表扫描
await db.select()
  .from(salarySlips)
  .where(eq(salarySlips.status, 'PUBLISHED'));
```

### 2. 插入约束
```typescript
// ✅ 正确 - 插入时必须包含 company_id
await db.insert(salarySlips).values({
  companyId,  // 必须有
  // ... 其他字段
});

// ❌ 错误 - 缺少 company_id
await db.insert(salarySlips).values({
  // 没有 companyId
});
```

### 3. Schema 导出约束
```typescript
// 在 schema.ts 底部的导出区域：

// ✅ 正确 - 使用默认分区作为别名
export const salarySlips = saasSalarySlips;  // 或 salarySlipsDefault
export const saasUsers = saasUsersDefault;
export const saasOrders = saasOrdersDefault;

// ❌ 错误 - 直接导出分区表定义
export const salarySlips = pgTable("salary_slips", {...});  // 不存在这个表！
```

### 4. 类型导出约束
```typescript
// ✅ 正确 - 从实际表导出类型
export type SalarySlip = InferSelectModel<typeof saasSalarySlips>;
export type InsertSalarySlip = InferInsertModel<typeof saasSalarySlips>;

// ❌ 错误 - 从不存在的表导出
export type SalarySlip = InferSelectModel<typeof salarySlips>;  // 如果 salarySlips 是别名可能有问题
```

---

## &#128202; 非分区表清单

以下表**不是**分区表，可以正常操作：

| 表名 | 说明 |
|------|------|
| `saas_tenants` | 租户表 |
| `saas_companies` | 企业表 |
| `employees` | 员工表 |
| `roles` | 角色表 |
| `user_roles` | 用户角色关联表 |
| `permissions` | 权限表 |
| `apps` | 应用表 |
| `company_app_instances` | 企业应用实例表 |
| `unified_configs` | 统一配置表 |
| `partners` | 合作伙伴表 |
| `open_api_keys` | API密钥表 |
| `open_apps` | 开放平台应用表 |
| `operation_logs` | 操作日志表 |

---

## &#128736;️ 开发前 Checklist

每次涉及数据库操作时，必须完成以下检查：

- [ ] 1. 确认操作的表是否在分区表清单中
- [ ] 2. 如果是分区表，查询是否包含 `company_id` 过滤
- [ ] 3. 如果是分区表，插入是否包含 `company_id` 字段
- [ ] 4. 检查 Schema 导出是否使用正确的表名
- [ ] 5. 使用 Manager 类而非直接 Drizzle 操作

---

## &#128193; 文件位置

| 文件 | 说明 |
|------|------|
| `src/storage/database/shared/schema.ts` | **正确的** Schema 文件 |
| ~~`src/db/schema.ts`~~ | 废弃的 Schema 文件，不要使用 |
| `src/infrastructure/database/shared/schema.ts` | 旧版 Schema，部分表仍使用 |

---

## &#128295; Manager 类列表

所有数据访问应通过 Manager 类进行：

| Manager 类 | 文件位置 | 对应表 |
|------------|----------|--------|
| `SaasUserManager` | `saasUserManager.ts` | `saas_users` |
| `SaasCompanyManager` | `saasCompanyManager.ts` | `saas_companies` |
| `SaasTenantManager` | `saasTenantManager.ts` | `saas_tenants` |
| `SalarySlipManager` | `salarySlipManager.ts` | `salary_slips` |
| `EmployeeManager` | `employeeManager.ts` | `employees` |
| `PartnerManager` | `partnerManager.ts` | `partners` |
| `OpenApiKeyManager` | `openApiKeyManager.ts` | `open_api_keys` |

---

## &#128680; 常见错误示例

### 错误1：从不存在的表导出类型
```typescript
// ❌ 错误
export type SaasCompany = InferSelectModel<typeof saasCompanies>;
// 如果 saasCompanies 是别名且指向分区表，可能出问题

// ✅ 正确
export type SaasCompany = InferSelectModel<typeof saasCompaniesDefault>;
// 或直接从实际表导出
```

### 错误2：查询不带分区键
```typescript
// ❌ 错误 - 全表扫描所有分区
const allSlips = await db.select().from(salarySlips);

// ✅ 正确 - 只扫描指定分区
const slips = await db.select()
  .from(salarySlips)
  .where(eq(salarySlips.companyId, companyId));
```

### 错误3：创建新表时未考虑分区
```typescript
// ❌ 错误 - 大表未分区
export const bigDataTable = pgTable("big_data", {
  id: varchar().primaryKey(),  // 单独主键
  companyId: varchar("company_id"),
  // ...
});

// ✅ 正确 - 考虑是否需要分区
// 如果数据量大且按 company_id 查询，应使用分区表
// 需要用原生 SQL 创建分区表
```

---

*最后更新: 2025-01-26*