背景
当前协议(packages/spec/src/data/field.zod.ts)有 48 种字段类型,但没有独立的“用户/人员”字段类型。目前表达用户关系有两条路径:
- 作者侧:
Field.lookup('sys_user', {...}) —— 外键硬编码指向 sys_user 表。
- 系统侧:
object.zod.ts 中 systemFields 已为 owner(owner_id)和 audit(created_by/updated_by)预留了自动注入位,但标注为 "Reserved for future",尚未落地。
框架已隐含“人员引用是一等公民”的路线图,但缺少作者可声明的人员字段类型。
提案
新增 user 字段类型,作为 lookup 的薄封装/语义化特化(不是一套新的关系机制),由引擎解析到配置的身份对象(默认 sys_user)。
主流低代码平台(Salesforce Lookup(User)/Owner、飞书多维表“人员”、钉钉宜搭“成员”、Airtable Collaborator、Dataverse、Mendix)普遍把“人员”做成独立字段类型,原因是它承载了普通 lookup 给不了的语义:
| 能力 |
lookup('sys_user') |
专用 user |
| 表名解耦(better-auth / 外部 IdP / 自定义身份表) |
❌ 硬编码 |
✅ 引擎解析当前身份对象 |
默认当前登录用户 $currentUser |
❌ |
✅ |
| 人员选择器 UI(头像、目录搜索、@提及) |
自行约定 |
✅ 内建 |
| 与权限/记录归属(owner→行级共享)打通 |
❌ |
✅ |
| 通知/审批路由(assignee 自动通知) |
❌ |
✅ |
| 多人值 |
需 multiselect 拼凑 |
✅ multiple: true |
| 按组织/角色过滤可选人 |
需手写 filter |
✅ userScope |
建议设计
// FieldType enum 新增
'user', // 人员引用 —— 解析到配置的身份对象(默认 sys_user)
// Field 工厂
user: (config: FieldInput = {}) => ({ type: 'user', ...config } as const),
配套配置(复用现有 reference 体系):
multiple?: boolean —— 单人 / 多人
userScope?: 'org' | 'all' | 'role:<x>' —— 限定可选范围(多租户下默认本组织成员)
defaultValue: '$currentUser' —— 创建时默认当前用户
- 引擎层
reference 默认解析为身份对象,作者无需写死 sys_user
与已预留的 systemFields.owner/audit 对齐:系统侧的 owner_id/created_by 本质上就是 user 类型的实例,二者共用同一套解析与渲染,路线一致。
影响范围
packages/spec/src/data/field.zod.ts:enum + Field.user 工厂 + 配置项
- 文档:
content/docs/guides/cheatsheets/field-type-gallery.mdx、skills/objectstack-data/rules/field-types.md
- 后续(可分阶段):REST、
$expand、校验、UI 渲染器、权限/通知联动
需要权衡
- 类型表面积:REST、
$expand、校验、UI 渲染都需新增 user 分支。
- 冗余风险:需明确文档——人员引用一律用
user,不再用 lookup('sys_user'),避免两种写法并存。
- 身份子系统耦合:
user 做成“引用身份”,避免把 auth 逻辑泄漏进通用字段层。
建议落地范围(MVP)
先只做协议层(spec)最小闭环:user 类型 enum + Field.user 工厂(含 multiple 与 $currentUser)+ 文档。权限/通知联动后续迭代。
背景
当前协议(
packages/spec/src/data/field.zod.ts)有 48 种字段类型,但没有独立的“用户/人员”字段类型。目前表达用户关系有两条路径:Field.lookup('sys_user', {...})—— 外键硬编码指向sys_user表。object.zod.ts中systemFields已为owner(owner_id)和audit(created_by/updated_by)预留了自动注入位,但标注为 "Reserved for future",尚未落地。框架已隐含“人员引用是一等公民”的路线图,但缺少作者可声明的人员字段类型。
提案
新增
user字段类型,作为lookup的薄封装/语义化特化(不是一套新的关系机制),由引擎解析到配置的身份对象(默认sys_user)。主流低代码平台(Salesforce Lookup(User)/Owner、飞书多维表“人员”、钉钉宜搭“成员”、Airtable Collaborator、Dataverse、Mendix)普遍把“人员”做成独立字段类型,原因是它承载了普通 lookup 给不了的语义:
lookup('sys_user')user$currentUsermultiple: trueuserScope建议设计
配套配置(复用现有 reference 体系):
multiple?: boolean—— 单人 / 多人userScope?: 'org' | 'all' | 'role:<x>'—— 限定可选范围(多租户下默认本组织成员)defaultValue: '$currentUser'—— 创建时默认当前用户reference默认解析为身份对象,作者无需写死sys_user与已预留的
systemFields.owner/audit对齐:系统侧的 owner_id/created_by 本质上就是user类型的实例,二者共用同一套解析与渲染,路线一致。影响范围
packages/spec/src/data/field.zod.ts:enum +Field.user工厂 + 配置项content/docs/guides/cheatsheets/field-type-gallery.mdx、skills/objectstack-data/rules/field-types.md$expand、校验、UI 渲染器、权限/通知联动需要权衡
$expand、校验、UI 渲染都需新增user分支。user,不再用lookup('sys_user'),避免两种写法并存。user做成“引用身份”,避免把 auth 逻辑泄漏进通用字段层。建议落地范围(MVP)
先只做协议层(spec)最小闭环:
user类型 enum +Field.user工厂(含multiple与$currentUser)+ 文档。权限/通知联动后续迭代。