ss-tools/specs/028-llm-datasource-supeset/checklists/requirements.md

Specification Quality Checklist: LLM Table Translation Service

Purpose: Validate specification completeness and quality before proceeding to planning
Created: 2026-05-08
Updated: 2026-06-11 (enhancement: Direct DB Insert + Connection Settings — IMPLEMENTED)
Feature: spec.md

Content Quality

• No implementation details (languages, frameworks, APIs) leak into spec.md
• Focused on user value and business needs — translation workflow, dictionary management, scheduling for operational stakeholders
• Written for non-technical stakeholders — uses business terminology throughout
• All mandatory sections completed (User Scenarios, Clarifications, Requirements, Key Entities, Success Criteria, Assumptions, Access Control Matrix)

UX Consistency

• Functional requirements fully support all flows in ux_reference.md (Flows A–G, updated for Superset API execution)
• Error handling requirements match all 'Error Experience' scenarios (A–I) in ux_reference.md
• No requirements contradict the defined User Persona or Context
• UX principles (preview gates manual runs, traceability, graceful degradation, cost awareness) are reflected in functional requirements
• INSERT execution via Superset API is consistent across spec, UX, quickstart, and contracts

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain — all post-review ambiguities resolved in Clarifications sessions
• Requirements are testable and unambiguous — each FR describes a specific, verifiable behavior
• Success criteria are measurable — 15 SC items include specific percentages, time bounds, or coverage targets
• Success criteria are technology-agnostic (no implementation details)
• All acceptance scenarios are defined — 7 user stories with 41 total acceptance scenarios
• Edge cases are identified — 19 core edge cases + 14 multi-language/correction + 3 direct DB (connection failure, deletion blocked, password changed) = 36 edge cases covering NULL values, missing tables, large datasets, concurrency, LLM failures, composite keys, dictionary duplicates, schedule overlaps, retention gap, Superset API errors, SQL injection, direct DB connection/auth/timeout failures
• Scope is clearly bounded — covers configuration, preview quality gate, execution via Superset API OR direct DB, history, dictionary management, feedback loop, scheduling, connection settings; dialect-aware SQL generation (PostgreSQL/Greenplum, ClickHouse)
• Dependencies and assumptions identified — 22 assumptions

Feature Readiness

• All functional requirements have clear acceptance criteria (mapped to user story acceptance scenarios)
• User scenarios cover primary flows: Configuration (P1) → Preview Quality Gate + Dictionary (P2) → Superset API Execution + Feedback + Scheduling (P3) → Audit (P4)
• Feature meets measurable outcomes defined in Success Criteria
• No implementation details leak into specification
• Feature aligns with existing ss-tools architecture patterns (plugin system, Superset integration, LLM provider, scheduler, notification, RBAC)
• Contradictions resolved: FR-023 (snapshot isolation), dictionary conflict model (overwrite/keep existing), preview model (quality gate), auto-insert for scheduled runs (after first successful manual run)
• New entities added: TranslationBatch, TranslationPreviewSession, TranslationPreviewRecord, MetricSnapshot
• Event model expanded: nullable run_id, terminal states (succeeded/partial/failed/cancelled/skipped), pre-run events
• Access control matrix defined with ownership constraints
• Dialect-aware SQL generation declared (PostgreSQL/Greenplum + ClickHouse, detected from Superset connection)
• Retention gap resolved: MetricSnapshot persistence before event pruning

Implementation Verification (2026-06-10)

Check	Status
Backend: translate plugin	✅ Exists at plugins/translate/ (59 source files, C2 skeleton)
Backend: translate routes	✅ Exists as api/routes/translate/ package (13 submodules)
Backend: translate services	✅ Decomposed across 59 plugin source files
Backend: translate models	✅ Exists as models/translate.py (401 строка)
Backend: translate schemas	✅ Exists as schemas/translate.py (712 строк)
Backend: translate tests	✅ 27 файлов в plugins/translate/__tests__/ + 12 внешних
Frontend: translate pages	✅ /translate/, /translate/[id]/, /translate/dictionaries/, /translate/history/
Frontend: translate components	✅ 14 Svelte компонентов (включая ConfigTabForm, RunTabContent, TargetTabForm, TargetSchemaHint)
Frontend: translate API client	✅ lib/api/translate/ (8 модулей)
Backend: ConnectionService	✅ Exists as core/connection_service.py (448 строк)
Backend: DbExecutor	✅ Exists as core/db_executor.py (369 строк)
Backend: Connection CRUD endpoints	✅ +5 endpoints in routes/settings.py
Frontend: ConnectionsTab	✅ Exists as routes/settings/ConnectionsTab.svelte (385 строк)
Frontend: InsertMethodSelector	✅ Exists as components/translate/InsertMethodSelector.svelte (185 строк)
Docker compose	✅ docker-compose.yml exists
Backend .env	✅ backend/.env (ENCRYPTION_KEY + feature flags)

Notes

• Post-review session resolved 3 critical contradictions and 10+ medium gaps.
• FR count: 78 (49 original + 14 multi-language/correction + 15 direct DB/connections) | SC count: 30 | Key entities: 15 | Edge cases: 36
• Preview model clarified as quality gate (not row-level approval for all rows).
• INSERT execution supports two methods: Superset /api/v1/sqllab/execute/ API (existing) AND direct DB connection (NEW via US11–US12).
• Database connection settings moved to common Settings → Connections tab with encryption, test, and dependency safety.
• connections: list[dict] stub in GlobalSettings promoted to list[DatabaseConnection] with Pydantic model validation.
• All manual copy/paste SQL Lab references removed from spec, UX, quickstart, and contracts.
• Spec status: Implemented ✅ (core + enhancement — all 160 tasks complete)
• Актуальные метрики: ~174 файла, ~39 400 строк кода (core + enhancement complete)