docs/v1.0/server/changelogs/2026-01-28-service-docs-datetime-fix.md

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

修复示例:

# ❌ 错误
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

修复示例:

# ❌ 错误
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

修复示例:

# ❌ 错误
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 定义）

修复示例:

# ❌ 错误
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

修复示例:

# ❌ 错误
'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 的时间戳字段

修复示例:

# ❌ 错误
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

修复示例:

# ❌ 错误
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 定义）

# ❌ 错误
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 定义）

# ❌ 错误
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 层时间计算

# ❌ 错误
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 层时间更新

# ❌ 错误
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

---

验证结果

# 验证命令
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 文档完全符合项目架构约束。