hyb-oa/.trellis/spec/hyb-oa/approval-workflow.md

Approval And Workflow

Source Docs

Read docs/需求-统一审批中心规约.md and the current workflow-related Trellis task before modifying approval behavior.

Rules

• No self-approval.
• Do not use admin as a business approver unless the current Trellis task explicitly defines an administrative fallback.
• Approval precheck, submission, workflow snapshot and task advancement must use consistent rule semantics.
• Existing workflow snapshots are historical facts; approval advancement should not drift because rules changed later.
• Reviewer review is required after changes touching workflow, status machine, approval rules, permissions or migrations.

Scenario: System Operator Is Not A Business Approver

1. Scope / Trigger

• Trigger: adding or changing OA account administration, role assignment, approval eligibility, payment review or emergency-superuser behavior.

2. Signatures

• Daily responsibility roles: manager, ceo, finance, system_admin.
• Emergency role: admin (*), hidden from ordinary assignment UI.
• System permissions: system.accounts.manage, system.roles.manage.
• Payment reviewer permission: payment.batch.review.

3. Contracts

• system_admin manages ordinary accounts and system configuration only; it does not imply leadership, finance, payroll, personnel-sensitive access or business approval authority.
• A payment reviewer must have both payment.batch.review and an explicit manager or ceo role. admin or system_admin alone is not a normal reviewer.
• manager does not imply that every employee reports to that account; reporting scope remains in direct_manager_id.
• A non-emergency system administrator cannot edit their own roles or grant, revoke or import admin / system_admin. Role changes remain audited.
• Employee aggregate endpoints must not treat system.settings as personnel- sensitive authority. Salary summaries require payroll.manage; performance summaries require system.users_sensitive; unauthorized branches issue no salary/performance query and return only the non-sensitive summary shape.

4. Validation & Error Matrix

• System administrator changes own roles -> 403 PERM_001 before role writes.
• System administrator changes a protected role -> 403 PERM_001, zero role and audit writes.
• Reviewer has permission but lacks manager|ceo -> 403 PERM_001.
• Batch creator attempts review -> deterministic 409 VALID_001.
• system_admin opens ordinary employee statistics -> salary is null, performance is empty and both sensitive query families remain untouched.

5. Good/Base/Bad Cases

• Good: one person may explicitly hold both manager and system_admin, while each route evaluates the responsibility required for that action.
• Base: system_admin creates or disables an ordinary account without seeing payroll, bank, identity or employee-contract content.
• Bad: treat admin as the default company leader or use system_admin as an approval fallback because the team is small.

6. Tests Required

• Role matrix for employee, manager, CEO, finance, system administrator and emergency administrator.
• Negative tests for self-role change, protected-role assignment/import and permission-only payment review.
• Negative employee-statistics test using the real system_admin permission set, plus positive tests for explicit payroll/personnel-sensitive authority.
• Reviewer read-only review after changing role or approval semantics.

7. Wrong vs Correct

Wrong

if (hasPermission(actor, "*")) allowPaymentReview();

Correct

if (!hasPermission(actor, "payment.batch.review")
  || !actor.roleCodes.some((role) => role === "manager" || role === "ceo")) {
  throw forbidden();
}