微信小程序本地开发协议

适用范围：wechat_wc 小程序前端及其本机 Docker 联调。依据：微信开放文档“小程序开发指南”、页面路由与自定义 tabBar 规范。最后核对：2026-09-16。

1. 目录与构建边界

业务源码只修改 src/、config/ 和受版本管理的配置文件；dist/ 是 Taro 编译产物，禁止手工修补。
每次修改小程序源码后执行 npm run build:weapp，微信开发者工具固定打开 wechat_wc/dist。
project.config.json、app.json 等由构建生成时，以 src/app.config.ts 与项目配置为唯一来源；新增页面、tab 页必须先更新源配置。
联调接口地址只从 .env/构建变量读取，不在页面内写死 127.0.0.1、域名或密钥。

2. 页面与路由规范

微信将页面组织为页面栈；navigateTo 只能打开非 tab 页，switchTab 只能切到 tab 页。连续发起的路由会排队，因此一次用户操作只能发起一次导航。

场景	使用方式	本项目约束
打开详情、编辑、结算等非 tab 页面	`Taro.navigateTo`	由列表项或按钮发起一次，不再在父级触摸结束时二次跳转。
返回上一页	`Taro.navigateBack`	返回页在 `useDidShow` 中刷新可能已变更的数据。
切换首页、商品、设计清单、订单、我的	`Taro.switchTab`	目标必须在 `src/app.config.ts` 的 `tabBar.list` 中。
替换当前非 tab 页面	`Taro.redirectTo`	仅在不应保留返回栈时使用。

useEffect(..., []) 只承担一次初始化；地址、订单、设计清单等从子页返回后可能变更的数据，必须在 useDidShow 刷新。
路由路径比较前统一为 /pages/... 格式，避免 pages/... 与 /pages/... 导致选中态误判。
跳转函数必须有明确的唯一职责：设置筛选条件、调用一次路由 API；不得混入重复路由、延时跳转或无关 Toast 控制。

3. 自定义 tabBar 规范

项目使用 tabBar.custom = true。微信规范要求仍完整声明 tabBar 页面；自定义组件仅负责渲染，并且每个 tab 页的 tabBar 实例彼此独立。

选中态唯一来源是当前 tab 页路径；进入、返回或外部 switchTab 后都应同步一次。
单击由子 tab 项处理；拖动仅由拖动结束逻辑处理。两者不可同时触发同一次 switchTab。
灰色选中遮罩只跟随一个 activeTab 状态；普通切换保留 CSS 的 left 过渡，拖动期间才临时关闭过渡。
自定义 tabBar 根节点维持可命中（pointer-events: auto）及正确层级；不得为了修复一个页面而随意改动全部 tabBar 的视觉样式。
对 tabBar 的任何修改，至少验证：首页 → 我的、我的快捷入口 → 设计清单/订单、拖动切换、返回 tab 页四种路径。

4. 数据、登录与接口规范

账户维度的数据（地址、设计、订单）以后端用户 ID 为准；本地 storage 只能用于离线兜底和首屏缓存。
真机联调使用 WX_MOCK_LOGIN=1 时，后端使用稳定的本地测试用户；不得用一次性的 wx.login code 作为用户标识。
地址、订单、设计列表请求成功后回写对应缓存；请求失败才回退缓存。不要并存两套相互覆盖的业务真相。
DTO/接口字段转换只放在 src/utils/api/ 的 adapter 中。页面层只消费前端类型，避免每个页面各自转换省市区、订单状态或设计状态。
对创建订单等写操作使用 requestId 幂等键；页面按钮在请求期间禁用，防止重复提交。

5. Toast、Loading 与错误处理

只关闭当前流程实际开启过的 Loading/Toast。禁止在每次点击前无条件调用 hideToast()；没有可关闭 Toast 时会产生运行时告警。
网络失败应保留可理解的用户提示，并在控制台记录原始错误；不能用空白页、静默吞错或无限 loading 替代错误状态。
真机控制台中与微信广告、日志目录等系统组件相关的文件不存在提示，需要与本项目业务报错分开判断；优先处理带有本项目页面、接口或栈信息的错误。

6. 本机联调与验收

启动后端：在 wxmp_backend 执行 docker compose up -d --build，确认 http://127.0.0.1:3090/health 返回 code: 0。
编译前端：在 wechat_wc 执行 npm run build:weapp。
微信开发者工具打开 wechat_wc/dist，本机调试使用对应的 API 基址；真机调试使用已备案、已配置合法域名的 HTTPS 基址。
每个涉及导航或状态的改动至少验证：首次进入、返回页面、切换 tab、真机预览四项。
验收通过后只提交源码与必要配置/文档；不得把偶然生成的 source map、个人配置或密钥提交到仓库。

7. 修改前检查清单

该需求属于页面、路由、数据还是视觉？只改对应层。
是否已有公共 API adapter、store 或组件可复用？有则复用，不复制一套逻辑。
是否会影响 tab 页、页面栈或真机数据？会则补充 useDidShow/真机验证。
是否能用一次状态更新和一次路由调用完成？能则不要叠加事件、计时器或重复 API。
是否通过 npm run build:weapp？未通过不得交付。

8. 官方资料总索引与使用规则

以下八个官方入口已于 2026-09-16 连通性核对成功。它们是开发依据，不复制官网全文到仓库；每次新增微信能力、组件或部署方式时，必须先查对应入口及其下级规范。

官方资料	本项目何时必须查阅	当前约束
小程序框架参考文档	改页面生命周期、路由、组件模型、渲染或分包	本项目使用 Taro 生成小程序代码，但必须遵守微信页面栈、tab 页和生命周期规则。
小程序组件参考文档	新增或修改 `View`、`ScrollView`、`Input`、`Picker`、`Button`、`Image` 等界面组件	先确认属性、事件和基础库兼容性；不以 Web DOM 行为作假设。
小程序 API 参考文档	调用登录、网络、存储、媒体选择、支付、地址、文件或系统接口	所有 `Taro.*` 调用须对应微信 API 能力，并处理 success/fail 和真机差异。
小程序服务端 API 参考文档	接入真实微信登录、支付、消息、内容安全或服务端凭证	AppSecret、access_token、支付证书只留在后端环境变量；前端不可保存或转发。
微信开发者工具参考文档	编译、预览、真机调试、上传、Source Map、性能诊断	`dist` 为唯一导入目录；提交前至少完成开发者工具编译和真机预览。
微信云托管参考文档	评估将 Nest/Docker 后端迁移至微信云托管	当前后端仍以 Docker Compose 部署；迁移前必须重新确认镜像、域名、环境变量和网络方案。
微信云开发参考文档	评估云函数、云数据库、云存储或云调用	当前项目不混用云开发数据源；若启用，先写迁移方案和接口契约，避免与 PostgreSQL 双写。
小程序 AI 能力参考文档	新增微信原生 AI 能力，或替换现有词云生成链路	现有词云走自建后端契约；切换前必须评估权限、资费、数据安全和失败降级。

资料使用的最小闭环

先在表中确定本次改动对应的官方资料。
只查与当前能力直接相关的下级页面、接口参数和基础库限制，避免整份文档复制或无目的阅读。
将结论落到一个公共 adapter、组件或配置文件；不要让每个页面自行实现同一套兼容逻辑。
在开发者工具和真机上验证后，才将“已支持”写入项目文档。

当前已直接采用的官方规则

页面栈与 switchTab/navigateTo 的目标限制。
onShow/useDidShow 用于从子页返回后的数据刷新。
自定义 tabBar 必须完整声明 tab 页，并由组件维护选中态。
真机调试与合法域名、服务端密钥隔离原则。

8.5 KiB Raw Blame History