Repository navigation
Expand file tree
/
Copy pathsys-approval-delegation.object.ts
More file actions
188 lines (173 loc) · 8.16 KB
/
Copy pathsys-approval-delegation.object.ts
File metadata and controls
188 lines (173 loc) · 8.16 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
import { ObjectSchema, Field } from '@objectstack/spec/data';
import { F } from '@objectstack/spec';
/**
* sys_approval_delegation — self-service out-of-office (OOO) delegation (#1322 M1).
*
* A standing, self-declared rule: "while I (the delegator) am out between
* `valid_from` and `valid_until`, route the approver slots that would resolve
* to me onto my delegate instead." The approval service consults active rows
* in `ApprovalService.expandApprovers` when resolving an approval node's
* INDIVIDUALLY-routed approvers (`type: user` / `field` / `manager`) — the
* delegate becomes a real pending approver and acts under their own identity,
* so nothing is impersonated and the audit trail stays honest.
*
* Modelled as its own object (not a scalar on the better-auth-locked
* `sys_user`), mirroring the `sys_user_position` delegation precedent
* (ADR-0091): the validity window is enforced at RESOLUTION time via the
* shared `isGrantActive` predicate — never by a background job (ADR-0049).
* The window is half-open `[valid_from, valid_until)` in UTC.
*
* `organization_id` is the organization the delegation belongs to: it
* reroutes only the approvals opened in that organization, and an
* organization-less row reroutes none (ADR-0131 D1;
* `ApprovalService.lookupActiveDelegation`).
*
* Scope note: this is the community-core OOO auto-skip only. Long-term proxy
* "act-as" access (viewing/acting on another user's full queue under their
* authority), delegation governance / segregation-of-duties, and org-wide
* administration of others' delegations are enterprise concerns tracked
* separately (objectstack-ai/cloud#855), not here.
*
* @namespace sys
*/
export const SysApprovalDelegation = ObjectSchema.create({
name: 'sys_approval_delegation',
label: 'Approval Delegation',
pluralLabel: 'Approval Delegations',
icon: 'user-clock',
isSystem: true,
// [ADR-0103, #3355] Admin/user-writable DATA on a platform-defined schema: a
// user authors their own out-of-office delegation. The bucket default is full
// CRUD (matching the full-CRUD apiMethods below), so no `userActions` block is
// needed — RLS/permission sets are the authz.
managedBy: 'system-data',
// The sentence Setup shows under the "Delegations (OOO)" title. It says
// "assigned to them personally" because only individually-routed approvers
// (`user` / `field` / `manager`) are rerouted; team, department, position and
// membership-level approvers are not (`ApprovalService.expandApprovers`).
description: 'While someone is away, approvals assigned to them personally go to their delegate.',
// [ADR-0079] The record title is `display_title`, a text formula over the
// same two columns `titleFormat` named. With no pointer declared, the
// registry's designate-only pass stamped `nameField: 'id'` (the first
// title-eligible field), so a renderer honouring ADR-0079's order (an
// explicit `nameField` wins over `titleFormat`) drew the raw id as the record
// page's H1. The retired `titleFormat` template beside it is gone (refused at
// save and by `os validate`); `sys-approval-delegation-display-title.test.ts`
// holds the formula to the text that template drew.
displayNameField: 'display_title',
nameField: 'display_title', // [ADR-0079] canonical primary-title pointer (mirrors deprecated displayNameField)
highlightFields: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until'],
listViews: {
active: {
type: 'grid',
name: 'active',
label: 'Active',
data: { provider: 'object', object: 'sys_approval_delegation' },
columns: ['delegator_id', 'delegate_id', 'valid_from', 'valid_until', 'reason'],
sort: [{ field: 'valid_until', order: 'asc' }],
pagination: { pageSize: 50 },
emptyState: {
title: 'No delegations',
message: 'Declare an out-of-office delegation so approvals route to a backup while you are away.',
},
},
},
fields: {
id: Field.text({ label: 'Delegation ID', required: true, readonly: true, group: 'System' }),
// [ADR-0079] The record title (`nameField` above). A formula is computed on
// read and has no stored column. Both source columns are required, so the
// expression needs no null guard.
display_title: Field.formula({
label: 'Title',
returnType: 'text',
expression: F`record.delegator_id + ' → ' + record.delegate_id`,
description: 'Record title: the delegator and the delegate (computed on read)',
group: 'Delegation',
}),
// A delegation names its own author as delegator: on every non-system
// write `bindDelegationWriteGuard` (lifecycle-hooks.ts) admits exactly one
// value here, the acting user, and refuses any other with 403 (its
// docstring holds why there is no admin exemption). So the picker offers
// that one value, instead of every user with all but one refused:
// `lookupFilters` is the picker's candidate query, and the engine resolves
// `{current_user_id}` against the caller on every read. Presentation only
// — the guard stays the enforcement, and what a write may store is
// unchanged. Since that one value is always the acting user, the field
// also defaults to it: `defaultValue: 'current_user'` is the spec's
// runtime token for a `sys_user` lookup (`DEFAULT_VALUE_TOKENS`), so a new
// delegation opens with the Delegator already filled instead of at an
// empty picker. Pinned in `sys-approval-delegation-delegator-picker.test.ts`.
delegator_id: Field.lookup('sys_user', {
label: 'Delegator',
required: true,
defaultValue: 'current_user',
lookupFilters: [{ field: 'id', operator: 'eq', value: '{current_user_id}' }],
group: 'Delegation',
description:
'The user going out of office. You can delegate only your own approvals, so this is always you: '
+ 'it starts as you and offers no one else. Their individually-routed approver slots are rerouted while active.',
}),
delegate_id: Field.lookup('sys_user', {
label: 'Delegate',
required: true,
group: 'Delegation',
description: 'The backup who receives the delegator\'s approvals while this rule is active. Acts under their own identity.',
}),
// [ADR-0091 D2] `isGrantActive` is the shared validity predicate.
valid_from: Field.datetime({
label: 'Valid From',
required: false,
group: 'Delegation',
description:
'Rule is inactive before this instant. Null = active immediately. ' +
'Checked each time an approval is routed, so the rule starts on time without any scheduled job.',
}),
valid_until: Field.datetime({
label: 'Valid Until',
required: false,
group: 'Delegation',
description:
'The rule stops applying at this time (UTC). Leave empty for no end date.',
}),
reason: Field.text({
label: 'Reason',
required: false,
maxLength: 500,
group: 'Delegation',
description: 'Why the delegation exists (e.g. "Annual leave 5/26–5/30"). Recorded on the substitution audit row.',
}),
organization_id: Field.lookup('sys_organization', {
label: 'Organization',
required: false,
group: 'System',
description: 'The organization this delegation belongs to. It reroutes only the approvals opened in this organization.',
}),
created_at: Field.datetime({
label: 'Created At',
defaultValue: 'NOW()',
readonly: true,
group: 'System',
}),
updated_at: Field.datetime({
label: 'Updated At',
defaultValue: 'NOW()',
readonly: true,
group: 'System',
}),
},
indexes: [
// Resolution-time lookup: "active delegations for this delegator".
{ fields: ['delegator_id', 'organization_id'] },
{ fields: ['delegate_id'] },
{ fields: ['valid_until'] },
],
enable: {
trackHistory: true,
searchable: true,
apiEnabled: true,
// `bulk` = the batch shape of the verbs above; the gate is `bulk ∧ child`
// (#3391 P1), so omitting it 405s /batch and the *Many routes (#3026).
apiMethods: ['get', 'list', 'create', 'update', 'delete', 'bulk'],
},
});