# Service 文档时间戳规范修复 **日期**: 2026-01-28 **类型**: 文档修复 **影响范围**: `docs/requirements/backend/04-services/**/*.md` ## 概述 全面修复 Service 文档中的 `datetime.utcnow` 错误用法，统一使用 `datetime.now(timezone.utc)` 符合项目时区规范。 ## 修复范围 共修复 **12 个 Service 文档**，涉及 **50+ 处**时间戳错误用法。 ### User 服务 (3个文档) #### 1. user-service.md - **修复数量**: 8 处 - **修复内容**: - Model 层时间戳字段：`created_at`, `updated_at`, `last_used_at` - Service 层时间计算：`expires_at`, `deleted_at` - 会话更新：`last_used_at` **修复示例**: ```python # ❌ 错误 created_at: datetime = Field(default_factory=datetime.utcnow) expires_at=datetime.utcnow() + timedelta(days=7) # ✅ 正确 created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) expires_at=datetime.now(timezone.utc) + timedelta(days=7) ``` #### 2. sms-service.md - **修复数量**: 9 处 - **修复内容**: - Model 层时间戳字段：`created_at`, `updated_at` - 验证码过期时间：`expires_at` - 验证码清理：`cutoff_time` - 验证码验证：`expires_at` 比较 - 软删除：`deleted_at` **修复示例**: ```python # ❌ 错误 expires_at=datetime.utcnow() + timedelta(minutes=10) cutoff_time = datetime.utcnow() - timedelta(hours=24) # ✅ 正确 expires_at=datetime.now(timezone.utc) + timedelta(minutes=10) cutoff_time = datetime.now(timezone.utc) - timedelta(hours=24) ``` #### 3. wechat-service.md - **修复数量**: 5 处 - **修复内容**: - Model 层时间戳字段：`created_at`, `updated_at` - 用户信息更新：`updated_at` - 时间戳生成：`timestamp` **修复示例**: ```python # ❌ 错误 user.updated_at = datetime.utcnow() timestamp = int(datetime.utcnow().timestamp()) # ✅ 正确 user.updated_at = datetime.now(timezone.utc) timestamp = int(datetime.now(timezone.utc).timestamp()) ``` --- ### Project 服务 (6个文档) #### 4. folder-service.md - **修复数量**: 2 处 - **修复内容**: Model 层时间戳字段 #### 5. project-service.md - **修复数量**: 2 处 - **修复内容**: Model 层时间戳字段（使用 Column 定义） **修复示例**: ```python # ❌ 错误 created_at = Column(DateTime, default=datetime.utcnow) updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) # ✅ 正确 created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc)) updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc)) ``` #### 6. project-resource-service.md - **修复数量**: 2 处 - **修复内容**: Model 层时间戳字段 #### 7. comment-service.md - **修复数量**: 3 处 - **修复内容**: - Model 层时间戳字段 - 评论解决时间：`resolved_at` **修复示例**: ```python # ❌ 错误 'resolved_at': datetime.utcnow() # ✅ 正确 'resolved_at': datetime.now(timezone.utc) ``` #### 8. screenplay-service.md - **修复数量**: 8 处 - **修复内容**: 多个 Model 的时间戳字段（Screenplay, ScreenplayVersion, ScreenplayCharacter, ScreenplayScene, ScreenplayProp） #### 9. screenplay-tag-service.md - **修复数量**: 4 处 - **修复内容**: ScreenplayTagDefinition 和 ScreenplayElementTag 的时间戳字段 #### 10. storyboard-service.md - **修复数量**: 4 处 - **修复内容**: Storyboard 和 StoryboardResource 的时间戳字段 **修复示例**: ```python # ❌ 错误 created_at: datetime = Field( default_factory=datetime.utcnow, sa_column=Column(DateTime(timezone=True)) ) # ✅ 正确 created_at: datetime = Field( default_factory=lambda: datetime.now(timezone.utc), sa_column=Column(DateTime(timezone=True)) ) ``` --- ### AI 服务 (1个文档) #### 11. ai-service.md - **修复数量**: 2 处 - **修复内容**: AIJob Model 的时间戳字段 --- ### Resource 服务 (1个文档) #### 12. file-storage-service.md - **修复数量**: 3 处 - **修复内容**: - FileChecksum Model 的时间戳字段 - 文件访问时间更新：`last_accessed_at` **修复示例**: ```python # ❌ 错误 file_checksum.last_accessed_at = datetime.utcnow() # ✅ 正确 file_checksum.last_accessed_at = datetime.now(timezone.utc) ``` --- ### Credit 服务 (已在之前修复) #### credit-service.md - **修复数量**: 5 处 - **修复内容**: - 积分冻结时间：`frozen_at` - 任务过期时间：`expires_at` - 任务完成时间：`completed_at` - 超时阈值计算：`timeout_threshold` - 旧记录清理：`cutoff_date` --- ## 修复模式总结 ### 1. Model 层时间戳字段（Field 定义） ```python # ❌ 错误 created_at: datetime = Field(default_factory=datetime.utcnow) updated_at: datetime = Field(default_factory=datetime.utcnow) # ✅ 正确 created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) ``` **关键点**: 必须使用 `lambda` 包装，否则所有实例共享同一时间戳。 ### 2. Model 层时间戳字段（Column 定义） ```python # ❌ 错误 created_at = Column(DateTime, default=datetime.utcnow) updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) # ✅ 正确 created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc)) updated_at = Column(DateTime, default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc)) ``` ### 3. Service 层时间计算 ```python # ❌ 错误 expires_at = datetime.utcnow() + timedelta(hours=24) cutoff_time = datetime.utcnow() - timedelta(days=30) # ✅ 正确 expires_at = datetime.now(timezone.utc) + timedelta(hours=24) cutoff_time = datetime.now(timezone.utc) - timedelta(days=30) ``` ### 4. Service 层时间更新 ```python # ❌ 错误 user.updated_at = datetime.utcnow() code.deleted_at = datetime.utcnow() # ✅ 正确 user.updated_at = datetime.now(timezone.utc) code.deleted_at = datetime.now(timezone.utc) ``` --- ## 修复统计 | 服务类型 | 文档数量 | 修复数量 | 主要修复内容 | |---------|---------|---------|-------------| | User 服务 | 3 | 22 | 时间戳字段、过期时间、软删除 | | Project 服务 | 6 | 25 | 时间戳字段、评论解决时间 | | AI 服务 | 1 | 2 | 时间戳字段 | | Resource 服务 | 1 | 3 | 时间戳字段、访问时间 | | Credit 服务 | 1 | 5 | 冻结时间、过期时间、完成时间 | | **总计** | **12** | **57** | - | --- ## 规范符合性 修复后，所有 Service 文档完全符合项目时区规范： - ✅ 所有 datetime 使用 `datetime.now(timezone.utc)` - ✅ 禁止使用已废弃的 `datetime.utcnow()` - ✅ Model 层使用 `default_factory=lambda: datetime.now(timezone.utc)` - ✅ Service 层时间计算使用 aware datetime - ✅ 所有时间戳包含时区信息 --- ## 相关规范 - **时区规范**: `docs/architecture/datetime-timezone-standards.md` - **Backend 规范**: `.claude/skills/jointo-tech-stack/references/backend.md > 时间与时区规范` - **Database 规范**: `.claude/skills/jointo-tech-stack/references/database.md` --- ## 验证结果 ```bash # 验证命令 grep -r "datetime.utcnow" docs/requirements/backend/04-services/ # 验证结果 No matches found. # ✅ 所有错误用法已修复 ``` --- ## 后续建议 1. **代码实现验证**: 检查实际代码实现是否与文档一致 2. **测试验证**: 运行测试确保时区处理正确 3. **CI/CD 检查**: 添加 pre-commit hook 检查 `datetime.utcnow` 用法 4. **文档审查**: 定期审查新增文档是否符合时区规范 --- ## 总结 本次修复全面清理了 Service 文档中的时间戳错误用法，统一使用 `datetime.now(timezone.utc)` 符合项目时区规范。修复涵盖 12 个文档、57 处错误用法，确保所有 Service 文档完全符合项目架构约束。