ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
490 lines
12 KiB
Markdown
490 lines
12 KiB
Markdown
# Base field JSON SSOT
|
||
|
||
> 适用命令：`lark-cli base +field-create`、`lark-cli base +field-update`
|
||
|
||
本文档定义 `+field-create` / `+field-update` 写字段时 `--json` 的推荐格式，是字段类型与字段 JSON 结构的 source of truth。目标不是复刻完整 schema，而是让 agent 稳定产出正确 payload。
|
||
|
||
## 1. 顶层规则（必须遵守）
|
||
|
||
- `--json` 必须是 JSON 对象。
|
||
- 顶层统一使用：`type` + `name` + 类型特有字段。
|
||
- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
|
||
- 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
|
||
- `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。
|
||
- `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。
|
||
|
||
推荐示例：
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"name": "需求背景",
|
||
"description": "记录需求背景与已知约束"
|
||
}
|
||
```
|
||
|
||
## 2. 字段速查
|
||
|
||
| 类型 | 最小必填字段 | 常见补充字段 |
|
||
|------|--------------|-------------|
|
||
| `text` | `type` `name` | `style.type` |
|
||
| `number` | `type` `name` | `style` |
|
||
| `select` | `type` `name` | `multiple` + `options`，或 `multiple` + `dynamic_options_source` |
|
||
| `datetime` | `type` `name` | `style.format` |
|
||
| `created_at` / `updated_at` | `type` `name` | `style.format` |
|
||
| `user` / `group_chat` | `type` `name` | `multiple` |
|
||
| `created_by` / `updated_by` | `type` `name` | 无 |
|
||
| `link` | `type` `name` `link_table` | `bidirectional` `bidirectional_link_field_name` |
|
||
| `formula` | `type` `name` `expression` | 无 |
|
||
| `lookup` | `type` `name` `from` `select` `where` | `aggregate` |
|
||
| `auto_number` | `type` `name` | `style.rules` |
|
||
| `attachment` / `location` / `checkbox` | `type` `name` | 无 |
|
||
|
||
所有类型都可额外传 `description`；上表的“常见补充字段”只列类型特有配置。
|
||
|
||
## 3. 各类型写法
|
||
|
||
### 3.1 text
|
||
|
||
文本字段；电话、超链接、邮箱、条码也都属于 `text`，通过 `style.type` 区分。
|
||
|
||
最小写法（默认 `style.type` 为 `plain`）：
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"name": "标题"
|
||
}
|
||
```
|
||
|
||
常用写法：
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"name": "标题",
|
||
"description": "主标题字段"
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"name": "联系电话",
|
||
"style": { "type": "phone" }
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"type": "text",
|
||
"name": "官网",
|
||
"style": { "type": "url" }
|
||
}
|
||
```
|
||
|
||
常用 `style.type`：`plain`（默认）、`phone`、`url`、`email`、`barcode`。
|
||
|
||
### 3.2 number
|
||
|
||
数字字段；货币、进度、评分都属于 `number`，通过 `style.type` 区分。
|
||
|
||
最小写法（默认 `style.type` 为 `plain`）：
|
||
|
||
```json
|
||
{
|
||
"type": "number",
|
||
"name": "工时"
|
||
}
|
||
```
|
||
|
||
`style` 是按 `type` 区分的对象；不同 `style.type` 的内部字段不一样，不要混传。
|
||
|
||
#### `plain`
|
||
|
||
支持字段：`precision`、`percentage`、`thousands_separator`
|
||
|
||
默认值 / 约束：
|
||
- `precision` 取值 `0..4`，默认 `2`
|
||
- `percentage` 默认 `false`
|
||
- `thousands_separator` 默认 `false`
|
||
|
||
```json
|
||
{
|
||
"type": "number",
|
||
"name": "工时",
|
||
"style": {
|
||
"type": "plain",
|
||
"precision": 2,
|
||
"percentage": false,
|
||
"thousands_separator": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `currency`
|
||
|
||
支持字段：`precision`、`currency_code`
|
||
|
||
默认值 / 约束：
|
||
- `precision` 取值 `0..4`，默认 `2`
|
||
- `currency_code` 必填，如 `CNY`、`USD`、`EUR`
|
||
|
||
```json
|
||
{
|
||
"type": "number",
|
||
"name": "预算",
|
||
"style": { "type": "currency", "precision": 2, "currency_code": "CNY" }
|
||
}
|
||
```
|
||
|
||
#### `progress`
|
||
|
||
支持字段：`percentage`、`color`
|
||
|
||
默认值 / 约束：
|
||
- `percentage` 默认 `true`
|
||
- `color` 必填
|
||
- `color` 可用：`Blue`、`Purple`、`DarkGreen`、`Green`、`Cyan`、`Orange`、`Red`、`Gray`、`WhiteToBlueGradient`、`WhiteToPurpleGradient`、`WhiteToOrangeGradient`、`GreenToRedGradient`、`RedToGreenGradient`、`BlueToPinkGradient`、`PinkToBlueGradient`、`SpectralGradient`
|
||
|
||
```json
|
||
{
|
||
"type": "number",
|
||
"name": "完成度",
|
||
"style": { "type": "progress", "percentage": true, "color": "Blue" }
|
||
}
|
||
```
|
||
|
||
#### `rating`
|
||
|
||
支持字段：`icon`、`min`、`max`
|
||
|
||
默认值 / 约束：
|
||
- `icon` 默认 `star`
|
||
- `icon` 可用：`star`、`heart`、`thumbsup`、`fire`、`smile`、`lightning`、`flower`、`number`
|
||
- `min` 取值 `0..1`，默认 `1`
|
||
- `max` 取值 `1..10`，默认 `5`
|
||
|
||
```json
|
||
{
|
||
"type": "number",
|
||
"name": "评分",
|
||
"style": { "type": "rating", "icon": "star", "min": 1, "max": 5 }
|
||
}
|
||
```
|
||
|
||
### 3.3 select
|
||
|
||
单选和多选都使用 `select`；用 `multiple` 区分。`multiple` 默认 `false`。静态选项用 `options`，动态选项用 `dynamic_options_source`；两者不要同时传。
|
||
|
||
#### 静态选项
|
||
|
||
支持字段：`multiple`、`options`
|
||
|
||
默认值 / 约束：
|
||
- `multiple` 默认 `false`
|
||
- `options` 最多 `10000` 项
|
||
- `options[]` 结构是 `{name, hue?, lightness?}`
|
||
- `options[].name` 必填
|
||
- `options[].hue` 可用：`Red`、`Orange`、`Yellow`、`Lime`、`Green`、`Turquoise`、`Wathet`、`Blue`、`Carmine`、`Purple`、`Gray` 缺省值为 `Blue`
|
||
- `options[].lightness` 可用：`Lighter`、`Light`、`Standard`、`Dark`、`Darker` 缺省值为 `Lighter`
|
||
- 选项里没有 `id`，只有 `name`。
|
||
|
||
```json
|
||
{
|
||
"type": "select",
|
||
"name": "状态",
|
||
"multiple": false,
|
||
"options": [
|
||
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
|
||
{ "name": "Done", "hue": "Green", "lightness": "Light" }
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 动态选项
|
||
|
||
支持字段：`multiple`、`dynamic_options_source`
|
||
|
||
默认值 / 约束：
|
||
- `multiple` 默认 `false`
|
||
- `dynamic_options_source` 结构是 `{table_id, field_id}`
|
||
- `dynamic_options_source.table_id` 填来源表 id 或表名
|
||
- `dynamic_options_source.field_id` 填来源字段 id 或字段名
|
||
- `dynamic_options_source` 仅创建支持；更新已有字段时不要传
|
||
- 引用选项条件 / 级联筛选条件：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
|
||
|
||
```json
|
||
{
|
||
"type": "select",
|
||
"name": "动态状态",
|
||
"multiple": false,
|
||
"dynamic_options_source": {
|
||
"table_id": "选项表",
|
||
"field_id": "候选状态"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 datetime
|
||
|
||
手动填写的日期/时间字段。系统时间用 `created_at` / `updated_at`。
|
||
|
||
最小写法：
|
||
|
||
```json
|
||
{
|
||
"type": "datetime",
|
||
"name": "截止时间"
|
||
}
|
||
```
|
||
|
||
支持字段：`style.format`
|
||
|
||
默认值 / 约束：
|
||
- `style.format` 默认 `yyyy/MM/dd` 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
|
||
|
||
常用写法：
|
||
|
||
```json
|
||
{
|
||
"type": "datetime",
|
||
"name": "截止时间",
|
||
"style": { "format": "yyyy-MM-dd HH:mm" }
|
||
}
|
||
```
|
||
|
||
### 3.5 created_at / updated_at
|
||
|
||
系统创建时间 / 系统更新时间字段；可配显示格式，但记录写入时应视为只读。
|
||
|
||
支持字段：`style.format`
|
||
|
||
默认值 / 约束：
|
||
- `style.format` 默认 `yyyy/MM/dd`
|
||
- 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
|
||
|
||
```json
|
||
{ "type": "created_at", "name": "创建时间" }
|
||
```
|
||
|
||
```json
|
||
{ "type": "updated_at", "name": "更新时间", "style": { "format": "yyyy/MM/dd HH:mm" } }
|
||
```
|
||
|
||
### 3.6 user / group_chat
|
||
|
||
人员字段和群字段都支持 `multiple`。
|
||
|
||
默认值 / 约束：
|
||
- `multiple` 默认 `true`
|
||
|
||
```json
|
||
{ "type": "user", "name": "负责人", "multiple": true }
|
||
```
|
||
|
||
```json
|
||
{ "type": "group_chat", "name": "负责群", "multiple": true }
|
||
```
|
||
|
||
### 3.7 created_by / updated_by
|
||
|
||
系统创建人 / 系统修改人字段；记录写入时应视为只读。
|
||
|
||
```json
|
||
{ "type": "created_by", "name": "创建人" }
|
||
```
|
||
|
||
```json
|
||
{ "type": "updated_by", "name": "更新人" }
|
||
```
|
||
|
||
### 3.8 link
|
||
|
||
关联字段；`link_table` 必填。
|
||
|
||
支持字段：`link_table`、`bidirectional`、`bidirectional_link_field_name`
|
||
|
||
默认值 / 约束：
|
||
- `link_table` 必填
|
||
- `link` 字段的单元格表示“当前记录关联到的对侧表记录集合”
|
||
- `bidirectional` 默认 `false`
|
||
- `bidirectional=true` 时，会在被关联表自动创建一个反向关联字段。任一侧记录的关联关系发生变更时，另一侧对应记录会自动同步更新
|
||
- `bidirectional_link_field_name` 仅在 `bidirectional=true` 时使用
|
||
- 关联字段筛选：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
|
||
|
||
```json
|
||
{
|
||
"type": "link",
|
||
"name": "关联任务",
|
||
"link_table": "任务表"
|
||
}
|
||
```
|
||
|
||
双向关联：
|
||
|
||
```json
|
||
{
|
||
"type": "link",
|
||
"name": "关联任务",
|
||
"link_table": "任务表",
|
||
"bidirectional": true,
|
||
"bidirectional_link_field_name": "反向关联"
|
||
}
|
||
```
|
||
|
||
更新时注意：
|
||
- `link` 不允许转换为其他类型，其他类型也不能转换为 `link`。
|
||
- 现有 `link` 字段的 `bidirectional` 不能改。
|
||
|
||
### 3.9 formula
|
||
|
||
公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
|
||
|
||
```json
|
||
{
|
||
"type": "formula",
|
||
"name": "合计",
|
||
"expression": "1+1"
|
||
}
|
||
```
|
||
|
||
### 3.10 lookup
|
||
|
||
查找引用字段；`from`、`select`、`where` 必填，`aggregate` 可选。创建/更新前先读 [lookup-field-guide.md](lookup-field-guide.md)。
|
||
|
||
支持字段：`from`、`select`、`where`、`aggregate`
|
||
|
||
默认值 / 约束：
|
||
- `from`、`select`、`where` 必填
|
||
- `aggregate` 默认 `raw_value` 代表不进行聚合，直接返回 select 回的原始值
|
||
- `aggregate` 可用：`raw_value`、`sum`、`average`、`counta`、`unique_counta`、`max`、`min`、`unique`
|
||
- `where.logic` 默认 `and`，仅支持 `and` / `or`
|
||
- `where.conditions` 至少 1 条
|
||
- `conditions` 每项是三元组 `[field, op, value?]`
|
||
|
||
```json
|
||
{
|
||
"type": "lookup",
|
||
"name": "状态汇总",
|
||
"from": "任务表",
|
||
"select": "状态",
|
||
"where": {
|
||
"logic": "and",
|
||
"conditions": [
|
||
["负责人", "==", { "type": "field_ref", "field": "当前负责人" }],
|
||
["状态", "non_empty", null]
|
||
]
|
||
},
|
||
"aggregate": "raw_value"
|
||
}
|
||
```
|
||
|
||
### 3.11 auto_number
|
||
|
||
自动编号字段；不写 `style.rules` 时使用默认规则：`NO.001`。
|
||
|
||
最小写法：
|
||
|
||
```json
|
||
{
|
||
"type": "auto_number",
|
||
"name": "编号"
|
||
}
|
||
```
|
||
|
||
支持字段：`style.rules`
|
||
|
||
默认值 / 约束：
|
||
- `style.rules` 是规则数组，数量 `1..9`
|
||
- 默认规则：
|
||
|
||
```json
|
||
{
|
||
"style": {
|
||
"rules": [
|
||
{ "type": "text", "text": "NO." },
|
||
{ "type": "incremental_number", "length": 3 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `text`
|
||
|
||
支持字段：`text`
|
||
|
||
```json
|
||
{ "type": "text", "text": "TASK-" }
|
||
```
|
||
|
||
#### `incremental_number`
|
||
|
||
支持字段：`length`
|
||
|
||
默认值 / 约束：
|
||
- `length` 取值 `1..9`
|
||
|
||
```json
|
||
{ "type": "incremental_number", "length": 4 }
|
||
```
|
||
|
||
#### `created_time`
|
||
|
||
支持字段：`date_format`
|
||
|
||
默认值 / 约束：
|
||
- `date_format` 可用：`yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`
|
||
|
||
```json
|
||
{ "type": "created_time", "date_format": "yyyyMMdd" }
|
||
```
|
||
|
||
自定义规则：
|
||
|
||
```json
|
||
{
|
||
"type": "auto_number",
|
||
"name": "编号",
|
||
"style": {
|
||
"rules": [
|
||
{ "type": "text", "text": "TASK-" },
|
||
{ "type": "created_time", "date_format": "yyyyMMdd" },
|
||
{ "type": "incremental_number", "length": 4 }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.12 attachment / location / checkbox
|
||
|
||
```json
|
||
{ "type": "attachment", "name": "附件" }
|
||
```
|
||
|
||
```json
|
||
{ "type": "location", "name": "位置" }
|
||
```
|
||
|
||
写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
|
||
|
||
```json
|
||
{ "type": "checkbox", "name": "完成" }
|
||
```
|
||
|
||
## 4. 创建与更新
|
||
|
||
- `+field-create`：按目标字段配置直接构造 `--json`。
|
||
- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。
|
||
|
||
## 5. 暂不支持字段
|
||
|
||
Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
|
||
|
||
## 6. 易错点
|
||
|
||
- `select` 只有一个类型；不要写 `single_select` / `multi_select`，用 `multiple` 控制是否多选。
|
||
- `number` 的精度、货币、进度、评分配置都放在 `style` 下，不要写顶层 `precision`。
|
||
- `datetime` 是手动日期字段；系统时间请改用 `created_at` / `updated_at`。
|
||
- `formula` / `lookup` 没读 guide 前不要直接写。
|