时区修正总结

修正目标

将 data_orders 表的三个 timestamp 字段（created_at、updated_at、processed_at）以及其他相关表的时间字段，从使用 UTC 时间改为使用东八区（Asia/Shanghai）时间。

修改内容

1. 创建时区工具模块

文件: app/core/common/timezone_utils.py

创建了统一的时区处理工具模块，提供以下功能：

now_china(): 获取当前东八区时间（带时区信息）
now_china_naive(): 获取当前东八区时间（不带时区信息，用于数据库存储）
to_china_time(): 将任意时区的时间转换为东八区时间
utc_to_china_naive(): 将 UTC 时间转换为东八区时间（不带时区信息）

2. 修正数据模型

2.1 `app/models/data_product.py`

DataProduct 模型:

created_at: datetime.utcnow → now_china_naive
updated_at: datetime.utcnow → now_china_naive
mark_as_viewed(): 使用 now_china_naive()
update_data_stats(): 使用 now_china_naive()

DataOrder 模型:

created_at: datetime.utcnow → now_china_naive
updated_at: datetime.utcnow → now_china_naive
processed_at: 默认值保持 None，但在更新时使用 now_china_naive()
update_status(): 使用 now_china_naive()
set_extraction_result(): 使用 now_china_naive()
set_graph_analysis(): 使用 now_china_naive()
set_result(): 使用 now_china_naive()
reject(): 使用 now_china_naive()

2.2 `app/models/metadata_review.py`

MetadataReviewRecord 模型:

created_at: datetime.utcnow → now_china_naive
updated_at: datetime.utcnow → now_china_naive

MetadataVersionHistory 模型:

created_at: datetime.utcnow → now_china_naive

update_review_record_resolution 函数:

resolved_at: 使用 now_china_naive()
updated_at: 使用 now_china_naive()

3. 修正服务层

3.1 `app/core/data_service/data_product_service.py`

修正了所有使用 datetime.utcnow() 的地方：

register_product(): 更新现有产品和创建新产品时使用 now_china_naive()
update_product_stats(): 使用 now_china_naive()
refresh_product_stats(): 使用 now_china_naive()
update_order(): 使用 now_china_naive()

3.2 `app/core/meta_data/redundancy_check.py`

修正了创建审核记录时的时间字段：

created_at: 使用 now_china_naive()
updated_at: 使用 now_china_naive()

3.3 `app/core/business_domain/business_domain.py`

修正了创建审核记录时的时间字段：

created_at: 使用 now_china_naive()
updated_at: 使用 now_china_naive()

技术实现

使用 zoneinfo 而非 pytz

本次修正使用了 zoneinfo 模块，而不是第三方库 pytz。理由如下：

标准库支持: Python 3.9+ 内置 zoneinfo，Python 3.8 使用 backports.zoneinfo
更简洁的 API: 相比 pytz，zoneinfo 的 API 更符合 Python 的 datetime 使用习惯
自动更新: 使用系统的 IANA 时区数据库，自动获取最新的时区规则

Python 版本兼容性

代码已兼容 Python 3.8 和 3.9+：

try:
    # Python 3.9+
    from zoneinfo import ZoneInfo
except ImportError:
    # Python 3.8 使用 backports
    from backports.zoneinfo import ZoneInfo

依赖要求:

Python 3.8: 需要安装 backports.zoneinfo 包
Python 3.9+: 使用标准库，无需额外安装
所有版本: 需要系统安装 tzdata 包

数据库存储策略

采用 naive datetime 存储策略：

数据库中存储不带时区信息的 datetime（naive datetime）
所有时间统一使用东八区时间
在应用层确保时间的一致性

这种策略的优点：

数据库字段类型简单（TIMESTAMP 而非 TIMESTAMP WITH TIME ZONE）
避免时区转换的复杂性
符合项目现有的数据库设计

影响范围

直接影响的表

data_orders: created_at, updated_at, processed_at
data_products: created_at, updated_at, last_updated_at, last_viewed_at
metadata_review_records: created_at, updated_at, resolved_at
metadata_version_history: created_at

间接影响

所有依赖这些时间字段的业务逻辑都将使用东八区时间，包括：

数据订单的创建、更新、处理流程
数据产品的注册、更新、查看记录
元数据审核记录的创建和解决

向后兼容性

已有数据

数据库中已存在的记录可能使用的是 UTC 时间。建议：

新旧数据混合期: 在一段时间内，数据库中会同时存在 UTC 时间和东八区时间的记录
数据迁移（可选）: 如果需要统一历史数据，可以执行以下 SQL：

-- 将 UTC 时间转换为东八区时间（+8小时）
UPDATE data_orders 
SET created_at = created_at + INTERVAL '8 hours',
    updated_at = updated_at + INTERVAL '8 hours',
    processed_at = processed_at + INTERVAL '8 hours'
WHERE created_at < '2026-01-12 00:00:00';  -- 修正前的数据

UPDATE data_products
SET created_at = created_at + INTERVAL '8 hours',
    updated_at = updated_at + INTERVAL '8 hours',
    last_updated_at = last_updated_at + INTERVAL '8 hours',
    last_viewed_at = last_viewed_at + INTERVAL '8 hours'
WHERE created_at < '2026-01-12 00:00:00';

UPDATE metadata_review_records
SET created_at = created_at + INTERVAL '8 hours',
    updated_at = updated_at + INTERVAL '8 hours',
    resolved_at = resolved_at + INTERVAL '8 hours'
WHERE created_at < '2026-01-12 00:00:00';

UPDATE metadata_version_history
SET created_at = created_at + INTERVAL '8 hours'
WHERE created_at < '2026-01-12 00:00:00';

API 响应

所有 API 返回的时间字段（ISO 8601 格式）现在表示的是东八区时间，而不是 UTC 时间。

测试建议

创建新订单: 验证 created_at 字段是否为东八区当前时间
更新订单状态: 验证 updated_at 和 processed_at 是否正确
注册数据产品: 验证时间字段是否正确
查看数据产品: 验证 last_viewed_at 是否更新为东八区时间
元数据审核: 验证审核记录的时间字段

符合业务规则

本次修正符合 BUSINESS_RULES.md 中的规定：

# Use East Asia timezone for all timestamps
from datetime import datetime
import pytz

虽然业务规则中提到了 pytz，但我们使用了更现代的 zoneinfo 标准库，功能等价且更优。

总结

✅ 所有相关的时间字段已统一使用东八区时间
✅ 创建了统一的时区工具模块，便于后续维护
✅ 修正了 6 个文件，涉及模型层和服务层
✅ 代码通过了 linter 检查，无语法错误
✅ 符合项目的业务规则要求

修正日期: 2026-01-12
修正人: AI Assistant

timezone_fix_summary.md 6.7 KB 文件历史 原始文件