fx-sim-data/README.md

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

# FX Sim Data

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

[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📖 简介

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

### ✨ 主要特性

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

## 📦 安装

```bash
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 组件（用于表单快速填充），还需要安装以下依赖：

```bash
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` 包含所有必需样式，开箱即用

## 🚀 快速开始

### 基本用法

```typescript
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',
//   ...
// }
```

### 使用预设场景

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

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

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

### 批量创建

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

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

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

## 📚 API 文档

### 个人 KYC 模块

#### `createPersonalInfo(options?)`

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

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

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

#### `createAddressInfo(options?)`

创建地址信息表单数据。

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

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

#### `createFinancialInfo(options?)`

创建财务信息表单数据。

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

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

### 企业 KYC 模块

#### `createCompanyInfo(options?)`

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

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

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

#### `createRelatedPerson(options?)`

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

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

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

#### `createCompanyFinancial(options?)`

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

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

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

### 测评问卷模块

#### `createRiskAssessment(quizData, config)`

创建风险测评问卷答案。

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

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

#### `createVirtualAssetData(questions, config)`

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

```typescript
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?)`

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

```typescript
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 组件需要样式支持，请在你的应用入口文件中导入样式：

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

**使用示例：**

```typescript
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 组件：**

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

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

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

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

## 🎨 预设场景

### 个人 KYC 预设

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

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

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

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

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

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

### 企业 KYC 预设

```typescript
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
```

## 🔧 开发

### 构建项目

```bash
# 安装依赖
npm install

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

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

# 类型检查
npm run typecheck

# 清理构建产物
npm run clean
```

### 使用本地版本

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

```bash
# 在本项目目录
npm link

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

### 使用 Panel 组件样式

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

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

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

**样式文件包含：**

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

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

## 📝 类型支持

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

```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 文档](https://fakerjs.dev/)
- [TypeScript 文档](https://www.typescriptlang.org/)
- [ISO 3166-1 国家代码](https://en.wikipedia.org/wiki/ISO_3166-1)

## ❓ 常见问题

### 如何创建可重复的数据？

使用 `seed` 选项：

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

### 如何自定义创建的数据？

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

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

### 支持哪些输出格式？

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

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

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

### 如何在 React 项目中使用？

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

```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**