OmniCRM 系统架构
本文档提供了 OmniCRM 系统架构的概述，包括组件关系和数据流。
高级系统概述
OmniCRM 是一个综合的 BSS/OSS 平台，集成了多个关键组件，为电信提供商提供完整的服务管理。
核心组件
1. 前端应用
OmniCRM Web UI
- React 单页面应用
- 客户管理、服务配置、计费的员工界面
- 实时配置状态更新
- 基于角色的访问控制
自助服务门户
- 面向客户的门户
- 服务管理和使用跟踪
- 发票查看和支付
- 与员工 UI 共享代码库，不同视图
2. API 层
OmniCRM API (Flask/Python)
- 所有操作的 RESTful API
- OpenAPI/Swagger 文档
- 基于 JWT 的认证
- 速率限制和缓存
- WebSocket 支持实时更新
关键 API 路由：
/crm/customer/*- 客户管理/crm/service/*- 服务操作/crm/product/*- 产品目录/crm/provision/*- 配置操作/crm/transaction/*- 计费交易/crm/invoice/*- 发票管理
3. 配置系统
4. 计费与评级
OCS/CGRateS 集成
- 实时收费和评级
- 账户管理
- 余额跟踪（货币、数据、语音、短信）
- 定期收费的行动计划
- 基于阈值的通知
计费工作流：
5. 数据模型
OmniCRM 使用关系数据库，具有以下核心模型。有关可视化实体关系图，请参见 客户、联系人、站点和服务。
客户及相关实体
客户 - 代表公司或个人的中心实体
| 字段 | 类型 | 描述 |
|---|---|---|
| customer_id | 整数 (PK) | 唯一标识符 |
| customer_name | 字符串 | 公司或个人名称 |
| customer_account_type | 枚举 | '个人' 或 '企业' |
| customer_status | 枚举 | '开放', '关闭', '暂停', '归档' |
| customer_payment_type | 字符串 | '预付' 或 '后付' |
| customer_enabled | 布尔 | 账户是否活跃 |
| tax_identifier | 字符串 | VAT/GST 号码 |
| contract_start_date | 日期时间 | 合同开始 |
| contract_end_date | 日期时间 | 合同结束 |
��系人 - 与客户相关联的人
| 字段 | 类型 | 描述 |
|---|---|---|
| contact_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 父客户 |
| contact_firstname | 字符串 | 名字 |
| contact_lastname | 字符串 | 姓氏 |
| contact_email | 字符串 | 电子邮件地址 |
| contact_phone | 字符串 | 电话号码 |
| contact_types | 字符串 | '主要', '计费', '技术' |
站点 - 实体服务交付地点
| 字段 | 类型 | 描述 |
|---|---|---|
| site_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 父客户 |
| site_name | 字符串 | 位置名称 |
| address_line_1 | 字符串 | 街道地址 |
| city, state, zip_code | 字符串 | 位置详情 |
| latitude, longitude | 浮点 | GPS 坐标 |
| google_maps_place_id | 字符串 | Google Maps 参考 |
| plus_code | 字符串 | 开放位置代码 |
服务与产品模型
服务 - 活动服务实例
| 字段 | 类型 | 描述 |
|---|---|---|
| service_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 父客户 |
| product_id | 整数 (FK) | 产品模板 |
| site_id | 整数 (FK) | 服务位置 |
| service_name | 字符串 | 显示名称 |
| service_uuid | 字符串 | 计费系统标识符 |
| service_status | 枚举 | 当��状态 |
| service_billed | 布尔 | 生成交易 |
| wholesale_cost | 浮点 | 供应商成本 |
| retail_cost | 浮点 | 客户价格 |
| bundled_parent | 整数 (FK) | 捆绑的父服务 |
产品 - 服务提供模板
| 字段 | 类型 | 描述 |
|---|---|---|
| product_id | 整数 (PK) | 唯一标识符 |
| product_name | 字符串 | 显示名称 |
| product_slug | 字符串 | 友好的 URL 名称 |
| category | 枚举 | '独立', '捆绑', '附加', '促销' |
| provisioning_play | 字符串 | Ansible playbook 名称 |
| provisioning_json_vars | JSON | Playbook 变量 |
| inventory_items_list | 字符串 | 所需库存 |
| retail_cost | 浮点 | 月费 |
| retail_setup_cost | 浮点 | 一次性费用 |
| enabled | 布尔 | 可供销售 |
计费模型
交易 - 单个收费/信用
| 字段 | 类型 | 描述 |
|---|---|---|
| transaction_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 父客户 |
| invoice_id | 整数 (FK) | 父发票（可选） |
| service_id | 整数 (FK) | 相关服务 |
| title | 字符串 | 交易描述 |
| retail_cost | 浮点 | 金额 |
| tax_percentage | 浮点 | 税率 |
| tax_amount | 浮点 | 计算的税 |
| void | 布尔 | 取消的交易 |
发票 - 计费的分组交易
| 字段 | 类型 | 描述 |
|---|---|---|
| invoice_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 父客户 |
| paid | 布尔 | 收到付款 |
| void | 布尔 | 取消的发票 |
| payment_reference | 字符串 | Stripe 交易 ID |
| start_date, end_date | 日期 | 计费周期 |
| due_date | 日期 | 付款截止日期 |
| retail_cost | 浮点 | 总金额 |
库存模型
库存 - 实体和虚拟资产
| 字段 | 类型 | 描述 |
|---|---|---|
| inventory_id | 整数 (PK) | 唯一标识符 |
| customer_id | 整数 (FK) | 指定客户 |
| service_id | 整数 (FK) | 关联服务 |
| inventory_template_id | 整数 (FK) | 项目类型模板 |
| item | 字符串 | 项目类型（SIM 卡、路由器等） |
| item_state | 枚举 | '新', '已分配', '已使用' 等 |
| itemtext1-20 | 字符串 | 灵活字段 |
| management_url | 字符串 | 设备管理 URL |
| config_content | 文本 | 配置文件 |
库存模板 - 定义库存项目结构
| 字段 | 类型 | 描述 |
|---|---|---|
| inventory_template_id | 整数 (PK) | 唯一标识符 |
| item | 字符串 | 模板名称 |
| itemtext1_label | 字符串 | itemtext1 字段的标签 |
| itemtext2_label | 字符串 | itemtext2 字段的标签 |
配置模型
配置 - 配置作业跟踪
| 字段 | 类型 | 描述 |
|---|---|---|
| provision_id | 整数 (PK) | 唯一标识符 |
| product_id | 整数 (FK) | 正在配置的产品 |
| customer_id | 整数 (FK) | 目标客户 |
| service_id | 整数 (FK) | 创建/修改的服务 |
| provisioning_play | 字符串 | Ansible playbook 名称 |
| provisioning_status | 整数 | 0=成功, 1=运行中, 2=失败 |
配置事件 - 单个配置步骤
| 字段 | 类型 | 描述 |
|---|---|---|
| provision_event_id | 整数 (PK) | 唯一标识符 |
| provision_id | 整数 (FK) | 父配置作业 |
| event_name | 字符串 | 任务名称 |
| event_number | 整数 | 序列号 |
| provisioning_status | 整数 | 0=成功, 1=运行中, 2=失败 |
| provisioning_result_json | JSON | 完整任务输出 |
用户与安全模型
用户 - 用户账户
| 字段 | 类型 | 描述 |
|---|---|---|
| id | 整数 (PK) | 唯一标识符 |
| username | 字符串 | 登录用户名 |
| 字符串 | 电子邮件地址 | |
| email_verified | 布尔 | 电子邮件已确认 |
| is_2fa_enabled | 布尔 | 启用双因素认证 |
| totp_secret | 字符串 | TOTP 密钥 |
角色 - 用户角色
| 字段 | 类型 | 描述 |
|---|---|---|
| id | 整数 (PK) | 唯一标识符 |
| name | 字符串 | 角色��称 |
| description | 字符串 | 角色描述 |
权限 - 细粒度权限
| 字段 | 类型 | 描述 |
|---|---|---|
| id | 整数 (PK) | 唯一标识符 |
| name | 字符串 | 权限名称（资源.操作） |
| description | 字符串 | 权限描述 |
关系：
- 用户有多个角色（多对多）
- 角色有多个权限（多对多）
- 用户可以链接到一个联系人（用于客户门户访问）
集成点
Stripe 支付网关
- 令牌化支付方式
- 符合 PCI 的卡存储
- 自动发票支付
- 退款处理
- 卡过期通知
Mailjet 电子邮件服务
- 事务性电子邮件（发票、欢迎、通知）
- 联系人同步
- 模板管理
- 投递跟踪
Google Maps
- 地址自动补全
- 地理编码和反向地理编码
- Plus Code 生成
- 站点位置映射
OCS/CGRateS
- 账户配置
- 实时评级
- 余额管理
- CDR 处理
- 行动计划和时间表
安全架构
安全特性：
- 基于 JWT 的认证
- 双因素认证（TOTP）
- 基于角色的访问控制（RBAC）
- 基于权限的资源访问
- 使用 Redis 的会话管理
- 密码哈希（bcrypt）
- 电子邮件验证
- 通过活动日志进行审计记录
部署架构
推荐的生产设置：
技术栈
后端：
- Python 3.x
- Flask Web 框架
- SQLAlchemy ORM
- Alembic 迁移
- Ansible 用于自动化
前端：
- React
- 状态管理
- React Router
- Axios 用于 API 调用
数据库：
- 关系数据库（主数据存储）
- Redis（缓存和会话）
外部服务：
- CGRateS（计费/评级）
- Stripe（支付）
- Mailjet（电子邮件）
- Google Maps（地理编码）
可扩展性考虑
水平扩展：
- 无状态 API 设计允许多个实例
- 负载均衡器分配请求
- Redis 用于共享会话状态
数据库扩展：
- 读取副本用于报告查询
- 连接池
- 查询优化和索引
大规模配置：
- 后台作业处理
- 多个 Ansible 工作进程
- 作业队列管理
- 失败配置的重试逻辑
监控与可观察性
关键指标：
- API 响应时间
- 配置成功/失败率
- 数据库连接池使用
- 缓存命中率
- 活动会话
日志记录：
- 应用日志（Flask）
- 配置日志（Ansible 输出）
- 活动日志（审计轨迹）
- 错误跟踪和警报
相关文档
- Ansible Playbooks - 配置自动化
- 配置系统 - 工作流细节
- 产品和服务 - 产品架构
- API 文档 - API 参考
- RBAC - 安全与权限