小医建档流程与架构分析报告

版本：v1.0

生成时间：2026-04-28 10:53

分析范围：/home/admin/.openclaw/workspace

文档数量：277 个 .md 文件

---

📋 执行摘要

本报告基于小医（健康之路医生助理）项目 workspace 的全部文档，对**用户建档流程**和**系统架构**进行全面分析，识别当前存在的问题并提出改进建议。

核心发现

---

一、建档流程分析

1.1 流程总览

用户添加小医微信
    ↓
系统自动解析 contactId（从会话标识）
    ↓
检查 user_index.json（判断新老用户）
    ↓
┌─────────────────────┬─────────────────────┐
│   新用户流程        │   老用户流程        │
│  (contactId 不存在)  │  (contactId 存在)    │
└─────────────────────┴─────────────────────┘
    ↓                         ↓
创建档案目录                 加载 SESSION_STATE
    ↓                         ↓
发送欢迎词 + FAQ              加载用户权限
    ↓                         ↓
引导提供信息（姓名 + 手机号）   正常会话
    ↓
调用 API 核验身份
    ↓
建档完成（verified=true）
    ↓
同步到 user_index.json

---

1.2 新用户建档详细流程

步骤 1：contactId 解析

**来源：** 从会话标识自动解析

会话标识格式：
agent:main:tutu-aggchat:direct:jkzl:vgw9nk8r:7v1xmj9q
                                        ↓
                                    contactId

**方法：**

---

步骤 2：档案创建

**档案目录：** `other-contacts/{contactId}/`

**档案文件：**

other-contacts/{contactId}/
├── profile.json              # 基本信息
├── {contactId}_SESSION_STATE.md  # 会话状态（可选）
└── memory/                   # 短期记忆（可选）
    └── YYYY-MM-DD.md

**profile.json 格式：**

{
  "contactId": "q29m0gev",
  "name": "陈美华",
  "role": "other-contacts",
  "verified": true,
  "phone": "13559110806",
  "doctorUid": 710558434,
  "createdAt": "2026-04-27 15:51",
  "lastUpdate": "2026-04-27 18:15"
}

---

步骤 3：欢迎词发送

**触发条件：** 新用户（contactId 不在 user_index.json 中）

**欢迎词内容：** 加载自 `skills/activity-faq/doctor-faq.md`

**发送规则：**

---

步骤 4：信息收集（简化版）

**仅需 2 项信息：**

**说明：** 医院、科室、省份等信息通过 API 核验后自动获取，无需用户手动提供。

**话术示例：**

您好！为了为您提供精准的查询服务，需要为您建立医生档案。

请您提供以下信息：
1. 姓名
2. 手机号

例如：张三，13559110806

---

步骤 5：身份核验

**调用 API：** `UserMgmt.Account.getUserInfoByLoginID`

**请求参数：**

{
  "loginID": "13559110806",
  "loginType": "1",
  "needDepartment": "false"
}

**核验结果处理：**

**核验通过后更新档案：**

{
  "contactId": "q29m0gev",
  "name": "陈美华",
  "role": "other-contacts",
  "verified": true,
  "phone": "13559110806",
  "doctorUid": 710558434,
  "hospital": "福州协和医院",
  "department": "心内科",
  "lastUpdate": "2026-04-27 18:15"
}

---

步骤 6：同步到 user_index.json

**同步脚本：** `scripts/sync_user_index.py`

**同步方式：**

# 手动同步所有档案
python3 scripts/sync_user_index.py

# 自动同步（新用户建档后调用）
scripts/sync_user_index.py

**user_index.json 格式：**

{
  "q29m0gev": {
    "name": "陈美华",
    "callName": "陈美华",
    "role": "other-contacts",
    "verified": true,
    "phone": "13559110806",
    "doctorUid": 710558434,
    "createdAt": "2026-04-27 15:51",
    "lastUpdate": "2026-04-27 18:22"
  }
}

---

1.3 老用户流程

识别逻辑

if contactId in user_index and user_index[contactId]['verified'] == true:
    # 老用户 → 加载权限
    role = user_index[contactId]['role']
    load_session_state(role, contactId)

SESSION_STATE 加载

---

1.4 员工身份核验（特殊流程）

**触发条件：** 用户在 `employees/employee_list.json` 预置名单中

**处理流程：**

**员工档案目录：** `employees/{姓名}_{contactId}/`

---

二、系统架构分析

2.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                     用户交互层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  企业微信   │  │   个人微信   │  │  Web 界面   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┴────────────────┘                 │
│                          │                                  │
│                  tutu-aggchat 通道                           │
└──────────────────────────┼──────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     应用服务层                               │
│  ┌───────────────────────┴───────────────────────┐         │
│  │            OpenClaw Agent (小医)              │         │
│  │  ┌─────────────┐  ┌─────────────┐            │         │
│  │  │  会话管理   │  │  技能调度   │            │         │
│  │  └─────────────┘  └─────────────┘            │         │
│  │  ┌─────────────┐  ┌─────────────┐            │         │
│  │  │  记忆系统   │  │  权限控制   │            │         │
│  │  └─────────────┘  └─────────────┘            │         │
│  └───────────────────────────────────────────────┘         │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     数据持久层                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ user_index  │  │  档案目录   │  │   记忆文件   │         │
│  │   .json     │  │  (JSON)     │  │   (.md)     │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  技能清单   │  │   配置中心   │  │   工单系统   │         │
│  │ manifest    │  │  config/    │  │  tickets/   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────┼──────────────────────────────────┐
│                     外部 API 层                               │
│  ┌─────────────────────────────────────────────────┐        │
│  │     健康之路开放平台 API                         │        │
│  │  - UserMgmt.Account.getUserInfoByLoginID        │        │
│  │  - DoctorIncomeUI.DoctorCashApi.query...        │        │
│  │  - DoctorIncomeUI.UserEnterInfoApi.get...       │        │
│  └─────────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘

---

2.2 用户分类与权限

**重要规则：**

---

2.3 数据隔离机制

workspace/
├── user_index.json              # 全局索引（所有用户可见）
├── employees/                   # 内部员工档案
│   ├── employee_list.json      # 员工预置名单
│   └── {姓名}_{contactId}/     # 员工个人档案（隔离）
├── other-contacts/              # 外部用户档案
│   └── {contactId}/            # 用户档案目录（隔离，不带姓名）
├── memory/                      # 全局记忆
│   ├── SESSION_STATE.md        # 全局活跃状态
│   └── YYYY-MM-DD.md           # 每日记忆
└── tickets/                     # 工单系统
    └── ticket-{date}-{num}.json # 工单文件

**隔离规则：**

---

2.4 技能架构

技能分层

核心技能清单

---

2.5 记忆系统

**WAL Protocol（写前日志）触发条件：**

---

三、存在的问题

3.1 🔴 严重问题

问题 1：user_index.json 同步风险

**问题描述：**

档案创建后，依赖脚本同步到 user_index.json，存在不同步风险。

**根本原因：**

**影响：**

**历史案例：**

**当前缓解措施：**

**建议改进：**

---

问题 2：渠道激活依赖用户主动发消息

**问题描述：**

tutu-aggchat 通道需要用户主动发消息才能激活，导致：

**影响：**

**历史案例：**

**当前缓解措施：**

**建议改进：**

---

3.2 ⚠️ 中等问题

问题 3：档案目录结构不统一

**问题描述：**

不同用户的档案目录结构存在差异：

**示例 1（标准）：**

other-contacts/q29m0gev/
└── profile.json

**示例 2（带 SESSION_STATE）：**

other-contacts/test_new_01/
├── test_new_01_SESSION_STATE.md
└── ...

**示例 3（旧格式）：**

other-contacts/phone-59152902/  # 目录名使用手机号
other-contacts/59152902/        # 目录名使用 contactId

**影响：**

**建议改进：**

---

问题 4：活动名称映射维护成本高

**问题描述：**

用户搜索的活动名称（品牌名）与系统实际活动名称不一致，需要维护映射表。

**当前映射关系：**

**影响：**

**建议改进：**

---

问题 5：SESSION_STATE 文件分散

**问题描述：**

SESSION_STATE 文件分布在多个位置：

**影响：**

**建议改进：**

---

3.3 ℹ️ 低优先级问题

问题 6：文档版本管理不规范

**问题描述：**

**建议改进：**

---

问题 7：测试档案未清理

**问题描述：**

存在多个测试档案：

**影响：**

**建议改进：**

---

四、改进建议

4.1 短期改进（1-2 周）

建议 1：增强同步脚本健壮性

**目标：** 确保 user_index.json 与档案目录 100% 同步

**措施：**

**实施步骤：**

# 1. 修改 sync_user_index.py
nano skills/user-onboard/scripts/sync_user_index.py

# 2. 增加重试逻辑
def call_update_script(contact_id, *args):
    max_retries = 3
    for i in range(max_retries):
        try:
            # 调用 update_user_index.py
            ...
            return True
        except Exception as e:
            if i == max_retries - 1:
                return False
            time.sleep(1)

# 3. 测试验证
python3 skills/user-onboard/scripts/sync-all-to-user-index.py

---

建议 2：增加渠道状态监控

**目标：** 实时掌握渠道激活状态

**措施：**

**监控脚本示例：**

#!/bin/bash
# check_channel_status.sh

echo "=== 渠道激活状态检查 ==="
echo ""

# 读取 user_index.json 中的所有 contactId
contactIds=$(cat user_index.json | jq -r 'keys[]')

for contactId in $contactIds; do
    # 调用 tutu API 检查渠道状态
    status=$(curl -s -X POST https://tutu-gateway.lovebenefits.com/... \
        -d "{\"contactId\":\"$contactId\"}" | jq -r '.status')
    
    if [ "$status" != "active" ]; then
        echo "⚠️  $contactId: 渠道未激活"
    fi
done

---

建议 3：统一档案目录结构

**目标：** 所有档案使用统一格式

**措施：**

**规范示例：**

# 标准格式
other-contacts/{contactId}/profile.json
employees/{姓名}_{contactId}/{姓名}_{contactId}_profile.json

# 禁止格式
other-contacts/phone-{phone}/  # 不使用手机号作为目录名
other-contacts/{name}/         # 不使用姓名作为目录名

---

4.2 中期改进（1-2 月）

建议 4：建立档案管理界面

**目标：** 运营人员可自助管理档案

**功能：**

**技术选型：**

---

建议 5：优化活动名称映射管理

**目标：** 降低映射表维护成本

**措施：**

**映射表格式优化：**

{
  "version": "1.0",
  "updatedAt": "2026-04-28",
  "mappings": [
    {
      "id": "map-001",
      "keywords": ["医道微光", "精准免疫"],
      "actualName": "精准免疫肿瘤诊疗管理",
      "shortUrl": "https://fjhma.com/1DL8uI",
      "active": true
    }
  ]
}

---

4.3 长期改进（3-6 月）

建议 6：引入数据库存储

**目标：** 替代文件存储，提高数据一致性

**当前架构：**

文件存储：user_index.json + 档案目录

**目标架构：**

SQLite/PostgreSQL 数据库
├── users 表（contactId, name, role, verified, ...）
├── profiles 表（详细档案信息）
├── sessions 表（会话状态）
└── memories 表（记忆内容）

**优势：**

---

建议 7：建立自动化测试体系

**目标：** 确保建档流程稳定性

**测试覆盖：**

**测试框架：**

---

五、风险评估

5.1 风险矩阵

---

5.2 应急预案

预案 1：user_index.json 损坏

**症状：**

**应急步骤：**

# 1. 备份当前文件
cp user_index.json user_index.json.bak

# 2. 从档案目录重建
python3 skills/user-onboard/scripts/sync-all-to-user-index.py

# 3. 验证重建结果
cat user_index.json | jq 'keys | length'

---

预案 2：API 调用大面积失败

**症状：**

**应急步骤：**

# 1. 检查 API 状态
curl -X POST https://api.yihu.com/OpenPlatform/cgiBin/1.0/...

# 2. 切换备用 API（如有）
# 修改 config/api-config.json

# 3. 降级处理
# 告知用户"系统繁忙，请稍后再试"
# 记录失败日志，后续补偿

---

预案 3：渠道大面积未激活

**症状：**

**应急步骤：**

# 1. 生成未激活用户列表
./scripts/check_channel_status.sh > unactivated_users.txt

# 2. 运营人员手动引导
# 通过短信/电话通知用户主动发消息

# 3. 验证激活结果
# 重新运行检查脚本

---

六、总结

6.1 架构优势

---

6.2 主要问题

---

6.3 优先级建议

---

附录

A. 相关文件清单

---

B. 关键脚本清单

---

C. 术语表

---

_报告生成时间：2026-04-28 10:53_

_分析范围：/home/admin/.openclaw/workspace（277 个 .md 文件）_

_版本：v1.0_