Files
cadworld/cadworld-api/docs/project-schema.md
T

4.7 KiB

机器人项目建表 SQL

部署项目功能前,在用户端使用的 MySQL 数据库中手动执行以下 SQL。只新增一张 robot_project 表,不自动迁移,不修改仓库 .sql 文件。每个用户的工作空间直接通过 owner_user_code 查询。

CREATE TABLE `robot_project` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '项目主键ID,仅内部使用',
  `project_code` varchar(64) COLLATE utf8mb4_bin NOT NULL COMMENT '项目唯一编码',
  `owner_user_code` char(32) COLLATE utf8mb4_bin NOT NULL COMMENT '所属用户唯一编码',
  `project_name` varchar(128) NOT NULL COMMENT '项目名称',
  `description` varchar(2000) NOT NULL DEFAULT '' COMMENT '项目简介',
  `cover_relative_path` varchar(512) COLLATE utf8mb4_bin DEFAULT NULL COMMENT '封面相对路径,不含域名和环境根目录',
  `snapshot_json` json NOT NULL COMMENT '独立保存的装配展示快照,不含原始对话和需求图片',
  `schema_version` varchar(32) COLLATE utf8mb4_bin NOT NULL COMMENT '项目快照格式版本,首版为project-v1',
  `match_status` varchar(16) COLLATE utf8mb4_bin NOT NULL COMMENT '方案完整度:complete或partial',
  `assembly_status` varchar(16) COLLATE utf8mb4_bin NOT NULL COMMENT '装配状态:ready或partial',
  `source_analysis_code` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL COMMENT '原始需求解析编码,仅用于溯源',
  `source_project_code` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL COMMENT 'fork来源项目编码,原创项目为空',
  `visibility` varchar(16) COLLATE utf8mb4_bin NOT NULL DEFAULT 'PRIVATE' COMMENT '可见性:PRIVATE私有,PUBLIC公开',
  `published_at` datetime(3) DEFAULT NULL COMMENT '最近一次从私有转为公开的时间,私有时为空',
  `deleted` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '删除标记:0未删除,1已删除',
  `created_at` datetime(3) NOT NULL COMMENT '创建时间',
  `updated_at` datetime(3) NOT NULL COMMENT '最近更新时间',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_robot_project_code` (`project_code`) COMMENT '项目编码唯一索引',
  KEY `idx_robot_project_owner`
    (`owner_user_code`, `deleted`, `updated_at`, `project_code`) COMMENT '个人项目列表索引',
  KEY `idx_robot_project_plaza`
    (`visibility`, `deleted`, `published_at`, `project_code`) COMMENT '广场项目列表索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
  COLLATE=utf8mb4_general_ci COMMENT='机器人装配项目表';

所有字符字段统一使用表级 utf8mb4 字符集。编码、路径、版本和状态字段指定 utf8mb4_bin,保留区分大小写的比较规则;名称和简介使用表级 utf8mb4_general_ci。

如果已经执行了此前的建表 SQL,手动执行以下语句,将原先单独使用 ASCII 的字段转换为 utf8mb4,保留原有类型、默认值及中文注释。新建表无需执行这段转换 SQL。

ALTER TABLE `robot_project`
  MODIFY COLUMN `project_code` varchar(64) COLLATE utf8mb4_bin NOT NULL COMMENT '项目唯一编码',
  MODIFY COLUMN `owner_user_code` char(32) COLLATE utf8mb4_bin NOT NULL COMMENT '所属用户唯一编码',
  MODIFY COLUMN `cover_relative_path` varchar(512) COLLATE utf8mb4_bin DEFAULT NULL COMMENT '封面相对路径,不含域名和环境根目录',
  MODIFY COLUMN `schema_version` varchar(32) COLLATE utf8mb4_bin NOT NULL COMMENT '项目快照格式版本,首版为project-v1',
  MODIFY COLUMN `match_status` varchar(16) COLLATE utf8mb4_bin NOT NULL COMMENT '方案完整度:complete或partial',
  MODIFY COLUMN `assembly_status` varchar(16) COLLATE utf8mb4_bin NOT NULL COMMENT '装配状态:ready或partial',
  MODIFY COLUMN `source_analysis_code` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL COMMENT '原始需求解析编码,仅用于溯源',
  MODIFY COLUMN `source_project_code` varchar(64) COLLATE utf8mb4_bin DEFAULT NULL COMMENT 'fork来源项目编码,原创项目为空',
  MODIFY COLUMN `visibility` varchar(16) COLLATE utf8mb4_bin NOT NULL DEFAULT 'PRIVATE' COMMENT '可见性:PRIVATE私有,PUBLIC公开';

来源编码不设置级联删除约束。保存项目后,原需求会话过期清理不影响项目;fork 后,来源项目取消发布或删除也不影响副本。

封面数据库路径示例为 projects/RP-xxx/covers/xxx.png。实际 OSS 对象键由当前 OSS_ROOT_PREFIX 加上此路径生成,域名由 APP_STORAGE_PUBLIC_BASE_URL 配置。切换环境只改变路径解析配置;若跨环境迁移数据,仍需将实际图片同步到目标桶的对应环境目录。

项目删除采用软删除。封面替换、项目软删除暂不物理清理 OSS 对象,因为已有 fork 可能共享这些对象;后续清理必须先确认没有项目引用。