Mini Program Guide

Mini Program Guide

微信小程序专项交付链路。3 个专属角色 + 1 个设计模式 + 1 份硬规范。

完整规范在 .claude/standards/miniapp.md；本文做使用层面解读。

---

4 个角色 + 1 模式

角色	阶段	工具
agf-uiux-designer (MiniApp Mode)	设计	spec.md + index.html，输出到 docs/design/[feature]-miniapp/
agf-miniapp-dev (#008)	开发	默认原生 WXML/WXSS/JS；Taro 仅在双端复用场景
agf-miniapp-code-reviewer (#010)	审查	代码质量 + 审核红线 + 包体积
agf-miniapp-qa-engineer (#012)	测试	DevTools 模拟器（SIT）+ 真机（E2E）+ 真实用户（UAT）

跨链路共用 agf-backend-dev / agf-ai-agent-dev / agf-ml-engineer。

触发：/agf-team-start [feature] 小程序版 或在任务描述中提到"小程序"/"miniapp"/"微信端"。

---

默认原生 vs Taro 决策

默认原生（WXML/WXSS/JS）。

仅以下 3 种场景用 Taro：

1. 该页面 80% 以上业务逻辑已存在于 Web React 组件，需要复用
2. 团队需要在 Web 与小程序之间快速同步同一功能（双端发布）
3. 选型分歧时由 agf-tech-lead 仲裁

不允许："为了用 React" / "团队习惯 React" 这类弱理由。

代码组织：

miniapp/
  native/               # 默认（原生）
    pages/[page]/[page].{wxml,wxss,js,json}
    components/[comp]/[comp].{wxml,wxss,js,json}
    utils/
  src/                  # Taro（仅触发场景）
    pages/
    components/
    services/
  config/
    project.config.json
    sitemap.json
  tests/e2e/            # miniprogram-automator 脚本

---

4 条审核红线（零容忍）

提审被驳回的高频原因。agf-miniapp-code-reviewer 把这 4 条当 Critical 必查：

红线	例子	修复
1. 隐私协议触发时机	用户进入小程序，还没同意隐私协议就调 getUserProfile	必须先弹同意框，写 storage，再调
2. 跳转非备案外链	wx.navigateTo({ url: 'https://外部站' })	只跳备案域名；外链改用 web-view 且必须备案
3. 未声明的数据收集	收集设备号 / 手机号但未在隐私协议中声明	在 app.json __usePrivacyCheck__: true + 隐私协议同步
4. 诱导分享 / 强制关注	"分享后才解锁" / "关注公众号才能继续"	全部移除

详见 miniapp.md 第 4 节。

---

性能硬墙

指标	上限	agent 责任
setData 单次 payload	256KB	dev 在每次 setData 前评估
主包体积	2MB	dev 接近时分包
总包体积	20MB	dev + reviewer 双查
长列表渲染	必须虚拟滚动	dev 不允许全量渲染

---

测试矩阵

阶段	工具	通过门槛
SIT	DevTools 模拟器	AC 通过率 100%
E2E	体验版二维码 + 真机	iOS（最新 Safari 内核）+ Android（华为/小米/OPPO 任一）各 1 台
UAT	体验版 + 真实用户	PRD AC 业务签字

E2E 真机覆盖场景：

• 网络切换（4G ↔ WiFi）
• 应用切到后台再回前台
• 低电量 / 断网 / 弱网
• iOS / Android 双端 UI 一致性

---

提审前置检查（4 项必检）

agf-miniapp-qa-engineer 在 UAT 前必检：

• 隐私协议弹窗时机正确（首次进入 + 用户主动操作前）
• 用户协议链接可达（404 / 文案对齐）
• wx.getUserProfile 仅在用户主动操作时触发
• wx.getLocation 等敏感 API 调用合规（如有）

---

自动化测试

单元测试（dev 写）

原生侧：miniprogram-simulate + Jest

Taro 侧：Jest + React Testing Library

E2E（dev 写脚本，QA 执行）

miniprogram-automator + Jest，置于 miniapp/native/tests/e2e/：

const automator = require('miniprogram-automator');

const miniProgram = await automator.launch({
  cliPath: '/Applications/wechatwebdevtools.app/Contents/MacOS/cli',
  projectPath: '/path/to/miniapp/native',
});

const page = await miniProgram.reLaunch('/pages/login/login');
const button = await page.$('.login-btn');
await button.tap();

const result = await page.waitFor('.success-toast');
expect(result).toBeTruthy();

---

Plugin / MCP 限制

不引入第三方 MCP：自动化测试基于微信官方工具。原因：审核合规要求工具链可控可解释。

---

进一步阅读

• miniapp.md — 完整专项规范
• agf-miniapp-dev.md — 开发 agent
• agf-miniapp-code-reviewer.md — 审查 agent
• agf-miniapp-qa-engineer.md — QA agent