docs/v1.0/server/rfcs/131-implementation-summary.md

RFC 131 实施总结：项目回收站系统

状态: 已完成开发，待部署
完成时间: 2026-01-21
相关文档: RFC 131 | Changelog

---

实施概览

项目回收站系统已完成所有核心功能的开发，包括数据库迁移、后端 API、定时任务等。

---

已完成工作

✅ 1. 文档 (100%)

• 更新项目服务文档
• 创建 RFC 131 技术方案
• 创建 Changelog 变更日志
• 创建实施总结文档

文件清单：

• docs/requirements/backend/04-services/project/project-service.md
• docs/server/rfcs/131-project-trash-system.md
• docs/server/changelogs/2026-01-21-project-trash-system.md
• docs/server/rfcs/131-implementation-summary.md

✅ 2. 数据库层 (100%)

• 更新 ProjectStatus 枚举（0-3）
• 添加 trashed_at, permanently_deleted_at 字段
• 创建数据库迁移脚本（支持升级和降级）
• 优化索引策略

文件清单：

• server/app/models/project.py - 模型更新
• server/app/migrations/005_project_status_enhancement.py - 迁移脚本

关键变更：

class ProjectStatus(IntEnum):
    ACTIVE = 0        # 活跃项目
    ARCHIVED = 1      # 用户归档
    TRASHED = 2       # 回收站（30天内可恢复）
    SOFT_DELETED = 3  # 软删除（用户不可见）

✅ 3. 数据访问层 (100%)

• move_to_trash() - 移至回收站
• restore_from_trash() - 从回收站恢复
• permanent_delete() - 永久删除
• get_trashed_projects() - 查询回收站
• count_trashed_projects() - 统计数量
• 更新所有查询条件（排除回收站和软删除）

文件清单：

• server/app/repositories/project_repository.py

✅ 4. Schema 层 (100%)

• 添加 ProjectStatusEnum
• 添加 ProjectTrashResponse
• 添加 ProjectTrashListResponse
• 添加 ProjectRestoreResponse
• 添加 ProjectDeleteResponse
• 更新 ProjectResponse 添加 trashed_at 字段

文件清单：

• server/app/schemas/project.py

✅ 5. 业务逻辑层 (100%)

• get_trash_projects() - 获取回收站列表（含剩余天数）
• restore_project() - 恢复项目（含权限和名称冲突检查）
• permanent_delete_project() - 永久删除（含状态验证）
• 更新 delete_project() - 改为移至回收站

文件清单：

• server/app/services/project_service.py

✅ 6. API 层 (100%)

• GET /api/v1/projects/trash - 查看回收站
• POST /api/v1/projects/{id}/restore - 恢复项目
• DELETE /api/v1/projects/{id}/permanent - 永久删除
• 更新 DELETE /api/v1/projects/{id} - 移至回收站

文件清单：

• server/app/api/v1/projects.py

路由顺序：

GET  /projects/trash              # 回收站列表（必须在 /{id} 之前）
GET  /projects/{id}               # 项目详情
DELETE /projects/{id}             # 移至回收站
POST /projects/{id}/restore       # 恢复
DELETE /projects/{id}/permanent   # 永久删除

✅ 7. 定时任务 (100%)

• cleanup_expired_trash() - 30天自动清理
• cleanup_old_soft_deleted_projects() - 物理删除（可选）
• 任务调度配置

文件清单：

• server/app/tasks/__init__.py
• server/app/tasks/cleanup.py

调度配置：

• 每天凌晨 2 点执行自动清理
• 可选：每月 1 号凌晨 3 点物理删除 90 天前软删除的项目

---

待完成工作

⚠️ 1. 任务调度集成 (0%)

需要在 server/app/main.py 中集成 APScheduler：

from apscheduler.schedulers.asyncio import AsyncIOScheduler
from app.tasks.cleanup import CLEANUP_TASKS

scheduler = AsyncIOScheduler()

# 注册清理任务
for task_id, task_config in CLEANUP_TASKS.items():
    scheduler.add_job(
        task_config['func'],
        trigger=task_config['schedule'],
        **{k: v for k, v in task_config.items() if k not in ['func', 'schedule', 'description']},
        id=task_id
    )

@app.on_event("startup")
async def startup_event():
    scheduler.start()
    logger.info("定时任务调度器已启动")

@app.on_event("shutdown")
async def shutdown_event():
    scheduler.shutdown()
    logger.info("定时任务调度器已关闭")

依赖安装：

pip install apscheduler

⚠️ 2. 单元测试 (0%)

需要编写测试用例：

• tests/test_project_trash.py - 回收站功能测试
• tests/test_cleanup_tasks.py - 定时任务测试

⚠️ 3. 前端集成 (0%)

需要实现：

• 回收站页面 (client/src/pages/TrashPage.tsx)
• API 客户端方法 (client/src/services/api/projects.ts)
• TanStack Query hooks (client/src/hooks/api/useProjects.ts)

---

部署指南

前置条件

• Docker 和 Docker Compose 已安装
• 数据库已备份
• 服务正常运行

部署步骤

1. 备份数据库

docker compose exec postgres pg_dump -U postgres daoyanzu > backup_$(date +%Y%m%d).sql

2. 执行迁移

# 进入服务器容器
docker compose exec server bash

# 在容器内执行迁移
python app/migrations/005_project_status_enhancement.py upgrade

# 退出容器
exit

3. 验证迁移

# 检查状态分布
docker compose exec postgres psql -U postgres -d daoyanzu -c \
  "SELECT status, COUNT(*) FROM projects GROUP BY status;"

# 检查新字段
docker compose exec postgres psql -U postgres -d daoyanzu -c \
  "SELECT column_name, data_type FROM information_schema.columns 
   WHERE table_name = 'projects' 
   AND column_name IN ('trashed_at', 'permanently_deleted_at');"

# 检查索引
docker compose exec postgres psql -U postgres -d daoyanzu -c \
  "SELECT indexname FROM pg_indexes WHERE tablename = 'projects';"

4. 重启服务

docker compose restart server

5. 测试 API

# 测试回收站列表
curl -X GET "http://localhost:6170/api/v1/projects/trash" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 测试删除（移至回收站）
curl -X DELETE "http://localhost:6170/api/v1/projects/{project_id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 测试恢复
curl -X POST "http://localhost:6170/api/v1/projects/{project_id}/restore" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 测试永久删除
curl -X DELETE "http://localhost:6170/api/v1/projects/{project_id}/permanent" \
  -H "Authorization: Bearer YOUR_TOKEN"

回滚方案

如果迁移出现问题，可以回滚：

# 进入服务器容器
docker compose exec server bash

# 执行回滚
python app/migrations/005_project_status_enhancement.py downgrade

# 退出容器
exit

# 重启服务
docker compose restart server

---

验证清单

数据库验证

• 状态字段类型为 SMALLINT
• 状态值为 0, 1, 2, 3
• trashed_at 字段存在
• permanently_deleted_at 字段存在
• 索引已更新
• 旧数据已正确迁移

API 验证

• GET /projects/trash 返回回收站列表
• DELETE /projects/{id} 移至回收站
• POST /projects/{id}/restore 恢复成功
• DELETE /projects/{id}/permanent 永久删除
• 权限检查正常（只有 owner 可操作）
• 错误处理正确

业务逻辑验证

• 删除后项目进入回收站
• 回收站项目不出现在正常列表
• 恢复后项目状态变为 active
• 永久删除后用户不可见
• 剩余天数计算正确
• 名称冲突检查正常

---

性能指标

预期性能

• 查询性能: 回收站查询 < 100ms
• 删除操作: < 50ms
• 恢复操作: < 100ms
• 自动清理: < 5s（处理 1000 个项目）

监控指标

• 回收站项目数量
• 自动清理成功率
• 恢复操作频率
• 永久删除频率

---

已知限制

1. 定时任务未集成: 需要手动集成 APScheduler
2. 无单元测试: 需要补充测试用例
3. 前端未实现: 需要实现回收站页面
4. 无批量操作: 不支持批量恢复/删除

---

后续优化

短期（1-2 周）

1. 集成定时任务调度器
2. 编写单元测试
3. 实现前端回收站页面
4. 添加操作日志

中期（1-2 月）

1. 支持批量操作
2. 添加回收站搜索
3. 自定义保留期
4. 回收站容量限制

长期（3-6 月）

1. 删除原因记录
2. 恢复历史追踪
3. 数据归档策略
4. 性能优化

---

团队协作

后端开发

• 数据库迁移 - 已完成
• API 实现 - 已完成
• 任务调度集成 - 待完成
• 单元测试 - 待完成

前端开发

• 回收站页面 - 待开始
• API 集成 - 待开始
• UI/UX 设计 - 待开始

测试

• 功能测试 - 待开始
• 性能测试 - 待开始
• 安全测试 - 待开始

运维

• 部署到测试环境 - 待开始
• 监控配置 - 待开始
• 告警规则 - 待开始

---

联系方式

如有问题，请联系：

• 后端负责人：待定
• 前端负责人：待定
• 项目经理：待定

---

文档版本: v1.0
最后更新: 2026-01-21
状态: 已完成开发，待部署