文章目录
- 1. 项目概述
- 1.1 项目背景
- 1.2 产品定位
- 1.3 服务角色业务
- 2. 整体技术架构
- 3. 各模块功能总览
- 1. auth — 认证授权
- 2. ticket — 工单核心
- 3. quotation — 服务报价
- 4. order — 服务订单
- 5. payment — 支付中心
- 6. ai — AI 集成
- 7. knowledge — 知识库
- 8. statistics — 统计分析
- 9. file — 文件上传
- 10. user — 用户管理
- 11. middleware — 中间件
- 12. shared — 基础设施
- 13. tasks — MQ 消费者
- 4. Redis、RabbitMQ、Elasticsearch使用场景
- 4.1 Redis使用场景
- 4.2 RabbitMQ使用场景
- 1. 交换机
- 2. 业务事件
- 3. DLX 延迟消息原理
- 4. 兜底机制
- 4.3 Elasticsearch使用场景
- 1. 索引
- 2. 搜索
- 3. 降级策略
- 4. ES 初始化
- 5. 项目核心业务流转图
- 6. 项目总结
1. 项目概述
1.1 项目背景
在企业IT外包、设备售后、技术支持等商业化服务场景中，传统工单系统普遍存在服务计费混乱、流程断裂、管理黑盒等核心痛点：
- 故障上报渠道分散，问题分类依赖人工经验，响应效率低；
- 服务报价、订单、支付线下流转，对账困难，收费标准不透明；
- 现场服务易出现隐性故障，追加费用流程不规范，易产生纠纷；
- 同类问题重复处理，历史经验难沉淀。
1.2 产品定位
「智枢」定位为AI驱动的商业化售后服务一体化平台，以「工单协同为核心、AI智能辅助为亮点、服务计费为闭环」，覆盖「报障→AI诊断→服务报价→订单支付→派单→工程师处理→知识库辅助→验收评价→AI总结沉淀」全链路，为企业售后、IT外包、技术支持团队提供可落地、可量化、可盈利的完整解决方案。
核心说明：本项目核心是技术服务交付，支付仅作为服务费用的结算环节，主体是工单服务全生命周期管理，并非实物商品交易。
1.3 服务角色业务
| 角色 | 权限说明 |
|---|
| 客户 | 提交报修工单、查看报价、确认报价、支付订单、验收评分 |
| 工程师 | 接收派单、提交报价、受理工单、处理工单、提交报告、查看知识库、AI问答 |
| 管理员 | 全局工单管理、超时人工派单、用户管理、知识库审核、数据统计、审计日志 |
2. 整体技术架构
技术栈: FastAPI + SQLAlchemy 2.0 异步 + MySQL 8.0 + RabbitMQ 3.12 + Redis 7.0 + Elasticsearch 8.10 + Vue 3 + TypeScript
项目完成后通过Docker部署在阿里云ECS服务器上。
3. 各模块功能总览
1. auth — 认证授权
| 功能 | 说明 |
|---|
| 密码登录 | 用户名/手机号 + 密码 |
| 短信登录 | 手机号 + 阿里云短信验证码 |
| 短信注册 | 短信验证码 + 密码创建客户账号 |
| JWT Token | access_token + refresh_token 双令牌 |
| RBAC 鉴权 | get_current_user+require_role(customer/engineer/admin) |
| 登出黑名单 | Token 加入 Redis 黑名单，TTL 内不可用 |
| 角色缓存 | 用户角色信息 Redis 缓存 60s |
2. ticket — 工单核心
| 功能 | 说明 |
|---|
| 客户创建工单 | POST /api/v1/tickets，自动 AI 诊断 + 多方派单 |
| 客户取消工单 | pending/quoting/quoted/paying 状态可取消 |
| 客户验收评价 | confirming → completed，评分 1-5 星 |
| 工程师受理 | 接受工单处理任务 |
| 工程师处理日志 | 逐条追加处理记录 |
| 工程师保存/提交报告 | report 草稿 / submit 跳转 confirming |
| 管理员全局查询 | 多维度筛选（状态/优先级/搜索） |
| 管理员手动派单 | manual_dispatch → 指定工程师 + 定价 |
| 管理员关闭工单 | 带原因关闭 |
| 管理员状态跳转 | quoting/quoted → processing（跳过报价/支付） |
| ES 搜索 | 工单标题+描述全文检索，标题权重 x2 |
| 状态机 | 9 状态 × 角色权限矩阵（state_machine.py） |
3. quotation — 服务报价
| 功能 | 说明 |
|---|
| 工程师创建主报价 | POST /api/v1/engineer/quotations |
| 工程师追加报价 | POST /api/v1/engineer/quotations/additional，24h 超时作废 |
| 工程师查看已报价 | 我的报价列表 |
| 工程师查看待报价 | 待报价工单（派单）列表 |
| 客户查看报价 | 单个工单下所有报价 |
| 客户选择报价 | select选定中标 + 其余 rejected |
| 客户确认报价 | confirm→ 锁定报价 + 生成订单 |
| 客户驳回报价 | reject单条驳回 |
| 状态机 | 6 状态（draft/pending/confirmed/locked/rejected/expired） |
4. order — 服务订单
| 功能 | 说明 |
|---|
| 自动生成订单 | 客户确认报价后自动创建（pending） |
| 金额校验 | 订单金额以服务端报价单为准 |
| 管理员订单列表 | GET /api/v1/admin/orders |
| 订单详情 | 含关联工单信息 |
| 状态机 | 4 状态（pending/paid/cancelled/completed） |
5. payment — 支付中心
| 功能 | 说明 |
|---|
| 发起支付 | POST /api/v1/payment/create/{order_id}，支持 wechat/alipay |
| Mock 支付 | 开发环境自动触发回调 |
| 支付回调 | 微信/支付宝签名验证 |
| 三重幂等 | Redis 分布式锁 + pay_no 唯一索引 + 状态检查 |
| 金额二次校验 | 回调金额 vs 服务端订单金额 |
| Lua 锁释放 | 仅持有者可释放 Redis 锁 |
| MQ 事件 | 支付成功发布payment.success |
6. ai — AI 集成
| 功能 | 说明 |
|---|
| AI 故障诊断 | POST /api/v1/ai/diagnosis，调 Dify 诊断工作流 |
| RAG 知识问答 | POST /api/v1/ai/rag/query，工程师检索知识库 |
| AI 工单总结 | POST /api/v1/ai/summary/{ticket_id}，工单关闭后生成总结 |
| 双客户端 | Mock（开发/测试）+ Dify Cloud（生产） |
| 降级策略 | AI 不可用时返回默认值，不阻塞主流程 |
| 任务记录 | ai_task表记录每次调用输入/输出/状态 |
7. knowledge — 知识库
| 功能 | 说明 |
|---|
| 文章 CRUD | 管理员创建/编辑/删除 |
| 草稿审核 | AI 生成草稿 → 管理员审核 → 发布/驳回 |
| 分类管理 | 知识库分类 CRUD |
| ES 搜索 | 全文检索优先 ES，降级 MySQL LIKE |
| ES 同步 | 发布/更新/删除时异步同步到 ES |
8. statistics — 统计分析
| 功能 | 说明 |
|---|
| 概览统计 | 工单总数/活跃数/完成数/总营收 |
| 工单分布 | 按状态 + 按优先级 GROUP BY |
| 工程师绩效 | TOP 20 解决工单数 + 评分 |
| 财务统计 | 总营收 + 订单总数 |
| Redis 缓存 | 4 个端点均缓存 60s，失败静默降级 |
9. file — 文件上传
| 功能 | 说明 |
|---|
| 上传 | POST /api/v1/files/upload，本地磁盘存储 |
| 查询 | 按工单 ID 查附件列表 |
| 删除 | 同时删除磁盘文件 |
| MIME 校验 | 白名单 + 魔法数字检测（jpg/png/gif/webp） |
10. user — 用户管理
| 功能 | 说明 |
|---|
| 管理员 CRUD | 创建/编辑/重置密码/启用禁用 |
| 工程师自助 | 个人设置 |
| 工程师画像 | rating/avg_resolve_time/total_resolved 增量更新 |
11. middleware — 中间件
| 中间件 | 功能 |
|---|
| CORS | 跨域允许 |
| RequestID | 为每个请求分配唯一 ID |
| 日志 | 请求/响应日志记录 |
| 限流 | 登录 5次/分钟、创建工单 10次/分钟、支付 10次/分钟（DEBUG 跳过） |
| 状态校验 | 部分端点校验前置状态 |
12. shared — 基础设施
| 模块 | 功能 |
|---|
database.py | SQLAlchemy 2.0 异步引擎 + session 工厂 |
redis.py | Redis 连接池 +get_redis依赖注入 |
rabbitmq.py | RabbitMQ 连接 + 交换机/队列声明 |
elasticsearch.py | ES 客户端初始化 |
event_publisher.py | MQ 事件发布 + DLX 延迟消息 |
es_sync.py | ES 异步同步发布工具（publish_sync/index_document/delete_document/search_index/ensure_indexes） |
response.py | 统一响应格式APIResponse.ok()/APIResponse.fail() |
audit.py | 审计日志写入（write_audit） |
sms.py | 阿里云短信发送客户端 |
pagination.py | 分页工具 |
13. tasks — MQ 消费者
| 消费者 | 消费队列 | 功能 |
|---|
ai_tasks.py | ticket.created | AI 故障诊断 + 多方竞价派单 |
ai_tasks.py | ticket.closed | AI 工单总结 + 知识库草稿 |
payment_tasks.py | payment.success | 支付后绑定工程师 + 工单转 processing |
bid_tasks.py | dispatch.timeout | 报价超时处理 + 2 分钟兜底扫描 |
quotation_tasks.py | quotation.additional.created+.expired | 追加报价 24h 超时调度 + 到期作废 |
sync_tasks.py | es.sync.# | ES 异步索引/删除文档 |
consumer.py | 消费者入口 | 统一连接 + 装饰器注册 |
4. Redis、RabbitMQ、Elasticsearch使用场景
4.1 Redis使用场景
| 使用场景 | 模块 | Key 模式 | TTL | 降级策略 |
|---|
| JWT 黑名单 | auth/dependencies | token_blacklist:{sha256(token)} | Token 到期 | Redis 不可用 → 放行（JWT 过期机制兜底） |
| 角色权限缓存 | auth/dependencies | rbac:role:{user_id} | 60s | Redis 不可用 → 跳过缓存直接查 DB |
| 短信验证码 | auth/service | sms:code:{scene}:{phone} | 300s | Redis 不可用 → 走阿里云 API 校验 |
| 短信冷却 | auth/service | sms:cooldown:{scene}:{phone} | 60s | Redis 不可用 → 跳过冷却检查 |
| RefreshToken 黑名单 | auth/service | token_blacklist:refresh:{sha256(token)} | Token 到期 | Redis 不可用 → 静默跳过 |
| 支付分布式锁 | payment/service | payment:lock:{pay_no} | 30s | 获取锁失败 → 等待 1s 重查 DB |
| 统计缓存 | statistics/router | stats:overview / ticket / engineer / finance | 60s | Redis 不可用 → 直接查 DB |
| 限流计数 | middleware/rate_limit | 内存实现（注释标注"生产环境替换为 Redis"） | — | — |
4.2 RabbitMQ使用场景
1. 交换机
| 交换机 | 类型 | durable | 用途 |
|---|
zhishu.events | TOPIC | ✓ | 业务事件总线 |
zhishu.sync | TOPIC | ✓ | ES 异步同步总线 |
zhishu.delay | TOPIC | ✓ | DLX 延迟消息（TTL 到期 → dead-letter →zhishu.events） |
2. 业务事件
| 事件 | 发布方 | 消费者 | 触发时机 |
|---|
ticket.created | ticket/service | ai_tasks.py | 客户创建工单 |
ticket.quoting | ai/service | —（通知用） | AI 诊断后进入待报价 |
ticket.dispatch_created | ai/service | —（通知用） | 派单记录创建 |
dispatch.timeout | ai/service →DLX | bid_tasks.py | 报价截止（5/15/30min） |
ticket.manual_dispatch | bid_tasks.py | —（通知管理员） | 全部超时转人工 |
ticket.processing | ticket/service | —（通知用） | 工单进入处理中 |
ticket.confirming | ticket/service | —（通知用） | 工程师提交报告 |
ticket.completed | ticket/service | —（通知用） | 客户验收通过 |
ticket.closed | ticket/service | ai_tasks.py | 工单终态 → AI 总结 |
payment.success | payment/service | payment_tasks.py | 支付回调验证通过 |
quotation.additional.created | quotation/service | quotation_tasks.py | 工程师追加报价 |
quotation.expired | quotation_tasks →DLX | quotation_tasks.py | 追加报价 24h 未确认 |
es.sync.# | 各模块 publish_sync | sync_tasks.py | 数据变更（通配符，所有模块复用） |
3. DLX 延迟消息原理
发布消息 → zhishu.delay 交换机 → 持有队列（TTL 倒计时） → TTL 到期 → dead-letter → DLX=zhishu.events, routing_key=原始key → 业务队列 → 消费者处理
4. 兜底机制
- dispatch.timeout:
bid_tasks.py每 2 分钟运行run_dispatch_safety_scanner()补偿可能丢失的 DLX 消息 - quotation.expired: 启动时运行
check_expired_quotations()扫描已过期的 pending 追加报价 - 消息积压保护: 毒消息首次 requeue 重试 1 次，二次失败 reject 永久丢弃
4.3 Elasticsearch使用场景
1. 索引
| 索引 | 同步方式 | 同步触发 |
|---|
tickets | MQ 异步（es.sync.#） | 工单创建/状态变更/数据更新 |
knowledge | MQ 异步（es.sync.#） | 文章发布/更新 |
2. 搜索
| 搜索场景 | 模块 | 方法 | 权重 |
|---|
| 工单搜索 | ticket/repository | search_index("tickets", ...) | title^2+description |
| 知识库搜索 | knowledge/service | search_index("knowledge", ...) | 全文检索 |
| 管理员工单搜索 | ticket/repository | 同上 | title^2+description |
3. 降级策略
- ES 搜索失败/无结果 → 降级为 MySQL LIKE 查询
- ES 同步失败 →
publish_sync内部 MQ 消息不阻塞主流程 - 消费者处理失败 → 写入 audit_log 记录
4. ES 初始化
- 应用启动时
ensure_indexes()检查并创建索引 - 分词器: IK 分词器（中文支持）
5. 项目核心业务流转图
![]()
6. 项目总结
不足：
- 工单图片是本地存储没有存储到oss上。
- 支付功能没有接入真实的微信支付/支付宝支付。
- 工单RAG-AI问答系统是使用的dify工作流的没有做到和知识库同步实时更新。
