# 管理端数据库变更 SQL 以下 SQL 由维护人员手工执行,应用不会自动迁库。已有数据库执行下面的增量 SQL;新建数据库先执行 database.md 中的四表 SQL,然后只创建本文件的任务表,不重复执行 ALTER。 执行前暂停社区端、后台和导入工具的写入并备份数据库。不要对已有列重复执行。所有时间字段由应用写入上海时间(Asia/Shanghai,UTC+8)。项目来源改为从任务表读取,因此社区端、后台和导入工具升级前都应创建任务表,即使暂不启动后台也需要执行。 ## 项目字段收敛 治理相关字段为 moderation_reason(管理员下架原因)和 repo_write_status(跨进程写入状态)。下架直接使用现有 publish_status=BLOCKED,不再增加独立治理状态。GitHub来源标识、地址、默认分支和许可证属于迁移任务,统一放在 project_import_task;第一版只支持GitHub,不存平台类型,也不额外区分用户创建与后台创建。 ## 已有数据库增加 STEP 单文件字段 已有数据库手工执行以下 SQL,再升级社区端、管理端和导入工具;新建数据库的 `database.md` 已包含这三个字段,不要重复执行。应用不自动迁库,不新增上传批次表。 ```sql ALTER TABLE project ADD COLUMN step_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'STEP文件环境相对路径,不含域名和环境根目录', ADD COLUMN step_file_name VARCHAR(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'STEP原始文件名,保留大小写中文和空格', ADD COLUMN step_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'STEP文件大小,单位字节,未绑定时为零'; ``` STEP 默认最大 500 MiB(524288000 字节),可通过管理端 `STEP_MAX_FILE_BYTES` 配置;调整时须同步前端限制和文案。签名有效期为 15 分钟,文件由浏览器直传 OSS,无需调整 API multipart 限制。对象路径为 `/project-resources/{projectCode}/step/{batchCode}/model{原始后缀}`,不包含环境根目录;原始文件名单独保存。未绑定时路径和文件名为 `''`,大小为 `0`,接口的三个 STEP 字段均为 `null`。 上传签名限定对象、精确大小、禁止覆盖和附件下载响应头;公开 URL 可直接下载,不提供额外下载接口。OSS 需允许管理端来源的 multipart POST,CDN 需透传 Content-Disposition。Fork 复制这三个字段并共享 OSS 对象。替换、移除或删除项目不物理删除对象,不影响其他副本。 STEP 与现有 URDF 使用相同的无状态确认方式:批次不落库,确认核验 OSS 对象及大小,项目锁内局部更新。重复确认会再次写入;签名过期后已上传对象仍可确认;并发以最后一次成功写入为准;替换或移除后重放旧请求可以重新绑定旧对象。不提供批次历史比对、严格幂等或旧批次防复活保证。旧版前端需求文档中的相关保证不适用于本期。 ## 已有数据库增加四类项目资源字段 在已完成原有部署的数据库中手工执行以下 SQL,再升级社区端、管理端和导入工具。新建数据库的 `database.md` 建表语句已包含这些字段,不要重复执行。 ```sql ALTER TABLE project ADD COLUMN model_glb_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '整机GLB环境相对路径,不含域名和环境根目录', ADD COLUMN model_glb_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '整机GLB文件大小,单位字节', ADD COLUMN model_parts_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '零件模型环境相对目录,以斜杠开头和结尾', ADD COLUMN model_parts_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '零件GLB文件清单,包含relativePath和sizeBytes', ADD COLUMN assembly_json_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '拼装步骤JSON环境相对路径,不含域名和环境根目录', ADD COLUMN assembly_json_size_bytes BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '拼装步骤JSON文件大小,单位字节', ADD COLUMN walking_resources_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '行走资源环境相对目录,以斜杠开头和结尾', ADD COLUMN walking_resources_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT '行走资源文件清单,包含relativePath和sizeBytes'; ``` 路径为未编码的 `/project-resources/{projectCode}/{resourceType}/{batchCode}/{relativePath}`,不含域名和环境根目录。目录字段以 `/` 结尾,清单内路径相对于对应目录。未绑定或清除后路径为 `''`、大小为 `0`、清单为 `[]`。 Fork 直接复制这八个字段并复用原 OSS 对象,因此副本保存的路径可以包含源项目编码。读取不校验路径属于当前项目;新上传和确认只能使用当前项目的目录。替换、清除和删除项目均保留 OSS 对象,避免破坏其他副本的引用。后续如增加资源清理任务,必须检查所有项目的共享引用。 ## 已有数据库增加字段 ```sql ALTER TABLE sys_user ADD COLUMN role VARCHAR(16) NOT NULL DEFAULT 'USER' COMMENT '用户角色 USER普通用户 ADMIN管理员 OFFICIAL官方托管账号'; ALTER TABLE sys_user ADD COLUMN password_hash VARCHAR(100) NULL COMMENT '管理员BCrypt密码哈希,普通用户为空'; ALTER TABLE sys_user ADD COLUMN session_version BIGINT NOT NULL DEFAULT 0 COMMENT '登录会话版本,禁用或修改密码时递增'; ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架'; ALTER TABLE project ADD COLUMN moderation_reason VARCHAR(500) NULL COMMENT '管理员下架原因'; ALTER TABLE project ADD COLUMN repo_write_status VARCHAR(16) NOT NULL DEFAULT 'IDLE' COMMENT '仓库写入状态 IDLE空闲 WRITING写入中 REVIEW待核对'; ``` ## 新建迁移任务表 ```sql CREATE TABLE project_import_task ( id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部任务主键', task_code CHAR(32) NOT NULL COMMENT '迁移任务业务编码', project_code CHAR(32) NOT NULL COMMENT '目标项目业务编码', operator_user_code CHAR(32) NOT NULL COMMENT '任务创建管理员用户编码', source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用', source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址', source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验', source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空', status VARCHAR(16) NOT NULL DEFAULT 'QUEUED' COMMENT '任务状态 QUEUED排队 RUNNING执行 SUCCEEDED成功 FAILED失败 REVIEW待核对', phase VARCHAR(32) NOT NULL DEFAULT 'QUEUED' COMMENT '迁移阶段 QUEUED CLEANING PRECHECK MIGRATING MIGRATED NORMALIZING BRANCH_READY LINKED', receipt_json TEXT NULL COMMENT '已确认迁移完成收据JSON,仅内部使用,不包含认证凭据', target_sha VARCHAR(64) NULL COMMENT '迁移后冻结的目标提交SHA', error_code VARCHAR(64) NULL COMMENT '最近失败错误码', warnings_json TEXT NOT NULL COMMENT '兼容性提醒JSON数组', started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)', finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)', created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)', PRIMARY KEY (id), UNIQUE KEY uk_import_task_code (task_code), UNIQUE KEY uk_import_project (project_code), KEY idx_import_source (source_repository_id), KEY idx_import_queue (status, created_at), CONSTRAINT fk_import_project FOREIGN KEY (project_code) REFERENCES project(project_code), CONSTRAINT fk_import_operator FOREIGN KEY (operator_user_code) REFERENCES sys_user(user_code) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='后台公开GitHub项目迁移任务'; ``` 没有管理员账号表、管理员会话表、审计表或仓库状态表。第一位管理员使用初始化命令设置,禁止手写明文密码入库。后续手工修改角色时必须同时递增 session_version,且 ADMIN 必须具有通过 BCrypt 编码的密码。官方托管账号由后台首次创建或迁移项目时自动建立,保留邮箱为 vibemake-official@internal.invalid。 REVIEW 或遗留 WRITING 不应直接改为 IDLE:先核对 Gitea 写入、迁移收据、LFS 完成情况、仓库身份及提交。已持久化成功收据时提供只读核对后的续跑;明确 GITEA_MIGRATION_REJECTED 的任务允许通过 retry 进入 CLEANING,核验并清理归属于该任务的失败仓库后重迁。清理身份使用现有 project.gitea_repo_id 保存,保留原任务与项目,不新增字段或表。已有 phase 为 VARCHAR,无需因新增 CLEANING 阶段执行数据库变更。不提供强制成功操作。 迁移响应丢失、没有成功收据的 REVIEW 任务,管理员点击 retry 后进入 VERIFYING,核验通过才在同一事务保存恢复收据、仓库身份和冻结提交,接续原任务。核验不通过继续 REVIEW,不删除仓库、不重新迁移。VERIFYING 沿用现有 phase 的 VARCHAR 字段,本次恢复能力不需要新增表或字段,也无需手工修改任务状态。 ## 已经执行过上一版管理端 SQL 的数据库 本节只供已经存在旧字段/旧任务表的数据库手工升级;尚未执行旧版 SQL 的数据库不要执行本节。先暂停写入并备份,不自动删除旧字段。 ```sql ALTER TABLE project_import_task ADD COLUMN source_repository_id BIGINT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用'; ALTER TABLE project_import_task ADD COLUMN source_repository_url VARCHAR(2048) NULL COMMENT 'GitHub仓库规范公开地址'; ALTER TABLE project_import_task ADD COLUMN source_default_branch VARCHAR(255) NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验'; ALTER TABLE project_import_task ADD COLUMN source_license VARCHAR(128) NULL COMMENT 'GitHub许可证标识,无法识别时为空'; UPDATE project_import_task t JOIN project p ON p.project_code = t.project_code SET t.source_repository_id = p.external_repository_id, t.source_repository_url = p.external_repository_url, t.source_default_branch = p.external_default_branch, t.source_license = p.external_license; -- 检查结果必须为空,才能把三个必需来源字段设为 NOT NULL。 SELECT task_code, project_code FROM project_import_task WHERE source_repository_id IS NULL OR source_repository_url IS NULL OR source_default_branch IS NULL; ALTER TABLE project_import_task MODIFY COLUMN source_repository_id BIGINT NOT NULL COMMENT 'GitHub稳定仓库标识,用于来源去重,仅内部使用'; ALTER TABLE project_import_task MODIFY COLUMN source_repository_url VARCHAR(2048) NOT NULL COMMENT 'GitHub仓库规范公开地址'; ALTER TABLE project_import_task MODIFY COLUMN source_default_branch VARCHAR(255) NOT NULL COMMENT 'GitHub仓库原默认分支,用于分支适配和续跑校验'; ALTER TABLE project_import_task ADD KEY idx_import_source (source_repository_id); UPDATE project SET publish_status = 'BLOCKED' WHERE moderation_status = 'BLOCKED' AND deleted = 0; ALTER TABLE project MODIFY COLUMN publish_status VARCHAR(16) NOT NULL DEFAULT 'UNPUBLISHED' COMMENT '发布状态 UNPUBLISHED未发布 PUBLISHED已发布 BLOCKED管理员下架'; ``` 旧版七个字段及其索引可以暂留,代码已不再读写;确认备份及来源回填完成后再清理。特别是只有旧 Excel 批次、没有后台任务的历史项目,其来源需保留原批次清单或另行归档,不能直接删除唯一来源信息。本次不对实际数据库执行增删字段操作。 ## 允许已删除项目的 GitHub 来源再次迁移(本次上线前执行) 仅供已经存在 `uk_import_source` 唯一索引的数据库执行。暂停后台创建迁移任务并备份后,在业务库中手工执行以下 SQL;新建任务表已使用普通索引,无需执行本节。应用不会修改实际表结构。 ```sql ALTER TABLE project_import_task DROP INDEX uk_import_source, ADD KEY idx_import_source (source_repository_id); ``` 来源标识保留在每条历史任务中,仍通过项目编码关联各自的项目。新版按 GitHub 稳定来源加锁,只对未删除项目去重;已删除项目可用新项目编码、新任务和新仓库再次迁移。旧项目、任务和仓库均保留,不会被覆盖或自动清理;管理员项目列表和详情仍不展示已删除项目。字段与中文注释保持不变。 部署时必须先完成上述索引调整,再更新所有管理端实例;旧索引会继续阻止创建第二条来源任务。允许重复来源后不能直接恢复全局唯一索引,回滚前须核对同一来源的历史任务记录。 ## 新建普通文件写入操作记录表(本次上线前执行) 只新增此表,不需要修改项目表。由运维手工执行;应用不自动迁库。时间全部为上海时间(Asia/Shanghai,UTC+8)。 ```sql CREATE TABLE repository_write_operation ( operation_code CHAR(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '写入操作业务编码,同时作为幂等键', project_code CHAR(32) NOT NULL COMMENT '项目业务编码', repository_id BIGINT NOT NULL COMMENT '操作发起时Gitea仓库内部标识,仅核验使用', repository_owner VARCHAR(255) NOT NULL COMMENT '操作发起时仓库所属账号', repository_name VARCHAR(255) NOT NULL COMMENT '操作发起时仓库名称', base_commit_sha VARCHAR(64) NOT NULL COMMENT '本次写入的基准提交SHA', request_digest CHAR(64) NOT NULL COMMENT '请求内容SHA256摘要,不保存文件正文', commit_message VARCHAR(1000) NOT NULL COMMENT '原始提交说明,不包含系统凭据尾注', status VARCHAR(16) NOT NULL COMMENT '操作状态 PROCESSING处理中 NEEDS_REVIEW超时待确认 SUCCEEDED已成功 FAILED明确失败', result_commit_sha VARCHAR(64) NULL COMMENT '确认成功的提交SHA', failure_status INT NULL COMMENT '明确失败时原HTTP状态码', last_error_code VARCHAR(64) NULL COMMENT '最近核对错误编码,不保存异常正文或凭证', check_count INT NOT NULL DEFAULT 0 COMMENT '后台已执行核对次数', next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)', created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)', PRIMARY KEY (operation_code), KEY idx_write_project_status (project_code, status, created_at), KEY idx_write_next_check (status, next_check_at) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='普通文件写入幂等凭据及自动核对记录'; ``` 已完成的操作记录仍用于幂等重放,不要在客户端可能重试期间删除。历史 REVIEW 没有操作记录,不会凭最新 SHA 自动判成功;需核对实际结果后按原维护流程处理。迁移、Fork 继续使用原流程。 ## 业务时间由 UTC 迁移到上海时间 新版统一通过 `ProjectSupport` 生成上海时间(`Asia/Shanghai`),字段类型保持 `DATETIME(3)`。以下 SQL 由维护人员手工执行,应用不会执行迁移,也不会自动修改已有数据库。 执行顺序:暂停社区端、管理端和导入工具,备份业务数据库及导入状态目录;确认以下六张表中的历史时间仍全部为 UTC 后执行一次转换;核对结果后同时部署新版各模块,并同步前端的 `+08:00` 解析方式,再恢复服务。新建空库无需执行数据转换。若已经写入上海时间或存在混合时区数据,必须先按切换记录确定待转换数据范围,不能直接执行以下全表更新;本脚本不能重复执行。 ```sql USE vibemake; START TRANSACTION; UPDATE sys_user SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR), updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR); UPDATE project SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR), updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR), published_at = DATE_ADD(published_at, INTERVAL 8 HOUR); UPDATE project_comment SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR), updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR); UPDATE project_like SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR); UPDATE project_import_task SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR), updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR), started_at = DATE_ADD(started_at, INTERVAL 8 HOUR), finished_at = DATE_ADD(finished_at, INTERVAL 8 HOUR); UPDATE repository_write_operation SET created_at = DATE_ADD(created_at, INTERVAL 8 HOUR), updated_at = DATE_ADD(updated_at, INTERVAL 8 HOUR), next_check_at = DATE_ADD(next_check_at, INTERVAL 8 HOUR); COMMIT; ``` 空值保持为空,毫秒精度保持不变。`next_check_at` 等调度时间也需要转换,避免切换后提前或延后核对任务。Git 提交日期、OSS 签名内容和 Gitea 内部数据库不参与转换。 已有数据库的时间字段注释可单独按以下 SQL 更新;DDL 会隐式提交,不要放入上面的数据转换事务。 ```sql ALTER TABLE sys_user MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)'; ALTER TABLE project MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)', MODIFY COLUMN published_at DATETIME(3) NULL COMMENT '最近发布时间(Asia/Shanghai)'; ALTER TABLE project_comment MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)'; ALTER TABLE project_like MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '点赞时间(Asia/Shanghai)'; ALTER TABLE project_import_task MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '更新时间(Asia/Shanghai)', MODIFY COLUMN started_at DATETIME(3) NULL COMMENT '最近开始时间(Asia/Shanghai)', MODIFY COLUMN finished_at DATETIME(3) NULL COMMENT '最近结束时间(Asia/Shanghai)'; ALTER TABLE repository_write_operation MODIFY COLUMN created_at DATETIME(3) NOT NULL COMMENT '创建时间(Asia/Shanghai)', MODIFY COLUMN updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间(Asia/Shanghai)', MODIFY COLUMN next_check_at DATETIME(3) NOT NULL COMMENT '下次只读核对时间(Asia/Shanghai)'; ``` 旧导入状态首次由新版读取时,将未声明时区的 `reservedAt` 从 UTC 转为上海时间,原子保存并标记 `timeZone=Asia/Shanghai`,后续不会再次转换。应在业务库完成转换后再续跑;未迁移的数据库时间与清单不一致时,现有归属校验会阻止接管项目。回滚应用前需要同时恢复数据库和导入状态备份,并恢复前端的旧时间解析约定。