hookehuyr

docs(AGENTS.md): 更新支付相关文档说明

补充以下细节:
1. 将 paySuccessRedirect.js 加入公共工具层高频文件列表
2. 完善支付确认页的支付成功跳转逻辑描述,明确跳转至接口返回的用户WebView或首页
3. 提示优先复用 paySuccessRedirect 工具,避免各页面重复编写跳转判断逻辑
......@@ -7,7 +7,7 @@
- 底部导航不是写死在页面里的,核心在 `src/components/AppTabbar.vue``src/stores/tabbar.js``src/api/tabbar.js``src/utils/tabbar.js`。应用启动时会预加载 tabbar 配置,`message``application``mine` 现在都按接口返回地址承接 WebView。
- 当前底部导航的真实结构是“后台动态菜单 + 固定 `pages/webview-preview/index` 承接页”,不是“每个 tab 都有一个固定业务页”。因此不要因为菜单地址来自后台,就把这条链路改回 `redirectTo`;非 `home` 按钮需要用 `navigateTo` 保留页面栈,这样进入 `webview-preview` 后微信原生左上角返回按钮才会出现。只有小程序冷启动直接进入某个 WebView 场景时,才会因为没有上一页而天然没有原生返回按钮。
- `src/pages/message/` 现在已经切到和导航栏“应用 / 我的”一致的 WebView 容器模式;`src/pages/message-detail/``src/api/message.js` 更适合作为旧版原生资讯列表/详情演示链路参考,不应再默认当作线上资讯主入口继续扩展。
- 支付相关目前有三类页面:`src/pages/pay-test/` 用于手工调试授权和支付参数;`src/pages/pay-confirm/` 是用户确认金额后点击支付的正式按钮页;`src/pages/pay-bridge/` 是给 H5/WebView 调起小程序支付用的桥页,负责自动授权、拉起支付、展示结果并返回上一页。
- 支付相关目前有三类页面:`src/pages/pay-test/` 用于手工调试授权和支付参数;`src/pages/pay-confirm/` 是用户确认金额后点击支付的正式按钮页,支付成功后会按 `getTabbarConfigAPI` 返回的 `data.user.link` 进入“我的”对应的 `WebView`,如果接口里连 `user` 字段都没有,则直接回首页`src/pages/pay-bridge/` 是给 H5/WebView 调起小程序支付用的桥页,负责自动授权、拉起支付、展示结果并返回上一页。
- `src/pages/webview-preview/` 是通用外链承接页,`src/pages/application/``src/pages/mine/`、首页外链入口都会复用这类能力;`src/pages/map-guide/` 是固定地图签到 H5 页;`src/pages/auth/` 是统一授权页,不能绕过。
- `src/pages/mine-backup/` 目前更适合作为旧版“我的”页视觉与交互备份参考,不应默认当作线上主链路去扩展新业务。
......@@ -20,7 +20,7 @@
- `src/hooks/`:较轻量的通用 hooks,目前主要是 `useGo.js` 这类导航辅助。
- `src/api/`:接口封装层。`fn.js` 是统一返回格式与 mock 接入的总入口,`index.js``tabbar.js``wx/pay.js` 分别承接首页、底部导航、微信支付等当前主链路接口;`message.js` 目前更偏旧版原生资讯列表/详情演示接口。
- `src/mock/`:本地 mock 体系。目录拆分规则是 `index.js` 统一入口、`modules/` 放 handler、`shared/` 放公共解析能力、`stores/` 放有状态 mock 数据、`fixtures/` 放静态样本。
- `src/utils/`:公共工具层。当前高频核心文件是 `authRedirect.js``request.js``config.js``webview.js``tabbar.js``wechatPay.js`;改动授权、环境、WebView 路由或支付时优先先看这里
- `src/utils/`:公共工具层。当前高频核心文件是 `authRedirect.js``request.js``config.js``webview.js``tabbar.js``paySuccessRedirect.js``wechatPay.js`;改动授权、环境、WebView 路由或支付时优先先看这里。若是“小程序内支付成功后该跳到哪里”这类问题,先看 `paySuccessRedirect.js`,不要在页面里各自重复写一份 `app_menu -> data.user.link -> webview-preview / 首页` 判断
- `src/stores/`:Pinia 状态目录。当前重点是 `tabbar.js`(底部导航配置)和 `router.js`(授权回跳来源页),其他 store 多为基础能力或历史保留。
- `src/assets/``src/constants/`:分别承接静态资源和常量;其中 `src/constants/` 目前较轻,新增共享枚举或键名时再往这里收。
- `config/`:构建与环境配置目录,`dev.js` / `prod.js` 控制 `API_RUNTIME_ENV`,不要把环境切换逻辑重新分散回页面层。
......@@ -46,7 +46,7 @@ Mock 目录也有明确分工:`src/mock/index.js` 只做统一入口和分发
支付链路现在至少有两种入口,不要再把它理解成只有一个测试桥页。第一种是当前线上主支付链路:业务页把 `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 -> 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` 的“展示金额 -> 用户点击 -> 调用共享支付能力”职责单一。无论改哪条链路,都需要区分成功、取消、失败三类状态,并至少在微信开发者工具或真机中验证一次“授权状态检查 -> 拉起支付 -> 返回结果展示/回跳”的流程。
仓库实现上,共享支付能力核心在 `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` 的“展示金额 -> 用户点击 -> 调用共享支付能力 -> 成功后按 `app_menu.data.user.link``webview-preview`,无 `user` 则回首页”职责单一。这个成功跳转规则当前集中在 `src/utils/paySuccessRedirect.js`,如果以后还有别的小程序内支付入口要复用同样落点,优先复用它,不要在各页面里各写一版菜单判断。无论改哪条链路,都需要区分成功、取消、失败三类状态,并至少在微信开发者工具或真机中验证一次“授权状态检查 -> 拉起支付 -> 返回结果展示/回跳”的流程。
## 提交与合并请求规范
当前 Git 历史以简短中文提交为主,例如 `初始化觉林寺小程序项目`。后续提交信息也请保持中文、简洁、祈使语气,并聚焦单一改动。提交 PR 时请附上:变更背景与解决方案、关联任务或问题、影响的页面或模块、手工验证步骤;涉及界面改动时,需补充截图或录屏。
......