20260731 114201 汇工作系统开发需求规格说明书

┌─────────────────────────────────────────────────────────┐
│                    汇工作平台                            │
│                                                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐      │
│  │话单采集  │ │录音管理  │ │漏话分析  │ │走访管理  │      │
│  │  引擎   │ │  服务   │ │  引擎   │ │  服务   │      │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘      │
│       │           │           │           │            │
│  ┌────┴───────────┴───────────┴───────────┴────┐       │
│  │              AI 语音质检引擎                 │       │
│  └────────────────────┬────────────────────────┘       │
│                       │                                 │
│  ┌─────────┐ ┌────────┴────────┐ ┌─────────┐          │
│  │报告生成  │ │   数据中台      │ │权限管理  │          │
│  │  服务   │ │ (存储/检索/统计) │ │  服务   │          │
│  └─────────┘ └─────────────────┘ └─────────┘          │
│                                                         │
└───────────┬─────────────────┬───────────────────────────┘
            │                 │
   ┌────────┴───────┐  ┌─────┴──────────┐
   │  电信网络侧    │  │  天翼云基础设施  │
   │ (5G/4G话单/录音)│  │ (计算/存储/安全) │
   └────────────────┘  └────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                        接入层                                │
│   ┌──────────┐   ┌──────────┐   ┌──────────┐              │
│   │ Web管理端 │   │ H5移动端  │   │ 开放API  │              │
│   │ (Vue3)   │   │ (Vue3)   │   │ (REST)   │              │
│   └─────┬────┘   └─────┬────┘   └─────┬────┘              │
│         └──────────────┴──────────────┘                     │
└────────────────────────┬────────────────────────────────────┘
                         │  HTTPS / WSS
┌────────────────────────┴────────────────────────────────────┐
│                      API 网关层                              │
│          (鉴权 / 限流 / 路由 / 日志 / 审计)                   │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                     业务服务层 (微服务)                       │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐   │
│  │话单采集 │ │录音管理 │ │漏话分析 │ │走访管理 │ │AI质检   │   │
│  │服务    │ │服务    │ │服务    │ │服务    │ │服务    │   │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘   │
│  ┌────────┐ ┌────────┐ ┌────────┐                          │
│  │报告生成 │ │权限管理 │ │通知服务 │                          │
│  │服务    │ │服务    │ │服务    │                          │
│  └────────┘ └────────┘ └────────┘                          │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────┴────────────────────────────────────┐
│                      数据层                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │PostgreSQL │  │  Redis   │  │ MinIO    │  │ElasticS. │   │
│  │(业务数据) │  │(缓存/队列)│  │(录音文件) │  │(全文检索) │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘

{
  "event_type": "call_completed",
  "call_id": "CL20260731143052_18117132919",
  "tenant_id": "TENANT_PTNSRCB",
  "phone_number": "18117132919",
  "call_direction": "outgoing",
  "callee_number": "13805061234",
  "start_time": "2026-07-31T14:30:52+08:00",
  "end_time": "2026-07-31T14:33:28+08:00",
  "duration_seconds": 156,
  "recording_url": "https://oss.ctyun.cn/rec/CL20260731143052_18117132919.wav"
}

GET /api/v1/call-records
  ?phone_number={string}
  &direction={incoming|outgoing}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
  &department_id={string}
  &page={int}&page_size={int}
Response: {
  "total": 156,
  "items": [{
    "call_id": "CL20260731143052_18117132919",
    "phone_number": "18117132919",
    "employee_name": "张三",
    "department": "个人金融部",
    "direction": "outgoing",
    "peer_number": "13805061234",
    "start_time": "2026-07-31T14:30:52+08:00",
    "duration_seconds": 156,
    "has_recording": true,
    "recording_id": "REC_20260731_001"
  }]
}

GET /api/v1/call-statistics/summary
  ?dimension={individual|department}
  &period={daily|weekly|monthly}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
Response: {
  "dimension": "individual",
  "period": "daily",
  "items": [{
    "employee_id": "EMP001",
    "employee_name": "张三",
    "department": "个人金融部",
    "outgoing_count": 28,
    "incoming_count": 12,
    "total_count": 40,
    "outgoing_duration_min": 95,
    "incoming_duration_min": 38,
    "total_duration_min": 133,
    "meets_threshold": true
  }]
}

POST /api/v1/call-thresholds
Request: {
  "department_id": "DEPT_PJRB",
  "role": "客户经理",
  "min_daily_outgoing": 20,
  "min_daily_total": 30
}

GET /api/v1/recordings
  ?phone_number={string}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
  &has_transcript={bool}
  &keyword={string}  # 转写全文检索
  &page={int}&page_size={int}
Response: {
  "total": 89,
  "items": [{
    "recording_id": "REC_20260731_001",
    "call_id": "CL20260731143052_18117132919",
    "phone_number": "18117132919",
    "employee_name": "张三",
    "duration_seconds": 156,
    "file_size_kb": 2450,
    "transcript_status": "completed",
    "created_at": "2026-07-31T14:35:00+08:00"
  }]
}

GET /api/v1/recordings/{recording_id}/play
Response: {
  "play_url": "https://...",  # 临时签名URL，有效期15分钟
  "expires_at": "2026-07-31T15:00:00+08:00"
}

GET /api/v1/recordings/{recording_id}/transcript
Response: {
  "recording_id": "REC_20260731_001",
  "status": "completed",
  "transcript": "您好，我是莆田农商行的客户经理张三...",
  "segments": [{
    "start_ms": 0,
    "end_ms": 3200,
    "speaker": "agent",
    "text": "您好，我是莆田农商行的客户经理张三"
  }, {
    "start_ms": 3500,
    "end_ms": 8200,
    "speaker": "customer",
    "text": "你好，我想咨询一下贷款的事"
  }]
}

GET /api/v1/missed-calls
  ?phone_number={string}
  &department_id={string}
  &status={pending|callback_done|expired}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
  &page={int}&page_size={int}
Response: {
  "total": 23,
  "items": [{
    "missed_call_id": "MC_20260731_001",
    "phone_number": "18117132919",
    "employee_name": "张三",
    "caller_number": "13805061234",
    "call_time": "2026-07-31T10:15:00+08:00",
    "status": "callback_done",
    "callback_time": "2026-07-31T10:22:00+08:00",
    "response_minutes": 7
  }]
}

GET /api/v1/missed-calls/statistics
  ?dimension={individual|department}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
Response: {
  "items": [{
    "employee_name": "张三",
    "department": "个人金融部",
    "missed_count": 5,
    "callback_count": 4,
    "callback_rate": 0.80,
    "avg_response_minutes": 12.5
  }]
}

POST /api/v1/visits/check-in  (H5端)
Request: {
  "customer_id": "CUST_001",
  "latitude": 25.4308,
  "longitude": 119.0077,
  "photos": ["base64_1", "base64_2"],
  "remark": "客户咨询经营贷款，已介绍产品方案"
}
Response: {
  "visit_id": "VIS_20260731_001",
  "check_in_time": "2026-07-31T09:30:00+08:00",
  "distance_to_customer_m": 120,
  "status": "normal"
}

GET /api/v1/visits
  ?employee_id={string}
  &department_id={string}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
  &page={int}&page_size={int}

GET /api/v1/visits/trajectory
  ?employee_id={string}
  &date={YYYY-MM-DD}
Response: {
  "employee_name": "张三",
  "date": "2026-07-31",
  "points": [{
    "visit_id": "VIS_20260731_001",
    "customer_name": "莆田市XX商贸有限公司",
    "latitude": 25.4308,
    "longitude": 119.0077,
    "check_in_time": "2026-07-31T09:30:00+08:00",
    "photo_count": 2
  }]
}

POST /api/v1/customers/batch-import
Request: {
  "customers": [{
    "name": "莆田市XX商贸有限公司",
    "contact_person": "李总",
    "phone": "13805061234",
    "address": "莆田市城厢区XX路XX号",
    "latitude": 25.4308,
    "longitude": 119.0077
  }]
}

POST /api/v1/qa-rules
Request: {
  "rule_name": "违规承诺检测",
  "department_id": "DEPT_PJRB",
  "dimension": "sensitive_word",
  "risk_level": "high",
  "keywords": ["保本保息", "绝对没问题", "稳赚不赔"],
  "regex_patterns": [".*保证.*收益.*"]
}

GET /api/v1/qa-reports
  ?department_id={string}
  &risk_level={high|medium|low|all}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
  &page={int}&page_size={int}
Response: {
  "total": 45,
  "items": [{
    "report_id": "QA_20260731_001",
    "recording_id": "REC_20260731_001",
    "employee_name": "张三",
    "department": "个人金融部",
    "qa_score": 85,
    "risk_level": "medium",
    "issues": [{
      "dimension": "service_standard",
      "description": "开场白未主动表明身份",
      "risk_level": "medium",
      "audio_start_ms": 1200,
      "audio_end_ms": 5800
    }],
    "created_at": "2026-07-31T14:45:00+08:00"
  }]
}

GET /api/v1/qa-reports/{report_id}
Response: {
  "report_id": "QA_20260731_001",
  "qa_score": 85,
  "risk_level": "medium",
  "dimensions": {
    "sensitive_word": {"passed": true, "details": "未检测到敏感词"},
    "service_standard": {"passed": false, "details": "开场白未主动表明身份", "segments": []},
    "emotion": {"passed": true, "emotion_score": 0.82, "details": "情绪正常"},
    "compliance": {"passed": true, "details": "话术合规"},
    "silence": {"passed": true, "max_silence_seconds": 8},
    "interruption": {"passed": true, "interruption_count": 1}
  }
}

GET /api/v1/reports/daily
  ?employee_id={string}
  &department_id={string}
  &date={YYYY-MM-DD}
Response: {
  "date": "2026-07-31",
  "employee_name": "张三",
  "department": "个人金融部",
  "metrics": {
    "outgoing_count": 28,
    "incoming_count": 12,
    "outgoing_duration_min": 95,
    "incoming_duration_min": 38,
    "missed_count": 2,
    "callback_rate": 1.0,
    "visit_count": 3,
    "qa_avg_score": 85,
    "risk_alert_count": 0,
    "pending_tasks": 5
  }
}

GET /api/v1/reports/export
  ?report_type={daily|weekly|monthly}
  &format={pdf|excel}
  &employee_id={string}
  &department_id={string}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
Response: binary file download

GET /api/v1/dashboard/kpi
  ?department_id={string}
  &start_date={YYYY-MM-DD}
  &end_date={YYYY-MM-DD}
Response: {
  "department": "个人金融部",
  "total_employees": 12,
  "metrics": {
    "total_calls": 1256,
    "avg_calls_per_person": 104.7,
    "total_visits": 89,
    "avg_qa_score": 87.3,
    "total_risk_alerts": 3,
    "missed_callback_rate": 0.92
  },
  "ranking": [{
    "rank": 1,
    "employee_name": "张三",
    "total_calls": 152,
    "qa_avg_score": 92,
    "visits": 12
  }]
}

POST /api/v1/auth/login
Request: { "username": "admin", "password": "***" }
Response: {
  "token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "expires_in": 7200,
  "user": {
    "user_id": "U001",
    "role": "bank_admin",
    "tenant_id": "TENANT_PTNSRCB",
    "name": "管理员"
  }
}

GET /api/v1/organizations/tree
Response: {
  "tenant_name": "莆田市农商行",
  "departments": [{
    "department_id": "DEPT_PJRB",
    "name": "个人金融部",
    "parent_id": null,
    "manager_name": "王部长",
    "employee_count": 15
  }]
}

POST /api/v1/employees
Request: {
  "name": "张三",
  "phone_number": "18117132919",
  "department_id": "DEPT_PJRB",
  "role": "customer_manager",
  "plan_code": "FLAGSHIP",  # BASIC / PROFESSIONAL / FLAGSHIP
  "qa_enabled": true
}

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Tenant  │1---*│Department│1---*│ Employee │
│ (租户)   │     │ (部门)   │     │ (员工)   │
└──────────┘     └──────────┘     └─────┬────┘
      │                                 │
      │          ┌──────────┐           │
      │1--------*│ PhoneNumber│1--------1│
      │          │(号码套餐) │           │
      │          └─────┬────┘           │
      │                │                │
      │          ┌─────┴────┐           │
      │1---------*│CallRecord│*---------1│
      │          │(通话记录) │           │
      │          └─────┬────┘           │
      │                │                │
      │          ┌─────┴────┐           │
      │1---------*│ Recording│          │
      │          │ (录音)   │           │
      │          └─────┬────┘           │
      │                │                │
      │          ┌─────┴────┐           │
      │1---------*│Transcript│          │
      │          │(转写文本) │          │
      │          └─────┬────┘           │
      │                │                │
      │          ┌─────┴────┐           │
      │1---------*│QAReport  │          │
                 │(质检报告) │          │
                 └──────────┘           │
                                        │
┌──────────┐     ┌──────────┐          │
│ Customer │1---*│  Visit   │*---------1│
│ (客户)   │     │ (走访)   │          │
└──────────┘     └──────────┘          │
                                        │
                 ┌──────────┐          │
                 │MissedCall│*---------1│
                 │(漏话)    │          │
                 └──────────┘          │
                                        │
                 ┌──────────┐          │
                 │  Report  │*---------1│
                 │(工作报告) │          │
                 └──────────┘          │
                                        │
                 ┌──────────┐          │
                 │AuditLog  │*---------1│
                 │(审计日志) │          │
                 └──────────┘

POST /api/v1/webhooks/telecom/call-event
Headers: X-Telecom-Signature: {HMAC-SHA256}
Body: {
  "event_type": "call_completed",
  "call_id": "CL20260731143052_18117132919",
  "tenant_id": "TENANT_PTNSRCB",
  "phone_number": "18117132919",
  "call_direction": "outgoing",
  "callee_number": "13805061234",
  "start_time": "2026-07-31T14:30:52+08:00",
  "end_time": "2026-07-31T14:33:28+08:00",
  "duration_seconds": 156,
  "connect_status": "connected"  # connected/missed/busy/failed
}
Response: { "code": 0, "message": "ok" }

POST /api/v1/webhooks/telecom/recording-ready
Headers: X-Telecom-Signature: {HMAC-SHA256}
Body: {
  "event_type": "recording_ready",
  "call_id": "CL20260731143052_18117132919",
  "tenant_id": "TENANT_PTNSRCB",
  "recording_url": "https://oss.ctyun.cn/rec/CL20260731143052_18117132919.wav",
  "duration_seconds": 156,
  "file_size_bytes": 2512000
}
Response: { "code": 0, "message": "ok" }

POST {ASR_SERVICE_URL}/api/v1/asr
Headers: Authorization: Bearer {token}
Body: {
  "audio_url": "https://oss.ctyun.cn/rec/CL20260731143052.mp3",
  "language": "zh-CN",
  "dialect": "minnan",  # 闽南语自适应
  "speaker_diarization": true,  # 说话人分离
  "enable_punctuation": true
}
Response: {
  "task_id": "ASR_TASK_001",
  "status": "processing"
}
# 异步回调
POST /api/v1/webhooks/asr/result
Body: {
  "task_id": "ASR_TASK_001",
  "status": "completed",
  "full_text": "您好，我是莆田农商行的...",
  "segments": [{ "start_ms": 0, "end_ms": 3200, "speaker": "agent", "text": "..." }],
  "accuracy_score": 0.88
}

POST {NLP_SERVICE_URL}/api/v1/emotion-analysis
Body: {
  "audio_url": "https://oss.ctyun.cn/rec/CL20260731143052.mp3",
  "segments": [{ "start_ms": 0, "end_ms": 3200, "speaker": "agent" }]
}
Response: {
  "emotions": [{
    "segment_index": 0,
    "speaker": "agent",
    "emotion": "neutral",
    "intensity": 0.5,
    "valence": 0.7  # -1(消极) ~ 1(积极)
  }]
}

POST {SMS_SERVICE_URL}/api/v1/sms/send
Body: {
  "phone_number": "18117132919",
  "template_code": "MISSED_CALL_ALERT",
  "template_params": {
    "caller_number": "13805061234",
    "call_time": "10:15"
  }
}
Response: { "code": 0, "message_id": "MSG_001" }