docs/v1.0/architecture/changelogs/2026-02-04-jointo-tech-stack-skill-architecture-update.md

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）

关键规范：

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 响应）

关键规范：

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、包含业务逻辑、不使用依赖注入）

关键规范：

@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

关键规范：

@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 的描述中添加了对新增内容的引用：

### [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 类，确保正确管理事务
• 更新所有测试文件，遵循新的测试规范

文档更新

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

团队培训

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

参考文档

• ADR 010: Repository 与 Service 层事务管理职责划分
• 后端架构规范指南
• Changelog: Project Repository 事务管理架构修复

变更历史

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