1 文档概述
本文档是汽车年检预约系统的技术方案文档,基于《软件需求规格说明书(SRS)》编写,作为系统设计、开发、测试的技术基准。
1.1 文档目的
- 明确技术选型决策及理由
- 定义系统架构和技术架构分层
- 描述核心业务的技术实现方案
- 定义数据库设计和API设计规范
- 评估技术风险及应对方案
1.2 参考文档
| 文档 | 编号 | 版本 |
| 软件需求规格说明书(SRS) | INS-SYS-SRS-001 | V1.0 |
| 用户需求文档(URD) | INS-SYS-URD-001 | V1.0 |
| 需求追踪矩阵(RTM) | INS-SYS-RTM-001 | V1.0 |
2 技术选型决策
2.1 选型原则
核心原则:技术为业务服务,没有最好的技术,只有最适合的技术。
- 业务优先:技术选型以满足业务需求为第一优先级
- 团队匹配:优先选择团队熟悉的技术,降低学习成本
- 适度先进:选择经过验证的成熟技术,不过度追求新技术
- 成本可控:考虑开发成本、维护成本、服务器成本
- 可扩展:支持未来业务扩展和技术演进
2.2 前端选型
2.2.1 候选方案对比
| 维度 | 权重 | 微信原生 | uni-app (Vue3) | Taro (React) |
| 业务匹配 | 30% | 90 | 92 | 80 |
| 技术成熟 | 20% | 95 | 85 | 80 |
| 团队能力 | 20% | 70 | 90 | 60 |
| 学习成本 | 10% | 60 | 85 | 65 |
| 维护成本 | 10% | 80 | 85 | 80 |
| 社区支持 | 5% | 90 | 85 | 80 |
| 扩展性 | 5% | 50 | 90 | 85 |
| 加权总分 | | 78.3 | 87.8 | 73.5 |
2.2.2 决策结论
选择:uni-app (Vue3)
• 团队Vue熟练,学习成本最低
• 一套代码支持微信小程序+H5+App,未来可扩展
• DCloud团队持续维护,社区活跃
• 关键API(扫码、定位、支付)都有良好封装
2.3 后端选型
2.3.1 候选方案对比
| 维度 | 权重 | Spring Boot | Node.js (Nest) | Go (Gin) |
| 业务匹配 | 30% | 92 | 78 | 82 |
| 技术成熟 | 20% | 95 | 85 | 80 |
| 团队能力 | 20% | 92 | 60 | 50 |
| 学习成本 | 10% | 85 | 65 | 45 |
| 维护成本 | 10% | 85 | 80 | 90 |
| 社区支持 | 5% | 95 | 90 | 80 |
| 扩展性 | 5% | 88 | 85 | 92 |
| 加权总分 | | 90.3 | 75.3 | 71.8 |
2.3.2 决策结论
选择:Spring Boot 3
• 团队Java熟练,零学习成本
• 定时任务(XXL-Job)、权限管理(Spring Security)生态成熟
• 后期对接交管系统(政务系统多用Java)更方便
• 企业级项目验证充分,稳定性高
2.4 数据库选型
| 数据库 | 用途 | 选型理由 |
| MySQL 8.0 | 业务数据存储 | 关系型数据,团队熟悉,生态成熟 |
| Redis 7.x | 缓存 + 分布式锁 | 预约并发控制,热点数据缓存 |
2.5 第三方服务选型
| 服务 | 选型 | 理由 | 成本 |
| 短信服务 | 阿里云短信 | 到达率≥99%,文档完善 | 0.04元/条 |
| OCR识别 | 腾讯云OCR | 准确率≥95%,支持行驶证识别 | 0.1元/次 |
| 地图服务 | 腾讯地图API | 小程序内置支持,免鉴权 | 免费(配额内) |
| 对象存储 | 阿里云OSS | 存储检测报告、图片等 | 0.12元/GB/月 |
2.6 最终技术栈
| 层级 | 技术 | 版本 | 用途 |
| 前端框架 | uni-app | Vue3版 | 微信小程序 + 未来H5/App |
| UI组件库 | uView Plus | 3.x | uni-app生态UI库 |
| 后端框架 | Spring Boot | 3.2+ | RESTful API服务 |
| ORM框架 | MyBatis-Plus | 3.5+ | 数据库操作 |
| 权限框架 | Spring Security + JWT | 6.x | 认证鉴权 |
| 定时任务 | XXL-Job | 2.4+ | 年检提醒等定时任务 |
| 接口文档 | Knife4j | 4.x | Swagger增强 |
| 关系数据库 | MySQL | 8.0+ | 业务数据存储 |
| 缓存 | Redis | 7.x | 缓存 + 分布式锁 |
| 容器化 | Docker | 24+ | 应用容器化 |
| 反向代理 | Nginx | 1.24+ | 负载均衡 + HTTPS |
| CI/CD | GitHub Actions | - | 自动化构建部署 |
| 监控 | Prometheus + Grafana | - | 系统监控告警 |
3 系统架构设计
3.1 整体架构图
图3-1 系统整体架构图
3.2 部署架构图
图3-2 部署架构图(阿里云ECS + Docker)
3.3 技术架构分层
| 层级 | 职责 | 技术 |
| 表现层 | 用户界面,交互逻辑 | uni-app / Vue3 + Element Plus |
| 接入层 | 反向代理,负载均衡,HTTPS | Nginx |
| 接口层 | RESTful API,参数校验,鉴权 | Spring Boot + Spring Security |
| 业务层 | 业务逻辑,事务管理 | Spring Boot Service层 |
| 数据层 | 数据访问,缓存 | MyBatis-Plus + Redis |
| 存储层 | 数据持久化 | MySQL 8 + Redis 7 |
| 调度层 | 定时任务调度 | XXL-Job |
| 外部服务层 | 第三方API调用 | 阿里云/腾讯云SDK |
4 核心设计方案
4.1 并发预约方案
预约场景存在并发竞争:多人同时抢同一个时段的最后1个名额。采用Redis分布式锁 + MySQL乐观锁双重保障。
方案流程
图4-1 并发预约流程(Redis分布式锁 + MySQL乐观锁)
核心代码
@Transactional
public Result bookAppointment(Long userId, Long slotId) {
String lockKey = "slot_lock:" + slotId;
RLock lock = redissonClient.getLock(lockKey);
try {
// 1. 获取分布式锁(10秒超时)
if (!lock.tryLock(10, TimeUnit.SECONDS)) {
return Result.fail("系统繁忙,请稍后重试");
}
// 2. 检查名额
TimeSlot slot = timeSlotMapper.selectById(slotId);
if (slot.getBookedCount() >= slot.getTotalCapacity()) {
return Result.fail("该时段已约满");
}
// 3. 乐观锁扣减
int affected = timeSlotMapper.decrCapacity(slotId, slot.getVersion());
if (affected == 0) {
return Result.fail("该时段已约满,请重新选择");
}
// 4. 创建订单
appointmentOrderService.create(userId, slotId);
// 5. 发送通知
notifyService.sendAppointmentConfirm(userId, slotId);
return Result.success("预约成功");
} finally {
if (lock.isHeldByCurrentThread()) {
lock.unlock();
}
}
}
4.2 实时进度方案
用户到站签到后,需要实时查看检测进度。MVP阶段采用前端轮询方案(每30秒刷新),后期可升级为WebSocket。
sequenceDiagram
participant U as 用户小程序
participant S as Spring Boot
participant R as Redis
participant DB as MySQL
participant W as 检测站后台
U->>S: GET /api/inspection/{orderId}/progress
S->>R: 查询缓存
R-->>S: 缓存命中/未命中
alt 缓存未命中
S->>DB: 查询检测进度
DB-->>S: 返回进度数据
S->>R: 写入缓存(30秒过期)
end
S-->>U: 返回进度数据
Note over U: 每30秒轮询一次
W->>S: PUT /api/admin/progress/{orderId}
S->>DB: 更新进度状态
S->>R: 清除缓存
S-->>W: 更新成功
Note over U: 下次轮询获取最新进度
4.3 年检提醒方案
年检提醒是系统的核心触达功能,采用XXL-Job定时任务 + 多通道提醒方案。
flowchart TD
A([每日凌晨2:00
XXL-Job触发]) --> B[扫描所有车辆
计算距到期天数]
B --> C{是否免检车辆?}
C -->|是| D{距到期天数}
C -->|否| E{距到期天数}
D -->|30天| D1[微信模板消息
请申领电子标志]
D -->|7天| D2[短信+微信
紧急提醒申领]
E -->|90天| E1[微信模板消息
建议提前安排]
E -->|30天| E2[短信+微信
请尽快预约]
E -->|7天| E3[短信+微信
紧急: 请立即预约]
E -->|当天| E4[短信+微信
逾期罚200扣3分]
D1 --> F[记录remind_log
防重复发送]
D2 --> F
E1 --> F
E2 --> F
E3 --> F
E4 --> F
style A fill:#E6F1FB,stroke:#185FA5
style C fill:#FAEEDA,stroke:#BA7517
style E4 fill:#f8d7da,stroke:#dc3545
style F fill:#d4edda,stroke:#28a745
4.4 检测站推荐算法
检测站推荐采用综合评分排序,考虑距离、评分、排队人数、价格四个维度。
// 综合评分公式
score = w1 × distanceScore + w2 × ratingScore + w3 × queueScore + w4 × priceScore
// 权重配置
w1 = 0.35 // 距离权重(最重要)
w2 = 0.30 // 评分权重
w3 = 0.20 // 排队权重
w4 = 0.15 // 价格权重
// 各维度评分(0-100分)
distanceScore = max(0, 100 - distanceKm × 2) // 距离越近分越高
ratingScore = station.rating × 20 // 5分制转100分
queueScore = max(0, 100 - queueCount × 5) // 排队越少分越高
priceScore = max(0, 100 - (price - minPrice) × 2) // 价格越低分越高
10 架构模式与项目结构
10.1 架构模式选择
10.1.1 项目复杂度评估
| 维度 | 当前情况 | 判断 |
| 用户量 | 初期1万以内,中期10万 | 低-中 |
| 功能模块 | 10个左右 | 中等 |
| 团队规模 | 4人(2后端+1前端+1测试) | 小团队 |
| 开发周期 | 3个月 | 短周期 |
| 并发量 | 初期100以内 | 低 |
| 数据量 | 初期百万级 | 低 |
结论:项目复杂度为"中低",选择单体应用(模块化分包),不需要微服务。
10.1.2 三种架构模式对比
| 维度 | 单体应用 | 多模块 | 微服务 |
| 适用场景 | 初创项目、小团队、MVP | 中型项目、模块清晰 | 大型项目、多团队、高并发 |
| 开发效率 | 最高 | 中 | 最低 |
| 部署复杂度 | 最低 | 低 | 高 |
| 团队要求 | 1-5人 | 3-10人 | 10+人 |
| 数据管理 | 单库 | 单库 | 每服务独立数据库 |
| 服务治理 | 不需要 | 不需要 | 需要(注册发现、网关、熔断) |
| 运维成本 | 最低 | 低 | 高 |
10.1.3 选择理由
选择:单体应用(模块化分包)
1. 团队4人,没有微服务运维能力,也没有专职运维
2. 3个月周期,微服务搭建就要1个月,时间不允许
3. 初期用户量和并发量都不高,单体完全能扛住
4. 功能模块耦合度高:预约→检测→进度→报告是串联流程,拆服务反而增加复杂度
5. 为未来拆分做准备:按模块分包,模块间通过接口通信,不直接调用实现类
10.1.4 未来演进路径
演进路线:单体 → 多模块 → 微服务
• 当前:单体应用(4人,3个月)
• 用户量达到10万+:拆分为Maven多模块,仍单部署
• 用户量达到100万+:拆分为微服务(Spring Cloud)
• 用户量达到1000万+:微服务 + K8s + 服务网格
按业务增长逐步演进,不要过度设计。
10.2 代码规范
| 规范 | 说明 |
| 命名规范 | 类名PascalCase,方法名camelCase,常量UPPER_SNAKE_CASE,表名snake_case |
| 包结构 | 按业务模块分包,每个模块内 controller → service → mapper → entity → dto → vo |
| 接口规范 | RESTful风格,统一响应格式 {code, message, data},接口版本 /api/v1/ |
| 异常处理 | 全局异常处理器GlobalExceptionHandler,业务异常用BusinessException + ErrorCode |
| 日志规范 | SLF4J + Logback,关键操作INFO级别,异常ERROR级别,禁止System.out |
| 注释规范 | 类和方法必须有JavaDoc,复杂逻辑必须有行内注释 |
| DTO/VO分离 | 请求用DTO(DataTransferObject),响应用VO(ViewObject),不直接暴露Entity |
10.3 Git规范
| 规范 | 说明 |
| 分支策略 | main(生产) / develop(开发) / feature/* (功能) / hotfix/* (修复) |
| 提交规范 | feat: 新功能 / fix: 修复 / docs: 文档 / refactor: 重构 / test: 测试 / chore: 构建 |
| Code Review | 所有合并到develop的代码必须经过Code Review |
| 版本标签 | 语义化版本 v1.0.0,生产发布打tag |
10.4 后端项目结构(Spring Boot 单体)
按业务模块分包,模块内按职责分层。模块间通过注入Service接口通信,不直接调用实现类。
inspection-backend/
├── pom.xml
├── Dockerfile
├── src/main/java/com/inspection/
│ ├── InspectionApplication.java # 启动类
│ │
│ ├── common/ # 公共模块(跨业务复用)
│ │ ├── config/ # 全局配置
│ │ │ ├── WebMvcConfig.java # MVC配置(跨域、拦截器)
│ │ │ ├── RedisConfig.java # Redis配置(序列化、连接池)
│ │ │ ├── MybatisPlusConfig.java # MyBatis-Plus配置(分页插件、乐观锁插件)
│ │ │ ├── SecurityConfig.java # Spring Security配置(JWT过滤器链)
│ │ │ └── Knife4jConfig.java # 接口文档配置
│ │ ├── constant/ # 常量与枚举
│ │ │ ├── OrderStatus.java # 订单状态枚举(待签到/已签到/检测中/合格/不合格/已取消/已爽约)
│ │ │ ├── InspectionStep.java # 检测环节枚举(外检/OBD/制动/灯光/轮胎/底盘)
│ │ │ └── RemindType.java # 提醒类型枚举(90天/30天/7天/当天/免检)
│ │ ├── exception/ # 异常处理
│ │ │ ├── BusinessException.java # 业务异常(携带ErrorCode)
│ │ │ ├── ErrorCode.java # 错误码定义(10001-用户未登录, 20001-时段已约满...)
│ │ │ └── GlobalExceptionHandler.java # 全局异常处理器(RestControllerAdvice)
│ │ ├── result/ # 统一响应
│ │ │ ├── Result.java # 统一响应体 Result<T> {code, message, data}
│ │ │ └── PageResult.java # 分页响应 PageResult<T> {total, list, pageNum, pageSize}
│ │ ├── util/ # 工具类
│ │ │ ├── JwtUtil.java # JWT工具(生成/解析/刷新token)
│ │ │ ├── AesUtil.java # AES-256加密工具(手机号、身份证号加密)
│ │ │ ├── OrderNoGenerator.java # 订单号生成器(雪花算法)
│ │ │ ├── DateUtil.java # 日期工具(年检日期计算、提前天数判断)
│ │ │ └── GeoUtil.java # 地理工具(经纬度距离计算)
│ │ └── annotation/ # 自定义注解
│ ├── RequireLogin.java # 登录校验注解(配合拦截器使用)
│ └── RateLimit.java # 限流注解(配合AOP使用)
│
│ ├── user/ # 用户模块
│ │ ├── controller/
│ │ │ ├── UserController.java # 用户API:登录(GET /api/user/login)、获取/更新信息
│ │ │ └── VehicleController.java # 车辆API:列表/添加/更新/删除、OCR识别行驶证
│ │ ├── service/
│ │ │ ├── UserService.java # 用户业务:微信登录、信息管理
│ │ │ ├── VehicleService.java # 车辆业务:CRUD、年检日期自动计算、免检判断
│ │ │ └── OcrService.java # OCR服务:调用腾讯云OCR识别行驶证照片
│ │ ├── mapper/
│ │ │ ├── UserMapper.java # 用户Mapper(BaseMapper<User>)
│ │ │ └── VehicleMapper.java # 车辆Mapper(含按到期日期查询的自定义方法)
│ │ ├── entity/
│ │ │ ├── User.java # 用户实体(@TableName("user"))
│ │ │ └── Vehicle.java # 车辆实体(含is_exempt免检标记)
│ │ ├── dto/
│ │ │ ├── LoginRequest.java # 登录请求DTO(code: 微信登录code)
│ │ │ ├── VehicleCreateRequest.java # 添加车辆DTO(plate_number, vin, register_date)
│ │ │ └── VehicleOCRResponse.java # OCR识别结果DTO
│ │ └── vo/
│ ├── UserInfoVO.java # 用户信息VO(脱敏手机号)
│ └── VehicleVO.java # 车辆信息VO(含年检状态、距到期天数)
│
│ ├── station/ # 检测站模块
│ │ ├── controller/
│ │ │ ├── StationController.java # 检测站API:列表(距离/评分/空闲排序)、详情、可预约时段
│ │ │ └── StationAdminController.java # 检测站管理API:CRUD、排期管理
│ │ ├── service/
│ │ │ ├── StationService.java # 检测站业务:查询、详情、管理
│ │ │ ├── TimeSlotService.java # 时段服务:生成时段、查询可用时段、容量管理
│ │ │ └── StationRecommendService.java # 推荐算法:综合评分 = 距离×0.35 + 评分×0.30 + 排队×0.20 + 价格×0.15
│ │ ├── mapper/
│ │ │ ├── StationMapper.java # 检测站Mapper(含地理位置查询的自定义SQL)
│ │ │ └── TimeSlotMapper.java # 时段Mapper(含乐观锁扣减方法decrCapacity)
│ │ ├── entity/
│ │ │ ├── Station.java # 检测站实体(含经纬度、评分、价格、日检测能力)
│ │ │ └── TimeSlot.java # 时段实体(含乐观锁version字段)
│ │ ├── dto/
│ │ │ ├── StationQueryRequest.java # 查询DTO(latitude, longitude, sort_by, city)
│ │ │ └── StationCreateRequest.java # 创建DTO
│ │ └── vo/
│ ├── StationVO.java # 检测站列表VO(含距离、当前排队人数)
│ ├── StationDetailVO.java # 检测站详情VO(含营业时间、可预约时段列表)
│ └── TimeSlotVO.java # 时段VO(含剩余名额、是否可预约)
│
│ ├── appointment/ # 预约模块(核心,最复杂)
│ │ ├── controller/
│ │ │ └── AppointmentController.java # 预约API:创建预约、取消预约、我的预约列表、扫码签到
│ │ ├── service/
│ │ │ ├── AppointmentService.java # 预约业务:创建/取消/列表/详情(调用BookingService)
│ │ │ ├── BookingService.java # 并发预约核心:Redis分布式锁 + MySQL乐观锁(详见4.1节)
│ │ │ └── CheckInService.java # 签到服务:扫码验证、签到状态更新
│ │ ├── mapper/
│ │ │ └── AppointmentOrderMapper.java # 预约订单Mapper(含按用户/状态查询的自定义方法)
│ │ ├── entity/
│ │ │ └── AppointmentOrder.java # 预约订单实体(status状态机:待签到→已签到→检测中→合格/不合格)
│ │ ├── dto/
│ │ │ ├── BookRequest.java # 预约请求DTO(vehicleId, slotId)
│ │ │ ├── CancelRequest.java # 取消请求DTO(orderId, reason)
│ │ │ └── CheckInRequest.java # 签到请求DTO(orderId, stationCode)
│ │ └── vo/
│ ├── AppointmentVO.java # 预约列表VO(含检测站名称、时段、状态)
│ └── AppointmentDetailVO.java # 预约详情VO(含检测站信息、车辆信息、进度)
│
│ ├── inspection/ # 检测模块
│ │ ├── controller/
│ │ │ ├── InspectionController.java # 检测API:查询进度、查看报告
│ │ │ └── InspectionAdminController.java # 检测管理API:更新进度(检测站后台调用)
│ │ ├── service/
│ │ │ ├── InspectionProgressService.java # 进度服务:查询/更新进度、计算预计剩余时间
│ │ │ └── InspectionReportService.java # 报告服务:生成报告、大白话解释、维修建议
│ │ ├── mapper/
│ │ │ ├── InspectionRecordMapper.java # 检测记录Mapper
│ │ │ └── InspectionProgressMapper.java # 检测进度Mapper(含按orderId+stepOrder查询)
│ │ ├── entity/
│ │ │ ├── InspectionRecord.java # 检测记录实体(item_name, result, detail, suggestion)
│ │ │ └── InspectionProgress.java # 检测进度实体(step_name, step_order, status, start/end_time)
│ │ └── vo/
│ ├── ProgressVO.java # 进度VO(6个环节状态列表 + 预计剩余时间)
│ └── ReportVO.java # 报告VO(含大白话解释、维修建议、费用参考)
│
│ ├── remind/ # 提醒模块
│ │ ├── service/
│ │ │ ├── RemindService.java # 提醒业务:判断提醒类型、防重复发送、多通道发送
│ │ │ ├── SmsService.java # 短信服务:调用阿里云短信API
│ │ │ └── WechatTemplateService.java # 微信模板消息:调用微信API发送模板消息
│ │ ├── task/
│ │ │ └── InspectionRemindTask.java # 年检提醒定时任务(XXL-Job,每日凌晨2:00执行)
│ │ ├── mapper/
│ │ │ └── RemindLogMapper.java # 提醒日志Mapper(防重复发送)
│ │ └── entity/
│ └── RemindLog.java # 提醒日志实体(vehicle_id, remind_type, remind_date)
│
│ ├── admin/ # 后台管理模块
│ │ ├── controller/
│ │ │ ├── AdminDashboardController.java # 数据看板:预约统计、检测站统计、趋势图
│ │ │ ├── AdminStationController.java # 检测站管理:CRUD、启用/禁用
│ │ │ ├── AdminOrderController.java # 预约管理:订单列表、状态变更
│ │ │ └── AdminUserController.java # 用户管理:用户列表、禁用
│ │ └── service/
│ └── AdminStatisticsService.java # 统计服务:日/周/月预约量、检测通过率、检测站排名
│
│ └── security/ # 安全模块
│ ├── filter/
│ │ └── JwtAuthenticationFilter.java # JWT过滤器:解析token、设置SecurityContext
│ ├── handler/
│ │ ├── LoginSuccessHandler.java # 登录成功处理:生成JWT token
│ │ └── LoginFailureHandler.java # 登录失败处理:返回错误信息
│ └── service/
│ └── UserDetailsServiceImpl.java # 用户详情服务:从数据库加载用户信息
│
├── src/main/resources/
│ ├── application.yml # 主配置(端口、日志级别)
│ ├── application-dev.yml # 开发环境(MySQL/Redis连接、日志DEBUG)
│ ├── application-prod.yml # 生产环境(MySQL/Redis连接、日志WARN)
│ ├── mapper/ # MyBatis XML(复杂SQL写在这里)
│ │ ├── user/UserMapper.xml
│ │ ├── user/VehicleMapper.xml
│ │ ├── station/StationMapper.xml # 含地理位置距离计算SQL
│ │ ├── station/TimeSlotMapper.xml # 含乐观锁扣减SQL
│ │ ├── appointment/AppointmentOrderMapper.xml
│ │ ├── inspection/InspectionRecordMapper.xml
│ │ ├── inspection/InspectionProgressMapper.xml
│ │ └── remind/RemindLogMapper.xml
│ └── db/
│ ├── schema.sql # 建表SQL(8张核心表 + 索引)
│ └── data.sql # 初始化数据(测试检测站数据)
│
└── docker/
├── docker-compose.yml # Docker编排(Nginx + Backend + MySQL + Redis)
└── nginx/
└── nginx.conf # Nginx配置(反向代理 + HTTPS)
10.5 前端项目结构(uni-app 微信小程序)
inspection-miniapp/
├── package.json
├── manifest.json # 小程序配置(appid、权限)
├── pages.json # 页面路由配置(tabBar、页面路径)
├── App.vue
├── main.js
│
├── pages/ # 页面(按业务模块组织)
│ ├── index/
│ │ └── index.vue # 首页:检测站推荐列表(距离+评分+排队排序)
│ ├── station/
│ │ └── detail.vue # 检测站详情:营业时间、评分、可预约时段选择
│ ├── appointment/
│ │ ├── create.vue # 创建预约:选择车辆→选择时段→确认预约
│ │ ├── list.vue # 我的预约列表(待签到/检测中/已完成/已取消)
│ │ └── detail.vue # 预约详情:检测进度实时追踪(6环节步骤条)
│ ├── vehicle/
│ │ ├── list.vue # 我的车辆列表(含年检状态、距到期天数)
│ │ ├── add.vue # 添加车辆:手动输入 / OCR识别行驶证
│ │ └── detail.vue # 车辆详情:年检信息、历史记录
│ ├── checkin/
│ │ └── index.vue # 扫码签到:调用wx.scanCode
│ ├── report/
│ │ └── detail.vue # 检测报告:合格/不合格项 + 大白话解释 + 维修建议
│ ├── calculator/
│ │ └── index.vue # 年检计算器(引流工具):车型+注册日期→下次年检时间
│ ├── selfcheck/
│ │ └── index.vue # 检前自检清单:灯光/刹车/轮胎/外观,逐项检查
│ └── mine/
│ ├── index.vue # 个人中心:我的车辆、我的预约、设置
│ └── profile.vue # 个人信息编辑
│
├── components/ # 公共组件(可复用UI)
│ ├── StationCard.vue # 检测站卡片(名称+地址+距离+评分+价格)
│ ├── VehicleCard.vue # 车辆卡片(车牌+品牌+年检状态+到期时间)
│ ├── ProgressSteps.vue # 检测进度步骤条(6环节,灰/蓝/绿状态)
│ ├── TimeSlotPicker.vue # 时段选择器(按时间段显示剩余名额)
│ ├── InspectionItem.vue # 检测项目卡片(合格绿色/不合格红色+详情)
│ └── EmptyState.vue # 空状态占位图
│
├── api/ # 接口封装(统一请求处理)
│ ├── request.js # 请求拦截器:自动携带token、统一错误处理、loading
│ ├── user.js # 用户接口:login、profile
│ ├── vehicle.js # 车辆接口:list、add、update、delete、ocr
│ ├── station.js # 检测站接口:list、detail、slots
│ ├── appointment.js # 预约接口:book、cancel、list、checkin
│ └── inspection.js # 检测接口:progress、report
│
├── store/ # 状态管理(Pinia)
│ ├── user.js # 用户状态:token、userInfo、isLogin
│ ├── vehicle.js # 车辆状态:vehicleList、currentVehicle
│ └── location.js # 定位状态:latitude、longitude、city
│
├── utils/ # 工具函数
│ ├── auth.js # 登录/token管理(存储、刷新、过期判断)
│ ├── location.js # 定位工具(wx.getLocation封装、定位失败降级)
│ ├── date.js # 日期工具(年检日期计算、距到期天数、格式化)
│ └── validator.js # 表单校验(车牌号、手机号、车架号格式校验)
│
├── static/ # 静态资源
│ ├── images/ # 图片(空状态、引导图)
│ └── icons/ # 图标
│
└── uni_modules/ # uni-app插件
└── uview-plus/ # UI组件库(按钮、表单、弹窗、导航栏)
10.6 管理后台项目结构(Vue3)
inspection-admin/
├── package.json
├── vite.config.js
├── src/
│ ├── main.js
│ ├── App.vue
│ ├── router/
│ │ └── index.js # 路由配置(含权限守卫)
│ ├── store/
│ │ └── user.js # 管理员状态
│ ├── views/
│ │ ├── dashboard/
│ │ │ └── index.vue # 数据看板:预约趋势图、检测站排名、通过率统计
│ │ ├── station/
│ │ │ ├── list.vue # 检测站列表(搜索、筛选、分页)
│ │ │ └── edit.vue # 编辑检测站(信息、排期、容量配置)
│ │ ├── order/
│ │ │ └── list.vue # 预约订单列表(状态筛选、导出)
│ │ ├── inspection/
│ │ │ └── progress.vue # 更新检测进度(检测站端使用)
│ │ └── system/
│ │ └── user.vue # 管理员用户管理
│ ├── api/ # 接口封装
│ ├── components/ # 公共组件(表格、表单、图表)
│ └── utils/ # 工具函数
10.7 模块间依赖关系
graph LR
A[user模块] -->|提供用户/车辆信息| D[appointment模块]
B[station模块] -->|提供检测站/时段信息| D
D -->|创建检测任务| E[inspection模块]
E -->|检测完成通知| F[remind模块]
A -->|用户手机号/openid| F
G[admin模块] -->|调用各模块Service| A
G --> B
G --> D
G --> E
style A fill:#E6F1FB,stroke:#185FA5
style B fill:#d4edda,stroke:#28a745
style D fill:#FAEEDA,stroke:#BA7517
style E fill:#CECBF6,stroke:#534AB7
style F fill:#F7C1C1,stroke:#A32D2D
style G fill:#f8f9fa,stroke:#dee2e6
模块间通信方式:单体内直接注入Service接口调用,不走HTTP/RPC。公共逻辑放在common模块,各模块通过依赖注入使用。
11 接口详细设计
11.1 统一响应格式
// 成功响应
{
"code": 200,
"message": "success",
"data": { ... }
}
// 失败响应
{
"code": 20001,
"message": "该时段已约满",
"data": null
}
// 分页响应
{
"code": 200,
"message": "success",
"data": {
"total": 100,
"list": [ ... ],
"pageNum": 1,
"pageSize": 10
}
}
11.2 错误码定义
| 错误码 | 含义 | 说明 |
| 200 | 成功 | 请求成功 |
| 400 | 参数错误 | 请求参数校验失败 |
| 401 | 未登录 | token无效或过期 |
| 403 | 无权限 | 无权访问该资源 |
| 404 | 资源不存在 | 接口或数据不存在 |
| 500 | 服务器错误 | 系统内部错误 |
| 10001 | 微信登录失败 | code无效或微信服务异常 |
| 10002 | 手机号已绑定 | 该手机号已绑定其他账号 |
| 20001 | 时段已约满 | 该时段名额已满 |
| 20002 | 并发冲突 | 多人同时抢名额,稍后重试 |
| 20003 | 重复预约 | 同一天已有预约 |
| 20004 | 免费取消期已过 | 距预约时间不足2小时 |
| 20005 | 爽约限制 | 累计3次爽约,限制预约7天 |
| 20006 | 车辆有未处理违章 | 需先处理违章才能预约 |
| 20007 | 交强险过期 | 需先续保才能预约 |
| 20008 | 免检车辆 | 免检车辆无需预约检测站 |
| 30001 | 签到时间错误 | 未到预约时段(前后30分钟) |
| 30002 | 签到地点错误 | 不在预约检测站 |
| 30003 | 已签到 | 该订单已签到 |
11.3 核心接口详细设计
11.3.1 创建预约 POST /api/appointment
请求参数
| 字段 | 类型 | 必填 | 说明 | 示例 |
| vehicleId | Long | 是 | 车辆ID | 1001 |
| slotId | Long | 是 | 时段ID | 5001 |
响应参数
| 字段 | 类型 | 说明 | 示例 |
| orderId | Long | 预约订单ID | 8001 |
| orderNo | String | 订单编号 | INS20260815001 |
| stationName | String | 检测站名称 | XX检测站 |
| appointmentTime | String | 预约时间 | 2026-08-20 10:00-10:30 |
请求示例
POST /api/appointment
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Content-Type: application/json
{
"vehicleId": 1001,
"slotId": 5001
}
响应示例
// 成功
{
"code": 200,
"message": "预约成功",
"data": {
"orderId": 8001,
"orderNo": "INS20260815001",
"stationName": "XX机动车检测站",
"appointmentTime": "2026-08-20 10:00-10:30"
}
}
// 失败:时段已约满
{
"code": 20001,
"message": "该时段已约满,请选择其他时段",
"data": null
}
11.3.2 扫码签到 POST /api/appointment/{id}/checkin
请求参数
| 字段 | 类型 | 必填 | 说明 | 示例 |
| id | Long | 是 | 路径参数,订单ID | 8001 |
| stationCode | String | 是 | 检测站二维码内容 | STATION_001 |
业务规则
- BR-CI-001:签到时间窗口为预约时段前后30分钟
- BR-CI-002:stationCode必须与预约的检测站匹配
- BR-CI-003:订单状态必须为"待签到"(0)
- BR-CI-004:签到成功后订单状态变更为"已签到"(1),记录签到时间
响应示例
// 成功
{
"code": 200,
"message": "签到成功",
"data": {
"orderId": 8001,
"status": 1,
"checkInTime": "2026-08-20 09:55:00"
}
}
// 失败:未到签到时间
{
"code": 30001,
"message": "未到预约时段,签到时间为09:30-10:30",
"data": null
}
11.3.3 检测进度 GET /api/inspection/{orderId}/progress
响应参数
| 字段 | 类型 | 说明 |
| orderId | Long | 订单ID |
| currentStep | String | 当前检测环节 |
| completedSteps | Integer | 已完成环节数 |
| estimatedMinutes | Integer | 预计剩余分钟数 |
| steps | Array | 6个检测环节详情 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"orderId": 8001,
"currentStep": "OBD",
"completedSteps": 1,
"estimatedMinutes": 25,
"steps": [
{"name": "外检", "status": 2, "startTime": "10:05", "endTime": "10:12"},
{"name": "OBD", "status": 1, "startTime": "10:12", "endTime": null},
{"name": "制动", "status": 0, "startTime": null, "endTime": null},
{"name": "灯光", "status": 0, "startTime": null, "endTime": null},
{"name": "轮胎", "status": 0, "startTime": null, "endTime": null},
{"name": "底盘", "status": 0, "startTime": null, "endTime": null}
]
}
}
// status: 0=未开始, 1=进行中, 2=已完成
11.3.4 检测站列表 GET /api/station/list
请求参数
| 字段 | 类型 | 必填 | 说明 | 示例 |
| latitude | Double | 是 | 用户纬度 | 39.9042 |
| longitude | Double | 是 | 用户经度 | 116.4074 |
| sortBy | String | 否 | 排序方式:distance/rating/queue/price,默认distance | distance |
| pageNum | Integer | 否 | 页码,默认1 | 1 |
| pageSize | Integer | 否 | 每页数量,默认10 | 10 |
响应示例
{
"code": 200,
"message": "success",
"data": {
"total": 50,
"list": [
{
"id": 101,
"name": "XX机动车检测站",
"address": "北京市朝阳区XX路XX号",
"distance": 2.3,
"rating": 4.5,
"price": 280,
"queueCount": 5,
"businessHours": "08:00-17:00",
"todayAvailable": true
}
],
"pageNum": 1,
"pageSize": 10
}
}
11.4 接口鉴权方案
| 接口 | 鉴权方式 | 说明 |
| POST /api/user/login | 无 | 微信登录,不需要token |
| GET /api/station/list | JWT | 需要登录 |
| POST /api/appointment | JWT | 需要登录 |
| POST /api/appointment/{id}/checkin | JWT | 需要登录 |
| GET /api/admin/* | JWT + 角色校验 | 需要管理员角色 |
12 部署方案
12.1 服务器配置
| 资源 | 规格 | 用途 | 月成本 |
| 阿里云ECS | 2核4G,50G SSD | 运行所有服务 | ¥200 |
| 域名 | .com域名 | API域名 | ¥60/年 |
| SSL证书 | Let's Encrypt | HTTPS | 免费 |
| 阿里云RDS | MySQL 8.0,1核1G | 生产数据库(可选,也可用Docker MySQL) | ¥100 |
12.2 Docker Compose配置
# docker-compose.yml
version: '3.8'
services:
nginx:
image: nginx:1.24
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf
- ./nginx/ssl:/etc/nginx/ssl
- ./admin/dist:/usr/share/nginx/html/admin
depends_on:
- backend
restart: always
backend:
build: ./backend
ports:
- "8080:8080"
environment:
- SPRING_PROFILES_ACTIVE=prod
- DB_HOST=mysql
- DB_PORT=3306
- DB_NAME=inspection
- DB_USER=${DB_USER}
- DB_PASSWORD=${DB_PASSWORD}
- REDIS_HOST=redis
- REDIS_PORT=6379
- JWT_SECRET=${JWT_SECRET}
- SMS_ACCESS_KEY=${SMS_ACCESS_KEY}
- SMS_ACCESS_SECRET=${SMS_ACCESS_SECRET}
- OCR_SECRET_ID=${OCR_SECRET_ID}
- OCR_SECRET_KEY=${OCR_SECRET_KEY}
depends_on:
- mysql
- redis
restart: always
mysql:
image: mysql:8.0
ports:
- "3306:3306"
environment:
- MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
- MYSQL_DATABASE=inspection
- MYSQL_USER=${DB_USER}
- MYSQL_PASSWORD=${DB_PASSWORD}
volumes:
- mysql_data:/var/lib/mysql
- ./db/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql
- ./db/data.sql:/docker-entrypoint-initdb.d/02-data.sql
restart: always
redis:
image: redis:7-alpine
ports:
- "6379:6379"
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- redis_data:/data
restart: always
volumes:
mysql_data:
redis_data:
12.3 Nginx配置
# nginx/nginx.conf
worker_processes auto;
events { worker_connections 1024; }
http {
# HTTPS配置
server {
listen 443 ssl;
server_name api.inspection.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
# 后端API代理
location /api/ {
proxy_pass http://backend:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 管理后台
location /admin/ {
alias /usr/share/nginx/html/admin/;
try_files $uri $uri/ /admin/index.html;
}
# 接口文档(仅开发环境开放)
location /doc.html {
proxy_pass http://backend:8080;
}
}
# HTTP跳转HTTPS
server {
listen 80;
server_name api.inspection.com;
return 301 https://$server_name$request_uri;
}
}
12.4 CI/CD流水线
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# 后端构建
- name: Build Backend
uses: actions/setup-java@v4
with:
java-version: '17'
- run: cd backend && mvn clean package -DskipTests
# 前端构建
- name: Build Admin
uses: actions/setup-node@v4
with:
node-version: '18'
- run: cd admin && npm install && npm run build
# 部署到服务器
- name: Deploy
uses: appleboy/ssh-action@v1
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_KEY }}
script: |
cd /opt/inspection
git pull origin main
cd backend && mvn clean package -DskipTests
cd ../admin && npm install && npm run build
cd .. && docker-compose up -d --build
12.5 上线检查清单
| 检查项 | 检查内容 | 状态 |
| 域名与SSL | 域名解析正确,SSL证书有效 | □ |
| 数据库 | 生产库已创建,表结构已初始化 | □ |
| 环境变量 | 所有密钥已配置到.env文件 | □ |
| 小程序审核 | 小程序已提交审核并通过 | □ |
| 短信签名 | 阿里云短信签名已审核通过 | □ |
| 接口测试 | 核心接口端到端测试通过 | □ |
| 性能测试 | 100并发预约无超卖 | □ |
| 安全检查 | HTTPS、SQL注入、XSS防护已验证 | □ |
| 监控告警 | 服务器监控和告警已配置 | □ |
| 数据备份 | 自动备份策略已配置 | □ |
14 开发排期
14.1 里程碑计划
| 阶段 | 时间 | 交付物 | 验收标准 |
| M1:项目启动 | 第1周 | 需求文档+技术方案+环境搭建 | 评审通过,开发环境可用 |
| M2:基础功能 | 第2-3周 | 用户登录+车辆管理+检测站列表 | 小程序能登录、看检测站 |
| M3:核心功能 | 第4-6周 | 预约+签到+进度+通知 | 核心流程端到端走通 |
| M4:增值功能 | 第7-8周 | 报告+自检+多车+计算器 | P1功能全部完成 |
| M5:后台管理 | 第9-10周 | 管理后台+检测站后台+数据统计 | 后台功能可用 |
| M6:测试上线 | 第11-12周 | 集成测试+性能测试+灰度发布+正式上线 | 无P0 bug,性能达标 |
14.2 任务分解(甘特图)
| 任务 |
负责人 |
W1 | W2 | W3 | W4 | W5 | W6 |
W7 | W8 | W9 | W10 | W11 | W12 |
| 需求分析+技术方案 | 全员 |
█ |
| | | | |
| | | | | |
| 环境搭建+数据库设计 | 后端A |
█ |
| | | | |
| | | | | |
| 用户登录+车辆管理 | 后端A |
|
█ |
█ |
| | |
| | | | | |
| 检测站+时段管理 | 后端B |
|
█ |
█ |
| | |
| | | | | |
| 首页+检测站列表 | 前端 |
|
█ |
█ |
| | |
| | | | | |
| 预约+签到核心功能 | 后端A |
| | |
█ |
█ |
█ |
| | | | | |
| 检测进度+报告 | 后端B |
| | |
█ |
█ |
|
| | | | | |
| 预约+进度+签到页面 | 前端 |
| | |
█ |
█ |
█ |
| | | | | |
| 年检提醒定时任务 | 后端A |
| | | | |
█ |
| | | | | |
| 报告+自检+多车+计算器 | 后端B+前端 |
| | | | | |
█ |
█ |
| | | |
| 管理后台+检测站后台 | 前端+后端A |
| | | | | |
| |
█ |
█ |
| |
| 功能测试+Bug修复 | 测试+全员 |
| | | | | |
| | | |
█ |
|
| 性能测试+灰度发布+上线 | 全员 |
| | | | | |
| | | | |
█ |
█ = 任务执行周期 | 颜色:绿=后端,蓝=前端,橙=增值,紫=后台,红=测试上线
14.3 风险缓冲
每个里程碑预留2-3天缓冲时间,应对需求变更、技术难点、人员请假等风险。总工期12周 = 10周开发 + 2周测试上线。