---
name: backend-dev
description: |
  This skill should be used when the user asks to "build a backend API", "design a database schema",
  "implement authentication", "create a REST endpoint", "develop a microservice", "set up server-side logic",
  "write API routes", "design system architecture", "implement business logic", "connect to database",
  "set up middleware", "configure ORM", "write server tests", "deploy backend service",
  or discusses backend-related tasks including API design, database design, authentication/authorization,
  server architecture, middleware, error handling, logging, performance optimization, or backend testing.
  Also triggered by technology-specific requests mentioning "Express", "FastAPI", "Spring Boot", "Django",
  "Rails", "Gin", "Fiber", "NestJS", "GraphQL", "gRPC", "WebSocket", "PostgreSQL", "MongoDB", "Redis",
  "JWT", "OAuth", "OpenAPI", "Swagger", "Docker compose backend", or "CI/CD pipeline".

  【中文触发场景】
  - "写后端接口"、"开发API"、"设计数据库"、"实现登录"
  - "搭建后端服务"、"写服务器代码"、"实现业务逻辑"
  - "数据库设计"、"表结构设计"、"API文档"
  - "后端架构设计"、"微服务拆分"、"接口规范"
  - "权限系统"、"中间件"、"错误处理"、"日志"
  - "后端测试"、"单元测试"、"集成测试"
  - "部署后端"、"Docker化"、"CI/CD配置"
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, TaskCreate, TaskUpdate, TaskList
---

# Backend Development Professional Workflow

> 专业后端开发工作流 —— 从需求到部署，结构化、可追溯、可审查。

## 核心原则

1. **防御性编程** —— 所有外部输入不可信，边界条件显式处理
2. **关注点分离** —— 分层架构（Handler → Service → Repository），每层只做一件事
3. **显式优于隐式** —— 依赖注入、配置外部化、错误显式传播
4. **渐进式交付** —— 先可运行，再优化；先核心路径，再边缘场景

## 工作流总览

```
Phase 0: 需求澄清与约束定义  ──→  明确边界、性能目标、部署环境
    ↓
Phase 1: 架构设计             ──→  分层/模块/数据流/技术选型 & 决策记录
    ↓
Phase 2: 核心实现（增量）      ──→  Repository → Service → Handler 由内向外
    ↓
Phase 3: 安全加固             ──→  认证/授权/输入校验/注入防护/速率限制
    ↓
Phase 4: 测试覆盖             ──→  单元 → 集成 → 契约测试（含边界与异常）
    ↓
Phase 5: 审查与改进           ──→  自审查清单 → 性能评估 → 文档收尾
```

每个阶段的 prompt 模板在 `prompts/` 目录中，按需引用。

## 阶段详细说明

### Phase 0: 需求澄清与约束定义

执行 `prompts/phase0-clarify.md` 中的提问框架，收齐以下信息：

| 维度 | 必须明确的点 |
|------|-------------|
| 上下文 | 业务场景、用户群体、预期流量 (QPS) |
| 技术栈 | 语言/框架/数据库/运行时版本 |
| 约束 | 部署方式（容器/Serverless/VM）、团队规模、时间线 |
| 接口风格 | REST / GraphQL / gRPC / WebSocket / 混合 |
| 数据要求 | 一致性级别、数据量级、是否需要事务 |
| 非功能要求 | P99延时、可用性 SLA、审计合规 |

输出文件：`.backend-dev/phase0-requirements.json`

### Phase 1: 架构设计

执行 `prompts/phase1-arch.md`，输出以下工件：

- **分层架构图** —— Handler / Service / Repository / 中间件栈
- **模块划分** —— 每个模块的职责、边界、依赖方向
- **数据模型** —— 核心 Entity 定义、表关系（ER）、索引策略
- **接口契约草案** —— 端点路径、请求/响应结构、状态码
- **技术选型决策记录 (ADR)** —— 每次选型附理由和替代方案
- **风险与缓解** —— 识别数据热点、单点瓶颈、降级策略

输出文件：`.backend-dev/phase1-architecture.json`

### Phase 2: 核心实现

按 **Repository → Service → Handler** 由内向外顺序，逐层实现：

```
Request  →  [Middleware]  →  Handler  →  Service  →  Repository  →  DB
                                            │
                                            ↓
                                        外部服务 / 缓存 / 消息队列
```

每条实现遵循：
1. **先定义接口（interface/trait/type），再实现**
2. **显式错误类型** —— 定义领域错误码，不在运行时拼字符串
3. **完备的日志** —— 每个外部调用的入口和出口都记录结构化日志
4. **幂等性考虑** —— 写操作的幂等键（idempotency key）设计

### Phase 3: 安全加固

执行 `prompts/phase3-security.md` 中的安全检查清单，逐项验证：

- 认证策略（JWT / Session / OAuth / API Key）
- 授权模型（RBAC / ABAC / ACL）
- 输入校验（结构化校验库 + 白名单策略）
- 注入防护（参数化查询 / ORM / 输出编码）
- 速率限制与防滥用
- 敏感数据（加密存储、响应脱敏、日志脱敏）
- CORS / CSP / HTTPS 强制

### Phase 4: 测试覆盖

执行 `prompts/phase4-testing.md`，按金字塔模型覆盖：

```
        ╱╲              手动探索测试
       ╱  ╲             E2E 测试 (关键用户路径)
      ╱    ╲            集成测试 (模块间契约)
     ╱______╲           单元测试 (核心逻辑 + 边界)
```

每条测试准则：
- 每个 Repository 方法对应一个集成测试
- 每个 Service 公共方法对应单元测试（mock 依赖层）
- 每条 Handler 路径（成功/鉴权失败/参数错误/404）各一个测试
- 错误路径优先级 ≥ 成功路径

### Phase 5: 审查与改进

执行 `prompts/phase5-review.md`，逐项审查：

1. **正确性审查** —— 并发竞态、事务边界、状态机状态遗漏
2. **性能审查** —— N+1 查询、缺少索引、未使用连接池、未分页
3. **可观测性** —— 结构化日志、指标埋点、健康检查端点、追踪上下文传播
4. **文档补全** —— API 文档 (OpenAPI)、README 运行说明、环境变量清单

## 交叉引用清单

- **`references/api-design.md`** —— REST / GraphQL / gRPC 设计规范与对比
- **`references/db-best-practices.md`** —— 表设计、索引策略、迁移、连接池
- **`references/error-handling.md`** —— 错误类型体系、结构化错误响应、全局异常处理
- **`references/security-baseline.md`** —— 安全基线检查表（OWASP Top 10 映射）
- **`references/struct-export.md`** —— 阶段间结构化数据传递格式定义

## 输出规范

所有中间产出统一存放于 `.backend-dev/` 目录，按阶段命名：

```
.backend-dev/
├── phase0-requirements.json    # 需求与约束
├── phase1-architecture.json    # 架构设计方案
├── phase2-impl-record.md       # 实现过程记录
├── phase3-security-report.md   # 安全审查报告
├── phase4-test-report.md       # 测试覆盖报告
├── phase5-review-report.md     # 最终审查报告
└── adr/                        # 架构决策记录（每项决策一个 markdown）
    ├── 001-use-postgresql.md
    └── 002-adopt-repository-pattern.md
```

## 注意事项

1. **增量交付** —— 不要一次性生成所有代码。每次围绕一个功能点的完整分层实现（Handler → Service → Repository），提交后继续下一个
2. **不重复造轮子** —— 优先使用框架内建机制和社区稳定库，仅在确有必要时自定义
3. **兼容性优先** —— 接口变更时保持向后兼容（字段添加不删除、可选参数扩展）
4. **不假设运行环境** —— 所有路径引用使用相对路径，配置使用环境变量 + 默认值