faker-cn: 中国大陆高保真虚拟数据生成引擎

faker-cn 是官方原版 Python Faker 的完全独立第三方提供者 (Provider)。

注意：本项目作为原生扩展独立运行，与任何修改了 Faker 源码且未提交 PR 的个人魔改版均无关联，您可以直接在官方标准版的 Faker 环境中无缝挂载使用。

它专门针对中国大陆身份数据进行了高精度的严谨构造和校验。所有的设定不仅为了“随机字符串”，更是为了实现社会逻辑的绝对自洽。

� 核心独家特性 (Why faker-cn?)

区别于传统的随机生成，faker-cn 注入了大量符合现实国情的逻辑判断：

1. 具有时代感的姓名 (Era-based Probabilistic & Gender-Strict Names)
   • 抛弃生硬的穷举。70后有 50% 概率叫“建军、淑兰”；10后有超 90% 的概率叫“子涵、宇轩”。姓名分布严格吻合年代缩影，且实现了极高精度的性别特征隔离（如男性绝不会叫“丽娟”）。
2. 逻辑自洽的财产与车辆 (Contextual Assets & Vehicle Plates)
   • 模拟真实 25% 车主比例，车主身份与年龄（25-55岁）和月薪（>15k概率极高）强绑定。
   • 真实人生轨迹的车牌：车牌前缀 60% 落实在工作地，30% 落实在户籍地，10% 模拟在教育大省（如湖北、江苏）上牌。更有 15% 的几率生成新能源绿牌（带 D/F 标识）。
3. 特化的国内网络足迹 (Digital Footprint Dynamics)
   • 分层的主力邮箱：年轻人（<25岁）大量分配 @qq.com；中年及职场人多为 @163.com。
   • 拒绝盲目的 Gmail：只有“程序员、高管、外贸、科学家”等涉外强相关职业，才有几率生成 gmail.com。
   • 逻辑自洽的个人主页 (WebHome)：不再盲目生成 URL。只有计算机/互联网相关从业者（程序员、架构师等）才会分配个人主页（如 github.io 或 .me），且域名与用户名严格锁定。其余行业人员默认为“无”。
   • 专属 Yopmail 临时邮箱：每个人物都会携带一个 yopmail 邮箱及一键直达链接 (yopmail_url)。
4. AI 赋能：人生轨迹与超写实证件照 (AI-Powered Stories & Realism Photos)
   • 自动化人生长卷：接入人工智能（DeepSeek/OpenAI 等），根据字段自动编写逻辑自洽的人物生平。
   • 超写实 3:4 蓝底证件照：通过生图引擎生成符合 3:4 比例、**极其写实（真人类质感）**的正面免冠蓝底证件照（色码：#438EDB）。
5. 硬核的底层规则校验
   • 完美的身份证生成：18位全准，严格 GB11643-1999 校验码算法（Mod 11-2），前 6 位与生成的出生地分毫不差。
   • 带有内置的高准度中国行政区划字典。
6. 极限深层社会与伦理断言 (Deep Social & Ethical Assertions)
   • 劳动法红线：自动拦截 16 岁以下的童工，拒绝 50 岁之前离奇“退休”的年轻人，剔除 40 岁还在读的大龄“学生”。
   • 严守阶层与学历滑移底线：顶级精英群体（如法官、医生、法医、总裁、架构师等）硬性绑定本科及以上学历底座，杜绝原版 Faker 随时可能掷出的“初中生主治大夫”的荒谬设定。
   • 财富逻辑纠察：未成年人或零收入群体及无业者，绝无可能名下挂靠小汽车等机动车资产；严防高管身份拿着极低薪水的“赤贫陷阱”。
   • 坚守真实学制红线兜底：严格依据中国 18 岁高考的基准线，坚决打回任何“19岁博士”或“20岁硕士”，底层逻辑网经历过连续 5 万次极端异常事件盲测 0 报错。

📦 保姆级安装指南

本库专为 Python 开发者和测试工程师编写，推荐在 Python 3.7+ 的环境中使用。

1. 安装原生 Faker 和本项目：

pip install Faker faker-cn

2. 在代码中无缝接入：

import json
from faker import Faker
from faker_cn import PersonaProvider

# 第一步：初始化官方的 Faker（指定语言为中文）
fake = Faker('zh_CN')

# 第二步：将我们强大的 faker-cn 引擎挂载进去
fake.add_provider(PersonaProvider)

就是这么简单！您已经解锁了最高级别的虚拟数据生成能力。

🚀 保姆级使用教程

场景一：一键生成一个完整的“真实人类”

当你不传入任何参数时，faker-cn 会像上帝掷骰子一样，完全随机但又极其严谨地捏造一个完整的人生长卷。

# 生成完整的人物档案字典
person = fake.persona()

print(f"姓名: {person['name']}, 身份证: {person['ssn']}")
print(f"他/她的主邮箱是: {person['email']}")
print(f"你还能直接去查看他的收件箱 (Yopmail): {person['yopmail_url']}")
print(f"他的车牌号是: {person['asset']['vehicle_plate']}")
print(f"他有 {person['asset']['deposit']} 存款")

场景二：我想接入人工智能 (人生轨迹+证件照)

如果你填入了 AI 的 API 密钥，faker-cn 将摇身一变为“赛博造物主”，为你补充照片和生平。

# 传入您的 AI keys
ai_config = {
    "api_key": "您的_DeepSeek_密钥",
    "image_api_key": "您的_SiliconFlow_密钥" # 用于生成蓝底证件照
}

person = fake.persona(use_ai=True, ai_config=ai_config)

print(f"人生经历: {person['life_story']}")
print(f"证件照 URL: {person['avatar_url']}")

场景三：我想定制特定的人设（按需生成）

比如，你正在测试一个只针对年轻女性高端用户的系统功能，你可以这样写：

# 生成一名 22-26岁，高管/外贸相关，北京户口的女性
custom_person = fake.persona(
    gender='女', 
    age_range=(22, 26), 
    job='跨国企业高管'
)
print(json.dumps(custom_person, ensure_ascii=False, indent=2))

你会惊奇地发现，由于设定了“跨国高管”且年龄较轻：

• 她的邮箱极有可能是 gmail.com 或高端企业邮箱。
• 设备参数 (os, user_agent) 大概率会是最新版 iPhone 或 Mac。
• 薪水数字被动态拉高。

场景三：极简模式（我只要特定的某几个字段）

在做大批量写入数据库的压力测试时，你可能不需要巨大的完整字典集，只要几个关键字段。可以利用 fields 参数，支持深层嵌套提取！

mini_person = fake.persona(
    gender='男',
    fields=[
        'name',                     # 姓名
        'social.education',         # 学历 (原样在 social 字典里)
        'hometown.city',            # 老家的城市
        'temp_email_url',           # 仅提取临时邮箱直达车
        'asset.vehicle_plate'       # 深层嵌套：仅要车牌号
    ]
)
print(mini_person)
# 输出示例: {'name': '张伟', 'education': '本科', 'city': '南京市', 'temp_email_url': '...', 'vehicle_plate': '苏A·829F5'}

📖 返回字段全景字典 (Data Structure)

调用 fake.persona() 默认返回的完整 JSON 结构如下，包含四大核心模块：基础信息、户口与常驻地、社会身份与账号、资金与资产。

🛠️ 数据字典更新维护

内部集成的中国地名与区划等统计数据可能随物理世界政策变更。你可以使用仓库自带脚本重新抓取、聚合本地数据：

python build_dicts.py

📜 协议声明 (License)

本项目拥抱开源，采用 GPL-3.0 License 进行分发。您可以自由使用、修改与研究。