SOFTWARE DESIGN DOCUMENT

汽修门店数字化系统 · 开发设计文档

文档编号 QX-SDD-2026-001　│　版本 V1.0　│　2026-11-08　│　对应需求 QX-SRS-2026-001 V1.0

项目代号	QX-Garage
交付形态	Web 管理端 + 技师安卓 APK + 客户微信小程序 + 定时任务与消息服务
部署形态	托管（乙方云主机）／私有化（甲方服务器），同一套镜像两种部署
首版范围	标准版功能集（轻量版为其子集，连锁版加多租户与总部视角）
关联文档	《需求说明书 QX-SRS-2026-001》《建设与运维服务报价单》《AI 自助修改能力方案 QX-AI-2026-001》

三条设计红线： ① 门店网络一断，前台还能开单；② 源码可交付，第三方能接手；③ 门店差异靠配置，不靠分支代码。后面所有技术选择都以这三条为约束。

1　设计目标与原则

目标	设计手段	验证方式
单人可交付、可维护	单体优先、模块内聚、模板库复用、无重型中间件依赖	新环境 30 分钟内跑起来
断网可用	前端本地库 + 出站队列 + 幂等键	拔网线做 5 单，恢复后数据一致
多端一致	uni-app 一套代码出小程序 / H5 / APK；业务接口统一	同一工单在三端显示一致
可交付源码	无闭源商业组件、无加密狗、构建脚本随源码交付	甲方服务器从零构建成功
门店差异可配置	字典、参数、价目表、流程开关全部落库	新增一家店不改代码，仅配置
升级不打断营业	蓝绿切换（托管）／停服窗口 ≤ 10 分钟（私有化）	升级演练两次

2　总体架构

采用「前后端分离 + 单体服务 + 异步任务」的务实架构。单体不是妥协，而是为了单店场景下的部署简单与交付成本可控；模块间以包边界隔离，为后续拆分预留接口。

┌─────────────────────────── 客户端 ───────────────────────────┐
│  Web 管理端(Vue3)   技师 APK(uni-app)   客户小程序(uni-app)   │
│  前台/库管/老板      报工·领料·拍照      查记录·确认·评价      │
└───────────────┬───────────────────┬──────────────────────────┘
                │ HTTPS / JSON      │ HTTPS
┌───────────────▼───────────────────▼──────────────────────────┐
│                    Nginx（TLS 终止 / 静态资源 / 限流）          │
└───────────────┬──────────────────────────────────────────────┘
┌───────────────▼──────────────────────────────────────────────┐
│  应用服务 Spring Boot 3（单体，按模块分包）                     │
│  ├ auth 认证授权      ├ cus 客户车辆     ├ biz 工单报价结算     │
│  ├ inv 库存采购       ├ fin 收款挂账     ├ mkt 提醒营销         │
│  ├ rpt 看板报表       ├ sys 系统管理     ├ job 定时任务         │
│  └ integration 微信/短信/支付/发票 适配层                       │
└──────┬───────────────┬───────────────┬───────────────────────┘
       │               │               │
┌──────▼─────┐  ┌──────▼─────┐  ┌──────▼──────┐  ┌───────────┐
│ MySQL 8    │  │ Redis      │  │ MinIO/本地  │  │ 外部通道  │
│ 业务数据    │  │ 缓存·锁·队列│  │ 图片附件    │  │ 微信/短信 │
└────────────┘  └────────────┘  └─────────────┘  └───────────┘

2.1　分层职责

层	职责	不做的事
接入层	TLS、静态资源、压缩、限流、请求体大小限制	不做业务判断
接口层（Controller）	参数校验、鉴权注解、DTO 转换、统一响应包装	不写业务逻辑、不直接访问 DAO
应用层（Service）	用例编排、事务边界、幂等控制、领域校验	不拼 SQL、不处理 HTTP
领域层（Domain）	实体、值对象、状态机、计价规则、库存扣减规则	不依赖框架
基础设施层	MyBatis 映射、Redis、文件存储、第三方适配	不含业务规则

3　技术选型

层面	选型	版本	理由
Web 管理端	Vue 3 + TypeScript + Vite + Element Plus	Vue 3.4+	国内生态成熟，门店一体机兼容好，AI 生成质量高
移动端	uni-app（Vue 3 语法）	3.x	一套代码出小程序 / H5 / APK，wgt 热更新成熟
后端	Spring Boot 3 + JDK 17	3.2+	私有化环境常见、招聘容易、第三方对接 SDK 齐全
持久层	MyBatis-Plus	3.5+	SQL 可控，复杂报表好写，门店侧 DBA 能看懂
数据库	MySQL 8.0（兼容 MariaDB 10.11）	8.0.36	私有化客户常已有；分区与窗口函数够用
缓存/队列	Redis 7	7.2	验证码、会话、分布式锁、轻量队列（Stream）
文件存储	MinIO（S3 协议）或本地磁盘	RELEASE.2024+	可私有化，接口标准，迁移成本低
任务调度	Spring Scheduler + Redis 分布式锁	—	单机场景无需引入 XXL-Job；多店再升级
部署	Docker Compose	24+	一键起停，门店/小客户足够；规模上来再上 K8s
监控	Spring Actuator + Prometheus + 日志轮转	—	轻量、可私有化、不依赖云厂商

4　模块设计

模块与需求编号、模板编号一一对应，便于排期与验收对齐。

模块	包名	核心职责	覆盖需求	模板
认证授权	`auth`	登录、令牌、RBAC、数据范围、密码策略	FR-31、FR-33	—
客户车辆	`cus`	客户档案、车辆档案、标签、欠款视图	FR-02	T05
工单	`biz.order`	接车开单、状态机、派工、追加、返修	FR-01、03、07、09、13	T01、T03
报价	`biz.quote`	价目、算价、版本、推送、客户确认、改价审批	FR-04～06	T02
结算	`fin.settle`	结算单、组合支付、折扣审批、日结月结	FR-14、16、18	T04
挂账	`fin.credit`	欠款台账、还款冲销、账龄	FR-15	T04
库存	`inv`	配件主数据、出入库、盘点、预警、批次成本	FR-19～22	T07
采购	`inv.purchase`	采购单、退货、供应商对账、应付	FR-23	T08
提醒营销	`mkt`	到期推算、提醒任务、回访、优惠券	FR-24、25、27	T06、T12
报表	`rpt`	看板聚合、提成计算、导出	FR-29、30、32	T10、T09
系统	`sys`	参数、字典、日志、版本发布、备份任务	FR-33、34	—
集成	`integration`	微信、支付、短信、发票、打印适配	第 8 章接口	—

4.1　工单状态机

CREATED ──派工──▶ ASSIGNED ──开工──▶ WORKING ──完工──▶ DONE
   │                  │                  │              │
   │                  │                  │              └─结算─▶ SETTLED ──交车──▶ CLOSED
   │                  │                  └─待料─▶ WAITING_PART ──到货──▶ WORKING
   │                  └─取消─▶ CANCELLED（需审批）
   └─客户不确认报价─▶ QUOTE_PENDING（超 24h 提醒）
禁止跳转：CREATED → DONE；SETTLED → WORKING（需返修单，另立工单并关联）

5　数据模型

5.1　表清单

表名	说明	关键索引
`cus_customer`	客户	uk(mobile)、idx(name)
`cus_vehicle`	车辆	uk(plate_no)、idx(customer_id)、idx(next_service_mileage)
`biz_order`	工单主表	uk(order_no)、idx(vehicle_id,created_at)、idx(status)
`biz_order_item`	工单明细（项目/配件）	idx(order_id)、idx(part_id)
`biz_quote`	报价单（含版本）	idx(order_id,version)
`biz_quote_confirm`	客户确认记录	uk(quote_id)
`biz_work_log`	施工报工与照片	idx(order_id)、idx(tech_id,work_date)
`inv_part`	配件主数据	uk(part_code)、idx(name)、idx(category)
`inv_stock`	库存余额（按仓库/批次）	uk(part_id,warehouse_id,batch_no)
`inv_stock_log`	库存流水	idx(part_id,created_at)、idx(ref_no)
`inv_purchase` / `inv_purchase_item`	采购与明细	idx(supplier_id,status)
`fin_settle`	结算单	uk(order_id)、idx(settle_date)
`fin_payment`	收款流水	idx(settle_id)、idx(pay_time)
`fin_credit`	挂账台账	idx(customer_id,status)、idx(due_date)
`mkt_remind`	提醒任务	idx(remind_date,status)、idx(vehicle_id)
`mkt_coupon` / `mkt_coupon_log`	优惠券与核销	idx(customer_id,status)
`sys_user` / `sys_role` / `sys_user_role` / `sys_permission`	账号与权限	uk(username)
`sys_config` / `sys_dict`	参数与字典	uk(config_key)、uk(dict_type,dict_code)
`sys_audit_log`	操作日志	idx(user_id,created_at)、idx(target_type,target_id)
`sys_app_version`	客户端版本与升级包	uk(platform,version_code)
`sys_outbox`	出站消息队列（离线补偿）	idx(status,next_retry_at)

5.2　核心表结构（节选）

-- 工单主表
CREATE TABLE biz_order (
  id            BIGINT PRIMARY KEY AUTO_INCREMENT,
  order_no      VARCHAR(24)  NOT NULL COMMENT 'RO+日期+序号',
  customer_id   BIGINT       NOT NULL,
  vehicle_id    BIGINT       NOT NULL,
  mileage_in    INT          NOT NULL COMMENT '进厂里程',
  fuel_level    TINYINT      NULL     COMMENT '油量 0-8',
  status        VARCHAR(20)  NOT NULL DEFAULT 'CREATED',
  advisor_id    BIGINT       NULL     COMMENT '服务顾问',
  tech_id       BIGINT       NULL     COMMENT '主修技师',
  quote_amount  DECIMAL(12,2) NOT NULL DEFAULT 0,
  settle_amount DECIMAL(12,2) NOT NULL DEFAULT 0,
  promise_at    DATETIME     NULL     COMMENT '承诺交车时间',
  closed_at     DATETIME     NULL,
  remark        VARCHAR(500) NULL,
  created_at    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  tenant_id     BIGINT       NOT NULL DEFAULT 1,
  UNIQUE KEY uk_order_no (order_no),
  KEY idx_vehicle (vehicle_id, created_at),
  KEY idx_status (tenant_id, status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 库存流水（只增不改，余额由流水推导 + 快照校验）
CREATE TABLE inv_stock_log (
  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
  part_id     BIGINT NOT NULL,
  warehouse_id BIGINT NOT NULL DEFAULT 1,
  batch_no    VARCHAR(32) NULL,
  biz_type    VARCHAR(16) NOT NULL COMMENT 'PURCHASE/ISSUE/RETURN/ADJUST/CHECK',
  qty         DECIMAL(12,3) NOT NULL COMMENT '正入负出',
  unit_cost   DECIMAL(12,4) NULL,
  ref_type    VARCHAR(16) NULL COMMENT 'ORDER/PURCHASE/CHECK',
  ref_no      VARCHAR(32) NULL,
  operator_id BIGINT NOT NULL,
  created_at  DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_part_time (part_id, created_at),
  KEY idx_ref (ref_type, ref_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

5.3　关键设计说明

库存只记流水：inv_stock 只存当前余额快照，任何变动必须写 inv_stock_log，两者由事务保证一致；每日 02:30 跑一次「流水汇总 = 余额」校验，不一致即告警。
金额用 DECIMAL：禁止 float；单价 4 位小数、金额 2 位小数，四舍五入在服务端统一处理。
软删除：主数据用 deleted_at，业务单据不删除，只做状态流转。
多租户：所有业务表带 tenant_id，MyBatis 拦截器自动注入，连锁版按门店隔离。
幂等：结算、收款、领料接口必须带 Idempotency-Key，服务端落 sys_outbox 去重。

6　接口设计

6.1　通用约定

风格：REST + JSON，版本前缀 /api/v1。
认证：Authorization: Bearer <access_token>，有效期 2 小时，refresh_token 14 天。
响应：{ "code": 0, "msg": "ok", "data": {...}, "traceId": "..." }，非 0 为业务错误。
分页：?page=1&size=20&sort=created_at,desc，返回 {list,total,page,size}。
时间：ISO 8601 带时区（2026-11-08T10:30:00+08:00）。
幂等：POST 写操作支持 Idempotency-Key，24 小时内重复请求返回首次结果。

6.2　接口清单（首版）

方法	路径	说明	权限
POST	`/auth/login`	账号密码登录	公开
POST	`/auth/wx-login`	微信扫码/小程序登录	公开
POST	`/auth/refresh`	刷新令牌	登录
GET	`/customers` · `/customers/{id}`	客户查询、详情（含车辆与欠款）	前台/老板
POST	`/customers`	新建客户	前台
GET	`/vehicles/by-plate/{plate}`	按车牌带出档案（开单用）	前台/技师
POST	`/orders`	接车开单	前台
GET	`/orders/{id}`	工单详情	按数据范围
PATCH	`/orders/{id}/status`	状态流转（派工/开工/完工/待料）	前台/技师
POST	`/orders/{id}/items`	增加项目或配件	前台/技师
POST	`/orders/{id}/quotes`	生成报价单（新版本）	前台
POST	`/quotes/{id}/send`	推送微信/短信	前台
POST	`/quotes/{id}/confirm`	客户确认（小程序，无需登录态，带签名 token）	客户
POST	`/quotes/{id}/approve-discount`	折扣/改价审批	老板
POST	`/orders/{id}/worklogs`	报工与照片	技师
POST	`/orders/{id}/issue-parts`	领料出库	技师/库管
POST	`/orders/{id}/settle`	结算（含组合支付）	前台
POST	`/settles/{id}/payments`	追加收款/还款	前台
GET	`/credits`	挂账台账（按账龄）	老板/前台
GET	`/parts` · `POST /parts`	配件查询与维护	库管
POST	`/stock/in` · `/stock/out` · `/stock/check`	入库、出库、盘点	库管
GET	`/stock/alerts`	低库存预警	库管/老板
GET	`/reminders` · `POST /reminders/{id}/send`	到期提醒名单与发送	前台
GET	`/dashboard/summary`	看板汇总（日/周/月）	老板
GET	`/reports/settlement-daily`	日结单	老板/前台
GET	`/app/version`	客户端版本检查与升级包	公开（带签名）
POST	`/sync/batch`	离线数据批量补传	登录

6.3　示例：生成报价单

POST /api/v1/orders/10231/quotes
Authorization: Bearer <token>
Idempotency-Key: 7c1f9a2e-...

{
  "items": [
    {"type":"LABOR","name":"更换机油机滤","qty":1,"unitPrice":80},
    {"type":"PART","partId":8801,"qty":4,"unitPrice":95}
  ],
  "validHours": 24,
  "remark": "建议同时更换空气滤芯"
}

200 OK
{
  "code":0,"msg":"ok",
  "data":{
    "quoteId":5521,"version":2,
    "amount":460.00,
    "shareUrl":"https://qx.example.com/q/8f3a...",
    "expireAt":"2026-11-09T10:30:00+08:00"
  },
  "traceId":"a1b2c3"
}

7　关键流程设计

7.1　开单到结算（主链路）

前台            服务端                    库存            客户
 │  POST /orders  │                        │               │
 │───────────────▶│ 校验车牌/生成单号       │               │
 │◀───────────────│ 201 {orderId,no}       │               │
 │  POST /quotes  │                        │               │
 │───────────────▶│ 算价(价目表)→落库       │               │
 │                │ 推送微信(异步)          │               │
 │                │───────────────────────────────────────▶│ 收到报价
 │                │◀───────────────────────────────────────│ 确认
 │  POST issue    │                        │               │
 │───────────────▶│ 事务：扣库存+写流水      │               │
 │                │───────────────▶│ 余额更新        │
 │  POST settle   │                        │               │
 │───────────────▶│ 事务：结算+收款+状态     │               │
 │◀───────────────│ 200 {settleId}         │               │
失败处理：库存不足 → 409 + 可替代件；微信推送失败 → 落 sys_outbox 重试 3 次后降级短信

7.2　到期提醒

每日 06:30 定时任务扫描 cus_vehicle：里程预测（上次里程 + 年均里程 × 月数）或时间阈值（上次保养 + 6 个月）。
命中生成 mkt_remind 记录，状态 PENDING，按客户去重（30 天内不重复提醒同一车）。
前台在「今日待提醒」一键发送：优先微信模板消息，未关注则短信，均失败标记 FAILED 并转人工电话。
客户回厂开单后，自动把提醒标记 CONVERTED，用于统计回厂率。

7.3　安卓客户端升级

类型	触发	机制	回滚
资源热更新	启动或每 6 小时	uni-app wgt 包（仅前端资源），下载校验 md5 后静默生效，下次启动加载	保留上一版本 wgt，失败自动回退
整包升级	原生能力变更时	下载 APK → 校验签名与 md5 → FileProvider 拉起安装	服务器保留上一版 APK
强制升级	接口不兼容	版本号低于 minVersion 时拦截主流程，只允许升级	—

GET /api/v1/app/version?platform=android&versionCode=1042
{
  "code":0,"data":{
    "latest":{"versionCode":1051,"versionName":"1.5.1","type":"WGT",
              "url":"https://.../app-1051.wgt","md5":"9f2c...","size":1834211},
    "minVersionCode":1030,
    "force":false,
    "note":"修复结算页金额显示问题"
  }
}

升级不能丢单：升级前检查本地未提交队列，非空则提示「有 2 单未同步，请先联网提交」，避免升级包覆盖本地暂存。

7.4　离线同步

前端用 IndexedDB 维护 outbox 表，每笔写操作带 clientId + seq。
恢复网络后按 seq 顺序调用 /sync/batch，服务端按 clientId 幂等去重。
冲突判定：服务端记录的 updated_at 晚于客户端基线时返回 409 CONFLICT，前端弹窗让前台选择「以本地为准」或「以服务器为准」。
库存类操作不在离线范围（必须在线），避免超卖。

8　多端构建与发布

端	技术	构建产物	发布方式	注意
Web 管理端	Vue3 + Vite	静态资源	Nginx 托管，版本目录 + 软链切换	index.html 禁缓存，资源文件名带 hash
技师 APK	uni-app → Android	APK（含 wgt）	自有分发页扫码安装；应用商店可选	需软著与 APP 备案；签名密钥离线保管
客户小程序	uni-app → 微信小程序	小程序包	微信开发者工具上传 → 提审 → 发布	类目选「汽车服务」，需服务类目资质
客户 H5	uni-app → H5	静态资源	与 Web 同域部署	微信内需配置 JS 安全域名
iOS	—	源码	按需交付源码，由甲方自行上架	首版不做 iOS 原生，客户侧走小程序
鸿蒙	—	源码	按需评估（不建议本行业采购）	需 DevEco 工具链，工时约 16 人时

8.1　构建流水线

git tag v1.5.1
  ├─ 后端：mvn -Pprod package → 镜像 app:1.5.1 → 推送仓库
  ├─ Web ：pnpm build → dist-1.5.1 → 上传 /var/www/releases
  ├─ 小程序：uni build:mp-weixin → CI 上传体验版 → 人工提审
  └─ APK ：uni build:app → 签名 → 生成 wgt + apk → 写入 sys_app_version

9　AI 辅助开发流水线

本项目以「模板库 + AI 生成 + 编译验证」的方式交付，AI 是产能工具，不是质量保证。每一环都有硬门禁：

阶段	输入	AI 做什么	人工门禁
1 需求落表	需求确认表 + 流程录屏	把口头需求转成 FR 条目与字段清单	与老板逐条确认，冻结版本
2 模板选型	FR 清单	匹配 T01～T15，给出差异点	确认复用边界，非标部分单独估时
3 代码生成	模板 + 字段映射	生成 CRUD、页面、接口、迁移脚本	Code Review：金额、库存、权限三处必查
4 编译构建	源码	自动修复编译错误（最多 3 轮）	构建产物可安装、可启动
5 真机验证	APK + 门店网络	生成测试用例与边界数据	20 笔真实工单跑通
6 回归与交付	验收清单	对比需求条目核对覆盖	甲方签字，进入质保

三条禁止： 禁止把客户真实数据投喂给外部模型；禁止跳过真机验证直接上线；禁止在未评审的情况下让 AI 修改库存与结算逻辑。生成代码必须经过与手写代码相同的评审与测试流程。

10　部署与运维

10.1　部署拓扑

Internet
   │ 443
┌──▼─────────────────────────────────────────┐
│ 云主机 / 门店服务器（4C8G 起，100G SSD）    │
│  ├ nginx        :443  静态 + 反代           │
│  ├ app          :8080  Spring Boot          │
│  ├ mysql        :3306  仅内网               │
│  ├ redis        :6379  仅内网               │
│  ├ minio        :9000  仅内网 / 或本地磁盘  │
│  └ backup cron  每日 02:00 全量 + 异地同步  │
└────────────────────────────────────────────┘

10.2　环境

环境	用途	数据	升级策略
dev	开发自测	造数	随时
staging	甲方验收演练	脱敏样本	上线前 2 天
prod	门店生产	真实数据	停服窗口 ≤ 10 分钟，提前 3 天预约

10.3　备份与恢复

数据库：每日 02:00 mysqldump --single-transaction，压缩后保留 30 天；每月 1 日全量归档保留 12 个月。
附件：MinIO 桶每日增量同步到备份目录，保留 30 天。
演练：每季度做一次恢复演练，记录 RTO/RPO 实测值。
私有化客户：提供备份脚本与恢复手册，备份介质由甲方提供。

10.4　监控与告警

指标	阈值	告警方式
接口 5xx 比例	> 1%（5 分钟）	企业微信机器人 + 短信
接口 P95 耗时	> 2s（10 分钟）	企业微信机器人
磁盘使用率	> 85%	短信
备份任务	失败	短信 + 电话
Outbox 积压	> 100 条或最老超 30 分钟	企业微信机器人
库存流水与余额不一致	> 0 条	短信（P1 工单）

11　安全设计

风险	措施
越权访问	接口级 `@PreAuthorize` + 数据范围拦截器（tenant/store/本人），默认拒绝
令牌泄露	access 2 小时、refresh 14 天且可吊销；异地登录提醒；退出即失效
密码爆破	bcrypt(cost=10)；5 次失败锁定 10 分钟；登录失败不区分账号是否存在
SQL 注入	全部参数化；禁止字符串拼接 SQL；导出类接口白名单字段
XSS / CSRF	前端转义 + CSP；写接口校验 Origin；Cookie 仅 SameSite=Lax
文件上传	白名单扩展名 + MIME 校验 + 大小限制 + 存储路径与文件名随机化，禁止执行权限
敏感数据	手机号 AES-GCM 加密存储，展示脱敏；导出需二次验证并记日志
接口重放	时间戳 + nonce + 签名；幂等键 24 小时
限流	Nginx 层 IP 限流；登录、短信、报价推送单独配额
审计	改价、折扣、库存调整、导出、删除全量入库，日志表禁止 UPDATE/DELETE

平台合规红线： 不使用个人微信机器人、群控或任何外挂式接入；所有消息与支付走官方接口。微信对个人号自动化明确按「外挂」处理，存在封号与不正当竞争风险（已有判赔判例）。

12　性能与容量

场景	数据量	目标	手段
工单列表	10 万条	< 1.5s	复合索引 (tenant_id, status, created_at)；只查必要字段；默认 20 条分页
看板汇总	30 万条明细	< 2s	每小时预聚合到 `rpt_daily`；当日数据实时查 + 缓存 60s
库存校验	5,000 SKU	< 200ms	余额表直接读；扣减用 `UPDATE ... WHERE qty >= ?` 乐观扣减
批量导入	5,000 行	< 3 分钟	分批 500 行 + 异步任务 + 进度轮询
图片上传	单张 2MB	< 3s	前端压缩到 1080p、WebP；直传 MinIO 预签名 URL

容量规划：单店首年数据约 2～5 GB（含图片 20～60 GB），4C8G + 100G SSD 足够；20 店以内单机可承载，超过 20 店建议拆库或上 K8s。

13　风险与对策

风险	影响	概率	对策
微信接口/规则变更	推送、支付失效	中	集成层做适配器与降级（短信/手工）；关注官方公告；合同约定第三方变更免责
门店网络不稳	无法开单	高	离线队列 + 本地暂存；上线前测速，必要时配 4G 备份路由
需求蔓延	工期与毛利双杀	高	需求冻结 + 变更单 + 人时上限；单均人时超 1.4 倍即止损
数据迁移质量差	上线延期、客诉	中	先抽样 50 条核对；字段缺失列清单由甲方确认
单人交付依赖	人员变动导致断档	中	模板库 + 文档化 + 源码交付；关键模块双人 Review
AI 生成代码缺陷	金额/库存错误	中	三处强制 Review（金额、库存、权限）+ 单元测试覆盖核心规则
模型调用成本失控	毛利下降	中	模板复用降低生成轮次；设置单项目 token 预算与告警

14　附录

14.1　错误码

码	含义	前端处理
0	成功	—
1001	参数校验失败	字段级提示
1002	未登录或令牌过期	跳登录 / 静默刷新
1003	无权限	提示并隐藏入口
2001	库存不足	展示可替代件与到货时间
2002	工单状态不允许该操作	刷新详情
2003	金额不平（组合支付）	高亮差额
2004	重复请求（幂等命中）	直接使用首次结果
3001	第三方通道失败	降级提示 + 重试
3002	数据冲突（离线同步）	弹窗二选一

14.2　代码结构

qx-garage/
├─ server/                 Spring Boot
│  ├─ qx-common/           通用：响应、异常、工具、审计
│  ├─ qx-domain/           实体、状态机、计价与库存规则
│  ├─ qx-app/              用例编排、事务、DTO
│  ├─ qx-infra/            MyBatis、Redis、MinIO、第三方适配
│  └─ qx-boot/             启动、配置、定时任务
├─ web/                    Vue3 管理端
├─ mobile/                 uni-app（技师端 + 客户小程序）
├─ deploy/                 docker-compose、nginx、备份脚本
└─ docs/                   本套文档与接口说明

14.3　交付物清单

可运行系统（含初始化数据与演示账号）
源代码（server / web / mobile）与构建脚本
数据库脚本（建表 + 字典 + 初始化）
部署文档、备份恢复手册、升级说明
操作手册（前台 / 技师 / 老板三份，图文）
接口文档（OpenAPI 导出）与测试用例

本文档为 V1.0 首版，与需求说明书同步评审；技术选型如需调整须走变更单。文档编号 QX-SDD-2026-001。

汽修门店数字化系统 · 开发设计文档

1 设计目标与原则

2 总体架构

2.1 分层职责

3 技术选型

4 模块设计

4.1 工单状态机

5 数据模型

5.1 表清单

5.2 核心表结构（节选）

5.3 关键设计说明

6 接口设计

6.1 通用约定

6.2 接口清单（首版）

6.3 示例：生成报价单

7 关键流程设计

7.1 开单到结算（主链路）

7.2 到期提醒

7.3 安卓客户端升级

7.4 离线同步

8 多端构建与发布

8.1 构建流水线

9 AI 辅助开发流水线

10 部署与运维

10.1 部署拓扑

10.2 环境

10.3 备份与恢复

10.4 监控与告警

11 安全设计

12 性能与容量

13 风险与对策

14 附录

14.1 错误码

14.2 代码结构

14.3 交付物清单