---
name: backend-api
when: '新建接口, API开发, 后端接口, REST API, 新增CRUD, 添加接口, 接口实现'
scope:
  - backend
products:
  - '*'
id: ka-artifact_template-backend-api
asset_kind: acceptance_template
lifecycle_status: active
owner_mechanism_id: mc-backend-implementation-contract
authority: supporting
routes:
  - '*'
primary_triggers:
  - 新建接口
  - API开发
  - 后端接口
  - REST API
  - 新增CRUD
  - 添加接口
  - 接口实现
priority: P2
specificity: 3
version: 1.1.0
last_reviewed: '2026-06-01'
consumes: []
emits:
  - acceptance_report
secondary_triggers: []
negative_triggers: []
type: acceptance_template
stages: ["联调验证"]
---

## 验收项
- [AC-01] Controller 层无业务逻辑（无 if/else 分支、计算、状态机） (check: grep -rn 'if\s*(.*>.*)\|if\s*(.*< .*)' {file} --include='*Controller.java')
- [AC-02] DTO 与 Entity 分离，请求/响应使用 DTO，不直接暴露 Entity (check: grep -c 'Entity\|@Table' {file} && grep -c 'class.*DTO\|class.*Request\|class.*Response' {file})
- [AC-03] 写操作 Service 方法有 @Transactional 注解 (check: grep -B2 'public.*save\|public.*update\|public.*delete\|public.*create' {file} | grep -c '@Transactional')
- [AC-04] 批量操作使用 batch SQL，无循环内逐条调用 (check: grep -A5 'for\s*(' {file} | grep -c 'mapper\.\|repository\.\|dao\.')
- [AC-05] 删除操作记录操作人和原因 (check: grep -A5 'delete\|remove' {file} | grep -c 'operator\|reason\|操作人')
- [AC-06] 所有异常经全局异常处理器返回，无散落 try-catch 吞异常 (check: grep -c 'catch\s*(.*Exception\s*\w*)\s*\{\s*\}' {file})
- [AC-07] 接口有 @Valid 或手动参数校验，不信任外部输入 (check: grep -c '@Valid\|@NotNull\|@NotBlank\|@Size\|validate' {file})
- [AC-08] 关键写操作有 INFO 级别审计日志（操作者/时间/对象） (check: grep -c 'log\.info\|auditLog\|操作日志' {file})
- [AC-09] 日志中无敏感信息（密码/token/身份证号） (check: grep -ic 'password\|token\|secret\|idcard\|身份证' {file})
- [AC-10] 权限检查注解到位（@PreAuthorize 或自定义鉴权） (check: grep -c '@PreAuthorize\|@RequiresPermissions\|checkPermission' {file})
- [AC-11] API 是否有版本号路径前缀（/api/v1/） (check: grep -c '@RequestMapping.*"/api/v[0-9]' {file})
- [AC-12] 写接口是否有幂等设计（幂等键或唯一约束） (check: grep -c 'Idempotent\|幂等\|idempotent' {file})
- [AC-13] 分页接口是否返回标准分页结构（total、list、pageNum、pageSize） (check: grep -c 'PageResult\|PageInfo\|PageResponse\|total.*list' {file})
- [AC-14] 是否有全局统一错误码体系 (check: grep -c 'ErrorCode\|BizCode\|ResultCode\|错误码' {file})
- [AC-15] 接口文档是否与实现同步（Swagger/OpenAPI 注解完整） (check: grep -c '@ApiOperation\|@Schema\|summary' {file})
- [AC-16] 是否有速率限制保护 (check: grep -c '@RateLimit\|RateLimiter\|限流\|rate' {file})
- [AC-17] 批量操作是否有数量上限（≤ 500 条） (check: grep -c '@Size.*max\|MAX_BATCH\|batchSize\|批量上限' {file})
