From f8c9c579f26965232643d72a1020bc06324456e5 Mon Sep 17 00:00:00 2001
From: Developer <developer@rwadurian.com>
Date: Tue, 2 Dec 2025 18:42:33 -0800
Subject: [PATCH] =?UTF-8?q?feat(admin-service):=20=E6=B7=BB=E5=8A=A0=20dat?=
 =?UTF-8?q?abase=20=E7=9B=AE=E5=BD=95=E5=92=8C=E5=88=9D=E5=A7=8B=E5=8C=96?=
 =?UTF-8?q?=E8=84=9A=E6=9C=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增目录和文件:
- database/init.sql: 数据库初始化脚本（保留用于未来需求）
- database/README.md: database 目录使用说明文档

database/ 目录用途:
1. 存放数据库初始化SQL脚本
2. 在Prisma migrations之后执行
3. 用于插入初始数据或设置序列号等

与Prisma的关系:
- Prisma migrations: 创建表结构
- database/init.sql: 插入初始数据

Docker Compose集成:
可通过volume映射到/docker-entrypoint-initdb.d/自动执行

参考其他服务:
- identity-service: 使用init.sql初始化序列号生成器
- mpc-service: 使用database/migrations存放迁移

当前状态:
- init.sql已创建但为空（目前不需要初始数据）
- 完整文档说明用途和使用方法

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../services/admin-service/database/README.md | 154 ++++++++++++++++++
 .../services/admin-service/database/init.sql  |  14 ++
 2 files changed, 168 insertions(+)
 create mode 100644 backend/services/admin-service/database/README.md
 create mode 100644 backend/services/admin-service/database/init.sql

diff --git a/backend/services/admin-service/database/README.md b/backend/services/admin-service/database/README.md
new file mode 100644
index 00000000..b6d94537
--- /dev/null
+++ b/backend/services/admin-service/database/README.md
@@ -0,0 +1,154 @@
+# Database 目录说明
+
+## 目录用途
+
+`database/` 目录用于存放数据库相关的初始化脚本和迁移文件。
+
+## 文件说明
+
+### init.sql
+**用途**: 数据库初始化脚本
+
+**使用场景**:
+- 在数据库首次创建后，需要插入初始数据时使用
+- 在 Docker Compose 启动时自动执行
+- 在测试环境中初始化测试数据
+
+**执行方式**:
+```bash
+# 手动执行（如果需要）
+psql -U postgres -d admin_service -f database/init.sql
+
+# 或通过 Docker Compose volume 映射自动执行
+```
+
+## 与 Prisma 的关系
+
+### Prisma Migrations
+- **位置**: `prisma/migrations/`
+- **用途**: 创建和管理数据库表结构
+- **执行**: `npx prisma migrate deploy`
+
+### database/init.sql
+- **位置**: `database/init.sql`
+- **用途**: 在表结构创建后，插入初始数据
+- **执行**: 在 migrations 之后手动或自动执行
+
+## 执行顺序
+
+正确的数据库初始化顺序：
+
+```
+1. Prisma Migrations (创建表结构)
+   ↓
+2. database/init.sql (插入初始数据)
+```
+
+## Docker Compose 集成
+
+如果需要在 Docker Compose 中使用初始化脚本，可以这样配置：
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    volumes:
+      - ./database/init.sql:/docker-entrypoint-initdb.d/01-init.sql
+      - postgres_data:/var/lib/postgresql/data
+```
+
+**注意**: PostgreSQL Docker 镜像会自动执行 `/docker-entrypoint-initdb.d/` 目录中的 `.sql` 文件。
+
+## 当前状态
+
+### Admin Service
+- ✅ Prisma schema 定义完成
+- ✅ Migrations 已创建
+- ⚠️  目前不需要初始数据
+- ✅ init.sql 文件已创建（保留用于未来需求）
+
+## 使用示例
+
+### 添加初始版本记录
+
+如果需要在数据库初始化时插入默认版本，可以编辑 `init.sql`:
+
+```sql
+INSERT INTO "AppVersion" (
+  id,
+  platform,
+  "versionCode",
+  "versionName",
+  "buildNumber",
+  "downloadUrl",
+  "fileSize",
+  "fileSha256",
+  changelog,
+  "isEnabled",
+  "isForceUpdate",
+  "createdBy",
+  "createdAt",
+  "updatedAt"
+)
+VALUES (
+  'initial-android',
+  'android',
+  1,
+  '1.0.0',
+  '1',
+  'https://example.com/app-v1.apk',
+  10485760,
+  'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+  'Initial release',
+  true,
+  false,
+  'system',
+  NOW(),
+  NOW()
+)
+ON CONFLICT (id) DO NOTHING;
+```
+
+## 参考其他服务
+
+### identity-service
+- 使用 `init.sql` 初始化账户序列号生成器
+- 示例: `INSERT INTO account_sequence_generator`
+
+### mpc-service
+- 使用 `database/migrations/` 存放自定义迁移
+
+## 最佳实践
+
+1. **幂等性**: 所有 SQL 脚本都应该是幂等的（可重复执行）
+   - 使用 `ON CONFLICT DO NOTHING`
+   - 使用 `IF NOT EXISTS`
+
+2. **注释**: 为所有初始化脚本添加清晰的注释
+
+3. **版本控制**: 将 `database/` 目录纳入 Git 版本控制
+
+4. **测试**: 确保初始化脚本在测试环境中正常工作
+
+## 故障排查
+
+### 初始化脚本未执行
+
+**原因**: PostgreSQL 只在首次创建数据库时执行 initdb 脚本
+
+**解决方案**:
+```bash
+# 删除 volume 重新创建
+docker-compose down -v
+docker-compose up
+```
+
+### 重复执行错误
+
+**原因**: 脚本不是幂等的
+
+**解决方案**: 使用 `ON CONFLICT` 或 `IF NOT EXISTS`
+
+---
+
+*最后更新: 2025-12-03*
diff --git a/backend/services/admin-service/database/init.sql b/backend/services/admin-service/database/init.sql
new file mode 100644
index 00000000..14261b97
--- /dev/null
+++ b/backend/services/admin-service/database/init.sql
@@ -0,0 +1,14 @@
+-- ============================================
+-- Admin Service 数据库初始化 (PostgreSQL)
+-- ============================================
+
+-- 此文件用于在数据库首次创建时初始化必要的数据
+-- 由 Prisma migrations 创建表结构后执行
+
+-- 示例：插入初始版本记录（如果需要）
+-- INSERT INTO "AppVersion" (id, platform, "versionCode", "versionName", "buildNumber", "downloadUrl", "fileSize", "fileSha256", changelog, "isEnabled", "isForceUpdate", "createdBy", "createdAt", "updatedAt")
+-- VALUES ('initial-version-id', 'android', 1, '1.0.0', '1', 'https://example.com/app.apk', 10485760, 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', 'Initial version', true, false, 'system', NOW(), NOW())
+-- ON CONFLICT (id) DO NOTHING;
+
+-- 注意：目前 admin-service 不需要初始数据
+-- 此文件保留用于未来可能的初始化需求