alt/agent-ops/rules/project/domain/client/rules.md

domain	last_rule_review_commit	last_rule_updated_at
client	704f1eb232	2026-06-24

client

목적 / 책임

ALT의 Flutter client surface를 담당한다. web/mobile/desktop targets, application shell, routing, feature presentation/data adapters, socket integration adapters, optional external push integrations, generated contract consumers, and client-side tests belong here.

포함 경로

• apps/client/lib/main.dart - Flutter app bootstrap
• apps/client/README.md - client-local setup and notes
• apps/client/lib/src/app/ - app shell, theme, router
• apps/client/lib/src/contracts/ - client-side contract parser helpers
• apps/client/lib/src/features/ - feature presentation code
• apps/client/lib/src/generated/ - generated Dart protobuf outputs consumed by the client
• apps/client/lib/src/integrations/ - client-side external integration adapters
• apps/client/android/, apps/client/ios/, apps/client/linux/, apps/client/macos/, apps/client/windows/, apps/client/web/ - Flutter platform targets and web assets
• apps/client/assets/ - client asset bundle inputs
• apps/client/tool/ - client-local tooling such as Dart protoc plugin wrapper
• apps/client/integration_test/ - Flutter integration tests
• apps/client/test/ - Flutter widget/unit tests
• apps/client/test_runtime/ - runtime smoke test helpers
• apps/client/analysis_options.yaml - Dart analyzer configuration
• apps/client/pubspec.yaml - Flutter package dependencies
• apps/client/pubspec.lock - resolved Flutter dependency lockfile

제외 경로

• services/api/ - socket server runtime
• packages/contracts/ - schema source for generated contracts
• packages/domain/ - Go domain models

주요 구성 요소

• AltClientApp - Material app shell using Riverpod
• AltClientBootstrapOptions - boot options for fullscreen mode and optional push initialization
• AltWorkbenchShell - top titlebar, right-side activity rail, center content switching, and right Agent dock scaffold
• appRouterProvider - go_router configuration
• DashboardScreen - initial responsive dashboard surface
• altParserMap - generated ALT protobuf message parser registration for Dart clients
• AltApiResult, AltApiError, and AltTransportKind - UI-copy-free API/transport result envelope for client repositories
• AltSocketClient - proto-socket client wrapper for ALT request/response flows
• AltSocketEndpoint - local/default socket endpoint value object
• SocketConnectionController - Riverpod connection state controller for socket lifecycle
• MarketRepository - socket-backed market list/bars data adapter returning AltApiResult
• BacktestRepository - socket-backed backtest command/query data adapter returning AltApiResult
• MattermostPushHostIntegration - optional external push integration boundary
• MattermostPushClient and MattermostPushPluginClient - host-facing push abstraction and production plugin adapter
• MattermostAuthService - optional Mattermost auth and FCM token registration service
• bootstrapAltClient - app bootstrap and platform integration startup

유지할 패턴

• Keep app-level shell and router under lib/src/app.
• Put user-facing screens under the lib/src/features/feature-name/presentation pattern.
• Put feature data adapters under lib/src/features/feature-name/data when they wrap ALT socket calls for a feature.
• Put socket and other external adapters under lib/src/integrations.
• Keep the workbench shell as product skeleton and composition boundary. Real quant operation surfaces are mounted after API/worker/domain headless paths are stable.
• Use sibling agent_shell for the common chat/agent UI only; keep ALT-specific market/backtest/portfolio logic in ALT client features or backend domains.
• Treat files under lib/src/generated as generated outputs; update them through codegen.
• Keep generated Dart parser registration aligned with every ALT protobuf message the client can decode, including paper/live trading messages when those surfaces are consumed.
• Repositories should map typed ErrorInfo to AltApiError and transport/connect/decode failures to AltTransportKind without embedding presentation copy.
• Use Material 3 components and responsive navigation patterns.
• Test user-visible app shell behavior through Flutter tests.
• Use services/api as the only ALT-owned runtime endpoint. Do not connect directly to worker runtime surfaces from client code.
• Keep operator shell bootstrapping separable from optional push/Firebase/Mattermost setup so core operator UI can start without external push readiness.
• Keep endpoint defaults in AltSocketEndpoint or provider/config boundaries; presentation widgets should consume state, not hard-code runtime endpoints.
• Keep Mattermost/Firebase/platform-channel behavior under lib/src/integrations and out of dashboard presentation widgets.
• Keep production access to NexoMessagingPlugin.instance behind MattermostPushPluginClient; tests and host orchestration should depend on MattermostPushClient.
• Keep connection lifecycle state in SocketConnectionController; feature widgets and repositories should consume the injected/live socket client rather than owning global sockets.

다른 도메인과의 경계

• api: client connects to API through integration adapters; server lifecycle and server-side socket parsing stay in services/api.
• contracts: client consumes generated/mapped contracts and owns Dart parser helpers; protobuf source stays in packages/contracts.
• agent-shell: common agent shell widget/message model only. ALT-specific quant workflow logic stays in ALT-owned client/core domains.
• operations: bin/test, bin/lint, and bin/build run client checks from the workspace root.
• worker: client never connects to worker directly; worker state reaches client only through API contracts.

금지 사항

• Do not place backend service code or Go module files under apps/client.
• Do not hand-edit Flutter generated platform files or registrants unless a platform integration explicitly requires it.
• Do not hand-edit generated protobuf Dart outputs.
• Do not hard-code production endpoint assumptions in presentation widgets.
• Do not put user-visible copy or layout decisions inside repository/result-envelope classes.
• Do not put ALT-specific quant domain logic into agent_shell.
• Do not add direct worker, database, Redis, or ALT-owned non-API runtime connections to Flutter client code.
• Do not make push notification or Mattermost availability a prerequisite for the base operator shell unless a dedicated push Milestone explicitly changes that boundary.