LWLT-AIBOT/.project-docs/20-architecture/system-overview.md

System Overview

Current Architecture

Authenticated employee manual or account-bound AgentBus input is routed through task-scoped AI/Shadow/Auto/Program orchestration into one validated operation contract. The machine registry contains 19 routes, while the external Agent remains limited to 18 and the two passenger-list routes plus shared-child batch creation are Program-only. The control plane separates the administrator management plane from the employee task data plane and owns account, channel owner, immutable task assignee, account-scoped execution queue, browser worker, session, task-type authorization, confirmation, audit, reversible archive, explicit owner force-delete behavior, and automatic organization-level leader-summary Webhook projection. The Chrome extension verifies the expected ERP account from one unique login identity node by normalized exact equality, resolves unique ERP objects, enforces page and write gates, performs native actions, and returns action-specific evidence.

Main Components

Component	Responsibility	Notes
agent设计规范/	Agent Prompt, five parsing Skills, business templates, business registry, and stable fixtures	Editable source for business semantics; not runtime evidence
schemas/ and mappings/	Parse-state, execution-state, ERP form, field, and lifecycle contracts	Current contracts only
control-plane/	Management/task-plane authorization, task/session persistence, parser orchestration, confirmation, audit, AgentBus channel ownership, task assignment, browser workers, attachments, receipts, encrypted leader-summary Webhook projection/outbox, and structured diagnostics	TypeScript source; build output goes to .build/; required schema advances through migration 023
LianSyn-platform/	Operator workbench and external parser adapter	Source and UI, not local task output
chrome-extension/ltjt-order-assistant/	Logged-in ERP resolution, preflight, native execution, response handling, requery, and dormant idle/reload safety handlers	Current server/platform does not trigger automatic updates; any code change requires synchronized versioned release updates
dist/	Versioned current deliverables and machine-readable release manifest	Not a compilation directory
.project-docs/	Task-isolated project memory and integrated canonical context	No runtime dependency
archive/	Date-scoped immutable history and evidence	Never defines current behavior

Important Boundaries

• AI/Program parsing and ERP resolution/execution share the final operation contract but do not share authority.
• Platform envelope fields such as task ID, account identity, authorization revision, session, parser decision, confirmation, transport, and audit never enter the business operation.
• The product is one fixed internal organization scope with three roles. Administrators are management-plane-only identities: they manage accounts, channels, employee route grants, parser routing, automation settings, and audit but cannot create, inspect, mutate, stream, claim, reconcile, delete, or execute business tasks. Team leads and users require explicit per-route grants and are owner-scoped for normal task operations. Team leads alone receive a dedicated organization-wide, read-only platform-operations dashboard over durably assigned manual and AgentBus tasks.
• Account passwords are accepted when non-empty without an application-level length rule. First-login forced password changes are disabled; voluntary changes and administrator resets still revoke the relevant sessions, while the historical must_change_password column remains compatibility-only storage.
• The leadership dashboard is an aggregate-first projection across assigned task, employee, original input, final output, time, task type, and completion state. It includes only durably assigned manual and agentbus work and uses immutable assigned_user_id for rankings, people filters, search, pagination, and detail; historical unassigned AgentBus rows are excluded. Summary cards are display-only; filtering is explicit and defaults to all results. List reads use one bounded read-only database transaction, SQL prefiltering, selective historical-message hydration, and full detail projection only for the current 20-row page. Its drill-through stays business-facing; technical payloads, internal identifiers, machine-shaped historical input, and technical failure text remain in separate authorized audit/engineering surfaces.
• Leader task summaries are a separate organization-level read projection, not an extension of dashboard, task, AgentBus, or ERP authority. Protected runtime configuration enables one fixed external Webhook for future stable manual and AgentBus outcomes from durably assigned non-administrator employees. The complete URL and token never enter storage or status output; encrypted summary payloads never copy raw instructions, attachments, customer/traveller data, URLs, or technical errors. Only strict gateway acceptance is recorded, not downstream delivery, and rejected or uncertain attempts are never automatically retried.
• Authorization is enforced in database, server, and service paths, not by navigation visibility. An administrator task-data-plane request fails before task storage or execution logic. A denied or unresolved employee business route stops before parsing, plugin dispatch, and ERP execution; assignee authorization is rechecked at confirmation and browser claim.
• Each enabled AgentBus channel owns one active non-admin employee account. Inbound work uses that account and route allowlist, persists the same account as immutable task assignee, and is returned only to that account's executable feed. A team-lead channel may additionally carry its leader's lower-priority proactive summary outbox; those rows use explicit destination/conversation routing and never become executable task traffic.
• Each employee account has one expected ERP identity and at most one fresh browser execution worker. The extension accepts ERP identity only from exactly one #Lable_UserName login node and normalized full equality; missing, duplicate, blank, substring-only, or unrelated body-text matches fail closed without returning the observed identity. Concurrent fresh workers, unbound channels, or unassigned tasks also fail closed. Browser claims, active-execution checks, and confirmed FIFO are serialized per immutable task assignee, so one account cannot block or occupy another account's queue.
• Administrators have no task read or execution model. Task lists/details, attachments, artifacts, lifecycle mutations, SSE history/live events, browser claims, plugin-result ingestion, and browser cleanup commands require a team_lead or user session matching assigned_user_id; the team-lead dashboard and notification outbox remain separate read projections.
• Extension 0.5.170 is the current manually published plugin baseline, Program parser v1.0.7 owns the new shared-child batch directive, the five Skills remain at 0.5.126, and the operator instruction DOCX is 0.5.127. The batch adapter enumerates and validates every matching shared-plan parent before the first write, executes in date/tid order, and stops without retry at the first blocked, failed, or uncertain result. The extension retains an idle-proof and guarded-reload message protocol, but the active control plane has no extension-release tables, ECS host mapping, OSS publication endpoint, Cloud Assistant dispatcher, or platform trigger; required migration is 023.
• Creator and manual input-turn attribution remain durable while business input stays encrypted at rest. Routine removal is reversible archive/restore. Separately confirmed force delete physically removes an authorized task regardless of lifecycle state, retains only a minimal non-content deletion audit marker, and cannot undo an ERP write that already occurred.
• Unknown, ambiguous, unverified, or post-write-uncertain states fail closed; automatic retries must not create duplicate writes.
• PostgreSQL is the sole required durable database/state middleware, and the production artifact provider is OSS. Redis, message queues, MongoDB, and search services are not runtime dependencies.
• Migrations through 023_leader_summary_webhook_delivery must complete before the updated application starts; migration 019 remains intentionally absent after the extension-updater rollback. Migration 021 removes legacy administrator task principals, migration 022 admits the Program-only shared-child batch route without granting it, and migration 023 disables unsent legacy AgentBus summary rows while creating the organization-level encrypted Webhook outbox. The current ACK topology starts with one application replica because AgentBus listeners and SSE emission are process-local; horizontal scale requires explicit coordination first.
• Operational diagnostics are privacy-safe structured JSON on stdout/stderr. Docker owns bounded rotation; repository files and a second mutable log database are not log sinks.
• In the trusted internal deployment, AgentBus roster attachment downloads may resolve to private/reserved addresses. Credential-free HTTPS, DNS resolution/pinning, redirect revalidation, size, timeout, and digest checks remain mandatory, and trusted channels/bridges own the network-input boundary.
• Canonical project memory is updated only under Integration Gate; feature tasks write only their task-scoped records.

Related Decisions

• DOC-001
• ARCH-001
• ROUTE-001
• RELEASE-001
• SAFETY-001
• NETWORK-001
• AUTH-001
• AUTH-002
• AUTH-003
• AUTH-004
• AUTH-005

Last Updated

2026-09-09