开发文档

数据模型

结合现有文档整理出的业务表、字段口径与当前实现差异。

先看一个关键事实

仓库里的历史数据文档包含“早期规划口径”和“当前已实现口径”两层信息，读的时候要分开：

早期规划文档里很多页面和表结构以 project_id 为核心
当前素材库实际实现已经切到“目录驱动”，核心表是 library_entries 和 library

开发时要优先以“当前实现口径”为准，而不是直接照搬早期方案。

当前素材库实现

`library_entries`

负责目录元数据
记录目录树、目录状态、归属人和回收站批次

`library`

负责素材文件主数据
上传成功后写入该表
当前重点字段包括：
- asset_name
- asset_type
- file_ext
- file_size
- storage_path
- relative_path
- shanghai_full_path
- checksum
- upload_user_id
- upload_time
- status
- original_storage_path
- original_relative_path
- deleted_by
- deleted_at
- recycle_batch

规划文档里的通用业务表

历史设计文档里仍保留了一批通用业务表定义，可作为后续扩展参考：

projects
assets
project_files
project_file_versions
upload_tasks
edit_statuses
operation_logs
system_configs

常用状态口径

素材状态

pending
uploading
stored
syncing
available
failed
archived

上传任务状态

pending
uploading
success
failed
retrying

编辑状态

editing
finished

字段设计原则

主键统一用 bigint unsigned
审计字段统一保留 created_at、updated_at
用户字段尽量复用现有后台用户体系
路径字段优先保存相对路径，完整路径主要用于展示和落盘缓存
状态字段尽量使用稳定枚举，不要混入自由文本

开发时的使用建议

先确认要改的是“已落地表”还是“规划表”
涉及素材库时，优先看 video-collab-material-library-current.md
涉及新业务实体时，再参考 video-collab-data-dictionary.md 和 video-collab-field-spec.md