mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-27 18:22:41 -08:00
87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
---
|
|
id: TASK-27
|
|
title: >-
|
|
Refactor project structure to reduce architectural complexity and split
|
|
oversized modules
|
|
status: In Progress
|
|
assignee: []
|
|
created_date: '2026-02-13 17:13'
|
|
updated_date: '2026-02-15 07:00'
|
|
labels:
|
|
- 'owner:architect'
|
|
- 'owner:backend'
|
|
- 'owner:frontend'
|
|
dependencies: []
|
|
priority: high
|
|
---
|
|
|
|
## Description
|
|
|
|
<!-- SECTION:DESCRIPTION:BEGIN -->
|
|
Create a phased backlog-backed restructuring plan that keeps current service-oriented architecture while reducing cognitive load from oversized modules and tightening module ownership boundaries.
|
|
|
|
This initiative should make future feature work easier by splitting high-complexity files, reducing tightly-coupled orchestration, and introducing measurable structural guardrails.
|
|
<!-- SECTION:DESCRIPTION:END -->
|
|
|
|
## Acceptance Criteria
|
|
<!-- AC:BEGIN -->
|
|
- [ ] #1 A phased decomposition plan is defined in task links and references the following target files: src/main.ts, src/anki-integration.ts, src/core/services/mpv-service.ts, src/renderer/*, src/config/*, and src/core/services/*.
|
|
- [ ] #2 Tasks are assigned with clear owners and include explicit dependencies so execution can proceed in parallel where safe.
|
|
- [ ] #3 Changes are constrained to structural refactors first (no behavior changes until foundational splits are in place).
|
|
- [ ] #4 Each subtask includes test/verification expectations (manual or automated) and a rollback-safe checkpoint.
|
|
<!-- AC:END -->
|
|
|
|
## Implementation Plan
|
|
|
|
<!-- SECTION:PLAN:BEGIN -->
|
|
## Revised Execution Sequence
|
|
|
|
### Phase 0 — Prerequisites (outside TASK-27 tree)
|
|
- **TASK-7** — Extract main.ts global state into AppState container (required before TASK-27.2)
|
|
- **TASK-9** — Remove trivial wrapper functions from main.ts (depends on TASK-7; recommended before TASK-27.2 but not blocking)
|
|
|
|
### Phase 1 — Lightweight Inventory
|
|
- **TASK-27.1** — Inventory files >400 LOC, document contracts, define smoke test checklist
|
|
|
|
### Phase 2 — Sequential Split Wave
|
|
Order matters to avoid merge conflicts:
|
|
1. **TASK-27.3** — anki-integration.ts split (self-contained, doesn't affect main.ts wiring until facade is stable)
|
|
2. **TASK-27.2** — main.ts split (after TASK-7 provides AppState container and 27.3 stabilizes the Anki facade)
|
|
3. **TASK-27.4** — mpv-service.ts split (absorbs TASK-8 scope; blocked until 27.1 is done)
|
|
4. **TASK-27.5** — renderer positioning.ts split (downscoped; after 27.2 to avoid import-path conflicts)
|
|
|
|
### Phase 3 — Stabilization
|
|
- **TASK-27.6** — Quality gates and CI enforcement
|
|
|
|
## Smoke Test Checklist (applies to all subtasks)
|
|
Every subtask must verify before merging:
|
|
- [ ] App starts and connects to MPV
|
|
- [ ] Subtitle text appears in overlay
|
|
- [ ] Card mining creates a note in Anki
|
|
- [ ] Field grouping modal opens and resolves
|
|
- [ ] Global shortcuts work (mine, toggle overlay, copy subtitle)
|
|
- [ ] Secondary subtitle display works
|
|
- [ ] TypeScript compiles with no new errors
|
|
- [ ] All existing tests pass (`pnpm test:core && pnpm test:config`)
|
|
<!-- SECTION:PLAN:END -->
|
|
|
|
## Implementation Notes
|
|
|
|
<!-- SECTION:NOTES:BEGIN -->
|
|
## Review Findings (2026-02-13)
|
|
|
|
### Key changes from original plan:
|
|
1. **Dropped parallel execution of Phase 2** — TASK-27.2 and 27.5 share import paths; 27.2 and 27.3 share main.ts wiring. Sequential order prevents merge conflicts.
|
|
2. **Added TASK-7 as external prerequisite** — main.ts has 30+ module-level `let` declarations. Splitting files without a state container first just scatters mutable state.
|
|
3. **TASK-8 absorbed into TASK-27.4** — TASK-8 (separate protocol from app logic) and TASK-27.4 (physical file split) overlap significantly. TASK-27.4 now covers both.
|
|
4. **TASK-27.5 downscoped** — Renderer is already well-organized (241-line orchestrator, handlers/, modals/, utils/ directories). Only positioning.ts (513 LOC) needs splitting.
|
|
5. **Simplified ownership model** — Removed multi-owner ceremony since this is effectively a solo project. Kept labels for categorical tracking only.
|
|
6. **Added global smoke test checklist** — No end-to-end or renderer tests exist, so manual verification is the safety net for every subtask.
|
|
<!-- SECTION:NOTES:END -->
|
|
|
|
## Definition of Done
|
|
<!-- DOD:BEGIN -->
|
|
- [ ] #1 Plan task links and ordering are recorded in backlog descriptions.
|
|
- [ ] #2 At least 2 independent owners are assigned with explicit labels in subtasks.
|
|
<!-- DOD:END -->
|