LWLT-AIBOT/.project-docs/20-architecture/data-flow.md

Data Flow

Primary Flows

Flow	Source	Destination	Notes
Business directive	Employee manual workbench or AgentBus	Route orchestrator	Manual input uses a signed-in team lead/user; AgentBus input uses the channel's bound employee account and its route allowlist. Administrators cannot enter this flow.
AgentBus execution ownership	Enabled channel	Employee account → immutable task assignee → executable feed	One account owns at most one channel; unbound channels and unassigned historical tasks stay non-executable.
Manual account authorization	Signed-in employee plus resolved business route	Intake and task-transition gates	Team leads/users require explicit grants; administrators manage grants but hold none, and denied or unresolved routes fail closed.
Parsing	Route orchestrator	AI Skill or deterministic Program parser	AI/Shadow/Auto/Program mode is frozen per task
Operation	Parser	Control-plane task and confirmation	Must validate against the same final contract
ERP execution	Confirmed task	Chrome extension and logged-in ERP page	Requires unique object, page identity, ownership, and write preflight
Completion evidence	ERP response/requery	Control-plane receipt and business reply	Evidence is action-specific; uncertain writes fail closed
Passenger workbook	Single .xls/.xlsx attachment	Deterministic encrypted canonical TSV	Exactly one complete ERP-semantic header is detected in rows 1–100 through finite aliases and arbitrary column order; exact leader-contact rules remain.
WeChat roster attachment	Strict transport envelope plus one structured payload.attachments[] entry	Existing awaiting_attachment task	Explicit conversation ID wins; otherwise strict Conversation: supplies the fallback. Placeholder text alone never creates a task.
Internal attachment download	Credential-free HTTPS URL	Bounded in-memory workbook bytes	Internal/private DNS answers are allowed; the selected address is pinned, every redirect is revalidated, and URL/host/IP/bytes are omitted from logs.
Operational diagnostics	Service, request, task, parser, AgentBus, attachment, database, and cleanup stages	Structured stdout/stderr and bounded Docker logs	Correlation identifiers, codes, outcomes, and durations only; no secrets or business payloads.
Platform operations oversight	Durably assigned manual/AgentBus task, encrypted instruction history, and readable outcome	Team-lead-only leadership projection	Immutable assignee is the employee dimension; unassigned historical AgentBus rows are excluded. Display-only summaries plus explicit filters drive an aggregate-first task/person/input/output/time/type/completion view, with bounded list reads and page-only detail hydration.
Team-lead task summary	Future stable manual/AgentBus task outcome for another non-admin employee	Role/channel reconciler → current-owner encrypted route → separate durable outbox → leader-owned AgentBus channel → WeChat	Automatic for active team leads with a usable route; employee replies are sent first, summary frames use stable IDs and explicit routing with no reply_to, and delivery failure never changes task state.
Browser worker selection	Immutable task assignee	One fresh account-bound browser connection	The heartbeat must prove the expected ERP identity from one unique login node by normalized exact equality; missing, duplicate, blank, substring-only, or mismatched identity is non-executable, with failover only after staleness.
Account-scoped ERP queue	Confirmed task assignee	Assigned account's browser worker	Organization-plus-account advisory locking preserves FIFO and at most one active execution for that account; another account's active, queued, stale, or uncertain work is outside this queue.
Executable event and result routing	Immutable task assignee	Matching authenticated employee page and plugin	Task APIs, SSE history/live events, claims, plugin results, and browser cleanup commands require a team-lead/user session matching the assignee; administrators are rejected before task handling.
Task removal	Owning employee	Archive/restore or permanent force delete	Archive/restore remains reversible and state-gated. Explicit owner force delete has no lifecycle-state gate, removes task-owned platform records atomically, retains a minimal deletion audit marker, and performs post-commit artifact/plugin cleanup best effort. Administrators cannot invoke either path.
Confirmation export	ERP source file	Archived source plus mobile delivery artifact	Visitor XLS becomes real XLSX; other types prefer PDF
Release	Editable source	dist/release-manifest.json and versioned artifacts	Manifest owns current hashes and filenames

State Ownership

• PostgreSQL owns durable control-plane account, management/task-plane role constraints, exact expected ERP identity, employee task-route grant, AgentBus channel owner, immutable task assignee, account-scoped queue/lease state, browser worker, session, confirmation, audit, archive, outcome state, and revisioned team-lead notification subscriptions/deliveries. Migration 021 removes and rejects administrator task principals. Notification destinations and payloads remain encrypted at rest. A force-deleted task no longer exists in task state; only its minimal non-content deletion audit marker remains, while an already delivered external message cannot be retracted.
• Production attachment bytes use the configured OSS provider; normalized sensitive fields remain encrypted.
• Chrome extension local state is bounded execution/reconciliation support, not canonical business history.
• .project-docs/30-worklog/tasks/ owns task-local project memory; canonical project state is an integrated projection.

External Interfaces

• Employee task workbench and separate administrator management pages at the control-plane service.
• AgentBus WebSocket channels and attachment delivery.
• Logged-in ERP browser pages under the Chrome extension host permissions.
• PostgreSQL, OSS, deployment gateway, and authenticated artifact download.

Last Updated

2026-09-07