@sokeai/cli 1.0.77 → 1.0.78

package/skills/mono/references/modules/soke-assign/README.md

@@ -0,0 +1,308 @@
+# 授客指派管理 Skill
+
+通用的学习资源指派系统，支持将课程、考试、学习地图等学习资源指派给部门和用户。
+
+## 功能概述
+
+这个 skill 提供了完整的指派管理功能，包括：
+
+- 📋 **部门查询**: 查询可用的部门列表，支持搜索和分页
+- 👥 **用户查询**: 查询可用的用户列表，支持多种搜索方式
+- ✅ **创建指派**: 将学习资源指派给部门或用户
+- 📊 **查询指派**: 查询已创建的指派记录，支持多维度筛选
+
+## 支持的模块
+
+- **course** - 课程指派
+- **exam** - 考试指派
+- **learning_map** - 学习地图指派
+- 其他模块（根据系统配置）
+
+## 支持的指派类型
+
+- **dept（部门）**: 部门下所有成员都可以学习
+- **user（用户）**: 只有指定的用户可以学习
+
+## 快速开始
+
+### 创建课程指派
+
+```bash
+# 1. 查询部门列表，获取部门ID
+soke-cli assign +list-departments --keyword "研发"
+
+# 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"
+```
+
+### 创建考试指派
+
+```bash
+# 指派考试给部门
+soke-cli assign +create \
+  --module "exam" \
+  --target-id "EXAM-UUID-12345" \
+  --dept-ids "130110584" \
+  --dept-names "研发部" \
+  --learn-type "required" \
+  --message-content "年度考核考试已开放，请按时参加！"
+```
+
+## 主要命令
+
+### 查询命令
+| 命令 | 说明 |
+|------|------|
+| `+list-departments` | 查询部门列表（获取部门ID和名称） |
+| `+list-users` | 查询用户列表（获取用户ID和姓名） |
+| `+list` | 查询指派列表 |
+
+### 操作命令
+| 命令 | 说明 |
+|------|------|
+| `+create` | 创建指派 |
+
+## 使用场景
+
+### 场景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
+# 1. 搜索用户
+soke-cli assign +list-users --keyword "张三" --search-target "name"
+# 输出：用户ID: 1241453468881932, 姓名: 张三
+
+# 2. 创建指派
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --user-ids "1241453468881932" \
+  --user-names "张三" \
+  --learn-type "required"
+```
+
+### 场景3: 批量指派给多个部门
+
+```bash
+# 1. 查询多个部门
+soke-cli assign +list-departments --keyword "战区"
+
+# 2. 批量创建指派
+soke-cli assign +create \
+  --module "course" \
+  --target-id "E08464D0-D567-4A01-8FAB-BD41AFFDB271" \
+  --dept-ids "130110584,130110585,130110586" \
+  --dept-names "安徽战区,江苏战区,浙江战区" \
+  --learn-type "required"
+```
+
+### 场景4: 创建多维度指派
+
+```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 "年度考核考试已开放，请按时参加！"
+```
+
+### 场景5: 查询和统计指派情况
+
+```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" \
+  --assign-type "user"
+
+# 按关键词搜索
+soke-cli assign +list \
+  --module "course" \
+  --keyword "研发"
+```
+
+## 参数说明
+
+### 查询部门列表参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --page | int | 否 | 1 | 页码 |
+| --limit | int | 否 | 10 | 每页数量 |
+| --parent-id | string | 否 | 1 | 父部门ID |
+| --keyword | string | 否 | - | 搜索关键词 |
+
+### 查询用户列表参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --dept-id | string | 否 | - | 部门ID |
+| --keyword | string | 否 | - | 搜索关键词 |
+| --search-target | string | 否 | name | 搜索目标：name/phone/job_number |
+| --page | int | 否 | 1 | 页码 |
+| --limit | int | 否 | 20 | 每页数量 |
+
+### 创建指派参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --module | string | 是 | - | 模块类型：course/exam/learning_map |
+| --target-id | string | 是 | - | 目标ID |
+| --learn-type | string | 否 | required | 学习类型：required/optional |
+| --dept-ids | string | 否 | - | 部门ID列表，逗号分隔 |
+| --dept-names | string | 否 | - | 部门名称列表，逗号分隔 |
+| --user-ids | string | 否 | - | 用户ID列表，逗号分隔 |
+| --user-names | string | 否 | - | 用户名称列表，逗号分隔 |
+| --message-content | string | 否 | 默认消息 | 通知消息内容 |
+| --message-switch | int | 否 | 1 | 消息开关：0关闭/1开启 |
+
+### 查询指派列表参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| --target-id | string | 否 | - | 目标ID |
+| --module | string | 否 | - | 模块类型 |
+| --learn-type | string | 否 | - | 学习类型 |
+| --assign-type | string | 否 | - | 指派类型：dept/user/group/position/role |
+| --keyword | string | 否 | - | 搜索关键词 |
+| --page | int | 否 | 1 | 页码 |
+| --limit | int | 否 | 10 | 每页数量 |
+
+## 注意事项
+
+1. **指派前准备**
+   - 确保目标资源已创建（如课程已发布）
+   - 使用 `+list-departments` 和 `+list-users` 查询可用的部门和用户
+   - 记录部门ID和用户ID用于创建指派
+
+2. **批量指派**
+   - 支持同时指派给多个对象
+   - 使用逗号分隔多个ID和名称
+   - ID和名称的顺序要一一对应
+
+3. **必修 vs 选修**
+   - **必修**（required）：用户必须完成学习
+   - **选修**（optional）：用户可选择性学习
+
+4. **消息通知**
+   - 默认开启消息通知（message-switch=1）
+   - 可自定义消息内容（message-content）
+   - 可通过 message-switch=0 关闭通知
+
+5. **权限要求**
+   - 需要具有指派的读写权限
+   - 只能查询和操作权限范围内的部门和用户
+
+6. **搜索方式**
+   - 部门搜索：按部门名称搜索
+   - 用户搜索：支持按姓名、手机号、工号搜索
+
+## 错误处理
+
+### 权限不足
+
+```bash
+# 错误信息: Permission denied
+# 解决方案: 检查是否已登录，并确认账号有相应权限
+soke-cli auth login
+```
+
+### 目标资源不存在
+
+```bash
+# 错误信息: Target not found
+# 解决方案: 检查目标ID是否正确，确认资源已创建
+```
+
+### 部门或用户不存在
+
+```bash
+# 错误信息: Department/User not found
+# 解决方案: 使用 +list-departments 或 +list-users 查询正确的ID
+```
+
+### 参数格式错误
+
+```bash
+# 错误信息: Invalid parameter format
+# 解决方案: 检查ID和名称列表是否一一对应，逗号分隔是否正确
+```
+
+## 相关文档
+
+- [SKILL.md](./MODULE.md) - 完整的 Skill 文档和 API 参考
+- [课程管理 Skill](../soke-course/MODULE.md) - 课程创建和管理
+- [考试管理 Skill](../soke-exam/MODULE.md) - 考试创建和管理
+- [共享配置 Skill](../soke-shared/MODULE.md) - 认证和配置管理
+
+## 工作流程图
+
+```
+指派工作流
+├── 1. 查询可用对象
+│   ├── +list-departments (查询部门)
+│   └── +list-users (查询用户)
+├── 2. 创建指派
+│   └── +create (指派给部门/用户/群组/职位/角色)
+└── 3. 验证和查询
+    └── +list (查询指派记录)
+```
+
+## 版本历史
+
+- v1.0.0 (2026-05-28): 初始版本，支持部门查询、用户查询、创建指派、查询指派列表

package/skills/{soke-certificate/SKILL.md → mono/references/modules/soke-certificate/MODULE.md}

@@ -9,7 +9,7 @@ metadata:
   cliHelp: "soke-cli certificate --help"
 ---
 
-**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)，其中包含认证、配置、权限处理**
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
 
 ## 核心概念
 
@@ -714,4 +714,4 @@ soke-cli certificate +delete --certificate-id <certificate_uuid>
 15. `+update` 的 `action` 支持 `update`、`publish`、`close`；`action=update` 时会发送证书数据字段
 16. `+delete` 是删除操作，请先确认目标证书 UUID
 17. 表格输出仅展示关键字段，完整字段请使用 `--format json`
-18. 权限不足或 Token 问题参考 [`../soke-shared/SKILL.md`](../soke-shared/SKILL.md)
+18. 权限不足或 Token 问题参考 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)