# 微信云开发规则

## 概述
本文档定义了使用微信云开发（CloudBase）为小程序提供后端服务的开发规范。
当 PRD 分析判定小程序需要后端服务且目标平台包含微信小程序时，在前端开发过程中同步生成云函数代码。部署操作在用户确认后通过 CloudBase MCP 工具完成。

## 适用条件
- 当小程序需要后端服务时启用（Taro 项目默认支持编译为微信小程序）
- `Taro.cloud` API 只在微信小程序（weapp）运行时可用，H5 预览时走 mock 数据
- 所有涉及 `Taro.cloud` 的代码必须用 `process.env.TARO_ENV === 'weapp'` 包裹

---

## 开发流程

### Phase A：后端需求分析

在 PRD 分析阶段（第一阶段）同步完成，识别需要云端支持的功能：

1. 需要用户身份识别 → 云函数 `login`（获取 openid）
2. 需要数据持久化 → 对应集合 + 云函数（CRUD）
3. 需要文件上传/下载 → 云存储 API

输出格式：
```
### 数据库集合设计
| 集合名 | 用途 | 核心字段 | 索引字段 |
|--------|------|----------|----------|
| users | 用户信息 | _openid, nickname, avatar, createTime | _openid |
| orders | 订单 | _openid, items, status, createTime | _openid, status |

### 云函数列表
| 函数名 | 用途 | 入参 | 返回 |
|--------|------|------|------|
| login | 获取用户openid | 无 | { openid } |
| getOrders | 查询订单 | { status? } | { orders: [] } |
```

### Phase B：生成云函数代码

在前端页面开发阶段（第六阶段）同步完成。每开发一个需要后端数据的页面时，同时生成对应的云函数代码，写入项目根目录的 `cloudfunctions/` 目录。每个云函数一个独立子目录。

### Phase C：前端调用层

前端统一使用 `src/services/cloud.ts`（模板已预置）封装调用：
- 微信平台（weapp）：走真实 `Taro.cloud.callFunction`
- 非微信平台（H5 预览、抖音、支付宝）：走 mock 数据

页面通过 service 层获取数据。涉及云函数的 mock 文件命名为 `src/data/<functionName>.ts`，`cloud.ts` 会在非微信环境下按函数名自动加载对应文件。

### Phase D：通过 MCP 部署（用户确认后执行）

用户确认部署后，使用 CloudBase MCP 工具完成部署（MCP 自动处理认证，无需主动管理登录状态）。

部署成功后，通过 MCP 的 `envQuery` 工具获取当前环境 ID，然后将 `app.tsx` 中 `Taro.cloud.init()` 的 `env` 参数设置为真实的环境 ID。如果 `envQuery` 无法获取，则询问用户提供环境 ID。

### Phase E：验证（部署后执行）

通过 MCP 调用云函数验证部署成功，输出结果摘要。

---

## 云函数代码规范

### 目录结构
```
cloudfunctions/
├── login/
│   ├── index.js
│   └── package.json
├── getUsers/
│   ├── index.js
│   └── package.json
└── createOrder/
    ├── index.js
    └── package.json
```

### 入口文件模板（index.js）
```javascript
const cloud = require('wx-server-sdk')
cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })
const db = cloud.database()

exports.main = async (event, context) => {
  try {
    const wxContext = cloud.getWXContext()
    const openid = wxContext.OPENID

    // 业务逻辑...
    const result = null // 替换为实际逻辑

    return { code: 0, message: 'success', data: result }
  } catch (err) {
    console.error('[functionName] error:', err)
    return { code: -1, message: err.message || '服务异常', data: null }
  }
}
```

### package.json 模板
```json
{
  "name": "functionName",
  "version": "1.0.0",
  "main": "index.js",
  "dependencies": {
    "wx-server-sdk": "~2.6.3"
  }
}
```

### 编码规范
- 函数命名：camelCase，动词开头（getXxx, createXxx, updateXxx, deleteXxx）
- 必须调用 `cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV })`
- 通过 `cloud.getWXContext().OPENID` 获取用户身份（免鉴权）
- 统一返回格式：`{ code: number, message: string, data: any }`
  - code=0 表示成功，code<0 表示失败
- 必须有 try-catch 错误处理
- 日志使用 `console.error('[函数名]', err)` 格式
- 云函数使用 CommonJS（`require` / `exports.main`），不使用 ESM

---

## 数据库规范

### 集合命名
- 小写字母 + 下划线：`users`, `user_profiles`, `order_items`
- 避免使用数据库保留字

### 文档结构约定
- 用户相关数据必须包含 `_openid` 字段用于权限控制
- 时间字段使用 `db.serverDate()` 写入
- 必须为高频查询字段建立索引

### 安全规则
- 默认规则："仅创建者可读写"（通过 _openid 匹配）
- 公开数据（如商品列表）：所有人可读，仅管理员可写

---

## 前端调用规范

### 初始化（app.tsx）

在 App 组件中初始化云开发，必须做平台判断：
```tsx
import { useEffect } from 'react'

function App(props) {
  useEffect(() => {
    if (process.env.TARO_ENV === 'weapp') {
      Taro.cloud.init({ env: 'your-env-id', traceUser: true })
    }
  }, [])
  return props.children
}
```

注意：`process.env.TARO_ENV` 在编译时被替换为常量，非微信平台的 cloud 代码会被 tree shaking 移除。

### Service 层封装（src/services/cloud.ts）

项目模板中已预置 `src/services/cloud.ts`，提供统一的云调用封装：
- 微信平台：走真实云函数调用
- 非微信平台（H5 预览、抖音、支付宝）：走 mock 数据

开发云函数时，只需修改此文件中的 mock fallback 逻辑为真实云调用即可。

### 页面中使用
```typescript
import { callFunction } from '@/services/cloud'

const [orders, setOrders] = useState<Order[]>([])

useEffect(() => {
  callFunction<Order[]>('getOrders', { status: 'pending' })
    .then(setOrders)
    .catch(err => console.error('[OrderPage]', err))
}, [])
```

---

## MCP 部署操作

### 配置 MCP

部署前需确认用户 IDE 已配置 CloudBase MCP。如果 MCP 工具不可用，通过以下方式帮助用户配置：

**方式一（推荐）：自动触发安装**

使用终端工具执行以下命令（根据操作系统选择），系统会自动打开 Trae 的 MCP 配置确认窗口：

- macOS: `open "trae-cn://trae.ai-ide/mcp-import?type=stdio&name=cloudbase&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjbG91ZGJhc2UvY2xvdWRiYXNlLW1jcEBsYXRlc3QiXX0%3D"`
- Windows: `start "" "trae-cn://trae.ai-ide/mcp-import?type=stdio&name=cloudbase&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjbG91ZGJhc2UvY2xvdWRiYXNlLW1jcEBsYXRlc3QiXX0%3D"`

执行后告知用户：
1. 在弹出的确认窗口中点击「确认」（添加 CloudBase MCP 服务）
2. 在弹出的 MCP 管理面板中，点击「+ 添加」按钮左侧的 🔄 按钮刷新，等待 cloudbase 下的工具列表加载成功
3. 回复「已配置」继续部署

**重要**：MCP 工具只有在用户发起新一轮对话后才能被检测到，因此必须等待用户回复后再继续部署流程，不要尝试在当前轮次中轮询检测。

**方式二：手动配置（仅当方式一失败时使用）**

1. 打开「设置」→「MCP」
2. 点击「+ 添加」→「手动配置」
3. 将以下 JSON 粘贴到输入框中并点击确认：

```json
{
  "mcpServers": {
    "cloudbase": {
      "command": "npx",
      "args": [
        "-y",
        "@cloudbase/cloudbase-mcp@latest"
      ]
    }
  }
}
```

用户确认配置完成后，可直接调用以下 MCP 工具。

### 部署顺序
1. 创建所有数据库集合
2. 为集合创建索引
3. 部署所有云函数
4. 调用 login 函数验证部署成功

### 创建数据库集合
- 工具：`writeNoSqlDatabaseStructure`
- 参数：`action: "createCollection"`, `collectionName: "xxx"`

### 创建索引
- 工具：`writeNoSqlDatabaseStructure`
- 参数：`action: "updateCollection"`, `collectionName: "xxx"`, 包含 CreateIndexes 配置

### 部署云函数
- 工具：`manageFunctions`
- 参数：`action: "createFunction"`, `functionName: "xxx"`, `functionRootPath: "<项目路径>/cloudfunctions"`

### 验证部署
- 工具：`manageFunctions`
- 参数：`action: "invoke"`, `functionName: "login"`, `params: {}`

### 输出部署结果
部署完成后，向用户输出摘要（环境 ID 从部署阶段 `envQuery` 获取的真实值动态替换）：
```
✅ 后端部署完成：
- 已部署云函数：login, getUsers, createOrder（共 3 个）
- 已创建数据库集合：users, orders（共 2 个）
- 验证结果：login 函数调用成功

🔗 云开发管理控制台：https://tcb.cloud.tencent.com/dev?envId=<环境ID>#/scf
   您可以点击上方链接，在腾讯云控制台中查看和管理云函数、数据库等资源。
```

---

## 约束

- **禁止执行任何 CLI 命令**（tcb、cloudbase、npm 等），所有云端操作通过 MCP 工具完成
- **H5 预览模式下使用 mock 数据**，不调用真实云端
- **env-id 在部署阶段确定**：生成代码时 `Taro.cloud.init({ env: '' })` 可留空或用任意占位，部署阶段通过 MCP `envQuery` 获取真实环境 ID 后修改 `app.tsx`
- **云函数使用 CommonJS**：`require` / `exports.main`，不使用 ESM
- **平台判断是强制的**：所有涉及 `Taro.cloud` 的代码必须用 `process.env.TARO_ENV === 'weapp'` 包裹
- **MCP 认证由 MCP 内部自动处理**：Skill 不需要主动调用 auth 工具或管理登录状态