联系人

联系人是 Bonds 的核心实体。每个联系人都属于一个 Vault，可以存储关于某个人的丰富结构化信息。

联系人信息

每个联系人支持：

• 姓名：名、姓、昵称、曾用名。
• 联系方式：邮箱、电话、社交媒体链接（12 种内置类型）。
• 地址：多个地址，支持类型标记（家庭、工作等），可选地理编码。
• 公司：职位和公司关联。
• 性别与代词：可自定义的性别和代词选项。
• 宗教：可选的宗教信仰。
• 需要验证标记：可将联系人标记为「需要验证」。当某些人的联系方式可能过期时，这是一个极佳的视觉提醒，便于你定期核对与确认。

模块

联系人详情页默认以查看模式打开，优先展示已填写、适合阅读的信息，包括摘要字段、快速信息和笔记，不显示编辑控件。切换到编辑模式后，可进入完整模板标签页并使用各模块的增删改功能。

联系人编辑页由模块组成，也就是显示在模板页面上的可配置组件。默认模块包括：

模块	说明
联系人姓名	姓名字段和昵称
重要日期	生日、纪念日、自定义日期
关系	家人、伴侣、朋友
笔记	附加到联系人的自由文本
任务	关联到联系人的待办事项
提醒	定时通知
通话	电话记录及备注
礼物	礼物想法和追踪
借贷	借入或借出的钱款或物品，支持数量、借出/借入日期、归还期限和归还状态
活动记录	重要活动与里程碑，可关联同一 Vault 内的其他参与联系人
宠物	宠物名称和类别（类别在账户层面统一管理）
分组	联系人分组归属
文档	上传的文件（PDF、图片）
媒体	照片和视频画廊
日记	带模板的日记式条目
目标	个人目标追踪
动态	活动时间线

模板

模板控制联系人详情页的布局。每个模板有多个页面（标签页），每个页面显示一组模块。默认模板包含：

1. 联系信息：头像、姓名、重要日期、性别、标签、公司、宗教。
2. 动态：活动时间线。
3. 社交：关系、宠物、分组、地址、联系方式。
4. 活动记录：重要活动与里程碑。
5. 目标：个人目标与进度。
6. 信息：文档、媒体、笔记、提醒、借贷、任务、通话、日记。

模板和模块分配可通过个性化设置自定义。

标签

标签是你可以分配给联系人的标记，用于组织和筛选。创建自定义标签，按你喜欢的方式分类联系人。

头像

每个联系人都有头像。如果没有上传照片，Bonds 会自动生成首字母头像，也就是一个带有联系人首字母的彩色圆形。颜色由名字的 MD5 哈希确定性生成，同一个名字始终得到相同的颜色。

宠物

你可以为联系人添加宠物。宠物类别在账户级别定义，允许你从预定义的类别列表（例如狗、猫或鸟）中进行选择。你可以通过系统设置中的“个性化设置”来管理这些宠物类别。

按身份反查联系人（by-identity）

集成应用和 AI 助手经常需要回答「这个邮箱/电话号属于哪个联系人？」，而不希望遍历整个 Vault 做字符串匹配。

Bonds 提供 vault 范围的反查端点：

GET /api/vaults/{vault_id}/contactInformation/by-identity?data=<value>&type_id=<n>

• data（必填）：要查找的身份值，匹配大小写不敏感。
• type_id（可选）：限定只在某种 ContactInformationType（例如只查邮箱）中查找。

响应是一组匹配，每条包含 contact_id、联系人姓名以及完整的 ContactInformationResponse。查找仅限单个 vault，要求对该 vault 至少拥有 Viewer 权限。

示例：

curl -H "Authorization: Bearer $TOKEN" \
  "$APP_URL/api/vaults/$VAULT_ID/contactInformation/[email protected]"

关系

定义联系人之间的关系，包括父母、子女、伴侣、朋友、同事等。关系类型按组分类：

• 爱情：伴侣、配偶、恋人。
• 家庭：父母、子女、兄弟姐妹。
• 友谊：密友、熟人。
• 工作：同事、导师、上司。

跨 Vault 关系

关系可以跨越不同的 Vault。添加关系时，联系人选择器会显示你有权访问的所有 Vault 中的联系人，按 Vault 名称分组。

• 若你对目标 Vault 拥有编辑者权限，系统会自动创建双向关系（两个联系人都能看到该关系）。
• 若你只有查看者权限，则只创建单向关系，界面会提示原因。
• 删除跨 Vault 关系时，会自动清理对方的反向记录。

合并重复联系人

新增记录与合并使用相同的联系人事务边界。已完成的新增会纳入下一次合并审核；若合并先完成，则拒绝向已删除来源新增。请刷新保留联系人后重试。因该原因被拒绝的文件上传会从存储中清理。动态记录与对应操作一起提交。CSV 和 Monica 导入逐条报告无法关联的记录；已经导入空间的文件仍可在“文件”中访问。

在同一空间选中 2–50 个联系人，点击合并联系人。先选择保留身份、可见性及布局的目标。预览显示所有非空资料值、冲突、重要日期和受影响记录数量；逐项选择冲突值并确认实际影响。预览后资料发生变化需重新审核。编辑者和管理员可操作，受保护联系人只能作为保留目标。

空字段自动补齐，公司与职位、初次见面日期各部分整体保留。笔记、电话、地址、文件、工作、任务、活动及提醒原位迁移，不删除内容相似的独立记录。相同成员关联及关系会归并，所选联系人间的关系因合并为自身关系而移除。额外生日／忌日转为普通日期，保留提醒 ID 及调度时间。群组角色冲突及当前空间无法访问的旧介绍人引用需先处理。修改或删除入向关系和介绍人引用必须拥有每个受影响引用所属空间的编辑权限；完全不变的保留联系人入向关系不要求外部编辑权限。

同空间笔记和活动描述中的结构化联系人提及也会重定向，包括其他联系人名下的笔记、未将被提及者列为参与者的活动。显示名、格式和附件保持不变，提及不会新增活动参与者。审核会显示受影响正文的数量；正文发生变化后须重新审核。合并前打开的编辑器须刷新，旧提交不能重新写入已删除的联系人链接。已有的跨空间或已删除联系人历史提及仍可随正文编辑保留，新增提及必须指向当前空间的有效联系人。其他空间的历史正文不会被改写。

日记文章保留段落 ID、格式及附件引用。合并也会检查本空间正文中的真实提及，涵盖旧版编辑或联系人跨空间往返后关联缺失的文章；仅为已迁移提及补齐保留联系人的关联。文章更新显式提交 contact_ids 而省略段落时，已存正文提及仍优先，解除提及需同时修改正文。仅更新元数据及最近联系时间时，历史正文和关联保持不变，只推进仍在本空间的现有关联联系人的时间；没有正文提及的旧文章仍支持显式联系人列表。正文中的联系人提及与关联表在同一事务内指向保留联系人，显示名及周围文字保持不变。合并前已打开的文章须刷新后再保存。文章编辑、删除与合并按相同锁顺序执行；段落变化会要求重新审核合并。日记仅支持同空间联系人，历史遗留的跨空间文章关联须先在所属日记中处理，合并不会借此改写其他空间正文。

不复制来源资料到笔记，不新增快照或撤销表。经明确确认后，未选中的单值字段从有效资料舍弃。来源沿用已有软删除生命周期，审计动态仅记录合并数量。操作不可撤销。Monica 重导入跳过已删除来源 UUID；vCard 文件导入仍只新增，再次导入可能产生重复项，但不会覆盖已合并联系人。

已关联 CardDAV 的联系人不可合并，包括停用、只读订阅及旧远端路径：后续拉取可能覆盖合并字段，远端删除也无法与本地事务保持原子性。请先在远端来源合并。即使联系人尚未关联，空间有启用的 DAV 推送时也需先暂停推送。未处理的原始 vCard 资料需先处理。确认时会重新校验这些限制，不删除远端记录或同步映射。

对于 Bonds 自身的 CardDAV 通讯录，已删除来源路径不可读取，也拒绝旧客户端回写。目标更新会校验请求中的 ETag，过期的条件写入不会覆盖合并结果。主动省略条件的客户端仍采用标准的无条件更新行为。

DAV 更新按单条记录核对。调整电话参数顺序或编辑邮箱不会重建无关电话记录或丢失其类型。新增、修改或删除投影到 vCard 的公历生日不影响其他重要日期；编辑保留生日和提醒 ID，重排待发送通知并保留发送历史。删除该生日会删除其关联提醒，与 Bonds 编辑器一致。未导出到 vCard 的不完整日期会保留。农历生日投影及独立同步的日历事件需在 Bonds 中编辑。

未改变的地址保留 ID、坐标和历史，客户端调整顺序、大小写或空格也不影响这些信息；其他地址可以独立新增或修改。删除普通共享地址只解除当前联系人的关联。替换含未导出详情或历史的地址会返回冲突，提示在 Bonds 中处理。Bonds CardDAV 与订阅拉取使用相同规则，包括暂停订阅、合并未关联联系人后恢复同步。被拒绝的更新整体回滚并记录日志，不推进同步检查点，解决对应记录后可重试。一批同步部分失败时，已成功拉取的记录不会在重试时被误判为本地编辑；真实的本地编辑仍受冲突保护。合并不会删除远端数据或重新分配同步身份。

只有明确选择“生日”类型的重要日期会作为 DAV 生日。升级会一次性为旧的仅靠 Birthday／Birthdate 标签识别、且同时具备月日的首个生日补上现有生日类型，保留原行、标签及提醒。更早的不完整日期会跳过；若所有候选都缺少月或日，则全部保留为普通日期，不产生 DAV 生日。普通日期不会因主生日删除、重复同步或重启而重新变成生日；要将普通日期作为主生日，请在 Bonds 中选择生日类型。

合并期间的过期资料编辑不会复活来源联系人，也不会把已迁移资料挂回来源。若编辑提示原记录不可用，请刷新保留联系人的页面。活动付款人引用需要活动所属空间的编辑权限，包括联系人移动后留下的历史引用。

地址保留每一段居住历史，即使多个期间共用同一地址。API 响应提供 contact_address_id，更新或删除具体期间时将它作为同名查询参数传入。旧地址 ID 调用对单一期间仍然有效；存在多个期间而未指定时返回 409。删除只移除选定期间，地址在没有任何期间引用时才删除。地址文字仍然共享，居住日期与过去／当前状态分别属于各期间。