字段映射策略

开放接口对外暴露的字段与内部数据模型需要进行映射转换。内部模型多使用整数编码（如 gender: 1/2），开放接口对外使用字符串枚举（如 gender: "male"/"female"），提升可读性和跨系统兼容性。

---

嘉宾字段映射

开放接口字段	内部模型字段	转换规则
gender	gender	1 → "male", 2 → "female"
education	education_level	1 → "高中及以下", 2 → "大专", 3 → "本科", 4 → "硕士", 5 → "博士"
income_level	income_level	1 → "10万以下", 2 → "10-20万", 3 → "20-30万", 4 → "30-50万", 5 → "50-100万", 6 → "100万以上"（由 income_amount 反推，保证一致）
income_amount	income_amount	年收入金额（元），BigInteger，权威字段，直接映射
family_income_amount	family_income_amount	家庭年收入金额（元），为空时等于 income_amount，直接映射
family_income_level	family_income_level	家庭年收入等级，与 income_level 相同的 6 档枚举，为空时等于 income_level
req_income_amount	req_income_amount	择偶收入要求下界（元），直接映射
req_income_text	req_income_text	择偶收入要求原文，直接映射
marital_status	marriage_status	1 → "未婚", 2 → "离异", 3 → "丧偶"
has_children	has_children	0 → "no", 1 → "yes"
has_house	has_house	0 → "no", 1 → "yes"
has_car	has_car	0 → "no", 1 → "yes"
workplace	workplace	直接映射
photos	photos	JSON 数组，需反序列化
self_intro	self_intro	直接映射
requirement	requirement	直接映射
status	status	1 → "incomplete", 2 → "available", 3 → "matching", 4 → "matched", 5 → "archived"

匹配字段映射

开放接口字段	内部模型字段	转换规则
guest_a_id	guest_a_id	直接映射
guest_b_id	guest_b_id	直接映射
guest_a_matchmaker_id	guest_a_matchmaker_id	直接映射
guest_b_matchmaker_id	guest_b_matchmaker_id	直接映射
status	status	字符串直接映射
match_score	match_score	0-100 整数，直接映射

会员字段映射

开放接口字段	内部模型字段	转换规则
user_id	user_id	直接映射
guest_id	guest_id	直接映射
plan_id	plan_id	直接映射
plan_name	plan_name	直接映射
expire_at	expire_at	直接映射
status	status	字符串直接映射

活动字段映射

开放接口字段	内部模型字段	转换规则
title	title	直接映射
cover_url	cover_url	直接映射
address	address	直接映射
male_quota	male_quota	整数
female_quota	female_quota	整数
male_fee	male_fee	直接映射
female_fee	female_fee	直接映射
status	status	字符串直接映射
audit_status	audit_status	字符串直接映射

公司字段映射

开放接口字段	内部模型字段	转换规则
name	name	直接映射
contact_name	contact_name	直接映射
contact_phone	contact_phone	直接映射
status	status	0 → "frozen", 1 → "active", 2 → "pending", 3 → "rejected"

工作微信号字段映射

开放接口字段	内部模型字段	转换规则
status	status	0 → "disabled", 1 → "active"
admin_id	admin_id	直接映射
wechat_number	wechat_number	直接映射
phone	phone	直接映射
wechat_nickname	wechat_nickname	直接映射
avatar	avatar	直接映射
qr_code	qr_code	直接映射
remark	remark	直接映射
association_count	计算字段	关联表记录数
user_count	计算字段	用户表关联数

注意：工作微信号的 status 字段是唯一需要转换的字段，其余字段均为直接映射。关联数量（association_count、user_count）为运行时计算字段，不对应单一数据库列。

微信群字段映射

开放接口字段	内部模型字段	转换规则
status	status	0 → "disabled", 1 → "active"
name	name	直接映射
group_no	group_no	直接映射
qr_code	qr_code	直接映射
remark	remark	直接映射
matchmaker_count	计算字段	关联红娘数（work_group_matchmakers 表）
work_wechat_count	计算字段	关联工作微信号数（work_group_work_wechats 表）

注意：微信群的 status 字段是唯一需要转换的字段，其余字段均为直接映射。成员数量（matchmaker_count、work_wechat_count）为运行时计算字段，不对应单一数据库列。

实现方式

在 app/schemas/open_api.py 中使用 Pydantic v2 的 field_validator 进行字段转换：

from pydantic import BaseModel, field_validator
from typing import Optional, List

class GuestOut(BaseModel):
    id: int
    name: str
    gender: str
    education: Optional[str] = None
    marital_status: Optional[str] = None
    status: str
    photos: List[str] = []

    @field_validator("gender", mode="before")
    @classmethod
    def convert_gender(cls, v):
        if isinstance(v, int):
            return {1: "male", 2: "female"}.get(v, "unknown")
        return v

    @field_validator("education", mode="before")
    @classmethod
    def convert_education(cls, v):
        if isinstance(v, int):
            return {1: "高中及以下", 2: "大专", 3: "本科", 4: "硕士", 5: "博士"}.get(v)
        return v