cloudcc-cli 2.3.2 → 2.3.4

package/src/user/docs/devguide.md

@@ -1,12 +1,6 @@
-# CloudCC 用户使用总结
+# CloudCC 用户 CLI 命令说明
 
-用户（User）是 CloudCC 系统的登录账号，用于访问系统资源和执行业务操作。
-
----
-
-## 快速开始（CLI 命令）
-
-### 支持的用户操作
+## 支持的命令
 
 | 操作 | 说明 |
 |------|------|
@@ -16,14 +10,10 @@
 | `update` | 编辑/禁用用户 |
 | `delete` | 删除用户 |
 
----
-
 ## CLI 命令详解
 
 ### 创建用户
 
-创建一个新的 CloudCC 用户。
-
 ```bash
 cc create user <path> <userName> <profileId> [email]
 ```
@@ -47,12 +37,8 @@ cc create user . "张三" a0I9D000000XXXXUAI
 cc create user . "李四" a0I9D000000XXXXUAI "lisi@example.com"
 ```
 
----
-
 ### 查询用户列表
 
-获取当前环境中的所有用户列表。
-
 ```bash
 cc get user <projectPath> [encodedCondJson]
 ```
@@ -66,19 +52,11 @@ cc get user <projectPath> [encodedCondJson]
 
 **查询条件参数：**
 
-| 参数名 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| `start` | number | 否 | 起始位置，默认 0 |
-| `limit` | number | 否 | 每页条数，默认 30 |
-| `viewId` | string | 否 | 视图 ID，不传则自动获取"全部"视图 |
-| `keyword` | string | 否 | 搜索关键词 |
-
-**自动获取视图逻辑：**
-
-1. 调用 `view/list/getViewList` 接口查询用户对象的所有视图
-2. 优先查找名为"全部"（或"All"）的视图
-3. 如果不存在"全部"视图，使用第一条视图数据
-4. 使用获取到的视图 ID 查询用户列表
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| `start` | number | 起始位置，默认 0 |
+| `limit` | number | 每页条数，默认 30 |
+| `keyword` | string | 搜索关键词 |
 
 **示例：**
 
@@ -88,547 +66,57 @@ 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>
 ```
 
-**参数说明：**
+**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` |
+| 字段名 | 说明 |
+|--------|------|
+| `id` | 用户 ID（必填）|
+| `loginName` | 登录名（必填）|
+| `isusing` | 是否启用：`true`/`false` |
+| `lastName` | 姓 |
+| `email` | 邮箱 |
+| `mobile` | 手机 |
+| `profileId` | 简档 ID |
+| `role` | 角色 ID |
 
 **示例：**
 
 ```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'
+# 禁用用户
+cc update user . '%7B%22id%22%3A%22xxx%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'
+# 启用用户
+cc update user . '%7B%22id%22%3A%22xxx%22%2C%22loginName%22%3A%22test%40cloudcc.com%22%2C%22isusing%22%3A%22true%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*