导入 / 导出

Bonds 支持 vCard 导入导出以及 Monica 4.x JSON 导入，方便从其他应用迁移数据或创建备份。

Monica 4.x 导入

如果你正在从 Monica CRM（4.x 版本）迁移，Bonds 可以导入你的完整数据，包括联系人、笔记、通话、任务、关系、照片等。

如何导入

1. 在 Monica 中，进入 设置，导出 下载 JSON 导出文件。
2. 在 Bonds 中，进入 Vault 设置，Monica 导入 标签页。
3. 上传 JSON 文件。所有数据将自动导入。

导入内容

Monica 实体	Bonds 映射
联系人	联系人（姓名、性别、昵称、职位、公司、星标、已故）
标签	标签
生日 / 去世日期	重要日期
笔记	笔记
通话	通话
任务	任务
提醒	提醒
地址	地址
联系方式（邮箱、电话等）	联系方式
宠物	宠物
礼物	礼物
债务	借贷
关系	关系（按类型名称匹配）
生活事件（Monica 旧字段）	活动记录
照片和文档	文件（base64 解码并存储）
活动（Monica 旧字段）	笔记（降级，带类型前缀）
对话	笔记（格式化为聊天记录）

专属的 Monica 导入兼容性处理

为了解决 Monica 与 Bonds 在数据结构定义上的差异，Bonds 实现了一套容错机制：

• 性别回退策略（Gender Fallback）：Monica 允许以任意文本形式（包含非英文或完全自定义的值）导出性别。如果在导入时未能在 Bonds 数据库中匹配到对应的预设性别，系统会智能回退到预设值，或动态映射为自定义性别选项，以确保数据完整迁移而不报错中断。
• 宠物类别处理：将 Monica 中的宠物数据映射到 Bonds 宠物对象时，系统会自动将动物类别转换匹配到 Bonds 账户级的内置或自定义宠物类别中（如猫、狗、鸟等），若无法识别则以默认宠物类型作为兜底。

重复检测

重复导入是安全的。联系人通过原始 Monica UUID 匹配，已存在的会跳过。

权限

只有 Vault 管理者（Manager） 可以执行导入。

Monica v5 用户

Monica v5 已移除 JSON 导出功能，仅保留 VCard 导出。如果你已升级到 v5：

• 使用 VCard 导入可迁移联系人基本信息（姓名、电话、邮箱、地址）。
• 如需完整迁移：请在升级到 v5 之前先从 4.x 导出 JSON。

vCard 导出

单个联系人

将任意联系人导出为 vCard 4.0 文件：

GET /api/vaults/:vault_id/contacts/:contact_id/vcard

返回包含联系人姓名、电话、邮箱和地址的 .vcf 文件。

批量导出

一次导出 Vault 中的所有联系人：

GET /api/vaults/:vault_id/contacts/export

返回包含所有联系人的单个 .vcf 文件。

vCard 导入

从 .vcf 文件导入联系人（支持单个和多联系人文件）：

POST /api/vaults/:vault_id/contacts/import

以 multipart 表单上传 .vcf 文件。Bonds 解析 vCard 并按以下字段映射创建联系人：

vCard 属性	Bonds 字段
FN	名 + 姓
N	结构化姓名
TEL	电话联系方式
EMAIL	邮箱联系方式
ADR	地址

提示

• 从其他应用迁移：大多数联系人管理应用（Google 通讯录、Apple 通讯录、Outlook、Monica）都支持导出 .vcf 文件。先从那里导出，再导入到 Bonds。
• 大批量导入：Bonds 处理多联系人 .vcf 文件，可以一次导入数百个联系人。
• 未导入的字段：没有直接映射的字段（如 vCard X- 扩展中的社交媒体资料）会被跳过。导入后可手动添加。

备份与恢复

如需完整数据备份（不仅是联系人），请使用管理面板中的内置备份系统。详见管理面板。