# CloudCC Project 文档（全量）

## 开发环境搭建

# CloudCC CRM 前后端开发环境搭建指南

---

## 1. 前置条件与总体说明

- 适用人群：CloudCC 前端组件、客户端脚本、后端类/触发器/定时器等二次开发工程师。
- **硬性要求**
  - 必须全局安装 **`cloudcc-cli`**（见第 3 节），否则无法使用 `cloudcc` 命令行与依赖 CLI 的发布/拉取等能力。
  - 必须有一个**工程根目录**（任意文件夹即可），用于存放二开代码与配置；**不强制**使用 `cloudcc create project` 初始化模板。
  - 工程根目录下**必须**提供 **`cloudcc-cli.config.json`**，用于配置开发者密钥、安全标记及当前环境（`use`）。CLI 会按 `cloudcc doc config devguide` 所述顺序解析配置。
- **工作方式（任选，可组合）**
  - 在终端进入工程根目录，直接执行 `cloudcc <action> <resource> ...`。
  - 使用 **VS Code**、**Cursor** 等编辑器打开同一工程根目录进行编辑与调试；可选安装 CloudCC 插件；在 **Cursor** 中建议安装内置 **Agent Skill**（见第 5 节）。
- 建议流程：
  1. 安装 Node 与 npm，并切换 npm 源
  2. 全局安装 `cloudcc-cli`
  3. 准备工程目录，并在根目录创建/维护 `cloudcc-cli.config.json`
  4. （可选）安装 VS Code / Cursor、CloudCC 插件；在 Cursor 中执行 `cloudcc install skill` 安装二开 Skill
  5. （可选）使用 `cloudcc create project` 拉取模板并 `npm i` / `npm run serve` 做前端本地调试
  6. 在 CRM 中获取开发者密钥与安全标记，写入配置文件
  7. 视情况配置私有云与多环境参数

---

## 2. 安装 Node 与 npm 源配置

### 2.1 安装 Node

- **推荐版本**：`v20.19.5`以上（官方示例）
- **下载地址**：
  - Node 官方历史版本下载：`https://nodejs.org/download/release/v20.19.5/`
- **建议**：使用 `nvm` 等 Node 多版本管理工具切换版本，保证与 CloudCC 官方推荐版本一致。

安装完成后，在终端中验证：

```bash
node -v
```

### 2.2 切换 npm 源到阿里镜像

为加速依赖安装，建议设置 npm 源为阿里镜像：

```bash
npm config set registry https://registry.npmmirror.com
```

验证是否设置成功：

```bash
npm config get registry
```

返回 `https://registry.npmmirror.com/` 即表示生效。

---

## 3. 安装 cloudcc-cli（全局）

### 3.1 Windows 用户

在命令行中执行：

```bash
npm install -g cloudcc-cli
```

### 3.2 macOS 用户

在终端中执行（需要 sudo）：

```bash
sudo npm install -g cloudcc-cli
```

### 3.3 验证安装

查看全局依赖列表，确认 `cloudcc-cli` 已安装：

```bash
npm ls -g --depth=0
```

在 macOS 上如需查看 sudo 下的全局包，可使用：

```bash
sudo npm ls -g --depth=0
```

---

## 4. 开发工具配置：安装 VS Code 与 CloudCC 插件（可选）

### 4.1 安装 VS Code

- 下载地址：`https://code.visualstudio.com/download`
- 安装完成后，用 VS Code 作为主要开发编辑器。

### 4.2 安装 CloudCC 插件

1. 打开 VS Code，点击左侧扩展（Extensions）图标
2. 搜索 `CloudCC`
3. 选择官方 CloudCC 插件并安装

> 若在 Cursor 中开发，可参考 CloudCC 帮助中心中关于「常用工具 / Cursor 安装方式」的说明：`https://help.cloudcc.cn/product03/chang-yong-gong-ju/`

---

## 5. 安装 Cursor Agent Skill（可选）

在已**全局安装 `cloudcc-cli`**（第 3 节）的前提下，可将包内自带的 **`cloudcc-dev-skill`** 安装到 Cursor 的 skills 目录，便于 Agent 按 CloudCC 二开规范引用 `cloudcc doc` 与模块清单。

**用户级（推荐，所有工程可用）**：安装到 `~/.cursor/skills/cloudcc-dev-skill`

```bash
cloudcc install skill
```

**仅当前工程**：安装到「当前工作目录」下的 `.cursor/skills/cloudcc-dev-skill`（请先 `cd` 到工程根目录）

```bash
cloudcc install skill project
```

或使用同义参数：

```bash
cloudcc install skill --project
```

说明：

- 需已能直接在终端执行 `cloudcc`（全局 npm bin 在 `PATH` 中）。
- 安装完成后如未看到 Skill，可重启 Cursor 或重新加载窗口。
- Skill 内容与包内 `cloudcc-dev-skill/` 目录一致（含 `SKILL.md`、`config.json`）。

---

## 6. 项目目录、运行方式与模板项目（可选）

### 6.1 工程目录与配置文件（必须）

- 使用**任意文件夹**作为 CloudCC 二开工程根目录（自行新建即可，**不必**先跑 `cloudcc create project`）。
- 工程根目录下**必须**存在 **`cloudcc-cli.config.json`**，用于写入安全标记、`CloudCCDev`、当前环境名 `use` 等（获取方式见第 7 节）。请勿将真实密钥提交到 Git（建议在 `.gitignore` 中忽略该文件或使用私密副本）。
- 在终端中执行 CLI 时，**当前工作目录**应位于该工程根目录（或能按 `config` 模块规则解析到该文件），否则部分命令会提示无效配置。

### 6.2 运行与开发工具（CLI / 编辑器）

- **命令行**：在工程根目录执行 `cloudcc --version` 确认 CLI 可用，再使用 `cloudcc doc`、`cloudcc get`、`cloudcc publish` 等子命令。
- **VS Code / Cursor**：用「打开文件夹」指向同一工程根目录即可编辑 `classes/`、`triggers/`、`schedule/` 等；与是否在终端使用 CLI **互不排斥**。
- 是否安装 CloudCC 插件、是否安装 Cursor Skill（第 5 节）均为**可选**，不影响 `cloudcc-cli` 作为命令行工具的基本使用。

### 6.3 模板项目与本地前端服务（可选）

若需要官方脚手架（含 `npm run serve` 等前端本地调试），可在终端执行：

```bash
cd ~/Documents
cloudcc create project demo1
```

`demo1` 为示例项目名，可替换；若使用 `.` 表示在当前目录创建。

1. 使用 VS Code 或 Cursor 打开创建出的项目目录。
2. 在编辑器中打开终端，在项目根目录安装依赖：

```bash
npm i
```

3. 启动本地开发服务器：

```bash
npm run serve
```

4. 在浏览器访问：

```text
http://localhost:8080/
```

看到模板页面即表示模板附带的前端本地环境已就绪。若未使用模板，仅需保证第 6.1 节的目录与 `cloudcc-cli.config.json` 即可进行类、触发器等后端扩展开发。

---

## 7. 获取并配置开发者密钥

> 目的：将本地工程与指定 CloudCC 环境（Org）关联。需使用具备「开发者权限」的账号在 CRM 中获取密钥和安全标记，并写入工程根目录下的 **`cloudcc-cli.config.json`**。

### 7.1 创建开发者账号

前提：拥有系统管理员账号。

1. 使用系统管理账号登录 CRM
2. 点击右上角齿轮，进入后台设置
3. 进入 `用户管理 → 新建` 创建新用户
4. 为新用户分配**具有开发者权限**的简档：
   - 路径：`管理用户 → 简档 → 对应简档 → 普通用户权限 → 代码管理`
   - 确认「代码管理」权限已开启

### 7.2 获取开发者密钥（CloudCCDev）

1. 使用开发者账号登录 CRM
2. 点击右上角齿轮，进入后台设置
3. 路径：`用户及控制 → 安全性控制 → 连接的应用程序 → 新建`
4. 填写：
   - 连接的应用程序名称
   - API 名称
   - 联系人电子邮件
5. 创建完成后，在详情页中找到 `CloudCC Dev`，点击后面的复制按钮，得到开发者密钥，妥善保管。

### 7.3 获取安全标记（safetyMark）

1. 使用同一开发者账号登录 CRM
2. 路径：`常规 → 个人设置 → 重置我的安全标记`
3. 点击后，安全标记会发送到用户邮箱，在邮箱中查收并记录。

### 7.4 配置 `cloudcc-cli.config.json`

在**工程根目录**创建或编辑 `cloudcc-cli.config.json`（与旧版 `cloudcc-cli.config.js` 语义一致，以下为 **JSON** 结构示例；字段含义不变）：

```json
{
    "use": "dev",
    "dev": {
        "safetyMark": "Required safety mark",
        "CloudCCDev": "Required developer key"
    },
    "prod": {
        "safetyMark": "Required safety mark",
        "CloudCCDev": "Required developer key"
    }
}
```

若需要覆盖用户名，可在对应环境对象中增加 `"username"` 字段（选填）。

说明：

- `use`：决定当前 CLI 使用哪一套环境配置（如 `"dev"`、`"prod"` 等，键名与下方对象名一致即可）。
- 不要把真实密钥提交到 Git 仓库（应在 `.gitignore` 中忽略该文件或改用本地私密配置流程）。

---

## 8. 私有云与特殊参数配置

### 8.1 私有云标记

在私有云场景下，对应环境对象中需增加 `"version": "private"`：

```json
{
    "use": "dev",
    "dev": {
        "safetyMark": "Required safety mark",
        "CloudCCDev": "Required developer key",
        "version": "private"
    },
    "prod": {
        "safetyMark": "Required safety mark",
        "CloudCCDev": "Required developer key",
        "version": "private"
    }
}
```

可选字段 `username` 如需使用，与第 7.4 节相同，写在对应环境对象内即可。

### 8.2 baseUrl 与网关前缀

示例：在某一环境（如 `dev`）对象内增加网关相关字段（精简自官方文档；值为示例，请按实际环境填写）。

说明：

- `baseUrl`：服务访问地址。国内默认 `https://developer.apis.cloudcc.cn`，海外默认 `https://developer.apis.cloudcc.com`；私有云可在登录 CRM 后，右键 → 检查 → 控制台执行 `$CCDK.CCConfig.getBaseUrl()` 获取。
- `destroyTimeout`：组件进入后台后自动销毁时间（毫秒），如 10 分钟为 `600000`。
- `devSvcDispatch`：开发者平台在网关配置的前缀名；注意 URL 不要以 `/` 结尾。
- `apiSvcPrefix` / `setupSvcPrefix`：分别为 api-service-svc、setup-svc 访问网关前缀。

```json
{
    "use": "dev",
    "dev": {
        "safetyMark": "xxx",
        "CloudCCDev": "xxx",
        "baseUrl": "http://xxx",
        "destroyTimeout": 600000,
        "devSvcDispatch": "/devconsole",
        "apiSvcPrefix": "/xxx",
        "setupSvcPrefix": "/xxx"
    }
}
```

`prod` 等其他环境如需相同网关字段，在对应环境对象内按实际值增删即可。

---

## 9. 多环境配置示例

`cloudcc-cli.config.json` 支持配置多个环境，通过顶层 `use` 字段选择当前使用的环境：

```json
{
    "use": "dev",
    "dev": {
        "safetyMark": "xxx",
        "CloudCCDev": "xxx"
    },
    "prod": {
        "safetyMark": "xxx",
        "CloudCCDev": "xxx"
    }
}
```

建议：

- 本地调试使用 `dev` 或测试环境
- 合并上线前在 `uat` 或类似环境进行回归验证
- 生产配置应仅在 CI/CD 或受控环境中可见，避免在开发机上长期保存生产密钥

---

## 10. 开发工具与代码规范补充

### 10.1 推荐开发工具组合

- 编辑器：**VS Code**、**Cursor** 等（可选配合 CloudCC 扩展；Cursor 可再执行 `cloudcc install skill`）
- 命令行：全局 **`cloudcc-cli`**（必须）
- 包管理：npm（建议配置阿里源；仅在使用带 `package.json` 的模板或前端工程时需要）
- 版本控制：Git

官方文档中的推荐插件示例：

- `ESLint`：代码规范检查
- `Vetur` / 对应 Vue 插件：Vue 语法高亮与提示
- `GitLens`：Git 历史与责任人查看
- `Live Server`：静态资源快速预览（如需）

### 10.2 代码规范（简要）

详细 JS/CSS/注释规范可参考官方文档「开发规范」小节，这里仅保留关键点：

- 启用 ESLint 作为基础校验
- 在项目根目录维护 `README.md`，记录每次发布版本与更新内容
- Vue 组件中使用 `scoped` 样式或统一引入的样式变量文件，避免污染全局

---