@sokeai/cli 1.0.41 → 1.0.53

package/skills/soke-assign/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: soke-assign
+summary: 授客学堂指派管理（创建指派/查询指派/查询部门/查询用户），支持课程、考试、学习地图等多种模块的指派操作
+version: 1.0.0
+description: "授客学堂指派管理：通用的学习资源指派系统，支持将课程、考试、学习地图等学习资源指派给部门、用户、群组、职位或角色。提供完整的指派生命周期管理，包括创建指派、查询指派列表、查询可用部门和用户。支持必修和选修两种学习类型，支持批量指派和消息通知。当用户需要为部门或用户分配学习任务时使用。"
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli assign --help"
+---
+
+# 指派管理 (assign)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+
+## ⚠️ 使用前提
+
+本 skill 基于 **soke-cli** 命令行工具，使用前必须完成以下步骤：
+
+1. **安装 soke-cli**：确保已安装 `@sokeai/cli` NPM 包或 soke-cli 二进制文件
+2. **用户登录授权**：运行 `soke-cli auth login` 完成 OAuth 设备码授权流程，获取用户访问令牌
+
+**快速开始**：
+```bash
+# 1. 用户登录授权（必须）
+soke-cli auth login
+
+# 2. 验证登录状态
+soke-cli config show
+```
+
+未完成登录授权将无法调用任何指派管理相关的 API。详细的认证配置说明请参考 [soke-shared/SKILL.md](../soke-shared/SKILL.md)。
+
+## 核心概念
+
+- **Assign（指派）**: 将学习资源分配给特定对象的操作，通过 `uuid` 标识
+- **Module（模块）**: 学习资源类型，如 course（课程）、exam（考试）、learning_map（学习地图）
+- **Target（目标）**: 被指派的学习资源，通过 `target_id` 标识
+- **AssignType（指派类型）**: 指派对象类型，包括 dept（部门）、user（用户）、group（群组）、position（职位）、role（角色）
+- **LearnType（学习类型）**: required（必修）或 optional（选修）
+
+## 支持的模块
+
+- **course** - 课程指派
+- **exam** - 考试指派
+- **learning_map** - 学习地图指派
+- 其他模块（根据系统配置）
+
+## 支持的指派类型
+
+- **dept（部门）**: 部门下所有成员都可以学习
+- **user（用户）**: 只有指定的用户可以学习
+
+## 可用命令
+
+### 1. 查询部门列表
+
+查询可用的部门列表，用于指派前选择目标部门。
+
+```bash
+soke-cli assign +list-departments [flags]
+```
+
+**参数**:
+- `--page` - 页码（默认：1）
+- `--limit` - 每页数量（默认：10）
+- `--parent-id` - 父部门ID（默认：1，查询顶级部门）
+- `--keyword` - 搜索关键词（部门名称）
+
+**示例**:
+```bash
+# 查询顶级部门
+soke-cli assign +list-departments
+
+# 搜索部门
+soke-cli assign +list-departments --keyword "研发"
+
+# 查询子部门
+soke-cli assign +list-departments --parent-id "130110584"
+```
+
+**输出信息**:
+- 部门ID（用于创建指派）
+- 部门名称
+- 父部门ID
+- 成员数量
+- 子部门数量
+
+---
+
+### 2. 查询用户列表
+
+查询可用的用户列表，用于指派前选择目标用户。
+
+```bash
+soke-cli assign +list-users [flags]
+```
+
+**参数**:
+- `--dept-id` - 部门ID
+- `--keyword` - 搜索关键词
+- `--search-target` - 搜索目标：name（姓名）/phone（手机号）/job_number（工号），默认：name
+- `--is-in` - 是否在权限范围内：0否/1是
+- `--is-new` - 是否新用户：0否/1是（默认：0）
+- `--page` - 页码（默认：1）
+- `--limit` - 每页数量（默认：20）
+
+**示例**:
+```bash
+# 查询所有用户
+soke-cli assign +list-users
+
+# 查询指定部门的用户
+soke-cli assign +list-users --dept-id "130110584"
+
+# 按姓名搜索
+soke-cli assign +list-users --keyword "张三" --search-target "name"
+
+```
+
+**输出信息**:
+- 用户ID（用于创建指派）
+- 姓名
+- 部门ID
+- 职位
+- 工号
+- 在职状态
+
+---
+
+### 3. 创建指派
+
+将学习资源指派给部门、用户、群组、职位或角色。
+
+```bash
+soke-cli assign +create [flags]
+```
+
+**必填参数**:
+- `--module` - 模块类型：course（课程）、exam（考试）、learning_map（学习地图）
+- `--target-id` - 目标ID（如课程ID、考试ID等）
+
+**可选参数**:
+- `--learn-type` - 学习类型：required（必修）、optional（选修），默认：required
+- `--dept-ids` - 部门ID列表，逗号分隔
+- `--dept-names` - 部门名称列表，逗号分隔，与dept-ids对应
+- `--user-ids` - 用户ID列表，逗号分隔
+- `--user-names` - 用户名称列表，逗号分隔，与user-ids对应
+- `--message-content` - 通知消息内容
+- `--message-switch` - 消息开关：0关闭/1开启，默认：1
+
+**示例**:
+```bash
+# 指派课程给部门（必修）
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --dept-ids "130110584" \
+  --dept-names "研发部" \
+  --learn-type "required" \
+  --message-content "新课程已为您安排，请及时学习！"
+
+# 指派课程给用户
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --user-ids "1241453468881932" \
+  --user-names "张三" \
+  --learn-type "required"
+
+# 同时指派给部门和用户
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --dept-ids "130110584,130110585" \
+  --dept-names "研发部,测试部" \
+  --user-ids "1241453468881932" \
+  --user-names "张三" \
+  --learn-type "required"
+
+# 指派考试给部门
+soke-cli assign +create \
+  --module "exam" \
+  --target-id "EXAM-UUID-12345" \
+  --dept-ids "130110584" \
+  --dept-names "研发部" \
+  --learn-type "required"
+
+# 创建选修课指派
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --dept-ids "130110584" \
+  --dept-names "研发部" \
+  --learn-type "optional"
+```
+
+**重要提示**:
+- 至少需要指定一种指派类型（部门或用户）
+- 支持批量指派，使用逗号分隔多个ID和名称
+- ID和名称的顺序要一一对应
+- 默认开启消息通知，可通过 `--message-switch 0` 关闭
+
+---
+
+### 4. 查询指派列表
+
+查询已创建的指派记录。
+
+```bash
+soke-cli assign +list [flags]
+```
+
+**参数**:
+- `--target-id` - 目标ID（筛选特定资源的指派）
+- `--module` - 模块类型：course/exam/learning_map等
+- `--learn-type` - 学习类型：required/optional
+- `--assign-type` - 指派类型：dept/user/group/position/role
+- `--keyword` - 搜索关键词（部门名、用户名等）
+- `--page` - 页码（默认：1）
+- `--limit` - 每页数量（默认：10）
+
+**示例**:
+```bash
+# 查询特定课程的所有指派
+soke-cli assign +list \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271"
+
+# 查询特定课程的部门指派
+soke-cli assign +list \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --assign-type "dept"
+
+# 按关键词搜索
+soke-cli assign +list \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --keyword "研发"
+
+# 查询必修课指派
+soke-cli assign +list \
+  --module "course" \
+  --learn-type "required"
+```
+
+**输出信息**:
+- 指派UUID
+- 指派对象名称
+- 指派类型
+- 目标ID
+- 学习类型
+- 创建时间
+- 创建人
+- 状态信息
+
+---
+
+## 完整工作流
+
+### 场景1：为新员工培训课程创建指派
+
+```bash
+# 步骤1: 查询部门列表，找到目标部门
+soke-cli assign +list-departments --keyword "研发"
+# 输出：部门ID: 130110584, 部门名称: 研发部
+
+# 步骤2: 查询该部门的用户（可选）
+soke-cli assign +list-users --dept-id "130110584"
+# 输出：用户列表
+
+# 步骤3: 创建课程指派
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --dept-ids "130110584" \
+  --dept-names "研发部" \
+  --learn-type "required" \
+  --message-content "新员工培训课程已为您安排，请在一周内完成学习！"
+
+# 步骤4: 验证指派是否成功
+soke-cli assign +list \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271"
+```
+
+### 场景2：为考试创建多维度指派
+
+```bash
+# 同时指派给部门和用户
+soke-cli assign +create \
+  --module "exam" \
+  --target-id "EXAM-UUID-12345" \
+  --dept-ids "130110584,130110585" \
+  --dept-names "研发部,测试部" \
+  --user-ids "1241453468881932" \
+  --user-names "张三" \
+  --learn-type "required" \
+  --message-content "年度考核考试已开放，请按时参加！"
+```
+
+---
+
+## 注意事项
+
+1. **指派前准备**
+   - 确保目标资源已创建（如课程已发布）
+   - 使用 `+list-departments` 和 `+list-users` 查询可用的部门和用户
+   - 记录部门ID和用户ID用于创建指派
+
+2. **批量指派**
+   - 支持同时指派给多个对象
+   - 使用逗号分隔多个ID和名称
+   - ID和名称的顺序要一一对应
+
+3. **必修 vs 选修**
+   - 必修（required）：用户必须完成学习
+   - 选修（optional）：用户可选择性学习
+
+4. **消息通知**
+   - 默认开启消息通知
+   - 可自定义消息内容
+   - 可通过 `--message-switch 0` 关闭通知
+
+5. **权限要求**
+   - 需要具有指派的读写权限
+   - 只能查询和操作权限范围内的部门和用户
+
+---
+
+## 常见问题
+
+### Q1: 如何获取课程ID？
+```bash
+soke-cli course +list-courses --page 1 --limit 10
+```
+
+### Q2: 如何获取部门ID？
+```bash
+soke-cli assign +list-departments --keyword "研发"
+```
+
+### Q3: 如何获取用户ID？
+```bash
+soke-cli assign +list-users --dept-id "1" --keyword "张三"
+```
+
+### Q4: 指派失败怎么办？
+检查以下几点：
+1. 目标资源是否已发布
+2. 部门ID和用户ID是否正确
+3. 是否有足够的权限
+4. module 参数是否正确
+
+### Q5: 可以同时指派给多种类型吗？
+可以！在一次指派中可以同时指定部门、用户、群组、职位和角色。
+
+---
+
+## API 接口
+
+本 skill 使用以下 API 接口：
+
+- `GET /skills/department/list` - 查询部门列表
+- `GET /skills/user/list` - 查询用户列表
+- `POST /skills/assignLog/create` - 创建指派
+- `GET /skills/assignLog/list` - 查询指派列表
+
+详细的 API 文档请参考 [API_PROXY_INTERFACES_2.0.md](../../docs/API_PROXY_INTERFACES_2.0.md)。
+
+---
+
+## 相关 Skills
+
+- **soke-course** - 课程管理，创建和管理课程
+- **soke-exam** - 考试管理，创建和管理考试
+- **soke-learning-profile** - 学习地图管理
+
+---
+
+**版本**: 1.0.0  
+**最后更新**: 2026-05-28