docs/v1.0/server/changelogs/2026-01-29-project-service-doc-tech-stack-compliance.md

项目服务文档技术栈规范符合性修正

变更日期：2026-01-29
变更类型：文档修正
影响范围：项目服务设计文档

---

变更概述

修正 project-service.md 文档以完全符合 jointo-tech-stack 技术栈规范，包括数据库设计、API 响应格式、枚举类型处理、异步编程等方面。

---

主要修正内容

1. 数据库设计规范

修正前：

• 缺少详细的 SQL 注释
• 索引注释不完整
• 缺少 ProjectStatus 枚举定义

修正后：

• ✅ 所有字段添加详细注释说明用途
• ✅ 所有索引添加用途说明
• ✅ 补充 ProjectStatus 枚举类（ACTIVE=0, ARCHIVED=1, TRASHED=2, SOFT_DELETED=3）
• ✅ 明确 UUID v7 主键由应用层生成（app.utils.uuid.generate_uuid_v7()）
• ✅ 移除 permanently_deleted_at 字段（简化回收站机制）

2. 异步编程规范

修正前：

def __init__(self, db: Session):

修正后：

def __init__(self, db: AsyncSession):

• ✅ Service 层使用 AsyncSession 而非 Session
• ✅ 所有方法保持 async/await 模式

3. UUID 生成方式

修正前：

id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))

修正后：

from app.utils.uuid import generate_uuid_v7

id = Column(String, primary_key=True, default=generate_uuid_v7)

• ✅ 使用 UUID v7 替代 UUID v4
• ✅ 导入正确的工具函数

4. 时间戳处理

修正前：

from datetime import datetime

created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))

修正后：

from datetime import datetime, timezone

created_at = Column(DateTime, default=lambda: datetime.now(timezone.utc))

• ✅ 补充 timezone 导入
• ✅ 所有时间戳使用 TIMESTAMPTZ 存储 UTC 时间

5. API 响应格式统一

修正前（不符合统一响应格式）：

{
  "items": [...],
  "total": 100
}

修正后（符合统一响应格式）：

{
  "success": true,
  "data": {
    "items": [...],
    "total": 100
  }
}

• ✅ 所有成功响应包裹在 data 字段中
• ✅ 添加 success 字段标识请求状态
• ✅ 错误响应使用 error 字段（文档中已说明）

6. 枚举映射表位置调整

修正前：枚举映射表放在"数据库设计"章节

修正后：枚举映射表移至"数据模型"章节开头

• ✅ 枚举映射是应用层逻辑，应该在数据模型章节
• ✅ 便于开发者查找枚举定义

7. 外键约束说明

修正前：

owner_id = Column(String, ForeignKey('users.id'), nullable=False)
folder_id = Column(String, ForeignKey('folders.id'))

修正后：

owner_id = Column(String, nullable=False)
folder_id = Column(String)

# 关系（注意：数据库层不使用外键约束，仅应用层维护引用完整性）
# owner = relationship("User", back_populates="projects")
# folder = relationship("Folder", back_populates="projects")

• ✅ 移除 ForeignKey 声明
• ✅ 注释说明禁用物理外键的原因
• ✅ 关系定义注释掉，说明仅应用层维护

8. 回收站机制优化

修正前：

• 使用 deleted_at 和 permanently_deleted_at 两个字段
• 状态说明分散在多处

修正后：

• ✅ 移除 permanently_deleted_at 字段（简化设计）
• ✅ 统一使用 status 字段管理状态
• ✅ 补充完整的状态转换说明：
  • 0: active（活跃）
  • 1: archived（归档）
  • 2: trashed（回收站，30天后自动转为 soft_deleted）
  • 3: soft_deleted（软删除，用户不可见）

9. 设计说明完善

新增内容：

• ✅ 补充"禁用物理外键"说明（第16条）
• ✅ 补充"回收站机制"详细说明（第10条）
• ✅ 补充 access_count 字段说明（分享管理）

10. 索引优化

修正前：包含不必要的索引

修正后：

• ✅ 移除 idx_projects_budget（V1 阶段预算字段为 0，无需索引）
• ✅ 移除 idx_projects_planned_duration 和 idx_projects_actual_duration（查询频率低）
• ✅ 保留核心查询索引（owner、folder、status、时间、全文搜索）

---

技术栈符合性检查

✅ 完全符合

1. 数据库设计：

   • UUID v7 主键
   • SMALLINT 枚举类型
   • TIMESTAMPTZ 时间戳
   • 禁用物理外键
   • GIN 索引支持 JSONB 和全文搜索

2. 后端架构：

   • AsyncSession 异步数据库会话
   • 分层架构（Model → Repository → Service → API）
   • IntEnum 枚举映射
   • Pydantic Schema 验证

3. API 设计：

   • 统一响应格式（success + data/error）
   • RESTful 风格
   • 分页参数标准化

4. 代码规范：

   • 导入 datetime.timezone
   • 使用 generate_uuid_v7()
   • 注释完整清晰

⚠️ 待补充（实现阶段）

1. Repository 层实现：文档中 Service 层调用 ProjectRepository，但未提供实现代码
2. 错误处理：需要补充自定义异常如何转换为统一 API 响应格式
3. 依赖注入：需要说明 AsyncSession 如何通过依赖注入获取

---

影响评估

文档层面

• ✅ 文档完全符合技术栈规范
• ✅ 开发者可以直接参考文档实现代码
• ✅ 减少实现阶段的返工

实现层面

• ⚠️ 需要确保实际代码与文档保持一致
• ⚠️ 需要补充 Repository 层实现文档
• ⚠️ 需要补充错误处理中间件文档

---

后续行动

1. 立即执行：

   • Review 修正后的文档
   • 确认回收站机制是否符合产品需求

2. 实现阶段：

   • 补充 ProjectRepository 实现文档
   • 补充错误处理中间件文档
   • 补充依赖注入配置文档

3. 测试阶段：

   • 验证 UUID v7 生成
   • 验证枚举类型转换
   • 验证 API 响应格式

---

相关文档

• jointo-tech-stack skill
• 数据库设计规范
• API 设计规范
• 后端架构规范

---

修正完成时间：2026-01-29
修正人员：Kiro AI Assistant