#266 fix: _resolve_person_name 支持 bigint person_id 直接 join persons.id

问题: SCRM 分析视图 #42/44/46/49/50 的 role=person + field=person_id
因 scrm_sessions.person_id 是 bigint，而旧实现生成
person_aliases.alias = scrm_sessions.person_id（varchar=bigint）导致报错。

修复:
- _resolve_person_name 增加 bigint 类型检测，直接 join persons.id
- 字符串别名列仍走 person_aliases.alias 解析
- 新增 2 例测试覆盖 bigint/varchar 两条路径

backend/app/services/analysis_engine.py

@@ -458,7 +458,18 @@ def _resolve_person_name(raw_col):
     - 待归并/person_id IS NULL 别名 → NULL(图表显示"(空)",提示去归并)
     - 未提取的新别名(不在 person_aliases) → NULL
     - sys/system 系统别名(person_id=NULL) → NULL(配合视图 raw 层 notin 过滤更佳)
+    - #266: bigint person_id 列(如 scrm_sessions.person_id)直接 join persons.id
     """
+    from sqlalchemy import BigInteger
+    # person_id 是 bigint 外键时,直接 join persons.id,跳过别名解析
+    if isinstance(raw_col.type, BigInteger):
+        subq = (
+            select(Person.display_name)
+            .where(Person.id == raw_col)
+            .limit(1)
+        )
+        return subq.scalar_subquery()
+    # 字符串别名列:走 person_aliases.alias 解析
     subq = (
         select(Person.display_name)
         .join(PersonAlias, PersonAlias.person_id == Person.id)

backend/tests/test_resolve_person_name_266.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""#266: _resolve_person_name 支持 bigint person_id 直接 join persons.id"""
+
+from sqlalchemy import BigInteger, Integer, String
+from sqlalchemy.orm import declarative_base
+from sqlalchemy.sql.schema import Column
+
+from app.services.analysis_engine import _resolve_person_name
+
+Base = declarative_base()
+
+
+class FakeModel(Base):
+    __tablename__ = "fake"
+    id = Column(Integer, primary_key=True)
+    person_id = Column(BigInteger)
+    operator_name = Column(String(64))
+
+
+def test_resolve_person_name_bigint_path():
+    """bigint person_id 列应直接生成 persons.id = raw_col 子查询"""
+    col = FakeModel.person_id
+    subq = _resolve_person_name(col)
+    sql = str(subq)
+    assert "persons.id" in sql
+    assert "person_aliases" not in sql
+
+
+def test_resolve_person_name_varchar_path():
+    """字符串别名列仍走 person_aliases.alias 解析"""
+    col = FakeModel.operator_name
+    subq = _resolve_person_name(col)
+    sql = str(subq)
+    assert "person_aliases" in sql
+    assert "alias" in sql

reference/客服管理系统-开源项目调研清单.md

@@ -0,0 +1,78 @@
+# 客服管理系统 · 开源项目调研清单
+
+> 调研日期：2026-10-06
+> 目标系统模块：客服工作量/绩效/流程管理、投诉分析（主体/原因/传递链）、退款分析（类型/原因）、客户画像（购买/充值/套餐/设备/店铺/标签/金额）、夜间批量分析 + 小模型（8B/14B/27B）预测性干预
+> 说明：以下项目按系统模块分类，链接均来自本次实际检索结果。
+
+## 一、客服工作台 / 工单 / 流程（工作量、SLA、操作记录参考）
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 1 | Chatwoot | https://github.com/chatwoot/chatwoot | 全渠道会话收件箱 + CSAT 报告；按坐席/团队/inbox 的绩效报表（接待量、响应时长、满意度），MIT 协议， star 数约 3.7 万，最接近"客服工作台+绩效报表"的成熟参考 |
+| 2 | 春松客服 CSKeFu | https://github.com/cskefu/cskefu （Gitee: gitee.com/cskefu） | 国产开源客服系统（Java）；坐席工作台、技能组分配、联系人 CRM 标签、坐席监控、质检报表；GVP 认证项目，中文文档友好 |
+| 3 | Zammad | https://github.com/zammad/zammad | 多渠道工单 + 可视化报表仪表盘（按部门/客服/客户类型统计时效、满意度、工单量）；规则引擎适合叠加 AI 分类分派 |
+| 4 | UVdesk | https://github.com/uvdesk/community-skeleton | Symfony 工单系统，电商友好（Shopify/Magento 集成可自动关联订单）；内置代理（客服）绩效报告，适合参考"退款/订单关联工单"的数据模型 |
+| 5 | FreeScout | https://github.com/freescout-helpdesk/freescout | Zendesk 轻量替代；SLA、自动指派、工时统计插件体系，适合小团队快速参考工单流转逻辑 |
+| 6 | osTicket | https://github.com/osTicket/osTicket | 经典工单系统，邮件转工单、自定义表单字段；结构简单，适合参考"工单+自定义字段（投诉类型/退款原因字段）"建模 |
+| 7 | Helpy | https://github.com/helpyio/helpy | 工单 + 知识库 + 社区，MIT 协议，适合参考知识库与服务小结模块 |
+| 8 | Frappe Helpdesk | https://github.com/frappe/helpdesk | Frappe 生态工单系统，天然与 ERP/CRM 数据打通；适合参考"客服工单与企业业务数据（订单/退款）联动"的架构 |
+| 9 | Django Helpdesk | https://github.com/django-helpdesk/django-helpdesk | Python/Django 工单系统，多队列、知识库、邮件同步；二次开发门槛低 |
+
+## 二、投诉文本分析 / 情绪识别 / 意图分类（NLP 参考）
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 10 | SKILL-kefu | https://github.com/liangdabiao/SKILL-kefu | LangChain/LangGraph 智能客服完整方案：**意图分类 16 类（含投诉、退款、退货）、情绪识别 7 类、自动工单、转人工、监控评价仪表盘**——与你"不关注对话原文、只分析话题类型+情绪"的路线高度吻合 |
+| 11 | sentiment_monitor | https://github.com/liugito/sentiment_monitor | 中文舆情监控系统：情感分析、关键词提取、实体识别、话题聚类、**负面案例自动标注+分级预警**——直接对应"投诉主体识别、投诉传递链预警" |
+| 12 | DocSentimentAnalysis | https://github.com/liuhuanyong/DocSentimentAnalysis | 篇章级情感计算（情感词典+依存句法规则），适合无标注语料冷启动阶段的投诉文本情绪打分 |
+| 13 | PaddleNLP | https://github.com/PaddlePaddle/PaddleNLP | 百度工业级中文 NLP 库；情感倾向分析（Senta）、UIE 信息抽取（可抽"投诉主体/投诉原因"结构化字段）、小样本学习 |
+| 14 | Dify | https://github.com/langgenius/dify | 开源 LLM 应用平台；用可视化工作流搭建"意图识别→条件分支→工单/预警"的编排，可作为投诉分析管线的原型工具 |
+
+## 三、客户画像 / CRM / 标签体系
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 15 | user_portrait | https://github.com/ZouRuia/user_portiart | 用户画像/标签系统教学型开源项目，含标签加工、RFM 价值分层实现，适合参考"购买/充值/金额→标签"的加工链路 |
+| 16 | iBizCRM | https://github.com/iBizLab/crm | 国产企业级开源 CRM（MIT）；客户 360° 视图、活动记录、自定义建模——可参考其客户主数据与标签模型 |
+
+## 四、退款 / 订单 / 售后（退款类型、退款原因的数据模型参考）
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 17 | CRMEB（PHP 版） | https://github.com/crmeb/crmeb | 开源电商系统：订单退款、售后（退换货原因）、会员充值/余额/消费记录、会员标签与行为详情——退款分析所需字段基本齐全 |
+| 18 | CRMEB（Java 版） | https://github.com/crmeb/crmeb_java | 同上架构的 Java/SpringBoot 版，含订单、余额、优惠券、会员模块，适合 Java 技术栈参考 |
+| 19 | likeshop | https://github.com/likeadmin-likeshop/likeshop | 开源单商户商城（含 APP/小程序/PC 后台）；订单、售后退款、会员体系完整，代码可读性强调二开 |
+
+## 五、数据统计 / 绩效看板（BI 层）
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 20 | DataEase | https://github.com/dataease/dataease | 国产开源 BI，拖拽做仪表板/数据大屏，支持 MySQL/ClickHouse/Doris/Excel/API 等数据源；适合快速搭"客服工作量+绩效+投诉+退款"管理驾驶舱 |
+| 21 | Apache Superset | https://github.com/apache/superset | Apache 顶级 BI，图表类型最全、SQL 灵活，适合有数据团队后做深度自助分析 |
+| 22 | Metabase | https://github.com/metabase/metabase | 最易上手的开源 BI，非技术人员可用查询构建器自助取数，支持定时报表推送邮件 |
+
+## 六、小模型微调（8B/14B/27B 预测性干预）
+
+| # | 项目 | 链接 | 与你系统的相关性 |
+|---|------|------|------------------|
+| 23 | LLaMA-Factory | https://github.com/hiyouga/LLaMA-Factory | 最主流的国产微调框架（WebUI + LoRA/QLoRA），已支持 Qwen2/Qwen3 全系列 0.5B~110B——你计划的 8B/14B/27B 投诉分类、退款原因归类、高风险客户预测模型都可以用它训练，单卡即可跑 LoRA |
+| 24 | Qwen-fine-tune | https://github.com/ChenXingLing/Qwen-fine-tune | 最小可跑的 Qwen LoRA 文本分类教程项目（PEFT + HC3 中文数据集），适合作为"投诉文本→分类标签"微调的第一个脚手架 |
+
+---
+
+## 落地建议（按你的两阶段路线）
+
+**第一阶段（统计分析 + 管理干预）**
+- 数据底座/报表：DataEase（或 Metabase）+ MySQL/ClickHouse，把接待量、工单、退款、投诉四张事实表做成日报看板
+- 字段建模参考：osTicket/UVdesk 的自定义字段（投诉类型、退款原因）、CRMEB 的售后/退款/会员充值表结构
+- 客服绩效指标参考：Chatwoot 的 CSAT/agent 报表、智齿/芝麻类产品的"工作量统计指标口径"（创建工单数、平均处理时长、3 分钟响应率、未回复率等）
+
+**第二阶段（夜间批量分析 + 小模型预测干预）**
+- 编排：Dify 工作流 或 直接 Python 批处理（Airflow 调度夜间任务）
+- 分类/抽取模型：PaddleNLP UIE 或 Qwen-8B LoRA 微调（LLaMA-Factory），输入=话题类型+投诉文本摘要+退款记录+操作日志，输出=客户风险分+干预建议清单
+- 情绪/升级预警：参考 sentiment_monitor 的负面分级预警机制
+
+## 备注
+- 纯开源、无商业后缀：Chatwoot（社区版 MIT）、Django Helpdesk、Helpy、iBizCRM、CRMEB（需保留版权）、likeshop、DataEase（GPLv3）、Superset、Metabase（社区版）、LLaMA-Factory、Qwen-fine-tune、DocSentimentAnalysis。
+- 注意：Chatwoot 的 `enterprise/` 目录、CRMEB/likeshop 的增值功能为商业授权，研究时以社区版代码为准。
+- 未收录但可关注：Rasa（对话意图框架）、悟空CRM（国产 CRM）、ClkLog（开源埋点+用户标签/分群）、Airflow（夜间批处理调度），本次未做逐一核验，需要可补充调研。

reference/客服管理系统-重点开源项目深度对比.md

@@ -0,0 +1,80 @@
+# 客服管理系统 · 重点开源项目深度对比
+
+> 调研日期：2026-10-06
+> 对比对象：从 24 个项目名录中选出与系统目标最贴合的 6 个，覆盖四个层次——客服工作台（Chatwoot / CSKeFu / Zammad / UVdesk）、BI 看板（DataEase）、小模型微调（LLaMA-Factory）。
+> 对比维度：定位与模块覆盖、技术栈、数据模型可借鉴点、报表/绩效能力、二次开发成本、许可证与商业化风险、综合匹配度。
+
+---
+
+## 一、总览对比表
+
+| 维度 | Chatwoot | 春松客服 CSKeFu | Zammad | UVdesk | DataEase | LLaMA-Factory |
+|---|---|---|---|---|---|---|
+| 定位 | 全渠道会话 + 客服平台 | 国产多渠道智能客服（含机器人） | 流程导向工单系统 | 电商友好工单系统 | 开源 BI / 数据可视化 | 大模型微调训练框架 |
+| 技术栈 | Ruby on Rails + Vue + PostgreSQL/Redis | Java（Spring）+ Pugjs 前端 | Ruby on Rails + ES | PHP Symfony + Backbone.js | Java(Spring Boot) + Vue + ECharts/AntV | PyTorch + Transformers + PEFT |
+| 覆盖你的模块 | 工作量✅ 绩效✅ 流程✅ 投诉标签✅ 画像(基础)⚠️ | 工作量✅ 绩效✅ 流程✅ 标签✅ 质检✅ | 工作量✅ 绩效✅ 流程✅ | 工作量✅ 绩效✅ 退款关联✅ | 全部指标的看板层✅ | 预测干预层✅ |
+| 报表/绩效能力 | Conversation/Agent/Inbox/Label/Team 五类报表 + CSAT + 可下载报表 | 坐席监控 + 质检报表（服务小结/反馈） | 内置仪表盘：按部门/客服/客户类型统计时效、满意度、工单量 | 代理绩效报告 + 工单过滤统计 | 拖拽式仪表板/大屏，40+ 图表，定时刷新 | 训练指标可视化（loss/eval）+ SwanLab 等集成 |
+| 数据模型亮点 | 会话+联系人自定义属性（Custom Attributes）、标签（Labels）、Shopify 订单集成 | 联系人 CRM 自定义标签、技能组、服务小结 | 工单生命周期状态机、SLA、多级权限 | 工单类型/多标签、自动化工作流（Automation Bundle） | 数据集/仪表板/权限模型 | instruction 微调数据集格式（Alpaca/ShareGPT） |
+| 二开门槛 | 中（Rails 生态，社区大） | 中高（Java 老架构，前端 Pugjs 小众） | 中（Rails，规则引擎复杂） | 低中（Symfony 扩展框架设计良好） | 低（拖拽为主，插件机制） | 低（WebUI + YAML 配置） |
+| 许可证 | MIT（`enterprise/` 目录除外，商用需注意） | **春松公共许可证 1.0（自定义协议，非标准 OSI，商用前必须读协议）** | AGPL-3.0（网络服务 copyleft，二开对外提供服务需开源） | OSL-3.0（copyleft，有传染性） | GPLv3（社区版，商用需注意；另有商业版） | Apache-2.0（最宽松✅） |
+| 社区活跃度 | 极高（约 3.7 万 star） | 中（v8 维护中，v7 已停止维护） | 高（约 5k star，持续迭代） | 中（Webkul 主导） | 高（2.4 万+ star） | 极高（最主流微调框架） |
+| 综合匹配度 | ★★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★★（报表层） | ★★★★★（AI 层） |
+
+---
+
+## 二、逐项分析
+
+### 1. Chatwoot —— 最佳"工作台 + 绩效报表"参考
+- **报表能力最强**：内置 Conversation / Agent / Inbox / Label / Team 五类运营报表 + CSAT 满意度报表 + 报表下载（CSV），几乎就是你要的"工作量、绩效"模块的现成实现。
+- **与你的分析路线契合**：它本身不深度分析对话内容，而是用 **Labels（标签）+ Custom Attributes（自定义属性）** 给会话打结构化标记——和你"只获取话题类型、不获取对话原文"的约束完全同构。投诉主体、投诉原因、退款类型都可以建模为自定义属性/标签。
+- **风险**：`enterprise/` 目录是商业授权；高级报表功能部分在商业版。自托管社区版够用，但不要指望它的报表完全覆盖你的定制指标。
+- **借鉴方式**：不必整体采用，重点读它的 `reports` 模块 SQL 口径（首次响应时长、解决时长、CSAT 聚合）和会话-联系人-标签数据模型。
+
+### 2. 春松客服 CSKeFu —— 最完整的国产客服参考（但许可证要当心）
+- **模块最贴你的需求**：坐席监控（实时干预）、技能组分配、联系人 CRM 自定义标签、质检（历史会话 + 服务小结 + 服务反馈报表）——这四块恰好对应你的"流程管理 + 绩效 + 画像标签 + 质检"。
+- **技术现实**：Java + Spring 老架构，前端用 Pugjs（小众模板引擎），二开招聘成本高；v7 已停止维护，只有 v8 在活跃维护。
+- **⚠️ 许可证修正**：它用的是自研的"春松公共许可证 1.0"（Chunsong Public License），**不是 MIT/Apache 这类标准协议**，商用授权条款需要逐条阅读（此前清单中"商业友好授权"的表述以官方协议文本为准）。
+
+### 3. Zammad —— 工单流程引擎的最佳参考
+- **强项**：工单生命周期状态机（新建→处理中→待回复→已解决→关闭→重新激活）、SLA 计时、多级权限/角色、成熟规则引擎（自动分派、优先级判断）。
+- **与你的映射**：你提到的"投诉传递链"本质就是工单流转路径，Zammad 的状态机 + 审计日志是最规范的参考实现。
+- **风险**：AGPL-3.0，如果你二开后作为网络服务对外提供，衍生作品需要开源。建议只学设计，不直接嵌入代码。
+
+### 4. UVdesk —— 电商退款场景的轻量参考
+- **强项**：Automation Bundle（工作流 + 预设回复）、Agent Activity（客服操作记录）、Ticket Types + 多标签；面向电商的订单关联设计。
+- **弱点**：报表维度不如 Chatwoot 细；PHP/Symfony 技术栈；OSL-3.0 同样带 copyleft 传染性。
+- **借鉴点**：工单自定义字段（类型/标签）+ 操作记录的表结构，适合你建"退款类型、退款原因"字段字典。
+
+### 5. DataEase —— 统计报表层的首选底座
+- **为什么必选**：你的第一阶段（数据统计 + 管理干预）本质是把接待量、工单、投诉、退款四张事实表变成看板。DataEase 拖拽出图、支持 MySQL/ClickHouse/Excel/API 数据源、有行级权限和 200+ 大屏模板，是国产开源里上手成本最低的。
+- **代价**：GPLv3 + 企业版功能分级（X-Pack），纯内部分析使用没有问题。
+- **替代**：Metabase（更简、社区版免费但行级权限要付费版）、Superset（功能最强但要写 SQL、运维成本高）。
+
+### 6. LLaMA-Factory —— 第二阶段（8B/14B/27B 预测干预）的训练底座
+- **为什么必选**：Apache-2.0 最宽松；WebUI + YAML 配置即可训练，支持 LoRA/QLoRA（单卡可训 8B~14B），已支持 Qwen3 全系列 0.5B~110B，与你的 8B/14B/27B 规划一一对应。
+- **你的用法**：每晚批量把"话题类型 + 投诉摘要 + 退款记录 + 操作日志"组装成 instruction 数据，训一个"客户风险分 + 干预建议"分类/排序模型，输出次日主动干预清单。
+- **配套**：可参考 Qwen-fine-tune 项目（最小 LoRA 分类脚手架）做第一个原型，跑通后再上 LLaMA-Factory 批量实验。
+
+---
+
+## 三、结论：推荐参考底座组合
+
+不建议单选一个大而全的系统（你的需求横跨四个层次，没有任何单个开源项目全覆盖）。推荐**分层组合、各取数据模型**：
+
+| 层次 | 推荐 | 用法 |
+|---|---|---|
+| ① 数据模型与指标口径 | **Chatwoot**（主）+ **Zammad**（状态机）+ **UVdesk**（自定义字段） | 只读源码学设计：会话/工单表结构、绩效指标 SQL 口径（首响时长、处理时长、CSAT）、投诉传递链状态机、退款原因字段字典 |
+| ② 统计看板 | **DataEase** | 直接部署，接你的业务库，1~2 周能出管理驾驶舱 |
+| ③ 投诉/退款文本结构化 | **PaddleNLP UIE**（冷启动）→ **LLaMA-Factory + Qwen-8B LoRA**（沉淀后） | UIE 免训练抽"投诉主体/原因"；积累标注后微调小模型替换 |
+| ④ 编排与调度 | Dify（原型）或 Python + Airflow（生产） | 夜间批处理：拉取当日 3000 会话 → 结构化 → 打分 → 生成干预清单 |
+
+**许可证红线**：对外商用产品化时，避免直接嵌入 AGPL（Zammad）/OSL（UVdesk）/春松自定义协议的代码；MIT（Chatwoot 社区版）与 Apache-2.0（LLaMA-Factory）可放心使用；GPL 系列（DataEase 社区版）内部分析无妨、对外分发需谨慎。
+
+---
+
+## 附：本对比的信息来源
+- Chatwoot 官方 README（功能清单与 MIT 声明）：https://github.com/chatwoot/chatwoot
+- 春松客服 README（模块清单、v7/v8 维护状态、春松公共许可证 1.0）：https://github.com/cskefu/cskefu
+- UVdesk README（模块、OSL-3.0、Symfony 架构）：https://github.com/uvdesk/community-skeleton
+- LLaMA-Factory LICENSE（Apache-2.0）及 README_zh（Qwen3 支持矩阵）
+- Zammad / DataEase 功能描述来自选型文章与项目页（见调研清单中的引用）