# {模块名称} - 错误码文档

> **module**: {模块名}
> **doc_type**: ErrorCodes
> **status**: Draft / Review / Active
> **owner**: {负责人}
> **upstream_docs**: 07-api.md, 04-state-machine.md
> **last_verified**: YYYY-MM-DD

---

## 错误码格式

```
{MODULE}_{分类}_{序号}
```

- `{MODULE}`: 模块前缀（如 PERF、ASSET、ORG）
- `分类`: 业务域缩写（如 CYCLE、KPI、AUTH）
- `序号`: 三位数字递增

---

## 错误码清单

### {分类1}（如：周期管理）

| 错误码 | HTTP 状态 | 触发条件 | 错误消息 | 处理建议 |
|--------|----------|---------|---------|---------|
| {MODULE}_{CAT}_001 | 400 | {什么操作 + 什么条件下触发} | {面向用户的错误消息或 i18n key} | {客户端应如何处理} |
| {MODULE}_{CAT}_002 | 403 | {触发条件} | {错误消息} | {处理建议} |
| {MODULE}_{CAT}_003 | 409 | {触发条件} | {错误消息} | {处理建议} |

### {分类2}（如：KPI 管理）

| 错误码 | HTTP 状态 | 触发条件 | 错误消息 | 处理建议 |
|--------|----------|---------|---------|---------|
| {MODULE}_{CAT}_001 | 400 | {触发条件} | {错误消息} | {处理建议} |

---

## 错误响应格式

```json
{
  "success": false,
  "error": {
    "code": "{MODULE}_{CAT}_{SEQ}",
    "message": "<i18n.key 或可读消息>",
    "details": {}
  },
  "statusCode": 400,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "path": "/api/v1/{module}/{path}",
  "method": "POST"
}
```

---

> 错误码按业务域分组，每个分类对应一个表格。新增错误码时在对应分类末尾追加序号。`04-state-machine.md` 中"违反时错误"列引用本文档的错误码。