AIclinicalresearch/docs/04-开发规范/09-数据库开发规范.md

# <20>唳旿摨枏<E691A8><E69E8F>𤏸<EFBFBD><F0A48FB8>?

> <EFBFBD><EFBFBD>𧋦: v1.0
> <EFBFBD>湔鰵<EFBFBD>交<EFBFBD>: 2026-01-11
> 蝻硋<EFBFBD><EFBFBD>峕艶: 2026-01-11 <20>唳旿摨㮖<E691A8><E3AE96><EFBFBD><EFBFBD><EFBFBD>餌<EFBFBD>

---

## 1. <20>詨<EFBFBD><E8A9A8>笔<EFBFBD>

### 1.1 摰匧<E691B0>蝚砌<E89D9A>

```
<EFBFBD>𩤃<EFBFBD> 暺<><E69ABA>瘜訫<E7989C>嚗帋遙雿閙㺭<E99699>桀<EFBFBD><E6A180>滢<EFBFBD><E6BBA2>㵪<EFBFBD>敹<EFBFBD>◆<EFBFBD><E29786><EFBFBD>隞踝<E99A9E>
```

### 1.2 蝳<>迫雿輻鍂<E8BCBB><E98D82>暒<EFBFBD>拙𦶢隞?

| <20>賭誘 | <20>梢埯蝑厩漣 | 霂湔<E99C82> |
|------|----------|------|
| `prisma db push --force-reset` | <20>𣞁 **<EFBFBD><EFBFBD><EFBFBD>** | 隡𡁜<E99AA1><F0A1819C>斗<EFBFBD><E69697>㗇㺭<E39787>桀<EFBFBD><E6A180>鱲risma蝞∠<E89D9E><E288A0><EFBFBD>笆鞊?|
| `prisma migrate reset` | <20>𣞁 **<EFBFBD><EFBFBD><EFBFBD>** | <20>滨蔭<E6BBA8>港葵<E6B8AF>唳旿摨?|
| `DROP DATABASE` | <20>𣞁 **<EFBFBD><EFBFBD><EFBFBD>** | <20>𣳇膄<F0A3B387>港葵<E6B8AF>唳旿摨?|
| `TRUNCATE TABLE` | <20><> 擃?| 皜<>征銵冽㺭<E586BD>?|

### 1.3 <20>刻<EFBFBD><E588BB><EFBFBD><EFBFBD><EFBFBD>典𦶢隞?

| <20>賭誘 | <20>券<EFBFBD>?| 摰匧<E691B0><E58CA7>?|
|------|------|--------|
| `prisma migrate dev` | 撘<><E69298>𤑳㴓憓<E3B493><E68693>蝘?| <20>?摰匧<E691B0> |
| `prisma migrate deploy` | <20>煺漣<E785BA>臬<EFBFBD>餈<EFBFBD>宏 | <20>?摰匧<E691B0> |
| `prisma db push` (<28>?--force-reset) | <20>峕郊schema<6D>唳㺭<E594B3>桀<EFBFBD> | <20>𩤃<EFBFBD> 靚冽<E99D9A>雿輻鍂 |
| `prisma generate` | <20><><EFBFBD>摰Ｘ<E691B0>蝡?| <20>?摰匧<E691B0> |

---

## 2. <20>唳旿摨枏<E691A8>隞質<E99A9E><E8B3AA>?

### 2.1 憭<>遢<EFBFBD>賭誘

```bash
# <20>朞<EFBFBD> Docker 憭<>遢嚗<E981A2>綫<EFBFBD>琜<EFBFBD>
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > backup_$(date +%Y%m%d_%H%M%S).sql

# PowerShell <20><>𧋦
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > "backup_$timestamp.sql"
```

### 2.2 憭<>遢<EFBFBD>嗆㦤

| <20>嗆㦤 | <20>臬炏敹<E7828F>◆ |
|------|----------|
| <20>扯<EFBFBD>隞颱<E99A9E> `prisma migrate` <20>?| <20>?敹<>◆ |
| <20>扯<EFBFBD> `prisma db push` <20>?| <20>?敹<>◆ |
| <20>函蔡<E587BD>啁<EFBFBD>鈭抒㴓憓<E3B493><E68693> | <20>?敹<>◆ |
| 瘥𤩺𠯫<F0A4A9BA>芸𢆡憭<F0A286A1>遢 | <20>?<3F>刻<EFBFBD> |
| <20>滚之<E6BB9A>蠘<EFBFBD><E8A098>穃<EFBFBD><E7A983>?| <20>?敹<>◆ |

### 2.3 憭<>遢<EFBFBD><E981A2>辣蝞∠<E89D9E>

```
AIclinicalresearch/
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> backup_20260111_131506.sql     # <20>交<EFBFBD>_<EFBFBD>園𡢿<E59C92>賢<EFBFBD>
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> rds_init_20251224_154529.sql   # <20><>蟮憭<E89FAE>遢
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD> ...
```

---

## 3. Schema <20>䀹凒瘚<E58792><E7989A>

### 3.1 <20><><EFBFBD>瘚<EFBFBD><E7989A>

```mermaid
graph TD
    A[靽格㺿 schema.prisma] --> B[憭<>遢<EFBFBD>唳旿摨𨩇
    B --> C[餈鞱<E9A488> prisma migrate dev]
    C --> D{餈<>宏<EFBFBD>𣂼<EFBFBD>?}
    D -->|<7C>砝 E[瘚贝<E7989A><E8B49D>蠘<EFBFBD>]
    D -->|<7C>帆 F[隞𤾸<E99A9E>隞賣<E99A9E>憭䓞
    E --> G{瘚贝<E7989A><E8B49D>朞<EFBFBD>?}
    G -->|<7C>砝 H[<5B>𣂷漱隞<E6BCB1><E99A9E>]
    G -->|<7C>帆 F
```

### 3.2 <20>瑚<EFBFBD>甇仿炊

```bash
# 1. 憭<>遢<EFBFBD>唳旿摨?
docker exec ai-clinical-postgres pg_dump -U postgres -d ai_clinical_research > backup_before_migration.sql

# 2. 靽格㺿 schema.prisma

# 3. <20>𥕦遣餈<E981A3>宏
npx prisma migrate dev --name describe_your_change

# 4. 璉<><E79289>亦<EFBFBD><E4BAA6>鞟<EFBFBD>餈<EFBFBD>宏 SQL
cat prisma/migrations/xxx_describe_your_change/migration.sql

# 5. 瘚贝<E7989A>

# 6. 憒<><E68692>憭梯揖嚗峕<E59A97>憭滚<E686AD>隞?
cat backup_before_migration.sql | docker exec -i ai-clinical-postgres psql -U postgres -d ai_clinical_research
```

---

## 4. Prisma 銝擧㺭<E693A7>桀<EFBFBD>銝滢<E98A9D><E6BBA2>湧䔮憸?

### 4.1 Prisma 銝滨恣<E6BBA8><E681A3><EFBFBD>撖寡情

隞乩<EFBFBD><EFBFBD>唳旿摨枏笆鞊∩<EFBFBD><EFBFBD>?`schema.prisma` 銝剖<E98A9D>銋㚁<E98A8B><E39A81><EFBFBD>閬<EFBFBD><E996AC><EFBFBD>祉恣<E7A589><E681A3><EFBFBD>

| 撖寡情 | 蝐餃<E89D90> | <20>交<EFBFBD> | <20>Ｗ<EFBFBD><EFBCB7>𡁏𧋦 |
|------|------|------|----------|
| `platform_schema.job_common` | 銵?| pg-boss 餈鞱<E9A488><E99EB1>嗅<EFBFBD>撱?| `restore_job_common.sql` |
| `platform_schema.create_queue()` | <20>賣㺭 | pg-boss <20>嘥<EFBFBD><E598A5>?| `restore_pgboss_functions.sql` |
| `platform_schema.delete_queue()` | <20>賣㺭 | pg-boss <20>嘥<EFBFBD><E598A5>?| `restore_pgboss_functions.sql` |

### 4.2 <20>Ｗ<EFBFBD><EFBCB7>?Prisma 蝞∠<E89D9E><E288A0><EFBFBD>笆鞊?

```bash
# 憒<><E68692>霂臬<E99C82>鈭?pg-boss <20>詨<EFBFBD>撖寡情嚗峕<E59A97>銵䕘<E98AB5>
npx prisma db execute --file restore_job_common.sql --schema prisma/schema.prisma
npx prisma db execute --file restore_pgboss_functions.sql --schema prisma/schema.prisma
```

### 4.3 璉<><E79289>交㺭<E4BAA4>桀<EFBFBD>銝?Prisma 銝<><E98A9D>湔<EFBFBD>?

```bash
# <20>亦<EFBFBD><E4BAA6>唳旿摨㮖葉<E3AE96><E89189>遆<EFBFBD>?
SELECT routine_name FROM information_schema.routines WHERE routine_schema = 'platform_schema';

# <20>亦<EFBFBD><E4BAA6>唳旿摨㮖葉<E3AE96><E89189>”
SELECT table_name FROM information_schema.tables WHERE table_schema = 'platform_schema';

# 撖寞<E69296> schema.prisma 摰帋<E691B0>
```

---

## 5. 憭?Schema <20>嗆<EFBFBD>閫<EFBFBD><E996AB>

### 5.1 Schema <20>賢<EFBFBD>閫<EFBFBD><E996AB>

| Schema | <20>券<EFBFBD>?| 蝷箔<E89DB7>銵?|
|--------|------|--------|
| `platform_schema` | 撟喳蝱<E596B3>箇<EFBFBD>霈暹鴌 | users, tenants, app_cache |
| `admin_schema` | 餈鞱𨯫蝞∠<E89D9E> | admin_operation_logs |
| `aia_schema` | AI<41>箄<EFBFBD><E7AE84>桃<EFBFBD> | conversations, messages |
| `asl_schema` | <20><>讃蝑偦<E89D91>?| screening_projects, literatures |
| `dc_schema` | <20>唳旿皜<E697BF><E79A9C> | dc_templates, dc_extraction_tasks |
| `pkb_schema` | 銝芯犖<E88AAF>亥<EFBFBD>摨?| knowledge_bases, documents |
| `iit_schema` | IIT憿寧𤌍 | projects, audit_logs |
| `rvw_schema` | 霈箸<E99C88>憸<EFBFBD>恣 | review_tasks |
| `capability_schema` | <20>𡁶鍂<F0A181B6>賢<EFBFBD> | prompt_templates |
| `public` | <20>扳㺭<E689B3>?<3F>澆捆 | users (<28>?, admin_logs |

### 5.2 銵典𦶢<E585B8>滩<EFBFBD><E6BBA9>?

```
{schema_name}.{module_prefix}_{entity_name}

蝷箔<EFBFBD>嚗?
- dc_schema.dc_templates
- dc_schema.dc_extraction_tasks
- asl_schema.screening_projects
```

---

## 6. 憭㚚睸銝擧㺭<E693A7>桀<EFBFBD><E6A180>湔<EFBFBD>?

### 6.1 頝?Schema 憭㚚睸

```prisma
// <20>?甇<>＆嚗𡁏<E59A97>蝖格<E89D96>摰𡁜<E691B0>蝟?
model ReviewTask {
  userId String @map("user_id")
  user   PublicUser @relation(fields: [userId], references: [id])
  
  @@schema("rvw_schema")
}

model PublicUser {
  id String @id
  reviewTasks ReviewTask[]
  
  @@schema("public")
}
```

### 6.2 憭㚚睸<E39A9A><E79DB8><EFBFBD>璉<EFBFBD><E79289>?

<EFBFBD>其蝙<EFBFBD>?`prisma db push` <20>𠬍<EFBFBD>璉<EFBFBD><E79289>亙<EFBFBD><E4BA99>格糓<E6A0BC>行迤蝖殷<E89D96>

```sql
SELECT 
  tc.table_schema, tc.table_name, kcu.column_name,
  ccu.table_schema AS foreign_schema, ccu.table_name AS foreign_table
FROM information_schema.table_constraints AS tc 
JOIN information_schema.key_column_usage AS kcu ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage AS ccu ON ccu.constraint_name = tc.constraint_name
WHERE tc.constraint_type = 'FOREIGN KEY';
```

---

## 7. 鈭𧢲<E988AD><F0A7A2B2>Ｗ<EFBFBD>瘚<EFBFBD><E7989A>

### 7.1 霂臬<E99C82><E887AC>唳旿<E594B3>Ｗ<EFBFBD>

```bash
# 1. <20>𨀣迫摨𠉛鍂
# 2. 隞𤾸<E99A9E>隞賣<E99A9E>憭?
cat backup_xxx.sql | docker exec -i ai-clinical-postgres psql -U postgres -d ai_clinical_research

# 3. 撉諹<E69289><E8ABB9>唳旿
npx tsx verify_system.ts

# 4. <20>滚鍳摨𠉛鍂
```

### 7.2 Schema 銝滢<E98A9D><E6BBA2>湔<EFBFBD>憭?

```bash
# 1. 璉<><E79289>亙榆撘?
npx tsx compare_schema_db.ts

# 2. <20>Ｗ<EFBFBD>蝻箏仃<E7AE8F><E4BB83>笆鞊?
npx prisma db execute --file restore_xxx.sql --schema prisma/schema.prisma

# 3. 撉諹<E69289>
```

---

## 8. 撘<><E69298>𤑳㴓憓?vs <20>煺漣<E785BA>臬<EFBFBD>

### 8.1 撘<><E69298>𤑳㴓憓?

- <20>臭誑雿輻鍂 `prisma migrate dev`
- <20>臭誑雿輻鍂 `prisma db push`嚗<EFBFBD>馬<EFBFBD>𠬍<EFBFBD>
- 摰𡁏<E691B0><F0A1818F>峕郊<E5B395>煺漣<E785BA>唳旿摨梶<E691A8><E6A2B6>?

### 8.2 <20>煺漣<E785BA>臬<EFBFBD>

- **<2A>芾<EFBFBD>**雿輻鍂 `prisma migrate deploy`
- **蝳<>迫**雿輻鍂隞颱<E99A9E> `--force` <20>?`--reset` <20><>㺭
- <20>䀹凒<E480B9>滚<EFBFBD>憿餅<E686BF><E9A485>墧<EFBFBD>霈∪<E99C88>
- 敹<>◆<EFBFBD>㗇<EFBFBD><E39787>啣<EFBFBD>隞?

---

## 9. 璉<><E79289>交<EFBFBD><E4BAA4>?

### 9.1 <20>唳旿摨枏<E691A8><E69E8F>游<EFBFBD>璉<EFBFBD><E79289>?

- [ ] 撌脣<E6928C>隞賣㺭<E8B3A3>桀<EFBFBD>
- [ ] 撌脣恣<E884A3>?schema.prisma <20>䀹凒
- [ ] 撌脫<E6928C><E884AB>交糓<E4BAA4>血蔣<E8A180>漤<EFBFBD> Prisma 蝞∠<E89D9E><E288A0><EFBFBD>笆鞊?
- [ ] 撌脣<E6928C>憭<EFBFBD><E686AD>皛𡁏䲮獢?
- [ ] 撌脣銁撘<E98A81><E69298>𤑳㴓憓<E3B493><E68693>霂?

### 9.2 <20>函蔡<E587BD>擧<EFBFBD><E693A7>?

- [ ] 摨𠉛鍂甇<E98D82>虜<EFBFBD>臬𢆡
- [ ] <20>唳旿摨栞<E691A8><E6A09E>交迤撣?
- [ ] pg-boss <20>笔<EFBFBD>甇<EFBFBD>虜撌乩<E6928C>
- [ ] <20>詨<EFBFBD><E8A9A8>蠘<EFBFBD>瘚贝<E7989A><E8B49D>朞<EFBFBD>

---

## 10. 撣貊鍂<E8B28A>𡁏𧋦

### 10.1 撉諹<E69289><E8ABB9>𡁏𧋦雿滨蔭

```
backend/
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> verify_system.ts           # 蝟餌<E89D9F>摰峕㟲<E5B395>折<EFBFBD>霂?
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> compare_schema_db.ts       # Schema銝擧㺭<E693A7>桀<EFBFBD>撖寞<E69296>
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> check_iit_asl_data.ts      # 璉<><E79289>交芋<E4BAA4>埈㺭<E59F88>?
<EFBFBD>鎿<EFBFBD><EFBFBD><EFBFBD> restore_job_common.sql     # <20>Ｗ<EFBFBD> job_common 銵?
<EFBFBD>婙<EFBFBD><EFBFBD><EFBFBD> restore_pgboss_functions.sql # <20>Ｗ<EFBFBD> pg-boss <20>賣㺭
```

### 10.2 敹恍<E695B9>罸<EFBFBD>霂<EFBFBD>𦶢隞?

```bash
# 霈曄蔭<E69B84>臬<EFBFBD><E887AC>㗛<EFBFBD>
$env:DATABASE_URL="postgresql://postgres:postgres123@localhost:5432/ai_clinical_research"

# 撉諹<E69289>蝟餌<E89D9F>
npx tsx verify_system.ts

# 璉<><E79289>交㺭<E4BAA4>?
npx tsx check_iit_asl_data.ts
```

---

## <20><><EFBFBD>嚗帋<E59A97><E5B88B><EFBFBD><EFBFBD>靘?

### 獢<><E78DA2>1嚗?026-01-11 <20>唳旿摨㯄<E691A8>蝵桐<E89DB5><E6A190>?

**<EFBFBD>笔<EFBFBD>**嚗帋蝙<E5B88B>?`prisma db push --force-reset` 撖潸稲<E6BDB8>?Prisma 蝞∠<E89D9E><E288A0><EFBFBD>笆鞊∩腺憭?

**敶勗<E695B6>**嚗?
- pg-boss <20>賣㺭銝Ｗ仃嚗屸<E59A97><E5B1B8>埈<EFBFBD>瘜閙釣<E99699>?
- job_common 銵其腺憭?
- <20>冽<EFBFBD><E586BD>唳旿銝Ｗ仃嚗<E4BB83>歇<EFBFBD>朞<EFBFBD> seed <20>Ｗ<EFBFBD>嚗?

**<EFBFBD>躰悌**嚗?
1. 瘞貉<E7989E>銝滩<E98A9D>雿輻鍂 `--force-reset`
2. <20>滢<EFBFBD><E6BBA2>滚<EFBFBD>憿餃<E686BF>隞?
3. 鈭<>圾 Prisma <20><>恣<EFBFBD><E681A3>器<EFBFBD>?

霂西<EFBFBD>嚗䫤docs/08-憿寧𤌍蝞∠<E89D9E>/2026-01-11-<2D>唳旿摨㮖<E691A8><E3AE96><EFBFBD><EFBFBD>餌<EFBFBD>.md`