ooodc/PicoBot
1
0
Fork 0
Code Pull Requests Activity
PicoBot/.agents/skills/lark-okr/references/lark-okr-entities.md
ooodc a7883dbed9 refactor(todo): 重构待办事项管理逻辑及更新状态规则 
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段
- 强制每个任务都必须有唯一 id，且由用户负责生成
- 修改合并模式逻辑，merge=true 下保留未提及的旧任务
- 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress）
- 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled
- 优化状态转换校验，允许特定状态间合法切换
- 简化任务变更消息，移除详细的新增/更新/移除统计
- 更新文档和示例，明确 id 必须由用户生成和使用
- 修复和补充测试，增强状态转换和合并模式验证
- 调整任务时间戳生成逻辑，统一使用当前时间及索引
- 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
2026-06-13 09:22:33 +08:00

330 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# OKR 实体定义
本文档描述飞书 OKR API (`/open-apis/okr/v2`) 中涉及的核心实体及其字段定义。
## 实体关系概览
```
Cycle (用户周期)
└── Objective (目标)
├── KeyResult (关键结果)
│ └── Indicator (指标)
│ └── list<Progress> (进展记录列表)
└── Indicator (指标)
└── list<Progress> (进展记录列表)
Alignment (对齐关系): Objective ↔ Objective
Category (分类): Objective 的分组标签
```
---
## Owner (所有者)
所有者标识 OKR 实体的归属，目前仅支持用户类型。
| 字段 | 类型 | 必填 | 说明 |
|--------------|----------|----|-----------------------------------------------|
| `owner_type` | `string` | 是 | 所有者类型，通常为 `"user"`。 |
| `user_id` | `string` | 否 | 员工 ID，类型由请求参数 `user_id_type` 决定（默认 `open_id`） |
---
## Cycle (用户周期)
用户周期是 OKR 的顶层容器，代表一个时间段内的所有目标与关键结果。
| 字段 | 类型 | 必填 | 说明 |
|-------------------|-----------|----|--------------------------------------------|
| `id` | `string` | 是 | 用户周期 ID |
| `create_time` | `string` | 是 | 创建时间 |
| `update_time` | `string` | 是 | 更新时间 |
| `tenant_cycle_id` | `string` | 是 | 租户周期 ID（同一周期在不同用户下有不同的用户周期 ID，但租户周期 ID 相同） |
| `owner` | `Owner` | 是 | 所有者 |
| `start_time` | `string` | 是 | 周期开始时间。总是从某月1日开始 |
| `end_time` | `string` | 是 | 周期结束时间。到某月最后一日结束 |
| `cycle_status` | `integer` | 否 | 周期状态，见下表 |
| `score` | `number` | 否 | 周期分数，范围 [0, 1]，支持一位小数 |
### 常用术语
- **当前周期**: 指周期的 start_time/end_time
指周期的 start_time / end_time 所在的时间段与当前时间重叠的周期（即： start_time <= 当前时间 且 end_time >= 当前时间）。 注意：时间重叠是判断当前周期的首要且必须的硬性条件，绝对不能仅仅根据 cycle_status == 1 去判断。 如果有多个符合时间重叠标准的周期，再在这些包含当前时间的周期中过滤，保留周期状态为 default (0) 或 normal (1) 的周期。如果仍然有多个，则选择其中较新的一个。当用户提及“上一个周期”，“下一个周期”一类的表述时，通常是以当前周期为准计算。
- **所有者**: 绝大多数所有者都是用户，少部分租户启用了“团队OKR”功能，所有者可能是部门。用户身份下，只能编辑所有者为当前用户的
OKR。
### 周期状态 (cycle_status)
| 值 | 常量名 | 说明 |
|---|-----------|-------------|
| 0 | `default` | 默认状态 |
| 1 | `normal` | 生效中 |
| 2 | `invalid` | 已失效（通常仍可填写） |
| 3 | `hidden` | 已隐藏（不可见） |
> **SHORTCUT：** `okr +cycle-list` [lark-okr-cycle-list.md](lark-okr-cycle-list.md) 获取用户的周期列表，可按时间筛选
>
> **API：** `cycles.list`
---
## Objective (目标)
目标是 OKR 中的 "O"，属于某个用户周期，可包含多个关键结果。
| 字段 | 类型 | 必填 | 说明 |
|---------------|----------------|----|---------------------------------------------------------|
| `id` | `string` | 是 | 目标 ID |
| `create_time` | `string` | 是 | 创建时间，毫秒时间戳，shortcut 会将其解析为日期时间 |
| `update_time` | `string` | 是 | 更新时间，毫秒时间戳，shortcut 会将其解析为日期时间 |
| `owner` | `Owner` | 是 | 所有者 |
| `cycle_id` | `string` | 是 | 所属用户周期 ID |
| `position` | `integer` | 是 | 排序序号，从 1 开始，范围 [1, 100] |
| `content` | `ContentBlock` | 否 | 目标内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
| `score` | `number` | 否 | 目标分数，范围 [0, 1]，支持一位小数 |
| `notes` | `ContentBlock` | 否 | 目标备注（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
| `weight` | `number` | 否 | 目标权重，范围 [0, 1]，支持三位小数 |
| `deadline` | `string` | 否 | 截止时间，毫秒时间戳，shortcut 会将其解析为日期时间 |
| `category_id` | `string` | 否 | 所属分类 ID |
> **SHORTCUT：**
> - `okr +cycle-detail` [lark-okr-cycle-detail.md](lark-okr-cycle-detail.md) 获取某个用户周期下的全部目标和关键结果。时间相关的字段会以日期时间格式解析
>
> **API：**
> - `cycle.objectives.list` — 获取周期下的目标列表
> - `objectives.get` — 获取单个目标
> - `cycle.objectives.create` — 创建目标
> - `objectives.delete` — 删除目标
> - `cycles.objectives_position` — 更新周期下的目标排序
> - `cycles.objectives_weight` — 更新周期下的目标权重
---
## KeyResult (关键结果)
关键结果是 OKR 中的 "KR"，属于某个目标，描述目标的可衡量成果。
| 字段 | 类型 | 必填 | 说明 |
|----------------|----------------|----|-----------------------------------------------------------|
| `id` | `string` | 是 | 关键结果 ID |
| `create_time` | `string` | 是 | 创建时间，毫秒时间戳 |
| `update_time` | `string` | 是 | 修改时间，毫秒时间戳 |
| `owner` | `Owner` | 是 | 所有者 |
| `objective_id` | `string` | 是 | 所属目标 ID |
| `position` | `integer` | 是 | 排序序号，从 1 开始，范围 [1, 100] |
| `content` | `ContentBlock` | 否 | 关键结果内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
| `score` | `number` | 否 | 关键结果分数，范围 [0, 1]，支持一位小数 |
| `weight` | `number` | 否 | 权重，范围 [0, 1]，支持三位小数 |
| `deadline` | `string` | 否 | 截止时间，毫秒时间戳 |
> **API：**
> - `objective.key_results.list` — 获取目标下的关键结果列表
> - `key_results.get` — 获取单个关键结果
> - `key_results.patch` — 更新关键结果
> - `key_results.delete` — 删除关键结果
> - `objectives.key_results_position` — 更新目标下的关键结果排序
> - `objectives.key_results_weight` — 更新目标下的关键结果权重
---
## Progress (进展记录)
进展记录挂载在目标（Objective）或关键结果（Key Result）上，用于记录阶段性进展内容与进度百分比。每条进展记录包含富文本内容和可选的进度率。
| 字段 | 类型 | 必填 | 说明 |
|-----------------|----------------|----|---------------------------------------------------------|
| `progress_id` | `string` | 是 | 进展记录 ID（int64，正整数） |
| `modify_time` | `string` | 是 | 最后修改时间，毫秒时间戳，shortcut 会将其解析为日期时间 |
| `content` | `ContentBlock` | 否 | 进展内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
| `progress_rate` | `ProgressRate` | 否 | 进度率，包含百分比和状态 |
### ProgressRate (进度率)
| 字段 | 类型 | 必填 | 说明 |
|-----------|----------|----|------------------------------------------------------------------------------------------------------------------------------|
| `percent` | `number` | 否 | 进度百分比，范围 [-99999999999, 99999999999]。百分比的取值通常在 0-100，但允许超过此范围，以表示超额完成或负增长等情况。挂载的目标或关键结果的量化指标不使用百分比单位时，以这个字段更新当前值。系统内最多保留两位小数 |
| `status` | `string` | 否 | 进度状态，shortcut 返回可读字符串，见下表 |
### 进度状态 (progress_rate.status)
| 值 | 常量名 | 说明 |
|-----------|-----|-------|
| `normal` | 正常 | 进展正常 |
| `overdue` | 逾期 | 进展逾期 |
| `done` | 已完成 | 进展已完成 |
### 创建进展记录时的参数
创建进展记录时，除了 `content` 外，还需要指定这条进展记录挂载的对应目标或关键结果：
| 字段 | 类型 | 必填 | 说明 |
|-----------------|----------------|----|---------------------------------------------------------|
| `content` | `ContentBlock` | 是 | 进展内容（富文本），见 [ContentBlock 定义](lark-okr-contentblock.md) |
| `target_id` | `string` | 是 | 目标 ID 或关键结果 ID |
| `target_type` | `integer` | 是 | 目标类型：`2`=目标（Objective），`3`=关键结果（KeyResult） |
| `progress_rate` | `ProgressRate` | 否 | 进度率，可设置 `percent` 和 `status` |
| `source_title` | `string` | 否 | 来源标题，用于在 OKR 界面中显示进展来源 |
| `source_url` | `string` | 否 | 来源 URL，用于在 OKR 界面中显示进展来源链接 |
> **SHORTCUT：**
> - `okr +progress-get` [lark-okr-progress-get.md](lark-okr-progress-get.md) 获取单条进展记录
> - `okr +progress-create` [lark-okr-progress-create.md](lark-okr-progress-create.md) 为目标或关键结果创建进展记录
> - `okr +progress-update` [lark-okr-progress-update.md](lark-okr-progress-update.md) 更新进展记录内容
> - `okr +progress-delete` [lark-okr-progress-delete.md](lark-okr-progress-delete.md) 删除进展记录
> - `okr +progress-list` [lark-okr-progress-list.md](lark-okr-progress-list.md) 获取目标/关键结果下的进展记录
---
## Indicator (指标)
指标是目标和关键结果的量化度量，可独立挂载在 Objective 或 KeyResult 上。
| 字段 | 类型 | 必填 | 说明 |
|--------------------------------|-----------------|----|------------------------------------|
| `id` | `string` | 是 | 指标 ID |
| `create_time` | `string` | 是 | 创建时间，毫秒时间戳 |
| `update_time` | `string` | 是 | 更新时间，毫秒时间戳 |
| `owner` | `Owner` | 是 | 所有者 |
| `entity_type` | `integer` | 是 | 所属实体类型：`2`=目标，`3`=关键结果 |
| `entity_id` | `string` | 是 | 所属实体 ID |
| `indicator_status` | `integer` | 是 | 指标状态，见下表 |
| `status_calculate_type` | `integer` | 是 | 状态计算方式，见下表 |
| `start_value` | `number` | 否 | 起始值，范围 [-99999999999, 99999999999] |
| `target_value` | `number` | 否 | 目标值，范围 [-99999999999, 99999999999] |
| `current_value` | `number` | 否 | 当前值，范围 [-99999999999, 99999999999] |
| `current_value_calculate_type` | `integer` | 否 | 当前值计算方式，见下表 |
| `unit` | `IndicatorUnit` | 否 | 指标单位 |
### 修改指南
- **进度值**: 一般指 `current_value`，单位未提及时通常用百分制计算。
- 当用户要求量化的更新 OKR 进度时，一般指的就是修改对应 OKR 的 Indicator。
- OKR 在未设置量化指标时，Indicator 的内容为空。如果用户未做特别说明，更新进度时可以默认将进度以百分制设置（初始值0，目标值100，unit
参见下文设置为 0/PERCENT）
### 指标状态 (indicator_status)
| 值 | 说明 |
|----|-----|
| -1 | 未定义 |
| 0 | 正常 |
| 1 | 有风险 |
| 2 | 已延期 |
### 状态计算方式 (status_calculate_type)
| 值 | 说明 | 适用范围 |
|---|-----------------|---------|
| 0 | 手动更新 | 目标、关键结果 |
| 1 | 基于进度和当前时间自动更新 | 目标、关键结果 |
| 2 | 基于风险最高的关键结果状态更新 | 仅目标 |
### 当前值计算方式 (current_value_calculate_type)
| 值 | 说明 | 适用范围 |
|---|---------------|---------|
| 0 | 手动更新 | 目标、关键结果 |
| 1 | 基于关键结果进度自动更新 | 仅目标 |
| 2 | 基于拆解的关键结果进度更新 | 仅关键结果 |
### IndicatorUnit (指标单位)
| 字段 | 类型 | 必填 | 说明 |
|--------------|-----------|----|-----------------------------------------------------------------------------|
| `unit_type` | `integer` | 是 | 单位类型：`0`=公共，`1`=自定义 |
| `unit_value` | `string` | 是 | 单位值。公共类型可选：`PERCENT`(百分比)、`NONE`(无单位)、`YUAN`(元)、`DOLLAR`(美元)；自定义类型字符长度不超过 5 |
> **API：**
> - `key_result.indicators.list` — 获取关键结果的指标
> - `objective.indicators.list` — 获取目标的指标
> - `indicators.patch` — 更新指标
---
## Alignment (对齐关系)
对齐关系描述两个目标之间的上下对齐。
| 字段 | 类型 | 必填 | 说明 |
|--------------------|-----------|----|-----------------------|
| `id` | `string` | 是 | 对齐 ID |
| `create_time` | `string` | 是 | 创建时间，毫秒时间戳 |
| `update_time` | `string` | 是 | 更新时间，毫秒时间戳 |
| `from_owner` | `Owner` | 是 | 发起对齐的所有者 |
| `to_owner` | `Owner` | 是 | 被对齐的所有者 |
| `from_entity_type` | `integer` | 是 | 发起对齐的实体类型，固定为 `2`（目标） |
| `from_entity_id` | `string` | 是 | 发起对齐的实体 ID |
| `to_entity_type` | `integer` | 是 | 被对齐的实体类型，固定为 `2`（目标） |
| `to_entity_id` | `string` | 是 | 被对齐的实体 ID |
> **API：**
> - `alignments.get` — 获取对齐关系
> - `alignments.delete` — 删除对齐关系
> - `objective.alignments.list` — 批量获取目标下的对齐关系
> - `objective.alignments.create` — 创建对齐关系
---
## Category (分类)
分类用于对目标进行分组标记（如"个人 OKR"、"团队 OKR"、"承诺 OKR"）等。具体的分类根据租户设置而定。
| 字段 | 类型 | 必填 | 说明 |
|-----------------|----------------|----|-------------------------------------------------------------|
| `id` | `string` | 是 | 分类 ID |
| `create_time` | `string` | 是 | 创建时间，毫秒时间戳 |
| `update_time` | `string` | 是 | 更新时间，毫秒时间戳 |
| `category_type` | `string` | 是 | 分类类型：`"person"`=个人，`"team"`=团队 |
| `enabled` | `boolean` | 是 | 是否启用 |
| `color` | `string` | 是 | 颜色标识：`blue`、`purple`、`wathet`、`turquoise`、`indigo`、`orange` |
| `name` | `CategoryName` | 是 | 多语言名称 |
### CategoryName (分类名称)
| 字段 | 类型 | 必填 | 说明 |
|------|----------|----|-----|
| `zh` | `string` | 否 | 中文名 |
| `en` | `string` | 否 | 英文名 |
| `ja` | `string` | 否 | 日文名 |
> **API：** `categories.list` — 批量获取租户设置的分类列表
---
## 通用请求参数
以下参数在多数 OKR API 中通用：
| 参数 | 位置 | 必填 | 默认值 | 说明 |
|----------------------|---------|----|------------------------|--------------------------------------------------|
| `user_id_type` | `query` | 否 | `"open_id"` | 用户 ID 类型：`open_id` \| `union_id` \| `user_id` |
| `department_id_type` | `query` | 否 | `"open_department_id"` | 部门 ID 类型：`open_department_id` \| `department_id` |
| `page_size` | `query` | 否 | `10` | 分页大小，最大 100 |
| `page_token` | `query` | 否 | `""` | 分页键，首页传空串 |
---
## 权限 Scope 说明
| Scope | 权限类型 | 说明 |
|--------------------------------|------|--------------|
| `okr:okr.content:readonly` | 读 | 读取 OKR 内容 |
| `okr:okr.content:writeonly` | 写 | 写入/删除 OKR 内容 |
| `okr:okr.period:readonly` | 读 | 读取 OKR 周期 |
| `okr:okr.progress:readonly` | 读 | 读取进展记录 |
| `okr:okr.progress:writeonly` | 写 | 创建/更新进展记录 |
| `okr:okr.progress:delete` | 写 | 删除进展记录 |
| `okr:okr.progress.file:upload` | 写 | 上传进展记录图片附件 |
| `okr:okr.setting:read` | 读 | 读取 OKR 设置 |
所有 OKR API 均支持 `user` 和 `tenant`（应用）两种 access token 类型。
## 参考
- [OKR ContentBlock 富文本格式](lark-okr-contentblock.md) — content/notes 字段的富文本结构定义
- [okr +cycle-list](lark-okr-cycle-list.md) — 列出用户 OKR 周期
- [okr +cycle-detail](lark-okr-cycle-detail.md) — 获取周期下的目标与关键结果
- [okr +progress-get](lark-okr-progress-get.md) — 获取进展记录
- [okr +progress-create](lark-okr-progress-create.md) — 创建进展记录
- [okr +progress-update](lark-okr-progress-update.md) — 更新进展记录
- [okr +progress-delete](lark-okr-progress-delete.md) — 删除进展记录
View Git Blame Copy Permalink