Hooke / jls-weapp

Go to a project
Toggle navigation Toggle navigation pinning
hookehuyr
55929fb5 1 parent 5e2f0f0d

docs: 完善支付相关文档与配置，修正地图引导页链接 

- 更新README与AGENTS.md中的支付链路说明，补充公共参数f、client_id由请求层统一补齐的提示
- 修正src/api/index.js中getWechatPayParamsAPI的JSDoc注释，更新描述与参数说明
- 修正地图引导页的硬编码URL，添加tabbar预览与mock相关参数
- 明确区分主支付链路与历史支付链路，补充使用注意事项与参数混用提示
Inline Side-by-side
Showing 4 changed files with 7 additions and 7 deletions
......@@ -41,9 +41,9 @@ Mock 目录也有明确分工：`src/mock/index.js` 只做统一入口和分发
## 授权与支付链路约定
授权逻辑的核心在 `src/app.js`、`src/utils/authRedirect.js`、`src/utils/request.js` 与 `src/pages/auth/index`。应用启动时会优先尝试静默授权，`sessionid` 统一写入 Taro 本地缓存，并由请求拦截器动态注入到请求头；接口返回 `401` 时，会先尝试 `refreshSession` 静默续期并重放原请求，失败后再降级跳转授权页。因此除非明确重构整条链路，否则不要随意改动 `sessionid` 的存取方式、`saveCurrentPagePath` / `returnToOriginalPage` 的回跳机制、`navigateToAuth` 的防重逻辑，也不要跳过 `src/pages/auth/index` 直接在业务页硬编码授权流程。若修改分享进入、启动授权、401 重试或来源页回填逻辑，需至少手工验证一次“未授权进入页面 -> 自动或手动授权 -> 成功回跳原页面”的完整闭环。
支付链路现在至少有两种入口，不要再把它理解成只有一个测试桥页。第一种是小程序内直接支付：业务页把 `order_id`、金额等参数带到 `src/pages/pay-confirm/index.vue`，用户确认后通过 `src/composables/useWechatMiniPay.js` 调用 `/srv/?a=pay`，再由小程序侧执行 `Taro.requestPayment`。第二种是 H5/WebView 发起支付：外部页面先进入 `pages/webview-preview/index` 或 tabbar 对应的 WebView 容器，再把 `order_id` 传给 `pages/pay-bridge/index`；桥页负责检查授权状态、必要时补做静默授权、拉起支付、展示成功/取消/失败结果，并自动返回上一页。
支付链路现在至少有两种入口，不要再把它理解成只有一个测试桥页。第一种是当前线上主支付链路：业务页把 `order_id`、金额等参数带到 `src/pages/pay-confirm/index.vue`，用户确认后通过 `src/composables/useWechatMiniPay.js` 调用 `/srv/?a=pay`，再由请求层统一补上公共参数 `f`、`client_id`，最后由小程序侧执行 `Taro.requestPayment`。第二种是 H5/WebView 发起支付：外部页面先进入 `pages/webview-preview/index` 或 tabbar 对应的 WebView 容器，再把 `order_id` 传给 `pages/pay-bridge/index`；桥页负责检查授权状态、必要时补做静默授权、拉起支付、展示成功/取消/失败结果，并自动返回上一页。
仓库实现上，共享支付能力核心在 `src/composables/useWechatMiniPay.js` 与 `src/api/index.js`；调试入口在 `src/pages/pay-test/index.vue`，正式确认页在 `src/pages/pay-confirm/index.vue`，H5 桥接页在 `src/pages/pay-bridge/index.vue`。另一条是通用支付封装，位于 `src/utils/wechatPay.js` 与 `src/api/wx/pay.js`，通过 `pay_id` 调用 `/srv/?a=icbc_pay_wxamp`。修改支付逻辑时务必先确认当前页面接的是哪一条接口链路，不要混用 `order_id` 与 `pay_id`，也不要在未拿到后端有效支付参数时直接调用 `requestPayment`。涉及 H5/WebView 唤起支付时，应优先保持 `pages/pay-bridge` 的桥接职责与返回参数约定稳定；涉及小程序内直接支付时，应优先保持 `pages/pay-confirm` 的“展示金额 -> 用户点击 -> 调用共享支付能力”职责单一。无论改哪条链路，都需要区分成功、取消、失败三类状态，并至少在微信开发者工具或真机中验证一次“授权状态检查 -> 拉起支付 -> 返回结果展示/回跳”的流程。
仓库实现上，共享支付能力核心在 `src/composables/useWechatMiniPay.js` 与 `src/api/index.js`；调试入口在 `src/pages/pay-test/index.vue`，正式确认页在 `src/pages/pay-confirm/index.vue`，H5 桥接页在 `src/pages/pay-bridge/index.vue`。另一条是历史保留的通用支付封装，位于 `src/utils/wechatPay.js` 与 `src/api/wx/pay.js`，通过 `pay_id` 调用 `/srv/?a=icbc_pay_wxamp`。当前若处理支付问题，默认先看 `order_id -> useWechatMiniPay -> /srv/?a=pay` 这条主链路；其中 `f`、`client_id` 由请求层公共参数统一补齐，不要在单个支付接口 URL 上重复手写。若没有用户明确点名 `pay_id`、`wechatPay.js` 或 `src/api/wx/pay.js`，暂时不要把排查范围扩到这条历史链路，也不要顺手改它。修改支付逻辑时务必先确认当前页面接的是哪一条接口链路，不要混用 `order_id` 与 `pay_id`，也不要在未拿到后端有效支付参数时直接调用 `requestPayment`。涉及 H5/WebView 唤起支付时，应优先保持 `pages/pay-bridge` 的桥接职责与返回参数约定稳定；涉及小程序内直接支付时，应优先保持 `pages/pay-confirm` 的“展示金额 -> 用户点击 -> 调用共享支付能力”职责单一。无论改哪条链路，都需要区分成功、取消、失败三类状态，并至少在微信开发者工具或真机中验证一次“授权状态检查 -> 拉起支付 -> 返回结果展示/回跳”的流程。
## 提交与合并请求规范
当前 Git 历史以简短中文提交为主，例如 `初始化觉林寺小程序项目`。后续提交信息也请保持中文、简洁、祈使语气，并聚焦单一改动。提交 PR 时请附上：变更背景与解决方案、关联任务或问题、影响的页面或模块、手工验证步骤；涉及界面改动时，需补充截图或录屏。
......
......@@ -121,7 +121,7 @@ export const API_ENVIRONMENTS = {
当前已经预置了以下 mock：
- 启动授权：`/srv/?a=openid`
- 支付参数：`/srv/?a=pay`、`/srv/?a=icbc_pay_wxamp`
- 支付参数：`/srv/?a=pay`（`f`、`client_id` 由请求层统一补齐）、`/srv/?a=icbc_pay_wxamp`
- 分享配置：`/srv/?a=wx_share`
- 短信与上传：`/srv/?a=sms`、`/srv/?a=upload`
- 消息示例：`/srv/?a=message&t=list`、`/srv/?a=message&t=detail`
......
......@@ -20,9 +20,9 @@ const Api = {
export const getHomeContentAPI = () => fn(fetch.get(Api.HOME_CONTENT))
/**
* @description 获取微信支付参数（对齐 meihuaApp 的支付接口）
* @description 获取微信支付参数（order_id 主支付链路）
* @param {Object} params 请求参数
* @param {string} params.order_id 测试订单 ID
* @param {string} params.order_id 支付订单 ID
* @returns {Promise<{code:number,data:any,msg:string}>}
*/
export const getWechatPayParamsAPI = (params) => fn(fetch.post(Api.PAY_TEST, params))
......
<!--
* @Date: 2026-04-22 13:14:52
* @LastEditors: hookehuyr hookehuyr@gmail.com
* @LastEditTime: 2026-04-29 13:59:22
* @LastEditTime: 2026-05-11 11:52:01
* @FilePath: /jls_weapp/src/pages/map-guide/index.vue
* @Description: 文件描述
-->
......@@ -10,5 +10,5 @@
</template>
<script setup>
const map_guide_url = 'https://oa-dev.onwall.cn/f/map/#/checkin/?id=835368&current_lng=121.52609&current_lat=31.25956&openid=oAHBN14FGjUihI-ayF22_rCe0APM&activityId=8353701&_t=00&navMode=jls&activeTab=home'
const map_guide_url = 'https://oa-dev.onwall.cn/f/map/#/checkin/?id=835368&current_lng=121.52609&current_lat=31.25956&openid=oAHBN14FGjUihI-ayF22_rCe0APM&activityId=8353701&_t=00&navMode=jls&activeTab=&jlsTabbarPreview=1&jlsTabbarMock=1'
</script>
......