shutro-erp 0.3.6 → 0.3.7

package/dist/permissions/approvals.js

@@ -1,7 +1,14 @@
 import { audit, HttpProblem } from '../server/index.js';
 const ref = (env, name) => env.model(name);
 /** Many-to-many fields read here: loaded by the object spec (defaults plus the relation), read as ids. */
-const MANY = new Set(['approvers', 'approverUsers']);
+const MANY = new Set([
+    'approvers',
+    'backups',
+    'approverUsers',
+    'extraUsers',
+    'backupUsers',
+    'companies',
+]);
 const specOf = (keys) => keys.some((k) => MANY.has(k))
     ? Object.fromEntries(keys.filter((k) => MANY.has(k)).map((k) => [k, true]))
     : keys;
@@ -11,6 +18,9 @@ async function find(env, model, where, keys, order) {
 }
 const REQUEST_KEYS = [
     'dueAt',
+    'backups',
+    'startedAt',
+    'explanation',
     'escalatedTo',
     'approvers',
     'required',
@@ -40,6 +50,7 @@ function info(row) {
         company: row['company'] ?? null,
         approverRole: String(row['approverRole'] ?? ''),
         approvers: Array.isArray(row['approvers']) ? row['approvers'] : [],
+        backups: Array.isArray(row['backups']) ? row['backups'] : [],
         required: Number(row['required'] ?? 1),
         approvals: Number(row['approvals'] ?? 0),
         round: Number(row['round'] ?? 1),
@@ -51,6 +62,12 @@ function info(row) {
         escalatedTo: typeof row['escalatedTo'] === 'string' && row['escalatedTo'] !== ''
             ? row['escalatedTo']
             : null,
+        startedAt: row['startedAt'] instanceof Date
+            ? row['startedAt'].toISOString()
+            : typeof row['startedAt'] === 'string'
+                ? row['startedAt']
+                : null,
+        explanation: row['explanation'] ?? null,
         state: row['state'],
         requestedBy: row['requestedBy'] ?? null,
         decidedBy: row['decidedBy'] ?? null,
@@ -112,36 +129,210 @@ async function userIn(su, model, id, field) {
     }
 }
 /**
- * Who decides a level, and how many approvals it needs: named people, a manager or a field's person (the role when
- * there is nobody), a role's holders when all or a number of them must approve; never the requester.
+ * The user in a field of the requester's employee: the field's employee's user (`unitHead`, `coach`), or the user
+ * itself (`expenseApprover`); null when there is none or Workforce is not installed.
+ */
+async function employeePerson(su, requester, field) {
+    let me;
+    try {
+        [me] = await find(su, 'hr.employee', { user: requester }, [field], ['id asc']);
+    }
+    catch {
+        return null;
+    }
+    const value = me?.[field];
+    if (me === undefined || typeof value !== 'number')
+        return null;
+    try {
+        // A field to an employee: that employee's user.
+        const [row] = (await ref(su, 'hr.employee')
+            .browse([me['id']])
+            .load({ [field]: { user: true } }));
+        return row?.[field]?.user?.id ?? null;
+    }
+    catch {
+        // A field to a user: the user.
+        return value;
+    }
+}
+/** The requester's employee in Workforce, with its department (null when Workforce is not installed or none). */
+async function employeeOf(su, requester) {
+    try {
+        const [me] = await find(su, 'hr.employee', { user: requester }, ['name', 'department'], ['id asc']);
+        if (me === undefined)
+            return null;
+        return {
+            name: String(me['name']),
+            department: typeof me['department'] === 'number' ? me['department'] : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** The head of a department and its approvers, with its name. */
+async function departmentOf(su, id) {
+    const set = await ref(su, 'hr.department').search({ where: { id } });
+    const [row] = set.length === 0
+        ? []
+        : (await set.load({ approvalUsers: true })).read(['name', 'head', 'approvalUsers']);
+    const headEmployee = typeof row?.['head'] === 'number' ? row['head'] : null;
+    const [head] = headEmployee === null ? [] : await find(su, 'hr.employee', { id: headEmployee }, ['user']);
+    return {
+        name: String(row?.['name'] ?? id),
+        head: typeof head?.['user'] === 'number' ? head['user'] : null,
+        approvers: Array.isArray(row?.['approvalUsers']) ? row['approvalUsers'] : [],
+    };
+}
+/** The people the record names for a level (its model's `approvalUsers(key)`), or null when it names none. */
+async function recordApprovers(su, model, id, key) {
+    const record = ref(su, model).browse([id]);
+    if (typeof record.approvalUsers !== 'function')
+        return null;
+    return [...((await record.approvalUsers(key)).get(id) ?? [])];
+}
+/** People's names, for explanations. */
+async function namesOf(su, ids) {
+    if (ids.length === 0)
+        return 'nobody';
+    const rows = await find(su, 'res.users', { id: { in: [...ids] } }, ['name']);
+    const by = new Map(rows.map((r) => [r['id'], String(r['name'])]));
+    return ids.map((u) => by.get(u) ?? `#${u}`).join(', ');
+}
+/**
+ * Who decides a level, how many approvals it needs and how they were found (RFC 0027 §2.1): named people, the
+ * requester's manager, their department's head or approvers, a field's person, the people the record names — plus
+ * the level's extra people —; a role's holders for a role, and when all or a number of them must approve. Never the
+ * requester. `nobody` when no one can decide (the policy's `whenNobody` decides what then).
  */
 async function approversOf(su, level, target, requester) {
     const role = typeof level['approverRole'] === 'string' ? level['approverRole'] : '';
+    const notes = [];
     let people = [];
-    const kind = level['approverKind'] ?? 'role';
-    if (kind === 'users')
+    const kind = String(level['approverKind'] ?? 'role');
+    const who = await namesOf(su, [requester]);
+    if (kind === 'users') {
         people = level['approverUsers'] ?? [];
+        notes.push(`Named people: ${await namesOf(su, people)}.`);
+    }
     else if (kind === 'manager') {
         const manager = await managerOf(su, requester);
         if (manager !== null)
             people = [manager];
+        notes.push(manager === null
+            ? `${who} has no manager with a user in Workforce.`
+            : `${who}’s manager: ${await namesOf(su, people)}.`);
+    }
+    else if (kind === 'department_head' || kind === 'department_approvers') {
+        const employee = await employeeOf(su, requester);
+        if (employee === null)
+            notes.push(`${who} is not an employee in Workforce.`);
+        else if (employee.department === null)
+            notes.push(`${employee.name} has no department.`);
+        else {
+            const department = await departmentOf(su, employee.department);
+            if (kind === 'department_head') {
+                if (department.head !== null)
+                    people = [department.head];
+                notes.push(department.head === null
+                    ? `${department.name} has no head with a user.`
+                    : `${department.name}’s head: ${await namesOf(su, people)}.`);
+            }
+            else {
+                people = department.approvers;
+                notes.push(`${department.name}’s approvers: ${await namesOf(su, people)}.`);
+            }
+        }
+    }
+    else if (kind === 'employee') {
+        // A person on the requester's employee record (RFC 0032 §3.2): their unit head, coach, expense approver…
+        const field = String(level['approverField'] ?? '');
+        const person = await employeePerson(su, requester, field);
+        if (person !== null)
+            people = [person];
+        notes.push(person === null
+            ? `${who} has no ${field} with a user in Workforce.`
+            : `${who}’s ${field}: ${await namesOf(su, people)}.`);
     }
     else if (kind === 'field') {
-        const person = await userIn(su, target.model, target.id, String(level['approverField'] ?? ''));
+        const field = String(level['approverField'] ?? '');
+        const person = await userIn(su, target.model, target.id, field);
         if (person !== null)
             people = [person];
+        notes.push(`The record’s ${field}: ${await namesOf(su, people)}.`);
+    }
+    else if (kind === 'record') {
+        const named = await recordApprovers(su, target.model, target.id, String(level['approverField'] ?? ''));
+        people = named ?? [];
+        notes.push(named === null
+            ? `${target.model} names no approvers.`
+            : `Named by the record: ${await namesOf(su, people)}.`);
     }
+    // A role decides a role level, and stands in when nobody else was found.
+    const roleHolders = role === '' ? [] : (await holders(su, role, target.company)).filter((u) => u !== requester);
+    const extra = level['extraUsers'] ?? [];
+    if (extra.length > 0) {
+        // A role with extra people: its holders by name, beside them.
+        if (kind === 'role') {
+            people = roleHolders;
+            notes.push(`Role ${role}: ${await namesOf(su, roleHolders)}.`);
+        }
+        people = [...new Set([...people, ...extra])];
+        notes.push(`Also: ${await namesOf(su, extra)}.`);
+    }
+    if (people.includes(requester))
+        notes.push(`${who} asked, so does not decide.`);
     people = people.filter((u) => u !== requester);
     const quorum = level['quorum'] ?? 'any';
-    if (people.length === 0 && quorum !== 'any' && role !== '')
-        people = (await holders(su, role, target.company)).filter((u) => u !== requester);
+    const byRole = people.length === 0 && role !== '';
+    if (byRole) {
+        notes.push(kind === 'role'
+            ? `Role ${role}: ${roleHolders.length} ${roleHolders.length === 1 ? 'person' : 'people'} in the company.`
+            : `Instead, role ${role}: ${roleHolders.length} ${roleHolders.length === 1 ? 'person' : 'people'} in the company.`);
+        if (roleHolders.length === 0)
+            notes.push('Nobody holds it yet: administrators decide.');
+        if (quorum !== 'any')
+            people = roleHolders;
+    }
     const count = Math.max(1, Number(level['quorumCount'] ?? 1));
     const required = quorum === 'all'
         ? Math.max(1, people.length)
         : quorum === 'count'
             ? Math.min(count, Math.max(1, people.length))
             : 1;
-    return { role: people.length > 0 && kind === 'users' ? '' : role, approvers: people, required };
+    return {
+        role: byRole ? role : '',
+        approvers: people,
+        required,
+        explanation: notes,
+        // A role always has someone: administrators decide a role nobody holds yet.
+        nobody: people.length === 0 && !byRole,
+    };
+}
+/** A company's segment (RFC 0027 §2.3), or null. */
+async function segmentOf(su, company) {
+    if (company === null)
+        return null;
+    const segments = await find(su, 'res.segment', { active: true }, ['companies']);
+    const mine = segments.find((s) => (s['companies'] ?? []).includes(company));
+    return mine === undefined ? null : mine['id'];
+}
+/** Whether a policy covers a company: its company, its companies and its segment's together; none: every company. */
+function covers(policy, company, segment) {
+    const one = typeof policy['company'] === 'number' ? policy['company'] : null;
+    const many = Array.isArray(policy['companies']) ? policy['companies'] : [];
+    const group = typeof policy['segment'] === 'number' ? policy['segment'] : null;
+    if (one === null && many.length === 0 && group === null)
+        return true;
+    if (company === null)
+        return false;
+    return one === company || many.includes(company) || (group !== null && group === segment);
+}
+/** The active policies of a model that cover a company, in order. */
+async function policiesFor(su, model, company, keys) {
+    const segment = await segmentOf(su, company);
+    const rows = await find(su, 'approval.policy', { targetModel: model }, [...keys, 'company', 'companies', 'segment'], ['sequence asc', 'id asc']);
+    return rows.filter((p) => covers(p, company, segment));
 }
 /** The record's company, when the model has one. */
 async function companyOf(su, model, id) {
@@ -158,6 +349,199 @@ async function companyOf(su, model, id) {
  * and levels; earlier pending requests of the records are cancelled (a resubmission starts a new round). Returns
  * the number of requests created.
  */
+/** Whether record `id` of `model` meets `condition` (a Shutro domain; empty: always). */
+async function matches(su, model, id, condition) {
+    if (condition === null || Object.keys(condition).length === 0)
+        return true;
+    return ((await ref(su, model).search({ where: { and: [{ id }, condition] }, limit: 1 })).length > 0);
+}
+/**
+ * Which of the last `limit` records of the policy's model each of its levels would have asked about (RFC 0025 step
+ * 4: the editor's preview), as the system; the policy's own condition first.
+ */
+export async function previewPolicy(su, policyId, limit = 50) {
+    const [policy] = await find(su, 'approval.policy', { id: policyId }, [
+        'targetModel',
+        'condition',
+        'company',
+        'companies',
+        'segment',
+    ]);
+    if (policy === undefined)
+        throw new HttpProblem(404, 'missing-record', 'Not found', 'No such policy.');
+    const model = String(policy['targetModel']);
+    const recent = await ref(su, model).search({
+        where: policy['condition'] ?? {},
+        order: ['id desc'],
+        limit,
+    });
+    const ids = recent.ids;
+    const levels = await find(su, 'approval.level', { policy: policyId }, ['name', 'condition'], ['sequence asc', 'id asc']);
+    const out = [];
+    for (const level of levels) {
+        const condition = level['condition'];
+        const matched = ids.length === 0
+            ? []
+            : condition === null || Object.keys(condition).length === 0
+                ? ids
+                : (await ref(su, model).search({ where: { and: [{ id: { in: ids } }, condition] } }))
+                    .ids;
+        out.push({ id: level['id'], name: String(level['name']), matched });
+    }
+    // The companies it covers: its company, its companies and its segment's, or every company.
+    const ids2 = new Set(Array.isArray(policy['companies']) ? policy['companies'] : []);
+    if (typeof policy['company'] === 'number')
+        ids2.add(policy['company']);
+    if (typeof policy['segment'] === 'number')
+        for (const s of await find(su, 'res.segment', { id: policy['segment'] }, ['companies']))
+            for (const c of s['companies'] ?? [])
+                ids2.add(c);
+    const all = ids2.size === 0 &&
+        typeof policy['segment'] !== 'number' &&
+        typeof policy['company'] !== 'number';
+    const names = ids2.size === 0
+        ? []
+        : (await find(su, 'res.company', { id: { in: [...ids2] } }, ['name'], ['name asc'])).map((c) => String(c['name']));
+    return { records: ids.length, levels: out, covers: { all, companies: names } };
+}
+/** Writes steps to the matrix log (RFC 0027 §2.5). */
+async function logEvents(su, events) {
+    if (events.length === 0)
+        return;
+    const at = new Date();
+    await ref(su, 'approval.event').create(events.map((e) => ({
+        request: e.request,
+        kind: e.kind,
+        user: e.user ?? null,
+        note: e.note === undefined || e.note === '' ? null : e.note,
+        at: e.at ?? at,
+    })));
+}
+/**
+ * Starts the levels whose turn it is and that have not started: `startedAt` now, the deadline counted from it
+ * (RFC 0027 §2.5), logged.
+ */
+async function startTurn(su, model, id, now) {
+    const turn = (await turnOf(su, model, id)).filter((r) => r.startedAt === null);
+    if (turn.length === 0)
+        return;
+    const rows = await find(su, 'approval.request', { id: { in: turn.map((r) => r.id) } }, ['level']);
+    const levelIds = rows.map((r) => r['level']).filter((l) => typeof l === 'number');
+    const levels = levelIds.length === 0
+        ? []
+        : await find(su, 'approval.level', { id: { in: levelIds } }, ['deadlineHours']);
+    const hours = new Map(levels.map((l) => [l['id'], Number(l['deadlineHours'] ?? 0)]));
+    for (const row of rows) {
+        const h = typeof row['level'] === 'number' ? (hours.get(row['level']) ?? 0) : 0;
+        await ref(su, 'approval.request')
+            .browse([row['id']])
+            .write({
+            startedAt: now,
+            ...(h > 0 ? { dueAt: new Date(now.getTime() + h * 3_600_000) } : {}),
+        });
+    }
+    await logEvents(su, turn.map((r) => ({ request: r.id, kind: 'started', at: now })));
+    await skipDuplicates(su, model, id, turn, now);
+}
+/**
+ * Skip approvers who already approved (RFC 0027 §2.2): for the levels just started, under a policy that asks for it,
+ * the approval of someone who approved an earlier level of this round counts here too — a vote marked `auto` —;
+ * a level that reaches its quorum this way is approved and the next turn starts (the record approved when it was
+ * the last).
+ */
+async function skipDuplicates(su, model, id, started, now) {
+    const policyIds = [
+        ...new Set(started.map((r) => r.policy).filter((p) => p !== null)),
+    ];
+    if (policyIds.length === 0)
+        return;
+    const skipping = new Set((await find(su, 'approval.policy', { id: { in: policyIds }, skipDuplicates: true }, ['id'])).map((p) => p['id']));
+    if (skipping.size === 0)
+        return;
+    const round = await currentRequests(su, model, id);
+    const earlier = round.filter((r) => r.state === 'approved');
+    if (earlier.length === 0)
+        return;
+    const votes = await find(su, 'approval.vote', { request: { in: earlier.map((r) => r.id) }, decision: 'approve' }, ['request', 'user']);
+    let approvedAny = false;
+    for (const request of started) {
+        if (request.policy === null || !skipping.has(request.policy))
+            continue;
+        const already = new Set((await find(su, 'approval.vote', { request: request.id }, ['user'])).map((v) => v['user']));
+        const allowed = new Set([
+            ...request.approvers,
+            ...request.backups,
+            ...(request.approvers.length === 0 && request.approverRole !== ''
+                ? await holders(su, request.approverRole, request.company)
+                : []),
+        ]);
+        let approvals = request.approvals;
+        let last = null;
+        for (const v of votes) {
+            const user = v['user'];
+            if (approvals >= request.required)
+                break;
+            if (user === request.requestedBy || already.has(user) || !allowed.has(user))
+                continue;
+            const level = earlier.find((r) => r.id === v['request'])?.levelName ?? '';
+            await ref(su, 'approval.vote').create([
+                {
+                    request: request.id,
+                    user,
+                    decision: 'approve',
+                    comment: `Approved already at ${level}.`,
+                    at: now,
+                    auto: true,
+                },
+            ]);
+            await logEvents(su, [
+                { request: request.id, kind: 'auto', user, note: `Approved already at ${level}.`, at: now },
+            ]);
+            already.add(user);
+            approvals += 1;
+            last = user;
+        }
+        if (approvals >= request.required && last !== null) {
+            await ref(su, 'approval.request')
+                .browse([request.id])
+                .write({ state: 'approved', decidedBy: last, decidedAt: now });
+            approvedAny = true;
+        }
+    }
+    if (!approvedAny)
+        return;
+    const after = await currentRequests(su, model, id);
+    if (after.every((r) => r.state === 'approved')) {
+        await su.emit('approval.decided', { model, id, state: 'approved', final: true });
+        for (const pid of new Set(after.map((r) => r.policy).filter((p) => p !== null))) {
+            const [policy] = await find(su, 'approval.policy', { id: pid }, ['onApproved']);
+            await runTransition(su, { model, id }, policy?.['onApproved']);
+        }
+        return;
+    }
+    await su.emit('approval.decided', { model, id, state: 'approved', final: false });
+    await startTurn(su, model, id, now);
+}
+/** The matrix log of a record's requests, when `env` may read the record. */
+export async function eventsOf(env, model, id) {
+    await ref(env, model).browse([id]).load(['id']); // as the caller: ACL and rules decide
+    return env.asSuperuser({ reason: 'approval log' }, async (su) => {
+        const requests = await find(su, 'approval.request', { targetModel: model, targetId: id }, [
+            'id',
+        ]);
+        if (requests.length === 0)
+            return [];
+        const rows = await find(su, 'approval.event', { request: { in: requests.map((r) => r['id']) } }, ['request', 'at', 'user', 'kind', 'note'], ['at asc', 'id asc']);
+        return rows.map((r) => ({
+            id: r['id'],
+            request: r['request'],
+            at: r['at'] instanceof Date ? r['at'].toISOString() : String(r['at']),
+            user: r['user'] ?? null,
+            kind: String(r['kind']),
+            note: r['note'] ?? null,
+        }));
+    });
+}
 export async function requestApprovals(records) {
     const { env, modelName, ids } = records;
     const requester = env.uid;
@@ -167,14 +551,28 @@ export async function requestApprovals(records) {
             const stale = await ref(su, 'approval.request').search({
                 where: { targetModel: modelName, targetId: id, state: 'pending' },
             });
-            if (stale.length > 0)
+            if (stale.length > 0) {
                 await stale.write({ state: 'cancelled' });
+                await logEvents(su, stale.ids.map((request) => ({
+                    request,
+                    kind: 'cancelled',
+                    user: requester,
+                    note: 'Submitted again.',
+                })));
+            }
             const [last] = await find(su, 'approval.request', { targetModel: modelName, targetId: id }, ['round'], ['round desc']);
             const round = Number(last?.['round'] ?? 0) + 1;
             const company = (await companyOf(su, modelName, id)) ?? env.companyId;
-            const policies = await find(su, 'approval.policy', { targetModel: modelName, or: [{ company: null }, { company }] }, ['name'], ['sequence asc', 'id asc']);
+            const policies = await policiesFor(su, modelName, company, [
+                'name',
+                'condition',
+                'whenNobody',
+            ]);
             const rows = [];
             for (const policy of policies) {
+                // A policy for some records only (a request category's): the record must match its condition.
+                if (!(await matches(su, modelName, id, policy['condition'])))
+                    continue;
                 const levels = await find(su, 'approval.level', { policy: policy['id'] }, [
                     'sequence',
                     'name',
@@ -182,20 +580,21 @@ export async function requestApprovals(records) {
                     'approverKind',
                     'approverRole',
                     'approverUsers',
+                    'extraUsers',
+                    'backupUsers',
                     'approverField',
                     'quorum',
                     'quorumCount',
                     'deadlineHours',
                 ], ['sequence asc', 'id asc']);
                 for (const level of levels) {
-                    const condition = level['condition'];
-                    const applies = condition === null ||
-                        Object.keys(condition).length === 0 ||
-                        (await ref(su, modelName).search({ where: { and: [{ id }, condition] }, limit: 1 }))
-                            .length > 0;
-                    if (!applies)
+                    if (!(await matches(su, modelName, id, level['condition'])))
                         continue;
                     const who = await approversOf(su, level, { model: modelName, id, company }, requester);
+                    const whenNobody = String(policy['whenNobody'] ?? 'refuse');
+                    if (who.nobody && whenNobody === 'refuse')
+                        refuse(422, 'no-approver', 'Nobody to approve', `Nobody can decide the level “${String(level['name'])}” of “${String(policy['name'])}”. ${who.explanation.join(' ')}`, 'Set who approves (Workforce: the manager or the department), or change the approval policy.');
+                    const skipped = who.nobody && whenNobody === 'skip';
                     rows.push({
                         policy: policy['id'],
                         level: level['id'],
@@ -206,19 +605,44 @@ export async function requestApprovals(records) {
                         company,
                         approverRole: who.role,
                         approvers: { set: who.approvers },
+                        backups: {
+                            set: (level['backupUsers'] ?? []).filter((u) => u !== requester),
+                        },
                         required: who.required,
                         round,
-                        ...(typeof level['deadlineHours'] === 'number' && level['deadlineHours'] > 0
-                            ? { dueAt: new Date(Date.now() + level['deadlineHours'] * 3_600_000) }
-                            : {}),
+                        explanation: [
+                            ...who.explanation,
+                            ...((level['backupUsers'] ?? []).length > 0
+                                ? [
+                                    `Backups: ${await namesOf(su, level['backupUsers'].filter((u) => u !== requester))}.`,
+                                ]
+                                : []),
+                            ...(skipped ? ['Nobody could decide: the level is skipped.'] : []),
+                        ].join(' '),
+                        ...(skipped ? { state: 'approved', decidedAt: new Date() } : {}),
                         requestedBy: requester,
                     });
                 }
             }
             if (rows.length === 0)
                 continue;
-            await ref(su, 'approval.request').create(rows);
+            const made = await ref(su, 'approval.request').create(rows);
             created += rows.length;
+            const now = new Date();
+            await logEvents(su, made.ids.map((request, i) => ({
+                request,
+                kind: rows[i]?.['state'] === 'approved' ? 'skipped' : 'created',
+                user: requester,
+                note: String(rows[i]?.['explanation'] ?? ''),
+                at: now,
+            })));
+            await startTurn(su, modelName, id, now);
+            // Every level skipped (nobody to ask, the policy says skip): approved now.
+            if (rows.every((r) => r['state'] === 'approved'))
+                for (const pid of new Set(rows.map((r) => r['policy']))) {
+                    const [policy] = await find(su, 'approval.policy', { id: pid }, ['onApproved']);
+                    await runTransition(su, { model: modelName, id }, policy?.['onApproved']);
+                }
             await audit(su, {
                 kind: 'approval.requested',
                 summary: `${rows.length} approval(s) requested for ${modelName} ${id}.`,
@@ -294,7 +718,7 @@ const holds = (roles, role, company) => role !== '' &&
  * the escalation role once it is late —, or for someone away who delegated to them (`{ for: <user> }`); null when not.
  */
 function approverFor(who, request) {
-    if (request.approvers.includes(who.uid))
+    if (request.approvers.includes(who.uid) || request.backups.includes(who.uid))
         return { for: null };
     if (request.approvers.length === 0 && (who.administrator || who.groups.has(request.approverRole)))
         return { for: null };
@@ -303,7 +727,7 @@ function approverFor(who, request) {
     for (const d of who.delegators) {
         if (d.user === request.requestedBy)
             continue;
-        if (request.approvers.includes(d.user))
+        if (request.approvers.includes(d.user) || request.backups.includes(d.user))
             return { for: d.user };
         if (request.approvers.length === 0 && holds(d.roles, request.approverRole, request.company))
             return { for: d.user };
@@ -401,6 +825,9 @@ export async function decide(env, requestId, decision, comment, from) {
                 at: new Date(),
                 onBehalfOf,
                 ip: from?.ip ?? null,
+                asBackup: onBehalfOf === null &&
+                    request.backups.includes(actor) &&
+                    !request.approvers.includes(actor),
             },
         ]);
         const approvals = request.approvals + (decision === 'approve' ? 1 : 0);
@@ -420,12 +847,29 @@ export async function decide(env, requestId, decision, comment, from) {
                 ? {}
                 : { decidedBy: actor, decidedAt: new Date(), comment: text === '' ? null : text }),
         });
+        await logEvents(su, [
+            {
+                request: request.id,
+                kind: state === 'pending' ? 'voted' : state,
+                user: actor,
+                note: [onBehalfOf === null ? '' : `For user ${onBehalfOf}.`, text]
+                    .filter((x) => x !== '')
+                    .join(' ') || null,
+            },
+        ]);
         if (state === 'rejected' || state === 'sent_back') {
             const open = round
                 .filter((r) => r.id !== request.id && r.state === 'pending')
                 .map((r) => r.id);
-            if (open.length > 0)
+            if (open.length > 0) {
                 await ref(su, 'approval.request').browse(open).write({ state: 'cancelled' });
+                await logEvents(su, open.map((id) => ({
+                    request: id,
+                    kind: 'cancelled',
+                    user: actor,
+                    note: `${request.levelName} ${state === 'rejected' ? 'rejected' : 'sent back'}.`,
+                })));
+            }
         }
         const done = state === 'rejected' ||
             state === 'sent_back' ||
@@ -446,6 +890,8 @@ export async function decide(env, requestId, decision, comment, from) {
                 ip: from?.ip ?? null,
             },
         });
+        if (state === 'approved' && !done)
+            await startTurn(su, target.model, target.id, new Date());
         await su.emit('approval.decided', { ...target, request: request.id, state, final: done });
         if (done && policy !== undefined) {
             const key = state === 'approved' ? 'onApproved' : state === 'rejected' ? 'onRejected' : 'onSentBack';
@@ -481,6 +927,7 @@ export async function withdraw(env, model, id) {
         await ref(su, 'approval.request')
             .browse(pending.map((r) => r.id))
             .write({ state: 'cancelled' });
+        await logEvents(su, pending.map((r) => ({ request: r.id, kind: 'cancelled', user: actor, note: 'Withdrawn.' })));
         await audit(su, {
             kind: 'approval.withdrawn',
             summary: `Approvals withdrawn for ${model} ${id}.`,
@@ -501,6 +948,179 @@ export async function withdraw(env, model, id) {
         return pending.length;
     });
 }
+const managesApprovals = (env) => env.administrator || env.groups.has('approvals.manager');
+/**
+ * Reassigns a pending request (RFC 0027 §2.6), for Approvals managers: its approvers replaced by `users`, or `users`
+ * added to them (a role's holders named first); never the requester; a reason required; logged, audited and
+ * announced (`approval.reassigned`, with the people added). @throws {HttpProblem} 403 / 404 / 409 / 422
+ */
+export async function reassign(env, requestId, users, mode, reason) {
+    if (!managesApprovals(env))
+        refuse(403, 'access', 'Approvals managers', 'Reassigning needs the Approvals manager role.');
+    const text = reason.trim();
+    if (text === '')
+        refuse(422, 'reason-required', 'Say why', 'A reassignment says why.');
+    const actor = env.uid;
+    return env.asSuperuser({ reason: `reassign approval ${requestId}` }, async (su) => {
+        const [request] = await loadRequests(su, { id: requestId }, ['id asc']);
+        if (request === undefined)
+            refuse(404, 'missing-record', 'Not found', `No approval request ${requestId}.`);
+        if (request.state !== 'pending')
+            refuse(409, 'approval-decided', 'Already decided', `This request is ${request.state}.`);
+        const chosen = [...new Set(users)];
+        if (chosen.length === 0)
+            refuse(422, 'validation', 'Nobody chosen', 'Choose who decides.');
+        if (request.requestedBy !== null && chosen.includes(request.requestedBy))
+            refuse(422, 'separation-of-duties', 'Separation of duties', 'The requester cannot approve their own record.');
+        const found = await find(su, 'res.users', { id: { in: chosen } }, ['id']);
+        if (found.length !== chosen.length)
+            refuse(422, 'validation', 'Unknown people', 'Every person must be a user.');
+        const before = request.approvers.length > 0
+            ? [...request.approvers]
+            : request.approverRole === ''
+                ? []
+                : (await holders(su, request.approverRole, request.company)).filter((u) => u !== request.requestedBy);
+        const next = mode === 'replace' ? chosen : [...new Set([...before, ...chosen])];
+        const required = Math.min(request.required, Math.max(1, next.length));
+        await ref(su, 'approval.request')
+            .browse([request.id])
+            .write({ approvers: { set: next }, required });
+        const note = `${await namesOf(su, before)} → ${await namesOf(su, next)}. ${text}`;
+        await logEvents(su, [{ request: request.id, kind: 'reassigned', user: actor, note }]);
+        await audit(su, {
+            kind: 'approval.reassigned',
+            summary: `${request.levelName} reassigned for ${request.targetModel} ${request.targetId}.`,
+            actor,
+            company: request.company,
+            targetModel: request.targetModel,
+            targetId: request.targetId,
+            details: { request: request.id, before, after: next, reason: text },
+        });
+        const added = next.filter((u) => !before.includes(u));
+        if (added.length > 0 && request.startedAt !== null)
+            await su.emit('approval.reassigned', { request: request.id, users: added });
+        const [after] = await loadRequests(su, { id: request.id }, ['id asc']);
+        return after;
+    });
+}
+/**
+ * Tells a current request's backups that it waits (RFC 0027 §2.6): for Approvals managers and the request's
+ * approvers; logged and announced (`approval.backups`). @throws {HttpProblem} 403 / 404 / 409
+ */
+export async function notifyBackups(env, requestId) {
+    const actor = env.uid;
+    return env.asSuperuser({ reason: `notify backups of approval ${requestId}` }, async (su) => {
+        const [request] = await loadRequests(su, { id: requestId }, ['id asc']);
+        if (request === undefined)
+            refuse(404, 'missing-record', 'Not found', `No approval request ${requestId}.`);
+        if (!managesApprovals(env) && !request.approvers.includes(actor))
+            refuse(403, 'access', 'Not an approver', 'Approvers and Approvals managers tell backups.');
+        if (request.state !== 'pending' || request.startedAt === null)
+            refuse(409, 'approval-not-current', 'Not waiting', 'Only a request whose turn it is.');
+        if (request.backups.length === 0)
+            refuse(409, 'no-backups', 'No backups', 'This level has no backups.');
+        await logEvents(su, [
+            {
+                request: request.id,
+                kind: 'notified',
+                user: actor,
+                note: await namesOf(su, request.backups),
+            },
+        ]);
+        await su.emit('approval.backups', { request: request.id, users: [...request.backups] });
+        return request.backups.length;
+    });
+}
+/** The fields of a level that decide its approvers: a change to one is synced to its waiting requests. */
+export const APPROVER_KEYS = [
+    'approverKind',
+    'approverRole',
+    'approverUsers',
+    'extraUsers',
+    'backupUsers',
+    'approverField',
+    'quorum',
+    'quorumCount',
+];
+/**
+ * Keeps waiting requests in step with their levels (RFC 0027 §2.6), as the system: each pending request of these
+ * levels gets its approvers found again — added to the ones it has, or replacing them, as its policy says (`mode`
+ * overrides it, for "Sync now") — logged when they change. Returns what changed, with the people added to requests
+ * whose turn it is (to tell, when the policy says so).
+ */
+export async function syncLevels(su, levelIds, mode) {
+    const out = [];
+    if (levelIds.length === 0)
+        return out;
+    const levels = await find(su, 'approval.level', { id: { in: [...levelIds] } }, [
+        'policy',
+        'name',
+        'approverKind',
+        'approverRole',
+        'approverUsers',
+        'extraUsers',
+        'backupUsers',
+        'approverField',
+        'quorum',
+        'quorumCount',
+    ]);
+    for (const level of levels) {
+        const [policy] = await find(su, 'approval.policy', { id: level['policy'] }, [
+            'syncPending',
+            'notifyOnSync',
+        ]);
+        const how = mode ?? String(policy?.['syncPending'] ?? 'add');
+        if (how === 'off')
+            continue;
+        const pending = await loadRequests(su, { level: level['id'], state: 'pending' }, ['id asc']);
+        for (const request of pending) {
+            const requester = request.requestedBy ?? 0;
+            const who = await approversOf(su, level, { model: request.targetModel, id: request.targetId, company: request.company }, requester);
+            const levelBackups = (level['backupUsers'] ?? []).filter((u) => u !== requester);
+            const approvers = how === 'add'
+                ? [...new Set([...request.approvers, ...who.approvers])]
+                : who.approvers.length > 0 || who.role !== ''
+                    ? who.approvers
+                    : request.approvers;
+            const backups = how === 'add' ? [...new Set([...request.backups, ...levelBackups])] : levelBackups;
+            const same = (a, b) => a.length === b.length && a.every((x) => b.includes(x));
+            const role = how === 'replace' ? who.role : request.approverRole;
+            if (same(approvers, request.approvers) &&
+                same(backups, request.backups) &&
+                role === request.approverRole)
+                continue;
+            await ref(su, 'approval.request')
+                .browse([request.id])
+                .write({
+                approvers: { set: approvers },
+                backups: { set: backups },
+                approverRole: role,
+                required: how === 'replace' ? who.required : request.required,
+                explanation: who.explanation.join(' '),
+            });
+            await logEvents(su, [
+                {
+                    request: request.id,
+                    kind: 'synced',
+                    note: `${how === 'add' ? 'Added' : 'Replaced'}: ${await namesOf(su, approvers)}${backups.length > 0 ? `; backups: ${await namesOf(su, backups)}` : ''}.`,
+                },
+            ]);
+            const [after] = await loadRequests(su, { id: request.id }, ['id asc']);
+            if (after === undefined)
+                continue;
+            const added = [
+                ...approvers.filter((u) => !request.approvers.includes(u)),
+                ...backups.filter((u) => !request.backups.includes(u)),
+            ];
+            out.push({
+                request: after,
+                added: request.startedAt === null ? [] : added,
+                notify: policy?.['notifyOnSync'] !== false,
+            });
+        }
+    }
+    return out;
+}
 /** `purchase.order` as people say it: "Purchase order". */
 const labelOf = (model) => {
     const words = model.replace(/[._]/g, ' ');
@@ -698,10 +1318,122 @@ export async function approvalStats(env) {
         };
     });
 }
+/** The periods of the matrix dashboard, in days (`all`: no limit). */
+const MATRIX_DAYS = { '7d': 7, '30d': 30, '3m': 91, '6m': 182, '1y': 365, all: null };
+export const MATRIX_PERIODS = Object.keys(MATRIX_DAYS);
+/**
+ * The matrix dashboard (RFC 0027 §2.7): the requests of the period the user decides — directly (named, or holding
+ * the role) or delegated (as a backup or for someone away) — a card per policy with what waits, what was approved
+ * and rejected; for Approvals managers also the hours each level takes to decide and the bottlenecks (who has the
+ * most requests late).
+ */
+export async function approvalMatrix(env, period, mode) {
+    const manages = managesApprovals(env);
+    return env.asSuperuser({ reason: 'approval matrix' }, async (su) => {
+        const who = await whoIs(su, env);
+        const days = MATRIX_DAYS[period];
+        const since = days === null ? null : new Date(Date.now() - days * 86_400_000);
+        const rows = await loadRequests(su, {
+            state: { ne: 'cancelled' },
+            ...(since === null ? {} : { createdAt: { gte: since } }),
+        }, ['id asc']);
+        const mine = (r) => r.approvers.includes(who.uid) ||
+            (r.approvers.length === 0 &&
+                r.approverRole !== '' &&
+                (r.company === null || r.company === who.companyId) &&
+                who.groups.has(r.approverRole));
+        const forOthers = (r) => !mine(r) &&
+            (r.backups.includes(who.uid) ||
+                who.delegators.some((d) => d.user !== r.requestedBy &&
+                    (r.approvers.includes(d.user) ||
+                        (r.approvers.length === 0 && holds(d.roles, r.approverRole, r.company)))));
+        const waitingNow = (r) => r.state === 'pending' && r.startedAt !== null;
+        const scoped = rows.filter((r) => r.requestedBy !== who.uid);
+        const direct = scoped.filter(mine);
+        const delegated = scoped.filter(forOthers);
+        const names = new Map((await find(
+        // Archived policies keep their requests' history.
+        su.withFlags({ activeTest: false }), 'approval.policy', {
+            id: {
+                in: [...new Set(rows.map((r) => r.policy).filter((p) => p !== null))],
+            },
+        }, ['name'])).map((p) => [p['id'], String(p['name'])]));
+        const cards = new Map();
+        for (const r of mode === 'direct' ? direct : delegated) {
+            const key = String(r.policy ?? 0);
+            const card = cards.get(key) ?? {
+                policy: r.policy,
+                title: (r.policy === null ? undefined : names.get(r.policy)) ?? r.targetModel,
+                waiting: 0,
+                approved: 0,
+                rejected: 0,
+                total: 0,
+            };
+            if (r.state === 'pending' && !waitingNow(r))
+                continue; // a later level: not anyone's turn yet
+            cards.set(key, {
+                ...card,
+                waiting: card.waiting + (waitingNow(r) ? 1 : 0),
+                approved: card.approved + (r.state === 'approved' ? 1 : 0),
+                rejected: card.rejected + (r.state === 'rejected' || r.state === 'sent_back' ? 1 : 0),
+                total: card.total + 1,
+            });
+        }
+        let levels = null;
+        let bottlenecks = null;
+        if (manages) {
+            const byLevel = new Map();
+            for (const r of rows) {
+                if (r.decidedAt === null || r.startedAt === null || r.state === 'pending')
+                    continue;
+                const policy = (r.policy === null ? undefined : names.get(r.policy)) ?? r.targetModel;
+                const key = `${policy}\u0000${r.levelName}`;
+                const entry = byLevel.get(key) ?? { policy, level: r.levelName, hours: [] };
+                entry.hours.push((Date.parse(r.decidedAt) - Date.parse(r.startedAt)) / 3_600_000);
+                byLevel.set(key, entry);
+            }
+            levels = [...byLevel.values()]
+                .map((e) => ({
+                policy: e.policy,
+                level: e.level,
+                decided: e.hours.length,
+                averageHours: Math.round((e.hours.reduce((a, b) => a + b, 0) / e.hours.length) * 10) / 10,
+            }))
+                .sort((a, b) => b.averageHours - a.averageHours);
+            const load = new Map();
+            const now = Date.now();
+            for (const r of rows.filter(waitingNow))
+                for (const u of r.approvers) {
+                    const entry = load.get(u) ?? { late: 0, waiting: 0 };
+                    entry.waiting += 1;
+                    if (r.dueAt !== null && Date.parse(r.dueAt) <= now)
+                        entry.late += 1;
+                    load.set(u, entry);
+                }
+            const people = new Map(load.size === 0
+                ? []
+                : (await find(su, 'res.users', { id: { in: [...load.keys()] } }, ['name'])).map((u) => [
+                    u['id'],
+                    String(u['name']),
+                ]));
+            bottlenecks = [...load.entries()]
+                .map(([user, l]) => ({ user, name: people.get(user) ?? `#${user}`, ...l }))
+                .sort((a, b) => b.late - a.late || b.waiting - a.waiting)
+                .slice(0, 10);
+        }
+        return {
+            cards: [...cards.values()].sort((a, b) => a.title.localeCompare(b.title)),
+            direct: direct.filter(waitingNow).length,
+            delegated: delegated.filter(waitingNow).length,
+            levels,
+            bottlenecks,
+        };
+    });
+}
 /** The people who may decide `request` now: its approvers (or its role's holders), the escalation role's once late,
  * and whoever they delegated to today; never the requester. */
 export async function decidersOf(su, request, today) {
-    const people = new Set(request.approvers);
+    const people = new Set([...request.approvers, ...request.backups]);
     if (request.approvers.length === 0 && request.approverRole !== '')
         for (const u of await holders(su, request.approverRole, request.company))
             people.add(u);
@@ -733,11 +1465,12 @@ export async function sweepDeadlines(su, now = new Date()) {
         'remindedAt',
         'escalatedTo',
         'createdAt',
+        'startedAt',
         'level',
     ]);
     for (const row of rows) {
         const due = new Date(row['dueAt']).getTime();
-        const start = new Date(row['createdAt']).getTime();
+        const start = new Date((row['startedAt'] ?? row['createdAt'])).getTime();
         const [request] = await loadRequests(su, { id: row['id'] }, ['id asc']);
         if (request === undefined)
             continue;
@@ -763,6 +1496,7 @@ export async function sweepDeadlines(su, now = new Date()) {
                     targetId: request.targetId,
                     details: { request: request.id, role },
                 });
+                await logEvents(su, [{ request: request.id, kind: 'escalated', note: role, at: now }]);
                 await su.emit('approval.escalated', { request: request.id, role });
                 out.push({ kind: 'escalated', request: { ...request, escalatedTo: role } });
                 continue;
@@ -770,16 +1504,19 @@ export async function sweepDeadlines(su, now = new Date()) {
         }
         if ((row['remindedAt'] ?? null) === null && now.getTime() >= start + (due - start) / 2) {
             await ref(su, 'approval.request').browse([request.id]).write({ remindedAt: now });
+            await logEvents(su, [{ request: request.id, kind: 'reminded', at: now }]);
             out.push({ kind: 'reminded', request });
         }
     }
     return out;
 }
 /** One-time links deciding `request` from an email, one per person who may decide it now (7 days). */
-export async function issueLinks(su, request, today, newToken, digestOf) {
+export async function issueLinks(su, request, today, newToken, digestOf, only) {
     const out = [];
     const expiresAt = new Date(Date.now() + 7 * 86_400_000);
     for (const user of await decidersOf(su, request, today)) {
+        if (only !== undefined && !only.includes(user))
+            continue;
         const token = newToken();
         await ref(su, 'approval.link').create([
             { request: request.id, user, tokenHash: digestOf(token), expiresAt },
@@ -859,12 +1596,24 @@ export async function installApprovalPolicies(env, modules) {
                 name: level.name,
                 condition: level.condition ?? null,
                 approverRole: level.approverRole,
-                approverKind: level.approver === 'manager'
-                    ? 'manager'
+                approverKind: typeof level.approver === 'string'
+                    ? level.approver
                     : typeof level.approver === 'object'
-                        ? 'field'
+                        ? 'record' in level.approver
+                            ? 'record'
+                            : 'employee' in level.approver
+                                ? 'employee'
+                                : 'field'
                         : 'role',
-                ...(typeof level.approver === 'object' ? { approverField: level.approver.field } : {}),
+                ...(typeof level.approver === 'object'
+                    ? {
+                        approverField: 'record' in level.approver
+                            ? level.approver.record
+                            : 'employee' in level.approver
+                                ? level.approver.employee
+                                : level.approver.field,
+                    }
+                    : {}),
                 quorum: level.quorum === undefined || level.quorum === 'any'
                     ? 'any'
                     : level.quorum === 'all'