feat: customer full-field display (raw_json + cloud-matching list + all-fields drawer)

Backend: - CustomerOut now exposes raw_json (verbatim upstream friend record) so the frontend can render every 云客 field without per-field structured columns. - The verbatim blob round-trips via from_attributes; no model change needed. Frontend: - CustomerList table mirrors the 云客客户列表 column set (头像/微信昵称/微信号/ 备注/真实姓名/手机/性别/地区/描述/销售员工/部门/来源/添加方式/添加时间/最近聊天/消息数/渠道). A readField helper reads the structured column first and falls back to raw_json.<camelCase>. - Row click opens an all-fields drawer (right side) rendering EVERY field of the record with Chinese labels, grouped (基本信息/联系方式/归属员工与部门/时间与来源/消息统计/好友状态/其他). Timestamps format to local datetime, flags render 是/否, image URLs render as el-image thumbnails, empty values show —. - New src/utils/customerFields.ts holds the camelCase→中文 label map, the structured-column alias map, group definitions, and value-type formatters; unknown raw_json keys auto-flow into an 其他 section so new upstream fields surface without code changes. - Drawer 查看聊天记录 action navigates to /chat/:channel/:ownerId/:talkerId (owner_account_id + friend_id + channel), preserving the existing path. Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-01 17:24:38 +08:00
parent 0df53c6b1a
commit e5af1a2bc2
5 changed files with 588 additions and 25 deletions
@@ -0,0 +1,275 @@
+/**
+ * Chinese-label map + grouping for the Customer all-fields drawer.
+ *
+ * The 云客 upstream friend record (`Customer.raw_json`) carries ~60 camelCase
+ * fields (see docs/superpowers/specs/2026-08-01-yunke-data-dictionary.md §2).
+ * This module turns that blob into a labeled, grouped, render-ready structure
+ * for the drawer, with structured columns preferred over the verbatim value
+ * when both exist (the structured column is type-normalized on ingest).
+ *
+ * Unknown keys (anything not in the label map) fall back to the raw key, so a
+ * new field added upstream still shows up in 其他 instead of disappearing.
+ */
+import type { Customer } from '@/api/types'
+import { formatTime } from './format'
+
+/** camelCase raw_json key → 中文 label. Missing keys fall back to the key. */
+export const CUSTOMER_FIELD_LABELS: Record<string, string> = {
+  // 基本信息
+  friendWxId: '客户微信ID',
+  friendWxNickname: '微信昵称',
+  friendWxAlias: '微信号',
+  friendWxRemark: '备注',
+  alias: '微信号(归属)',
+  realName: '真实姓名',
+  gender: '性别',
+  region: '地区',
+  description: '描述',
+  friendHeadImageUrl: '头像',
+  headImg: '头像(备用)',
+  // 联系方式
+  phone: '手机号',
+  wechatPhone: '微信手机号',
+  friendWxPhone: '好友手机号',
+  // 归属员工与部门
+  saleName: '销售员',
+  userName: '员工姓名',
+  userId: '员工ID',
+  wxId: '归属微信ID',
+  ownerWchatId: '归属微信号',
+  deptName: '部门',
+  deptRouteName: '部门路径',
+  deptRoute: '部门路径编码',
+  // 时间与来源
+  lastChatTime: '最近聊天时间',
+  createTime: '创建时间',
+  addTime: '添加时间',
+  addType: '添加方式',
+  fromType: '客户来源',
+  // 消息统计
+  sendNum: '发送消息数',
+  receiveNum: '接收消息数',
+  messageCount: '消息总数',
+  // 好友状态
+  friendState: '好友状态',
+  friendType: '好友类型',
+  friendTypeYunke: '云客好友类型',
+  deleteFlag: '删除标记',
+  isBlock: '是否拉黑',
+  isReFriend: '是否重复好友',
+  isQyFriend: '是否企微好友',
+  isSale: '是否销售好友',
+  // 其他 / 内部
+  version: '版本号',
+  companyCode: '公司编码',
+  encryptUsername: '加密用户名',
+  friendWxNicknameReverse: '昵称倒排(检索用)',
+  verifyFlag: '验证标记',
+}
+
+/**
+ * raw_json camelCase key → the structured snake_case column that mirrors it.
+ * When a structured column is populated we prefer it (type-normalized); we
+ * fall back to the verbatim raw_json value otherwise.
+ */
+const STRUCTURED_ALIAS: Record<string, keyof Customer> = {
+  friendWxId: 'friend_id',
+  friendWxNickname: 'friend_nickname',
+  friendWxRemark: 'friend_remark',
+  realName: 'real_name',
+  phone: 'phone',
+  region: 'region',
+  saleName: 'sale_name',
+  deptName: 'dept_name',
+  friendHeadImageUrl: 'head_image_url',
+  lastChatTime: 'last_chat_time',
+  messageCount: 'message_count',
+  version: 'version',
+}
+
+/** Fields whose value is an image URL → render as a thumbnail. */
+const IMAGE_KEYS = new Set(['friendHeadImageUrl', 'headImg'])
+
+/** Fields whose value is a millisecond epoch → format to local datetime. */
+const TIMESTAMP_KEYS = new Set(['lastChatTime', 'createTime', 'addTime'])
+
+/** Fields whose value is a gender code (0/1/2). */
+const GENDER_KEYS = new Set(['gender'])
+
+/** Fields whose value is a boolean / 0|1 flag → render 是/否. */
+const BOOLEAN_KEYS = new Set([
+  'isBlock',
+  'isReFriend',
+  'isQyFriend',
+  'isSale',
+])
+
+/** Drawer sections, rendered in this order. */
+export interface CustomerFieldGroup {
+  title: string
+  /** camelCase raw_json keys to surface in this section. */
+  keys: string[]
+}
+
+export const CUSTOMER_FIELD_GROUPS: CustomerFieldGroup[] = [
+  {
+    title: '基本信息',
+    keys: [
+      'friendWxId',
+      'friendWxNickname',
+      'friendWxAlias',
+      'friendWxRemark',
+      'realName',
+      'gender',
+      'region',
+      'description',
+      'friendHeadImageUrl',
+      'headImg',
+    ],
+  },
+  {
+    title: '联系方式',
+    keys: ['phone', 'wechatPhone', 'friendWxPhone'],
+  },
+  {
+    title: '归属员工与部门',
+    keys: [
+      'saleName',
+      'userName',
+      'userId',
+      'wxId',
+      'ownerWchatId',
+      'deptName',
+      'deptRouteName',
+      'deptRoute',
+    ],
+  },
+  {
+    title: '时间与来源',
+    keys: ['lastChatTime', 'createTime', 'addTime', 'addType', 'fromType'],
+  },
+  {
+    title: '消息统计',
+    keys: ['sendNum', 'receiveNum', 'messageCount'],
+  },
+  {
+    title: '好友状态',
+    keys: [
+      'friendState',
+      'friendType',
+      'friendTypeYunke',
+      'deleteFlag',
+      'isBlock',
+      'isReFriend',
+      'isQyFriend',
+      'isSale',
+    ],
+  },
+]
+
+/** Every key already surfaced via a group (so 其他 can skip duplicates). */
+const KNOWN_KEYS = new Set(CUSTOMER_FIELD_GROUPS.flatMap((g) => g.keys))
+
+/** Resolve the 中文 label for a raw_json key (falls back to the key). */
+export function fieldLabel(key: string): string {
+  return CUSTOMER_FIELD_LABELS[key] ?? key
+}
+
+/**
+ * Read a field value with structured-column preference.
+ * Returns the verbatim raw_json value when no structured column maps.
+ */
+export function readField(c: Customer, camelKey: string): unknown {
+  const alias = STRUCTURED_ALIAS[camelKey]
+  if (alias) {
+    const v = c[alias]
+    if (v !== null && v !== undefined) return v
+  }
+  return c.raw_json?.[camelKey]
+}
+
+/** A single field prepared for drawer rendering. */
+export interface DisplayField {
+  key: string
+  label: string
+  /** Raw value (for text fallback). */
+  value: unknown
+  /** How the template should render it. */
+  render: 'image' | 'time' | 'gender' | 'bool' | 'text' | 'empty'
+  /** Pre-formatted text (for time/gender/bool/text kinds). Empty for image/empty. */
+  text: string
+}
+
+/** gender code (0/1/2) → label. Other codes pass through as `性别 N`. */
+export function genderLabel(v: unknown): string {
+  if (v === 0 || v === '0') return '未知'
+  if (v === 1 || v === '1') return '男'
+  if (v === 2 || v === '2') return '女'
+  return `性别 ${String(v)}`
+}
+
+/** 0|1|true|false → 是/否; other ints pass through so info isn't hidden. */
+export function yesNoLabel(v: unknown): string {
+  if (v === true || v === 1 || v === '1') return '是'
+  if (v === false || v === 0 || v === '0') return '否'
+  return String(v)
+}
+
+/** Classify + format a single field for the drawer. */
+export function toDisplayField(c: Customer, camelKey: string): DisplayField {
+  const value = readField(c, camelKey)
+  const label = fieldLabel(camelKey)
+  if (value === null || value === undefined || value === '') {
+    return { key: camelKey, label, value, render: 'empty', text: '' }
+  }
+  if (IMAGE_KEYS.has(camelKey) && typeof value === 'string') {
+    return { key: camelKey, label, value, render: 'image', text: '' }
+  }
+  if (TIMESTAMP_KEYS.has(camelKey) && typeof value === 'number') {
+    return { key: camelKey, label, value, render: 'time', text: formatTime(value) }
+  }
+  if (GENDER_KEYS.has(camelKey)) {
+    return { key: camelKey, label, value, render: 'gender', text: genderLabel(value) }
+  }
+  if (BOOLEAN_KEYS.has(camelKey)) {
+    return { key: camelKey, label, value, render: 'bool', text: yesNoLabel(value) }
+  }
+  return { key: camelKey, label, value, render: 'text', text: String(value) }
+}
+
+/**
+ * Build the grouped display model for a customer.
+ *
+ * Each known group only includes fields that have a value (empty ones are
+ * dropped to keep the drawer compact). A trailing 其他 section collects every
+ * raw_json key not already surfaced, so new upstream fields show up
+ * automatically instead of being silently hidden.
+ */
+export interface CustomerFieldSection {
+  title: string
+  fields: DisplayField[]
+}
+
+export function buildCustomerSections(c: Customer): CustomerFieldSection[] {
+  const sections: CustomerFieldSection[] = CUSTOMER_FIELD_GROUPS.map((g) => ({
+    title: g.title,
+    fields: g.keys
+      .map((k) => toDisplayField(c, k))
+      .filter((f) => f.render !== 'empty'),
+  }))
+
+  // 其他: every raw_json key not already shown, in original insertion order.
+  const raw = c.raw_json ?? {}
+  const others: DisplayField[] = []
+  for (const key of Object.keys(raw)) {
+    if (KNOWN_KEYS.has(key)) continue
+    const f = toDisplayField(c, key)
+    if (f.render === 'empty') continue
+    others.push(f)
+  }
+  if (others.length > 0) {
+    sections.push({ title: '其他字段', fields: others })
+  }
+
+  return sections.filter((s) => s.fields.length > 0)
+}