Skip to content

统一联系人名片与资料页 ​

配置与入口 ​

AppSettings.contactCard 由 @weq/service/contact-card 定义默认值、可选字段及顺序归一化。只保存内容可见性、正文顺序和群内可选内容顺序,不保存操作能力开关。未知、重复及已移除字段不会重新进入设置;局部设置补丁保留其他已选内容。

配置通过 bootstrap.getSettings/setContactCard 读写,复用全局配置备份、设置更新通知、设置搜索和恢复默认。设置页不查询真实账号资料;设置页的「预览」读取 account.getSelfProfile 用同一个名片组件渲染本人名片,读不到时给骨架,禁止任何虚构示例联系人。能量等级不属于展示字段,能量值保持独立。

MemberProfileCard 负责浮层定位与生命周期,ContactProfileSurface 负责内嵌资料页;身份、正文、群上下文及操作使用 contactProfile 下的共用组件。普通联系人浮层复用成员名片,不再并行维护一套正文。

行模型与容器(唯一实现) ​

  • components/contactProfile/ContactRow.tsx:唯一的数据行组件(ContactRow)、分区小标题(ContactSection)、技术详情折叠(ContactTechnicalDetails)、局部失败(ContactInlineError)、空态(ContactEmptyState)。label 固定 96px、值 13px 左对齐可换行、空值整行不渲染;旧组件的 .weq-profile-row 通过 profile-workspace.css 的容器归一化跟随同一网格,不再各自排版。
  • 名片壳与资料页壳共用身份区 ContactIdentity、操作区 ContactActions、页头 ProfilePageHeader(工具栏标题 + 右上关闭 + 身份/操作,文档流内、不覆盖章节标题;actions 可省略)。联系人资料页使用 layout="split" 和 ContactIdentity.cardBody:左侧沿用名片分行身份正文及显示设置,右侧每行一个操作;命名容器 contact-profile 宽度不足时整组操作移到身份区下方,横向自动换行并填满每行,不依赖浏览器窗口宽度。群资料页保留默认布局。
  • ProfileWorkspace 负责目录与章节:宽屏 weq-profile-directory 竖目录,窄屏为 weq-profile-directory-tabs 横向章节条。联系人传入 showTitle=false,不在正文重复标签标题;互动标识和画像用 ContactSection.prominent 输出同级标题及分割线,其余分区沿用普通小标题。
  • 样式归属:目录、工作区、行模型、共用技术详情组件只在 styles/profile-workspace.css;styles/contact-card.css 只保留名片壳、身份区、操作区、群上下文与设置页专属部分。当前状态复用聊天顶栏的 OnlineStatus;QQ、QID、UID、签名使用分行身份正文,沿用名片开关,四页正文不重复。联系人资料页不再挂载技术详情组件。
  • ProfileInlineField 共用群昵称、头衔、备注及分组的原行表单;QQProfileField 延迟挂载备注/分组/群名的在线状态读取,复用 qqWrite 与账号绑定。备注、群名和分组写入需读回确认才退出表单,失败保留草稿;分组使用下拉控件,群名称仅对群主/管理员提供,标题的资料导航行为不变。保存后刷新名片名称与群详情的独立查询缓存,不写入会话名称投影。
  • 编辑继续使用 ContactRow 的标签和值列,不替换标签或嵌入设置页行模型。ProfileEditorRow 在本人字段上下文中只输出内容控件,ProfileEditorAction 将已有提交按钮投到当前字段唯一的操作组,离开该上下文仍保留原设置表单。SelfProfileField 与 ProfileInlineField 共用 profile-field-editor.css 的控件及保存/取消样式;地区网格只包含地区选择,窄处按内容列宽换行。本人展示范围批量读取后以括号显示,点击才展开分段控件;范围草稿与内容草稿入口独立,共用一次保存和失败重试协调。

数据与加载 ​

  • 本地输入立即渲染;补充资料使用包含账号配置和目标身份的共享查询键。只读挂载使用 useQQWriteSession 的被动模式,不额外创建周期性能力轮询;编辑和互动继续使用实时读写会话。
  • 本地资料、云端名片名称、QQ 秀和装扮复用前端缓存及在途请求。资料读取支持可选的 expectedAccountUin/expectedAccountConfigId,保留旧调用兼容;服务端校验来源并拒绝切换后的迟到结果。名称投影不修改会话名称缓存。
  • peerStats.fields 可选择 level/likeCount,省略时仍读取两项;服务层分别调用已有指标缓存,单项失败不清空另一项成功结果。只显示等级时不发送获赞读取。
  • 标签目录、详细资料等根据启用内容挂载;同一接口被多个字段使用时复用查询结果。成功空目录与请求失败区分,零照片标签保留,照片续页只在进入相册后读取。
  • ProfileExtrasContent 和 ProfileDetailsContent 支持页内承接,ProfileExtraDialog 复用相同内容与查询。原有签名、问答、照片互动不另建协议或写入通道。
  • 私聊存在性优先使用完整目录和隐藏、历史及临时会话状态;必要时只读取会话边界。本群发言复用 browseConversation 的发送者过滤和游标分页。空间预览按点击延迟加载,复用空间读取和媒体网格,不预取评论或续页。

资料页章节采用共享目录容器,保留同一对象的章节、分页和滚动位置。lib/contactWorkspace.ts 定义基础内容页及旧导航映射:details/signatures/history/edit 归入 profile,portrait 归入 marks,questions 归入 personality。勋章墙章节及专用读取已撤下,不保留隐藏入口;遗留未知页签回到个人资料。旧教育、签名、历史章节只定位个人资料,不恢复已移除的独立入口;学校、签名、项目历史在实际触发点旁打开详情。本人编辑及对外展示设置与名片偏好分开。

本人身份复用 usePersonRelationship 判断,页头和区域名称为「我的资料」;目录使用 SELF_WORKSPACE_SECTIONS,依次为个人资料、群内资料、个性展示、礼物墙,不显示「与我的关系」。礼物墙复用 GiftWall 的收发切换与游标分页,首次选中才挂载,不在个性装扮中保留入口;全局搜索通过 self-profile 目标和 giftwall 标签直达本人资料。他人资料另有「与我的关系」,不展示本人的礼物;不适用的旧标签回到个人资料。本人浏览器回归 run-self-profile.mjs 同时覆盖礼物墙的深浅主题、宽窄屏及收发切换。

ProfileDisclosure 仅用于问答、本人编辑等仍需折叠的内容,收起保留现场并通过 TabActivity 暂停读取。互动画像随关系页直接挂载,不再折叠。ProfileExtraDialog 的教育和签名、共同群名单、项目历史使用显式锚点及 presentation=popover、anchorPlacement=side;QQ 秀展柜与本人头像历史同样支持锚点,保留原分页、互动与关闭行为。ContactDressRow 仅输出真实装扮素材,不复用带头像和 QQ 秀的个性主页舞台。

项目级历史(展示暂撤下) ​

当前 contactHistoryVisibility 中的固定常量 CONTACT_HISTORY_DISPLAY_ENABLED=false 统一关闭自建资料历史展示,不提供设置或隐藏菜单。ContactFieldHistoryProvider 只隔离旧上下文并透传正文,不挂载查询;字段可用性恒为假,字段按钮与汇总 ContactHistory 不挂载内容。QQ 原生的 profileExtras.signatureHistory 与 profileExtras.avatarHistory 保留原路径,不经过这个开关。已有存储、采集及迁移数据不变。

以下为保留但未挂到正式界面的实现说明;实现回归在测试中显式启用,正式关闭状态由 contact_history_visibility.test.ts 验证。

启用展示时,ContactFieldHistoryProvider 绑定账号、数据源、对象及可选成员 UID;ContactRow 和分区标题根据项目元数据在原位置挂历史按钮。弹窗内容默认不继承宿主的项目历史,打开其他联系人后由其资料 Provider 提供对应历史;Modal 与 OverlayLayer 复用纯上下文隔离组件。

  • history.fieldSummary 只在打开资料时读取本地历史,worker 每批最多处理 100 条该对象的记录,返回变化项目和是否仍在构建;构建中短间隔继续,完成后仅活动资料页每 30 秒校准一次。离开后停止。无关的大名单和照片正文不解压,不扫描整个账号。
  • projectContactHistoryFields 为已知资料返回逐项目投影:未返回字段与明确清空分开,生日/地区的部分返回保留既有子字段,集合按稳定身份归一;同来源的不同接口与查询分页共用字段流,不把本地和云端初值差异当作真实历史。群成员投影锁定群和 UID,成员换页不产生丢失或误判。
  • history.sqlite 的 field_progress、field_versions、field_changed 为可重建派生索引,保留 A→B→A,合并 UID/QQ 号后重新建立受影响的索引;不删除或改写原始 versions/content。变化标记单独保存,完成后的校准不再扫描整个项目版本表。索引格式独立管理,不改变产品版本号。
  • history.fieldVersions 按项目分页,在分页前按时间合并跨来源连续相同的值,合并首次/最近观察时间,保留 A→B→A;不对所有历史值做全局去重。服务端继续校验账号及数据源,前端缓存键包含完整身份,切群重建对应历史上下文。
  • 逐字段展示由 contactFieldPresentation 明确区分趋势、变更、条目比较和图片;生日/年龄、时间戳、状态码和身份编号不因底层是数字就画趋势。数值图表使用现有 D3,按实际观察时间绘制阶梯线,遇到未知值断开,旁列准确值及增减;只展示已加载范围,不额外读取全量历史。
  • 集合条目按业务身份比较,连续业务内容相同的旧快照只在展示层合并时间,保留原始资料;分页用「不再出现」而非断言删除。精选照片索引仍只存身份,打开该字段时按每批至多四个请求读取相同历史版本、补齐该版本已有图片引用,不查询当前相册或重写索引;补齐失败仍显示旧引用。后续分页失败保留已加载记录并原位重试。
  • 头像不以 URL 字符串判定变化:avatar_content 按原始观察版本保存已取得图片字节的 SHA-256,avatar_pending 记录尚无图片可核实的引用。运行时注入已有媒体缓存的只读获取器,不为资料采集批量下载头像;缺图或读取失败不会产生换头像标记。打开资料时按批补算可用缓存,补算成功后重建对应对象的字段索引;不联网反查旧头像,不假定旧 URL 现在返回的图片就是历史图片。原始 URL 始终留在原始观察中。

UID 仅在开启该字段时进入身份区。styles/contact-workspace.css 承担联系人资料页专属样式,不修改群资料页的布局。

ContactGroupWorkspace 通过绑定账号和数据源的 listUserGroups 分页读取本地成员记录,合并来源群,不遍历所有群成员;群名优先使用当前群资料、来源群和已有会话目录,缺失时显示群号。切群重新构造 profileContext,不改联系人及当前会话;成员行与本群发言、聊天分析共用该上下文。选择记忆按账号、数据源和 UID 隔离,内存有界;来源群优先于记忆。listUserGroups 保留旧调用,同时使用已有 scopedGroupRead 拒绝跨账号、跨数据源及迟到响应。

定向验证 ​

ProfileSummary 的属性对照直接衔接前面的关系字段,不创建独立分区、小标题或分割线。保留服务器标题和文案,无标题时使用「资料对比」,不将不同属性描述为共同点。profile_summary_ui.test.ts 与 run-profile-summary.mjs 覆盖该命名、原文保留及桌面/窄屏深浅主题下的连续排列。

家乡与共同点 ​

  • profileExtras.details 在公司、说明、邮箱、家乡 24002 与区县 20043 之外,请求旧学校文字 20021 与职业 27037(四字节大端整数);数值学校 ID 不作学校名称。所在地通过独立 profileExtras.region 复用 getCloudProfile 的 0xfe1_2 / bytes 20032,不与家乡混用。两条查询都复用既有账号、进程及目标校验。
  • profile-regions 子入口只输出浏览器可用的类型及 formatQqRegion,不引入传输、Node 模块或整份地区目录。零/空地区代码继续遍历下级,但不显示「不限」;全部未选返回 null,未返回与损坏值不伪造为有效资料。本人使用已有地区目录查询,其他人的 hometownText / regionText 在服务端用同一个函数生成。
  • ContactOnlineFields 仅在相应字段缺少本地内容时挂载在线补全,已有值立即显示。职业、学校和其他详细资料共享查询;所在地单独读取,学校文字缺失或旧资料失败时,独立读取 educationHistory 并跳过他人的隐藏经历。本地仅有学历时仍先显示,不等待学校补全。字段隐藏、预览、本地模式或离开章节时不新增对应读取。
  • ProfileSummary 复用 ContactRow、查询缓存和活动章节状态。ProfileExtrasService.similarity 通过原路由绑定账号配置、目标及进程,按业务和目标在途去重;所有结果再次检查来源及目标,不修改名称缓存或 QQ 数据库。
  • 共同点由 profile/similarity 直接请求 OidbSvc.0xcf4,不先请求资料卡聚合,也不在失败后切换到聚合。请求 from@1、to@2、qzone@4=true、newDna@6=false;响应 from@1/to@2 必须匹配双方,从 DnaInfo@14 的 wording@3 读取严格 UTF-8 主文案,source=dna。不推断相同属性,不使用新 DNA 的聊天小结或友谊时间线。该独立路径已在 macOS 当前真实登录态读取到非空文案;成功空列表、业务拒绝、错目标和损坏响应分别处理,不用空结果掩盖错误。
  • 资料卡聚合的请求/解析、专用 JCE 编解码、待确认签名登记及默认探测候选均已移出产品;没有隐藏开关或聚合回退。
  • 资料对比向所有有有效 QQ 号的他人联系人挂载,不按好友/非好友/关系未知或机器人/企业账号筛选;本人通过共享身份目录识别并排除,没有 QQ 身份的本地对象不发请求。当前 macOS 真实好友查询已通过正式服务返回非空文案。普通共同好友/共同群和互动画像不受影响;所有补全只读,均不写 QQ 原库或会话名称缓存。
  • 读取使用现有中央签名策略,不更换登录身份或伪装 Android,不恢复已撤下的好友扩展备注接口。

针对性协议用例在 profile_similarity.test.ts、profile_details.test.ts;sign_policy.test.ts 保证已撤下聚合不保留策略或默认探测入口。账号绑定和在途检查沿 profile_extras.test.ts 与 profile_extras_router.test.ts;界面/路由回归为 profile_summary_ui.test.ts、contact_workspace_sections.test.ts 和 contact_workspace_model.test.ts,包含已撤下勋章墙的导航和路由不存在、旧页签回退检查。浏览器入口 run-profile-summary.mjs 使用既有 Playwright/浏览器环境变量,以 WEQ_PROFILE_APPROVED_QA 保存证据,覆盖本人/他人格式一致、无勋章入口或查询、所有他人联系人的资料对比与本人排除、空态及失败重试,退出时关闭自身服务器及浏览器。

服务测试覆盖字段默认、归一化、排序、持久化、备份恢复及等级与获赞的实际读取选择;渲染测试覆盖名片浮层、头像补全、来源隔离、备注及群资料编辑和既有互动能力。

浏览器回归入口为 apps/desktop/test/browser/run-contact-card.mjs。通过 WEQ_PLAYWRIGHT_IMPORT、WEQ_BROWSER_EXECUTABLE 复用已有浏览器;WEQ_CONTACT_CARD_QA 指定截图和查询记录目录。脚本使用合成资料,禁止外网请求,退出时关闭自身浏览器和 Vite 服务。WEQ_CONTACT_CARD_BASELINE=1 可加载重构前的名片组件作同夹具对照。

浏览器记录用于核对真实首帧、冷开与缓存复用、可选查询及响应式布局,不等同于真实 QQ 网络耗时或长期性能验收。

四页资料工作区回归入口为 apps/desktop/test/browser/run-contact-workspace.mjs,沿用相同浏览器环境变量,以 WEQ_CONTACT_WORKSPACE_QA 指定截图和检查记录目录;覆盖教育/共同群/项目历史旁侧弹窗、QQ 秀顺序与对齐、紧凑标识、常驻画像、切群及所选群发言、四种宽度与深浅主题。模型与页内测试为 contact_workspace_model.test.ts、contact_workspace_sections.test.ts、contact_field_history_ui.test.ts;项目历史 worker 回归在 service 的 contact_field_history.test.ts,原始留存回归在 contact_history.test.ts。

原行编辑定向测试为 profile_inline_field.test.ts 与 group_member_inline_edit.test.ts;浏览器入口 apps/desktop/test/browser/run-profile-inline.mjs 使用同一运行时环境变量,以 WEQ_PROFILE_INLINE_QA 指定截图目录,覆盖备注保存/清空/取消、分组、群名称、失败草稿及深浅主题窄屏布局,所有写入均为合成桩。

本人字段与范围回归为 self_profile_field.test.ts、profile_display_settings.test.ts;run-profile-field-editor.mjs 用 WEQ_PROFILE_FIELD_QA 输出截图,覆盖 1180/390/320px 深浅主题的标签节点及样式稳定、输入/地区/多行布局、统一操作尺寸及内容旁间距、同行居中、仅改范围、两种编辑顺序、部分成功重试和键盘焦点。useProfileFieldEscape 在捕获阶段让当前上层资料内的编辑优先处理 Esc,焦点移到空白后也可取消最近的编辑,不穿透新打开的详情,不取消在途保存;profile_field_escape.test.ts 覆盖这些顺序。范围专用行通过 rangeOnly 省略正文,只显示一份摘要。run-self-profile.mjs 与 run-profile-display.mjs 继续验证现有本人资料和展示设置路径。

当前文档对应 v2.7.4 · 已发布内容以 CHANGELOG 为准