FX Sim Data

KYC/企业信息模拟数据工具库 - 提供完整的TypeScript类型支持

📖 简介

fx-sim-data 是一个专为 KYC（了解你的客户）和企业信息表单设计的模拟数据工具库。它使用 faker.js 提供符合真实业务场景的测试数据，并提供完整的 TypeScript 类型支持。

✨ 主要特性

• 🎯 完整的 TypeScript 支持 - 所有函数和数据结构都有详细的类型定义
• 🌍 真实的国家数据 - 基于 ISO 3166-1 标准的国家/地区代码
• 🎲 faker.js 驱动 - 使用业界标准的数据生成库
• 📦 模块化设计 - 可按需导入所需模块
• 🔧 灵活配置 - 支持自定义种子、预设场景等
• 🚀 开箱即用 - 提供 CommonJS 和 ESM 两种格式

📦 安装

npm install fx-sim-data @faker-js/faker
# 或
yarn add fx-sim-data @faker-js/faker
# 或
pnpm add fx-sim-data @faker-js/faker

使用 Demo Panel 组件

如果要使用 Demo Panel 组件（用于表单快速填充），还需要安装以下依赖：

npm install react react-dom antd

注意：Panel 组件的样式已经预编译在 fx-sim-data/styles.css 中，无需额外配置 Tailwind CSS。

样式编译原理：

• 构建时 Tailwind 会自动扫描所有 Panel 组件（.demo.tsx 文件）
• 提取所有使用的 className（如 fixed、bottom-8、bg-white 等）
• 编译成完整的 CSS 文件并压缩
• 最终生成的 dist/styles.css 包含所有必需样式，开箱即用

🚀 快速开始

基本用法

import { createPersonalInfo, createCompanyInfo } from "fx-sim-data";

// 创建个人信息
const personalData = createPersonalInfo();
console.log(personalData);
// {
//   nationality: 'HKG',
//   idType: 'PASSPORT',
//   firstName: 'John',
//   lastName: 'Smith',
//   ...
// }

// 创建企业信息
const companyData = createCompanyInfo();
console.log(companyData);
// {
//   companyName: 'Tech Corp',
//   registrationCountry: 'HKG',
//   ...
// }

使用预设场景

import { personalInfoPresets, companyInfoPresets } from "fx-sim-data";

// 创建香港居民数据（使用身份证）
const hkResident = personalInfoPresets.hkResidentWithIdCard();

// 创建香港上市公司数据
const hkListedCompany = companyInfoPresets.hkListedCompany();

批量创建

import { createPersonalInfoBatch } from "fx-sim-data";

// 创建 10 条个人信息数据
const dataList = createPersonalInfoBatch(10);

// 创建可重复的数据（使用种子）
const repeatableData = createPersonalInfoBatch(5, { seed: 12345 });

📚 API 文档

个人 KYC 模块

createPersonalInfo(options?)

创建个人基本信息表单数据。

import { createPersonalInfo, PersonalInfoFormData } from "fx-sim-data";

const data: PersonalInfoFormData = createPersonalInfo({
  includeOverseas: true, // 包含海外居民信息
  nationality: "HKG", // 指定国籍
  includeChineseName: true, // 包含中文姓名
  isPermanentId: false, // 证件是否长期有效
  seed: 12345, // 自定义种子
});

createAddressInfo(options?)

创建地址信息表单数据。

import { createAddressInfo } from "fx-sim-data";

const addressData = createAddressInfo({
  currentCountry: "HKG", // 指定居住国家
  residenceProofType: "UTILITY_BILL", // 指定证明文件类型
  seed: 12345,
});

createFinancialInfo(options?)

创建财务信息表单数据。

import { createFinancialInfo } from "fx-sim-data";

const financialData = createFinancialInfo({
  employmentStatus: "EMPLOYED", // 就业状态
  industry: "TECHNOLOGY", // 行业
  incomeSourceCountry: "HKG", // 收入来源国家
  isUSPerson: "NO", // 是否美国公民
  seed: 12345,
});

企业 KYC 模块

createCompanyInfo(options?)

创建企业基本信息表单数据。

import { createCompanyInfo } from "fx-sim-data";

const companyData = createCompanyInfo({
  registrationCountry: "HKG", // 注册国家
  listingStatus: "YES", // 上市状态
  companyType: "FOR_PROFIT", // 公司类型
  seed: 12345,
});

createRelatedPerson(options?)

创建关联人士（董事、股东等）信息。

import { createRelatedPerson } from "fx-sim-data";

const relatedPerson = createRelatedPerson({
  type: "INDIVIDUAL_SHAREHOLDER", // 人士类型
  isShareholdingBeneficiary: true, // 是否为股东/实益拥有人
  seed: 12345,
});

createCompanyFinancial(options?)

创建企业财务信息表单数据。

import { createCompanyFinancial } from "fx-sim-data";

const financialData = createCompanyFinancial({
  netProfit: 50000000, // 自定义净利润
  netAssets: 500000000, // 自定义净资产
  vaHoldingsRatio: 20, // 虚拟资产占比
  seed: 12345,
});

测评问卷模块

createRiskAssessment(quizData, config)

创建风险测评问卷答案。

import { createRiskAssessment, RISK_ASSESSMENT_PRESETS } from "fx-sim-data";

const answers = createRiskAssessment(quizData, {
  targetRiskType: RISK_ASSESSMENT_PRESETS.MODERATE.riskType, // 稳健型
});

createVirtualAssetData(questions, config)

创建虚拟资产知识测试答案。

import { createVirtualAssetData, VIRTUAL_ASSET_PRESETS } from "fx-sim-data";

const answers = createVirtualAssetData(questions, {
  targetScore: 70, // 目标分数：及格（70分）
});

// 或使用预设
const excellentAnswers = createVirtualAssetData(
  questions,
  VIRTUAL_ASSET_PRESETS.EXCELLENT // 100分
);

工具函数

triggerFileUpload(options?)

在浏览器环境中触发文件上传控件（用于自动化测试）。

import { triggerFileUpload } from "fx-sim-data";

await triggerFileUpload({
  fileUrl: "/test-file.png",
  fileName: "mock-file.png",
  selector: 'input[type="file"]',
  onSuccess: (file) => console.log("上传成功", file),
  onError: (error) => console.error("上传失败", error),
});

Demo Panel 组件

用于快速集成到表单中的 React 组件，可一键填充测试数据。

⚠️ 重要：导入样式文件

Panel 组件需要样式支持，请在你的应用入口文件中导入样式：

// 在你的 main.tsx 或 App.tsx 顶部导入
import "fx-sim-data/styles.css";

使用示例：

import { PersonalInfoPanel, CompanyInfoPanel, Panels } from "fx-sim-data";
import "fx-sim-data/styles.css"; // 导入样式
import { Form } from "antd";

function MyForm() {
  const [form] = Form.useForm();

  return (
    <Form form={form}>
      {/* 使用个人信息 Panel */}
      <PersonalInfoPanel form={form} />

      {/* 使用公司信息 Panel */}
      <CompanyInfoPanel form={form} />

      {/* 或通过 Panels 对象访问 */}
      <Panels.AddressInfo form={form} />
      <Panels.FinancialInfo form={form} />
    </Form>
  );
}

可用的 Panel 组件：

// 个人KYC
PersonalInfoPanel; // 个人信息
AddressInfoPanel; // 地址信息
FinancialInfoPanel; // 财务信息

// 企业KYC
CompanyInfoPanel; // 公司信息
CompanyStructurePanel; // 公司结构/关联人士
CompanyFinancialPanel; // 公司财务
CompanyUploadFilePanel; // 公司文件上传

// 测评问卷
RiskAssessmentPanel; // 风险测评
VirtualAssetPanel; // 虚拟资产测试

// 其他
EnhancedDueDiligencePanel; // 增强尽职调查
SupplementaryMaterialsPanel; // 补充材料

🎨 预设场景

个人 KYC 预设

import { personalInfoPresets } from "fx-sim-data";

// 香港居民（身份证）
personalInfoPresets.hkResidentWithIdCard();

// 中国大陆居民（护照）
personalInfoPresets.mainlandChineseWithPassport();

// 海外居住的中国公民
personalInfoPresets.overseasChinese();

// 外国居民
personalInfoPresets.foreignResident();

// 长期有效证件
personalInfoPresets.permanentIdDocument();

企业 KYC 预设

import {
  companyInfoPresets,
  companyStructurePresets,
  companyFinancialPresets,
} from "fx-sim-data";

// 公司信息预设
companyInfoPresets.hkListedCompany(); // 香港上市公司
companyInfoPresets.hkPrivateCompany(); // 香港非上市公司
companyInfoPresets.mainlandCompany(); // 中国大陆公司
companyInfoPresets.singaporeCompany(); // 新加坡公司

// 关联人士预设
companyStructurePresets.individualShareholder(); // 个人股东
companyStructurePresets.individualDirector(); // 个人董事
companyStructurePresets.corporateShareholder(); // 法人股东

// 财务信息预设
companyFinancialPresets.smallProfitable(); // 小型盈利企业
companyFinancialPresets.mediumProfitable(); // 中型盈利企业
companyFinancialPresets.largeProfitable(); // 大型盈利企业
companyFinancialPresets.highNetWorth(); // 高净值企业

🏗️ 项目结构

fx-sim-data/
├── src/
│   ├── index.ts                    # 主入口文件
│   ├── types.ts                    # 类型定义汇总
│   ├── data/                       # 国家数据（JSON）
│   │   ├── country.json
│   │   ├── country-allowed.json
│   │   └── country-restricted.json
│   ├── personal/                   # 个人KYC模块
│   │   ├── personal-info/          # 个人信息
│   │   ├── address-info/           # 地址信息
│   │   └── financial-info/         # 财务信息
│   ├── company/                    # 企业KYC模块
│   │   ├── company-info/           # 公司信息
│   │   ├── company-structure/      # 公司结构
│   │   └── company-financial/      # 公司财务
│   ├── risk-assessment/            # 风险测评
│   ├── virtual-asset-test/         # 虚拟资产测试
│   └── utils/                      # 工具函数
├── dist/                           # 编译输出（自动生成）
│   ├── index.js                    # CommonJS 格式
│   ├── index.mjs                   # ESM 格式
│   ├── index.d.ts                  # TypeScript 类型定义
│   └── ...
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

🔧 开发

构建项目

# 安装依赖
npm install

# 构建（生成 dist/ 目录）
npm run build

# 开发模式（监听文件变化）
npm run dev

# 类型检查
npm run typecheck

# 清理构建产物
npm run clean

使用本地版本

在其他项目中测试本地版本：

# 在本项目目录
npm link

# 在目标项目目录
npm link fx-sim-data

使用 Panel 组件样式

本库的 Panel 组件样式已经预编译，无需配置 Tailwind CSS。

只需在应用入口导入样式文件：

// main.tsx 或 App.tsx
import "fx-sim-data/styles.css";

样式文件包含：

• 所有 Panel 组件使用的 Tailwind 工具类
• 优化过的样式，避免与 Ant Design 冲突
• 已压缩，体积小巧

如果你想自定义样式，可以在导入后覆盖 CSS 变量或类名。

📝 类型支持

本库提供完整的 TypeScript 类型定义，所有导出的函数和数据结构都有详细的类型注解：

// 导入类型
import type {
  PersonalInfoFormData,
  CompanyInfoFormData,
  RelatedPersonData,
  // ... 更多类型
} from "fx-sim-data";

// 或从 types 子模块导入
import type { PersonalInfoFormData } from "fx-sim-data/types";

🌐 国家/地区支持

本库使用基于 ISO 3166-1 的真实国家数据：

• 所有国家 (country.json) - 用于国籍、出生地等字段
• 允许的国家 (country-allowed.json) - 用于受限制的选择
• 受限制国家 (country-restricted.json) - 用于企业 KYC

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT © FX Sim Data

🔗 相关链接

• faker.js 文档
• TypeScript 文档
• ISO 3166-1 国家代码

❓ 常见问题

如何创建可重复的数据？

使用 seed 选项：

const data1 = createPersonalInfo({ seed: 12345 });
const data2 = createPersonalInfo({ seed: 12345 });
// data1 和 data2 完全相同

如何自定义创建的数据？

大多数函数都接受配置选项：

const data = createPersonalInfo({
  nationality: "HKG", // 固定国籍为香港
  includeChineseName: true, // 必须包含中文姓名
  isPermanentId: true, // 证件长期有效
});

支持哪些输出格式？

本库同时支持 CommonJS 和 ESM 两种格式：

// CommonJS
const { createPersonalInfo } = require("fx-sim-data");

// ESM
import { createPersonalInfo } from "fx-sim-data";

如何在 React 项目中使用？

直接导入使用即可，TypeScript 会自动提供类型提示：

import { createPersonalInfo } from 'fx-sim-data';
import { useState } from 'react';

function MyComponent() {
  const [data, setData] = useState(() => createPersonalInfo());

  return (
    <div>
      <pre>{JSON.stringify(data, null, 2)}</pre>
      <button onClick={() => setData(createPersonalInfo())}>
        重新创建
      </button>
    </div>
  );
}

Made with ❤️ for better testing experience