SmartFix：分布式校园智能报修与派单平台

SmartFix 是“智能化软件工厂工具链调研及演示”课程大作业的实验系统。系统把自然语言报修转换为结构化工单，通过异步 Worker 调用独立 AI 服务完成分类、紧急度、相似历史工单与派单推荐，再由调度员确认，形成可追踪的人机协同闭环。

SmartFix 报修人工作台

核心能力

四角色 RBAC：报修人、调度员、维修人员、管理员；
工单状态机、乐观锁、审计时间线；
幂等创建、SLA 临期/超时状态、处理日志、解决方案与五星验收；
API → 数据库任务队列 → Worker → AI 服务的分布式异步链路；
中文报修分类、优先级、字段提取、相似工单检索；
先按技能/区域硬约束过滤，再按负载解释性排序的派单推荐；
外部模型可选，未配置或不可用时自动降级到可复现的本地智能引擎；
AI 连续失败三次后转人工，不丢失工单；
AI 原始结论保留与调度员人工纠偏，纠偏原因可追踪；
指数退避、事务 Outbox、trace_id、事件查看和 Prometheus 兼容指标；
自动 API 文档、自动测试、覆盖率门禁、Docker Compose 和 GitHub Actions。

架构

flowchart LR
    U[浏览器工作台] --> API[FastAPI 业务 API :8000]
    API --> DB[(SQLite / Job / Outbox)]
    DB --> W[异步 Worker]
    W --> AIS[AI 分析服务 :8001]
    AIS --> LLM[可选 OpenAI-compatible LLM]
    AIS --> RULE[本地规则与相似度引擎]
    W --> DB
    DB --> API

本机快速演示采用 API 内置 Worker；分布式模式让三个进程/容器独立运行。SQLite 是课程演示的零配置选择，通过 WAL、事务抢占、幂等键、乐观锁和 Outbox 支持本项目规模；生产部署应迁移 PostgreSQL 与 Redis/RabbitMQ/Kafka，并为消费者实现事件去重。

5 分钟启动

方式一：当前 Windows 环境直接运行

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python scripts/seed_demo.py --reset
Set-ExecutionPolicy -Scope Process Bypass
.\scripts\run_local.ps1

打开：

Web 工作台：http://127.0.0.1:8000
OpenAPI/Swagger：http://127.0.0.1:8000/docs
健康检查：http://127.0.0.1:8000/api/health

方式二：Docker Compose 三服务运行

docker compose up --build

Compose 会启动 api、worker、ai-service 三个服务并使用共享持久卷。当前开发机未安装 Docker，因此 Compose 文件已做静态设计，最终演示机需要实际执行一次该命令并保留截图。

演示账号

统一密码：demo123

用户名	角色	用途
`reporter`	报修人	创建工单、补充信息、评分验收
`dispatcher`	调度员	AI 纠偏、审核推荐、派单/重试
`tech_wang`	维修人员	东区给排水/设施工单
`tech_chen`	维修人员	西区网络/设备工单
`tech_xie`	维修人员	全校供电/安全/设备工单
`admin`	管理员	全局查看与控制

账号仅用于本地课程演示。上线前必须更换密码与 SMARTFIX_AUTH_SECRET。

一条完整演示路径

用 reporter 提交“东区 3 栋水管不停漏水，地面严重积水”；
工单进入 AI_ANALYZING，Worker 完成分析后转 PENDING_DISPATCH；
用 dispatcher 查看 AI 分类、紧急度、SLA、相似工单和推荐；必要时填写理由纠正 AI，验证原始结果仍被保留；
派给 tech_wang；
用 tech_wang 记录进展并执行 ASSIGNED → IN_PROGRESS → RESOLVED，提交可复核解决方案；
用 reporter 给出 1～5 分评价并验收，系统原子转为 CLOSED；
用 admin 查看 Outbox 事件和 /api/metrics，再打开审计时间线。

状态主链：

AI_ANALYZING → PENDING_DISPATCH → ASSIGNED → IN_PROGRESS → RESOLVED → CLOSED
                         ↑              │
                         └──────────────┘ 退回/改派

测试

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\test.ps1

当前本地基线：22 项功能/接口测试全部通过，Python 代码覆盖率 81.48%，门禁为 70%。测试覆盖：

认证、权限隔离和输入校验；
完整工单状态流；
乐观锁冲突；
AI 分类、优先级、字段提取；
相似工单与派单硬约束；
AI Worker 重试三次后转人工；
幂等重复请求、人工纠偏、处理记录、SLA、评价和事务 Outbox；
独立 AI 服务接口契约；
40 条中文 AI 固定评价集及指标门槛。

管线基准可用 python scripts/benchmark_pipeline.py 重跑。当前证据为：50 次创建平均 18.10 ms，Worker 50.51 job/s；20 次、8 线程同键重试只落库 1 条工单。结果只代表当前单机课程环境。

在 Windows 已安装 Edge 的环境中，启动服务并执行 python scripts/capture_demo.py --base-url http://127.0.0.1:8000，可重新生成报修工作台、调度纠偏和验收评价三张证据图。

测试数据与后续运行结果应以当前工作区重新执行为准，不要只复制 README 中的历史数字。

可选外部模型

Docker Compose 会自动读取仓库根目录的 .env。本机直接运行时，请在 PowerShell 中设置同名环境变量，例如 $env:LLM_API_KEY="..."。配置项如下：

ANALYSIS_MODE=hybrid
LLM_BASE_URL=https://your-provider.example/v1
LLM_API_KEY=...
LLM_MODEL=...

rules：完全本地、确定性，适合测试和断网演示；
hybrid：优先 LLM，失败自动回退到本地引擎；
llm：只用外部模型，失败进入 Worker 重试；
strict-remote：用于演示独立 AI 服务故障与最终人工回退。

密钥只允许放在本机环境变量或未提交的 .env 中。

项目结构

app/                 业务 API、认证、数据库、Worker、智能引擎、前端
ai_service/          可独立部署的 AI HTTP 服务
tests/               单元、接口、状态流、失败恢复测试
scripts/             本地启动、测试、演示数据和 AI 评价脚本
prompts/             需求分析、代码实现、测试生成的版本化生产资产
docs/evidence/       测试结果、评价数据、运行日志与界面截图
.github/workflows/   自动测试与容器构建
compose.yaml         API + Worker + AI service 三服务编排

人机协同控制

本项目不让 AI 直接派单或发布：

人类确认需求与验收标准；
AI 生成分类、推荐、代码和测试候选；
自动测试和质量门禁提供确定性证据；
调度员、开发审查者在关键关口批准；
失败和人工修改沉淀为审计记录与下一轮上下文。

成员分工

姓名	学号	GitLink 用户名	负责内容
王兆阳	25023077	`ILLBE_RICH`	需求基线、核心工单业务、项目统筹
陈世贤	25023087	`chenchenchen`	智能引擎、Agent 调研、AI 固定集评价
谢轩	25023023	`rib12316`	数据、Worker、可靠性、部署与 CI
李星谊	25023034	`YGKing`	Web 前端、测试实验、证据整理与演示

实验证据

仓库仅提交 docs/evidence/：其中包含 AI 固定集结果、管线基准、覆盖率与 pytest 记录、真实 HTTP 日志、架构图和界面截图。课程报告、设计说明及其 DOCX/HTML/PDF 导出文件保留在本地，不纳入代码仓库。