# 后端规范（入口）

> **目标**: 统一后端 API、分层、错误处理与安全规范  
> **最后更新**: 2026-03-13

---

## ✅ 入口与执行

- 后端功能开发：`backend-main`
- 数据库与迁移：`database-main`
- 测试策略与用例：[测试规范入口](../../test-backend/references/testing-standards.md)

---

## 核心规则（摘要）

### 文档与契约
- 修改后端功能前，先读对应模块的 `01-prd.md`、`06-data-model.md`、`07-api.md`，如存在再读 `04-state-machine.md`。
- 未经确认，不得擅自变更路径、字段名、语义、错误码等外部契约。
- 文档与实现冲突时，必须停止并等待确认。

### 分层约束
- Controller 只处理 HTTP 请求与参数映射，不承载业务逻辑。
- Service 承载业务逻辑与编排。
- Repository 只负责持久化访问。
- 不要在 Controller 中直接写业务规则。

### 实现检查清单
- 输入校验
- 认证与授权判断
- 错误映射
- 幂等性（如适用）
- 与数据模型、状态机、API 契约保持一致

### 错误与安全
- 优先返回稳定的机器可读 `code`，不要直接把临时文案当契约。
- 涉及权限、鉴权、外部副作用、事务边界的改动，必须明确验证方式。

### 权限与角色
- 新增后端模块时，必须同步更新 `prisma/seeds/roles.seed.ts`，为 Employee/Leader/DepartmentManager 角色分配对应的查看权限。
- 权限码必须与 `constants/permissions.ts` 中定义的完全一致，不能自己编（如 `cycle:view` 不是 `cycle:read`）。
- 新增权限后必须运行 `npx ts-node prisma/seeds/iam-seed.ts` 更新数据库。
- 状态转换、计算等自动逻辑，不要依赖用户手动调 API——应在状态流转中自动触发（如 `startConfirming` 自动计算绩效结果）。

### API 响应格式与前后端对接
- **状态转换类 API 必须返回完整资源对象**，不得只返回 `{ id, status }`。前端通常用返回值直接替换本地状态，字段缺失会导致 UI 数据丢失。
- **列表 API 统一返回 `{ items: [...] }` 或直接返回数组**，同一模块内不得混用。新增端点前先确认前端 TypeScript 接口期望的字段名和嵌套结构。
- **字段命名必须与前端接口定义一致**。后端返回 `organizationId` 而前端期望 `id` 这类不一致会导致前端静默过滤掉所有数据。
- **空数据场景**：列表/概览类 API 在无数据时返回空数组或零值结构（如 `{ items: [], total: 0 }`），不得抛异常。单资源查询找不到时抛 404 是正确的。
- 新增或修改 API 后，必须用 curl 验证返回的 JSON 字段名和结构，与前端 `services/api/*.ts` 中的类型定义交叉检查。

## 参考入口

- [后端架构](docs/standards/02-backend-architecture.md)
- [数据库规范](../../database-main/references/database-standards.md)
- [测试规范](../../test-backend/references/testing-standards.md)
- `.agents/skills/backend-main/SKILL.md`

---

**维护者**: FFOA 后端团队  
**最后更新**: 2026-03-13