iloom-flatten/skills/meoo-cloud/SKILL.md

---
name: meoo-cloud
description: 提供云服务后端能力（数据库、认证、文件存储、Edge Functions）。任何需要数据存储、用户认证、文件上传、实时功能、服务端逻辑的开发都必须先加载此技能进行初始化。例如：开发 CRM 系统、博客网站、聊天应用、文件管理器、AI 应用等。
---

# Meoo Cloud 云服务开发技能

## 技能概述

Meoo Cloud 基于 Supabase 提供后端云服务（数据库、认证、文件存储、Edge Functions），通过 meoo-cli 命令行工具进行管理和操作。

## 快速开始

### 必读文档策略（BLOCKING — 不可跳过）

BLOCKING: 在执行任何 meoo-cli 命令（包括 cloud init）或编写任何云服务代码之前，MUST 先用 Read 工具读取对应的参考文档。违反此规则将导致错误的 RLS 策略、遗漏必传参数、数据库结构不规范等严重问题。

| 开发需求 | 必读文档（MUST Read） | 主要CLI命令 | 适用场景 |
|----------|----------|-------------|----------|
| **数据库操作** | `skills/meoo-cloud/references/database.md` | `cloud migrate/query/tables` | 任何项目的基础数据存储 |
| **文件上传存储** | `skills/meoo-cloud/references/storage.md` | `cloud migrate` + 前端代码 | 图片、文档、媒体文件处理 |
| **实时功能聊天** | `skills/meoo-cloud/references/realtime.md` | `cloud migrate` + 订阅代码 | 即时通讯、协作应用 |
| **API 接口、云函数开发** | `skills/meoo-cloud/references/edge-functions.md` | `cloud deploy-function/delete-function` | 自定义后端逻辑、第三方集成 |
| **用户认证系统** | `skills/meoo-cloud/references/authentication.md` | `cloud migrate` + 认证代码 | 登录注册、权限管理、管理员、管理后台 |
| **遇到错误问题** | `skills/meoo-cloud/references/troubleshooting.md` | 各种诊断命令 | 调试和问题解决 |

### 标准执行流程（严格按顺序，不可跳步）

1. **分析需求** → 确定属于上表哪个功能模块
2. **读取文档** → 使用 Read 工具读取对应的参考文档（BLOCKING：此步完成前，严禁执行后续任何步骤）
3. **初始化服务** → `meoo-cli cloud init -d "项目描述"`
4. **按文档实施** → 设计数据结构 → 执行 migrate → 编写业务代码

NEVER: 严禁跳过第 2 步直接执行 cloud init 或任何其他 CLI 命令。你的第一个工具调用必须是 Read 参考文档，不是 Bash。

## 开发约束与注意事项

### 文档优先原则（强制）
- ✅ **正确流程**：Read 参考文档 → cloud init → 按文档编写代码
- ❌ **严重违规**：cloud init → cloud migrate（跳过文档）
- ❌ **严重违规**：cloud init → 直接编写代码（跳过文档）
- ❌ **严重违规**：直接执行任何 meoo-cli 命令（跳过文档）

### 技术约束
- **CLI 操作**：所有云服务管理通过 meoo-cli 命令执行
- **SQL 执行**：只能通过 `cloud migrate/query --sql "..."` 直接传参，不支持写 .sql 文件后用 shell 执行
- **禁止编辑**：初始化后 `src/supabase/client.ts` 和 `src/supabase/types.ts` 由系统自动生成
- **保留 Schema**：不得修改 auth/storage/realtime/supabase_functions/vault 等系统表
### 使用原则
- **匿名优先**：默认免登录可用；新建表 `user_id` 可空、RLS 默认 `USING (true)`。
- **加登录 = 整体改造**：要做登录时连同现有表与功能一起 review —— 升级 RLS、补全各模块权限相关逻辑。详见 `references/authentication.md`。
- **禁止 Mock**：所有功能基于云服务使用真实的数据，禁止 mock 数据
- 前端所有云服务操作都必须在 UI 上给用户明确的成功/失败反馈。

### AI 服务集成
如果项目需要 AI 功能，必须先加载对应的技能：
- **文本 AI**：`meoo-llm-ai` - 聊天对话、文本生成、总结翻译等
- **应用内图片生成**：`meoo-image-gen-ai` - 给用户应用接入文生图、图片编辑等能力；对话中或构建态生成页面素材走 Bash `meoo-cli image-generate`
- **视觉理解**：`meoo-vision-ai` - 图片识别等

---

## CLI 命令完整参考
**cloud 命令必须单独调用，不支持与其他命令在一行一起调用**
### cloud init - 初始化云服务

**前置条件**：MUST 先用 Read 工具读取与当前需求相关的参考文档（如 `database.md`、`edge-functions.md` 等），理解数据结构和约束后再执行初始化。
**说明**：初始化 Meoo Cloud 服务，自动安装依赖，生成客户端文件

**参数说明**：
- `-d, --description <描述>` (必需)：项目功能描述，用于标识项目用途和功能范围，32 字以内

**示例**：
```bash
meoo-cli cloud init -d "项目描述"
```

### cloud migrate - 数据库结构变更

**前置条件**：MUST 先 Read `skills/meoo-cloud/references/database.md`，了解 RLS 策略模板和字段规范后再执行。

**说明**：执行数据库结构变更，包括创建表、修改结构、RLS 策略等。--name、--changes 和 --sql 参数都是必传的，缺一不可。
变更说明中要用 markdown 格式详细说明一下改动点。

**SQL 编写建议**：
- 单次 `--sql` 不要过长，复杂变更（建表 / 索引 / RLS / 种子数据）拆成多次 migrate 分别执行，便于定位失败和重试。
- RLS 策略名用**英文 snake_case 无引号**，格式 `<scope>_<action>_<table>`（如 `anon_select_posts`、`users_update_own_data`）。禁止中文或带空格策略名，否则会和外层 `--sql "..."` 双引号冲突。

**参数说明**：
- `--sql <SQL语句>` (必需)：要执行的 SQL DDL 语句，包括 CREATE TABLE、ALTER TABLE、RLS 策略等
- `--name <迁移名称>` (必需)：如 create_messages_table
- `--changes <变更说明>` (必需)：Markdown 格式阅读友好的描述本次变更内容，应包含表结构、字段说明等

**示例**：
```bash
# 1. 创建消息表
meoo-cli cloud migrate --sql "
CREATE TABLE messages (
  id SERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);" --name "create_messages_table" --changes "创建 **messages** 表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | SERIAL | 主键，自增 |
| content | TEXT | 消息内容 |
| created_at | TIMESTAMPTZ | 创建时间 |"

# 2. 启用 RLS 并添加访问策略
meoo-cli cloud migrate --sql "
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

CREATE POLICY anon_select_messages ON messages
  FOR SELECT
  USING (true);

CREATE POLICY anon_insert_messages ON messages
  FOR INSERT
  WITH CHECK (true);
" --name "add_messages_rls" --changes "为 **messages** 表启用 RLS 并添加匿名访问策略

| 策略名 | 操作 | 条件 | 说明 |
|--------|------|------|------|
| anon_select_messages | SELECT | USING (true) | 任何人都能读取消息 |
| anon_insert_messages | INSERT | WITH CHECK (true) | 任何人都能发送消息 |

```

### cloud query - 数据查询操作

**说明**：执行 SELECT 查询、INSERT/UPDATE/DELETE 数据操作、数据验证和调试，不可用于 DDL

**参数说明**：
- `--sql <SQL语句>` (必需)：要执行的 SQL DML 语句，支持 SELECT、INSERT、UPDATE、DELETE 操作

**示例**：
```bash
meoo-cli cloud query --sql "SELECT * FROM users LIMIT 10"
meoo-cli cloud query --sql "INSERT INTO users (name) VALUES ('张三')"
```

### cloud tables - 查看表结构

**说明**：列出所有表及其结构、字段定义和约束

**示例**：
```bash
meoo-cli cloud tables
```

### cloud status - 查看云服务状态

**说明**：查询当前项目云服务实例状态和 Supabase 的基本信息，确认服务是否正常运行

**示例**：
```bash
meoo-cli cloud status
```

### deploy-function - 部署函数

**前置条件**：MUST 先 Read `skills/meoo-cloud/references/edge-functions.md`，了解函数结构和环境变量后再部署。

**说明**：部署 Edge Function 到 Meoo Cloud，每次代码修改后必须重新部署

**参数说明**：
- `-n, --name <函数名称>` (必需)：要部署的 Edge Function 名称，需与 functions/ 目录下的文件夹名称一致
- `-j, --jwt <布尔值>` (可选)：是否启用 JWT 身份验证，默认为 true。设置为 false 时允许匿名访问

**示例**：
```bash
meoo-cli cloud deploy-function -n my-function
meoo-cli cloud deploy-function -n my-function -j false
```

### delete-function - 删除函数

**说明**：删除已部署的 Edge Function

**参数说明**：
- `-n, --name <函数名称>` (必需)：要删除的 Edge Function 名称

**示例**：
```bash
meoo-cli cloud delete-function -n my-function
```

### list-functions - 查看函数和环境变量

**说明**：列出已部署的 Edge Functions，显示可用的环境变量和 secrets

**示例**：
```bash
meoo-cli cloud list-functions
```