nexus/Project/fonrey/DATA_MODEL/ENUMS.md

For AI assistants: Read this entire file before writing any code. All decisions here are final. Do not suggest alternatives unless asked.

Fonrey — 统一枚举字典（ENUMS）

定位：本文件是 Fonrey 全局枚举标准（Public + Tenant）的统一实现基线。
版本：v2.2
日期：2026-04-28
适用范围：DATA_MODEL_PUBLIC.md、DATA_MODEL_LOGIN.md、DATA_MODEL_ORG.md、DATA_MODEL_COMPLEX.md、DATA_MODEL_PROPERTY.md、DATA_MODEL_CLIENT.md、DATA_MODEL_PERMISSION.md、DATA_MODEL_SETTING.md

⚠️ 枚举值命名规范：所有枚举值统一使用 lower_snake_case（全小写+下划线）。
历史遗留大写值（SUCCESS/FAILED、BOOLEAN/SCOPE/INTEGER、REPLACE/RESTRICT/GRANT、A_urgent/A_app/B_schema/C_feature）在 v2.2 中已统一迁移为小写。
DB CHECK 约束、enum_labels 种子数据、前端代码须同步更新为新值；迁移脚本须包含历史数据 UPDATE。

---

一、枚举分层标准（必须遵守）

Fonrey 采用两层枚举体系：

1. 固定枚举（Fixed Enum）

   • 值域固定，受 CHECK 或强业务约束保护
   • 作为系统契约，不能随意改值
   • 可落地到 public.enum_labels（用于统一标签）

2. 可配置枚举（Configurable Enum）

   • 值域由租户自行维护
   • 存储在 Tenant Schema：lookup_groups + lookup_items
   • 禁止对业务表字段加固定 CHECK IN (...)

---

二、全局固定枚举（Public / 平台级）

2.1 tenant 生命周期

domain: public.tenant.plan

• basic：基础版
• professional：专业版
• enterprise：企业版

domain: public.tenant.status

• creating：创建中
• active：正常
• suspended：已挂起
• pending_delete：待删除
• deleted：已删除
• failed：创建/初始化失败

domain: public.tenant.suspended_reason

• overdue：欠费
• violation：违规
• requested：客户申请
• other：其他

2.2 平台管理员

domain: public.platform_admin.role

• super_admin：超级管理员
• ops_operator：运营管理员
• read_only_auditor：只读审计员

2.3 平台审计与备份导出

domain: public.platform_audit.result

• success：成功
• failed：失败

domain: public.backup_schedule.frequency

• hourly：每小时
• daily：每日
• weekly：每周

domain: public.backup_schedule.storage_target

• local：本地存储
• s3：Amazon S3
• r2：Cloudflare R2
• gcs：Google Cloud Storage

domain: public.backup_record.trigger_type

• auto：自动触发
• manual：手动触发
• pre_upgrade：升级前触发
• pre_restore：恢复前触发

domain: public.backup_record.status

• pending：待执行
• in_progress：执行中
• success：成功
• failed：失败

domain: public.export_task.format

• csv：CSV
• json：JSON
• sql_dump：SQL 导出

domain: public.export_task.status

• pending：待执行
• in_progress：执行中
• success：成功（语义等价原 done，与 backup_record.status 对齐）
• failed：失败

2.4 升级与发布（Public）

domain: public.upgrade_event.event_type

• upgrade：升级
• rollback：回滚

domain: public.upgrade_event.upgrade_type

• app：A类-应用升级（原 A_app）
• schema：B类-数据库结构升级（原 B_schema）
• feature：C类-功能开关升级（原 C_feature）

domain: public.upgrade_event.strategy

• full：全量发布
• canary：灰度发布

domain: public.upgrade_event.status

• draft：草稿
• pre_check：预检查
• pre_backup：预备份
• batch_running：批次执行中
• batch_done：批次完成
• halted：已暂停
• succeeded：已成功
• failed：失败
• rollback_running：回滚中
• rolled_back：已回滚

domain: public.upgrade_event.failure_policy

• halt_batch：失败即停止批次
• continue：失败继续

domain: public.client_release.platform

• win32：Windows 客户端

domain: public.client_release.arch

• x64：x64 架构
• arm64：ARM64 架构

domain: public.client_release.release_type

• normal：普通更新
• force：强制更新

domain: public.client_release.status

• draft：草稿
• published：已发布
• archived：已归档

---

三、Tenant 固定枚举（模块级，值域统一）

说明：以下字段在 Tenant Schema 中存储，但值域为系统统一标准，属于“全局实现标准”。

3.1 登录认证（account/login）

domain: login.user_account.status

• active：启用
• disabled：停用
• locked：锁定

domain: login.login_attempt.failure_reason

• wrong_password：用户名或密码错误
• wrong_captcha：验证码错误
• account_locked：账号锁定
• account_disabled：账号停用
• tenant_not_found：租户不存在

---

3.2 组织人事（org）

domain: org.org_unit.type

• company：公司
• division：事业部
• region：大区
• area：区域
• district：片区
• store：门店
• group：店组
• functional：职能部门

domain: org.org_unit.attribute

• direct：直营
• franchise：加盟

domain: org.staff.role

• agent：经纪人
• store_manager：店长
• area_manager：区域经理
• admin：系统管理员
• operator：运营/行政
• system：系统账号

domain: org.staff.status

• active：在职
• probation：试用
• resigned：离职
• frozen：冻结

domain: org.staff_personal_info.gender

• male：男
• female：女
• unknown：未知

domain: org.staff_personal_info.id_type

• id_card：身份证
• passport：护照
• other：其他

domain: org.staff_transfer.transfer_type

• onboard：入职
• transfer：调动
• resign：离职
• rejoin：复职
• supervisor_change：上级变更
• role_change：角色变更
• freeze：冻结账号
• unfreeze：恢复账号

domain: org.staff_account.platform

• fonrey：房睿主账号
• 58anjuke：58安居客
• cnreic：中国网络经纪人
• wechat_mp：微信公众号

---

3.3 权限系统（permission）

domain: permission.module

• home：首页
• property：房源
• new_house：新房
• client：客源
• transaction：交易
• data：数据
• marketing：营销
• hr：人事OA
• contract：合同
• trinet：三网
• system：系统
• mobile：移动端
• smart_store：智能门店
• recharge：在线充值

domain: permission.value_type

• boolean：开关型（原 BOOLEAN）
• scope：范围型（原 SCOPE）
• integer：数值型（原 INTEGER）

domain: permission.role_category

• agent：置业顾问
• store_manager：店管
• director：总经
• operator：运营/行政
• custom：自定义

domain: permission.scope_level

• none：无
• self：本人
• group：本组
• store：本门店
• area：本区域
• region：本大区
• company：全公司

domain: permission.override_mode

• replace：覆盖（原 REPLACE）
• restrict：限制（原 RESTRICT）
• grant：授予（原 GRANT）

domain: permission.data_scope_type

• self：本人
• group：本组
• store：本门店
• area：本区域
• region：本大区
• company：全公司
• custom_unit：自定义组织单元

domain: permission.change_log.target_type

• role：角色
• role_permission：角色权限
• staff_role：员工角色
• staff_override：员工权限覆盖
• staff_scope：员工数据范围

domain: permission.change_log.action

• create：创建
• update：更新
• delete：删除
• assign：分配
• revoke：撤销

---

3.4 楼盘区域（complex）

domain: complex.school.type

• primary：小学
• middle：初中
• high：高中
• k9：九年一贯制
• k12：十二年一贯制

domain: complex.school.nature

• public：公立
• private：私立
• international：国际

domain: complex.school.level

• normal：普通
• key：重点
• top：名校

domain: complex.building_type

• slab：板楼
• tower：塔楼
• slab_tower：板塔结合

domain: complex.water_type

• civil：民水
• commercial：商水

domain: complex.electricity_type

• civil：民电
• commercial：商电

domain: complex.school_zone_type

• guaranteed：对口
• reference：参考
• lottery：摇号

domain: complex.photo.category

• complex：楼盘图
• layout：户型图
• vr：VR图
• other：其他

---

3.5 房源（property）

domain: property.property_type

• residential：住宅
• villa：别墅
• commercial_residential：商住
• shop：商铺
• office：写字楼
• other：其他

domain: property.status

• for_sale：出售
• for_rent：出租
• for_sale_rent：租售
• suspended：暂缓
• sold_elsewhere：他售
• rented_elsewhere：他租
• sold：成交
• unlisted：未挂牌

domain: property.attribute

• public：公盘
• private：私盘
• special：特盘
• sealed：封盘

domain: property.orientation

• east：东
• south：南
• west：西
• north：北
• southeast：东南
• northeast：东北
• east_west：东西
• south_north：南北
• northwest：西北
• southwest：西南

domain: property.decoration

• rough：毛坯
• plain：清水
• simple：简装
• medium：中装
• fine：精装
• luxury：豪装

domain: property.house_status

• owner_occupied：业主自住
• vacant：空置
• tenant_occupied：租客在住
• unknown：未知

domain: property.viewing_time

• anytime：随时看房
• by_appointment：预约看房
• inconvenient：不便看房

domain: property.grade

• a：A（急迫）
• b：B（较强）
• c：C（一般）
• d：D（较弱）

domain: property.contact.gender

• male：先生
• female：女士

domain: property.contact.identity

• owner：业主
• contact：联系人
• subletter：转租人
• tenant：租客
• agent：代理人
• corporate：企业法人

domain: property.listing_history.listing_type

• for_sale：出售挂牌
• for_rent：出租挂牌

domain: property.listing_history.status

• active：生效中
• ended：已结束

domain: property.follow_log.log_type

• written：手写跟进
• modified：修改跟进
• sensitive_op：敏感操作
• sensitive_view：敏感查看
• other：其他
• system：系统

domain: property.follow_log.ai_tag

• ai_for_sale：AI判断可售
• ai_not_for_sale：AI判断不可售

domain: property.follow_attachment.file_type

• bmp：BMP
• jpg：JPG
• png：PNG
• svg：SVG
• gif：GIF

domain: property.key.key_type

• mechanical：机械钥匙
• password：密码钥匙

domain: property.commission.owner_type

• owner：产权人本人
• authorized_third：授权第三方

domain: property.commission.status

• active：有效
• expired：过期
• cancelled：取消

domain: property.commission_attachment.category

• id_card：身份证件
• property_cert：产权证明
• commission_letter：委托书
• other：其他

domain: property.field_survey.status

• draft：草稿
• submitted：已提交

domain: property.survey_photo.category

• layout：户型图
• living_room：客厅
• dining_room：餐厅
• bedroom：卧室
• bathroom：卫生间
• kitchen：厨房
• entrance：入户
• balcony：阳台
• study：书房
• indoor_other：室内其他
• outdoor：室外

domain: property.photo.category

• cover：封面
• entrance：入户
• living_room：客厅
• dining_room：餐厅
• bedroom：卧室
• bathroom：卫生间
• kitchen：厨房
• balcony：阳台
• study：书房
• indoor_other：室内其他
• outdoor：室外
• panorama：全景

domain: property.attachment.category

• id_card：身份证件
• property_cert：产权证明
• commission_letter：委托书
• other：其他

domain: property.number_holder_approval.status

• pending：待审批
• approved：已通过
• rejected：已驳回

---

3.6 客源（client）

domain: client.client_type

• private：私客
• public：公客
• transacted：成交客

domain: client.status

• buying：求购
• renting：求租
• buy_or_rent：租购
• suspended：暂缓
• bought：已购
• rented_done：已租
• public：公客
• invalid：无效

⚠️ 合法组合约束（client_type × client.status）
client_type 表示客源的"身份类别"，status 表示客源的"当前业务状态"，两者是不同维度。
合法组合矩阵如下：

client_type	允许的 status 值	禁止的 status 值
private（私客）	buying / renting / buy_or_rent / suspended / invalid	public、bought、rented_done（未成交不可用终态）
public（公客）	public / buying / renting / buy_or_rent / suspended / invalid	bought、rented_done
transacted（成交客）	bought / rented_done	其他所有值（终态不可逆）

实施要求：

• 服务层（ClientService）在状态变更时必须校验组合合法性
• DB 侧可用触发器或 CHECK 约束覆盖最关键禁止项（如 transacted + 非终态）
• private → public 转换须调用专用方法 transfer_to_public()，同时修改 client_type 和 status

domain: client.grade

• A：A（急迫）
• B：B（较强）
• C：C（一般）
• D：D（较弱）
• E：E（暂不关注）

domain: client.property_usage

• residential：住宅
• villa：别墅
• commercial_residential：商住
• shop：商铺
• office：写字楼
• other：其他

domain: client.buying_purpose

• rigid：刚需
• investment：投资
• school_district：学区
• upgrade：改善
• commercial：商用
• other：其他

domain: client.payment_method

• full：全额
• mortgage：商业贷款
• mortgage_fund：商贷+公积金
• fund：公积金

domain: client.properties_owned

• none：无
• local_none：本地无/外地有
• local_has：本地有

domain: client.id_type

• id_card：身份证
• passport：护照
• hk_macao：港澳通行证
• other：其他

domain: client.transfer_to_public_type

• manual：手动转公
• auto：自动转公
• marketing_jump：营销客跳公
• resource_public：资料客素公

domain: client.invalid_reason

• invalid_phone：号码无效
• peer_agent：同行
• ad：广告推销
• no_intent：无意向
• other：其他

domain: client.transacted_type

• bought：我购
• rented：我租

domain: client.transacted_property_type

• second_hand：二手
• new_house：新房

domain: client.activity_level

• new_matched：新配对
• active_7d：7日活跃
• active_30d：30日活跃
• active_90d：90日活跃
• expiring：即将过期
• frozen：暂缓中
• invalid：无效

domain: client.contact.gender

• male：先生
• female：女士

domain: client.requirement_type

• second_hand：二手
• new_house：新房
• rental：租房

domain: client.floor_preference

• no_first：不要一楼
• low：低楼层
• mid：中楼层
• high：高楼层
• no_top：不要顶楼

domain: client.orientation

• east：东
• south：南
• west：西
• north：北

domain: client.decoration

• rough：毛坯
• plain：清水
• simple：简装
• medium：中装
• fine：精装
• luxury：豪装

domain: client.building_age_range

• within_5y：5年内
• 5_10y：5-10年
• 10_15y：10-15年
• 15_20y：15-20年
• over_20y：20年以上

domain: client.follow_log.log_type

• written：写入跟进
• modified：修改跟进
• sensitive_view：敏感查看
• other：其他
• system：系统

domain: client.viewing.viewing_type

• appointment：预约
• viewing：带看
• revisit：复看
• empty：空看

domain: client.viewing.client_intent

• interested：感兴趣
• not_interested：不感兴趣
• negotiating：谈判中
• cancelled：取消

domain: client.property_match.match_source

• recorded：录客配房
• system：系统配房

domain: client.property_match.match_group

• quality_layout：优质户型
• price_reduced：降价
• hot：热门
• newly_listed：新上

domain: client.property_match.status

• suggested：待推送
• shared：已分享
• rejected：已反馈不合适
• viewed：客户已查看

domain: client.status_log.change_type

• status_change：改状态
• grade_change：改等级
• to_public：转公客
• to_transacted：转成交
• to_invalid：转无效
• owner_change：改归属人
• source_change：改来源
• merge：合并客源

---

3.7 系统配置（setting）

domain: setting.tenant_setting.value_type

• bool：布尔
• int：整数
• string：字符串
• enum：枚举

domain: setting.field_rule.module

• property：房源
• client：客源（预留）

domain: setting.field_rule.entity_type（与 property.property_type 对齐）

• residential：住宅
• villa：别墅
• commercial_residential：商住
• shop：商铺
• office：写字楼
• other：其他

domain: setting.field_rule.trade_status

• sale：出售
• rent：出租
• sale_rent：租售
• all：全部（原设计为 *，因 SQL/URL/权限表达式通配误解风险已统一改为 all；DB CHECK 约束、前端筛选器须同步）

domain: setting.field_rule.requirement

• required：必填
• optional：选填
• hidden：隐藏

---

四、Tenant 可配置枚举字段清单（lookup_items 权威）

以下字段值域由 lookup_items 维护，属于租户级配置，不在业务表中写死 CHECK。

domain（统一命名）	对应字段	当前状态	说明
client.source	clients.source	✅ 已落地	客源来源
client.follow_purpose	client_follow_logs.purpose	✅ 已落地	客源跟进目的
property.source	properties.source	✅ 已落地	房源来源
property.follow_purpose	follow_logs.purpose	🔄 建议统一	房源跟进目的（建议与 client.follow_purpose 共享或独立分组）
property.commission_type	commissions.commission_type	🔄 待入组	委托类型（独家/非独家等）
client.match_feedback	client_property_matches.feedback	🔄 待入组	配房反馈原因
org.reward_punish_category	staff_reward_punish.category	🔄 待入组	人事奖惩类别

4.1 lookup_groups 规范（Tenant Schema）

• module: 业务模块标识（如 client / property / org）
• key: 领域键（如 source / follow_purpose）
• 同一组内 value 不可重复（UNIQUE(group_id, value)）
• is_system = TRUE 的项禁止物理删除（仅可停用）

---

五、统一实现约束

1. 固定枚举值不可改名：只能新增或停用，禁止修改既有 value。
2. 中文展示从字典取值：前端/UI 不得硬编码中文。
3. 可配置枚举不得加固定 CHECK：防止租户自定义被数据库约束阻断。
4. 跨模块同名枚举必须复用语义：如 status 在不同领域必须使用 domain 区分，不允许混用。
5. 缓存规范：
   • 固定枚举：public:enum_labels:{domain}（建议 TTL 24h）
   • 可配置枚举：{schema}:setting:lookup:{module}.{key}（TTL 300s）

---

六、变更流程（必须同步）

新增或修改任一枚举时，必须同时更新：

1. 本文档 ENUMS.md
2. 对应 DATA_MODEL_*.md 字段定义（CHECK / 注释 / 业务规则）
3. enum_labels 种子数据（若为固定枚举）或 lookup_groups/items fixture（若为可配置枚举）
4. 服务层缓存失效逻辑（Redis key）

---

七、与 ADR 的一致性说明

本文件已对齐以下冻结决策：

• 固定枚举与可配置枚举双轨并存
• 状态机和值域以文档为权威来源
• Tenant 级可配置枚举统一由 setting 模块托管
• Agent 编码前先读枚举标准，禁止各模块自行定义“影子枚举”