docs: accept leader summary notification architecture

This commit is contained in:
inman committed 2026-09-07 13:25:14 +08:00
1 parent 1a3ab63700
commit a2888db243
15 files changed
+157 -18

No files matched your search

@@ -0,0 +1,49 @@
# AUTH-003: Team-lead task-summary notifications
## Status
Accepted
## Date
2026-09-07
## Context
Team leads could inspect manual employee work through the read-only operations dashboard, but they had no bounded proactive notification path. Reusing employee AgentBus replies or fabricating inbound correlation would mix oversight with task ownership and execution routing. The fixed deployment also has no team-membership model from which a narrower supervisor scope can be derived.
## Decision
- Model each recipient as one administrator-managed subscription for an active `team_lead` and that leader's enabled AgentBus channel. The scope is the fixed organization, the feature defaults off, and manual and AgentBus task sources are independently selectable.
- Project only results created after the current subscription revision starts. Include stable completed, failed, cancelled, and uncertain outcomes for tasks assigned to other non-administrator employees; never backfill history or copy transient progress.
- Keep the summary projection read-only. It does not alter `assigned_user_id`, route grants, confirmation, queue position, executable SSE, browser claim, plugin result handling, reconciliation, or ERP authority, and delivery failure never changes task state.
- Use a dedicated revisioned durable outbox rather than `agentbus_deliveries`. Encrypt recipient address, conversation ID, and payload at rest; expose only bounded fingerprints and counts to administration and diagnostics.
- Require an explicitly verified recipient/conversation route before enablement. A subscription, target, role, ownership, or channel change cancels obsolete unsent rows without automatically rerouting them.
- Keep messages deterministic and business-safe: employee username, registered business label, public task ID, submission time, generic outcome wording, and allowlisted group/order identifiers only. Do not copy original instructions, attachments, customer or traveller details, URLs, technical payloads, or technical errors.
- Send employee replies before the smaller leader-summary batch. Proactive frames use event `task.summary`, stable ID `leader-summary-<delivery-id>`, explicit `to` and `conversation_id`, and no `reply_to`; inbound `task.summary` is reserved so an echo cannot create work.
- Treat WebSocket delivery as at-least-once. Downstream routing should deduplicate the stable frame ID, and deleting platform data cannot retract a message already accepted by AgentBus or WeChat.
## Rationale
A separate projection preserves the existing employee reply and ERP execution invariants while giving leaders timely, privacy-bounded awareness. Default-off administration, target verification, encryption, revisioned deduplication, and future-only projection limit accidental disclosure and make route changes fail closed.
## Consequences
- Migration `020_leader_task_summary_notifications` is required before the updated control plane starts.
- The `/channels` administrator page configures and observes subscriptions; it is not an arbitrary message composer and deliberately exposes no live test-send endpoint.
- Repository verification proves projection, privacy, retry, priority, echo rejection, and database behavior, but production enablement still requires an authorized migration/restart plus a controlled AgentBus/WeChat canary for the exact target.
- A later real team-membership model may narrow scope, but role labels alone must not be used to invent reporting relationships.
## Supersedes
- None. This extends the read-only leadership model without superseding AUTH-001 or AUTH-002.
## Related
- `.project-docs/10-decisions/AUTH-001-fixed-scope-account-authorization.md`
- `.project-docs/10-decisions/AUTH-002-account-scoped-execution-and-force-delete.md`
- `.project-docs/30-worklog/tasks/20260907-implement-leader-agentbus-copy-b7e31a94.md`
- `control-plane/migrations/020_leader_task_summary_notifications.sql`
- `control-plane/src/leader-notification-service.ts`
- `control-plane/src/agentbus.ts`
- `agent设计规范/agentbus-reply-contract.md`
@@ -12,6 +12,7 @@
| NETWORK-001 | In the trusted internal deployment, AgentBus roster attachment URLs may resolve to internal/private addresses; HTTPS, credential rejection, DNS pinning, redirect validation, bounds, and digest checks remain. | Active | 2026-08-31 | AgentBus attachment ingress | [Reply contract](../../agent设计规范/agentbus-reply-contract.md) |
| AUTH-001 | The fixed deployment scope uses administrator-managed `admin`, `team_lead`, and `user` accounts, owner-isolated normal tasks, display-only leadership metrics with explicit filtering, explicit non-admin route grants, and assignee-bound AgentBus/browser/ERP execution. | Active except clauses superseded by AUTH-002 | 2026-09-01 | Authentication, authorization, audit, AgentBus workers, and operations oversight | [ADR](AUTH-001-fixed-scope-account-authorization.md) |
| AUTH-002 | ERP execution is serialized per immutable assigned account, administrator visibility is never execution routing, and explicit force delete physically removes authorized tasks regardless of lifecycle state. | Active | 2026-09-03 | ERP claim queues, executable events/results, and task removal | [ADR](AUTH-002-account-scoped-execution-and-force-delete.md) |
| AUTH-003 | Administrator-configured team-lead task summaries are a default-off, organization-wide read projection with a verified proactive AgentBus target and a separate encrypted outbox; they never grant task or ERP authority. | Active | 2026-09-07 | Team-lead notifications, AgentBus outbound routing, and summary privacy | [ADR](AUTH-003-leader-task-summary-notifications.md) |
## Superseded And Reverted Decisions