docs: integrate automatic leader summary routing

This commit is contained in:
inman committed 2026-09-07 16:20:02 +08:00
1 parent 0b3aa5c42d
commit 6bdaa2a6e6
9 files changed
+76 -16

No files matched your search

@@ -14,35 +14,41 @@ Team leads could inspect manual employee work through the read-only operations d
## 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.
- Treat leader-summary delivery as an automatic consequence of an active `team_lead` identity with that leader's enabled, account-bound AgentBus channel. The scope is the fixed organization and both manual and AgentBus task sources are always included; there is no separate administrator subscription switch or source selector.
- 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.
- Derive the proactive route from AgentBus state. Prefer the latest accepted inbound `from` and `conversation_id` whose task is assigned to the current channel owner; otherwise use the channel's `external_user_ref` and the normal `agentbus:<sender>` conversation fallback. If neither exists, remain waiting until the leader's first valid inbound message. Channel rebind clears the previous external-user reference, and a route, role, ownership, account-validity, or channel change creates a new revision and cancels obsolete unsent rows instead of sending them to a stale target.
- 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.
A separate projection preserves the existing employee reply and ERP execution invariants while giving leaders timely, privacy-bounded awareness. Role-driven activation matches the meaning of the `team_lead` identity; current-owner route correlation, encryption, revisioned deduplication, future-only projection, and fail-closed invalidation limit accidental disclosure without requiring administrators to duplicate AgentBus routing state.
## 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.
- The `/channels` administrator page observes automatic status only; it is not an arbitrary message composer and exposes neither a subscription mutation endpoint nor a live test-send endpoint.
- The migration's `enabled DEFAULT false` remains an internal fail-closed storage default. Only the runtime role/channel/route reconciler activates a row, so migration 020 does not need to change.
- Repository verification proves projection, privacy, retry, priority, echo rejection, and database behavior, but production assurance still requires an authorized rollout plus a controlled AgentBus/WeChat canary of automatic route resolution.
- 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.
## Revision
- 2026-09-07: Replaced the initial administrator-configured/default-off workflow with role-driven automatic activation at explicit user direction. The fixed organization scope, privacy allowlist, future-only projection, independent encrypted outbox, and no-ERP-authority boundaries remain unchanged.
## 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`
- `.project-docs/30-worklog/tasks/20260907-auto-leader-summary-routing-5e8c1a73.md`
- `control-plane/migrations/020_leader_task_summary_notifications.sql`
- `control-plane/src/leader-notification-service.ts`
- `control-plane/src/agentbus.ts`
+1 -1
View File
@@ -12,7 +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) |
| AUTH-003 | Active team-lead identities automatically receive an organization-wide read projection through their current-owner AgentBus route and a separate encrypted outbox; it never grants 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