项目接口对接说明

最后核对：2026-07-31。本文件后半部分保留了早期接口预留记录；如与本节“实际实现状态”冲突，以本节和 config/api.uts、services/ 中的实现为准。

实际实现状态

• 开发环境当前使用 http://192.168.110.13:8080；仅用于开发者工具或同网段调试。预发布和生产必须配置 HTTPS 微信合法请求域名，不得将局域网地址用于发布版本。
• 已接入并由统一请求层调用：微信手机号登录、会话刷新与登出、协议、首页/资讯/政策、权益专题与商户、商户和商品详情、订单创建与优惠试算、待支付查询与微信支付拉起、支付结果轮询、待使用动态核销码、退款申请、已完成/已取消/使用记录、人才卡资料与动态码、家属卡、人才卡升级、配偶就业、加油手机号登记、停车车牌登记、子女信息、体检套餐与学校介绍详情。
• 支付与退款的最终状态只由服务端和汇付异步通知确认；前端不能把拉起支付或提交退款视作成功结果。
• 目前仍未实现或未完成正式联调的能力必须保留为待办：酒店预约、体检预约、电影兑换券及券码、洗车外部服务审核、服务浏览记录、家属附属卡运营审核、微信客服，以及相关管理后台配置。这些均为二期范围，本轮不实现。
• 文档中任何“待确认”“未对接”条目，都应先对照实际端点和服务层判断，不能据此重复搭建模拟接口。

历史接入说明

• 已建立 config/api.uts、services/http.uts、services/session.uts、services/auth.uts 与 services/business.uts。页面不得自行调用 uni.request 或写死后台域名。
• 测试、生产 Base URL 仍刻意留空；当前开发环境临时配置为本机局域网地址 http://192.168.110.13:8080，仅用于微信开发者工具同网段调试。发版前必须替换为 HTTPS 合法请求域名。已登记不需要身份信息的首批用户端路径：GET /api/app/home、GET /api/app/news、GET /api/app/news/{id}。
• 已接入统一层的登录、支付、体检预约、酒店预约、家属卡申请/解绑、配偶就业、车牌、加油手机号登记、子女信息和人才卡升级，均须在后台返回成功后再跳转结果页。
• 已实现资讯运营闭环的首批接口：管理端使用 GET/POST /api/admin/business/news、GET/PUT /api/admin/business/news/{id} 和 PATCH /api/admin/business/news/{id}/status 管理草稿、发布、下架、置顶与排序；小程序仅读取已发布资讯。
• 电影券、动态码、订单详情和富文本详情尚缺真实业务响应字段；上传表单已要求 fileId 回填，但仍待后台确认上传响应，以上均不能宣称已完成正式联调。
• 在接口资料未确认前，禁止猜测真实 URL、字段名、令牌格式或业务状态码。

已落地的接入边界

sanitizeRichText 仅作为前端防御性兜底，服务端白名单清洗仍是唯一可信边界。富文本接口未确认前，页面不得将其当作生产动态内容。

待后端提供的资料

建议的接口封装边界

后端资料到位后，创建以下目录与职责（文件名可按项目约定微调）：

services/
├─ http.uts                 # 请求基础封装：baseURL、请求头、超时、统一错误转换
├─ auth.uts                 # 登录、令牌读取/刷新/清理
├─ home.uts                 # 首页资讯、城市介绍等接口
├─ benefit.uts              # 权益分类、权益详情、商户列表
├─ talent-card.uts          # 人才卡信息、二维码/核验信息
├─ order.uts                # 用卡记录、订单详情
├─ policy.uts               # 政策列表、政策详情
└─ profile.uts              # 用户资料、认证状态、设置

原则：页面不直接散落调用 uni.request；页面只调用对应业务服务，所有公共错误和鉴权处理集中在 http.uts / auth.uts。

商户详情路由过渡约定

• 静态演示阶段，通用商户详情入口携带 merchantType、name、image、address、discount 作为页面首屏展示快照，避免不同商户错误显示默认资料。
• merchantType 当前兼容 food、hotel、scenic、apartment 及其他通用服务类型；医疗和交通服务继续兼容现有专用 type 参数。
• 后台接入后，路由必须以稳定的 merchantId/benefitId 为主，展示快照只能用于减少首屏空白，详情接口返回后必须覆盖快照；不得依赖名称识别商户类型或业务状态。
• 图片、地址、优惠、团购开关、免费券状态、经纬度和使用说明均以后端详情接口为准，路由参数不可作为支付、核销或资格判断依据。

商品与支付业务 ID 链路

• 固定链路为 merchantId → productId → orderId：商户套餐进入商品详情必须携带 merchantId、productId；创建订单或进入订单确认后必须生成/返回 orderId。
• 商品名称、图片、价格等路由快照只用于静态演示或接口返回前占位，详情、库存、优惠资格和最终金额必须按业务 ID 从后台获取。
• 进入优惠券选择页必须携带当前 merchantId、productId、orderId，选择后使用 orderId + couponId + priceVersion 重新试算，不得创建新的订单上下文。
• 支付成功页以 orderId 查询并展示结果；旧 orderNo 仅保留短期兼容，新增代码和接口文档统一使用 orderId。
• 待支付详情必须返回绝对失效时间 expireAt（毫秒时间戳或后端约定的可解析时间），客户端每次显示页面时据此重新计算剩余时间，禁止只返回固定倒计时秒数。
• 支付、酒店预约和体检预约仅在后台明确返回成功后使用 redirectTo 进入结果页；结果页返回使用记录，不保留可重复提交的原表单页面。
• 酒店和体检可预约日期范围必须由后台返回，客户端最小日期至少为当天，并在提交接口再次进行服务端校验。

建议的通用协议（待后台确认）

请求

Content-Type: application/json
Authorization: Bearer <accessToken>     # 具体格式以后端为准
X-Request-Id: <客户端生成的追踪 ID>       # 如后端支持则启用

响应适配目标

{
  "code": 0,
  "message": "success",
  "data": {},
  "traceId": ""
}

接入时须在 http.uts 中适配后端真实结构，业务页面不得依赖未确认的 code/message/data 命名。

预留业务接口清单

统一异常处理要求

接口接入完成标准

1. 服务层包含参数、返回值和异常的明确类型。
2. 开发/测试/生产地址从配置读取，不硬编码在页面。
3. 接口响应经统一转换后才交给页面使用。
4. 页面具备加载、空、失败、重试和登录失效状态。
5. 接口变更同步更新本文档，以及对应页面的操作说明。