数据持久化

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 数据持久化与初始化指南

## 问题说明

之前出现数据和功能消失的根本原因是：

1. **缺少自动化的数据初始化机制**
   - 邮件模板等初始数据没有被自动导入
   - 需要手动运行 `pnpm db:seed` 才能初始化数据

2. **数据库连接由 SDK 管理**
   - 数据库实例通过 `FutureBirdAadminAi-coding-dev-sdk` 动态获取
   - 不在项目的完全控制范围内

3. **缺少启动时的数据完整性检查**
   - 应用启动时不会自动检查必要数据是否存在
   - 缺少自动修复机制

## 解决方案

### 1. 自动化数据初始化

项目现在已经配置了自动数据初始化机制：

#### 方式一：启动时自动检查（推荐）

应用启动时，访问 `/api/system/health` 会自动触发数据初始化检查：

```bash
curl http://localhost:5000/api/system/health
```

这会自动：
- 检查邮件模板是否存在，不存在则自动导入
- 检查 SMTP 配置是否存在

#### 方式二：手动运行初始化脚本

```bash
# 初始化所有数据（包括管理员、套餐、工资项目、邮件模板）
pnpm db:seed

# 仅检查和初始化应用数据
npx tsx scripts/initialize-app-data.ts
```

#### 方式三：仅导入邮件模板

```bash
npx tsx scripts/import-email-templates.ts
```

### 2. 数据初始化脚本说明

#### `scripts/seed-data.ts`
完整的种子数据初始化脚本，包括：
- 创建默认超级管理员
- 创建默认合作伙伴
- 创建系统配置
- 创建默认套餐
- 创建默认工资项目
- **创建邮件模板** ✅

#### `scripts/initialize-app-data.ts`
轻量级的数据检查脚本，仅检查：
- 邮件模板是否存在
- SMTP 配置是否存在

适用于应用启动时的快速检查。

#### `scripts/import-email-templates.ts`
专门用于导入邮件模板的脚本。

### 3. 防止数据丢失的最佳实践

#### 3.1 定期备份数据

```bash
# 导出所有数据
pnpm db:export

# 导出后会生成 data-export/ 目录下的 JSON 文件
```

#### 3.2 数据迁移时保留数据

当修改数据库结构时，使用 `db:migrate` 而不是直接删除数据库：

```bash
# 推荐方式：迁移数据
pnpm db:migrate

# 不推荐：删除数据库重建
```

#### 3.3 启动时检查数据

在 `scripts/dev.sh` 中添加健康检查：

```bash
# 启动前确保数据存在
curl -s http://localhost:5000/api/system/health > /dev/null 2>&1 || true
```

### 4. 数据完整性保障

#### 4.1 启动检查清单

应用启动时应检查以下数据：
- ✅ 超级管理员账户
- ✅ 邮件模板
- ✅ 默认套餐
- ✅ 工资项目模板

#### 4.2 数据恢复流程

如果发现数据丢失，按以下流程恢复：

1. **检查备份文件**
   ```bash
   ls -la data-export/
   ```

2. **从备份恢复**
   ```bash
   pnpm db:import
   ```

3. **重新初始化（如果备份不存在）**
   ```bash
   pnpm db:seed
   ```

### 5. 环境变量配置

确保数据库配置正确，避免使用临时数据库：

```env
# .env
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
```

### 6. 监控和告警

建议添加以下监控：

- 数据库连接状态
- 关键数据表的数据量
- API 健康检查

## 常见问题

### Q1: 为什么邮件模板会消失？

A: 邮件模板数据保存在 `data-export/email_templates.json` 中，但没有被自动导入到数据库。现在已修复，`seed-data.ts` 会自动导入邮件模板。

### Q2: 如何防止数据丢失？

A: 定期运行 `pnpm db:export` 备份数据，确保数据库连接配置正确，不要删除或重置数据库。

### Q3: 应用重启后数据会丢失吗？

A: 正常情况下不会。数据持久化在 PostgreSQL 数据库中，应用重启不会影响。但如果数据库配置为临时数据库，数据会丢失。

### Q4: 如何验证数据完整性？

A: 访问 `/api/system/health`，会自动检查并初始化必要的数据。

## 总结

通过以上改进，现在：

1. ✅ 邮件模板会自动初始化
2. ✅ 启动时有数据完整性检查
3. ✅ 提供了数据备份和恢复机制
4. ✅ 防止了手动操作的遗漏

数据和功能不再会因为忘记初始化而消失。