3.4 KiB

Raw Blame History

数据库表注释迁移补充

日期：2026-01-29
类型：数据库迁移
影响范围：folder_members 表

变更概述

为 folder_members 表补充完整的表和字段注释，确保数据库文档完整性。

问题背景

在检查数据库迁移文件时发现：

✅ folders 表：初始迁移中已有完整注释
❌ folder_members 表：初始迁移中缺少注释
✅ folder_shares 表：专门迁移中已有完整注释
✅ folder_export_jobs 表：专门迁移中已有完整注释

解决方案

创建新的迁移文件 20260129_1700_add_folder_members_comments.py，为 folder_members 表添加完整注释。

添加的注释

表注释：

COMMENT ON TABLE folder_members IS '文件夹成员表';

字段注释：

COMMENT ON COLUMN folder_members.id IS '成员记录ID (UUID v7)';
COMMENT ON COLUMN folder_members.folder_id IS '文件夹ID（逻辑外键，无物理约束）';
COMMENT ON COLUMN folder_members.user_id IS '用户ID（逻辑外键，无物理约束）';
COMMENT ON COLUMN folder_members.role IS '成员角色: 1=owner, 2=editor, 3=viewer';
COMMENT ON COLUMN folder_members.inherited IS '是否从父文件夹继承权限';
COMMENT ON COLUMN folder_members.invited_by IS '邀请人用户ID（逻辑外键，无物理约束）';
COMMENT ON COLUMN folder_members.joined_at IS '加入时间（自动记录时区）';
COMMENT ON COLUMN folder_members.created_at IS '创建时间（自动记录时区）';

迁移文件

文件路径：server/alembic/versions/20260129_1700_add_folder_members_comments.py

Revision ID：20260129_1700
Revises：20260129_1600

执行结果

$ docker exec jointo-server-app alembic upgrade head
INFO  [alembic.runtime.migration] Running upgrade 20260129_1600 -> 20260129_1700, 添加 folder_members 表的注释

$ docker exec jointo-server-app alembic current
20260129_1700 (head)

验证

使用 \d+ folder_members 命令验证注释已成功添加：

Table "public.folder_members"
   Column   |           Type           | Description
------------+--------------------------+------------------------------------------
 id         | uuid                     | 成员记录ID (UUID v7)
 folder_id  | uuid                     | 文件夹ID（逻辑外键，无物理约束）
 user_id    | uuid                     | 用户ID（逻辑外键，无物理约束）
 role       | smallint                 | 成员角色: 1=owner, 2=editor, 3=viewer
 inherited  | boolean                  | 是否从父文件夹继承权限
 invited_by | uuid                     | 邀请人用户ID（逻辑外键，无物理约束）
 joined_at  | timestamp with time zone | 加入时间（自动记录时区）
 created_at | timestamp with time zone | 创建时间（自动记录时区）

影响范围

✅ 数据库元数据完整性提升
✅ 开发者可通过 \d+ 命令查看字段说明
✅ 数据库文档自动化生成更准确
✅ 无数据变更，无业务影响

后续建议

建议在创建新表时，在同一迁移文件中同时添加表和字段注释，避免后续补充。

变更人：Kiro
审核状态：✅ 已验证

3.4 KiB Raw Blame History