wangxuming/LWLT-AIBOT
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile batch and webhook integration

Browse Source
This commit is contained in:
inman committed 2026-09-09 17:33:19 +08:00
1 parent 295409bff0
commit a6abd32618
17 files changed
+185 -43
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.project-docs/10-decisions/AUTH-003-leader-task-summary-notifications.md
+3 -1
View File
@@ -2,7 +2,7 @@
## Status
Accepted
Superseded in transport and activation by AUTH-005; retained for projection/privacy history
## Date
@@ -42,11 +42,13 @@ A separate projection preserves the existing employee reply and ERP execution in
## 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.
- 2026-09-09: AUTH-005 replaced the AgentBus/channel/route transport with one organization-level external Webhook and terminal one-attempt delivery semantics. The future-only scope, privacy allowlist, independent projection, and no-task/ERP-authority boundaries continue under AUTH-005.
## 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/10-decisions/AUTH-005-leader-summary-external-webhook.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`
.project-docs/10-decisions/AUTH-004-admin-management-plane-and-leader-oversight.md
+3 -2
View File
@@ -20,7 +20,7 @@ The user explicitly required administrators to be management-plane-only identiti
- Administrator sessions do not register browser workers, open task SSE, call the ERP extension bridge, receive task cleanup commands, own employee channels, hold business-route grants, or become leader-summary subscribers or recipients.
- Only active `team_lead` and `user` identities enter the task data plane. Their normal task APIs, executable events, browser claims/results, reconciliation, archive/restore, and force delete remain restricted to immutable `assigned_user_id`.
- The operations dashboard is available only to team leads. It is an organization-wide, read-only business projection over durably assigned `manual` and `agentbus` tasks. Employee rankings, person filters, search, pagination, and detail use immutable `assigned_user_id`; historical AgentBus rows without an assignee are excluded rather than inferred.
- Dashboard visibility does not grant cross-user task mutation, executable events, artifacts, browser access, reconciliation, or ERP authority. AUTH-002 account-scoped queues and AUTH-003's separate privacy-bounded leader-summary outbox remain unchanged.
- Dashboard visibility does not grant cross-user task mutation, executable events, artifacts, browser access, reconciliation, or ERP authority. AUTH-002 account-scoped queues and AUTH-005's separate privacy-bounded leader-summary Webhook outbox remain unchanged.
- Migration `021_admin_task_data_plane_isolation` removes legacy administrator task assignments and executable bindings without deleting task history, then uses database constraints and role-promotion cleanup to prevent administrators from re-entering task-principal relationships.
## Rationale
@@ -41,13 +41,14 @@ Separating management identities from business-task identities eliminates accide
- AUTH-001's manual-task-only dashboard scope and origin-based employee attribution.
- AUTH-002 clauses retaining administrator-wide task reads or administrator force-delete authority.
AUTH-002's per-assignee execution queues and employee force-delete semantics remain active. AUTH-003 remains active without change.
AUTH-002's per-assignee execution queues and employee force-delete semantics remain active. AUTH-005 now governs leader-summary transport while preserving its separation from task and ERP authority.
## 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/10-decisions/AUTH-003-leader-task-summary-notifications.md`
- `.project-docs/10-decisions/AUTH-005-leader-summary-external-webhook.md`
- Feature commit `9043ad6eda0deb2a620e1303467d1c3bd80374ed`
- Feature commit `a2378c8`
- `control-plane/migrations/021_admin_task_data_plane_isolation.sql`
.project-docs/10-decisions/AUTH-005-leader-summary-external-webhook.md
+52
View File
@@ -0,0 +1,52 @@
# AUTH-005: Organization-level leader-summary external Webhook
## Status
Accepted
## Date
2026-09-09
## Context
AUTH-003 delivered privacy-bounded team-lead summaries through a leader-owned AgentBus channel and a learned WeChat route. The user later supplied a fixed external Webhook contract and clarified that only the organization-wide leader-summary transport should change; normal employee AgentBus task intake, replies, ownership, confirmation, ERP queues, and execution must remain unchanged.
The external API has no idempotency key, downstream delivery identifier, status query, or callback. A successful HTTP exchange can therefore prove only that the gateway accepted the request, while a timeout or lost response cannot distinguish “not received” from “accepted but response lost.”
## Decision
- Configure one organization-level leader-summary destination only through protected runtime values `WEBHOOK_SEND_URL` and `WEBHOOK_EXTERNAL_TOKEN`. Both must be present, the production URL must use HTTPS and end with `/webhookInfo/sendMessageByOut`, and the token must contain exactly 32 non-whitespace characters. The complete URL and token never enter the database, logs, audit, or administrator response.
- Send exactly one `POST` JSON request with raw `x-token` and body `{id:"9999", content:<summary>}`. Only HTTP 200 with `code === 0` and `data === true` is “accepted”; accepted does not mean delivered to WeChat.
- Keep the projection organization-wide, future-only, and read-only. It covers stable manual and AgentBus outcomes for durably assigned non-administrator employees and retains the existing privacy allowlist, generic failure wording, and uncertain-write distinction. It never changes task ownership, employee replies, parser behavior, confirmation, queue state, browser claims, reconciliation, or ERP authority.
- Store summary state and encrypted payloads only in the dedicated revisioned `leader_task_summary_webhook_*` tables. Each organization/revision/task/milestone is unique and may be attempted at most once.
- Never automatically retry an explicit rejection, timeout, network failure, 5xx response, invalid or unknown response, oversized response, or expired sending lease. Mark ambiguous cases uncertain; configuration changes cancel unsent old-revision rows and make in-flight old-revision rows uncertain.
- Isolate configuration, initialization, projection, database, and delivery failures inside the summary worker. They may disable or degrade summary delivery but cannot block the normal HTTP service or mutate ordinary tasks, employee `agentbus_deliveries`, AgentBus channels, parsing, or ERP execution.
- Expose only a read-only administrator status with safe configuration state, bounded fingerprints, counts, and accepted/rejected/uncertain terminology. There is no administrator send-test or message-composer endpoint.
## Rationale
A dedicated one-attempt Webhook outbox preserves the established privacy and task-authority boundaries while removing leader-summary dependence on a team-lead AgentBus account, channel, or learned conversation route. Treating ambiguous sends as terminal uncertainty is safer than automatic retry because the provider offers no deduplication or delivery evidence.
## Consequences
- Migrations must run in order through `022_shared_child_order_batch_create` and `023_leader_summary_webhook_delivery` before the integrated control plane starts.
- Migration 023 disables legacy AgentBus summary subscriptions and cancels their unsent rows while preserving historical tables and already recorded outcomes. Normal employee `agentbus_deliveries` are untouched.
- Production enablement requires the provider-confirmed complete gateway URL, the real 32-character token, database backup/migration, deployment/restart, and a separately authorized bounded external-send canary.
- Repository tests and disposable PostgreSQL exercises prove isolation, encryption, one-attempt semantics, and accepted-versus-delivered wording; they do not prove live gateway or WeChat delivery.
## Supersedes
- AUTH-003 clauses that activate summaries from a `team_lead` identity plus owned AgentBus channel, learn or invalidate AgentBus/WeChat routes, prioritize summary frames inside AgentBus, or use at-least-once `task.summary` frames.
AUTH-003's organization-wide future-only projection, privacy allowlist, separate encrypted storage, and non-expansion of task/ERP authority remain active through this decision.
## Related
- `.project-docs/10-decisions/AUTH-003-leader-task-summary-notifications.md`
- `.project-docs/10-decisions/AUTH-004-admin-management-plane-and-leader-oversight.md`
- `.project-docs/30-worklog/tasks/20260908-leader-webhook-api-7c4e9a12.md`
- `agent设计规范/leader-summary-webhook-contract.md`
- `control-plane/migrations/023_leader_summary_webhook_delivery.sql`
- `control-plane/src/external-webhook-client.ts`
- `control-plane/src/leader-notification-service.ts`
.project-docs/10-decisions/EXT-001-central-service-host-extension-updates.md
+2 -2
View File
@@ -10,9 +10,9 @@ Reverted
## Reversal
On 2026-09-03 the user explicitly directed that this iteration be backed up and its server-side automatic-update architecture removed from the main branch, then clarified that the Chrome plugin itself must remain at `0.5.167` at that rollback point. The exact full-stack state at commit `b2e33e2e5d29138891eabc93969cf24907492dfe` is preserved on remote branch `codex/backup-extension-update-20260903-b2e33e2`. Active `main` later advanced the manually distributed plugin to `0.5.169` and the control plane to migration 021 without restoring private-OSS/ECS update orchestration.
On 2026-09-03 the user explicitly directed that this iteration be backed up and its server-side automatic-update architecture removed from the main branch, then clarified that the Chrome plugin itself must remain at `0.5.167` at that rollback point. The exact full-stack state at commit `b2e33e2e5d29138891eabc93969cf24907492dfe` is preserved on remote branch `codex/backup-extension-update-20260903-b2e33e2`. Active `main` later advanced the manually distributed plugin to `0.5.170` and the control plane to migration 023 without restoring private-OSS/ECS update orchestration.
This ADR is retained only as historical server-architecture context and no longer governs the active control plane. Plugin-side idle proof and guarded reload handlers remain as dormant capabilities in `0.5.169` with no current server/platform trigger. The reverted server code was never deployed, migration 019 was not applied, no OSS extension release was published, and no Cloud Assistant or Chrome reload action was performed by these repository tasks.
This ADR is retained only as historical server-architecture context and no longer governs the active control plane. Plugin-side idle proof and guarded reload handlers remain as dormant capabilities in `0.5.170` with no current server/platform trigger. The reverted server code was never deployed, migration 019 was not applied, no OSS extension release was published, and no Cloud Assistant or Chrome reload action was performed by these repository tasks.
## Context
.project-docs/10-decisions/decision-index.md
+5 -3
View File
@@ -6,14 +6,15 @@
|---|---|---|---|---|---|
| DOC-001 | `.project-docs/` is the sole active project-memory system; feature tasks own task-scoped records and Integration Gate owns canonical memory. | Active | 2026-08-28 | All repository work | [Governance](../../AGENTS.md) |
| ARCH-001 | AI parsers provide business semantics only; platform state, ERP resolution, execution evidence, and audit remain outside the business operation. | Active | 2026-08-28 | Parser and execution architecture | [System entry](../../README.md) |
| ROUTE-001 | The machine registry is the authority for 18 parser routes; the two passenger-list routes are Program-only. | Active | 2026-08-28 | Manual and AgentBus intake | [Machine registry](../../control-plane/src/business-routes.ts) |
| ROUTE-001 | The machine registry is the authority for 19 parser routes; 18 remain available to the external Agent and three routes are Program-only. | Active | 2026-09-09 | Manual and AgentBus intake | [Machine registry](../../control-plane/src/business-routes.ts) |
| RELEASE-001 | Current artifacts, filenames, versions, and SHA-256 values are defined only by `dist/release-manifest.json`. | Active | 2026-08-28 | Release and delivery | [Release manifest](../../dist/release-manifest.json) |
| SAFETY-001 | Real ERP access/write, task mutation, extension reload, service restart, deployment, and external delivery require explicit task-scoped authorization. | Active | 2026-08-28 | Operations and maintenance | [Governance](../../AGENTS.md) |
| 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, explicit employee route grants, and assignee-bound AgentBus/browser/ERP execution. | Active except clauses superseded by AUTH-002 and AUTH-004 | 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, and explicit owner force delete physically removes authorized tasks regardless of lifecycle state. | Active except administrator task-access clauses superseded by AUTH-004 | 2026-09-03 | ERP claim queues, executable events/results, and task removal | [ADR](AUTH-002-account-scoped-execution-and-force-delete.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) |
| AUTH-003 | Team-lead summaries used a current-owner AgentBus route and separate encrypted outbox without granting task or ERP authority. | Superseded in transport/activation by AUTH-005; retained for projection/privacy history | 2026-09-07 | Historical leader-summary AgentBus routing | [ADR](AUTH-003-leader-task-summary-notifications.md) |
| AUTH-004 | Administrators are management-plane-only identities; team leads alone receive an assignee-based, cross-source operations dashboard while employee task operations remain owner-only. | Active | 2026-09-07 | Administrator isolation, task APIs, database principals, and leadership oversight | [ADR](AUTH-004-admin-management-plane-and-leader-oversight.md) |
| AUTH-005 | Organization-wide leader summaries use one protected external Webhook, a future-only encrypted outbox, strict accepted-versus-delivered terminology, and terminal one-attempt failure semantics without changing normal AgentBus/task/ERP behavior. | Active | 2026-09-09 | Leader-summary projection and external delivery | [ADR](AUTH-005-leader-summary-external-webhook.md) |
## Superseded And Reverted Decisions
@@ -22,7 +23,8 @@
| DOC-LEGACY-001 | Root `task_plan.md`, `findings.md`, and `progress.md` were the active project-memory system. | DOC-001 | 2026-08-28 |
| AUTH-001 (partial) | Organization-wide ERP FIFO and archive-only operator removal. | AUTH-002 | 2026-09-03 |
| AUTH-001 / AUTH-002 (partial) | Administrator task creation, task-wide reads, dashboard access, task transitions, and force-delete authority; manual-only leadership dashboard scope. | AUTH-004 | 2026-09-07 |
| EXT-001 | Central-service private-OSS and ECS Cloud Assistant orchestration for shared unpacked-extension updates. | Server architecture reverted by explicit user decision; exact full implementation remains on `codex/backup-extension-update-20260903-b2e33e2`, while the active manually distributed plugin has advanced to `0.5.169`. | 2026-09-03 |
| AUTH-003 (transport and activation) | Team-lead identity/channel activation, learned AgentBus/WeChat routing, and at-least-once `task.summary` frames. | AUTH-005 | 2026-09-09 |
| EXT-001 | Central-service private-OSS and ECS Cloud Assistant orchestration for shared unpacked-extension updates. | Server architecture reverted by explicit user decision; exact full implementation remains on `codex/backup-extension-update-20260903-b2e33e2`, while the active manually distributed plugin has advanced to `0.5.170`. | 2026-09-03 |
## Decision Criteria