323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
> For AI assistants: Read this entire file before writing any code. All decisions here are final.
|
||
|
||
# Fonrey — 统一状态机规范 (STATE_MACHINE)
|
||
|
||
**定位**：本文档是 Fonrey 项目所有实体生命周期与状态流转的唯一权威定义。
|
||
**变更历史**：
|
||
|
||
| 日期 | 变更人 | 变更内容 |
|
||
|---|---|---|
|
||
| 2026-06-04 | Sisyphus | 初始版本：整合各模块状态机逻辑，对齐 ENUMS v2.2 |
|
||
|
||
---
|
||
|
||
## 1. 通用约定
|
||
|
||
- **状态值命名**：统一采用 `lower_snake_case`，必须与 `DATA_MODEL/ENUMS.md` 完全一致。
|
||
- **触发动作**：状态迁移必须由显式的动作（Action）或事件（Event）触发。
|
||
- **操作日志**：所有关键状态迁移（除系统内部中间态外）必须记录对应的 `status_log` 或 `audit_log` 表。
|
||
- **不可逆规则**：标注为“终态”的状态禁止迁回初始态或中间态。
|
||
- **权限要求**：状态迁移接口必须校验操作者的 DataScope 与 Function Permission。
|
||
|
||
---
|
||
|
||
## 2. 租户生命周期 (Public.Tenant)
|
||
|
||
**实体**: `public.tenants` | **字段**: `status`
|
||
**参考**: `DATA_MODEL_PUBLIC.md` §2.1, §4.1
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> creating
|
||
creating --> active: 初始化完成
|
||
creating --> failed: 初始化失败
|
||
active --> suspended: 逾期/违规/申请
|
||
suspended --> active: 恢复条件满足
|
||
active --> pending_delete: 申请注销
|
||
suspended --> pending_delete: 申请注销
|
||
pending_delete --> deleted: 30天后/人工确认
|
||
deleted --> [*]
|
||
```
|
||
|
||
### 状态枚举值
|
||
(domain: `public.tenant.status`)
|
||
- `creating`: 创建中
|
||
- `active`: 正常
|
||
- `suspended`: 已挂起
|
||
- `pending_delete`: 待删除
|
||
- `deleted`: 已删除
|
||
- `failed`: 创建/初始化失败
|
||
|
||
### 状态迁移表
|
||
|
||
| 当前状态 | 下一状态 | 触发动作/事件 | 触发角色 | 副作用 | 是否可逆 |
|
||
|---|---|---|---|---|---|
|
||
| `creating` | `active` | 租户 Schema 初始化成功 | System | 写 `tenant_status_logs` | 否 |
|
||
| `creating` | `failed` | 初始化脚本执行失败 | System | 记录错误日志 | 否 |
|
||
| `active` | `suspended` | 欠费/违规/License过期 | System/SuperAdmin | 设置 `suspended_until`, 写日志 | 是 |
|
||
| `suspended` | `active` | 缴费成功/解封/到期恢复 | System/SuperAdmin | 清除挂起原因 | 是 |
|
||
| `active`/`suspended` | `pending_delete` | 提交注销申请 | TenantAdmin | 设置 `deleted_at` | 是 |
|
||
| `pending_delete` | `deleted` | 确认注销/静默期结束 | SuperAdmin/System | 物理删除或深度标记 | 否 |
|
||
|
||
**来源章节**: `DATA_MODEL_PUBLIC.md` §4.1
|
||
|
||
---
|
||
|
||
## 3. 客源状态机 (Client)
|
||
|
||
**实体**: `client.clients` | **字段**: `status`
|
||
**参考**: `DATA_MODEL_CLIENT.md` §3.1, §4 | `ENUMS.md` §3.6
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> buying
|
||
[*] --> renting
|
||
[*] --> buy_or_rent
|
||
|
||
state "活跃态" as Active {
|
||
buying
|
||
renting
|
||
buy_or_rent
|
||
}
|
||
|
||
Active --> suspended: 暂时无需求
|
||
suspended --> Active: 重新激活
|
||
|
||
Active --> public: 手动转公/超时自动
|
||
suspended --> public: 手动转公
|
||
|
||
Active --> bought: 转成交(我购)
|
||
Active --> rented_done: 转成交(我租)
|
||
|
||
Active --> invalid: 转无效
|
||
suspended --> invalid: 转无效
|
||
|
||
invalid --> Active: 经理审批恢复
|
||
|
||
bought --> [*]
|
||
rented_done --> [*]
|
||
public --> [*]
|
||
```
|
||
|
||
### 状态枚举值
|
||
(domain: `client.status`)
|
||
- `buying`: 求购
|
||
- `renting`: 求租
|
||
- `buy_or_rent`: 租购
|
||
- `suspended`: 暂缓
|
||
- `bought`: 已购 (我购)
|
||
- `rented_done`: 已租 (我租)
|
||
- `public`: 公客
|
||
- `invalid`: 无效
|
||
|
||
### 状态迁移表
|
||
|
||
| 当前状态 | 下一状态 | 触发动作/事件 | 触发角色 | 副作用 | 是否可逆 |
|
||
|---|---|---|---|---|---|
|
||
| `buying`/`renting`/`buy_or_rent` | `suspended` | 修改状态为暂缓 | 经纪人 | 写 `client_status_logs` | 是 |
|
||
| `suspended` | `buying`/`renting`/`buy_or_rent` | 重新激活需求 | 经纪人 | 更新 `last_active_at` | 是 |
|
||
| `Active`/`suspended` | `public` | 手动转公/超时自动转公 | 经纪人/System | 修改 `client_type='public'` | 否 |
|
||
| `Active` | `bought`/`rented_done` | 录入成交合同 | 经纪人 | 修改 `client_type='transacted'` | 否 |
|
||
| `Active`/`suspended` | `invalid` | 标记无效 | 经纪人 | 记录 `invalid_reason` | 需审批 |
|
||
|
||
### 禁迁规则
|
||
- `transacted` (bought/rented_done) 状态为绝对终态，禁止迁往任何其他状态。
|
||
- `public` 状态客源禁止直接修改为 `private` 状态下的需求状态，必须走领用流程。
|
||
|
||
**来源章节**: `DATA_MODEL_CLIENT.md` §4, `ENUMS.md` §3.6
|
||
|
||
---
|
||
|
||
## 4. 房源状态机 (Property)
|
||
|
||
**实体**: `property.properties` | **字段**: `status`
|
||
**参考**: `DATA_MODEL_PROPERTY.md` §3, §4.1
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> unlisted
|
||
unlisted --> for_sale: 挂牌出售
|
||
unlisted --> for_rent: 挂牌出租
|
||
|
||
state "在盘态" as Listed {
|
||
for_sale
|
||
for_rent
|
||
for_sale_rent
|
||
}
|
||
|
||
Listed --> suspended: 业主暂缓
|
||
suspended --> Listed: 重新上架
|
||
|
||
Listed --> sold: 本司成交
|
||
Listed --> sold_elsewhere: 他售
|
||
Listed --> rented_elsewhere: 他租
|
||
|
||
Listed --> unlisted: 下架
|
||
|
||
sold --> [*]
|
||
sold_elsewhere --> [*]
|
||
```
|
||
|
||
### 状态枚举值
|
||
(domain: `property.status`)
|
||
- `for_sale`: 出售
|
||
- `for_rent`: 出租
|
||
- `for_sale_rent`: 租售
|
||
- `suspended`: 暂缓
|
||
- `sold_elsewhere`: 他售
|
||
- `rented_elsewhere`: 他租
|
||
- `sold`: 成交
|
||
- `unlisted`: 未挂牌
|
||
|
||
### 状态迁移表
|
||
|
||
| 当前状态 | 下一状态 | 触发动作/事件 | 触发角色 | 副作用 | 是否可逆 |
|
||
|---|---|---|---|---|---|
|
||
| `unlisted` | `for_sale`/`for_rent` | 房源挂牌 | 经纪人 | 新增 `listing_histories` | 是 |
|
||
| `Listed` | `suspended` | 业主通知暂缓 | 经纪人 | 写跟进日志 | 是 |
|
||
| `Listed` | `sold` | 本司录入成交 | 经纪人 | 自动结束挂牌历史 | 否 |
|
||
| `Listed` | `sold_elsewhere`/`rented_elsewhere` | 核实他司已成交 | 经纪人 | | 否 |
|
||
| `Listed` | `unlisted` | 强制下架 | 管理员 | | 是 |
|
||
|
||
**来源章节**: `DATA_MODEL_PROPERTY.md` §3
|
||
|
||
---
|
||
|
||
## 5. 客户/房源等级 (Grade)
|
||
|
||
**实体**: `client.clients` / `property.properties` | **字段**: `grade`
|
||
**参考**: `DATA_MODEL_CLIENT.md` §3.1 | `DATA_MODEL_PROPERTY.md` §4.1
|
||
|
||
### 状态枚举值
|
||
(domain: `client.grade` / `property.grade`)
|
||
- `A`: A (急迫)
|
||
- `B`: B (较强)
|
||
- `C`: C (一般)
|
||
- `D`: D (较弱)
|
||
- `E`: E (暂不关注) - 仅客源
|
||
|
||
### 状态迁移表
|
||
|
||
| 当前状态 | 下一状态 | 触发动作/事件 | 触发角色 | 副作用 | 是否可逆 |
|
||
| ---- | ------------------- | ------- | ---- | ----------------------------- | ---- |
|
||
| 任意状态 | `A`/`B`/`C`/`D`/`E` | 手动调整等级 | 经纪人 | 写 `status_log` / `follow_log` | 是 |
|
||
|
||
**来源章节**: `DATA_MODEL_CLIENT.md` §4, `DATA_MODEL_PROPERTY.md` §3
|
||
|
||
---
|
||
|
||
## 6. 账号状态机 (Account)
|
||
|
||
**实体**: `login.user_accounts` | **字段**: `status`
|
||
**参考**: `DATA_MODEL_LOGIN.md` §5.1
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> active: 创建(初始密码)
|
||
active --> locked: 密码错误≥5次
|
||
locked --> active: 30min到期/手动解锁
|
||
active --> disabled: 离职/手动停用
|
||
disabled --> active: 复职/手动恢复
|
||
```
|
||
|
||
### 状态枚举值
|
||
(domain: `login.user_account.status`)
|
||
- `active`: 启用
|
||
- `disabled`: 停用
|
||
- `locked`: 锁定
|
||
|
||
### 状态迁移表
|
||
|
||
| 当前状态 | 下一状态 | 触发动作/事件 | 触发角色 | 副作用 | 是否可逆 |
|
||
|---|---|---|---|---|---|
|
||
| `active` | `locked` | 密码连续错误5次 | System | 设置 `locked_until` | 是 |
|
||
| `locked` | `active` | 时间到期/管理员解锁 | System/Admin | | 是 |
|
||
| `active` | `disabled` | 员工离职/手动停用 | Admin/System | 踢出所有 Session | 是 |
|
||
|
||
**来源章节**: `DATA_MODEL_LOGIN.md` §5.1
|
||
|
||
---
|
||
|
||
## 7. 升级事件状态机 (Upgrade Event)
|
||
|
||
**实体**: `public.upgrade_events` | **字段**: `status`
|
||
**参考**: `DATA_MODEL_PUBLIC.md` §4.2
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> draft
|
||
draft --> pre_check: 提交
|
||
pre_check --> pre_backup: 健康检查通过
|
||
pre_backup --> batch_running: 备份完成
|
||
batch_running --> batch_done: 批次租户成功
|
||
batch_done --> batch_running: 下一批次
|
||
batch_done --> succeeded: 全部完成
|
||
|
||
batch_running --> halted: 失败/门控拦截
|
||
halted --> batch_running: 人工继续
|
||
halted --> rollback_running: 人工回滚
|
||
rollback_running --> rolled_back: 回滚完成
|
||
|
||
batch_running --> failed: 严重故障
|
||
```
|
||
|
||
### 状态枚举值
|
||
(domain: `public.upgrade_event.status`)
|
||
- `draft`: 草稿
|
||
- `pre_check`: 预检查
|
||
- `pre_backup`: 预备份
|
||
- `batch_running`: 批次执行中
|
||
- `batch_done`: 批次完成
|
||
- `halted`: 已暂停
|
||
- `succeeded`: 已成功
|
||
- `failed`: 失败
|
||
- `rollback_running`: 回滚中
|
||
- `rolled_back`: 已回滚
|
||
|
||
**来源章节**: `DATA_MODEL_PUBLIC.md` §4.2
|
||
|
||
---
|
||
|
||
## 8. 其他辅助状态
|
||
|
||
### 8.1 备份/导出任务 (Backup/Export)
|
||
**字段**: `status` | **参考**: `ENUMS.md` §2.3
|
||
- `pending` -> `in_progress` -> `success` / `failed`
|
||
|
||
### 8.2 客户端发布 (Client Release)
|
||
**字段**: `status` | **参考**: `ENUMS.md` §2.4
|
||
- `draft` -> `published` -> `archived`
|
||
- **约束**: 同平台架构下仅允许一个 `published`。
|
||
|
||
### 8.3 员工状态 (Staff)
|
||
**字段**: `status` | **参考**: `DATA_MODEL_ORG.md` §4
|
||
- `probation` -> `active` -> `resigned`
|
||
- `active` <-> `frozen`
|
||
|
||
### 8.4 审批流 (Approval)
|
||
**实体**: `number_holder_approvals` | **字段**: `status`
|
||
- `pending` -> `approved` / `rejected`
|
||
|
||
---
|
||
|
||
## X. 状态机一致性校验清单
|
||
|
||
1. **枚举同步**: 状态字段值是否在 `ENUMS.md` 中定义且拼写一致？
|
||
2. **日志完备**: 每次 `status` 变更是否伴随对应的 `status_log` 插入动作？
|
||
3. **并发控制**: 状态变更是否包含 `version` 乐观锁检查？
|
||
4. **终态拦截**: 业务逻辑是否显式禁止从终态（如 `sold`, `deleted`, `rolled_back`）向外迁移？
|
||
5. **副作用触发**: 状态变更相关的异步任务（如转公客通知、缓存清理）是否已在 Service 层注册？
|
||
|
||
---
|
||
|
||
## 待澄清问题
|
||
|
||
1. **Client Invalid 恢复路径**: `DATA_MODEL_CLIENT.md` §4 提到“需经理审批后可恢复”，但未定义恢复后的目标状态（是恢复到 `suspended` 还是之前的活跃态？）。
|
||
- *涉及文件*: `DATA_MODEL_CLIENT.md`
|
||
2. **Property Unlisted 属性**: 房源在 `unlisted` 状态下，其 `attribute` (公/私盘) 是否有意义？若从 `private` 挂牌变为 `unlisted`，再次挂牌时是否应默认保留 `private` 属性？
|
||
- *涉及文件*: `DATA_MODEL_PROPERTY.md`
|
||
3. **Tenant Deleted 物理性**: `DATA_MODEL_PUBLIC.md` §4.1 提到“硬删除直接到 deleted”，但在 §2.1 又说“硬删除直接物理删除行”。需要明确 `deleted` 状态是代表软删除的终点还是物理删除前的标记。
|
||
- *涉及文件*: `DATA_MODEL_PUBLIC.md`
|
||
4. **Staff Resigned 恢复**: 离职员工复职（`rejoin`）后，其 `status` 是回到 `probation` 还是 `active`？
|
||
- *涉及文件*: `DATA_MODEL_ORG.md`
|