# 数据库表注释迁移补充

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

---

## 变更概述

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

## 问题背景

在检查数据库迁移文件时发现：
- ✅ `folders` 表：初始迁移中已有完整注释
- ❌ `folder_members` 表：初始迁移中缺少注释
- ✅ `folder_shares` 表：专门迁移中已有完整注释
- ✅ `folder_export_jobs` 表：专门迁移中已有完整注释

## 解决方案

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

### 添加的注释

**表注释**：
```sql
COMMENT ON TABLE folder_members IS '文件夹成员表';
```

**字段注释**：
```sql
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`

## 执行结果

```bash
$ 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+` 命令查看字段说明
- ✅ 数据库文档自动化生成更准确
- ✅ 无数据变更，无业务影响

## 相关文档

- [文件夹服务文档](../../requirements/backend/04-services/project/folder-service.md)
- [初始迁移文件](../../server/alembic/versions/20260127_1931_3a3a2a1417de_initial_schema_初始化所有表结构.py)

## 后续建议

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

---

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