Initial LisgloSIPS V2 implementation

SOFTSWITCH_PLATFORM_DESIGN_V1.md

@@ -0,0 +1,766 @@
+# 自研软交换运营平台 V1 产品设计文档
+
+## 1. 系统定位
+
+本系统定位为基于 OpenSIPS + RTPEngine 的软交换运营平台，用于支撑多客户、多供应商、多线路组、费率计费、话单查询、录音质检和 SIP 运维。
+
+OpenSIPS 负责 SIP 信令控制、注册鉴权、路由选择、话单基础数据和与媒体代理的协同。RTPEngine 负责 RTP 媒体转发、NAT 穿透和录音能力。自研平台负责客户、供应商、费率、账单、质检、权限、报表等业务运营能力。
+
+推荐定位：
+
+- OpenSIPS-CP：V1 保留，作为技术运维后台，用于排障和底层配置。
+- 自研平台：业务运营后台，用于客户、计费、线路、话单、质检和权限管理。
+
+## 2. 目标用户角色
+
+### 2.1 超级管理员
+
+负责全局配置、租户/客户管理、供应商管理、系统参数、权限和安全策略。
+
+### 2.2 运营管理员
+
+负责客户开通、线路组配置、路由策略、时段控制、话单查询和日常运营。
+
+### 2.3 财务人员
+
+负责客户费率、供应商费率、账单、成本、利润、充值、授信和对账。
+
+### 2.4 质检人员
+
+负责录音抽检、录音试听、质检标注、问题分类和质检报告。
+
+### 2.5 技术运维
+
+负责 SIP Trace、在线通话、注册状态、网关状态、OpenSIPS/RTPEngine 监控和故障排查。
+
+### 2.6 客户账号
+
+V1 不包含客户登录端。客户侧能力暂不开放独立门户，仅保留内部运营后台使用。
+
+## 3. 一级菜单设计
+
+```text
+运营平台
+├── 概览 Dashboard
+├── 客户管理
+├── 供应商管理
+├── 线路与路由
+├── 费率与计费
+├── 话单中心
+├── 质检中心
+├── SIP 运维
+├── 监控告警
+├── 系统设置
+└── 权限与审计
+```
+
+## 4. 页面功能设计
+
+## 4.1 概览 Dashboard
+
+用途：展示平台整体运行状态。
+
+核心卡片：
+
+- 今日通话数
+- 当前在线通话数
+- 今日接通率
+- 今日客户消费
+- 今日供应商成本
+- 今日毛利
+- 在线注册用户数
+- RTPengine 节点状态
+- OpenSIPS 节点状态
+- 异常网关数量
+- 质检待处理数量
+
+主要图表：
+
+- 最近 24 小时通话量趋势
+- 最近 24 小时接通率趋势
+- 客户消费 TOP 10
+- 供应商成本 TOP 10
+- 失败响应码分布
+
+OpenSIPS/RTPEngine 对接点：
+
+- OpenSIPS MI：`ps`、`get_statistics`、`dlg_list`
+- OpenSIPS DB：CDR 表、subscriber/location 表
+- RTPEngine 控制接口：节点状态
+
+## 4.2 客户管理
+
+### 客户列表
+
+字段：
+
+- 客户 ID
+- 客户名称
+- SIP 域名
+- 认证方式
+- 网关数量
+- 状态
+- 余额
+- 授信额度
+- 计费模式
+- 线路组
+- 创建时间
+
+操作：
+
+- 新增客户
+- 编辑客户
+- 禁用/启用客户
+- 配置费率
+- 配置线路组
+- 查看话单
+- 查看账单
+
+### 客户详情
+
+模块：
+
+- 基本信息
+- SIP 账号
+- 客户网关
+- IP 白名单
+- 费率方案
+- 线路组
+- 外呼时段
+- 余额/授信
+- 录音质检策略
+- 操作日志
+
+### 客户网关与业务策略
+
+设计要求：
+
+- 同一个客户可配置多个接入网关。
+- 每个客户网关可单独开启或关闭录音。
+- 同一个客户下，不同客户网关来源 IP + 不同被叫前缀，可映射到不同业务。
+- 每个业务映射项需绑定对应客户费率和落地网关组。
+
+建议字段：
+
+- 客户
+- 客户网关 ID
+- 来源 IP
+- 被叫前缀
+- 业务名称
+- 录音开关
+- 客户费率方案
+- 落地网关组
+- 优先级
+- 状态
+
+OpenSIPS 对接点：
+
+- `subscriber`：SIP 用户认证
+- `domain`：客户域名
+- `address`：客户 IP 白名单
+- `dr_groups`：客户所属路由组
+
+## 4.3 供应商管理
+
+### 供应商列表
+
+字段：
+
+- 供应商 ID
+- 供应商名称
+- 网关数量
+- 状态
+- 结算周期
+- 费率方案
+- 联系人
+- 创建时间
+
+操作：
+
+- 新增供应商
+- 编辑供应商
+- 禁用/启用供应商
+- 管理网关
+- 管理供应商费率
+- 查看成本话单
+
+### 落地网关
+
+字段：
+
+- 网关 ID
+- 供应商
+- SIP 地址
+- 端口
+- 协议
+- 权重
+- 优先级
+- 探测模式
+- 当前状态
+- 描述
+
+### 供应商网关业务策略
+
+设计要求：
+
+- 同一个供应商可配置多个落地网关。
+- 同一个网关下，可按不同被叫前缀区分业务。
+- 同一个网关下，也可按不同主叫号码或主叫号段区分业务。
+- 每个业务映射项需绑定对应供应商费率，用于成本结算。
+
+建议字段：
+
+- 供应商
+- 网关 ID
+- 主叫号码/号段
+- 被叫前缀
+- 业务名称
+- 供应商费率方案
+- 优先级
+- 状态
+
+OpenSIPS 对接点：
+
+- `dr_gateways`
+- `dispatcher`
+- `drouting` MI：`dr_gw_status`、`dr_reload`
+
+## 4.4 线路与路由
+
+### 线路组
+
+用途：把多个供应商网关组合成一个客户可使用的落地线路池。
+
+字段：
+
+- 线路组 ID
+- 线路组名称
+- 适用客户
+- 网关列表
+- 路由策略
+- 失败重试策略
+- 状态
+
+路由策略：
+
+- 按优先级
+- 按权重
+- 按成本最低
+- 按接通率
+- 按号码前缀
+- 按时段
+
+### 路由规则
+
+字段：
+
+- 规则 ID
+- 客户/客户组
+- 号码前缀
+- 线路组
+- 优先级
+- 生效时间
+- 状态
+- 备注
+
+补充规则：
+
+- 客户侧优先按客户网关 + 来源 IP 识别接入入口。
+- 在接入入口下继续按被叫前缀识别业务。
+- 识别出业务后绑定客户费率和落地网关组。
+- 供应商侧优先按供应商网关匹配，再按被叫前缀或主叫号码匹配成本业务和费率。
+
+OpenSIPS 对接点：
+
+- `dr_rules`
+- `dr_groups`
+- `dr_carriers`
+- `dialplan`
+
+## 4.5 费率与计费
+
+### 客户费率
+
+字段：
+
+- 客户
+- 业务名称
+- 客户网关（可选）
+- 国家/地区
+- 号码前缀
+- 单价
+- 计费周期
+- 首周期
+- 生效时间
+- 失效时间
+
+计费周期示例：
+
+- 1/1：按秒计费
+- 6/6：每 6 秒一个计费单位
+- 60/60：按分钟计费
+- 60/6：首分钟，之后每 6 秒
+
+### 供应商费率
+
+字段类似客户费率，但用于计算成本。
+
+补充维度：
+
+- 供应商
+- 供应商网关（可选）
+- 主叫号码/号段（可选）
+- 被叫前缀
+- 业务名称
+
+### Billing Worker
+
+职责：
+
+- 读取未计费 CDR
+- 识别客户业务
+- 匹配客户费率
+- 识别供应商业务
+- 匹配供应商费率
+- 按计费周期计算客户费用
+- 按计费周期计算供应商成本
+- 计算毛利
+- 写入已计费话单
+- 更新余额或授信占用
+
+计费公式示例：
+
+```text
+计费秒数 = ceil(实际通话秒数 / 计费周期) * 计费周期
+客户费用 = 计费秒数 / 60 * 客户分钟单价
+供应商成本 = 计费秒数 / 60 * 供应商分钟单价
+毛利 = 客户费用 - 供应商成本
+```
+
+OpenSIPS 对接点：
+
+- `acc`
+- `dialog`
+- CDR 表
+- 自研 billing 表
+
+## 4.6 话单中心
+
+### 原始 CDR
+
+字段：
+
+- Call-ID
+- 客户
+- 客户网关
+- 来源 IP
+- 主叫
+- 被叫
+- 业务名称
+- 开始时间
+- 接通时间
+- 结束时间
+- 通话时长
+- 计费时长
+- SIP 响应码
+- 供应商
+- 网关
+- 路由规则
+- 录音状态
+
+### 已计费话单
+
+字段：
+
+- 原始 CDR ID
+- 客户费率
+- 供应商费率
+- 客户费用
+- 供应商成本
+- 毛利
+- 计费状态
+- 计费时间
+
+操作：
+
+- 查询
+- 导出 CSV
+- 重新计费
+- 查看 SIP Trace
+- 查看录音
+- 页面内试听录音
+- 查看命中业务、客户费率、供应商费率和路由规则
+
+## 4.7 质检中心
+
+### 抽检规则
+
+字段：
+
+- 客户
+- 抽检比例
+- 指定号码
+- 指定线路
+- 最小时长
+- 最大时长
+- 是否录音
+- 生效时间
+
+### 录音列表
+
+字段：
+
+- Call-ID
+- 客户
+- 主叫
+- 被叫
+- 通话时间
+- 通话时长
+- 录音文件
+- 质检状态
+- 试听操作
+
+### 录音详情
+
+功能：
+
+- 播放录音
+- 查看录音基础信息
+- 标注问题
+- 打分
+- 导出质检报告
+
+RTPEngine 对接点：
+
+- RTPEngine 录音能力
+- recording daemon
+- 录音文件存储
+
+外部服务：
+
+- 对象存储，例如 MinIO/S3
+
+## 4.8 SIP 运维
+
+页面：
+
+- 在线注册
+- 在线通话
+- SIP Trace
+- 网关状态
+- Domain 管理
+- Address 白名单
+- Dispatcher
+- Dynamic Routing
+- RTPEngine 状态
+
+用途：
+
+- 给技术运维排障
+- 不建议直接暴露给普通业务人员
+
+OpenSIPS 对接点：
+
+- `usrloc`
+- `dialog`
+- `tracer`
+- `dispatcher`
+- `drouting`
+- `domain`
+- `permissions`
+- `rtpengine`
+
+## 4.9 监控告警
+
+监控项：
+
+- OpenSIPS 进程状态
+- OpenSIPS MI 是否可用
+- RTPEngine 节点是否可用
+- SIP 5060 是否监听
+- RTP 端口范围是否开放
+- 数据库连接
+- CDR 堆积
+- Billing Worker 堆积
+- 录音文件入库任务堆积
+- 磁盘空间
+
+告警方式：
+
+- 邮件
+- 企业微信/钉钉/飞书
+- 短信
+
+推荐工具：
+
+- Prometheus
+- Grafana
+- Loki 或 ELK
+- Alertmanager
+- Monit
+
+## 4.10 系统设置
+
+页面：
+
+- SIP 域名
+- 监听地址
+- MI 连接配置
+- RTPengine 节点
+- 录音存储
+- 全局计费参数
+- 时区与时间格式
+- 安全策略
+
+## 4.11 权限与审计
+
+### 角色权限
+
+角色示例：
+
+- 超级管理员
+- 运营管理员
+- 财务
+- 质检
+- 技术运维
+- 客户只读账号
+
+### 操作日志
+
+记录：
+
+- 登录
+- 新增/修改/删除客户
+- 修改费率
+- 修改路由
+- 手动重计费
+- 下载录音
+- 导出话单
+
+## 5. 核心业务流程
+
+## 5.1 客户开通流程
+
+```text
+新增客户
+  -> 分配 SIP 域名或账号
+  -> 配置 IP 白名单或 SIP 账号密码
+  -> 配置客户网关
+  -> 配置客户网关录音开关
+  -> 配置客户网关业务策略
+  -> 配置客户费率
+  -> 配置线路组
+  -> 配置外呼时段
+  -> 启用客户
+  -> OpenSIPS reload 对应模块
+```
+
+## 5.2 外呼流程
+
+```text
+客户发起 INVITE
+  -> OpenSIPS 判断来源 IP/账号
+  -> 识别客户
+  -> 识别客户网关
+  -> 检查客户状态和余额
+  -> 检查外呼时段
+  -> 按被叫前缀识别客户业务
+  -> 匹配客户费率
+  -> 选择落地网关组
+  -> 选择供应商网关
+  -> 按供应商网关 + 被叫前缀/主叫号码识别供应商业务
+  -> 调用 RTPEngine 处理媒体
+  -> 生成 Dialog/CDR
+  -> 通话结束后 Billing Worker 计费
+```
+
+## 5.3 呼入分发流程
+
+```text
+上游呼入到 SIP 域名
+  -> OpenSIPS domain 判断
+  -> 根据域名/DID/客户规则匹配目标
+  -> dispatcher 或 drouting 分发到后端服务器
+  -> 记录 CDR
+```
+
+## 5.4 计费流程
+
+```text
+通话结束
+  -> OpenSIPS 写入原始 CDR
+  -> Billing Worker 拉取未计费 CDR
+  -> 识别客户业务
+  -> 匹配客户费率
+  -> 识别供应商业务
+  -> 匹配供应商费率
+  -> 计算费用和成本
+  -> 写入已计费话单
+  -> 更新客户余额/授信
+  -> 生成账单统计
+```
+
+## 5.5 质检流程
+
+```text
+通话建立
+  -> 判断是否命中录音规则
+  -> OpenSIPS 控制 RTPEngine 录音
+  -> 通话结束生成录音文件
+  -> 录音入库
+  -> 质检人员页面试听录音
+  -> 标注问题并生成报告
+```
+
+## 6. 建议数据库模块
+
+业务库建议和 OpenSIPS 原生库分开，避免升级 OpenSIPS 时互相影响。
+
+```text
+opensips 原生库：
+- subscriber
+- location
+- domain
+- address
+- dialog
+- acc / cdr
+- dr_gateways
+- dr_rules
+- dr_groups
+- dispatcher
+- rtpengine
+- sip_trace
+
+业务库：
+- customers
+- customer_accounts
+- customer_rate_plans
+- customer_rates
+- customer_gateways
+- customer_gateway_policies
+- vendors
+- vendor_gateways
+- vendor_rate_plans
+- vendor_rates
+- vendor_gateway_policies
+- route_groups
+- route_group_items
+- outbound_time_policies
+- raw_cdrs
+- rated_cdrs
+- invoices
+- balances
+- recordings
+- quality_reviews
+- users
+- roles
+- permissions
+- audit_logs
+```
+
+## 7. 与 OpenSIPS/RTPEngine 的边界
+
+OpenSIPS 负责：
+
+- SIP 协议
+- 鉴权
+- 注册
+- 路由
+- 通话状态
+- MI 控制
+- CDR 基础数据
+
+RTPEngine 负责：
+
+- RTP 转发
+- NAT 穿透
+- 媒体锚定
+- 录音
+
+自研平台负责：
+
+- 客户管理
+- 供应商管理
+- 费率
+- 计费
+- 账单
+- 质检
+- 权限
+- 报表
+- 审计
+
+## 8. V1 优先级建议
+
+### P0：先跑通运营闭环
+
+- 客户管理
+- 供应商管理
+- 线路组
+- 客户费率
+- 供应商费率
+- 原始 CDR
+- Billing Worker
+- 已计费话单
+- 预付费余额实时控制
+- Dashboard 基础指标
+
+### P1：提升运营能力
+
+- 时段控制
+- 授信管理
+- 账单
+- 导出
+- 网关健康状态
+- SIP Trace 跳转
+
+### P2：质检和录音运营
+
+- 录音规则
+- 录音列表
+- 录音试听
+- 质检标注
+- 质检报表
+
+### P3：高可用和企业化
+
+- 多 OpenSIPS 节点
+- 多 RTPEngine 节点
+- 数据库高可用
+- 多角色权限
+- 审计日志
+- 告警中心
+
+## 9. Figma 原型页面清单
+
+建议优先画这些页面：
+
+1. Dashboard
+2. 客户列表
+3. 客户详情
+4. 客户费率
+5. 供应商列表
+6. 落地网关
+7. 线路组
+8. 路由规则
+9. 原始 CDR
+10. 已计费话单
+11. 账单详情
+12. 录音列表
+13. 录音详情
+14. SIP 运维概览
+15. 系统设置
+
+## 10. V1 范围确认
+
+已确认范围：
+
+- 不需要客户登录端。
+- 需要预付费余额实时控制。
+- 不需要多 OpenSIPS 节点，V1 按单节点设计。
+- 保留 OpenSIPS-CP，作为技术运维后台。
+
+按以上范围进入下一阶段：
+
+```text
+产品原型 -> 数据库设计 -> API 设计 -> OpenSIPS 脚本改造 -> Billing Worker -> 前端开发
+```