技术设计方案文档：“X超”智能体育助手小程序
文档状态: V1.0 创建日期: 2026-04-22 负责人: 高级架构师团队
一、业务定义与验收说明 (Product & Acceptance Spec)
1.1 需求描述
本项目旨在为大型体育赛事（对标“中网”）开发一款名为“X超”的微信小程序智能助手。该小程序需绑定客户自有公众号，为观赛用户提供一站式服务，核心解决停车难、找座难、信息获取难的问题。 核心功能优先级排序：
- P0 (核心流程): 车位一览与推荐、票务信息查询核验。
- P1 (体验增强): 观赛规则智能问答、基础版（非AR）座位分区导览。
- P2 (噱头/二期): AR分色实景导览。
1.2 核心指标
| 指标维度 | 指标项 | 目标值 | 验收标准 |
|---|---|---|---|
| 性能 | 小程序首屏加载 | < 1.5s | 4G弱网环境下首屏FCP |
| 性能 | 车位数据更新延迟 | < 30s | API轮询间隔与数据落库时差 |
| 业务 | 票务查询成功率 | 99.9% | 排除三方票务系统故障外 |
| 业务 | 问答准确率(关键词匹配) | 95% | 覆盖知识库内50-100条标准问法 |
| 体验 | 基础路线导览成功率 | 98% | 用户点击“导航”后成功拉起地图 |
1.3 不做清单 (Out of Scope)
- 不做 自建二维码生成与验票系统（仅做展示与核验跳转/查询）。
- 一期不做 复杂的AI大模型对话（仅用关键词匹配+云端兜底）。
- 一期不做 真实的3D建模/点云扫描AR导航（仅做模拟AR或2D高精度室内地图导航）。
- 不做 iOS/Android 全机型AR深度适配（AR功能若上，仅支持主流高端机型，低端机自动降级为2D地图）。
- 不做 后端服务器硬件采购与机房托管（全栈云开发/云托管）。
1.4 术语表
| 术语 | 定义 |
|---|---|
| X超 | 小程序项目代号 |
| 三方票务 | 指大麦、猫眼或客户私有票务系统API。 |
| 兜底方案 | 当AR失效或GPS弱时，回归到2D地图文字引导或人工客服。 |
| 分色/分区 | 指体育场看台的颜色区域划分（如A区红色，B区蓝色），用于快速定位。 |
1.5 价值评估
- 用户价值：减少30%寻车位时间，100%消除因找不到座位导致的场内拥堵。
- 商业价值：增强公众号粉丝粘性，降低现场引导志愿者人力成本。
- 技术价值：沉淀高并发赛事场景下的缓存穿透与降级方案。
1.6 风险评估 (关键！依据批复深化)
| 风险项 | 风险等级 | 影响 | 应对/缓解措施 |
|---|---|---|---|
| 三方票务API不稳定/无权限 | 高 | 票务功能不可用，项目延期。 | 1. 合同前置：明确需主办方提供API文档与测试Key。 2. Mock机制：开发阶段基于Mock数据先行。 3. 降级文案：接口超时展示“票务系统繁忙，请稍后或出示纸质票”。 |
| 停车场API覆盖不全/数据不准 | 高 | 推荐错误车位，引发投诉。 | 1. 冗余设计：支持手动录入车位余量（运营后台）。 2. 信心指数：UI显示数据更新时间，超过5分钟提示“数据仅供参考”。 |
| 场馆GPS信号弱/AR漂移 | 高 | 导航失效，用户迷失。 | 1. 技术选型降级：一期不做真实AR，改用2D矢量地图+蓝牙信标辅助定位。 2. 产品兜底：提供“拍照识图”功能（拍照当前场景，后台返回文字路径指引）。 |
| 客户UI/UX一票否决 | 中 | 反复修改，上线延期。 | 1. 采用成熟的组件库（TDesign）。 2. 快速产出高保真交互原型图确认，再编码。 |
| 资源资质到位慢 | 中 | 开发环境阻塞。 | 1. 开发方垫资开通云资源（Serverless按量付费）。 2. 域名、SSL证书提前申请，预留备案时间。 |
二、业务模块与总体架构 (Business Modules & Overall Architecture)
2.1 核心业务流程时序图 (车位+票务+导览)
2.2 DDD 限界上下文防腐
| 上下文 (Bounded Context) | 核心职责 | 防腐层 (Anti-Corruption Layer) |
|---|---|---|
| 车位上下文 (Parking Context) | 停车场聚合、余位计算、推荐算法 | ParkingAdapter 屏蔽不同停车场数据源（API A返回XML，API B返回JSON）的差异，统一转换为内部ParkingLot实体。 |
| 票务上下文 (Ticket Context) | 票夹展示、座位信息核验 | TicketTranslator 屏蔽大麦/猫眼/私有票务的数据字段差异。绝不直接暴露三方原始错误码给前端。 |
| 导览上下文 (Navigation Context) | 场馆GIS、路径规划、区域定位 | LocationGateway 封装微信小程序定位API与蓝牙信标SDK。若GPS精度<10米，自动降级为手动选点。 |
| 问答上下文 (FAQ Context) | 知识库检索、高频问题匹配 | 意图识别层：优先Elasticsearch/本地缓存关键词匹配，若无结果再调用云端AI API（如文心一言/通义千问），节省Token成本。 |
2.3 爆炸半径控制
- 部署隔离：车位服务、票务服务、基础用户服务独立部署在云托管的不同版本/服务中。
- 故障降级：
- 车位API挂 -> 前端展示静态地图+“停车场运营信息更新中”+ 客服电话。
- 票务API挂 -> 依然展示本地缓存的票务基本信息（若有），禁止白屏。
2.4 架构演进与扩展性预留
- AR模块预留：
Navigation Context内部设计IARProvider接口。- V1.0 实现：
MockARProvider(仅显示箭头贴纸+相机背景，无SLAM定位)。 - V2.0 实现：
ARKitProvider(需iPhone 12+ / 高端Android支持)。
- V1.0 实现：
2.5 组织匹配与容错
- 前端团队：负责小程序UI/UX及交互，不深入处理三方API差异。
- 后端团队：通过BFF层（Backend for Frontend）聚合原子服务，屏蔽后端复杂度，前端只需调用一个聚合接口。
三、成本与资源估算 (FinOps)
3.1 算力估算 (基于微信云托管)
- 场景：赛事期间日活约 1-2万人，并发请求主要集中在赛前2小时。
- 规格：最小副本数 2 (0.25核0.5G) + 弹性伸缩最大至 10。
- 预估月费：¥500 - ¥1500 (按量计费，非赛事期间缩容至0)。
3.2 存储与带宽成本
- CDN流量：小程序代码包+场馆地图SVG/PNG资源，约 50GB/月 -> ¥100。
- 数据库：云开发文档型数据库，存储票务缓存、用户问答日志 -> ¥50。
3.3 流量精算 (API调用费用)
| 服务 | 预估调用量 | 单价 | 月成本 |
|---|---|---|---|
| 三方票务API | 1万次查询 | 通常主办方免费提供 | ¥0 |
| 云端AI大模型 | 500次兜底调用 (Token) | ¥0.02/次 | ¥10 |
| 地图API (路径规划) | 2万次 | 微信小程序自带/免费额度内 | ¥0 |
四、编码实施与数据设计规范
4.1 业务流程与状态流转
显式状态机图 (票务查询状态)
异常分支与补偿时序图 (车位推荐)
- 异常：停车场API超时或返回乱码。
- 补偿：
- 后台定时任务（Cron）每5分钟抓取一次数据存入数据库。
- API实时查询失败时，降级读取数据库最后一次成功的时间戳数据。
- 若数据库也为空，返回静态配置的停车场列表（仅名称和固定电话）。
4.2 数据架构与生命周期
缓存防御策略 (重点解决车位高频查询)
- 缓存穿透：车位ID不存在 -> 布隆过滤器 (预热所有合法停车场ID)。
- 缓存击穿：热门场馆车位Key过期 -> 互斥锁 (Redisson) 保证只有一个线程去拉取三方API重构缓存。
- 缓存雪崩：所有车位Key同时过期 -> 随机TTL (30s + Random(1~10s))。
数据量级预估与归档策略
- 问答日志表：单日预估500条，按月归档至冷存储（COS），保留3个月。
4.3 接口设计与安全防御
明确错误码映射表 (票务模块)
| 三方票务原始错误 | 内部错误码 | 前端用户可见文案 |
|---|---|---|
TICKET_NOT_FOUND | 404001 | 暂无您的购票记录，请核对登录手机号。 |
ORDER_NOT_PAID | 402001 | 订单尚未支付，请完成支付后重试。 |
API_RATE_LIMIT | 429001 | 当前查询人数较多，请稍后再试。 |
SYSTEM_ERROR | 500000 | 系统繁忙，请下拉刷新或查看实体票。 |
水平越权校验逻辑 (关键安全点)
- 场景：用户查看
ticketId=1001的详情。 - 逻辑：后端服务层必须校验
SELECT user_id FROM ticket WHERE id = 1001。 - 强制约束：禁止仅依赖前端传入的
userId参数进行查询。必须从Header解析的JWT Token中提取当前登录用户ID。
4.4 稳定性与容灾设计
强依赖降级预案
| 强依赖服务 | 核心功能 | 降级预案 (B计划) |
|---|---|---|
| 三方票务API | 展示电子票 | 提示用户出示购票短信或纸质票，展示静态座位图。 |
| 场馆GPS信号 | AR/实景导航 | 强制切换至2D地图模式，展示文字路标（“向前50米右转”）。 |
| 停车场API | 显示余位 | 显示“当前余位数据更新延迟，仅供参考”，展示静态评价（车位充足/紧张）。 |
P0 告警规则提案
- 票务接口成功率 < 95% (5分钟内) -> 电话告警运维/开发。
- 车位接口响应时间 P99 > 2s -> 钉钉群告警，排查三方API网络。
五、测试策略与质量门禁
异常场景测试覆盖矩阵 (AR与GPS专项)
| 场景 | 前置条件 | 预期结果 |
|---|---|---|
| GPS信号弱 | 进入室内/地下室 | App自动提示“检测到GPS信号弱，已切换至室内地图模式”。 |
| AR初始化失败 | 低端Android机 | 自动跳过AR，直接展示2D指北针。 |
| 摄像头权限拒绝 | 点击“AR导航” | 弹窗引导去设置页开启，同时保留“文字导航”入口。 |
| 三方票务返回乱码 | Mock Server配置 | 小程序不Crash，展示通用错误提示。 |
六、上线回滚与运维手册
6.1 功能开关 (Feature Flag)
FEATURE_AR_ENABLE：默认 OFF。上线一周稳定后，仅对白名单用户（测试机型）开放 ON。FEATURE_AI_ENABLE：默认 ON。若云AI费用超标，一键切换为纯本地关键词模式。
6.2 数据库回滚 DDL
- 原则：只做新增字段，绝不删除字段/重命名字段。
- 回滚方案：代码回滚至旧版本，新字段留空不影响旧逻辑。
附、架构决策记录 (ADR)
ADR-01-2026-04-22: 关于AR导航技术选型的决策
- 背景：客户提出AR分色导览，但项目周期紧、全机型覆盖难度大、场馆GPS信号差。
- 结论：一期采用“伪AR + 高精度2D矢量图”策略。
- 伪AR：仅调用摄像头显示实景，叠加固定的箭头UI贴纸，不做空间计算(SLAM)。
- 2D矢量图：基于座位号计算逻辑路径，在SVG地图上高亮路线。
- 后果：
- 正面：开发工作量减少80%，规避了80%的Android机型兼容性崩溃风险，稳定性高。
- 负面：缺乏真实的AR沉浸感，可能无法满足客户对“噱头”的最高期待。
- 替代方案：集成商汤/视+ AR SDK（被否决，成本高，开发周期长，且仍需扫描建模）。
功能拆分与工期评估表
| 优先级 | 一级功能模块 | 二级功能 | 三级功能/详细说明 | 预估工期 (人日) | 备注与关键依赖 |
|---|---|---|---|---|---|
| P0 | 基础架构与框架 | 小程序初始化 | 公众号绑定与跳转逻辑 | 2 | 需提前完成公众号关联配置 |
| 微信云托管环境搭建与域名备案 | 3 | 依赖基础设施资源到位速度 | |||
| 全局用户授权与手机号绑定 | 2 | ||||
| 车位一览系统 | 数据接入层 | 三方停车场API对接与适配 (ParkingAdapter) | 3 | 高风险：需协调三方提供文档与Key | |
| 停车场数据定时抓取CronJob与降级库构建 | 2 | 兜底方案：API失效时读取降级库 | |||
| 业务逻辑层 | 实时余位计算与缓存策略 (Redis布隆过滤器) | 3 | 防止缓存穿透/击穿 | ||
| 空位充足度推荐算法 (红/黄/绿饱和度) | 1 | ||||
| 前端展示层 | 地图组件集成与停车场标记点渲染 | 3 | |||
| 车位详情页与一键导航 (跳转地图App) | 2 | ||||
| 票务信息查询 | 数据接入层 | 三方票务系统对接 (TicketTranslator) | 4 | 高风险：需主办方开通API权限 | |
| 票务数据Mock机制 (应对开发期接口未就绪) | 1 | 并行开发保障 | |||
| 业务逻辑层 | 票夹信息聚合与座位号格式化展示 | 2 | |||
| 水平越权校验逻辑 (基于JWT Token) | 1 | 安全红线 | |||
| 前端展示层 | 电子票根样式开发 (座位号/区域/时间) | 2 | |||
| 票务核验状态展示 (仅查询，不生成码) | 1 | ||||
| P0小计 | 32 人日 | 约 1.5 个月 (按1人全栈/2人并行估算) | |||
| P1 | 观赛规则问答 | 知识库构建 | 50-100条FAQ结构化整理与导入 | 2 | 内容由客户提供 |
| 检索逻辑 | 本地关键词匹配引擎 (Elasticsearch/本地缓存) | 3 | 优先本地匹配，节约AI成本 | ||
| 云端AI大模型API兜底调用 | 1 | 仅本地无结果时调用 | |||
| 前端交互 | 智能问答悬浮窗与对话界面 | 2 | |||
| 基础分区导览 | 2D场馆地图 | 场馆2D矢量图绘制 (基于座位分区图) | 5 | 核心工作：需要高清底图与坐标标定 | |
| 逻辑引擎 | 座位号解析与区域坐标映射算法 | 3 | 输入"A区15排"映射至SVG路径 | ||
| 前端展示 | SVG交互式地图渲染与高亮路线 | 3 | |||
| 兜底方案 | 静态文字路径指引与"拍照识图"后台人工接口 | 2 | 解决GPS信号弱问题 | ||
| 后台管理系统 | 运营配置 | 停车场手动录入/修改余量界面 | 2 | 应对API数据不准 | |
| 知识库问答内容CMS管理 | 2 | ||||
| P1小计 | 25 人日 | 约 1.2 个月 (可与P0并行开发) | |||
| P2 | AR实景导览 | 伪AR相机层 | 调用手机摄像头与背景流获取 | 2 | 按伪AR设计 (无SLAM) |
| 叠加渲染层 | 2D指北针/箭头贴纸在屏幕固定位置绘制 | 2 | 不做空间计算，避免全机型适配坑 | ||
| 机型兼容降级 | 低端机/安卓适配检查与自动降级至2D地图 | 3 | 核心是降级策略实现 | ||
| 分色分区适配 | 根据座位区域渲染不同颜色边框滤镜 (伪色) | 1 | |||
| P2小计 | 8 人日 | 约 0.4 个月 (仅开发伪AR噱头版) | |||
| 测试与发布 | 质量保障 | 全链路联调 | P0/P1接口联调与异常场景覆盖 | 5 | 必须Mock三方API异常 |
| 性能与兼容性 | 小程序真机调试 (iOS/Android主流机型) | 3 | |||
| 上线发布 | 灰度发布配置 (Feature Flag)、生产环境验证 | 2 | |||
| 测试小计 | 10 人日 | 约 0.5 个月 |
汇总工期与交付建议
| 阶段 | 内容范围 | 预估周期 (并行2人团队) | 里程碑交付物 |
|---|---|---|---|
| 一期交付 | P0 车位 + 票务 | 3.5 - 4 周 | 核心功能可用版本 (解决停车与验票痛点) |
| 二期交付 | P1 问答 + 2D导览 + 后台 | 累计 6 - 7 周 | 完整运营版本 (包含后台内容维护能力) |
| 三期交付 | P2 伪AR导览 | 累计 8 - 9 周 | 全功能版本 (满足噱头需求且稳定降级) |
风险缓冲说明：
- 上述工期未包含三方API资质审批等待期。若主办方提供大麦/猫眼API文档和Key延迟，P0票务功能将存在延期风险，建议合同中明确约定接口交付时间节点。
- 若客户坚持要求真实SLAM空间计算AR（非伪AR），P2部分工期需追加至30人日以上，且需额外预留硬件扫描建模时间。