1798 lines
66 KiB
Markdown
1798 lines
66 KiB
Markdown
# 小程序管理技能 v3.0
|
||
|
||
> 📅 创建日期：2026-01-25
|
||
> 📅 更新日期：2026-01-25（v3.0 全能版）
|
||
> 📋 通过微信开放平台API完整管理小程序的全生命周期：申请、认证、开发、审核、发布、运营
|
||
> 🚀 支持多小程序管理、一键部署、自动认证检查、汇总报告
|
||
|
||
---
|
||
|
||
## 🎯 能力全景图
|
||
|
||
```
|
||
╔══════════════════════════════════════════════════════════════════════════════╗
|
||
║ 小程序管理技能 v3.0 能力全景图 ║
|
||
╠══════════════════════════════════════════════════════════════════════════════╣
|
||
║ ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 🔧 工具整合层 │ ║
|
||
║ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ ║
|
||
║ │ │ 微信开发者 │ │ miniprogram │ │ 开放平台 │ │ GitHub │ │ ║
|
||
║ │ │ 工具 CLI │ │ -ci (npm) │ │ API │ │ Actions │ │ ║
|
||
║ │ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 📦 核心功能层 │ ║
|
||
║ │ │ ║
|
||
║ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ ║
|
||
║ │ │ 多小程序 │ │ 项目 │ │ 一键 │ │ 汇总 │ │ ║
|
||
║ │ │ 管理 │ │ 检查 │ │ 部署 │ │ 报告 │ │ ║
|
||
║ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ 🚀 部署流程 │ ║
|
||
║ │ │ ║
|
||
║ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ ║
|
||
║ │ │ 检查 │ → │ 编译 │ → │ 上传 │ → │ 提审 │ → │ 审核 │ → │ 发布 │ │ ║
|
||
║ │ │check │ │build │ │upload│ │audit │ │wait │ │release│ │ ║
|
||
║ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ ║
|
||
║ │ │ │ │ │ │ │ │ ║
|
||
║ │ ▼ ▼ ▼ ▼ ▼ ▼ │ ║
|
||
║ │ 自动化 自动化 自动化 自动化 等待 手动/自动 │ ║
|
||
║ │ 1-7天 │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
╚══════════════════════════════════════════════════════════════════════════════╝
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 命令速查表
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `mp_full.py report` | 生成所有小程序汇总报告 | `python3 mp_full.py report` |
|
||
| `mp_full.py check` | 检查项目问题 | `python3 mp_full.py check soul-party` |
|
||
| `mp_full.py auto` | 全自动部署（上传+提审） | `python3 mp_full.py auto soul-party` |
|
||
| `mp_deploy.py list` | 列出所有小程序 | `python3 mp_deploy.py list` |
|
||
| `mp_deploy.py add` | 添加新小程序 | `python3 mp_deploy.py add` |
|
||
| `mp_deploy.py cert-status` | 查询认证状态 | `python3 mp_deploy.py cert-status soul-party` |
|
||
| `mp_deploy.py cert-done` | 标记认证完成 | `python3 mp_deploy.py cert-done soul-party` |
|
||
| `mp_deploy.py release` | 发布上线 | `python3 mp_deploy.py release soul-party` |
|
||
|
||
---
|
||
|
||
## 🎯 技能概述
|
||
|
||
本技能用于通过API实现微信小程序的完整管理，包括：
|
||
|
||
### 核心能力
|
||
|
||
| 阶段 | 能力 | 说明 |
|
||
|------|------|------|
|
||
| **申请** | 快速注册小程序 | 复用公众号主体资质，无需300元认证费 |
|
||
| **认证** | 企业认证管理 | 自动检查认证状态、提醒过期、材料管理 |
|
||
| **配置** | 基础信息设置 | 名称、头像、介绍、类目管理 |
|
||
| **开发** | 代码管理 | 上传代码、生成体验版 |
|
||
| **审核** | 提审发布 | 提交审核、查询状态、撤回、发布 |
|
||
| **运营** | 接口管理 | 域名配置、隐私协议、接口权限 |
|
||
| **推广** | 小程序码 | 生成无限量小程序码 |
|
||
| **数据** | 数据分析 | 访问数据、用户画像 |
|
||
|
||
### v2.0 新增能力
|
||
|
||
| 能力 | 命令 | 说明 |
|
||
|------|------|------|
|
||
| **多小程序管理** | `mp_deploy.py list` | 统一管理多个小程序 |
|
||
| **一键部署** | `mp_deploy.py deploy <id>` | 编译→上传→提审一步完成 |
|
||
| **认证管理** | `mp_deploy.py cert <id>` | 认证状态检查、材料管理 |
|
||
| **快速上传** | `mp_deploy.py upload <id>` | 快速上传代码到开发版 |
|
||
|
||
### 开源工具集成
|
||
|
||
| 工具 | 用途 | 安装方式 |
|
||
|------|------|----------|
|
||
| **miniprogram-ci** | 微信官方CI工具 | `npm install miniprogram-ci -g` |
|
||
| **微信开发者工具CLI** | 本地编译上传 | 安装开发者工具自带 |
|
||
| **multi-mini-ci** | 多平台小程序上传 | GitHub开源 |
|
||
|
||
---
|
||
|
||
## 🚀 触发词
|
||
|
||
- 管理小程序
|
||
- 小程序申请
|
||
- 小程序审核
|
||
- 小程序发布
|
||
- 上传小程序代码
|
||
- 配置小程序域名
|
||
- 生成小程序码
|
||
- 查看小程序状态
|
||
|
||
---
|
||
|
||
## 🏗️ 技术架构
|
||
|
||
### 管理方式对比
|
||
|
||
| 方式 | 优点 | 缺点 | 适用场景 |
|
||
|------|------|------|----------|
|
||
| **微信后台手动操作** | 无需开发 | 效率低，无法批量 | 单个小程序 |
|
||
| **微信开发者工具CLI** | 简单易用 | 功能有限 | 开发测试 |
|
||
| **开放平台API（本方案）** | 功能完整、可自动化 | 需要开发 | 批量管理、自动化 |
|
||
|
||
### 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 小程序管理引擎 v1.0 │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 第一层：认证层 │ │
|
||
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
|
||
│ │ │ 第三方平台 │ │ component_ │ │ authorizer_ │ │ │
|
||
│ │ │ 认证信息 │ → │ access_token │ → │ access_token │ │ │
|
||
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 第二层：管理API层 │ │
|
||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||
│ │ │ 注册 │ │ 配置 │ │ 代码 │ │ 审核 │ │ 运营 │ │ │
|
||
│ │ │ 管理 │ │ 管理 │ │ 管理 │ │ 管理 │ │ 管理 │ │ │
|
||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ ↓ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 第三层：本地CLI层 │ │
|
||
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
|
||
│ │ │ mp_manager.py │ │ 微信开发者 │ │ 自动化脚本 │ │ │
|
||
│ │ │ Python CLI │ │ 工具 CLI │ │ Shell │ │ │
|
||
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 前置条件
|
||
|
||
### 1. 微信开放平台账号
|
||
|
||
- 注册地址：https://open.weixin.qq.com/
|
||
- 完成开发者资质认证（需企业资质）
|
||
|
||
### 2. 创建第三方平台
|
||
|
||
登录开放平台后台 → 管理中心 → 第三方平台 → 创建
|
||
|
||
**必填信息**：
|
||
- 平台名称
|
||
- 服务类型（选择"平台型"可管理多个小程序）
|
||
- 授权发起页域名
|
||
- 消息与事件接收URL
|
||
|
||
### 3. 获取关键凭证
|
||
|
||
| 凭证 | 说明 | 获取方式 |
|
||
|------|------|----------|
|
||
| `component_appid` | 第三方平台AppID | 开放平台后台 |
|
||
| `component_appsecret` | 第三方平台密钥 | 开放平台后台 |
|
||
| `component_verify_ticket` | 验证票据 | 微信每10分钟推送 |
|
||
| `component_access_token` | 平台调用凭证 | API获取，2小时有效 |
|
||
| `authorizer_access_token` | 授权方调用凭证 | API获取，2小时有效 |
|
||
|
||
---
|
||
|
||
## 🔑 认证流程
|
||
|
||
### 获取 component_access_token
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/api_component_token
|
||
{
|
||
"component_appid": "你的第三方平台AppID",
|
||
"component_appsecret": "你的第三方平台密钥",
|
||
"component_verify_ticket": "微信推送的验证票据"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"component_access_token": "xxxx",
|
||
"expires_in": 7200
|
||
}
|
||
```
|
||
|
||
### 获取预授权码
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/api_create_preauthcode
|
||
{
|
||
"component_appid": "你的第三方平台AppID"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"pre_auth_code": "xxxx",
|
||
"expires_in": 600
|
||
}
|
||
```
|
||
|
||
### 引导用户授权
|
||
|
||
```
|
||
https://mp.weixin.qq.com/cgi-bin/componentloginpage?
|
||
component_appid=第三方平台AppID&
|
||
pre_auth_code=预授权码&
|
||
redirect_uri=授权回调地址&
|
||
auth_type=1 # 1=仅小程序，2=仅公众号，3=两者都可
|
||
```
|
||
|
||
### 获取 authorizer_access_token
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/api_query_auth
|
||
{
|
||
"component_appid": "第三方平台AppID",
|
||
"authorization_code": "授权回调返回的code"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"authorization_info": {
|
||
"authorizer_appid": "授权方AppID",
|
||
"authorizer_access_token": "授权方调用凭证",
|
||
"expires_in": 7200,
|
||
"authorizer_refresh_token": "刷新令牌"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 核心API接口
|
||
|
||
### 一、小程序注册
|
||
|
||
#### 1.1 复用公众号资质快速注册
|
||
|
||
**前提**：已有认证的公众号
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/account/fastregister?access_token=ACCESS_TOKEN
|
||
{
|
||
"ticket": "公众号扫码授权的ticket"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"errcode": 0,
|
||
"errmsg": "ok",
|
||
"appid": "新注册的小程序AppID",
|
||
"authorization_code": "授权码"
|
||
}
|
||
```
|
||
|
||
**优势**：
|
||
- 无需重新提交主体材料
|
||
- 无需对公打款
|
||
- 无需支付300元认证费
|
||
|
||
**限制**：
|
||
- 非个体户：每月可注册5个
|
||
- 个体户：每月可注册1个
|
||
|
||
#### 1.2 快速注册企业小程序
|
||
|
||
**前提**：有企业营业执照
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/fastregisterminiprogram
|
||
{
|
||
"name": "小程序名称",
|
||
"code": "统一社会信用代码",
|
||
"code_type": 1, # 1=营业执照
|
||
"legal_persona_wechat": "法人微信号",
|
||
"legal_persona_name": "法人姓名",
|
||
"component_phone": "联系电话"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 二、基础信息配置
|
||
|
||
#### 2.1 获取基础信息
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/account/getaccountbasicinfo
|
||
# 无请求参数
|
||
|
||
# 返回
|
||
{
|
||
"appid": "小程序AppID",
|
||
"account_type": 2, # 2=小程序
|
||
"principal_type": 1, # 1=企业
|
||
"principal_name": "主体名称",
|
||
"realname_status": 1, # 1=已认证
|
||
"nickname": "小程序名称",
|
||
"head_image_url": "头像URL",
|
||
"signature": "简介"
|
||
}
|
||
```
|
||
|
||
#### 2.2 修改名称
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/setnickname?access_token=ACCESS_TOKEN
|
||
{
|
||
"nick_name": "新名称",
|
||
"id_card": "管理员身份证号",
|
||
"license": "营业执照media_id", # 需要先上传
|
||
"naming_other_stuff_1": "其他证明material_id" # 可选
|
||
}
|
||
```
|
||
|
||
#### 2.3 修改头像
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/account/modifyheadimage?access_token=ACCESS_TOKEN
|
||
{
|
||
"head_img_media_id": "头像图片media_id", # 需要先上传
|
||
"x1": 0, "y1": 0, "x2": 1, "y2": 1 # 裁剪区域
|
||
}
|
||
```
|
||
|
||
#### 2.4 修改简介
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/account/modifysignature?access_token=ACCESS_TOKEN
|
||
{
|
||
"signature": "新的简介内容" # 4-120字
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 三、类目管理
|
||
|
||
#### 3.1 获取可选类目
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/cgi-bin/wxopen/getallcategories?access_token=ACCESS_TOKEN
|
||
```
|
||
|
||
#### 3.2 获取已设置类目
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/cgi-bin/wxopen/getcategory?access_token=ACCESS_TOKEN
|
||
```
|
||
|
||
#### 3.3 添加类目
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/wxopen/addcategory?access_token=ACCESS_TOKEN
|
||
{
|
||
"categories": [
|
||
{
|
||
"first": 1, # 一级类目ID
|
||
"second": 2, # 二级类目ID
|
||
"certicates": [ # 资质证明
|
||
{"key": "资质名称", "value": "media_id"}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3.4 删除类目
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/wxopen/deletecategory?access_token=ACCESS_TOKEN
|
||
{
|
||
"first": 1,
|
||
"second": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 四、域名配置
|
||
|
||
#### 4.1 设置服务器域名
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/modify_domain?access_token=ACCESS_TOKEN
|
||
{
|
||
"action": "set", # add/delete/set/get
|
||
"requestdomain": ["https://api.example.com"],
|
||
"wsrequestdomain": ["wss://ws.example.com"],
|
||
"uploaddomain": ["https://upload.example.com"],
|
||
"downloaddomain": ["https://download.example.com"],
|
||
"udpdomain": ["udp://udp.example.com"],
|
||
"tcpdomain": ["tcp://tcp.example.com"]
|
||
}
|
||
```
|
||
|
||
#### 4.2 设置业务域名
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/setwebviewdomain?access_token=ACCESS_TOKEN
|
||
{
|
||
"action": "set", # add/delete/set/get
|
||
"webviewdomain": ["https://web.example.com"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 五、隐私协议配置
|
||
|
||
#### 5.1 获取隐私协议设置
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/getprivacysetting?access_token=ACCESS_TOKEN
|
||
{
|
||
"privacy_ver": 2 # 1=当前版本，2=开发版本
|
||
}
|
||
```
|
||
|
||
#### 5.2 设置隐私协议
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/component/setprivacysetting?access_token=ACCESS_TOKEN
|
||
{
|
||
"privacy_ver": 2,
|
||
"setting_list": [
|
||
{
|
||
"privacy_key": "UserInfo",
|
||
"privacy_text": "用于展示用户头像和昵称"
|
||
},
|
||
{
|
||
"privacy_key": "Location",
|
||
"privacy_text": "用于获取您的位置信息以推荐附近服务"
|
||
},
|
||
{
|
||
"privacy_key": "PhoneNumber",
|
||
"privacy_text": "用于登录验证和订单通知"
|
||
}
|
||
],
|
||
"owner_setting": {
|
||
"contact_email": "contact@example.com",
|
||
"contact_phone": "15880802661",
|
||
"notice_method": "弹窗提示"
|
||
}
|
||
}
|
||
```
|
||
|
||
**常用隐私字段**：
|
||
|
||
| privacy_key | 说明 |
|
||
|-------------|------|
|
||
| `UserInfo` | 用户信息（头像、昵称） |
|
||
| `Location` | 地理位置 |
|
||
| `PhoneNumber` | 手机号 |
|
||
| `Album` | 相册 |
|
||
| `Camera` | 相机 |
|
||
| `Record` | 麦克风 |
|
||
| `Clipboard` | 剪切板 |
|
||
| `MessageFile` | 微信消息中的文件 |
|
||
| `ChooseAddress` | 收货地址 |
|
||
| `BluetoothInfo` | 蓝牙 |
|
||
|
||
---
|
||
|
||
### 六、代码管理
|
||
|
||
#### 6.1 上传代码
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/commit?access_token=ACCESS_TOKEN
|
||
{
|
||
"template_id": 1, # 代码模板ID
|
||
"ext_json": "{\"extAppid\":\"授权方AppID\",\"ext\":{}}",
|
||
"user_version": "1.0.0",
|
||
"user_desc": "版本描述"
|
||
}
|
||
```
|
||
|
||
**注意**：需要先在第三方平台创建代码模板
|
||
|
||
#### 6.2 获取体验版二维码
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/get_qrcode?access_token=ACCESS_TOKEN&path=pages/index/index
|
||
# 返回二维码图片
|
||
```
|
||
|
||
#### 6.3 获取已上传的代码页面列表
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/get_page?access_token=ACCESS_TOKEN
|
||
|
||
# 返回
|
||
{
|
||
"errcode": 0,
|
||
"page_list": ["pages/index/index", "pages/my/my"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 七、审核管理
|
||
|
||
#### 7.1 提交审核
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/submit_audit?access_token=ACCESS_TOKEN
|
||
{
|
||
"item_list": [
|
||
{
|
||
"address": "pages/index/index",
|
||
"tag": "电子书 阅读 创业",
|
||
"first_class": "教育",
|
||
"second_class": "在线教育",
|
||
"first_id": 1,
|
||
"second_id": 2,
|
||
"title": "首页"
|
||
}
|
||
],
|
||
"preview_info": {
|
||
"video_id_list": [],
|
||
"pic_id_list": []
|
||
},
|
||
"version_desc": "版本说明",
|
||
"feedback_info": "反馈内容",
|
||
"feedback_stuff": "media_id" # 反馈附件
|
||
}
|
||
```
|
||
|
||
#### 7.2 查询审核状态
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/get_auditstatus?access_token=ACCESS_TOKEN
|
||
{
|
||
"auditid": 1234567890
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"errcode": 0,
|
||
"status": 0, # 0=审核成功，1=审核被拒，2=审核中，3=已撤回，4=审核延后
|
||
"reason": "拒绝原因", # status=1时返回
|
||
"screenshot": "截图"
|
||
}
|
||
```
|
||
|
||
#### 7.3 查询最新审核状态
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/get_latest_auditstatus?access_token=ACCESS_TOKEN
|
||
```
|
||
|
||
#### 7.4 撤回审核
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/undocodeaudit?access_token=ACCESS_TOKEN
|
||
```
|
||
|
||
**限制**：单个小程序每天只能撤回1次
|
||
|
||
---
|
||
|
||
### 八、发布管理
|
||
|
||
#### 8.1 发布已审核通过的版本
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/release?access_token=ACCESS_TOKEN
|
||
{} # 无请求参数
|
||
|
||
# 返回
|
||
{
|
||
"errcode": 0,
|
||
"errmsg": "ok"
|
||
}
|
||
```
|
||
|
||
#### 8.2 版本回退
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN
|
||
```
|
||
|
||
**限制**：只能回退到上一个版本，且只能回退一次
|
||
|
||
#### 8.3 获取可回退版本历史
|
||
|
||
```python
|
||
# GET https://api.weixin.qq.com/wxa/revertcoderelease?access_token=ACCESS_TOKEN&action=get_history_version
|
||
```
|
||
|
||
#### 8.4 分阶段发布
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/grayrelease?access_token=ACCESS_TOKEN
|
||
{
|
||
"gray_percentage": 10 # 灰度比例 1-100
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 九、小程序码生成
|
||
|
||
#### 9.1 获取小程序码（有限制）
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/getwxacode?access_token=ACCESS_TOKEN
|
||
{
|
||
"path": "pages/index/index?scene=123",
|
||
"width": 430,
|
||
"auto_color": false,
|
||
"line_color": {"r": 0, "g": 0, "b": 0},
|
||
"is_hyaline": false # 是否透明背景
|
||
}
|
||
# 返回图片二进制
|
||
```
|
||
|
||
**限制**：每个path只能生成10万个
|
||
|
||
#### 9.2 获取无限小程序码（推荐）
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/getwxacodeunlimit?access_token=ACCESS_TOKEN
|
||
{
|
||
"scene": "user_id=123&from=share", # 最长32字符
|
||
"page": "pages/index/index", # 必须是已发布的页面
|
||
"width": 430,
|
||
"auto_color": false,
|
||
"line_color": {"r": 0, "g": 0, "b": 0},
|
||
"is_hyaline": false
|
||
}
|
||
# 返回图片二进制
|
||
```
|
||
|
||
**注意**：scene参数需要在小程序中用`onLoad(options)`解析
|
||
|
||
#### 9.3 生成小程序短链接
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/genwxashortlink?access_token=ACCESS_TOKEN
|
||
{
|
||
"page_url": "pages/index/index?id=123",
|
||
"page_title": "页面标题",
|
||
"is_permanent": false # 是否永久有效
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"errcode": 0,
|
||
"link": "https://wxaurl.cn/xxxx"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 十、接口权限管理
|
||
|
||
#### 10.1 查询接口调用额度
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/openapi/quota/get?access_token=ACCESS_TOKEN
|
||
{
|
||
"cgi_path": "/wxa/getwxacode"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"quota": {
|
||
"daily_limit": 100000,
|
||
"used": 500,
|
||
"remain": 99500
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 10.2 重置接口调用次数
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/cgi-bin/clear_quota?access_token=ACCESS_TOKEN
|
||
{
|
||
"appid": "小程序AppID"
|
||
}
|
||
```
|
||
|
||
**限制**：每月只能重置10次
|
||
|
||
---
|
||
|
||
### 十一、数据分析
|
||
|
||
#### 11.1 获取访问趋势
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/datacube/getweanalysisappiddailyvisittrend?access_token=ACCESS_TOKEN
|
||
{
|
||
"begin_date": "20260101",
|
||
"end_date": "20260125"
|
||
}
|
||
|
||
# 返回
|
||
{
|
||
"list": [
|
||
{
|
||
"ref_date": "20260125",
|
||
"session_cnt": 1000, # 打开次数
|
||
"visit_pv": 5000, # 访问次数
|
||
"visit_uv": 800, # 访问人数
|
||
"visit_uv_new": 100, # 新用户数
|
||
"stay_time_uv": 120.5, # 人均停留时长（秒）
|
||
"stay_time_session": 60.2 # 次均停留时长（秒）
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 11.2 获取用户画像
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/datacube/getweanalysisappiduserportrait?access_token=ACCESS_TOKEN
|
||
{
|
||
"begin_date": "20260101",
|
||
"end_date": "20260125"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ 快速使用
|
||
|
||
### 方式一：使用Python管理脚本（推荐）
|
||
|
||
```bash
|
||
# 进入脚本目录
|
||
cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
|
||
|
||
# 安装依赖
|
||
pip install httpx python-dotenv
|
||
|
||
# 配置凭证
|
||
cp .env.example .env
|
||
# 编辑 .env 填入你的凭证
|
||
|
||
# 使用命令行工具
|
||
python mp_manager.py status # 查看小程序状态
|
||
python mp_manager.py audit # 查看审核状态
|
||
python mp_manager.py release # 发布上线
|
||
python mp_manager.py qrcode # 生成小程序码
|
||
```
|
||
|
||
### 方式二：使用微信开发者工具CLI
|
||
|
||
```bash
|
||
# CLI路径
|
||
CLI="/Applications/wechatwebdevtools.app/Contents/MacOS/cli"
|
||
|
||
# 打开项目
|
||
$CLI -o "/path/to/miniprogram"
|
||
|
||
# 编译
|
||
$CLI build-npm --project "/path/to/miniprogram"
|
||
|
||
# 预览（生成二维码）
|
||
$CLI preview --project "/path/to/miniprogram" --qr-format image --qr-output preview.png
|
||
|
||
# 上传代码
|
||
$CLI upload --project "/path/to/miniprogram" --version "1.0.0" --desc "版本说明"
|
||
|
||
# 提交审核
|
||
$CLI submit-audit --project "/path/to/miniprogram"
|
||
```
|
||
|
||
### 方式三：直接调用API
|
||
|
||
```python
|
||
import httpx
|
||
|
||
# 配置
|
||
ACCESS_TOKEN = "你的access_token"
|
||
BASE_URL = "https://api.weixin.qq.com"
|
||
|
||
async def check_audit_status(auditid: int):
|
||
"""查询审核状态"""
|
||
async with httpx.AsyncClient() as client:
|
||
resp = await client.post(
|
||
f"{BASE_URL}/wxa/get_auditstatus?access_token={ACCESS_TOKEN}",
|
||
json={"auditid": auditid}
|
||
)
|
||
return resp.json()
|
||
|
||
# 使用
|
||
result = await check_audit_status(1234567890)
|
||
print(result)
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 文件结构
|
||
|
||
```
|
||
小程序管理/
|
||
├── SKILL.md # 技能说明文档（本文件）
|
||
├── scripts/
|
||
│ ├── mp_manager.py # 小程序管理CLI工具
|
||
│ ├── mp_api.py # API封装类
|
||
│ ├── requirements.txt # Python依赖
|
||
│ └── .env.example # 环境变量模板
|
||
└── references/
|
||
├── API接口速查表.md # 常用API速查
|
||
├── 隐私协议填写指南.md # 隐私协议配置指南
|
||
└── 审核规范.md # 审核常见问题
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 常见问题
|
||
|
||
### Q1: 如何获取 component_verify_ticket？
|
||
|
||
微信会每10分钟向你配置的"消息与事件接收URL"推送。你需要部署一个服务来接收并存储它。
|
||
|
||
```python
|
||
# 接收推送示例
|
||
@app.post("/callback")
|
||
async def receive_ticket(request: Request):
|
||
xml_data = await request.body()
|
||
# 解密并解析XML
|
||
# 提取 ComponentVerifyTicket
|
||
# 存储到Redis或数据库
|
||
return "success"
|
||
```
|
||
|
||
### Q2: 审核被拒常见原因？
|
||
|
||
| 原因 | 解决方案 |
|
||
|------|----------|
|
||
| 类目不符 | 确保小程序功能与所选类目一致 |
|
||
| 隐私协议缺失 | 配置完整的隐私保护指引 |
|
||
| 诱导分享 | 移除"分享到群获取xx"等诱导文案 |
|
||
| 虚拟支付 | iOS不能使用虚拟支付，需走IAP |
|
||
| 内容违规 | 检查文案、图片是否合规 |
|
||
| 功能不完整 | 确保所有页面功能正常 |
|
||
|
||
### Q3: 审核需要多长时间？
|
||
|
||
- 首次提审：1-7个工作日
|
||
- 非首次：1-3个工作日
|
||
- 加急审核：付费服务，24小时内
|
||
|
||
### Q4: 如何提高审核通过率？
|
||
|
||
1. **提交完整测试账号**：如需登录才能体验功能
|
||
2. **录制操作视频**：复杂功能建议附上操作视频
|
||
3. **详细的版本描述**：说明本次更新内容
|
||
4. **完善隐私协议**：所有收集数据的接口都要说明用途
|
||
|
||
### Q5: 代码模板是什么？
|
||
|
||
第三方平台需要先将小程序代码上传到"草稿箱"，再添加到"代码模板库"。之后可以用这个模板批量部署到多个小程序。
|
||
|
||
流程：开发完成 → 上传到草稿箱 → 添加到模板库 → 使用模板部署
|
||
|
||
---
|
||
|
||
## 🔗 官方文档
|
||
|
||
- [微信开放平台文档](https://developers.weixin.qq.com/doc/oplatform/)
|
||
- [第三方平台开发指南](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/getting_started/how_to_read.html)
|
||
- [小程序管理接口](https://developers.weixin.qq.com/doc/oplatform/openApi/OpenApiDoc/)
|
||
- [代码管理接口](https://developers.weixin.qq.com/doc/oplatform/openApi/OpenApiDoc/miniprogram-management/code-management/commit.html)
|
||
- [隐私协议开发指南](https://developers.weixin.qq.com/miniprogram/dev/framework/user-privacy/)
|
||
|
||
---
|
||
|
||
## 📊 当前项目配置
|
||
|
||
### Soul派对小程序
|
||
|
||
| 项目 | 配置值 |
|
||
|------|--------|
|
||
| **AppID** | `wxb8bbb2b10dec74aa` |
|
||
| **项目路径** | `/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram` |
|
||
| **API域名** | `https://soul.quwanzhi.com` |
|
||
| **当前版本** | `1.0.13` |
|
||
| **认证状态** | ⏳ 审核中（等待1-5工作日） |
|
||
| **检查结果** | ✅ 8项通过 / ⚠️ 2项警告 / ❌ 0项错误 |
|
||
| **可上传** | ✅ 是 |
|
||
| **可发布** | ❌ 需等待认证通过 |
|
||
|
||
### 快速命令
|
||
|
||
```bash
|
||
# 打开项目
|
||
/Applications/wechatwebdevtools.app/Contents/MacOS/cli -o "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram"
|
||
|
||
# 预览
|
||
/Applications/wechatwebdevtools.app/Contents/MacOS/cli preview --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --qr-format image --qr-output preview.png
|
||
|
||
# 上传
|
||
/Applications/wechatwebdevtools.app/Contents/MacOS/cli upload --project "/Users/karuo/Documents/开发/3、自营项目/一场soul的创业实验/miniprogram" --version "1.0.0" --desc "版本说明"
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 全自动部署流程（v3.0）
|
||
|
||
### 完整生命周期流程图
|
||
|
||
```
|
||
╔══════════════════════════════════════════════════════════════════════════════╗
|
||
║ 小程序完整生命周期管理 ║
|
||
╠══════════════════════════════════════════════════════════════════════════════╣
|
||
║ ║
|
||
║ 阶段一：准备阶段 ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ │ ║
|
||
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
|
||
║ │ │ 注册小程序│ → │ 企业认证 │ → │ 配置项目 │ │ ║
|
||
║ │ │ (微信后台)│ │ (300元/年)│ │ (添加到管理)│ │ ║
|
||
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
|
||
║ │ │ │ │ │ ║
|
||
║ │ │ │ ▼ │ ║
|
||
║ │ │ │ mp_deploy.py add │ ║
|
||
║ │ │ ▼ │ ║
|
||
║ │ │ 等待审核 1-5 天 │ ║
|
||
║ │ │ mp_deploy.py cert-done │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ 阶段二：开发阶段 ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ │ ║
|
||
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
|
||
║ │ │ 编写代码 │ → │ 本地测试 │ → │ 项目检查 │ │ ║
|
||
║ │ │ (开发者) │ │ (模拟器) │ │ mp_full │ │ ║
|
||
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
|
||
║ │ │ │ ║
|
||
║ │ ▼ │ ║
|
||
║ │ mp_full.py check <id> │ ║
|
||
║ │ 检查: 配置/域名/隐私/认证 │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ 阶段三：部署阶段（全自动） ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ │ ║
|
||
║ │ mp_full.py auto <id> -v "1.0.0" -d "版本描述" │ ║
|
||
║ │ │ │ ║
|
||
║ │ ▼ │ ║
|
||
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
|
||
║ │ │ ① 检查 │ → │ ② 上传 │ → │ ③ 提审 │ │ ║
|
||
║ │ │ 项目问题 │ │ 代码到微信│ │ 提交审核 │ │ ║
|
||
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
|
||
║ │ │ │ │ │ ║
|
||
║ │ ▼ ▼ ▼ │ ║
|
||
║ │ 自动检测 使用CLI/npm 已认证→API提审 │ ║
|
||
║ │ 配置/认证/域名 优先级选择 未认证→手动提审 │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ 阶段四：发布阶段 ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ │ ║
|
||
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
|
||
║ │ │ 等待审核 │ → │ 审核通过 │ → │ 发布上线 │ │ ║
|
||
║ │ │ 1-7工作日 │ │ 通知 │ │ release │ │ ║
|
||
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
|
||
║ │ │ │ ║
|
||
║ │ ▼ │ ║
|
||
║ │ mp_deploy.py release <id> │ ║
|
||
║ │ 或 微信后台点击发布 │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ │ ║
|
||
║ ▼ ║
|
||
║ 阶段五：运营阶段 ║
|
||
║ ┌─────────────────────────────────────────────────────────────────────┐ ║
|
||
║ │ │ ║
|
||
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
|
||
║ │ │ 数据分析 │ │ 汇总报告 │ │ 版本迭代 │ │ ║
|
||
║ │ │ mp_manager│ │ mp_full │ │ 循环部署 │ │ ║
|
||
║ │ └──────────┘ └──────────┘ └──────────┘ │ ║
|
||
║ │ │ │ │ │ ║
|
||
║ │ ▼ ▼ ▼ │ ║
|
||
║ │ data命令 report命令 返回部署阶段 │ ║
|
||
║ │ │ ║
|
||
║ └─────────────────────────────────────────────────────────────────────┘ ║
|
||
║ ║
|
||
╚══════════════════════════════════════════════════════════════════════════════╝
|
||
```
|
||
|
||
### 工具整合架构图
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────────────────┐
|
||
│ 小程序管理工具整合架构 │
|
||
├────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 用户命令层 │ │
|
||
│ │ mp_full.py report │ mp_full.py check │ mp_full.py auto │ │
|
||
│ │ mp_deploy.py list │ mp_deploy.py cert │ mp_manager.py status │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Python 管理层 │ │
|
||
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
|
||
│ │ │ mp_full.py │ │ mp_deploy.py │ │ mp_api.py │ │ │
|
||
│ │ │ 全能管理器 │ │ 部署工具 │ │ API封装 │ │ │
|
||
│ │ │ • 检查 │ │ • 多小程序 │ │ • 认证 │ │ │
|
||
│ │ │ • 报告 │ │ • 认证管理 │ │ • 审核 │ │ │
|
||
│ │ │ • 自动部署 │ │ • 发布 │ │ • 发布 │ │ │
|
||
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 外部工具层 │ │
|
||
│ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │
|
||
│ │ │ 微信开发者 │ │ miniprogram │ │ 微信开放平台 │ │ │
|
||
│ │ │ 工具 CLI │ │ -ci (npm) │ │ API │ │ │
|
||
│ │ │ │ │ │ │ │ │ │
|
||
│ │ │ • 打开项目 │ │ • 上传代码 │ │ • 提交审核 │ │ │
|
||
│ │ │ • 预览 │ │ • 预览 │ │ • 发布 │ │ │
|
||
│ │ │ • 上传 │ │ • 构建npm │ │ • 认证管理 │ │ │
|
||
│ │ │ • 编译 │ │ • sourceMap │ │ • 数据分析 │ │ │
|
||
│ │ └───────────────┘ └───────────────┘ └───────────────┘ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ▼ ▼ ▼ │ │
|
||
│ │ 优先级: 1 优先级: 2 优先级: 3 │ │
|
||
│ │ (无需密钥) (需要密钥) (需要token) │ │
|
||
│ └─────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
# 进入脚本目录
|
||
cd /Users/karuo/Documents/个人/卡若AI/02_卡人（水）/小程序管理/scripts
|
||
|
||
# 1. 查看已配置的小程序
|
||
python3 mp_deploy.py list
|
||
|
||
# 2. 添加新小程序（交互式）
|
||
python3 mp_deploy.py add
|
||
|
||
# 3. 检查认证状态
|
||
python3 mp_deploy.py cert-status soul-party
|
||
|
||
# 4. 一键部署
|
||
python3 mp_deploy.py deploy soul-party
|
||
|
||
# 5. 审核通过后发布
|
||
python3 mp_deploy.py release soul-party
|
||
```
|
||
|
||
### 命令速查
|
||
|
||
| 命令 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `list` | 列出所有小程序 | `python3 mp_deploy.py list` |
|
||
| `add` | 添加新小程序 | `python3 mp_deploy.py add` |
|
||
| `deploy` | 一键部署 | `python3 mp_deploy.py deploy soul-party` |
|
||
| `upload` | 仅上传代码 | `python3 mp_deploy.py upload soul-party` |
|
||
| `cert` | 提交认证 | `python3 mp_deploy.py cert soul-party` |
|
||
| `cert-status` | 查询认证状态 | `python3 mp_deploy.py cert-status soul-party` |
|
||
| `cert-done` | 标记认证完成 | `python3 mp_deploy.py cert-done soul-party` |
|
||
| `release` | 发布上线 | `python3 mp_deploy.py release soul-party` |
|
||
|
||
---
|
||
|
||
## 📋 企业认证详解
|
||
|
||
### 认证流程图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 企业认证流程 │
|
||
├──────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||
│ │ 准备 │ → │ 提交 │ → │ 审核 │ │
|
||
│ │ 材料 │ │ 认证 │ │ 等待 │ │
|
||
│ └─────────┘ └─────────┘ └─────────┘ │
|
||
│ │ │ │ │
|
||
│ ↓ ↓ ↓ │
|
||
│ ┌─────────────────────────────────────────┐ │
|
||
│ │ • 营业执照 • 微信后台上传 • 1-5工作日 │ │
|
||
│ │ • 法人身份证 • 法人扫码验证 • 审核结果 │ │
|
||
│ │ • 法人微信号 • 支付300元 • 通知 │ │
|
||
│ └─────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ⚠️ 认证有效期：1年，到期需年审 │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 认证材料清单
|
||
|
||
| 材料 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| 企业营业执照 | ✅ | 扫描件或照片，信息清晰 |
|
||
| 法人身份证 | ✅ | 正反面照片 |
|
||
| 法人微信号 | ✅ | 需绑定银行卡，用于扫码验证 |
|
||
| 联系人手机号 | ✅ | 接收审核通知 |
|
||
| 认证费用 | ✅ | 300元/年 |
|
||
| 其他资质 | 可选 | 特殊行业需要（如医疗、金融） |
|
||
|
||
### 认证状态说明
|
||
|
||
| 状态 | 说明 | 下一步操作 |
|
||
|------|------|------------|
|
||
| `unknown` | 未知/未检查 | 运行 `cert-status` 检查 |
|
||
| `pending` | 审核中 | 等待1-5个工作日 |
|
||
| `verified` | 已认证 | 可以正常发布 |
|
||
| `rejected` | 被拒绝 | 查看原因，修改后重新提交 |
|
||
| `expired` | 已过期 | 需要重新认证（年审） |
|
||
|
||
### 认证API（第三方平台）
|
||
|
||
如果你有第三方平台资质，可以通过API代商家提交认证：
|
||
|
||
```python
|
||
# POST https://api.weixin.qq.com/wxa/sec/wxaauth?access_token=ACCESS_TOKEN
|
||
{
|
||
"auth_type": 1, # 1=企业
|
||
"auth_data": {
|
||
"name": "企业名称",
|
||
"code": "统一社会信用代码",
|
||
"legal_persona_wechat": "法人微信号",
|
||
"legal_persona_name": "法人姓名",
|
||
"legal_persona_idcard": "法人身份证号",
|
||
"component_phone": "联系电话"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 GitHub开源工具推荐
|
||
|
||
### 1. miniprogram-ci（官方）
|
||
|
||
微信官方提供的CI工具，支持Node.js环境使用。
|
||
|
||
**安装**：
|
||
```bash
|
||
npm install miniprogram-ci -g
|
||
```
|
||
|
||
**使用**：
|
||
```javascript
|
||
const ci = require('miniprogram-ci');
|
||
|
||
const project = new ci.Project({
|
||
appid: 'wxb8bbb2b10dec74aa',
|
||
type: 'miniProgram',
|
||
projectPath: '/path/to/miniprogram',
|
||
privateKeyPath: '/path/to/private.key',
|
||
ignores: ['node_modules/**/*']
|
||
});
|
||
|
||
// 上传
|
||
await ci.upload({
|
||
project,
|
||
version: '1.0.0',
|
||
desc: '版本描述',
|
||
setting: {
|
||
es6: true,
|
||
minify: true
|
||
}
|
||
});
|
||
```
|
||
|
||
**获取私钥**：
|
||
1. 登录小程序后台
|
||
2. 开发管理 → 开发设置
|
||
3. 小程序代码上传密钥 → 下载
|
||
|
||
### 2. multi-mini-ci
|
||
|
||
多平台小程序自动化上传工具。
|
||
|
||
**GitHub**: https://github.com/Ethan-zjc/multi-mini-ci
|
||
|
||
**支持平台**：
|
||
- 微信小程序
|
||
- 支付宝小程序
|
||
- 百度小程序
|
||
- 字节跳动小程序
|
||
|
||
### 3. GitHub Actions集成
|
||
|
||
在项目中创建 `.github/workflows/deploy.yml`：
|
||
|
||
```yaml
|
||
name: Deploy MiniProgram
|
||
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
|
||
jobs:
|
||
deploy:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- name: Setup Node.js
|
||
uses: actions/setup-node@v3
|
||
with:
|
||
node-version: '18'
|
||
|
||
- name: Install dependencies
|
||
run: npm install
|
||
|
||
- name: Build
|
||
run: npm run build
|
||
|
||
- name: Upload to WeChat
|
||
env:
|
||
PRIVATE_KEY: ${{ secrets.MINIPROGRAM_PRIVATE_KEY }}
|
||
run: |
|
||
echo "$PRIVATE_KEY" > private.key
|
||
npx miniprogram-ci upload \
|
||
--pp ./dist \
|
||
--pkp ./private.key \
|
||
--appid wxb8bbb2b10dec74aa \
|
||
--uv "1.0.${{ github.run_number }}" \
|
||
-r 1 \
|
||
--desc "CI auto deploy"
|
||
```
|
||
|
||
---
|
||
|
||
## 📁 完整文件结构（v3.0）
|
||
|
||
```
|
||
小程序管理/
|
||
├── SKILL.md # 技能说明文档（本文件）
|
||
├── scripts/
|
||
│ ├── mp_full.py # 全能管理工具（推荐）⭐
|
||
│ ├── mp_deploy.py # 部署工具（多小程序管理）
|
||
│ ├── mp_manager.py # API管理工具（基础版）
|
||
│ ├── mp_api.py # API封装类（Python SDK）
|
||
│ ├── apps_config.json # 多小程序配置文件
|
||
│ ├── requirements.txt # Python依赖
|
||
│ ├── env_template.txt # 环境变量模板
|
||
│ └── reports/ # 检查报告存放目录
|
||
│ ├── summary_*.json # 汇总报告
|
||
│ └── report_*.json # 项目报告
|
||
└── references/
|
||
├── API接口速查表.md # 常用API速查
|
||
├── 企业认证完整指南.md # 认证操作指南
|
||
├── 隐私协议填写指南.md # 隐私协议配置指南
|
||
└── 审核规范.md # 审核常见问题
|
||
```
|
||
|
||
### 脚本功能对比
|
||
|
||
| 脚本 | 功能 | 推荐场景 |
|
||
|------|------|----------|
|
||
| **mp_full.py** | 全能：检查+报告+自动部署 | 日常管理（推荐） |
|
||
| **mp_deploy.py** | 多小程序管理+认证 | 多项目管理 |
|
||
| **mp_manager.py** | API调用工具 | 高级操作 |
|
||
| **mp_api.py** | Python SDK | 二次开发 |
|
||
|
||
---
|
||
|
||
## 📊 多小程序配置
|
||
|
||
配置文件位于 `scripts/apps_config.json`：
|
||
|
||
```json
|
||
{
|
||
"apps": [
|
||
{
|
||
"id": "soul-party",
|
||
"name": "Soul派对",
|
||
"appid": "wxb8bbb2b10dec74aa",
|
||
"project_path": "/path/to/miniprogram",
|
||
"certification": {
|
||
"status": "verified",
|
||
"enterprise_name": "厦门智群网络科技有限公司"
|
||
}
|
||
},
|
||
{
|
||
"id": "another-app",
|
||
"name": "另一个小程序",
|
||
"appid": "wx1234567890",
|
||
"project_path": "/path/to/another",
|
||
"certification": {
|
||
"status": "pending"
|
||
}
|
||
}
|
||
],
|
||
"certification_materials": {
|
||
"enterprise_name": "厦门智群网络科技有限公司",
|
||
"license_number": "统一社会信用代码",
|
||
"legal_persona_name": "法人姓名",
|
||
"component_phone": "15880802661"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ 常见场景速查
|
||
|
||
### 场景1：发布时提示"未完成微信认证"
|
||
|
||
```bash
|
||
# 1. 检查认证状态
|
||
python3 mp_deploy.py cert-status soul-party
|
||
|
||
# 2. 如果未认证，查看认证指引
|
||
python3 mp_deploy.py cert soul-party
|
||
|
||
# 3. 在微信后台完成认证后，标记完成
|
||
python3 mp_deploy.py cert-done soul-party
|
||
|
||
# 4. 重新部署
|
||
python3 mp_deploy.py deploy soul-party
|
||
```
|
||
|
||
### 场景2：新建小程序并快速上线
|
||
|
||
```bash
|
||
# 1. 添加小程序配置
|
||
python3 mp_deploy.py add
|
||
|
||
# 2. 提交认证
|
||
python3 mp_deploy.py cert my-new-app
|
||
|
||
# 3. 在微信后台完成认证（1-5天）
|
||
|
||
# 4. 认证通过后标记
|
||
python3 mp_deploy.py cert-done my-new-app
|
||
|
||
# 5. 一键部署
|
||
python3 mp_deploy.py deploy my-new-app
|
||
|
||
# 6. 审核通过后发布
|
||
python3 mp_deploy.py release my-new-app
|
||
```
|
||
|
||
### 场景3：仅更新代码（不提审）
|
||
|
||
```bash
|
||
# 快速上传到开发版
|
||
python3 mp_deploy.py upload soul-party -v "1.0.5" -d "修复xxx问题"
|
||
```
|
||
|
||
### 场景4：批量管理多个小程序
|
||
|
||
```bash
|
||
# 查看所有小程序
|
||
python3 mp_deploy.py list
|
||
|
||
# 检查所有认证状态
|
||
for app in soul-party another-app third-app; do
|
||
echo "=== $app ==="
|
||
python3 mp_deploy.py cert-status $app
|
||
done
|
||
```
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
### 官方文档
|
||
- [微信开放平台](https://developers.weixin.qq.com/doc/oplatform/)
|
||
- [小程序CI工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html)
|
||
- [第三方平台代认证](https://developers.weixin.qq.com/doc/oplatform/Third-party_Platforms/2.0/product/weapp_wxverify.html)
|
||
|
||
### 开源项目
|
||
- [miniprogram-ci](https://www.npmjs.com/package/miniprogram-ci) - 官方CI工具
|
||
- [multi-mini-ci](https://github.com/Ethan-zjc/multi-mini-ci) - 多平台上传
|
||
- [uz-miniprogram-ci](https://github.com/uzhan/uz-miniprogram-ci) - 一键上传发布
|
||
|
||
### 相关文章
|
||
- [GitHub Actions集成小程序CI](https://idayer.com/use-github-actions-and-mp-ci-for-wechat-miniprogram-ci/)
|
||
|
||
---
|
||
|
||
## 🔥 实战经验库（持续更新）
|
||
|
||
> 基于 Soul创业派对 项目开发过程中的真实问题和解决方案
|
||
|
||
### 一、数据库与后端问题
|
||
|
||
#### 1.1 后台初始化失败：Unknown column 'password' in 'field list'
|
||
|
||
**问题现象**：后台用户管理显示"初始化失败"
|
||
|
||
**根本原因**：数据库表结构缺少字段
|
||
|
||
**解决方案**：创建数据库初始化API自动修复
|
||
|
||
```typescript
|
||
// app/api/db/init/route.ts
|
||
// 自动检查并添加缺失字段
|
||
const columnsToAdd = [
|
||
{ name: 'password', type: 'VARCHAR(100)' },
|
||
{ name: 'session_key', type: 'VARCHAR(100)' },
|
||
{ name: 'referred_by', type: 'VARCHAR(50)' },
|
||
{ name: 'is_admin', type: 'BOOLEAN DEFAULT FALSE' },
|
||
]
|
||
|
||
for (const col of columnsToAdd) {
|
||
// 检查列是否存在，不存在则添加
|
||
await query(`ALTER TABLE users ADD COLUMN ${col.name} ${col.type}`)
|
||
}
|
||
```
|
||
|
||
**访问修复**：`curl https://your-domain.com/api/db/init`
|
||
|
||
---
|
||
|
||
#### 1.2 Column 'open_id' cannot be null
|
||
|
||
**问题现象**：后台添加用户失败
|
||
|
||
**根本原因**：数据库 `open_id` 字段设置为 NOT NULL，但后台添加用户时没有openId
|
||
|
||
**解决方案**：
|
||
```sql
|
||
ALTER TABLE users MODIFY COLUMN open_id VARCHAR(100) NULL
|
||
```
|
||
|
||
**最佳实践**：openId允许为NULL，因为：
|
||
- 后台手动添加的用户没有openId
|
||
- 微信登录用户有openId
|
||
- 两种用户需要共存
|
||
|
||
---
|
||
|
||
#### 1.3 AppID配置不一致
|
||
|
||
**问题现象**：微信登录返回错误，或获取openId失败
|
||
|
||
**根本原因**：项目中多个文件使用了不同的AppID
|
||
|
||
**检查清单**：
|
||
|
||
| 文件 | 配置项 | 正确值 |
|
||
|:---|:---|:---|
|
||
| `miniprogram/project.config.json` | appid | wxb8bbb2b10dec74aa |
|
||
| `app/api/miniprogram/login/route.ts` | MINIPROGRAM_CONFIG.appId | wxb8bbb2b10dec74aa |
|
||
| `app/api/wechat/login/route.ts` | APPID | wxb8bbb2b10dec74aa |
|
||
| `app/api/withdraw/route.ts` | WECHAT_PAY_CONFIG.appId | wxb8bbb2b10dec74aa |
|
||
|
||
**搜索命令**：
|
||
```bash
|
||
# 查找所有AppID配置
|
||
rg "wx[a-f0-9]{16}" --type ts --type json
|
||
```
|
||
|
||
---
|
||
|
||
#### 1.4 用户ID设计最佳实践
|
||
|
||
**推荐方案**：使用 `openId` 作为用户主键
|
||
|
||
```typescript
|
||
// 微信登录创建用户
|
||
const userId = openId // 直接使用openId作为用户ID
|
||
await query(`
|
||
INSERT INTO users (id, open_id, ...) VALUES (?, ?, ...)
|
||
`, [userId, openId, ...])
|
||
```
|
||
|
||
**优势**：
|
||
- 与微信官方标识一致
|
||
- 便于追踪和管理
|
||
- 后台显示更直观
|
||
|
||
**兼容方案**：后台添加的用户使用 `user_` 前缀
|
||
|
||
---
|
||
|
||
### 二、前端与UI问题
|
||
|
||
#### 2.1 Next.js Hydration错误
|
||
|
||
**问题现象**：页面显示"哎呀，出错了"，控制台报 hydration 错误
|
||
|
||
**根本原因**：服务端和客户端渲染结果不一致（如使用localStorage、zustand持久化）
|
||
|
||
**解决方案**：添加mounted状态检查
|
||
|
||
```tsx
|
||
export default function AdminLayout({ children }) {
|
||
const [mounted, setMounted] = useState(false)
|
||
|
||
useEffect(() => {
|
||
setMounted(true)
|
||
}, [])
|
||
|
||
// 等待客户端mount后再渲染
|
||
if (!mounted) {
|
||
return <div>加载中...</div>
|
||
}
|
||
|
||
return <div>{children}</div>
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2 数据类型不匹配：toFixed() 报错
|
||
|
||
**问题现象**：显示金额时报错 `toFixed is not a function`
|
||
|
||
**根本原因**：数据库返回的 `DECIMAL` 字段是字符串类型
|
||
|
||
**解决方案**：
|
||
```tsx
|
||
// ❌ 错误
|
||
<div>{user.earnings.toFixed(2)}</div>
|
||
|
||
// ✅ 正确
|
||
<div>{parseFloat(String(user.earnings || 0)).toFixed(2)}</div>
|
||
```
|
||
|
||
**通用处理函数**：
|
||
```typescript
|
||
const formatMoney = (value: any) => {
|
||
return parseFloat(String(value || 0)).toFixed(2)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 三、小程序开发问题
|
||
|
||
#### 3.1 搜索功能：章节ID格式不一致
|
||
|
||
**问题现象**：搜索结果跳转到阅读页404
|
||
|
||
**根本原因**：
|
||
- `book-chapters.json` 使用 `chapter-2`, `chapter-3` 格式
|
||
- 阅读页使用 `1.1`, `1.2` 格式
|
||
|
||
**解决方案**：从标题提取章节号
|
||
|
||
```typescript
|
||
// 从标题提取章节号（如 "1.1 荷包：..." → "1.1"）
|
||
const sectionIdMatch = chapter.title?.match(/^(\d+\.\d+)\s/)
|
||
const sectionId = sectionIdMatch ? sectionIdMatch[1] : chapter.id
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.2 搜索功能：敏感信息过滤
|
||
|
||
**需求**：搜索结果不能显示用户手机号、微信号等
|
||
|
||
**实现**：
|
||
```typescript
|
||
const cleanContent = content
|
||
.replace(/1[3-9]\d{9}/g, '***') // 手机号
|
||
.replace(/微信[：:]\s*\S+/g, '微信：***') // 微信号
|
||
.replace(/QQ[：:]\s*\d+/g, 'QQ：***') // QQ号
|
||
.replace(/邮箱[：:]\s*\S+@\S+/g, '邮箱：***') // 邮箱
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.3 上下章导航：付费内容也需要显示
|
||
|
||
**需求**：即使用户没有购买，也要显示上一篇/下一篇导航
|
||
|
||
**实现**：将导航组件移到付费墙之外
|
||
|
||
```html
|
||
<!-- 付费墙 -->
|
||
<view class="paywall">
|
||
<!-- 解锁按钮 -->
|
||
</view>
|
||
|
||
<!-- 章节导航 - 始终显示 -->
|
||
<view class="chapter-nav">
|
||
<view class="nav-btn nav-prev" bindtap="goToPrev">上一篇</view>
|
||
<view class="nav-btn nav-next" bindtap="goToNext">下一篇</view>
|
||
</view>
|
||
```
|
||
|
||
---
|
||
|
||
#### 3.4 分销绑定：推广码捕获
|
||
|
||
**需求**：用户通过分享链接进入时，自动绑定推广者
|
||
|
||
**实现流程**：
|
||
|
||
```javascript
|
||
// app.js - onLaunch/onShow
|
||
onLaunch(options) {
|
||
if (options.query && options.query.ref) {
|
||
wx.setStorageSync('referral_code', options.query.ref)
|
||
this.bindReferral(options.query.ref)
|
||
}
|
||
}
|
||
|
||
// 小程序码scene参数解析
|
||
const scene = decodeURIComponent(options.scene)
|
||
const params = new URLSearchParams(scene)
|
||
const ref = params.get('ref')
|
||
```
|
||
|
||
**后端绑定**：
|
||
```sql
|
||
UPDATE users SET referred_by = ? WHERE id = ? AND referred_by IS NULL
|
||
```
|
||
|
||
---
|
||
|
||
### 四、后台管理优化
|
||
|
||
#### 4.1 菜单精简原则
|
||
|
||
**优化前（9项）**：
|
||
- 数据概览、网站配置、内容管理、用户管理、匹配配置、分销管理、支付配置、分账提现、二维码、系统设置
|
||
|
||
**优化后（6项）**：
|
||
- 数据概览、内容管理、用户管理、分账管理、支付设置、系统设置
|
||
|
||
**精简原则**：
|
||
1. 合并相似功能（分销管理 + 分账提现 → 分账管理）
|
||
2. 移除低频功能（二维码、匹配配置 → 可在系统设置中配置）
|
||
3. 核心功能优先
|
||
|
||
---
|
||
|
||
#### 4.2 用户绑定关系展示
|
||
|
||
**需求**：查看用户的推广下线详情
|
||
|
||
**实现API**：
|
||
```typescript
|
||
// GET /api/db/users/referrals?userId=xxx
|
||
const referrals = await query(`
|
||
SELECT * FROM users WHERE referred_by = ?
|
||
ORDER BY created_at DESC
|
||
`, [referralCode])
|
||
```
|
||
|
||
**展示信息**：
|
||
- 绑定总数、已付费人数、免费用户
|
||
- 累计收益、待提现金额
|
||
- 每个绑定用户的状态（VIP/已付费/未付费）
|
||
|
||
---
|
||
|
||
### 五、分销与提现
|
||
|
||
#### 5.1 自动分账规则
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|:---|:---|:---|
|
||
| 分销比例 | 90% | 推广者获得订单金额的90% |
|
||
| 结算方式 | 自动 | 用户付款后立即计入推广者账户 |
|
||
| 提现方式 | 微信零钱 | 企业付款到零钱 |
|
||
| 提现门槛 | 1元 | 累计收益≥1元可提现 |
|
||
|
||
#### 5.2 提现流程
|
||
|
||
```
|
||
用户申请提现
|
||
↓
|
||
扣除账户余额，增加待提现金额
|
||
↓
|
||
管理员后台审核
|
||
↓
|
||
批准 → 调用微信企业付款API → 到账
|
||
拒绝 → 返还用户余额
|
||
```
|
||
|
||
---
|
||
|
||
### 六、开发规范
|
||
|
||
#### 6.1 配置统一管理
|
||
|
||
```typescript
|
||
// lib/config.ts
|
||
export const WECHAT_CONFIG = {
|
||
appId: process.env.WECHAT_APPID || 'wxb8bbb2b10dec74aa',
|
||
appSecret: process.env.WECHAT_APPSECRET || '...',
|
||
mchId: '1318592501',
|
||
apiKey: '...'
|
||
}
|
||
```
|
||
|
||
**所有API文件统一引用此配置，避免硬编码**
|
||
|
||
#### 6.2 数据库字段命名
|
||
|
||
| 前端字段 | 数据库字段 | 说明 |
|
||
|:---|:---|:---|
|
||
| openId | open_id | 微信openId |
|
||
| hasFullBook | has_full_book | 是否购买全书 |
|
||
| referralCode | referral_code | 推广码 |
|
||
| pendingEarnings | pending_earnings | 待提现收益 |
|
||
|
||
**规则**：数据库使用snake_case，前端使用camelCase
|
||
|
||
#### 6.3 错误处理模板
|
||
|
||
```typescript
|
||
export async function POST(request: Request) {
|
||
try {
|
||
const body = await request.json()
|
||
// 业务逻辑
|
||
return NextResponse.json({ success: true, data: ... })
|
||
} catch (error) {
|
||
console.error('[API名称] 错误:', error)
|
||
return NextResponse.json({
|
||
success: false,
|
||
error: '用户友好的错误信息'
|
||
}, { status: 500 })
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📌 问题排查清单
|
||
|
||
### 小程序无法登录
|
||
|
||
- [ ] 检查AppID是否正确（project.config.json vs 后端）
|
||
- [ ] 检查AppSecret是否正确
|
||
- [ ] 检查API域名是否已配置
|
||
- [ ] 检查后端服务是否正常运行
|
||
- [ ] 查看后端日志 `[MiniLogin]`
|
||
|
||
### 后台显示异常
|
||
|
||
- [ ] 运行 `/api/db/init` 初始化数据库
|
||
- [ ] 检查数据库连接是否正常
|
||
- [ ] 清除浏览器缓存（Cmd+Shift+R）
|
||
- [ ] 查看浏览器控制台错误
|
||
|
||
### 搜索功能无结果
|
||
|
||
- [ ] 检查 `public/book-chapters.json` 是否存在
|
||
- [ ] 检查章节文件路径是否正确（filePath字段）
|
||
- [ ] 检查关键词编码（中文需URL编码）
|
||
|
||
### 提现失败
|
||
|
||
- [ ] 检查用户余额是否充足
|
||
- [ ] 检查用户是否有openId
|
||
- [ ] 检查微信商户API证书配置
|
||
- [ ] 查看后端日志 `[Withdraw]`
|
||
|
||
---
|
||
|
||
**创建时间**：2026-01-25
|
||
**更新时间**：2026-01-25
|
||
**版本**：v3.1（新增实战经验库）
|
||
**维护者**：卡若
|