bindbox-mini/.trae/documents/基于 Swagger 的 App 用户 API 汇总与 Uni-App 微信登录页面实现方案.md

API 文档汇总（App 用户相关）

• 登录与绑定：

  • POST /api/app/users/weixin/login（miniapp/src/api/apis/apiDefinitions.js:106）

    • 请求: App_weixin_login_request（code、invite_code，可选）

    • 响应: App_weixin_login_response（token、user_id、avatar、nickname、invite_code）（miniapp/src/api/apis/globals.d.ts:760）

  • POST /api/app/users/{user_id}/phone/bind（apiDefinitions.js:123）

    • 请求: App_bind_phone_request（code，来源于微信手机号授权）（globals.d.ts:376）

    • 响应: 成功布尔或标准成功结构（项目统一在 responded 钩子返回 response.data 或 response.data.data，miniapp/src/api/apis/index.js:59）

• 用户资料与地址：

  • PUT /api/app/users/{user_id} 修改头像/昵称（apiDefinitions.js:107）

    • 请求: App_modify_user_request（avatar、nickname，可选）（globals.d.ts:363）

  • GET /api/app/users/{user_id}/addresses 列表（apiDefinitions.js:108）/ POST 新增（apiDefinitions.js:109）/ DELETE 删除（apiDefinitions.js:110）/ PUT .../default 设默认（apiDefinitions.js:114）

    • 新增请求: App_add_address_request（姓名、手机号、省市区、详细地址、是否默认）（globals.d.ts:367）

    • 响应: 列表返回数组，新增/删除/设默认返回标准成功结构（项目统一 responded 处理）

• 积分与统计：

  • GET /api/app/users/{user_id}/points（apiDefinitions.js:124）/ GET .../points/balance（apiDefinitions.js:125）

    • 响应: App_points_balance_response（balance）（globals.d.ts:773）

  • GET /api/app/users/{user_id}/stats（apiDefinitions.js:126）

    • 响应: App_user_stats_response（coupon_count、item_card_count、points_balance）（globals.d.ts:776）

• 订单与卡券/道具：

  • GET /api/app/users/{user_id}/orders（apiDefinitions.js:122）→ 订单列表（类型包含 Model_order_items 等）

  • GET /api/app/users/{user_id}/coupons（apiDefinitions.js:118）/ GET .../invites（apiDefinitions.js:119）

  • GET /api/app/users/{user_id}/item_cards（apiDefinitions.js:120）/ GET .../item_cards/uses（apiDefinitions.js:121）

    • 响应: User_item_card_with_template[]（globals.d.ts:978）

现有代码要点（可复用）

• API 客户端：alova + 生成器（miniapp/src/api/apis/index.js:35、112；miniapp/alova.config.js:6），已封装 Authorization、401 刷新登录（index.js:9-33）。

• 登录页（Taro版）：miniapp/src/pages/login/index.vue，逻辑封装在 Apis.login.WechatAppLogin（index.js:122-421）。

登录页面实现（Uni-App Vue3）

• 页面结构：Logo/说明文案、按钮「微信登录」与open-type="getPhoneNumber"的手机号授权按钮，加载与错误提示。

• 流程：

  • uni.login({ provider: 'weixin' }) 获取 code → 调用 POST /api/app/users/weixin/login → 存储 token、user_id 到 uni.setStorageSync。

  • 可选：用户点击手机号授权后触发 onGetPhoneNumber，拿到 code 调用 POST /api/app/users/{user_id}/phone/bind 绑定手机号。

  • 登录完成后拉取 GET /api/app/users/{user_id}/stats 与 .../points/balance 更新首页状态。

• 网络层：

  • 方案A（推荐，复用现有）：在 Uni-App 中引入与复用 alova 生成的 Apis（保持统一的拦截器与基址、响应处理）。

  • 方案B（轻量）：使用 uni.request 封装最小调用（登录/绑定/统计），按现有 Authorization: Bearer <token> 规则注入。

• 配置与安全：

  • baseURL 指向后端地址（如 http://127.0.0.1:9991），并在微信小程序后台配置合法域名/证书；避免在日志中输出明文 token/手机号等敏感信息。

• 路由与状态：

  • 在 pages.json 新增 pages/login/index，登录成功后 uni.reLaunch 到首页；使用 pinia 存储 isLogin、userInfo、points 等（参考 miniapp/src/store/index.js）。

• 错误处理：

  • 按当前项目的分类提示（连接被拒绝、超时、域名未配置、SSL 错误、404、500、参数错误）进行用户级文案与重试入口（参考 index.js:221-253）。

验证与交付

• 验证：真机或开发者工具下，观察 code 获取、接口返回、token/user_id 存储与后续接口成功；埋点或日志控制台输出关键步骤。

• 交付：

  • 新增 pages/login/index.vue（Uni-App Vue3 Composition API 实现）。

  • 复用或新增 API 封装（A/B 二选一）。

  • 配置/路由调整与最小 pinia 状态接入。

后续执行步骤

• 接入 Swagger 源：将生成器输入指向 http://127.0.0.1:9991/swagger/v1/swagger.json（或项目后端的 Swagger JSON），生成/更新 Apis 并对齐 baseURL。

• 按上述方案完成页面与调用接入，并保持与现有 alova 响应处理一致性。