@sokeai/cli 1.0.76 → 1.0.78

package/skills/mono/references/modules/soke-certificate/MODULE.md

@@ -0,0 +1,717 @@
+---
+name: soke-certificate
+summary: 证书管理查询
+version: 1.0.0
+description: "证书管理查询：查询证书列表、证书分类、证书获得人员。当用户需要查看证书模板/证书列表、筛选已发布证书、获取证书 UUID 或查询证书发放人员时使用。 | Certificate management query: list certificates, certificate categories, and certificate users. Use when users need certificate templates/lists, published certificate filtering, certificate UUIDs, or issued certificate users."
+metadata:
+  requires:
+    bins: ["soke-cli"]
+  cliHelp: "soke-cli certificate --help"
+---
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)，其中包含认证、配置、权限处理**
+
+## 核心概念
+
+- **Certificate（证书）**: 企业后台配置的证书模板或证书资源，通过 `uuid` 标识
+- **Category（证书分类）**: 证书分类，通过 `category_id` / `uuid` 标识
+- **CertificateUser（证书获得人员）**: 已获得某个证书的学员记录
+
+## Shortcuts（推荐优先使用）
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+templates`](#templates) | 查询证书内置模板列表 |
+| [`+list`](#list) | 查询证书列表 |
+| [`+category`](#category) | 查询证书分类 |
+| [`+create`](#create) | 创建证书 |
+| [`+get`](#get) | 获取证书详情 |
+| [`+users`](#users) | 查询证书用户获取记录 |
+| [`+award`](#award) | 手动颁发证书 |
+| [`+cancel-user`](#cancel-user) | 取消学员证书 |
+| [`+check-linked`](#check-linked) | 查询证书模块关联 |
+| [`+coordinate`](#coordinate) | 设置证书坐标 |
+| [`+update`](#update) | 更新证书数据、发布或关闭证书 |
+| [`+delete`](#delete) | 删除证书 |
+
+---
+
+## 命令详解
+
+### +templates
+
+查询证书内置模板列表。
+
+**命令格式**:
+```bash
+soke-cli certificate +templates [--format json|yaml|table]
+```
+
+**返回字段**（表格显示关键字段）:
+- `name`: 模板名称
+- `url`: 模板图片 URL
+- `path`: 模板文件路径
+
+**示例**:
+```bash
+soke-cli certificate +templates
+
+# 查看完整返回
+soke-cli certificate +templates --format json
+```
+
+**接口**: `GET /skills/certificate/template`
+
+---
+
+### +list
+
+查询证书列表，支持按状态筛选。
+
+**命令格式**:
+```bash
+soke-cli certificate +list \
+  [--page <page>] \
+  [--limit <limit>] \
+  [--status <status>] \
+  [--keyword <keyword>] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--page`: 页码，默认 `1`
+- `--limit`: 每页条数，默认 `10`
+- `--status`: 证书状态，可选；`0` 未发布，`1` 已发布，`2` 已关闭
+- `--keyword`: 关键词，模糊查询证书标题/编码
+
+**返回字段**（表格显示关键字段）:
+- `uuid`: 证书 UUID
+- `title`: 证书标题
+- `status`: 证书状态
+- `code`: 证书编号
+- `type`: 证书类型
+- `category_title`: 分类名称
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+
+**示例**:
+```bash
+# 查询已发布证书
+soke-cli certificate +list --page 1 --limit 10 --status 1
+
+# 模糊查询证书
+soke-cli certificate +list --keyword "普通证书" --page 1 --limit 10
+
+# 查询全部证书并输出完整 JSON
+soke-cli certificate +list --page 1 --limit 20 --format json
+```
+---
+
+### +create
+
+创建证书。通常先通过 `+templates` 获取模板 `url/path`，再通过 `+category` 获取分类 UUID。
+
+**命令格式**:
+```bash
+soke-cli certificate +create \
+  --title <title> \
+  --code <code> \
+  --image <template_url> \
+  --target-path <template_path> \
+  --category-id <category_uuid> \
+  [--category-title <title>] \
+  [--path <uuid1,uuid2>] \
+  [--status <0|1|2>] \
+  [--description <text>] \
+  [--custom-content <text>] \
+  [--serial-number <number>] \
+  [--is-expiration <0|1>] \
+  [--expiration-day <days>] \
+  [--is-expiration-remind <0|1>] \
+  [--type <type>] \
+  [--advance-day <days>] \
+  [--is-student <0|1>] \
+  [--format json|yaml|table]
+```
+
+**核心参数**:
+- `--title`: 证书标题，必填
+- `--code`: 证书编号，必填；必须唯一，只能由字母、数字、下划线组成，不超过 20 位
+- `--image`: 证书图片 URL，必填；可以来自图片库图片，也可以来自 `+templates` 返回的内置模板 URL
+- `--target-path`: 证书图片 OSS 路径，必填；例如 `dingfc5d942826fce9d9/public/image/certificate/certificate1.png`
+- `--category-id`: 分类 UUID，必填，来自 `+category`
+- `--path`: 分类路径 UUID 列表；不传时默认使用 `--category-id`
+- `--custom-content`: 自定义内容；不传时默认使用 `--description`
+- `--serial-number`: 流水号位数，系统会自动生成流水号并作为证书编号尾数；建议位数大于系统学员数位数，否则可能造成证书编号重复
+
+**常用默认值**:
+- `--status`: 默认 `0`
+- `--serial-number`: 默认 `6`
+- `--is-expiration`: 默认 `0`
+- `--expiration-day`: 默认 `0`
+- `--is-expiration-remind`: 默认 `0`
+- `--type`: 默认 `1`
+- `--advance-day`: 默认 `1`
+- `--is-student`: 默认 `1`
+
+**返回字段**（表格显示关键字段）:
+- `uuid`: 新证书 UUID
+- `title`: 证书标题
+- `status`: 证书状态
+- `code`: 证书编号
+- `serial_number`: 流水号位数
+- `is_expiration`: 是否按有效期过期
+- `expiration_day`: 有效天数
+- `create_time`: 创建时间
+- `create_user_name`: 创建人
+
+**示例**:
+```bash
+soke-cli certificate +create \
+  --title "111" \
+  --code "2343242345546565645" \
+  --image "https://newsokecdn.soke.cn/dingfc5d942826fce9d9/public/image/certificate/certificate1.png" \
+  --target-path "dingfc5d942826fce9d9/public/image/certificate/certificate1.png" \
+  --category-id "704E6B75-F4B3-4961-AEE4-D8C9FCC2D7FC" \
+  --status 0 \
+  --description "测试证书" \
+  --custom-content "测试证书" \
+  --serial-number 6 \
+  --is-expiration 1 \
+  --expiration-day 30 \
+  --is-expiration-remind 0 \
+  --type 1 \
+  --format json
+```
+---
+
+### +category
+
+查询证书分类列表，支持按分类名称模糊搜索。
+
+**命令格式**:
+```bash
+soke-cli certificate +category \
+  [--keyword <keyword>] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--keyword`: 关键词，模糊查询证书分类名称
+
+**返回字段**（表格显示关键字段）:
+- `uuid`: 分类 UUID
+- `title`: 分类名称
+- `parent_id`: 父分类 ID
+- `weight`: 排序权重
+- `has_children`: 是否有子分类
+- `create_dept_user_name`: 创建人
+- `create_time`: 创建时间
+
+**示例**:
+```bash
+# 按关键词查询证书分类
+soke-cli certificate +category --keyword "添加编号"
+
+# 查询全部证书分类并输出完整 JSON
+soke-cli certificate +category --format json
+```
+---
+
+### +get
+
+获取证书详情。
+
+**命令格式**:
+```bash
+soke-cli certificate +get \
+  --certificate-id <certificate_uuid> \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list` 返回的 `data.list[].uuid`
+
+**返回字段**（表格显示关键字段）:
+- `uuid`: 证书 UUID
+- `title`: 证书标题
+- `status`: 证书状态
+- `code`: 证书编号
+- `type`: 证书类型
+- `target_point`: 目标学分/学时
+- `category_title`: 分类名称
+- `expire_time`: 过期时间
+- `create_time`: 创建时间
+- `update_time`: 更新时间
+
+**示例**:
+```bash
+soke-cli certificate +get --certificate-id DAACD37D-1B72-4CE4-B8D0-12C7F4DAA4C3
+
+# 查看完整 info 和 categoryInfo
+soke-cli certificate +get --certificate-id DAACD37D-1B72-4CE4-B8D0-12C7F4DAA4C3 --format json
+```
+---
+
+### +users
+
+查询证书用户获取记录，支持按证书、关键词、状态分页筛选。
+
+**命令格式**:
+```bash
+soke-cli certificate +users \
+  --certificate-id <certificate_uuid> \
+  [--keyword <keyword>] \
+  [--page <page>] \
+  [--limit <limit>] \
+  [--status <status>] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，必填
+- `--keyword`: 关键词，模糊查询用户姓名/工号
+- `--page`: 页码，默认 `1`
+- `--limit`: 每页条数，默认 `10`
+- `--status`: 获取记录状态筛选，默认 `all`
+
+**返回字段**（表格显示关键字段）:
+- `uuid`: 证书获取记录 UUID
+- `dept_user_id`: 部门用户 ID
+- `dept_user_name`: 学员姓名
+- `job_number`: 工号
+- `certificate_title`: 证书名称
+- `certificate_num`: 证书编号
+- `module`: 来源模块
+- `status`: 状态
+- `award_time`: 颁发时间
+- `expire_time`: 证书过期时间
+
+**示例**:
+```bash
+# 查询某证书下的用户获取记录
+soke-cli certificate +users --certificate-id 8200D7C4-6DD1-4F09-BC9B-940512A7E7C4 --page 1 --limit 10 --status all
+
+# 按用户关键词筛选
+soke-cli certificate +users --certificate-id 8200D7C4-6DD1-4F09-BC9B-940512A7E7C4 --keyword "武玲"
+
+# 查看完整字段
+soke-cli certificate +users --certificate-id 8200D7C4-6DD1-4F09-BC9B-940512A7E7C4 --format json
+```
+---
+
+### +award
+
+手动给用户颁发证书。`user_list` 需要使用部门用户列表中的用户对象。
+
+**命令格式**:
+```bash
+soke-cli certificate +award \
+  --certificate-id <certificate_uuid> \
+  --certificate-title <title> \
+  --certificate-num <certificate_num> \
+  --certificate-image <image_url> \
+  --user-list-json '<user_array_json>' \
+  [--lang zh] \
+  [--utcoffset -28800] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list`
+- `--certificate-title`: 证书标题
+- `--certificate-num`: 证书编号
+- `--certificate-image`: 证书图片 URL
+- `--user-list-json`: 部门用户对象数组 JSON，来自 `contact +list-department-users`
+- `--lang`: 语言，默认 `zh`
+- `--utcoffset`: 时区偏移，默认 `-28800`
+
+**user-list-json 示例字段**:
+- `dept_id`: 部门 ID
+- `user_id`: 用户 ID
+- `show_name`: 展示姓名
+- `dept_user_id`: 部门用户 ID
+- `dept_user_name`: 部门用户姓名
+- `avatar_color`: 头像颜色
+- `avatar`: 头像
+- `job_number`: 工号
+- `position`: 职位
+
+**示例**:
+```bash
+# 先查询部门用户
+soke-cli contact +list-department-users --dept-id -999 --page 1 --page-size 100 --format json
+
+# 使用部门用户对象数组颁发证书
+soke-cli certificate +award \
+  --certificate-id CE459727-7895-4F90-9F68-FEEB532BC5EA \
+  --certificate-title "普通证书批量导入测试1111" \
+  --certificate-num "15678765432123456787" \
+  --certificate-image "https://newsokecdn.soke.cn/dingfc5d942826fce9d9/public/image/certificate/certificate2.gif" \
+  --user-list-json '[{"dept_id":-999,"user_id":"92B5B989-A708-477A-8ACF-4222C7137CF5","show_name":"钰欣","dept_user_id":"SOKE0088-5840-423E-B205-0E3CC6D877F1","dept_user_name":"钰欣","avatar_color":"#4DA9EB","avatar":"","job_number":"","position":""}]'
+```
+
+**接口**: `POST /skills/certificate/user/create?lang=zh&utcoffset=-28800`
+
+---
+
+### +cancel-user
+
+取消学员证书。路径里的 UUID 是 `certificate +users` 返回的证书获取记录 `uuid`，不是证书 UUID。
+
+**命令格式**:
+```bash
+soke-cli certificate +cancel-user \
+  --certificate-user-id <certificate_user_uuid> \
+  --content <reason> \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-user-id`: 证书获取记录 UUID，来自 `certificate +users` 返回的 `data.list[].uuid`
+- `--content`: 取消理由
+
+**返回字段**（表格显示关键字段）:
+- `status`: 更新后的状态
+- `is_delete`: 是否删除
+- `cancel_message`: 取消原因
+- `update_time`: 更新时间
+- `update_user_name`: 更新人
+- `certificate_image`: 证书图片
+
+**示例**:
+```bash
+# 先查询证书用户获取记录，拿到记录 uuid
+soke-cli certificate +users --certificate-id 8200D7C4-6DD1-4F09-BC9B-940512A7E7C4 --format json
+
+# 取消学员证书
+soke-cli certificate +cancel-user \
+  --certificate-user-id 47C64244-E402-4CD9-84FD-406E7967BE33 \
+  --content "这是理由"
+```
+
+**接口**: `PUT /skills/certificate/user/update/{uuid}`
+
+---
+
+### +check-linked
+
+查询证书是否被课程、考试、学习地图、培训或学习阶段关联。
+
+**命令格式**:
+```bash
+soke-cli certificate +check-linked \
+  --certificate-id <certificate_uuid> \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list` 返回的 `data.list[].uuid`
+
+**返回字段**（表格显示关键字段）:
+- `module`: 模块标识
+- `module_name`: 模块名称
+- `title`: 关联资源标题
+- `title_num`: 关联资源数量
+
+**示例**:
+```bash
+soke-cli certificate +check-linked --certificate-id 8200D7C4-6DD1-4F09-BC9B-940512A7E7C4
+```
+
+---
+
+### +coordinate
+
+设置证书上的用户名、发证时间、到期时间、编号、自定义内容、积分、部门等字段坐标和样式。
+
+**命令格式**:
+```bash
+soke-cli certificate +coordinate \
+  --certificate-id <certificate_uuid> \
+  [--user-name-left <px>] \
+  [--user-name-top <px>] \
+  [--user-name-font-size <px>] \
+  [--user-name-color <color>] \
+  [--date-time-left <px>] \
+  [--date-time-top <px>] \
+  [--date-time-font-size <px>] \
+  [--date-time-color <color>] \
+  [--expire-time-left <px>] \
+  [--expire-time-top <px>] \
+  [--expire-time-font-size <px>] \
+  [--expire-time-color <color>] \
+  [--cert-code-left <px>] \
+  [--cert-code-top <px>] \
+  [--cert-code-font-size <px>] \
+  [--cert-code-color <color>] \
+  [--customize-left <px>] \
+  [--customize-top <px>] \
+  [--customize-font-size <px>] \
+  [--customize-color <color>] \
+  [--point-left <px>] \
+  [--point-top <px>] \
+  [--point-font-size <px>] \
+  [--point-color <color>] \
+  [--dept-names-left <px>] \
+  [--dept-names-top <px>] \
+  [--dept-names-font-size <px>] \
+  [--dept-names-color <color>] \
+  [--width <px>] \
+  [--height <px>] \
+  [--dept-show <0|1>] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list` 返回的 `data.list[].uuid`
+- `--user-name-left/top/font-size/color`: 用户名距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--date-time-left/top/font-size/color`: 发证时间距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--expire-time-left/top/font-size/color`: 到期时间距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--cert-code-left/top/font-size/color`: 证书编号距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--customize-left/top/font-size/color`: 自定义内容距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--point-left/top/font-size/color`: 积分距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--dept-names-left/top/font-size/color`: 部门距离左边框、顶部的像素位置，以及文字大小和颜色
+- `--width` / `--height`: 证书画布宽高，单位像素
+- `--dept-show`: 部门是否显示，`0` 不显示，`1` 显示
+- `--status`: 证书状态，`0` 未发布，`1` 已发布，`2` 已关闭
+- `--action`: 坐标设置动作，默认 `coor`
+- `--nwidth` / `--nheight`: 证书图片宽高缩放比例
+
+**示例**:
+```bash
+soke-cli certificate +coordinate \
+  --certificate-id 65092195-49D0-453F-9CE1-A6CBB4502EF1 \
+  --user-name-left "518.7747789200492px" \
+  --user-name-top "450.53825882621436px" \
+  --user-name-font-size "16px" \
+  --user-name-color "#409EFF" \
+  --date-time-left "826.5791337253736px" \
+  --date-time-top "496.53478056534476px" \
+  --expire-time-left "707.2756554645041px" \
+  --expire-time-top "498.1573838275412px" \
+  --cert-code-left "780.7005668573794px" \
+  --cert-code-top "443.16283331829567px" \
+  --cert-code-font-size "16px" \
+  --cert-code-color "#409EFF" \
+  --customize-left "444px" \
+  --customize-top "218px" \
+  --customize-font-size "16px" \
+  --customize-color "#409EFF" \
+  --point-left "220px" \
+  --point-top "160px" \
+  --point-font-size "16px" \
+  --point-color "#409EFF" \
+  --dept-names-left "220px" \
+  --dept-names-top "220px" \
+  --dept-names-font-size "16px" \
+  --dept-names-color "#409EFF" \
+  --width 1653 \
+  --height "1169.9919626086958" \
+  --dept-show 1
+```
+
+---
+
+### +update
+
+更新证书数据、发布证书或关闭证书。接口根据 `action` 判断操作类型：`update` 更新数据，`publish` 发布，`close` 关闭。
+
+**命令格式**:
+```bash
+soke-cli certificate +update \
+  --certificate-id <certificate_uuid> \
+  --action <update|publish|close> \
+  [--title <title>] \
+  [--code <code>] \
+  [--store-code <old_code>] \
+  [--image <image_url>] \
+  [--target-path <oss_path>] \
+  [--description <text>] \
+  [--path <uuid1,uuid2>] \
+  [--custom-content <text>] \
+  [--serial-number <number>] \
+  [--expire-time <YYYY-MM-DD>] \
+  [--target-point <point>] \
+  [--credit-year <year>] \
+  [--is-expiration <0|1>] \
+  [--expiration-day <days>] \
+  [--is-expiration-remind <0|1>] \
+  [--advance-day <days>] \
+  [--is-student <0|1>] \
+  [--is-designated-personnel <0|1>] \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list` 返回的 `data.list[].uuid`
+- `--action`: 操作类型；`update` 更新数据，`publish` 发布证书，`close` 关闭证书
+- `--title`: 证书标题，`action=update` 时必填
+- `--code`: 新证书编号，`action=update` 时必填；唯一，只能由字母、数字、下划线组成，不超过 20 位
+- `--store-code`: 原证书编号，`action=update` 时必填
+- `--image`: 证书图片 URL，`action=update` 时必填；可以来自图片库或内置模板
+- `--target-path`: 证书图片 OSS 路径，`action=update` 时必填
+- `--path`: 分类路径 UUID 列表，多个用英文逗号分隔，`action=update` 时必填
+- `--custom-content`: 自定义内容；不传时默认使用 `--description`
+
+**返回字段**（表格显示关键字段）:
+- `title`: 证书标题
+- `code`: 证书编号
+- `status`: 更新后的状态
+- `update_time`: 更新时间
+- `update_user_name`: 更新人
+
+**示例**:
+```bash
+# 更新证书数据
+soke-cli certificate +update \
+  --certificate-id 65092195-49D0-453F-9CE1-A6CBB4502EF1 \
+  --action update \
+  --title "证书关闭获取测试" \
+  --code "1234444445577447787" \
+  --store-code "123444444557744778" \
+  --image "https://newsokecdn.soke.cn/dingfc5d942826fce9d9/public/image/certificate/certificate4.png" \
+  --target-path "dingfc5d942826fce9d9/public/image/certificate/certificate4.png" \
+  --description "232323" \
+  --path "DFECCF24-AFC5-40E4-A0FD-3B71BFB6B140" \
+  --custom-content "1212" \
+  --serial-number 6 \
+  --target-point "0.00"
+
+# 发布证书
+soke-cli certificate +update --certificate-id 65092195-49D0-453F-9CE1-A6CBB4502EF1 --action publish
+
+# 关闭证书
+soke-cli certificate +update --certificate-id 65092195-49D0-453F-9CE1-A6CBB4502EF1 --action close
+```
+
+**接口**: `PUT /skills/certificate/update/{uuid}`
+
+---
+
+### +delete
+
+删除证书。
+
+**命令格式**:
+```bash
+soke-cli certificate +delete \
+  --certificate-id <certificate_uuid> \
+  [--format json|yaml|table]
+```
+
+**参数说明**:
+- `--certificate-id`: 证书 UUID，通常来自 `certificate +list` 返回的 `data.list[].uuid`
+
+**示例**:
+```bash
+soke-cli certificate +delete --certificate-id DAACD37D-1B72-4CE4-B8D0-12C7F4DAA4C3
+```
+
+**接口**: `DELETE /skills/certificate/delete/{uuid}`
+
+---
+
+## 常见工作流
+
+### 查询内置模板
+
+```bash
+soke-cli certificate +templates
+```
+
+### 创建证书
+
+```bash
+soke-cli certificate +templates
+soke-cli certificate +category --keyword "<分类关键词>"
+soke-cli certificate +create \
+  --title "<证书标题>" \
+  --code "<唯一证书编号>" \
+  --image "<templates 返回的 url>" \
+  --target-path "<模板或图片库图片的 OSS path>" \
+  --category-id "<category 返回的 uuid>" \
+  --description "<证书简介>"
+```
+
+### 查询已发布证书并获取 UUID
+
+```bash
+soke-cli certificate +list --status 1 --page 1 --limit 10 --format json
+```
+
+从返回的 `data.list[].uuid` 中获取证书 UUID。
+
+### 查看证书详情
+
+```bash
+soke-cli certificate +get --certificate-id <certificate_uuid> --format json
+```
+
+### 查询证书用户获取记录
+
+```bash
+soke-cli certificate +users --certificate-id <certificate_uuid> --page 1 --limit 10 --status all
+```
+
+### 手动颁发证书
+
+```bash
+soke-cli contact +list-department-users --dept-id <dept_id> --format json
+soke-cli certificate +award --certificate-id <certificate_uuid> --certificate-title "<证书标题>" --certificate-num "<证书编号>" --certificate-image "<证书图片 URL>" --user-list-json '<部门用户对象数组 JSON>'
+```
+
+### 取消学员证书
+
+```bash
+soke-cli certificate +users --certificate-id <certificate_uuid> --format json
+soke-cli certificate +cancel-user --certificate-user-id <certificate +users 返回的 uuid> --content "<取消理由>"
+```
+
+### 删除前检查模块关联
+
+```bash
+soke-cli certificate +check-linked --certificate-id <certificate_uuid>
+```
+
+### 设置证书坐标
+
+```bash
+soke-cli certificate +get --certificate-id <certificate_uuid> --format json
+soke-cli certificate +coordinate --certificate-id <certificate_uuid> --user-name-left "518px" --user-name-top "450px"
+```
+
+### 更新、发布或关闭证书
+
+```bash
+soke-cli certificate +update --certificate-id <certificate_uuid> --action update --title "<证书标题>" --code "<新证书编号>" --store-code "<原证书编号>" --image "<图片 URL>" --target-path "<OSS path>" --path "<分类 UUID>"
+soke-cli certificate +update --certificate-id <certificate_uuid> --action publish
+soke-cli certificate +update --certificate-id <certificate_uuid> --action close
+```
+
+### 删除证书
+
+```bash
+soke-cli certificate +delete --certificate-id <certificate_uuid>
+```
+
+## 注意事项
+
+1. `+list` 使用 `limit` 参数，对接 `/skills/certificate/list`
+2. `+templates` 返回内置模板 URL 和对应 path
+3. `+create` 的 `image` 可以来自图片库图片或 `+templates` 返回的内置模板 URL
+4. `+create` 的 `path` 不传时默认使用 `category-id`
+5. `+create` 的 `target-path` 是图片 OSS 路径，不是完整 URL
+6. `+create` 的 `code` 是唯一证书编号，只能由字母、数字、下划线组成，不超过 20 位
+7. `+create` 的 `serial-number` 是系统自动生成的流水号位数，作为编号尾数，建议大于系统学员数位数
+8. `+category` 对接新版证书分类接口，返回结构为 `data.list.list`
+9. `+get` 返回完整 `data`，表格仅展示证书核心字段
+10. `+users` 对接证书用户获取记录接口，按 `certificate_id` 查询证书下用户获取记录
+11. `+award` 的 `user-list-json` 必须是部门用户对象数组，先从 `contact +list-department-users` 获取
+12. `+cancel-user` 使用的是 `+users` 返回的证书获取记录 UUID，不是证书 UUID
+13. `+check-linked` 可用于删除前确认是否有关联模块
+14. `+coordinate` 会根据命令行参数自动组装接口所需的坐标 JSON
+15. `+update` 的 `action` 支持 `update`、`publish`、`close`；`action=update` 时会发送证书数据字段
+16. `+delete` 是删除操作，请先确认目标证书 UUID
+17. 表格输出仅展示关键字段，完整字段请使用 `--format json`
+18. 权限不足或 Token 问题参考 [`../soke-shared/MODULE.md`](../soke-shared/MODULE.md)