# {模块名称} - 状态机文档

> **module**: {模块名}
> **doc_type**: StateMachine
> **status**: Draft / Review / Active
> **owner**: {负责人}
> **upstream_docs**: 01-prd.md, 03-architecture.md
> **last_verified**: YYYY-MM-DD

---

## {N}. {对象名称}状态机（{EntityName}）

### 核心对象

| 字段 | 内容 |
|------|------|
| 对象类型 | {例如：绩效周期/审批工单/资产} |
| 状态字段 | `status` |
| 数据表 | `{table_name}` |

### 状态列表

| 状态代码 | 说明 | 业务终态 | 生命周期终态 |
|---------|------|---------|------------|
| {STATE} | {说明} | ✅ / ❌ | ✅ / ❌ |

> **业务终态**：不再允许任何业务修改（如 COMPLETED）。**生命周期终态**：不再允许任何操作（如 ARCHIVED）。两者可以不同。

> **废弃枚举值**（如有）：列出数据库中保留但不再使用的状态值，并标注硬规则——"新写入不得再产生该值，读取旧数据时仅做兼容映射"。

### 合法流转

| 当前状态 | 可流转到 | 触发动作 | 执行者 | 守卫条件 | 违反时错误 |
|---------|---------|---------|--------|---------|-----------|
| {STATE} | {STATE} | {动作} | {角色/系统} | {前置校验条件} | {HTTP状态码 错误码（说明）} |

> **守卫条件**：状态转换前必须满足的前置校验。AI agent 实现时必须将每个守卫条件转化为代码中的显式校验。
> **违反时错误**：引用 `08-error-codes.md` 中的定义。一个转换可能有多个守卫条件对应不同错误码，用 `/` 分隔。
> **系统触发**：部分转换由系统自动触发（如"周期推进时自动冻结评分"），在执行者列标注"系统"，区别于人工操作。

### 各阶段前端功能映射（如需）

> 当模块有多角色且各阶段可操作内容不同时，用此表格明确各角色在各状态下的可操作项。

| 阶段 | {角色1}可操作 | {角色2}可操作 | {角色3}可操作 |
|------|-------------|-------------|-------------|
| {STATE} | {操作列表} | {操作列表} | {操作列表} |

### 状态流转图

```mermaid
stateDiagram-v2
    [*] --> DRAFT: 创建
    DRAFT --> ACTIVE: 发布
```

---

> 一个模块可以有多个状态机，每个用独立的 `## {N}. {名称}` 章节描述。

---

## 状态机关系概览（如需）

> 当模块有多个状态机时，用 mermaid graph 展示它们之间的依赖关系。

---

## 设计原则

> 总结本模块状态机的共性规则。

- {如"单向流转为主，除驳回重新编辑外"}
- {如"人工触发：阶段流转由 HR 手动触发"}
- {如"终态分层：区分业务终态和生命周期终态"}

## 状态变更审计

所有状态变更需记录审计日志：变更前状态、变更后状态、变更时间、执行者、变更原因（如适用）。

---

## 异常路径

> 本节显式声明状态机中的异常场景。AI agent 不应假设"合理行为"，而应严格按此实现。

### 不合法的状态转换

| 尝试操作 | 当前状态 | 期望行为 |
|---------|---------|---------|
| {如"提交审批"} | {如"周期非 GOAL_SETTING"} | {如"返回 409 PERF_CYCLE_004"} |

### 超时与未响应

| 场景 | 超时时间 | 处理方式 |
|------|---------|---------|
| {场景描述} | {时间或"当前无自动超时"} | {处理方式} |

### 并发冲突

| 场景 | 处理方式 |
|------|---------|
| {场景描述} | {如"后提交者需基于最新状态校验，具体策略以实现为准"} |

> 异常路径数量按模块实际需要调整。关键原则：所有非正常路径都必须有显式的期望行为定义，不留给 AI agent 自行推断。