Workflows
Create approvals, checks, or onboarding from a template. Todos reach the right person; publish to the app desktop when needed.
Source docs/en/site/mech-workflow.md
Document version: 2.5 Status: Process definitions + publish for use + optional app desktop + inspection/approval templates available (Web + mobile to-dos) Voice: For product, operations, and integrators.
Related: 工作流与合规.md, 工作区应用.md, 服务通知.md, HR platform plugin
1. Up front
Cadau provides a Workflows top-bar module (same level as Agents and Skills center) to:
- Create in-workspace process definitions from platform templates;
- Publish means the workflow is usable: workspace members start it from Published. Business hooks, plugin start, and calling another workflow also require published. It does not have to go on the app desktop;
- Put on the app desktop is a separate optional step for an icon;
- Manage instances and My to-dos (including service-notice reach and handling on mobile).
Recommended templates: IWAY factory audit, blank process, simple approval. Classic “on-site compliance inspection” still works; migrating to the generic-engine template is suggested.
2. Four-layer model
| Layer | User language | Storage |
|---|---|---|
| Template | Create from template → IWAY / blank / simple approval | Code workflow/templates.go |
| Process definition | My processes | workflow_definitions |
| Process group order | Named-group order on My processes (workspace-shared) | workspace_workflow_group_order |
| Published app | App-desktop icon | workspace_apps (app_kind=workflow) |
| Instance / to-do | One inspection, approval, remediation | workflow_instances / workflow_tasks |
3. User path
- Top-bar feature menu → Workflows
- Create from template → fill a name → optional “publish to the app desktop after create” (default not published)
- Suite is chosen only at publish: ungrouped (straight onto the desktop), an existing suite, or a new suite; you may not publish and only use it in the Workflows module
- In My processes, open to start an instance: fill the start-node form; if the form has an org-department multi-select field, tick departments (from HR); when needed pick approver/handler (employees already bound to a Cadau account)
- Publish / unpublish / archive
- Front-line people enter handling from the Apps desktop (if published), My to-dos, I'm involved (all by default; in progress / finished filters), or Service notices (Web / phone)
Start-page copy and fields all come from process design (start-form node title/description/submit-button copy and field list). Platform templates (factory audit, simple approval) only prefill these parameters at create time; they do not hard-code the UI at runtime by template.
Org-data convention:
- Departments and employees follow the HR system-level plugin; do not create new “department / plant” workspace apps, and the start side no longer uses a “plant” concept.
- Handler resolve is still a Cadau
user_id: the UI picks from HR employees and writes theirmindlink_user_id. - Old processes that still carry a historical
departments_app_idfall back to that only when HR is unavailable.
4. HTTP API (/workspaces/{id}/workflows)
| Method | Path | Note | |||||
|---|---|---|---|---|---|---|---|
| GET | /templates | Platform template list | |||||
| GET | /hr/org-units | For start: HR department list | |||||
| GET | /hr/employees | For start/design: HR employee list (including mindlink_user_id) | |||||
| GET | /hr/positions | For design: position/grade catalog (department-position staffing handlers) | |||||
| GET | /step-catalog | Process-designer node catalog (core ∪ enabled plugins) | |||||
| GET | /compliance/surveys | Process settings: default check-scheme list (used when starting from Workflows; when starting from an inspection plan, that set wins) | |||||
| GET/POST | /definitions | Process-definition list / create; list may take `?status=active\ | archived\ | all` (default active) | |||
| GET | /definitions/{defId} | Definition detail | |||||
| PATCH | /definitions/{defId} | Update name, description, related app, and similar | |||||
| POST | /definitions/{defId}/publish | Publish to the app desktop | |||||
| POST | /definitions/{defId}/unpublish | Unpublish | |||||
| POST | /definitions/{defId}/archive | Archive (soft; hidden from the default list; recoverable) | |||||
| POST | /definitions/{defId}/unarchive | Unarchive, restore as usable | |||||
| POST | /definitions/{defId}/start | Start an instance; body optional is_test: true marks a test ticket (title prefixed “[测试]”) | |||||
| POST | /definitions/{defId}/cleanup-test-instances | Hard-delete cleanable test instances under this definition (started by self; admins may clear all) plus their to-dos/work tickets/agent tasks | |||||
| GET | /instances?definition_id=&is_test= | Instance list; is_test is all (default) / 0 (formal only) / 1 (test only) | |||||
| GET | /instances/{instanceId} | Instance detail (includes is_test) | |||||
| POST | /instances/{instanceId}/cancel | Cancel an in-progress instance (also cancels queued/running agent tasks) | |||||
| GET | /tasks/mine | My to-dos (including covering others during a delegate window, and duties that can be claimed) | |||||
| GET | `/mine?kind=todo\ | submitted\ | handled\ | involved` | Inbox across workflows: to-dos, runs I started, runs I handled, runs I’m involved in (kind=involved may take `phase=all\ | active\ | ended`; omitted phase is in-progress; includes document number when present) |
| POST | /tasks/{taskId}/complete | Complete a to-do | |||||
| POST | /tasks/{taskId}/reassign | Reassign a to-do (body: to_user_id) | |||||
| GET/PUT/DELETE | /assignee-delegate | Own handler delegate (receive others’ to-dos while on leave/away) | |||||
| GET/PUT | /group-order | Named-group order on My workflows (workspace-shared; body { group_keys: string[] }) |
Workspace business duties (collaboration API, not /workflows prefix): GET/POST /workspaces/{id}/duties, plus PATCH/DELETE of …/duties/{dutyId}, members and pack-grants.
Compliance-specific: /frameworks, /compliance/knowledge-status still exist.
Conversation tools (work assistants): workflow_list / workflow_create / workflow_start.
5. Implementation mapping
| User concept | Implementation | |
|---|---|---|
| Templates | internal/workflow/templates.go | |
| Definition CRUD / publish / archive | definitions.go, lifecycle.go, store/workflow_definition.go | |
| Generic engine | runner.go (including human.approve, handler resolve, countersign / any-one sign) | |
| HR department/employee/position BFF | handlers/workflows_hr.go → platformplugin.InvokeOperation | |
| Business duties | store/workspace_duty.go, handlers/workspace_duties.go; to-do assignee_role=duty:<key> | |
| Department-position staffing | HR lib/staffing.ts; handler type=hr_dept_position (dept_position_id or department variable × position) | |
| Named-list countersign / any-one | Handler type=users + `config.approval_mode=all | any; countersign.go` |
| Agent-judged handler | type=agent; run the agent synchronously; result may land user/duty/staffing/identity; reason variable assignee_agent_reason | |
| To-do notices | notify/workflow.go → module.workflows | |
| Web Workflows module | WorkflowPanel.tsx, route /workflows | |
| Process group order | store/workflow_group_order.go; GET/PUT …/workflows/group-order | |
| Mobile | client/mobile/app/(app)/workflows/ | |
| Compliance runtime | ComplianceWorkflowPanel.tsx + internal/compliance/ |
6. Later (P3)
- [ ] To-do due reminders (scheduled scan)
- [x] Countersign / any-one sign (named list at design time; parallel to-dos; countersign = all must pass / one reject stops)
- [ ] Multi-level approval chains and automatic routing by workspace role
- [ ] Hard delete after archive / export an audit pack