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

> **变更日期**：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. 异步编程规范

**修正前**：
```python
def __init__(self, db: Session):
```

**修正后**：
```python
def __init__(self, db: AsyncSession):
```

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

### 3. UUID 生成方式

**修正前**：
```python
id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
```

**修正后**：
```python
from app.utils.uuid import generate_uuid_v7

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

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

### 4. 时间戳处理

**修正前**：
```python
from datetime import datetime

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

**修正后**：
```python
from datetime import datetime, timezone

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

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

### 5. API 响应格式统一

**修正前**（不符合统一响应格式）：
```json
{
  "items": [...],
  "total": 100
}
```

**修正后**（符合统一响应格式）：
```json
{
  "success": true,
  "data": {
    "items": [...],
    "total": 100
  }
}
```

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

### 6. 枚举映射表位置调整

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

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

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

### 7. 外键约束说明

**修正前**：
```python
owner_id = Column(String, ForeignKey('users.id'), nullable=False)
folder_id = Column(String, ForeignKey('folders.id'))
```

**修正后**：
```python
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](/.claude/skills/jointo-tech-stack/SKILL.md)
- [数据库设计规范](/.claude/skills/jointo-tech-stack/references/database.md)
- [API 设计规范](/.claude/skills/jointo-tech-stack/references/api-design.md)
- [后端架构规范](/.claude/skills/jointo-tech-stack/references/backend.md)

---

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