feat: harden query read-only workflow

2026-07-07 17:20:44 +08:00
1 parent 58bbc394e9
commit 617c15dbfe
@@ -0,0 +1,46 @@
+# Frontend Architecture
+
+OpsxSQL frontend uses a light domain-first structure:
+
+- `pages`: route-level composition only
+- `features`: business domains such as datasource, Redis, Mongo, query, ticket, RBAC, governance, system
+- `api`: transport clients grouped by backend domain
+- `components`: existing shared app components
+- `shared`: new cross-domain primitives
+
+Production guideline:
+
+- Keep page files below about 700 lines.
+- Move reusable business UI into `features/<domain>/components`.
+- Move domain state/data orchestration into `features/<domain>/hooks`.
+- Move cross-domain helpers into `shared/lib`.
+- Avoid putting transport logic inside components.
+- New API imports should prefer domain paths such as `api/datasource/redis` and `api/system/user`; top-level API files are compatibility shims.
+- Database-engine-specific behavior belongs under `features/datasource/engines/<engine>` or the engine domain (`features/redis`, `features/mongo`) when the surface is large enough.
+
+Domain map:
+
+- `features/datasource`: instance inventory, connection forms, import flows, MySQL/PostgreSQL engine panels
+- `features/redis`: Redis key/value browsing, Redis result formatting, Redis command helpers
+- `features/mongo`: MongoDB collection/document browsing and Mongo shell result rendering
+- `features/query`: self-service query workspace, templates, query history, result rendering
+- `features/ticket`: change ticket lifecycle, execution, rollback, approval actions
+- `features/governance`: workflows, audit rules, risk policy, execution windows, SLA policy
+- `features/rbac`: users, roles, permission groups, LDAP sync
+- `features/system`: settings, notifications, announcements, audit logs, appearance
+
+First migration sample:
+
+- Redis value formatting and command helpers now live in `features/redis`.
+- Redis Hash result display is shared by Redis detail and query workflows.
+- Query template/history UI now lives in `features/query`.
+
+Current page-size hotspots:
+
+- `InstancePage.tsx`: datasource domain
+- `UsersPage.tsx`: RBAC domain
+- `TicketsPage.tsx` and `TicketDetailPage.tsx`: ticket domain
+- `WorkflowPage.tsx`: governance domain
+- `LdapConfigPage.tsx`: RBAC/system boundary; should be folded into RBAC LDAP panels or system integration settings
+
+Use `npm run audit:pages` in `frontend/` to find pages over the 700-line budget.
@@ -0,0 +1,94 @@
+# Frontend Modernization Roadmap
+
+This roadmap tracks the global cleanup from page-heavy implementation toward production-grade domain modules.
+
+## Phase 1: Guardrails
+
+- Add `features/*` domain boundaries.
+- Keep page files below 700 lines.
+- Add `npm run audit:pages`.
+- Prefer `api/<domain>` imports for new code.
+
+Status: started.
+
+## Phase 2: Data Assets And Engines
+
+Target pages:
+
+- `InstancePage.tsx`
+- `InstanceDetailPage.tsx`
+- `RedisDetailPage.tsx`
+- `MongoDBDetailPage.tsx`
+- `SchemaSidebar.tsx`
+
+Target domains:
+
+- `features/datasource`
+- `features/datasource/engines/mysql`
+- `features/datasource/engines/postgresql`
+- `features/redis`
+- `features/mongo`
+
+Expected outcome:
+
+- MySQL/PostgreSQL/Redis/Mongo share consistent instance headers, metadata panels, query result density, and dangerous-action affordances.
+- Engine-specific behavior is isolated.
+
+## Phase 3: Query And Change Platform
+
+Target pages:
+
+- `QueriesPage.tsx`
+- `TicketCreatePage.tsx`
+- `TicketsPage.tsx`
+- `TicketDetailPage.tsx`
+- `AutoTaskPage.tsx`
+
+Target domains:
+
+- `features/query`
+- `features/ticket`
+
+Expected outcome:
+
+- Query workspace, ticket creation, audit results, execution confirmation, rollback evidence, and todo views use shared production patterns.
+
+## Phase 4: Governance And RBAC
+
+Target pages:
+
+- `WorkflowPage.tsx`
+- `AuditRulesPage.tsx`
+- `UsersPage.tsx`
+- `RolesPage.tsx`
+- `InstanceGroupPage.tsx`
+- `LdapConfigPage.tsx`
+
+Target domains:
+
+- `features/governance`
+- `features/rbac`
+
+Expected outcome:
+
+- Approval workflow, risk policy, roles, permissions, permission groups, and LDAP sync become coherent domains instead of page-local implementations.
+
+## Phase 5: System Operations
+
+Target pages:
+
+- `SettingsPage.tsx`
+- `ConfigPlatformPage.tsx`
+- `PlatformConfigPage.tsx`
+- `NotificationPage.tsx`
+- `AnnouncementPage.tsx`
+- `AuditLogsPage.tsx`
+- `AppearanceSettings.tsx`
+
+Target domain:
+
+- `features/system`
+
+Expected outcome:
+
+- System settings, notifications, announcements, audit logs, retention, and appearance use one system-governance layout.