feat: 创建数据库

docs/v3.5/数据库设计文档.md

@@ -2,12 +2,16 @@
 
 > 数据库：PostgreSQL；ORM：Prisma。数据库选型已按用户确认更新。
 >
-> 状态：目标设计，尚未创建数据库、Prisma Schema 或业务迁移；线上集合、数据量和异常分布待 S0 盘点。
+> 状态：目标设计，本地开发数据库已配置；10 张业务表及初始配置已在本地创建；尚未创建 Prisma Schema 或接入 Prisma 迁移历史；线上集合、数据量和异常分布待 S0 盘点。
 >
 > 更新日期：2026-10-12。
 >
 > 配套方案：[云服务端迁移方案](../云服务端迁移方案.md)。本文细化该方案的数据结构与一致性规则。
 
+已生成 [数据库初始化 SQL](../../apps/server/prisma/sql/README.md)，建库、10 张表及配置初始化已在 PostgreSQL 18.6 临时库执行验证，19 项约束检查通过；临时库已清理，开发库随后已正式执行基线 SQL，创建 10 张表和两条配置记录；未创建 Prisma Schema 或导入线上数据。
+
+本地开发使用 Docker PostgreSQL，图片等资源直接使用七牛；云服务器首期只常驻生产库，隔离测试库在真实联调时按需创建，可复用同一 PostgreSQL 实例。详见 [开发与部署环境方案](./开发与部署环境方案.md) 与 [本地数据库说明](../../infra/README.md)。本地数据库已配置，本文 10 张表已在本地创建，业务 API 尚未实现。
+
 ## 1. 范围与依据
 
 首期迁移现有微信小程序后端，统一使用 PostgreSQL 主数据库、NestJS API 和七牛文件存储。小程序仍在 `doodle-mini` 维护，数据库模型与迁移只放在 `doodle-store/apps/server/prisma`。Web 与管理后台通过 API 访问，不直接连接数据库。
@@ -170,6 +174,8 @@ UNIQUE `(user_id, worksheet_id)`；列表索引 `(user_id, created_at DESC, id D
 
 UNIQUE `(user_id, export_id)` 使用 PostgreSQL 默认 NULL 语义，允许同用户多条 export_id=NULL；**不使用 NULLS NOT DISTINCT**。空串先转 NULL，避免旧记录冲突。新版 API 必填 exportId，NULL 只允许历史导入。重复非空 exportId 若指向不同题型，隔离处理，不能任意挑一条。
 
+SQL CHECK 限定 NULL exportId 只能出现在 source=import 的历史记录中；其余来源必须提供非空白事件 ID，旧桥负责生成 legacy 事件 ID。
+
 索引 `(user_id, created_at DESC, id DESC)`、`(worksheet_id, created_at DESC, id DESC)`。不同 exportId 的同题型多次保存都是有效事件；禁止 UNIQUE `(user_id, worksheet_id)` 或按秒级时间窗口去重。
 
 ### 3.6 page_configs — 页面配置权威源
@@ -189,17 +195,17 @@ UNIQUE `(user_id, export_id)` 使用 PostgreSQL 默认 NULL 语义，允许同
 
 ```json
 {
-  "featured": [
-    {
-      "id": "原题型ID",
-      "title": "练习纸",
-      "previewImg": { "assetId": "预览资产ID" },
-      "path": "/原页面路径?原参数",
-      "available": true
-    }
-  ],
-  "hot": [],
-  "sections": []
+    "featured": [
+        {
+            "id": "原题型ID",
+            "title": "练习纸",
+            "previewImg": { "assetId": "预览资产ID" },
+            "path": "/原页面路径?原参数",
+            "available": true
+        }
+    ],
+    "hot": [],
+    "sections": []
 }
 ```
 
@@ -247,6 +253,8 @@ UNIQUE source_ref_hash、UNIQUE object_ref_hash（可空）；索引 `(owner_use
 
 qiniu ready 必须具备 bucket、objectKey、objectRefHash、mimeType、sizeBytes 和 checksum；external ready 必须有经核实的 externalUrl，无法取得内容摘要时在报告注明。源文件下载、上传与校验完成后才 ready，再写业务外键。DB 存引用，访问域名从服务配置取；私有签名 URL 在响应时生成，不能写回数据库或页面配置。
 
+SQL 检查 ready 必填字段、external 的 HTTPS 前缀、avatar 必须 private，以及摘要/hash 为 64 位小写十六进制。摘要计算和规范化由服务端完成；HTTPS 前缀检查不代替域名白名单或远程文件校验。
+
 上传和对象存储操作不放在长数据库事务中；先完成上传并登记资产，再短事务绑定业务记录。未绑定文件由清理流程回收，清理前检查 users、worksheets、categories 和 page_configs 的所有引用。旧桥复制云文件后也必须遵循同一路径。
 
 ### 4.2 job_runs — 调度与执行结果
@@ -374,7 +382,7 @@ UNIQUE `(job_name, run_key)`；索引 `(status, locked_until)`、`(job_name, cre
 - datasource 使用 `provider = "postgresql"`。具体 PostgreSQL 主版本、Prisma 版本、Node 运行时组合在 S1 样板中验证并锁定，不照抄旧 MySQL Schema 或旧连接参数。
 - PostgreSQL 类型映射：字符串 `@db.VarChar(n)`、计数 BigInt `@db.BigInt`、日期 DateTime `@db.Timestamptz(3)`、JSON `@db.JsonB`。SQL 的 now() 负责新建时间；更新由服务显式维护，内容时间不依赖自动 updatedAt 推断。
 - PostgreSQL CHECK、标识符列排序规则、DESC 索引和本文事务 SQL 以版本化迁移 SQL 为最终落点；Prisma Schema 同步描述可表达的约束。业务验证不能代替数据库唯一键。
-- `apps/server/prisma/schema.prisma`、`migrations/` 与迁移说明同版本提交；本文是实施输入，本次不生成看似已执行的 Schema/迁移文件，也不连接生产库。
+- 当前可执行基线 SQL 位于 `apps/server/prisma/sql`，尚未纳入 Prisma 迁移历史。后续 `schema.prisma`、`migrations/` 与迁移说明同版本提交；已有表的数据库先登记基线，不能重复执行初始建表 DDL。本次不连接生产库。
 - 新增列采用可兼容上一 API 版本的步骤，数据回填和收紧 NOT NULL/外键分开验证；应用回滚继续使用新主库。正式环境不使用 db push 随意覆盖结构。
 - 原始导出、隔离记录、文件映射、导入报告和恢复校验随迁移批次归档。数据库备份使用 PostgreSQL 工具链，并实际演练恢复；备份目标在服务器之外。
 - 首期不分表、不分区、不引入 Redis、队列或全文搜索。限制连接池与导入并发，按 2 核 4 GB 实际联调结果配置，禁止所有应用默认建立无限连接。