仓库指南

项目结构与模块组织

源码位于 src/。路由页面放在 src/pages/<page>/，每个页面通常包含 index.vue、index.less 和 index.config.js。通用组件放在 src/components/，复用逻辑放在 src/composables/ 与 src/hooks/，接口封装放在 src/api/，公共工具放在 src/utils/，全局状态放在 src/stores/。构建配置集中在 config/，应用入口为 src/app.js 和 src/app.config.js。

构建、调试与开发命令

使用 pnpm install 安装依赖。开发微信小程序时运行 pnpm dev:weapp，调试 H5 时运行 pnpm dev:h5。生产构建常用 pnpm build:weapp，如有多端需求，也可使用 pnpm build:h5、pnpm build:alipay 等命令。提交前必须执行 pnpm lint，当前仓库已配置的自动检查主要就是 ESLint。

代码风格与命名约定

项目基于 JavaScript、Vue 3 单文件组件、Less 和 Taro 4。请遵循现有风格：.vue 文件统一使用 2 空格缩进，业务逻辑保持简洁，优先使用组合式写法。可复用组件使用 PascalCase 命名，例如 PosterBuilder；组合式函数和 hooks 使用 useXxx.js 命名，例如 useGo.js；接口方法统一使用 xxxAPI 后缀，例如 getUserInfoAPI。导入路径优先使用 @/utils、@/components 等别名，避免过深的相对路径。

测试要求

当前 package.json 中没有独立的单元测试框架，因此默认验证方式为 pnpm lint 加手工联调。修改页面、路由、认证或请求逻辑后，请至少在微信开发者工具中走通相关流程。若变更涉及 src/utils/authRedirect.js、src/utils/request.js 或 src/api/，需要重点检查登录态、页面回跳和接口请求是否正常。后续如新增自动化测试，建议贴近功能放置，并使用 *.spec.js 命名。

Mock 环境与接口联调约定

仓库当前支持“正式环境 / 本地 Mock 环境”两套 API 运行模式，且环境切换只允许通过配置文件统一控制，不要在页面里单独写开关。开发环境默认读取 config/dev.js 里的 env.API_RUNTIME_ENV，生产构建默认读取 config/prod.js；当 API_RUNTIME_ENV 为 mock 时，本地所有接口统一走 src/mock/，当其为 production 时，统一走真实接口。若只是临时联调某个页面，也不要在页面组件里直接写 USE_MOCK_DATA 之类的局部布尔开关，优先保持“一个地方切整个环境”的规则稳定。

Mock 目录也有明确分工：src/mock/index.js 只做统一入口和分发；src/mock/modules/*.mock.js 按业务模块注册 handler；src/mock/shared/ 放请求解析、响应包装、handler 匹配等公共能力；src/mock/stores/*.store.js 只处理需要状态变化的 mock 数据；src/mock/fixtures/*.fixture.js 只放静态样本和数据工厂。新增 mock 时，优先按“fixture -> store（如有状态）-> module handler -> modules/index.js 注册”的顺序扩展，不要再回到一个超大 mockData.js 式文件里堆条件分支。页面层不应该知道 mock 细节，只应该继续调用正常的 xxxAPI。

授权与支付链路约定

授权逻辑的核心在 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 重试或来源页回填逻辑，需至少手工验证一次“未授权进入页面 -> 自动或手动授权 -> 成功回跳原页面”的完整闭环。

支付链路给业务侧的精简描述可以理解为：map-demo 的 H5 页面先通过项目里的 pages/webview-preview/index 进入小程序 WebView，当 H5 侧需要发起支付时，再把 order_id 传给小程序里的 pages/pay-bridge/index；桥页负责检查授权状态、必要时补做静默授权，然后通过 src/composables/useWechatMiniPay.js 调用 /srv/?a=pay 向后端换取微信支付参数，最后由小程序侧执行 Taro.requestPayment 拉起正式支付。支付完成后，桥页会根据成功、取消、失败三种结果给出状态提示，并自动返回上一页，回到原来的 WebView/H5 场景。

仓库实现上，测试/桥接链路核心在 src/composables/useWechatMiniPay.js、src/api/index.js、src/pages/pay-test/index.vue、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 的桥接职责与返回参数约定稳定；涉及支付结果处理时，需区分成功、取消、失败三类状态，并至少在微信开发者工具或真机中验证一次“授权状态检查 -> 拉起支付 -> 返回结果展示/回跳”的流程。

提交与合并请求规范

当前 Git 历史以简短中文提交为主，例如 初始化觉林寺小程序项目。后续提交信息也请保持中文、简洁、祈使语气，并聚焦单一改动。提交 PR 时请附上：变更背景与解决方案、关联任务或问题、影响的页面或模块、手工验证步骤；涉及界面改动时，需补充截图或录屏。

文档与描述语言要求

本仓库默认使用中文沟通与书写。今后新增或修改的说明性文字请统一使用中文，包括但不限于文档、注释说明、提交说明、PR 描述、变更摘要和协作备注；如必须保留英文术语，请同时提供中文语义，避免只写英文描述。

安全与配置提示

不要提交真实的 AppID、令牌或生产环境域名。首次接手项目时，请优先检查 src/utils/config.js、config/dev.js、config/prod.js 与 project.config.json。授权与支付测试环境当前会复用既有后端配置，调整域名、client_id、支付接口地址或 WebView 跳转地址前，必须先确认不会影响 openid、会话续期和微信支付参数生成。除非明确要重构认证链路，否则不要随意删除或绕过 src/pages/auth/index 认证页；同理，除非明确要废弃本地 mock 联调能力，否则不要把 API_RUNTIME_ENV、src/mock/index.js 或 src/mock/modules/ 里的统一分发能力改回页面内局部开关。