fix: expand all UUID fields from varchar(32) to varchar(36) [P0] #204

Merged

xiaoxia merged 2 commits from fix/ingest-job-library-id-length into develop 2026-07-10 08:02:29 +08:00

Conversation 1 Commits 2 Files Changed 4

+346 -74

xiaoxia commented 2026-07-10 01:23:40 +08:00

Owner

Copy Link

Copy Source

P0 Hotfix: StringDataRightTruncation on upload/direct/complete

问题

ingest_jobs.library_id 字段为 varchar(32)，但标准 UUID（带横杠）是 36 字符，导致小程序上传时 StringDataRightTruncation 错误，上传功能完全不可用。

修复范围

全库扫描，所有 String(32) UUID 字段统一扩到 String(36)：

表	字段
projects	id, owner_user_id
edit_templates	id
edit_plans	id, template_id, source_edit_plan_id, project_id, created_by_user_id
template_clip_configs	id, template_id
edit_plan_clips	id, plan_id, template_clip_config_id, asset_id
ingest_jobs	id, project_id, library_id, result_asset_id
classification_jobs	id, project_id, asset_id
generation_tasks	id, project_id, strategy_id, asset_library_id, voice_library_id, created_by_user_id, source_edit_plan_id, batch_id
generated_videos	id, project_id, generation_task_id, duplicate_of
jobs	id, project_id, source_id, created_by_user_id

变更

• models.py: 10 张表所有 String(32) → String(36)
• alembic/versions/036_expand_uuid_fields_to_36.py: 迁移脚本
• tests/unit/test_uuid_field_length.py: 43 个单元测试

测试

• 43 个新测试全部通过
• 全量 1197 个单元测试无回归

## P0 Hotfix: StringDataRightTruncation on upload/direct/complete ### 问题 `ingest_jobs.library_id` 字段为 `varchar(32)`，但标准 UUID（带横杠）是 36 字符，导致小程序上传时 `StringDataRightTruncation` 错误，上传功能完全不可用。 ### 修复范围 全库扫描，所有 `String(32)` UUID 字段统一扩到 `String(36)`： | 表 | 字段 | |---|---| | projects | id, owner_user_id | | edit_templates | id | | edit_plans | id, template_id, source_edit_plan_id, project_id, created_by_user_id | | template_clip_configs | id, template_id | | edit_plan_clips | id, plan_id, template_clip_config_id, asset_id | | **ingest_jobs** | **id, project_id, library_id, result_asset_id** | | classification_jobs | id, project_id, asset_id | | generation_tasks | id, project_id, strategy_id, asset_library_id, voice_library_id, created_by_user_id, source_edit_plan_id, batch_id | | generated_videos | id, project_id, generation_task_id, duplicate_of | | jobs | id, project_id, source_id, created_by_user_id | ### 变更 - `models.py`: 10 张表所有 `String(32)` → `String(36)` - `alembic/versions/036_expand_uuid_fields_to_36.py`: 迁移脚本 - `tests/unit/test_uuid_field_length.py`: 43 个单元测试 ### 测试 - 43 个新测试全部通过 - 全量 1197 个单元测试无回归

xiaoxia added 1 commit 2026-07-10 01:23:40 +08:00

fix: expand all UUID fields from varchar(32) to varchar(36) ... abc54ace4e

P0 hotfix: ingest_jobs.library_id (and all other UUID fields across 10
tables) were varchar(32), but standard UUIDs with hyphens are 36 chars,
causing StringDataRightTruncation on insert — mini-program upload was
completely broken.

Changes:
- models.py: All String(32) UUID fields → String(36) across 10 tables
  (projects, edit_templates, edit_plans, template_clip_configs,
   edit_plan_clips, ingest_jobs, classification_jobs, generation_tasks,
   generated_videos, jobs)
- Alembic migration 036: ALTER COLUMN for all affected fields
- Unit tests: 43 tests verifying String(36) on all UUID columns and
  standard UUID construction with hyphens

Fixes: upload/direct/complete StringDataRightTruncation error

xiaoxia added 1 commit 2026-07-10 01:28:31 +08:00

chore: refresh schema-metadata-snapshot.json for UUID varchar(36) expansion ... f5f24e828c

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

xiaoxia commented 2026-07-10 07:59:24 +08:00

Author

Owner

Copy Link

Copy Source

✅ 审查结论：通过，可合并

PR #204 UUID 字段长度修复 — 代码审计报告

严重等级	数量
P0 阻塞	0
P1 高危	0
P2 中危	0
P3 优化	3

---

✅ 核心修复验证通过

1. Alembic 迁移脚本正确

• 迁移版本：036_expand_uuid_36，down_revision 正确指向 035_editing_mode
• upgrade / downgrade 双向完整，downgrade 按倒序执行
• 表名、字段名与 models.py 完全一致，无拼写错误
• 使用 op.alter_column() 标准语法，兼容 PostgreSQL

2. 全库扫描彻底，无遗漏
共覆盖 10 张表、42 个字段，全部从 varchar(32) 扩到 varchar(36)：

表名	字段数	字段
projects	2	id, owner_user_id
edit_templates	1	id
edit_plans	5	id, template_id, source_edit_plan_id, project_id, created_by_user_id
template_clip_configs	2	id, template_id
edit_plan_clips	4	id, plan_id, template_clip_config_id, asset_id
ingest_jobs	4	id, project_id, library_id, result_asset_id
classification_jobs	3	id, project_id, asset_id
generation_tasks	8	id, project_id, strategy_id, asset_library_id, voice_library_id, created_by_user_id, source_edit_plan_id, batch_id
generated_videos	4	id, project_id, generation_task_id, duplicate_of
jobs	4	id, project_id, source_id, created_by_user_id

已验证：users、assets、asset_libraries、title_libraries、voice_libraries、voice_clone_profiles 等表本来就是 varchar(36)，无需迁移，不属于遗漏。

3. 性能风险评估：低

• PostgreSQL 中 ALTER COLUMN TYPE varchar(36) 从 varchar(32) 扩容，仅修改系统表元数据（atttypmod），不需要重写表
• 操作几乎瞬时完成（毫秒级），大表也不会锁表很久
• 注意：仍需短暂 ACCESS EXCLUSIVE 锁，建议低峰期执行

4. 单元测试覆盖充分

• 43 个测试全部通过（本地验证 + CI 全绿）
• 覆盖所有 10 张表的所有 UUID 字段长度校验
• 包含 P0 回归测试：test_ingest_job_library_id_accepts_standard_uuid 专门验证 36 字符标准 UUID
• 包含模型构造测试：验证带横杠 UUID 可正常构造 ORM 对象

5. Schema 快照同步更新

• docs/schema-metadata-snapshot.json 已同步刷新，所有 VARCHAR(32) → VARCHAR(36)
• 快照与迁移脚本、模型定义三者一致

---

💡 P3 优化建议（不阻塞合并）

P3-1：迁移脚本建议显式指定 existing_nullable

• 文件：alembic/versions/036_expand_uuid_fields_to_36.py
• 位置：第 43-50 行（upgrade）和第 58-65 行（downgrade）
• 问题：existing_nullable=None 让 Alembic 自动检测 nullable 属性，虽然 PostgreSQL 场景下没问题，但显式指定更安全可靠，避免不同数据库行为差异
• 建议：从模型定义中提取每列的 nullable 属性，显式传入 existing_nullable=True/False

P3-2：建议低峰期执行迁移并提前验证

• 场景：生产环境执行迁移时
• 问题：虽然 varchar 扩容很快，但 ALTER TABLE 仍需短暂排他锁，高并发时可能造成连接堆积
• 建议：
  1. 先在 staging 环境验证迁移耗时
  2. 生产环境在业务低峰期执行
  3. 迁移前确认无长事务持有该表锁

P3-3：紧急修复分支建议从 develop 独立检出

• 观察：PR #204 分支基于 feature/unified-rendering-and-pipeline（PR #202）开发，包含了 PR #201 和 #202 的全部功能代码
• 说明：PR #201/#202 均已通过审查，合到 develop 没问题，不影响本次修复质量
• 建议：未来生产紧急修复建议直接从 develop/main 检出独立分支，避免功能代码与修复代码耦合，降低回滚复杂度

---

🔍 已验证项

• ✅ 迁移脚本表名、字段名全部正确，无拼写错误
• ✅ 所有 varchar(32) UUID 字段均已覆盖，无遗漏
• ✅ upgrade / downgrade 双向逻辑正确
• ✅ ORM 模型定义与迁移一致（String(32) → String(36)）
• ✅ 43 个单元测试全通过
• ✅ schema 快照同步更新
• ✅ 无 SQL 注入风险（DDL 语句，参数为表名列名）
• ✅ CI 全量测试通过无回归

---

结论：通过，可合并。 生产紧急修复质量达标，P0 问题彻底解决，3 个 P3 为最佳实践建议，不影响上线。

✅ **审查结论：通过，可合并** **PR #204 UUID 字段长度修复 — 代码审计报告** | 严重等级 | 数量 | |---------|------| | P0 阻塞 | 0 | | P1 高危 | 0 | | P2 中危 | 0 | | P3 优化 | 3 | --- ## ✅ 核心修复验证通过 **1. Alembic 迁移脚本正确** - 迁移版本：`036_expand_uuid_36`，down_revision 正确指向 `035_editing_mode` - upgrade / downgrade 双向完整，downgrade 按倒序执行 - 表名、字段名与 `models.py` 完全一致，无拼写错误 - 使用 `op.alter_column()` 标准语法，兼容 PostgreSQL **2. 全库扫描彻底，无遗漏** 共覆盖 **10 张表、42 个字段**，全部从 `varchar(32)` 扩到 `varchar(36)`： | 表名 | 字段数 | 字段 | |------|--------|------| | projects | 2 | id, owner_user_id | | edit_templates | 1 | id | | edit_plans | 5 | id, template_id, source_edit_plan_id, project_id, created_by_user_id | | template_clip_configs | 2 | id, template_id | | edit_plan_clips | 4 | id, plan_id, template_clip_config_id, asset_id | | ingest_jobs | 4 | id, project_id, library_id, result_asset_id | | classification_jobs | 3 | id, project_id, asset_id | | generation_tasks | 8 | id, project_id, strategy_id, asset_library_id, voice_library_id, created_by_user_id, source_edit_plan_id, batch_id | | generated_videos | 4 | id, project_id, generation_task_id, duplicate_of | | jobs | 4 | id, project_id, source_id, created_by_user_id | 已验证：`users`、`assets`、`asset_libraries`、`title_libraries`、`voice_libraries`、`voice_clone_profiles` 等表本来就是 `varchar(36)`，无需迁移，不属于遗漏。 **3. 性能风险评估：低** - PostgreSQL 中 `ALTER COLUMN TYPE varchar(36)` 从 `varchar(32)` 扩容，仅修改系统表元数据（atttypmod），**不需要重写表** - 操作几乎瞬时完成（毫秒级），大表也不会锁表很久 - 注意：仍需短暂 ACCESS EXCLUSIVE 锁，建议低峰期执行 **4. 单元测试覆盖充分** - 43 个测试全部通过（本地验证 + CI 全绿） - 覆盖所有 10 张表的所有 UUID 字段长度校验 - 包含 P0 回归测试：`test_ingest_job_library_id_accepts_standard_uuid` 专门验证 36 字符标准 UUID - 包含模型构造测试：验证带横杠 UUID 可正常构造 ORM 对象 **5. Schema 快照同步更新** - `docs/schema-metadata-snapshot.json` 已同步刷新，所有 VARCHAR(32) → VARCHAR(36) - 快照与迁移脚本、模型定义三者一致 --- ## 💡 P3 优化建议（不阻塞合并） ### P3-1：迁移脚本建议显式指定 existing_nullable - **文件**：`alembic/versions/036_expand_uuid_fields_to_36.py` - **位置**：第 43-50 行（upgrade）和第 58-65 行（downgrade） - **问题**：`existing_nullable=None` 让 Alembic 自动检测 nullable 属性，虽然 PostgreSQL 场景下没问题，但显式指定更安全可靠，避免不同数据库行为差异 - **建议**：从模型定义中提取每列的 nullable 属性，显式传入 `existing_nullable=True/False` ### P3-2：建议低峰期执行迁移并提前验证 - **场景**：生产环境执行迁移时 - **问题**：虽然 varchar 扩容很快，但 ALTER TABLE 仍需短暂排他锁，高并发时可能造成连接堆积 - **建议**： 1. 先在 staging 环境验证迁移耗时 2. 生产环境在业务低峰期执行 3. 迁移前确认无长事务持有该表锁 ### P3-3：紧急修复分支建议从 develop 独立检出 - **观察**：PR #204 分支基于 `feature/unified-rendering-and-pipeline`（PR #202）开发，包含了 PR #201 和 #202 的全部功能代码 - **说明**：PR #201/#202 均已通过审查，合到 develop 没问题，不影响本次修复质量 - **建议**：未来生产紧急修复建议直接从 develop/main 检出独立分支，避免功能代码与修复代码耦合，降低回滚复杂度 --- ## 🔍 已验证项 - ✅ 迁移脚本表名、字段名全部正确，无拼写错误 - ✅ 所有 `varchar(32)` UUID 字段均已覆盖，无遗漏 - ✅ upgrade / downgrade 双向逻辑正确 - ✅ ORM 模型定义与迁移一致（String(32) → String(36)） - ✅ 43 个单元测试全通过 - ✅ schema 快照同步更新 - ✅ 无 SQL 注入风险（DDL 语句，参数为表名列名） - ✅ CI 全量测试通过无回归 --- **结论：通过，可合并。** 生产紧急修复质量达标，P0 问题彻底解决，3 个 P3 为最佳实践建议，不影响上线。

xiaoxia merged commit 31c833745f into develop 2026-07-10 08:02:29 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#204