# 文件夹服务集成完成

**日期**：2026-02-04  
**类型**：集成完成  
**影响范围**：后端 - 文件夹服务（路由注册、定时任务、测试配置）

---

## 变更概述

完成文件夹服务的最终集成工作，包括公开 API 路由注册、Celery 定时任务配置和测试数据库配置。

---

## 变更内容

### 1. 公开 API 路由注册

**文件**：`server/app/main.py`

**变更**：
```python
# 注册公开路由（无需认证）
from app.api.v1.public.shared_folders import router as public_shared_folders_router
app.include_router(
    public_shared_folders_router,
    prefix="/api/v1",
    tags=["公开分享"]
)
```

**说明**：
- 注册公开分享链接访问接口
- 无需认证即可访问
- 路由前缀：`/api/v1/public/shared/f/{token}`

---

### 2. Celery 任务配置

**文件**：`server/app/core/celery_app.py`

#### 2.1 任务模块注册

**变更**：
```python
celery_app = Celery(
    "jointo",
    broker=settings.CELERY_BROKER_URL,
    backend=settings.CELERY_RESULT_BACKEND,
    include=[
        "app.tasks.ai_tasks",
        "app.tasks.export_tasks",
        "app.tasks.credit_tasks",
        "app.tasks.cleanup_files",
        "app.tasks.folder_export_tasks",      # 新增
        "app.tasks.folder_cleanup_tasks",     # 新增
    ]
)
```

#### 2.2 任务路由配置

**变更**：
```python
task_routes={
    "app.tasks.ai_tasks.*": {"queue": "ai"},
    "app.tasks.export_tasks.*": {"queue": "export"},
    "app.tasks.folder_export_tasks.*": {"queue": "export"},        # 新增
    "app.tasks.folder_cleanup_tasks.*": {"queue": "maintenance"},  # 新增
},
```

**说明**：
- 导出任务路由到 `export` 队列
- 清理任务路由到 `maintenance` 队列

#### 2.3 定时任务配置

**变更**：
```python
beat_schedule={
    # ... 其他定时任务 ...
    
    # 每天凌晨 2 点清理过期的导出文件
    "cleanup-expired-exports": {
        "task": "app.tasks.folder_cleanup_tasks.cleanup_expired_exports",
        "schedule": crontab(hour=2, minute=0),
    },
    # 每天凌晨 3 点清理过期的分享链接
    "cleanup-expired-share-links": {
        "task": "app.tasks.folder_cleanup_tasks.cleanup_expired_share_links",
        "schedule": crontab(hour=3, minute=0),
    },
    # 每月 1 号凌晨 4 点清理撤销的分享链接（30天前）
    "cleanup-revoked-shares": {
        "task": "app.tasks.folder_cleanup_tasks.cleanup_revoked_shares",
        "schedule": crontab(day_of_month=1, hour=4, minute=0),
    },
}
```

**定时任务说明**：

| 任务名称 | 执行时间 | 功能 | 队列 |
|---------|---------|------|------|
| `cleanup-expired-exports` | 每天 02:00 | 清理过期的导出文件（24小时后） | maintenance |
| `cleanup-expired-share-links` | 每天 03:00 | 自动撤销过期的分享链接 | maintenance |
| `cleanup-revoked-shares` | 每月 1 号 04:00 | 物理删除已撤销 30 天的分享记录 | maintenance |

---

### 3. 测试配置更新

**文件**：
- `tests/unit/repositories/test_folder_share_repository.py`
- `tests/unit/repositories/test_folder_export_repository.py`

**变更**：
- 将所有测试方法的 `async_session` 参数改为 `db_session`
- 删除底部的 TODO fixture（使用 `conftest.py` 中的统一配置）

**示例**：
```python
# 变更前
async def test_create_user_share(self, async_session):
    repo = FolderShareRepository(async_session)

# 变更后
async def test_create_user_share(self, db_session):
    repo = FolderShareRepository(db_session)
```

**说明**：
- 使用 `server/tests/conftest.py` 中定义的 `db_session` fixture
- 自动处理事务回滚，确保测试隔离
- 无需额外配置测试数据库

---

## 部署说明

### 1. 重启服务

```bash
# 重启 FastAPI 应用（加载新路由）
docker restart jointo-server-app

# 重启 Celery Beat（加载新定时任务）
docker restart jointo-server-celery-beat

# 重启 Celery Worker（加载新任务模块）
docker restart jointo-server-celery-export
```

### 2. 验证路由注册

```bash
# 访问 API 文档
curl http://localhost:8000/api/docs

# 查找公开分享接口
# GET /api/v1/public/shared/f/{token}
# GET /api/v1/public/shared/f/{token}/info
# POST /api/v1/public/shared/f/{token}/verify-password
```

### 3. 验证定时任务

```bash
# 进入 Celery Beat 容器
docker exec -it jointo-server-celery-beat bash

# 查看定时任务配置
celery -A app.core.celery_app inspect scheduled

# 手动触发清理任务（测试）
docker exec jointo-server-app python -c "
from app.tasks.folder_cleanup_tasks import cleanup_expired_exports
result = cleanup_expired_exports.apply()
print(result.get())
"
```

---

## 测试验证

### 1. 运行单元测试

```bash
# 运行所有文件夹相关测试
docker exec jointo-server-app pytest tests/unit/repositories/test_folder_*.py -v

# 运行特定测试
docker exec jointo-server-app pytest tests/unit/repositories/test_folder_share_repository.py::TestFolderShareRepository::test_create_user_share -v
```

### 2. 测试公开 API

```bash
# 测试访问分享链接（无密码）
curl http://localhost:8000/api/v1/public/shared/f/test_token_123

# 测试访问分享链接（有密码）
curl "http://localhost:8000/api/v1/public/shared/f/test_token_123?password=secret"

# 测试获取分享信息
curl http://localhost:8000/api/v1/public/shared/f/test_token_123/info
```

### 3. 测试 Celery 任务

```bash
# 测试导出任务
docker exec jointo-server-app python -c "
from app.tasks.folder_export_tasks import process_folder_export
result = process_folder_export.apply_async(args=['test_job_id'])
print(f'Task ID: {result.id}')
"

# 查看任务状态
docker exec jointo-server-app python -c "
from celery.result import AsyncResult
from app.core.celery_app import celery_app
result = AsyncResult('task_id', app=celery_app)
print(f'Status: {result.status}')
print(f'Result: {result.result}')
"
```

---

## 架构图

### 文件夹服务完整架构

```
┌─────────────────────────────────────────────────────────────┐
│                      文件夹服务架构                          │
└─────────────────────────────────────────────────────────────┘

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  认证 API    │     │  公开 API    │     │  Celery 任务  │
│              │     │              │     │              │
│ /folders     │     │ /public/     │     │ - 导出任务   │
│ /shares      │     │  shared/f/   │     │ - 清理任务   │
│ /exports     │     │  {token}     │     │              │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       └────────────────────┼────────────────────┘
                            │
                    ┌───────▼────────┐
                    │  Service 层    │
                    │                │
                    │ - FolderService│
                    └───────┬────────┘
                            │
                    ┌───────▼────────┐
                    │ Repository 层  │
                    │                │
                    │ - FolderRepo   │
                    │ - ShareRepo    │
                    │ - ExportRepo   │
                    └───────┬────────┘
                            │
                    ┌───────▼────────┐
                    │  数据库层      │
                    │                │
                    │ - folders      │
                    │ - folder_shares│
                    │ - folder_exports│
                    └───────┬────────┘
                            │
                    ┌───────▼────────┐
                    │  对象存储      │
                    │                │
                    │ - 阿里云 OSS   │
                    │ - 导出文件     │
                    └────────────────┘
```

---

## 相关文档

- [文件夹服务需求文档](../../requirements/backend/04-services/project/folder-service.md)
- [Repository 层补全](./2026-02-04-folder-service-repository-completion.md)
- [完整实现文档](./2026-02-04-folder-service-complete-implementation.md)
- [OSS 集成文档](./2026-02-04-folder-service-oss-integration.md)

---

## 总结

本次变更完成了文件夹服务的最终集成：

1. ✅ **公开 API 路由** - 注册到 FastAPI 应用
2. ✅ **Celery 任务模块** - 注册到 Celery 应用
3. ✅ **任务路由配置** - 分配到正确的队列
4. ✅ **定时任务配置** - 配置清理任务调度
5. ✅ **测试配置更新** - 使用统一的测试 fixture

文件夹服务现已完全集成到项目中，可以正常运行。所有功能已就绪：

- ✅ 文件夹 CRUD 操作
- ✅ 用户分享和链接分享
- ✅ 异步导出任务
- ✅ 定时清理任务
- ✅ 公开分享链接访问
- ✅ 阿里云 OSS 集成
- ✅ 单元测试覆盖

**下一步建议**：
1. 实现文件夹内容收集逻辑（导出任务中的 TODO）
2. 添加集成测试（端到端测试）
3. 添加性能测试（大文件夹导出）
4. 配置监控和告警（任务失败通知）