# Jointo Tech Stack Skill 架构规范更新

**日期**: 2026-02-04  
**类型**: Skill 更新  
**影响范围**: 后端开发规范

---

## 概述

将 ADR 010 和后端架构规范指南的内容整合到 `jointo-tech-stack` skill 中，确保开发人员在编写代码时能够遵循正确的架构模式。

## 变更内容

### 1. 更新 `backend.md`

#### 1.1 补充分层架构概览

在"仓储模式"章节开头添加了三层架构概览：

```
┌─────────────────────────────────────┐
│         API Layer (FastAPI)         │  ← 接口层：请求验证、响应格式化
├─────────────────────────────────────┤
│       Service Layer (Business)      │  ← 业务层：事务管理、业务逻辑
├─────────────────────────────────────┤
│    Repository Layer (Data Access)   │  ← 数据层：数据访问、查询构建
└─────────────────────────────────────┘
```

**核心原则**（参考 ADR 010）：
- Repository 层：只负责数据访问，使用 `flush()`，不调用 `commit()`
- Service 层：负责事务管理，调用 `commit()` 和 `rollback()`
- API 层：负责请求验证、依赖注入、响应格式化

#### 1.2 重写 Repository 层规范

**新增内容**：
- Repository 层职责清单（应该做什么 ✅ / 不应该做什么 ❌）
- 完整的 Repository 标准模板（包含 CRUD 和查询方法）
- 常见错误示例（调用 commit、包含业务逻辑、调用其他 Repository）

**关键规范**：
```python
async def create(self, project: Project) -> Project:
    """创建项目"""
    self.session.add(project)
    await self.session.flush()  # ✅ 仅 flush，不 commit
    return project
```

#### 1.3 重写 Service 层规范

**新增内容**：
- Service 层职责清单（应该做什么 ✅ / 不应该做什么 ❌）
- 完整的 Service 标准模板（包含事务管理、业务逻辑编排）
- 常见错误示例（不管理事务、直接构建 SQL、处理 HTTP 响应）

**关键规范**：
```python
async def create_project(self, data: ProjectCreate, user_id: str) -> Project:
    """创建项目"""
    try:
        # 1. 业务验证
        # 2. 创建数据
        # 3. 记录日志
        
        # 4. ✅ 提交事务
        await self.session.commit()
        
        return created
    except Exception as e:
        await self.session.rollback()
        raise
```

#### 1.4 补充 API 层规范

**新增内容**：
- API 层职责清单（应该做什么 ✅ / 不应该做什么 ❌）
- 完整的 API 标准模板（包含依赖注入、异常处理）
- 常见错误示例（直接调用 Repository、包含业务逻辑、不使用依赖注入）

**关键规范**：
```python
@router.post("", response_model=ProjectResponse)
async def create_project(
    data: ProjectCreate,  # ✅ Pydantic 自动验证
    current_user: User = Depends(get_current_user),
    service: ProjectService = Depends(get_project_service)
):
    """创建项目"""
    try:
        project = await service.create_project(data, str(current_user.id))
        return project
    except DuplicateError as e:
        raise HTTPException(status_code=400, detail=str(e))
```

#### 1.5 新增测试规范章节

**新增内容**：
- 测试策略（测试金字塔）
- Repository 单元测试规范和示例
- Service 单元测试规范和示例
- API 集成测试规范和示例
- 测试配置（conftest.py）
- 运行测试命令
- 测试最佳实践
- Code Review Checklist

**关键规范**：
```python
@pytest.mark.asyncio
class TestProjectRepository:
    async def test_create_project(self, db_session):
        """测试创建项目"""
        repo = ProjectRepository(db_session)
        
        # ✅ 在测试方法内创建数据
        project = Project(...)
        created = await repo.create(project)
        
        assert created.id is not None
        # ✅ 不需要手动 commit，conftest 会自动回滚
```

### 2. 更新 `SKILL.md`

在 `backend.md` 的描述中添加了对新增内容的引用：

```markdown
### [backend.md](references/backend.md)
后端完整规范，包括：
- 项目结构和分层架构（Repository/Service/API 三层职责划分）
- 异步编程规范
- 依赖注入模式
- 错误处理规范
- 日志和监控
- **事务管理规范**（Repository 使用 flush，Service 使用 commit）
- **测试规范**（Repository/Service/API 单元测试和集成测试）
```

### 3. 同步更新多个 skill 目录

项目中存在多个 skill 目录，已同步更新：
- ✅ `.claude/skills/jointo-tech-stack/` - Claude Desktop 使用
- ✅ `.trae/skills/jointo-tech-stack/` - Trae AI 使用

确保所有 AI 助手都能获取到最新的架构规范。

## 变更原因

### 问题背景

在实施 Project Repository 单元测试时，发现了严重的架构设计问题：

1. **Repository 层错误地管理事务**：调用 `commit()` 违反单一职责原则
2. **测试事务冲突**：fixture 中创建数据导致与 conftest 的事务管理冲突
3. **职责不清晰**：Repository、Service、API 层的事务管理职责不明确

### 解决方案

创建了 ADR 010 和后端架构规范指南，明确了三层架构的职责划分。为了确保开发人员在编写代码时能够遵循正确的模式，需要将这些规范整合到 `jointo-tech-stack` skill 中。

## 影响范围

### 开发人员

- ✅ 在编写 Repository 代码时，会看到明确的职责清单和标准模板
- ✅ 在编写 Service 代码时，会看到完整的事务管理示例
- ✅ 在编写测试代码时，会看到正确的测试模式
- ✅ 在 Code Review 时，可以参考 Checklist 检查代码质量

### 现有代码

- ⚠️ 需要检查现有的 Repository 代码，确保没有调用 `commit()`
- ⚠️ 需要检查现有的 Service 代码，确保正确管理事务
- ⚠️ 需要更新现有的测试代码，遵循新的测试规范

## 后续工作

### 代码审查

- [ ] 检查所有 Repository 类，确保没有调用 `commit()`
- [ ] 检查所有 Service 类，确保正确管理事务
- [ ] 更新所有测试文件，遵循新的测试规范

### 文档更新

- [x] 创建 ADR 010（已完成）
- [x] 创建后端架构规范指南（已完成）
- [x] 更新 jointo-tech-stack skill（已完成）
- [ ] 更新团队开发文档

### 团队培训

- [ ] 团队分享会：讲解三层架构职责划分
- [ ] Code Review 培训：使用 Checklist 检查代码
- [ ] 测试培训：讲解正确的测试模式

## 参考文档

- [ADR 010: Repository 与 Service 层事务管理职责划分](../adrs/010-repository-service-transaction-management.md)
- [后端架构规范指南](../../server/guides/backend-architecture.md)
- [Changelog: Project Repository 事务管理架构修复](../../server/changelogs/2026-02-04-project-repository-transaction-management-fix.md)

## 变更历史

- 2026-02-04: 初始版本，整合 ADR 010 和架构规范指南到 skill