完善 value_rank 社交图设计并落地 @ 结构化存储

- messages 表新增 mentioned_user_ids 字段设计，使用 JSON 数组字符串存储被@用户清单 - 新增社交图相关表设计：t_message_mentions、t_social_edges_daily、t_value_rank_social_daily - 增加迁移脚本 20260421_add_mentions_and_social_graph_tables.sql，支持现网平滑升级 - 改造 MessageStorageDB 入库流程：解析 msg_source.atuserlist 并写入 mentioned_user_ids - 更新 value_rank README：补充社交图数据链路、可产出图表及实现说明
2026-04-21 13:34:19 +08:00
parent dfa17c5f95
commit 2730595a88
4 changed files with 214 additions and 9 deletions
--- a/db/message_storage.py
+++ b/db/message_storage.py
@@ -2,6 +2,8 @@

 from datetime import datetime
 import json
+import re
+import xml.etree.ElementTree as ET
 from typing import Dict, List, Optional

 from db.base import BaseDBOperator
@@ -39,15 +41,17 @@ class MessageStorageDB(BaseDBOperator):

        # 尽可能保存完整原始负载：优先使用对象自带序列化能力，其次兜底到 __dict__。
        raw_payload = self._serialize_raw_payload(msg)
+        # 在入库阶段结构化提取被@清单，避免后续统计每次都回扫原始包。
+        mentioned_user_ids_json = self._extract_mentioned_user_ids(msg)

        sql_with_raw_payload = """
        INSERT INTO messages (
            group_id, timestamp, sender, content, message_type,
-            attachment_url, message_id, message_xml, raw_payload, message_thumb
+            attachment_url, message_id, message_xml, raw_payload, mentioned_user_ids, message_thumb
        )
-        VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+        VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
        """
-        params_with_raw_payload = (*base_params[:8], raw_payload, base_params[8])
+        params_with_raw_payload = (*base_params[:8], raw_payload, mentioned_user_ids_json, base_params[8])
        if self.execute_update(sql_with_raw_payload, params_with_raw_payload):
            return True

@@ -87,6 +91,48 @@ class MessageStorageDB(BaseDBOperator):
            # 最后的保底策略：即使序列化失败，也确保字段有可追溯文本，避免丢失原始上下文。
            return str(msg)

+    def _extract_mentioned_user_ids(self, msg: WxMessage) -> str:
+        """从消息中提取被@用户ID列表，并返回 JSON 数组字符串。
+
+        解析策略：
+        1. 优先从 `msg.msg_source` 的 XML 里读取 `atuserlist` 节点；
+        2. 若 XML 解析失败，则退化为正则提取 `atuserlist` 文本；
+        3. 去重并过滤空值，保证输出稳定。
+
+        返回值示例：`["wxid_a","wxid_b"]`
+        """
+        raw_xml = str(getattr(msg, "msg_source", "") or "")
+        if not raw_xml:
+            return "[]"
+
+        at_user_list_text = ""
+        try:
+            root = ET.fromstring(raw_xml)
+            node = root.find(".//atuserlist")
+            if node is not None and node.text:
+                at_user_list_text = str(node.text).strip()
+        except Exception:
+            # 兼容异常格式 XML，采用正则兜底，确保尽量不丢数据。
+            match = re.search(r"<atuserlist><!\[CDATA\[(.*?)\]\]></atuserlist>", raw_xml, flags=re.IGNORECASE | re.DOTALL)
+            if match:
+                at_user_list_text = str(match.group(1) or "").strip()
+
+        if not at_user_list_text:
+            return "[]"
+
+        # 微信 atuserlist 常见分隔符为 ','，但实际环境可能混入 ';' 或空白，这里统一兼容。
+        raw_ids = re.split(r"[,\s;]+", at_user_list_text)
+        seen = set()
+        result = []
+        for uid in raw_ids:
+            normalized_uid = str(uid or "").strip()
+            if not normalized_uid or normalized_uid in seen:
+                continue
+            seen.add(normalized_uid)
+            result.append(normalized_uid)
+
+        return json.dumps(result, ensure_ascii=False)
+
    def get_recent_messages(self, group_id: str, hours_ago: int = 8, min_content_length: int = 6) -> List[Dict]:
        """获取最近的消息"""
        sql = """
--- a/db/scripts/init.sql
+++ b/db/scripts/init.sql
@@ -40,6 +40,7 @@ create or replace table message_archive.messages
    message_id     varchar(32)  null comment '消息 id',
    message_xml    text         null comment '消息 xml 部分',
    raw_payload    longtext     null comment 'API 原始消息完整负载（完整序列化数据）',
+    mentioned_user_ids longtext null comment '消息中被@用户ID清单（JSON数组字符串）',
    message_thumb  longtext     null comment '视频或图片消息的缩略图路径',
    image_path     varchar(255) null comment '图片URL路径'
 )
@@ -60,6 +61,49 @@ create or replace index idx_message_type
 create or replace index messages_message_id_index
    on message_archive.messages (message_id);

+create or replace table message_archive.t_message_mentions
+(
+    id                bigint auto_increment
+        primary key,
+    message_id        varchar(32)                           not null comment '原始消息ID',
+    group_id          varchar(100)                          not null comment '群ID',
+    sender_id         varchar(100)                          not null comment '发送者ID（@发起人）',
+    mentioned_user_id varchar(100)                          not null comment '被@用户ID',
+    stat_date         date                                  not null comment '统计日期',
+    msg_time          datetime                              not null comment '消息时间',
+    create_time       datetime default current_timestamp()  null comment '创建时间',
+    constraint uk_message_sender_mentioned
+        unique (message_id, sender_id, mentioned_user_id)
+)
+    comment '消息@关系明细表';
+
+create or replace index idx_group_date
+    on message_archive.t_message_mentions (group_id, stat_date);
+
+create or replace index idx_mentioned_group_date
+    on message_archive.t_message_mentions (mentioned_user_id, group_id, stat_date);
+
+create or replace table message_archive.t_social_edges_daily
+(
+    id                bigint auto_increment
+        primary key,
+    stat_date         date                                 not null comment '统计日期',
+    group_id          varchar(100)                         not null comment '群ID',
+    from_user_id      varchar(100)                         not null comment '互动发起方',
+    to_user_id        varchar(100)                         not null comment '互动接收方',
+    mention_count     int      default 0                   not null comment '@次数',
+    reply_count       int      default 0                   not null comment '回复次数（预留）',
+    interaction_score decimal(10, 2) default 0.00         not null comment '互动强度分（可用于关系网权重）',
+    create_time       datetime default current_timestamp() null comment '创建时间',
+    update_time       datetime default current_timestamp() null on update current_timestamp() comment '更新时间',
+    constraint uk_day_group_edge
+        unique (stat_date, group_id, from_user_id, to_user_id)
+)
+    comment '社交关系日边表（用于关系网和搭子榜）';
+
+create or replace index idx_group_day_score
+    on message_archive.t_social_edges_daily (group_id, stat_date, interaction_score);
+
 create or replace table message_archive.speech_counts
 (
    id       int auto_increment comment '自增主键ID'
--- a/db/scripts/migrations/20260421_add_mentions_and_social_graph_tables.sql
+++ b/db/scripts/migrations/20260421_add_mentions_and_social_graph_tables.sql
@@ -0,0 +1,50 @@
+-- 消息表增加被@清单字段（JSON 数组字符串）
+ALTER TABLE message_archive.messages
+    ADD COLUMN IF NOT EXISTS mentioned_user_ids LONGTEXT NULL COMMENT '消息中被@用户ID清单（JSON数组字符串）' AFTER raw_payload;
+
+-- 消息@关系明细表
+CREATE TABLE IF NOT EXISTS message_archive.t_message_mentions (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    message_id VARCHAR(32) NOT NULL COMMENT '原始消息ID',
+    group_id VARCHAR(100) NOT NULL COMMENT '群ID',
+    sender_id VARCHAR(100) NOT NULL COMMENT '发送者ID（@发起人）',
+    mentioned_user_id VARCHAR(100) NOT NULL COMMENT '被@用户ID',
+    stat_date DATE NOT NULL COMMENT '统计日期',
+    msg_time DATETIME NOT NULL COMMENT '消息时间',
+    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    UNIQUE KEY uk_message_sender_mentioned (message_id, sender_id, mentioned_user_id),
+    KEY idx_group_date (group_id, stat_date),
+    KEY idx_mentioned_group_date (mentioned_user_id, group_id, stat_date)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='消息@关系明细表';
+
+-- 社交关系日边表（用于关系网和搭子榜）
+CREATE TABLE IF NOT EXISTS message_archive.t_social_edges_daily (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    stat_date DATE NOT NULL COMMENT '统计日期',
+    group_id VARCHAR(100) NOT NULL COMMENT '群ID',
+    from_user_id VARCHAR(100) NOT NULL COMMENT '互动发起方',
+    to_user_id VARCHAR(100) NOT NULL COMMENT '互动接收方',
+    mention_count INT NOT NULL DEFAULT 0 COMMENT '@次数',
+    reply_count INT NOT NULL DEFAULT 0 COMMENT '回复次数（预留）',
+    interaction_score DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '互动强度分（可用于关系网权重）',
+    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    UNIQUE KEY uk_day_group_edge (stat_date, group_id, from_user_id, to_user_id),
+    KEY idx_group_day_score (group_id, stat_date, interaction_score)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='社交关系日边表（用于关系网和搭子榜）';
+
+-- Value Rank 社交日汇总表（个人维度）
+CREATE TABLE IF NOT EXISTS message_archive.t_value_rank_social_daily (
+    id BIGINT PRIMARY KEY AUTO_INCREMENT,
+    stat_date DATE NOT NULL COMMENT '统计日期',
+    group_id VARCHAR(100) NOT NULL COMMENT '群ID',
+    user_id VARCHAR(100) NOT NULL COMMENT '用户ID',
+    mentioned_count INT NOT NULL DEFAULT 0 COMMENT '被@次数（入度）',
+    mention_others_count INT NOT NULL DEFAULT 0 COMMENT '@他人次数（出度）',
+    unique_interactors INT NOT NULL DEFAULT 0 COMMENT '与其发生互动的去重人数',
+    interaction_score DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '社交影响力分',
+    create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+    UNIQUE KEY uk_day_group_user (stat_date, group_id, user_id),
+    KEY idx_group_day_score (group_id, stat_date, interaction_score)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Value Rank 社交日汇总表';