邮件联系人名片与 IM 资料需求说明
版本：V1.1 · 更新：2026 年 10 月 8 日 · 状态：开发评审稿。
本文说明桌面邮件阅读区的联系人点击功能，重点是邮箱与 IM 账号匹配后的用户详情卡。文中区分“已确认规则”“当前原型”“待确认项”，开发不可把禁用占位当作已实现业务，也不可自行补齐待确认规则。
一、目标与范围
用户在阅读邮件时，无需离开邮箱即可查看发件人或收件人的身份资料、复制邮箱地址；邮箱匹配到 IM 账号时，可进一步查看协同用户详情。
本次范围包括联系人入口、邮箱名片、IM 详情卡、邮箱复制提示、加载与异常状态。未匹配 IM 的联系人需要区分是否已添加为邮件联系人，这是已提出的展示需求，尚未实现两态分支。
联系人名片的添加星标、移入免提醒、邮件特别提醒不在系统规划范围内：不展示入口，不保留禁用占位，也不列为后续待开发项。参考截图中的这些功能不纳入需求。
本次不实现真实发信、聊天、语音、视频、联系人维护或权限系统。日程邀请卡片、日历联动、邮件列表原有星标展示和移动端维持原有行为。截图仅用于结构参考，高保真视觉由 UI 设计师负责。
二、入口与打开方式
- 在桌面邮件详情头部，点击发件人的头像、名称或邮箱区域，打开对应邮箱名片。
- 点击收件人邮箱，打开该收件人的邮箱名片。查询目标是被点击的地址，不是当前登录邮箱或邮件中其他人的地址。
- 名片锚定点击位置；打开名片不改变当前邮件选择和阅读位置。
- 匹配到 IM 后，点击名片头部打开二级 IM 详情卡。邮箱复制按钮是独立操作，不触发详情展开。
- 详情优先显示在名片右侧，空间不足时自动避让至左侧或调整位置，内容不能超出视口而不可访问。
- Escape 先关闭最上层详情并返回其触发入口；继续关闭名片时返回原联系人入口。点击外部区域按 Popover 的标准行为关闭。
当前入口不包含邮件正文中的任意地址或 ICS 卡片内部的组织者／参与人。未来若扩展这些入口，应复用同一套组件，不另建名片逻辑。
三、身份判断：两个维度不可混用
“是否匹配 IM”与“是否已添加为邮件联系人”是独立状态：未匹配 IM 的地址也可能已保存为邮件联系人；匹配 IM 也不等于已保存为邮件联系人。
| IM 匹配结果 | 邮件联系人状态 | 展示结果 | 当前交付状态 |
|---|---|---|---|
| 匹配成功 | 独立判断 | 邮箱名片，可展开 IM 用户详情 | 名片与详情已实现；联系人保存状态未接入 |
| 明确未匹配 | 未添加 | 未添加邮件联系人名片 | 两态展示待实现 |
| 明确未匹配 | 已添加 | 已添加邮件联系人名片 | 两态展示待实现 |
查询中或失败 | 不能据此推断 | 加载或错误状态，不显示“未匹配”结论 | 加载、错误及重试已实现 |
IM 匹配规则
- 当前系统约定邮箱地址与 IM 账号一对一。匹配成功须返回唯一 IM 身份，而不只是“存在账号”的布尔值。
- 按被点击的明确地址查询；不能按发件人名称、相似地址、头像或邮件正文推断身份。邮件显示名称不能作为可信 IM 资料来源。
- 当前原型仅去除地址首尾空白后做精确匹配，不推断大小写等价、邮箱别名、点号或
+tag。生产环境地址规范化策略需单独确认。 - 返回零个账号是“未匹配”；超时、异常或无法访问是“查询失败／不可用”，不得伪装成未匹配。出现多个匹配结果属于违反一对一约束，不得取第一条后继续展示。
- 用户快速切换邮件或点击另一地址时，旧请求不能覆盖新地址的结果。缓存必须按目标地址隔离；生产环境还需按用户及允许访问的身份范围隔离。
四、未匹配 IM 的两种名片
两种名片均显示联系人名称、完整邮箱的可复制入口和头像；不显示 IM 用户详情入口。
| 状态 | 主操作区 | 更多菜单 |
|---|---|---|
未添加邮件联系人 | 添加为邮件联系人、写邮件、更多 | 查看往来邮件 |
已添加邮件联系人 | 写邮件、往来邮件、更多 | 编辑联系人、删除联系人 |
此表整理自两张参考截图，并已按产品确认去除不规划的功能，描述目标展示，不代表当前原型已按此分支渲染。添加／删除是否在原型中切换状态、联系人归属范围及其他操作的实际业务行为仍待确认；未确认前保持禁用，不做虚假成功提示。
五、匹配 IM 后的用户详情卡
保留“邮箱名片 → 点击头部 → IM 详情卡”的两级结构；本次替换的是第二级详情，不是整个邮箱界面。
布局顺序
- 右上角更多入口。
- 居中圆形头像，下方居中显示用户姓名。
- 分隔线下依次为昵称、teleConnect+ ID、电话号码、邮箱、部门。字段名称左对齐，字段值右对齐。
- 独立备注行：左侧“备注”，右侧“添加备注”。
- 底部三列入口：消息、语音、视频；每列图标在上、文案在下。
当前原型详情卡宽 320px，采用 shadcn Neutral 浅色、统一字体和语义令牌；不复制参考图品牌、人物照片或颜色。原型没有头像资源时使用统一人物图标。性别标识不在当前数据模型与本次要求中，不自行添加。
字段来源与缺失处理
| 展示字段 | 来源及规则 | 缺失／过长处理 |
|---|---|---|
| 头像、姓名 | 匹配到的 IM 用户资料，非邮件显示名 | 头像缺失显示默认人物图标；姓名允许换行 |
昵称、电话号码 | IM 用户可选资料，不用姓名代填昵称，不伪造电话 | 缺失显示“未提供”；过长单行截断 |
teleConnect+ ID | 协同账号展示标识；原型暂显示模拟 IM ID | 生产展示字段与内部主键的映射待确认 |
| 邮箱 | 匹配账号的完整邮箱，点击复制 | 可截断显示，但复制、可访问名称与完整提示保留原地址 |
| 部门 | IM 资料的部门信息；原型为演示部门 | 过长单行截断并保留完整提示；生产缺失情况待确认 |
备注、更多、消息、语音、视频目前全部禁用。不自动创建聊天、不发起通话、不读写备注。当前详情卡不再保留旧版“往来邮件／查看日程”、企业字段或底部“写邮件”按钮；邮件相关操作仍在外层名片。
六、邮箱点击复制
- 邮箱名片和 IM 详情中的地址均支持复制。复制动作只写入剪贴板，不发信、不打开邮箱程序、不关闭名片。
- 可用鼠标点击、Enter 或 Space 操作，触控目标至少 44px。复制按钮不能嵌套在打开详情的按钮中。
- 只有浏览器确认写入成功后才显示气泡：“邮箱地址复制成功”。英文界面对应“Email address copied”。
- 写入失败、剪贴板能力不可用或权限受限时显示：“复制失败，请检查浏览器剪贴板权限后重试”。不能先报成功，也不能静默失败。
- 即使地址被视觉截断，也必须复制完整地址，不含省略号、按钮提示文案或多余显示标签。
- 请求进行中防止重复提交；完成后保留邮箱按钮焦点。提示短暂展示，不阻断继续阅读，也不因重复点击无限堆叠。
七、数据与组件实现约束
当前原型已有接口
resolveIMContact(email: string): Promise<IMContact | null>
interface IMContact {
id: string
email: string
name: string
nickname?: string
phoneNumber?: string
jobTitleKey: "designer" | "prototypeRole"
departmentKey: "productDepartment"
organizationKey: "demoCompany"
}
这是静态原型的模型与 repository 接口，不是生产 HTTP 契约。jobTitleKey 等键仅服务演示文案，生产数据不应照抄这些固定枚举；也不能将 im-you 等演示 ID 当作实际 teleConnect+ ID。
生产实现需同时提供 IM 匹配结果与邮件联系人状态，不能让前端通过按钮文案猜测是否已添加。具体接口路径、联系人 ID、权限过滤、字段可见性及多邮箱下的联系人归属尚未锁定；应由开发与产品确认后定稿。
当前复用 MailContactTrigger、ContactIdentity、IMProfile、CopyEmail；联系人数据只通过 repository 与查询层进入视图，加载和异常使用统一 AsyncState。资料卡使用批准的 Popover、Avatar、Button 与 Dropdown Menu，不复制原始组件或引入另一套 UI。
界面标签、提示和可访问名称支持中文／英文；姓名与邮箱等用户原始资料保持原值。卡片的邮箱、电话和部门仅来自用户有权查看的资料，不把“已匹配”当作可以展示全部个人资料的授权。本原型不建设服务端或持久化。
八、验收用例
- 点击发件人的头像／名称／地址和收件人地址，打开的始终是该地址对应的名片，邮件选择与 URL 不因打开名片而变化。
- 查询中显示加载；查询异常显示错误并可重试，不能显示“未匹配”作为异常兜底。
- 未匹配 IM 时没有 IM 详情入口；未来接入联系人状态后，两种名片按第四节显示，不用 IM 匹配状态替代保存状态。
- 匹配 IM 时显示真实匹配身份；点击头部展开新版详情，资料字段顺序与第五节一致。
- 头像、昵称、电话缺失时按规定降级，不出现伪造资料或破图；长邮箱及部门不撑破卡片。
- 分别在邮箱名片和 IM 详情复制地址，得到完整邮箱并显示成功气泡；复制不触发资料展开，不关闭卡片。
- 剪贴板拒绝／不可用时明确提示失败，不出现成功提示。
- 快速切换联系人或邮件，不串用姓名、资料或旧请求结果；重新打开同一地址可复用有效缓存。
- 键盘可打开、复制、逐层关闭；关闭回到对应入口，复制后焦点保留；所有可操作目标至少 44px。
- 在 1280／1440／1920px 桌面视口检查弹卡边界、左右避让和长字段；满足浅色 AA 对比度及 reduced motion 规范。
- 中英文界面标签和复制反馈正确，邮件正文及原始联系人资料不被翻译或改写。
- 备注、更多、消息、语音、视频及外层未实现操作仍禁用；不发送真实邮件或建立通信、不持久化。
- 匹配或未匹配 IM 的联系人名片均不出现添加星标、移入免提醒、邮件特别提醒入口；此调整不移除邮件列表原有星标标记。
原型可用样本：林语 linyu@example.com 与原型用户 you@telemail.example 已匹配 IM；teleMail 团队 hello@telemail.example 与 Alex Morgan alex@example.com 未匹配。当前没有“未添加／已添加邮件联系人”两态样本，不得把这些未匹配样本直接判为已添加。
九、开发前待确认
- 未匹配 IM 时，“添加／删除邮件联系人”是否只做会话内状态切换，还是继续禁用展示？其他操作的业务闭环另行确认。
- 邮件联系人属于协同用户统一通讯录，还是具体连接邮箱账号？多个邮箱下如何读取和维护保存状态？
- 匹配 IM 的用户已保存为邮件联系人时，外层名片的操作区是否也需要切换？
- 正式 teleConnect+ 展示 ID、昵称、电话、部门、头像的来源和权限规则是什么？空资料、隐藏资料与无访问权是否需要不同文案？
- 生产地址规范化、账号停用／解除绑定及缓存失效策略是什么？
- 备注、更多菜单、消息、语音、视频开放时的菜单项、权限与失败反馈是什么？
以上事项未确认前，不自行推断或扩展。当前可以依照已确认部分开发资料展示与复制；联系人维护和真实通信另行评审。