# Celery 应用路径标准化

**日期**: 2026-01-28  
**类型**: 架构优化  
**影响范围**: Celery 应用配置、文档规范

## 概述

统一 Celery 应用配置路径，删除冗余文件，确保项目架构清晰。将 Celery 应用配置从 `app/tasks/celery_app.py` 迁移到 `app/core/celery_app.py`，符合核心基础设施的架构设计。

## 问题背景

项目中存在两个 `celery_app.py` 文件：

1. **`app/core/celery_app.py`**: 配置完整，包含任务路由、限流、BaseTask 等高级配置
2. **`app/tasks/celery_app.py`**: 配置简单，功能较少

**问题**:
- 路径不一致导致混淆
- 大部分任务文件使用 `app.core.celery_app`，但 `ai_service.py` 使用 `app.tasks.celery_app`
- 文档中路径不统一
- 时区配置不一致（`Asia/Shanghai` vs `UTC`）

## 解决方案

### 1. 统一使用 `app/core/celery_app`

**理由**:
- **符合架构**: `core/` 目录存放核心基础设施（database, config, security, celery_app）
- **配置完整**: 包含任务路由、限流、BaseTask 等高级配置
- **使用广泛**: 5 个文件使用 vs 1 个文件使用
- **职责清晰**: `core/` 存放基础设施，`tasks/` 存放任务实现

**项目结构**:
```
app/core/
├── config.py          # 配置管理（全局单例）
├── database.py        # 数据库连接（全局单例）
├── security.py        # 安全工具（全局单例）
├── cache.py           # 缓存配置（全局单例）
├── celery_app.py      # Celery 应用（全局单例）✅
└── storage.py         # 存储配置（全局单例）

app/tasks/
├── ai_tasks.py        # AI 任务实现
├── export_tasks.py    # 导出任务实现
└── credit_tasks.py    # 积分任务实现
```

### 2. 修复时区配置

**问题**: `app/core/celery_app.py` 使用 `timezone="Asia/Shanghai"`，不符合项目 UTC 规范。

**修复**:
```python
# ❌ 错误
celery_app.conf.update(
    timezone="Asia/Shanghai",
    enable_utc=True,
)

# ✅ 正确
celery_app.conf.update(
    timezone="UTC",
    enable_utc=True,
)
```

**理由**: 项目统一使用 UTC 时区，数据库和后端均使用 UTC，Celery 也应保持一致。

## 执行步骤

### 1. 删除冗余文件

```bash
# 删除 app/tasks/celery_app.py
rm server/app/tasks/celery_app.py
```

### 2. 修复代码导入路径

**修复 `ai_service.py`**:
```python
# ❌ 错误
from app.tasks.celery_app import celery_app

# ✅ 正确
from app.core.celery_app import celery_app
```

### 3. 修复时区配置

**修复 `app/core/celery_app.py`**:
```python
celery_app.conf.update(
    timezone="UTC",  # 修改为 UTC
    enable_utc=True,
)
```

### 4. 更新文档

**修复 `backend.md`**:
- 更新 Celery 应用配置路径
- 更新 Docker Compose 命令
- 更新常用命令

**修复 `infrastructure.md`**:
- 已使用正确路径，无需修改

## 修改文件清单

### 代码文件

| 文件 | 操作 | 说明 |
|------|------|------|
| `server/app/tasks/celery_app.py` | 删除 | 冗余文件 |
| `server/app/core/celery_app.py` | 修改 | 修复时区配置 |
| `server/app/services/ai_service.py` | 修改 | 修复导入路径 |

### 文档文件

| 文件 | 操作 | 说明 |
|------|------|------|
| `.claude/skills/jointo-tech-stack/references/backend.md` | 修改 | 更新 Celery 路径 |
| `.claude/skills/jointo-tech-stack/references/infrastructure.md` | 无需修改 | 已使用正确路径 |

## 标准用法

### 导入方式

```python
# 在任务文件中
from app.core.celery_app import celery_app

@celery_app.task(name="app.tasks.ai_tasks.generate_image")
def generate_image(prompt: str):
    pass

# 在 Service 中
from app.core.celery_app import celery_app

task = generate_image.delay("测试")
```

### 命令行使用

```bash
# 启动 Worker
celery -A app.core.celery_app worker -Q ai -l info

# 启动 Beat
celery -A app.core.celery_app beat -l info

# 查看任务列表
celery -A app.core.celery_app inspect registered

# 查看活跃任务
celery -A app.core.celery_app inspect active
```

### Docker Compose 配置

```yaml
celery-ai:
  build: .
  command: celery -A app.core.celery_app worker -Q ai -l info -n ai-worker@%h
  depends_on:
    - postgres
    - redis
    - rabbitmq

celery-beat:
  build: .
  command: celery -A app.core.celery_app beat -l info
  depends_on:
    - postgres
    - redis
    - rabbitmq
```

## 验证结果

### 代码验证

```bash
# 验证导入路径
grep -r "from app.tasks.celery_app import" server/app/
# 结果：无匹配（✅ 已全部修复）

grep -r "from app.core.celery_app import" server/app/
# 结果：6 个文件使用正确路径
```

### 文档验证

```bash
# 验证文档路径
grep -r "app.tasks.celery_app" .claude/skills/jointo-tech-stack/references/
# 结果：无匹配（✅ 已全部修复）

grep -r "app.core.celery_app" .claude/skills/jointo-tech-stack/references/
# 结果：所有文档使用正确路径
```

## 影响评估

### 正面影响

1. **架构清晰**: 核心基础设施统一放在 `core/` 目录
2. **路径统一**: 所有代码和文档使用相同路径
3. **时区一致**: Celery 时区与项目规范一致
4. **减少混淆**: 删除冗余文件，避免开发者困惑

### 潜在影响

1. **需要重启服务**: 修改 Celery 配置后需要重启 Worker 和 Beat
2. **文档更新**: 需要通知团队成员使用新路径

## 后续建议

1. **CI/CD 检查**: 添加 pre-commit hook 检查 `app.tasks.celery_app` 导入
2. **团队通知**: 通知团队成员使用 `app.core.celery_app`
3. **文档审查**: 定期审查文档确保路径一致

## 相关规范

- **Backend 规范**: `.claude/skills/jointo-tech-stack/references/backend.md > Celery 异步任务`
- **Infrastructure 规范**: `.claude/skills/jointo-tech-stack/references/infrastructure.md > Celery 异步任务`
- **时区规范**: `docs/architecture/datetime-timezone-standards.md`

## 总结

本次优化统一了 Celery 应用配置路径，删除了冗余文件，修复了时区配置，确保项目架构清晰、规范一致。所有代码和文档现在使用统一的 `app.core.celery_app` 路径，符合核心基础设施的架构设计。