96 lines
8.5 KiB
Markdown
96 lines
8.5 KiB
Markdown
# 微信小程序本地开发协议
|
|
|
|
> 适用范围：`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. 本机联调与验收
|
|
|
|
1. 启动后端：在 `wxmp_backend` 执行 `docker compose up -d --build`，确认 `http://127.0.0.1:3090/health` 返回 `code: 0`。
|
|
2. 编译前端：在 `wechat_wc` 执行 `npm run build:weapp`。
|
|
3. 微信开发者工具打开 `wechat_wc/dist`，本机调试使用对应的 API 基址；真机调试使用已备案、已配置合法域名的 HTTPS 基址。
|
|
4. 每个涉及导航或状态的改动至少验证：首次进入、返回页面、切换 tab、真机预览四项。
|
|
5. 验收通过后只提交源码与必要配置/文档；不得把偶然生成的 source map、个人配置或密钥提交到仓库。
|
|
|
|
## 7. 修改前检查清单
|
|
|
|
- 该需求属于页面、路由、数据还是视觉？只改对应层。
|
|
- 是否已有公共 API adapter、store 或组件可复用？有则复用，不复制一套逻辑。
|
|
- 是否会影响 tab 页、页面栈或真机数据？会则补充 `useDidShow`/真机验证。
|
|
- 是否能用一次状态更新和一次路由调用完成？能则不要叠加事件、计时器或重复 API。
|
|
- 是否通过 `npm run build:weapp`？未通过不得交付。
|
|
|
|
## 8. 官方资料总索引与使用规则
|
|
|
|
以下八个官方入口已于 2026-09-16 连通性核对成功。它们是开发依据，不复制官网全文到仓库；每次新增微信能力、组件或部署方式时，必须先查对应入口及其下级规范。
|
|
|
|
| 官方资料 | 本项目何时必须查阅 | 当前约束 |
|
|
| --- | --- | --- |
|
|
| [小程序框架参考文档](https://developers.weixin.qq.com/miniprogram/dev/reference/index) | 改页面生命周期、路由、组件模型、渲染或分包 | 本项目使用 Taro 生成小程序代码，但必须遵守微信页面栈、tab 页和生命周期规则。 |
|
|
| [小程序组件参考文档](https://developers.weixin.qq.com/miniprogram/dev/component/) | 新增或修改 `View`、`ScrollView`、`Input`、`Picker`、`Button`、`Image` 等界面组件 | 先确认属性、事件和基础库兼容性；不以 Web DOM 行为作假设。 |
|
|
| [小程序 API 参考文档](https://developers.weixin.qq.com/miniprogram/dev/api/) | 调用登录、网络、存储、媒体选择、支付、地址、文件或系统接口 | 所有 `Taro.*` 调用须对应微信 API 能力，并处理 success/fail 和真机差异。 |
|
|
| [小程序服务端 API 参考文档](https://developers.weixin.qq.com/miniprogram/dev/server/API/) | 接入真实微信登录、支付、消息、内容安全或服务端凭证 | AppSecret、access_token、支付证书只留在后端环境变量；前端不可保存或转发。 |
|
|
| [微信开发者工具参考文档](https://developers.weixin.qq.com/miniprogram/dev/devtools/devtools) | 编译、预览、真机调试、上传、Source Map、性能诊断 | `dist` 为唯一导入目录；提交前至少完成开发者工具编译和真机预览。 |
|
|
| [微信云托管参考文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloudservice/wxcloudrun/src/basic/intro) | 评估将 Nest/Docker 后端迁移至微信云托管 | 当前后端仍以 Docker Compose 部署；迁移前必须重新确认镜像、域名、环境变量和网络方案。 |
|
|
| [微信云开发参考文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloudservice/wxcloud/basis/getting-started) | 评估云函数、云数据库、云存储或云调用 | 当前项目不混用云开发数据源；若启用，先写迁移方案和接口契约，避免与 PostgreSQL 双写。 |
|
|
| [小程序 AI 能力参考文档](https://developers.weixin.qq.com/miniprogram/dev/ai/guide) | 新增微信原生 AI 能力，或替换现有词云生成链路 | 现有词云走自建后端契约；切换前必须评估权限、资费、数据安全和失败降级。 |
|
|
|
|
### 资料使用的最小闭环
|
|
|
|
1. 先在表中确定本次改动对应的官方资料。
|
|
2. 只查与当前能力直接相关的下级页面、接口参数和基础库限制，避免整份文档复制或无目的阅读。
|
|
3. 将结论落到一个公共 adapter、组件或配置文件；不要让每个页面自行实现同一套兼容逻辑。
|
|
4. 在开发者工具和真机上验证后，才将“已支持”写入项目文档。
|
|
|
|
### 当前已直接采用的官方规则
|
|
|
|
- 页面栈与 `switchTab`/`navigateTo` 的目标限制。
|
|
- `onShow`/`useDidShow` 用于从子页返回后的数据刷新。
|
|
- 自定义 tabBar 必须完整声明 tab 页，并由组件维护选中态。
|
|
- 真机调试与合法域名、服务端密钥隔离原则。
|