weldone-db-migration

Weldone Db Migration

Overview

规范处理 Weldone 项目的数据库结构同步问题。优先遵循仓库已有 EF Core migration 与 justfile 数据库任务，避免直接往 PostgreSQL 里添加字段、建表、改约束或手写 schema 修复。

当最新代码包含数据库模型变更但本地数据库未同步时，执行迁移更新数据库；当代码确实缺少迁移时，先明确需要新增 migration，不要伪造数据库状态；当需要运行 DbMigrator 时，先备份数据库以防数据丢失。

Trigger Conditions

触发此 skill 当出现以下任一情况：

• 拉取、切换、合并代码后，用户提到没有执行 update-db、数据库结构不匹配、缺字段、缺表、migration 没跑。
• 运行、测试、启动报错包含 column does not exist、relation does not exist、42703、42P01、pending migrations、The model backing the context has changed、Npgsql.PostgresException 等数据库 schema 相关信号。
• 任务涉及修改 Entity、WeldoneDbContext、EF Core configuration、migration、seed data、数据库枚举、索引、约束或外键。
• 准备通过 SQL、脚本、Adminer、psql、数据库客户端或硬编码逻辑直接补字段、补表、改 schema。
• 准备执行 just migrate 或需要判断“代码最新但数据库不是最新”还是“代码缺少 migration”。

Hard Rules

• 禁止直接向数据库添加业务字段、表、索引、约束或外键来匹配代码，除非用户明确要求手工 SQL，并且说明这是临时修复。
• 禁止把数据库缺字段问题修成代码 fallback、忽略字段、空值兜底或删除属性，除非确认需求就是代码回滚。
• 优先执行仓库任务：just update-db；需要种子数据时，必须先备份 PostgreSQL 数据库，再执行 just migrate。
• 需要新增迁移时使用：just add-m <MigrationName>，不要手写 migration 文件替代 EF 生成结果。
• 回滚或移除迁移时使用：just remove-m 或 just update-db <MigrationName>，不要删除 migration 文件后假装完成。
• 执行数据库命令前，先确认工作目录为 Weldone 仓库根目录；默认是 D:\weldone，如项目位于其他路径，给脚本传入 -RepoRoot <路径>。
• 执行本 skill 的 .ps1 脚本时一律使用 pwsh -NoProfile -ExecutionPolicy Bypass -File ...；脚本内默认 UTF-8。
• migrate 前备份路径必须从 $env:APPDATA 拼接到 Roboticplus\Weldone\backup-db，禁止写死 C:\Users\<用户名>。
• 备份文件名必须使用当前时间生成，格式为 ai-backup-before-migrate-yyyy-MMdd-HHmm-ssff.backup，不要复用固定示例名。
• 遇到数据库连接失败，优先检查 PostgreSQL 是否启动、连接串配置和 just pod，不要改模型或迁移。

Workflow

1. Classify the Failure

先判断问题类型：

• 本地数据库落后：migration 已存在，但数据库未应用。执行 just update-db。
• 需要种子数据：schema 已更新，但基础数据、权限、配置或默认记录缺失。先备份，再执行 just migrate。
• 代码缺少 migration：实体或 DbContext 变化存在，但 migration 列表没有对应变更。先运行检查，再用 just add-m <Name> 生成 migration。
• 连接/环境问题：数据库不可达、认证失败、连接串错误、容器未启动。先修环境，不改 schema。

2. Inspect Before Acting

运行快速检查：

pwsh -NoProfile -ExecutionPolicy Bypass -File <skill>/scripts/check-db-migration-state.ps1 -RepoRoot D:\weldone