--- description: "WeChat Mini Program integration with Zion.app backend. Use when: (1) Developing WeChat Mini Programs, (2) Using CommonJS module system (require\/module.exports), (3) Making GraphQL requests via wx.request, (4) Handling Mini Program file structure (.wxml, .wxss, .wxs, .js), (5) Integrating authentication, (6) Uploading files to Zion storage" alwaysApply: false applyToFiles: - "**\/miniprogram\/**" - "**\/*.wxml" - "**\/*.wxss" - "**\/*.wxs" - "**\/project.config.json" - "**\/app.json" --- # 微信小程序 + Zion.app 开发规则 ## Overview 本文档规定了微信小程序与 Zion.app 后端集成时的开发规则和最佳实践。所有开发必须严格遵循本文档中的规则。 **相关文档**： - [Zion.app 后端架构](.\/zion-backend-architecture.mdc) - [Zion.app 二进制资源上传](.\/zion-binary-asset-upload-rules.mdc) - [Zion.app 数据库操作](.\/zion-database-gql-api-rules.mdc) --- ## 模块系统 ### 使用 CommonJS [MUST] **必须使用 CommonJS 模块系统**： ```javascript \/\/ ✅ 正确 const { functionName } = require('.\/utils\/file.js') module.exports = { functionName } \/\/ ❌ 错误 import { functionName } from '.\/utils\/file.js' ``` --- ## 网络请求 ### 使用 wx.request [MUST] **必须使用 `wx.request` 进行网络请求**： ```javascript function graphqlRequest(query, variables = {}, token = null) { return new Promise((resolve, reject) => { wx.request({ url: 'https:\/\/zion-app.functorz.com\/zero\/{projectExId}\/api\/graphql-v2', method: 'POST', data: { query, variables }, header: { 'Content-Type': 'application\/json', ...(token ? { 'Authorization': `Bearer ${token}` } : {}) }, success: (res) => { if (res.data.errors) { reject(new Error(res.data.errors[0].message)) } else { resolve(res.data.data) } }, fail: reject }) }) } ``` --- ## 用户认证 ### 静默登录实现 [MUST] **实现微信小程序静默登录的步骤**： ```javascript \/\/ 1. 获取微信登录 code const loginRes = await new Promise((resolve, reject) => { wx.login({ success: resolve, fail: reject }) }) \/\/ 2. 调用 Zion GraphQL mutation 进行静默登录 const query = ` mutation LoginWithWechatMiniApp($code: String!) { loginWithWechatMiniApp(code: $code) { account { id username profileImageUrl \/\/ 必须包含 } jwt { token } } } ` const result = await graphqlRequest(query, { code: loginRes.code }) const { account, jwt } = result.loginWithWechatMiniApp \/\/ 3. 保存 token 和账户信息 wx.setStorageSync('token', jwt.token) wx.setStorageSync('account', account) ``` **开发要求**： - **必须请求 `profileImageUrl` 字段**：用于后续头像显示 - `wx.login` 返回的 `code` 只能使用一次，5 分钟内有效 --- ## 文件上传到 OSS ### 上传流程 [MUST] 上传文件到 Zion.app 的 OSS 存储必须遵循以下流程。详细协议请参考 [Zion.app 二进制资源上传规则](.\/zion-binary-asset-upload-rules.mdc)。 #### Step 1: 计算文件的 MD5 Base64 **必须使用 `wx.getFileInfo` API 计算 MD5**： ```javascript const fileInfo = await new Promise((resolve, reject) => { wx.getFileInfo({ filePath: filePath, digestAlgorithm: 'md5', success: resolve, fail: reject }) }) \/\/ fileInfo.digest 是十六进制字符串，需要转换为 Base64 \/\/ 转换逻辑：将十六进制字符串转换为字节数组，再转换为 Base64 ``` #### Step 2: 获取 Presigned Upload URL ```javascript const query = `mutation GetImagePresignedUrl($md5: String!, $suffix: MediaFormat!) { imagePresignedUrl(imgMd5Base64: $md5, imageSuffix: $suffix, acl: PRIVATE) { imageId uploadUrl uploadHeaders } }` const result = await graphqlRequest(query, { md5: md5Base64, suffix: 'JPEG' }, token) const { imageId, uploadUrl, uploadHeaders } = result.imagePresignedUrl ``` #### Step 3: 上传文件 **必须遵循以下规则**： 1. **必须保留所有 uploadHeaders**：presigned URL 的签名是基于这些 headers 计算的，移除任何 header 都会导致 403 错误 2. **必须确保上传的数据和计算 MD5 时使用的数据完全一致** 3. **必须使用真正的 ArrayBuffer**：不能依赖 `instanceof ArrayBuffer` 检查 ```javascript \/\/ 读取文件数据并转换为 ArrayBuffer const fileManager = wx.getFileSystemManager() let fileData = fileManager.readFileSync(filePath) let originalFileData = fileData instanceof ArrayBuffer ? fileData : (() => { const uint8Array = new Uint8Array(fileData) const buffer = new ArrayBuffer(uint8Array.length) new Uint8Array(buffer).set(uint8Array) return buffer })() \/\/ 上传文件（必须保留所有 uploadHeaders） await new Promise((resolve, reject) => { wx.request({ url: uploadUrl, method: 'PUT', data: originalFileData, header: { 'Content-Type': 'image\/jpeg', ...uploadHeaders }, responseType: 'text', success: (res) => { if (res.statusCode === 200 || res.statusCode === 204) { resolve(imageId) } else { reject(new Error(`上传失败: ${res.statusCode}`)) } }, fail: reject }) }) ``` ### 常见错误处理 - **`InvalidDigest`**：必须使用 `wx.getFileInfo` API 计算 MD5，确保上传数据与计算 MD5 时使用的数据完全一致 - **`SignatureDoesNotMatch`**：必须保留所有 uploadHeaders，不要移除任何 header（特别是 Content-MD5） - **`文件数据格式不正确`**：使用属性检查而不是 `instanceof`，强制转换为真正的 ArrayBuffer ### 文件下载（处理网络 URL）[MUST] **处理网络资源时必须先下载到本地**： ```javascript if (avatarUrl.startsWith('http:\/\/') || avatarUrl.startsWith('https:\/\/')) { const downloadRes = await new Promise((resolve, reject) => { wx.downloadFile({ url: avatarUrl, success: (res) => { if (res.statusCode === 200 && res.tempFilePath) { resolve(res) } else { reject(new Error('下载失败')) } }, fail: reject }) }) localFilePath = downloadRes.tempFilePath } ``` --- ## 用户信息编辑 ### 头像选择实现 [MUST] **使用微信小程序原生组件实现头像选择**： ```xml

wechat-miniprogram