Joseph Doherty
26ff8d9b4f
Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
194 lines
7.2 KiB
Markdown
194 lines
7.2 KiB
Markdown
# Migration Phase Proposals Plan
|
|
|
|
## Objective
|
|
|
|
Create OpenSpec change proposals for all remaining migration phases (2-9), review each with Codex MCP, answer questions with best practices, and collect unanswered questions in questions.md.
|
|
|
|
## Phases Overview
|
|
|
|
| Phase | Change ID | Spec Dependencies | Parallelizable |
|
|
|-------|-----------|-------------------|----------------|
|
|
| 1 | migrate-database-schema | database-schema, sql-views-types, sql-business-logic | ✅ DONE |
|
|
| 2 | setup-solution-foundation | (infrastructure) | Yes |
|
|
| 3 | implement-domain-models | domain-models | Yes |
|
|
| 4 | implement-data-access | data-access | Yes |
|
|
| 5 | implement-data-sync | data-sync | Yes |
|
|
| 6 | implement-search-processing | search-processing | Yes |
|
|
| 7 | implement-excel-export | excel-export | Yes |
|
|
| 8 | implement-web-api | web-api-auth | Yes |
|
|
| 9 | implement-blazor-ui | web-ui | Yes |
|
|
|
|
## Execution Strategy
|
|
|
|
### Batch 1: Parallel Proposals (Phases 2-5)
|
|
Create 4 proposals in parallel - these are foundational phases.
|
|
|
|
**Phase 2: setup-solution-foundation**
|
|
- Scope: DI configuration, appsettings structure, project references, base infrastructure
|
|
- Key deliverables: Program.cs setup, configuration binding, service registration patterns
|
|
- No spec dependencies (infrastructure scaffolding)
|
|
|
|
**Phase 3: implement-domain-models**
|
|
- Scope: All domain entities from domain-models spec (52 requirements)
|
|
- Key deliverables: Models/, Enums/, Extensions/, validation
|
|
- Dependencies: Phase 2 (solution structure)
|
|
|
|
**Phase 4: implement-data-access**
|
|
- Scope: Repository interfaces and implementations (50+ requirements)
|
|
- Key deliverables: ILotFinderRepository, IJdeRepository, ICmsRepository, IDbConnectionFactory
|
|
- Dependencies: Phase 3 (domain models)
|
|
|
|
**Phase 5: implement-data-sync**
|
|
- Scope: BackgroundService for cache refresh (15+ requirements)
|
|
- Key deliverables: DataSyncService, IDataFetcher<T>, health checks
|
|
- Dependencies: Phase 4 (data access)
|
|
|
|
### Batch 2: Parallel Proposals (Phases 6-7)
|
|
Create 2 proposals in parallel - these are processing phases.
|
|
|
|
**Phase 6: implement-search-processing**
|
|
- Scope: SqlKata query building, search execution
|
|
- Key deliverables: ISearchQueryBuilder, SearchProcessor, filter handlers
|
|
- Dependencies: Phase 4 (data access)
|
|
|
|
**Phase 7: implement-excel-export**
|
|
- Scope: ClosedXML workbook generation
|
|
- Key deliverables: IExcelExportService, sheet generators, formatting
|
|
- Dependencies: Phase 6 (search results)
|
|
|
|
### Batch 3: Sequential Proposals (Phases 8-9)
|
|
Create 2 proposals - API then UI.
|
|
|
|
**Phase 8: implement-web-api**
|
|
- Scope: REST endpoints, SignalR hub, authentication
|
|
- Key deliverables: Controllers, StatusHub, IAuthService, LDAP integration
|
|
- Dependencies: Phases 5, 6, 7
|
|
|
|
**Phase 9: implement-blazor-ui**
|
|
- Scope: Blazor WASM pages and components
|
|
- Key deliverables: Pages/, Components/, SignalR client, Radzen integration
|
|
- Dependencies: Phase 8 (API endpoints)
|
|
|
|
## Proposal Template
|
|
|
|
Each proposal follows OpenSpec structure:
|
|
```
|
|
openspec/changes/<change-id>/
|
|
├── proposal.md # Summary, scope, acceptance criteria
|
|
├── design.md # Architecture decisions (when needed)
|
|
├── tasks.md # Ordered work items with validation
|
|
└── specs/ # Spec deltas (ADDED/MODIFIED requirements)
|
|
└── <spec-name>/
|
|
└── spec.md
|
|
```
|
|
|
|
## Codex MCP Review Prompts
|
|
|
|
**For each proposal, run:**
|
|
```
|
|
Review openspec/changes/<change-id>/ against:
|
|
- openspec/specs/<related-spec>/spec.md
|
|
- OLD/<legacy-source-files>
|
|
- NEW/src/<target-directories>
|
|
|
|
Verify:
|
|
1. All requirements from spec are covered in tasks
|
|
2. Dependency order is correct
|
|
3. Acceptance criteria are measurable
|
|
4. Design decisions align with specs
|
|
|
|
Report gaps, errors, recommendations.
|
|
```
|
|
|
|
## Best Practice Decisions
|
|
|
|
Pre-answer common questions with best practices:
|
|
|
|
| Question | Decision | Rationale |
|
|
|----------|----------|-----------|
|
|
| Async vs sync methods | Async-first with CancellationToken | Modern .NET pattern |
|
|
| Exception handling | Custom typed exceptions per layer | Clear error propagation |
|
|
| Configuration | IOptions<T> pattern | Type-safe, testable |
|
|
| Logging | ILogger<T> with structured logging | Framework integration |
|
|
| Testing | xUnit + Shouldly + NSubstitute | Project constraints (no FluentAssertions) |
|
|
| DI lifetime | Scoped for DB, Singleton for config | Standard patterns |
|
|
| Nullable refs | Enable project-wide | Modern C# safety |
|
|
|
|
## Questions Collection
|
|
|
|
All unanswered questions go to: `openspec/changes/questions.md`
|
|
|
|
Format:
|
|
```markdown
|
|
## Phase N: <change-id>
|
|
|
|
### Question: <topic>
|
|
- Context: <why this matters>
|
|
- Options: <possible answers>
|
|
- Impact: <what depends on this decision>
|
|
```
|
|
|
|
## Execution Order
|
|
|
|
1. **Create questions.md** - Empty file for collecting questions
|
|
2. **Batch 1** - Launch 4 parallel agents for Phases 2-5
|
|
3. **Review Batch 1** - Codex MCP review all 4 proposals
|
|
4. **Batch 2** - Launch 2 parallel agents for Phases 6-7
|
|
5. **Review Batch 2** - Codex MCP review both proposals
|
|
6. **Batch 3** - Create Phase 8, then Phase 9 (sequential due to dependencies)
|
|
7. **Review Batch 3** - Codex MCP review both proposals
|
|
8. **Final validation** - `openspec validate --changes` for all proposals
|
|
9. **Summary** - Report all proposals created, questions collected
|
|
|
|
## Validation Checklist
|
|
|
|
For each proposal:
|
|
- [ ] `openspec validate <change-id> --strict` passes
|
|
- [ ] Codex MCP review completed
|
|
- [ ] All answerable questions resolved with best practice
|
|
- [ ] Unanswerable questions added to questions.md
|
|
- [ ] Dependencies on other phases documented
|
|
|
|
## Critical Files
|
|
|
|
```
|
|
openspec/
|
|
├── changes/
|
|
│ ├── questions.md # Collected unanswered questions
|
|
│ ├── migrate-database-schema/ # ✅ DONE
|
|
│ ├── setup-solution-foundation/ # Phase 2
|
|
│ ├── implement-domain-models/ # Phase 3
|
|
│ ├── implement-data-access/ # Phase 4
|
|
│ ├── implement-data-sync/ # Phase 5
|
|
│ ├── implement-search-processing/ # Phase 6
|
|
│ ├── implement-excel-export/ # Phase 7
|
|
│ ├── implement-web-api/ # Phase 8
|
|
│ └── implement-blazor-ui/ # Phase 9
|
|
└── specs/
|
|
├── database-schema/
|
|
├── domain-models/
|
|
├── data-access/
|
|
├── data-sync/
|
|
├── search-processing/
|
|
├── excel-export/
|
|
├── web-api-auth/
|
|
├── web-ui/
|
|
├── sql-business-logic/
|
|
└── sql-views-types/
|
|
```
|
|
|
|
## Spec-to-Phase Mapping
|
|
|
|
| Spec | Primary Phase | Tasks |
|
|
|------|---------------|-------|
|
|
| database-schema | Phase 1 (DONE) | DbUp scripts |
|
|
| sql-views-types | Phase 1 (DONE) | Views, TVPs |
|
|
| sql-business-logic | Phase 1 (DONE) | Stored procedures |
|
|
| domain-models | Phase 3 | Entity classes |
|
|
| data-access | Phase 4 | Repository interfaces/implementations |
|
|
| data-sync | Phase 5 | BackgroundService |
|
|
| search-processing | Phase 6 | Query builder |
|
|
| excel-export | Phase 7 | ClosedXML service |
|
|
| web-api-auth | Phase 8 | Controllers, auth, SignalR |
|
|
| web-ui | Phase 9 | Blazor pages/components |
|