cloudcc-cli 2.3.1 → 2.3.2

package/src/user/docs/devguide.md

@@ -0,0 +1,634 @@
+# CloudCC 用户使用总结
+
+用户（User）是 CloudCC 系统的登录账号，用于访问系统资源和执行业务操作。
+
+---
+
+## 快速开始（CLI 命令）
+
+### 支持的用户操作
+
+| 操作 | 说明 |
+|------|------|
+| `create` | 创建新用户 |
+| `get` | 查询用户列表 |
+| `view` | 查看单个用户详情 |
+| `update` | 编辑/禁用用户 |
+| `delete` | 删除用户 |
+
+---
+
+## CLI 命令详解
+
+### 创建用户
+
+创建一个新的 CloudCC 用户。
+
+```bash
+cc create user <path> <userName> <profileId> [email]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `path` | 是 | 项目路径，`.` 表示当前目录 |
+| `userName` | 是 | 用户名称 |
+| `profileId` | 是 | 关联简档 ID |
+| `email` | 否 | 用户邮箱 |
+
+**示例：**
+
+```bash
+# 创建用户
+cc create user . "张三" a0I9D000000XXXXUAI
+
+# 创建带邮箱的用户
+cc create user . "李四" a0I9D000000XXXXUAI "lisi@example.com"
+```
+
+---
+
+### 查询用户列表
+
+获取当前环境中的所有用户列表。
+
+```bash
+cc get user <projectPath> [encodedCondJson]
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `encodedCondJson` | 否 | URI 编码后的查询条件 JSON |
+
+**查询条件参数：**
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `start` | number | 否 | 起始位置，默认 0 |
+| `limit` | number | 否 | 每页条数，默认 30 |
+| `viewId` | string | 否 | 视图 ID，不传则自动获取"全部"视图 |
+| `keyword` | string | 否 | 搜索关键词 |
+
+**自动获取视图逻辑：**
+
+1. 调用 `view/list/getViewList` 接口查询用户对象的所有视图
+2. 优先查找名为"全部"（或"All"）的视图
+3. 如果不存在"全部"视图，使用第一条视图数据
+4. 使用获取到的视图 ID 查询用户列表
+
+**示例：**
+
+```bash
+# 获取所有用户
+cc get user .
+
+# 带查询条件（搜索关键词）
+cc get user . '%7B%22keyword%22%3A%22张三%22%2C%22limit%22%3A50%7D'
+
+# 分页查询
+cc get user . '%7B%22start%22%3A0%2C%22limit%22%3A30%7D'
+```
+
+---
+
+### 查看单个用户详情
+
+获取指定用户的详细信息。
+
+```bash
+cc view user <projectPath> <userId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `userId` | 是 | 用户 ID |
+
+**示例：**
+
+```bash
+# 查看用户详情
+cc view user . 00520260C00C6FEfsMnT
+```
+
+---
+
+### 编辑/禁用用户
+
+编辑用户信息或禁用/启用用户。
+
+```bash
+cc update user <projectPath> <userDataJson>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `userDataJson` | 是 | 用户数据 JSON 字符串（需 URI 编码）|
+
+**userDataJson 关键字段说明：**
+
+| 字段名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `id` | string | 是 | 用户 ID |
+| `loginName` | string | 是 | 登录名（邮箱）|
+| `lastName` | string | 否 | 姓 |
+| `alias` | string | 否 | 别名 |
+| `email` | string | 否 | 邮箱 |
+| `mobile` | string | 否 | 手机 |
+| `phone` | string | 否 | 电话 |
+| `title` | string | 否 | 职务 |
+| `department` | string | 否 | 部门 |
+| `company` | string | 否 | 公司 |
+| `profileId` | string | 否 | 简档 ID |
+| `role` | string | 否 | 角色 ID |
+| `manager` | string | 否 | 上级 ID |
+| `isusing` | string | 否 | 是否启用：`true`/`false` |
+| `userlicence` | string | 否 | 用户许可证 |
+| `usertimezone` | string | 否 | 时区，如 `G20` |
+| `currency` | string | 否 | 货币，如 `USD` |
+| `languageLocaleKey` | string | 否 | 语言，如 `zh` |
+
+**示例：**
+
+```bash
+# 禁用用户（将 isusing 设为 false）
+cc update user . '%7B%22id%22%3A%2200520260C00C6FEfsMnT%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22false%22%7D'
+
+# 启用用户（将 isusing 设为 true）
+cc update user . '%7B%22id%22%3A%2200520260C00C6FEfsMnT%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22true%22%7D'
+
+# 修改用户信息
+cc update user . '%7B%22id%22%3A%2200520260C00C6FEfsMnT%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22lastName%22%3A%22%E5%BC%A0%E4%B8%89%22%2C%22mobile%22%3A%2213800138000%22%7D'
+```
+
+---
+
+### 删除用户
+
+删除指定的用户。
+
+```bash
+cc delete user <projectPath> <userId>
+```
+
+**参数说明：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `projectPath` | 否 | 项目路径，默认当前目录 |
+| `userId` | 是 | 用户 ID |
+
+**示例：**
+
+```bash
+# 删除指定用户
+cc delete user . 00520260C00C6FEfsMnT
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：为新员工创建 CloudCC 账号
+
+```bash
+# 1. 确认项目已初始化（有 cloudcc-cli.config.js）
+cat cloudcc-cli.config.js
+
+# 2. 查询可用简档，确定要分配的权限
+cc get profile .
+
+# 3. 创建新用户
+cc create user . "王五" a0I9D000000XXXXUAI "wangwu@example.com"
+
+# 4. 验证用户创建成功
+cc get user .
+
+# 5. 查看用户详情
+cc view user . <userId>
+
+# 6. 如需禁用用户
+cc update user . '%7B%22id%22%3A%22<userId>%22%2C%22loginName%22%3A%22wangwu%40example.com%22%2C%22isusing%22%3A%22false%22%7D'
+
+# 7. 如需删除
+cc delete user . <userId>
+```
+
+### 场景：批量查询和禁用用户
+
+```bash
+# 1. 查询用户列表（带关键词搜索）
+cc get user . '%7B%22keyword%22%3A%22test%22%7D'
+
+# 2. 查看特定用户详情
+cc view user . 00520260C00C6FEfsMnT
+
+# 3. 禁用该用户
+cc update user . '%7B%22id%22%3A%2200520260C00C6FEfsMnT%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22false%22%7D'
+```
+
+---
+
+## API 接口详情
+
+### 什么是用户？
+
+**用户（User）** 是 CloudCC 系统的登录账号，每个用户必须关联一个简档以确定其权限范围。
+
+### 核心属性
+
+| 属性 | 说明 | 示例 |
+|------|------|------|
+| **ID（id）** | 用户唯一标识 | `00520260C00C6FEfsMnT` |
+| **登录名（loginName）** | 用户登录邮箱 | `zhangsan@example.com` |
+| **姓名（lastName）** | 用户显示名称 | `张三` |
+| **简档（profileId）** | 关联的简档 ID | `aaa2025EA1EC76ARe61f` |
+| **角色（role）** | 关联的角色 ID | `2025183834EA349bLUaB` |
+| **状态（isusing）** | 是否启用 | `true` / `false` |
+| **创建时间** | 用户创建时间戳 | `1757993089000` |
+
+---
+
+## 一、查询用户列表
+
+### 1.1 接口说明
+
+查询用户列表采用两步流程：
+
+1. **获取视图列表**：调用 `view/list/getViewList` 获取用户对象的视图列表
+2. **查询用户数据**：使用获取到的视图 ID 调用 `usermange/queryUserList`
+
+### 1.2 获取视图列表
+
+**接口**: `POST /api/view/list/getViewList`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `objId` | string | 是 | 对象 ID，用户对象固定为 `"user"` |
+
+**返回数据**：
+
+视图列表数组，每条记录包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` / `viewId` | string | 视图唯一标识 |
+| `name` / `viewName` | string | 视图名称 |
+| `label` | string | 视图显示标签 |
+
+**视图选择逻辑**：
+
+- 优先选择名称为 `"全部"` 或 `"All"` 的视图
+- 如不存在，使用列表中的第一条视图
+
+### 1.3 查询用户数据
+
+**接口**: `POST /api/usermange/queryUserList`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `start` | number | 否 | 起始位置，默认 0 |
+| `limit` | number | 否 | 每页条数，默认 30 |
+| `viewId` | string | 是 | 视图 ID |
+| `keyword` | string | 否 | 搜索关键词 |
+
+**返回数据**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功",
+  "data": {
+    "list": [
+      {
+        "id": "00520260C00C6FEfsMnT",
+        "loginName": "zhangsan@example.com",
+        "lastName": "张三",
+        "email": "zhangsan@example.com",
+        "isusing": "true",
+        "profileId": "aaa2025EA1EC76ARe61f",
+        "role": "2025183834EA349bLUaB",
+        "createdate": 1757993089000
+      }
+    ],
+    "total": 100
+  }
+}
+```
+
+---
+
+## 二、查询单个用户详情
+
+### 2.1 接口说明
+
+**接口**: `POST /api/usermange/viewUser`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `userId` | string | 是 | 用户 ID |
+
+**返回字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 用户唯一标识 |
+| `loginName` | string | 登录名（邮箱）|
+| `lastName` | string | 姓 |
+| `alias` | string | 别名 |
+| `email` | string | 邮箱 |
+| `mobile` | string | 手机 |
+| `phone` | string | 电话 |
+| `title` | string | 职务 |
+| `department` | string | 部门 |
+| `company` | string | 公司 |
+| `profileId` | string | 关联简档 ID |
+| `role` | string | 角色 ID |
+| `manager` | string | 上级用户 ID |
+| `isusing` | string | 是否启用：`true`/`false` |
+| `userlicence` | string | 用户许可证 |
+| `usertimezone` | string | 时区 |
+| `currency` | string | 货币 |
+| `languageLocaleKey` | string | 语言 |
+| `createdate` | number | 创建时间（时间戳）|
+| `lastmodifydate` | number | 最后修改时间（时间戳）|
+
+**返回示例**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功",
+  "data": {
+    "id": "00520260C00C6FEfsMnT",
+    "loginName": "zhangsan@example.com",
+    "lastName": "张三",
+    "alias": "",
+    "email": "zhangsan@example.com",
+    "mobile": "13800138000",
+    "phone": "",
+    "title": "经理",
+    "department": "技术部",
+    "company": "CloudCC",
+    "profileId": "aaa2025EA1EC76ARe61f",
+    "role": "2025183834EA349bLUaB",
+    "manager": "0052026F0E7C7A9kKjCz",
+    "isusing": "true",
+    "userlicence": "Cloudcc 许可",
+    "usertimezone": "G20",
+    "currency": "USD",
+    "languageLocaleKey": "zh",
+    "createdate": 1757993089000,
+    "lastmodifydate": 1757993089000
+  }
+}
+```
+
+---
+
+## 三、编辑/禁用用户
+
+### 3.1 接口说明
+
+**接口**: `POST /api/usermange/editandsave`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `dataJson` | string | 是 | 用户数据 JSON 字符串 |
+
+**dataJson 字段说明**（必填字段必须包含）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 用户 ID |
+| `loginName` | string | 是 | 登录名 |
+| `isusing` | string | 否 | 是否启用：`true`/`false` |
+| `lastName` | string | 否 | 姓 |
+| `alias` | string | 否 | 别名 |
+| `email` | string | 否 | 邮箱 |
+| `mobile` | string | 否 | 手机 |
+| `phone` | string | 否 | 电话 |
+| `title` | string | 否 | 职务 |
+| `department` | string | 否 | 部门 |
+| `company` | string | 否 | 公司 |
+| `profileId` | string | 否 | 简档 ID |
+| `role` | string | 否 | 角色 ID |
+| `manager` | string | 否 | 上级 ID |
+| `userlicence` | string | 否 | 用户许可证 |
+| `usertimezone` | string | 否 | 时区 |
+| `currency` | string | 否 | 货币 |
+| `languageLocaleKey` | string | 否 | 语言 |
+| `isKnowledgeUser` | string | 否 | 是否知识库用户 |
+| `isteam` | string | 否 | 是否是团队 |
+| `isforecast` | string | 否 | 是否预测用户 |
+| `partneruser` | string | 否 | 是否合作伙伴用户 |
+| `wxzhbdzt` | string | 否 | 微信账号绑定状态 |
+
+**请求示例**：
+
+```javascript
+{
+  "dataJson": "{\"loginName\":\"testdemo@cloudcc.com\",\"isusing\":\"false\",\"lastName\":\"测试\",\"email\":\"testdemo@cloudcc.com\",\"id\":\"00520260C00C6FEfsMnT\"}"
+}
+```
+
+**返回示例**：
+
+```javascript
+{
+  "result": true,
+  "returnInfo": "操作成功"
+}
+```
+
+### 3.2 禁用用户流程
+
+1. 先通过 `viewUser` 接口获取用户完整信息
+2. 将 `isusing` 字段改为 `"false"`
+3. 调用 `editandsave` 接口提交修改
+
+### 3.3 启用用户流程
+
+1. 先通过 `viewUser` 接口获取用户完整信息
+2. 将 `isusing` 字段改为 `"true"`
+3. 调用 `editandsave` 接口提交修改
+
+---
+
+## 四、创建用户
+
+### 4.1 接口说明
+
+**接口**: `POST /api/user/createUser`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `name` | string | 是 | 用户名称 |
+| `email` | string | 否 | 用户邮箱 |
+| `profileId` | string | 是 | 关联简档 ID |
+
+---
+
+## 五、删除用户
+
+### 5.1 删除前检查
+
+- [ ] 是否有未完成的重要业务数据
+- [ ] 是否是系统管理员（建议先转移管理员权限）
+- [ ] 级联影响确认
+
+### 5.2 删除流程
+
+**接口**: `POST /api/user/deleteUser`
+
+**请求参数**：
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `id` | string | 是 | 用户 ID |
+
+---
+
+## 六、用户数据结构
+
+### 6.1 列表数据格式
+
+```javascript
+{
+  id: "00520260C00C6FEfsMnT",
+  loginName: "zhangsan@example.com",
+  lastName: "张三",
+  email: "zhangsan@example.com",
+  isusing: "true",
+  profileId: "aaa2025EA1EC76ARe61f",
+  role: "2025183834EA349bLUaB",
+  createdate: 1757993089000
+}
+```
+
+### 6.2 完整数据格式
+
+```javascript
+{
+  id: "00520260C00C6FEfsMnT",
+  loginName: "zhangsan@example.com",
+  lastName: "张三",
+  alias: "",
+  email: "zhangsan@example.com",
+  mobile: "13800138000",
+  phone: "",
+  fax: "",
+  title: "经理",
+  department: "技术部",
+  company: "CloudCC",
+  profileId: "aaa2025EA1EC76ARe61f",
+  role: "2025183834EA349bLUaB",
+  manager: "0052026F0E7C7A9kKjCz",
+  isusing: "true",
+  userlicence: "Cloudcc 许可",
+  usertimezone: "G20",
+  currency: "USD",
+  languageLocaleKey: "zh",
+  isKnowledgeUser: "false",
+  isteam: "false",
+  isforecast: "false",
+  partneruser: "false",
+  wxzhbdzt: "false",
+  createdate: 1757993089000,
+  lastmodifydate: 1757993089000
+}
+```
+
+---
+
+## 七、最佳实践
+
+### 命名规范
+
+| 项目 | 规范 | 示例 |
+|------|------|------|
+| 用户名 | 使用真实姓名 | `张三`、`李四` |
+| 邮箱 | 使用企业邮箱 | `zhangsan@company.com` |
+| 登录名 | 使用邮箱格式 | `zhangsan@company.com` |
+
+### 权限分配
+
+- **按需分配**：根据用户角色分配合适的简档
+- **定期审查**：定期检查用户权限是否合理
+- **离职处理**：及时禁用或删除离职员工账号
+
+### 用户状态管理
+
+- **启用**（`isusing: "true"`）：用户可以正常登录和使用系统
+- **禁用**（`isusing: "false"`）：用户无法登录，但数据保留
+- **删除**：永久删除用户记录
+
+### 推荐操作流程
+
+1. 新员工入职：创建用户 → 分配简档和角色 → 启用
+2. 员工离职：禁用用户 → 转移数据所有权 → 删除用户
+3. 权限变更：查看用户详情 → 修改简档/角色 → 更新用户
+
+---
+
+## 八、常见问题
+
+**Q: 用户创建后无法登录？**
+
+A: 检查以下几点：
+1. 用户状态 `isusing` 是否为 `"true"`
+2. 关联的简档是否有登录权限
+3. 邮箱格式是否正确
+
+**Q: 如何禁用用户？**
+
+A: 调用 `cc update user` 命令，传入 `isusing: "false"` 参数：
+```bash
+cc update user . '%7B%22id%22%3A%22<userId>%22%2C%22loginName%22%3A%22<email>%22%2C%22isusing%22%3A%22false%22%7D'
+```
+
+**Q: 如何启用已禁用的用户？**
+
+A: 调用 `cc update user` 命令，传入 `isusing: "true"` 参数：
+```bash
+cc update user . '%7B%22id%22%3A%22<userId>%22%2C%22loginName%22%3A%22<email>%22%2C%22isusing%22%3A%22true%22%7D'
+```
+
+**Q: 可以修改用户的简档吗？**
+
+A: 可以，调用 `cc update user` 命令修改 `profileId` 字段。
+
+**Q: 删除用户会影响数据吗？**
+
+A: 删除用户通常不会删除其创建的业务数据，但建议先确认数据归属问题。
+
+**Q: 如何查看用户的完整信息？**
+
+A: 调用 `cc view user` 命令，传入 `userId` 参数获取详情。
+
+**Q: 如何查看用户列表？**
+
+A: 调用 `cc get user` 命令，支持关键词搜索和分页。
+
+---
+
+*文档版本：1.1 | 最后更新：2026-03-26*