汽车年检预约系统

技术方案文档
文档编号INS-SYS-TS-001
版本V1.0
编制日期2026-08-15
密级内部

目 录

1 文档概述

本文档是汽车年检预约系统的技术方案文档,基于《软件需求规格说明书(SRS)》编写,作为系统设计、开发、测试的技术基准。

1.1 文档目的

1.2 参考文档

文档编号版本
软件需求规格说明书(SRS)INS-SYS-SRS-001V1.0
用户需求文档(URD)INS-SYS-URD-001V1.0
需求追踪矩阵(RTM)INS-SYS-RTM-001V1.0

2 技术选型决策

2.1 选型原则

核心原则:技术为业务服务,没有最好的技术,只有最适合的技术。

2.2 前端选型

2.2.1 候选方案对比

维度权重微信原生uni-app (Vue3)Taro (React)
业务匹配30%909280
技术成熟20%958580
团队能力20%709060
学习成本10%608565
维护成本10%808580
社区支持5%908580
扩展性5%509085
加权总分78.387.873.5

2.2.2 决策结论

选择:uni-app (Vue3)
• 团队Vue熟练,学习成本最低
• 一套代码支持微信小程序+H5+App,未来可扩展
• DCloud团队持续维护,社区活跃
• 关键API(扫码、定位、支付)都有良好封装

2.3 后端选型

2.3.1 候选方案对比

维度权重Spring BootNode.js (Nest)Go (Gin)
业务匹配30%927882
技术成熟20%958580
团队能力20%926050
学习成本10%856545
维护成本10%858090
社区支持5%959080
扩展性5%888592
加权总分90.375.371.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-appVue3版微信小程序 + 未来H5/App
UI组件库uView Plus3.xuni-app生态UI库
后端框架Spring Boot3.2+RESTful API服务
ORM框架MyBatis-Plus3.5+数据库操作
权限框架Spring Security + JWT6.x认证鉴权
定时任务XXL-Job2.4+年检提醒等定时任务
接口文档Knife4j4.xSwagger增强
关系数据库MySQL8.0+业务数据存储
缓存Redis7.x缓存 + 分布式锁
容器化Docker24+应用容器化
反向代理Nginx1.24+负载均衡 + HTTPS
CI/CDGitHub Actions-自动化构建部署
监控Prometheus + Grafana-系统监控告警

3 系统架构设计

3.1 整体架构图

汽车年检预约系统整体架构图

图3-1 系统整体架构图

3.2 部署架构图

汽车年检预约系统部署架构图

图3-2 部署架构图(阿里云ECS + Docker)

3.3 技术架构分层

层级职责技术
表现层用户界面,交互逻辑uni-app / Vue3 + Element Plus
接入层反向代理,负载均衡,HTTPSNginx
接口层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)  // 价格越低分越高

5 数据库设计

5.1 ER图

汽车年检预约系统ER图

图5-1 实体关系图(ER图)

5.2 核心表设计

5.2.1 用户表(user)

字段名类型必填说明
idBIGINT是主键,自增
openidVARCHAR(64)是微信openid,唯一索引
phoneVARCHAR(20)否手机号,AES加密存储
nameVARCHAR(50)否用户姓名
avatar_urlVARCHAR(255)否头像URL
created_atDATETIME是创建时间
updated_atDATETIME是更新时间

5.2.2 车辆表(vehicle)

字段名类型必填说明
idBIGINT是主键,自增
user_idBIGINT是用户ID,外键
plate_numberVARCHAR(20)是车牌号
vinVARCHAR(50)否车架号
engine_numberVARCHAR(50)否发动机号
brandVARCHAR(50)否品牌型号
register_dateDATE是注册日期
vehicle_typeTINYINT是1小型 2大型
fuel_typeTINYINT是1汽油 2柴油 3新能源
next_inspection_dateDATE是下次年检日期
is_exemptBOOLEAN是是否6年免检

5.2.3 检测站表(station)

字段名类型必填说明
idBIGINT是主键,自增
nameVARCHAR(100)是检测站名称
addressVARCHAR(200)是详细地址
phoneVARCHAR(20)是联系电话
longitudeDECIMAL(10,6)是经度
latitudeDECIMAL(10,6)是纬度
ratingDECIMAL(2,1)否评分(1-5)
priceDECIMAL(10,2)否检测价格(元)
daily_capacityINT是每日检测能力
business_hoursVARCHAR(50)是营业时间
statusTINYINT是1正常 0关闭

5.2.4 预约时段表(time_slot)

字段名类型必填说明
idBIGINT是主键,自增
station_idBIGINT是检测站ID,外键
dateDATE是日期
start_timeTIME是开始时间
end_timeTIME是结束时间
total_capacityINT是总名额
booked_countINT是已预约数
versionINT是乐观锁版本号

5.2.5 预约订单表(appointment_order)

字段名类型必填说明
idBIGINT是主键,自增
user_idBIGINT是用户ID,外键
vehicle_idBIGINT是车辆ID,外键
station_idBIGINT是检测站ID,外键
slot_idBIGINT是时段ID,外键
order_noVARCHAR(32)是订单号,唯一索引
statusTINYINT是0待签到 1已签到 2检测中 3合格 4不合格 5已取消 6已爽约
check_in_timeDATETIME否签到时间
complete_timeDATETIME否完成时间
cancel_timeDATETIME否取消时间

5.3 索引策略

表索引类型用途
useropenid唯一索引微信登录查询
vehicleuser_id普通索引用户车辆列表
vehiclenext_inspection_date普通索引年检提醒扫描
stationlatitude, longitude联合索引地理位置查询
time_slotstation_id, date联合索引可用时段查询
appointment_orderorder_no唯一索引订单号查询
appointment_orderuser_id普通索引用户订单列表
inspection_progressorder_id, step_order联合索引进度查询
remind_logvehicle_id, remind_type, remind_date联合索引防重复提醒

6 API设计

6.1 用户模块

方法路径说明鉴权
POST/api/user/login微信登录否
GET/api/user/profile获取用户信息是
PUT/api/user/profile更新用户信息是

6.2 车辆模块

方法路径说明鉴权
GET/api/vehicle/list我的车辆列表是
POST/api/vehicle添加车辆(手动/OCR)是
PUT/api/vehicle/{id}更新车辆信息是
DELETE/api/vehicle/{id}删除车辆是
POST/api/vehicle/ocrOCR识别行驶证是

6.3 检测站模块

方法路径说明鉴权
GET/api/station/list检测站列表(距离/评分/空闲排序)是
GET/api/station/{id}检测站详情是
GET/api/station/{id}/slots可预约时段是

6.4 预约模块

方法路径说明鉴权
POST/api/appointment创建预约是
PUT/api/appointment/{id}/cancel取消预约是
GET/api/appointment/list我的预约列表是
POST/api/appointment/{id}/checkin扫码签到是

6.5 检测模块

方法路径说明鉴权
GET/api/inspection/{orderId}/progress检测进度是
GET/api/inspection/{orderId}/report检测报告是

6.6 管理后台模块

方法路径说明鉴权
GET/api/admin/station/list检测站管理列表管理员
POST/api/admin/station添加检测站管理员
PUT/api/admin/station/{id}更新检测站管理员
GET/api/admin/order/list预约订单列表管理员
PUT/api/admin/progress/{orderId}更新检测进度检测站
GET/api/admin/statistics数据统计管理员

7 安全设计

安全维度措施实现方式
传输安全全站HTTPSNginx配置SSL证书(Let's Encrypt免费证书)
认证鉴权JWT TokenSpring Security + JWT,Token有效期2小时
数据加密敏感字段AES加密手机号、身份证号AES-256加密存储
SQL注入防护参数化查询MyBatis-Plus自动参数化
XSS防护HTML转义前端输出时转义,后端入库前过滤
CSRF防护Token验证JWT机制天然防CSRF
接口限流Redis限流同一IP每分钟最多60次请求
短信防刷验证码限频同一手机号60秒1次,每天10次
数据备份每日全量+每小时增量阿里云RDS自动备份
日志审计操作日志记录关键操作记录到audit_log表

8 性能设计

场景指标方案
检测站列表≤1秒Redis缓存热门城市检测站列表,30分钟过期
预约提交≤500msRedis分布式锁 + 乐观锁,异步写入
并发预约100并发数据一致Redis扣减 + MySQL乐观锁双重保障
检测进度≤300msRedis缓存,30秒过期
页面首屏≤2秒图片懒加载 + 接口并行请求
短信发送到达率≥99%阿里云短信,失败自动重试

8.1 缓存策略

缓存项Key格式过期时间更新策略
检测站列表station:list:{city}30分钟主动更新+过期淘汰
检测站详情station:detail:{id}10分钟主动更新
可用时段slot:available:{stationId}:{date}5分钟预约时主动清除
检测进度progress:{orderId}30秒更新时主动清除
用户信息user:info:{userId}1小时更新时主动清除

9 技术风险与应对

风险概率影响应对方案
检测站数据获取难高高MVP人工录入,同时谈合作;先做一个城市验证
实时进度对接难高中MVP检测站后台人工更新,后期对接设备
并发预约超卖中高Redis分布式锁+MySQL乐观锁双重保障
小程序审核被拒中中提前准备资质,预留缓冲时间
阿里云短信签名审核慢中低提前1个月申请,备用腾讯云短信
OCR识别率不够低中识别后让用户确认,失败允许手动输入
Redis分布式锁失效低高使用Redisson,自带看门狗续期+红锁

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

请求参数

字段类型必填说明示例
vehicleIdLong是车辆ID1001
slotIdLong是时段ID5001

响应参数

字段类型说明示例
orderIdLong预约订单ID8001
orderNoString订单编号INS20260815001
stationNameString检测站名称XX检测站
appointmentTimeString预约时间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

请求参数

字段类型必填说明示例
idLong是路径参数,订单ID8001
stationCodeString是检测站二维码内容STATION_001

业务规则

响应示例

// 成功
{
    "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

响应参数

字段类型说明
orderIdLong订单ID
currentStepString当前检测环节
completedStepsInteger已完成环节数
estimatedMinutesInteger预计剩余分钟数
stepsArray6个检测环节详情

响应示例

{
    "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

请求参数

字段类型必填说明示例
latitudeDouble是用户纬度39.9042
longitudeDouble是用户经度116.4074
sortByString否排序方式:distance/rating/queue/price,默认distancedistance
pageNumInteger否页码,默认11
pageSizeInteger否每页数量,默认1010

响应示例

{
    "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/listJWT需要登录
POST /api/appointmentJWT需要登录
POST /api/appointment/{id}/checkinJWT需要登录
GET /api/admin/*JWT + 角色校验需要管理员角色

12 部署方案

12.1 服务器配置

资源规格用途月成本
阿里云ECS2核4G,50G SSD运行所有服务¥200
域名.com域名API域名¥60/年
SSL证书Let's EncryptHTTPS免费
阿里云RDSMySQL 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防护已验证□
监控告警服务器监控和告警已配置□
数据备份自动备份策略已配置□

13 日志与监控

13.1 日志规范

日志级别使用场景示例
ERROR系统异常、外部服务调用失败、数据不一致Redis连接失败、短信发送异常
WARN业务异常、降级处理、性能告警预约时段已满、接口响应超时
INFO关键业务操作、状态变更用户登录、预约创建、签到成功
DEBUG调试信息(仅开发环境)SQL执行、Redis操作

13.2 关键日志记录点

操作日志级别记录内容
用户登录INFOuserId, openid, loginTime, ip
创建预约INFOuserId, orderId, slotId, stationId
预约并发冲突WARNuserId, slotId, conflictCount
签到成功INFOuserId, orderId, checkInTime
检测进度更新INFOorderId, step, status, operator
短信发送INFOphone(脱敏), type, result, cost
短信发送失败ERRORphone(脱敏), type, errorCode, errorMsg
Redis操作异常ERRORkey, operation, exception
接口响应超时WARNurl, method, costMs, threshold

13.3 监控指标

维度指标告警阈值
服务器CPU使用率>80% 持续5分钟
服务器内存使用率>85% 持续5分钟
服务器磁盘使用率>90%
应用接口响应时间(P99)>1秒
应用接口错误率>1% 持续5分钟
应用JVM堆内存使用率>80%
数据库连接数>80% 最大连接数
数据库慢查询数量>10条/分钟
Redis内存使用率>80%
Redis连接数>100
业务预约成功率<95%
业务短信到达率<99%

13.4 监控方案

工具用途配置
Prometheus指标采集Spring Boot Actuator暴露 /actuator/prometheus
Grafana可视化看板预置JVM、HTTP、MySQL、Redis看板
AlertManager告警通知配置告警规则,通知到钉钉/飞书/短信
阿里云日志服务日志收集与检索Logback配置输出到SLS

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 任务分解(甘特图)

任务 负责人 W1W2W3W4W5W6 W7W8W9W10W11W12
需求分析+技术方案全员 █
环境搭建+数据库设计后端A █
用户登录+车辆管理后端A █ █
检测站+时段管理后端B █ █
首页+检测站列表前端 █ █
预约+签到核心功能后端A █ █ █
检测进度+报告后端B █ █
预约+进度+签到页面前端 █ █ █
年检提醒定时任务后端A █
报告+自检+多车+计算器后端B+前端 █ █
管理后台+检测站后台前端+后端A █ █
功能测试+Bug修复测试+全员 █
性能测试+灰度发布+上线全员 █

█ = 任务执行周期 | 颜色:绿=后端,蓝=前端,橙=增值,紫=后台,红=测试上线

14.3 风险缓冲

每个里程碑预留2-3天缓冲时间,应对需求变更、技术难点、人员请假等风险。总工期12周 = 10周开发 + 2周测试上线。

15 成本估算

15.1 开发成本

角色人数月薪(估算)工期成本
后端开发2人¥20,0003个月¥120,000
前端开发1人¥18,0003个月¥54,000
测试1人¥15,0002个月¥30,000
人力成本小计¥204,000

15.2 基础设施成本(首年)

项目规格月成本年成本
阿里云ECS2核4G¥200¥2,400
域名.com-¥60
SSL证书Let's Encrypt-免费
阿里云短信约7万条/年¥230¥2,800
腾讯云OCR约5000次/年¥40¥500
腾讯地图API免费配额内-免费
阿里云OSS10G存储¥2¥24
基础设施成本小计¥5,784

15.3 总成本汇总

类别成本
人力成本(3个月)¥204,000
基础设施(首年)¥5,784
其他(办公、工具等)¥5,000
总成本¥214,784

15.4 成本优化建议