167 lines
7.3 KiB
Markdown
167 lines
7.3 KiB
Markdown
# V1 Block 09 — Persistence Preparation
|
|
|
|
Status: In progress — Chunks 9.1 and 9.2 complete
|
|
|
|
Purpose: Prepare the domain layer for future MongoDB-backed persistence without adding a MongoDB driver, network behavior, sync behavior, or database runtime dependency too early.
|
|
|
|
MongoDB is the committed persistence target. This block should make the core persistence-friendly and MongoDB-document-friendly while keeping the scheduling engine independent from database APIs.
|
|
|
|
## Chunk 9.1 — Repository interface
|
|
|
|
Recommended Codex level: medium
|
|
|
|
Tasks:
|
|
|
|
Define repository interfaces for:
|
|
|
|
- tasks
|
|
- projects
|
|
- locked blocks
|
|
- scheduling operations/state snapshots
|
|
|
|
Rules:
|
|
|
|
- Do not couple the scheduling engine directly to MongoDB APIs.
|
|
- Use interfaces that a future MongoDB adapter can implement.
|
|
- Keep the current implementation in-memory if needed.
|
|
- Repository interfaces should preserve domain rules rather than bypassing services.
|
|
- Do not introduce alternative database assumptions.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Domain services can depend on interfaces.
|
|
- Tests can use fake/in-memory repositories.
|
|
- Interfaces do not import MongoDB, Flutter, platform-specific APIs, or network/client APIs.
|
|
- Interface names and method shapes are compatible with document-style persistence.
|
|
|
|
Completed:
|
|
|
|
- Added pure Dart repository interfaces for tasks, projects, locked blocks/overrides, and scheduling state snapshots.
|
|
- Added in-memory repository implementations for tests and early app wiring.
|
|
- Added scheduling snapshot state that can rebuild `SchedulingInput` and `SchedulingResult` without persistence APIs.
|
|
- Exported repository interfaces through the public core library.
|
|
- Added repository tests covering task/project/locked-block/snapshot fake usage.
|
|
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.
|
|
|
|
BREAKPOINT: Stop here. Confirm `extra high` mode before implementing the persistence edge-case test suite.
|
|
|
|
## Chunk 9.2 — Persistence edge-case regression test suite
|
|
|
|
Recommended Codex level: extra high
|
|
|
|
Tasks:
|
|
|
|
Before model serialization changes, add or expand tests that define persistence-sensitive behavior clearly.
|
|
|
|
Cover these cases:
|
|
|
|
- task IDs remain stable across copy/update operations
|
|
- project IDs remain stable across copy/update operations
|
|
- locked block IDs remain stable across copy/update operations
|
|
- DateTime values are stored and compared using the documented convention
|
|
- nullable fields can be intentionally preserved
|
|
- nullable fields that need clearing have explicit clear behavior or documented mapping behavior
|
|
- enum values have stable persistence names or a clearly tested mapping plan
|
|
- `RewardLevel.notSet` remains distinct from `RewardLevel.veryLow`
|
|
- backlog age behavior has a documented source timestamp or TODO before database work
|
|
- in-memory fake repositories can round-trip saved records without losing scheduling fields
|
|
- repository operations do not mutate input objects unexpectedly
|
|
- document-shaped maps preserve all fields needed by future MongoDB persistence
|
|
- generated document field names are stable and migration-friendly
|
|
|
|
Rules:
|
|
|
|
- This chunk may add tests and small model helpers needed to make persistence behavior testable.
|
|
- Do not add a MongoDB driver, MongoDB client, Atlas setup, connection string, local MongoDB service requirement, or database adapter yet.
|
|
- Do not add alternative database mappings or non-MongoDB terminology.
|
|
- Do not add sync, networking, cloud accounts, or background services.
|
|
- Do not mark this chunk complete unless `dart analyze` and `dart test` pass.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Persistence-sensitive test group exists.
|
|
- Tests capture stable IDs, enum mapping, nullable-field behavior, DateTime convention, and document-shaped mapping expectations.
|
|
- Any unresolved persistence detail is documented as a TODO in the plan or architecture notes.
|
|
- No alternative-database references remain in the active persistence plan.
|
|
|
|
Completed:
|
|
|
|
- Added persistence edge-case regression tests for stable task, project, and locked-block IDs across copy/update helpers.
|
|
- Added UTC ISO-8601 DateTime persistence convention helpers and tests.
|
|
- Added enum persistence-name mapping tests, including `RewardLevel.notSet` remaining distinct from `RewardLevel.veryLow`.
|
|
- Added nullable-field preservation and explicit schedule-clearing tests.
|
|
- Added backlog age source tests documenting `Task.createdAt` as the current staleness source.
|
|
- Added in-memory repository round-trip and unmodifiable-read tests.
|
|
- Added MongoDB-oriented document field-name constants and tests for task/statistics, project, locked-block, override, scheduling snapshot, and embedded scheduling structures.
|
|
- Verified with `dart format lib test`, `dart analyze`, and `dart test`.
|
|
|
|
TODO for Chunk 9.3:
|
|
|
|
- Define document mapping behavior for clearing nullable non-schedule fields before adding model serialization helpers. Current explicit clear behavior only covers task schedule placement through `Task.copyWith(clearSchedule: true)`.
|
|
|
|
BREAKPOINT: Stop here. Confirm `high` mode before model serialization changes.
|
|
|
|
## Chunk 9.3 — MongoDB-document-safe models
|
|
|
|
Recommended Codex level: high
|
|
|
|
Tasks:
|
|
|
|
Make models persistence-friendly and MongoDB-document-friendly:
|
|
|
|
- stable IDs
|
|
- enum serialization helpers or clear mapping plan
|
|
- DateTime handling convention
|
|
- nullable fields documented
|
|
- nullable field clear helpers where needed
|
|
- migration-safe document field names where possible
|
|
- document-shaped map conversion helpers only if they do not over-couple the domain layer
|
|
- clear mapping rules for nested task statistics and future child-task ownership fields
|
|
|
|
Rules:
|
|
|
|
- Keep model helpers independent from MongoDB client libraries.
|
|
- Prefer plain Dart map/document shapes that a later adapter can translate into MongoDB documents.
|
|
- Do not introduce database connection logic in this chunk.
|
|
- Do not add table assumptions, joins, or relational schema requirements.
|
|
|
|
Acceptance criteria:
|
|
|
|
- Models can round-trip through document-shaped map/json-like structures or have a clear TODO for MongoDB document mappings.
|
|
- Tests cover at least task serialization if implemented.
|
|
- Tests cover enum persistence mapping if implemented.
|
|
- Tests cover intentional clearing of nullable fields if helper behavior is added.
|
|
- Tests confirm `not set` reward remains distinct from very low reward through mapping.
|
|
|
|
BREAKPOINT: Stop here. Confirm `low` mode before documenting the explicit non-sync boundary.
|
|
|
|
## Chunk 9.4 — Explicit non-sync / no-database-runtime boundary
|
|
|
|
Recommended Codex level: low
|
|
|
|
Tasks:
|
|
|
|
Document that V1 persistence work prepares for MongoDB but does not implement runtime database access, sync, accounts, or background services.
|
|
|
|
Rules:
|
|
|
|
- No network sync code.
|
|
- No cloud assumptions.
|
|
- No MongoDB connection strings.
|
|
- No Atlas setup.
|
|
- No local MongoDB server requirement.
|
|
- No background service implementation.
|
|
- No mobile notification or background reconciliation implementation in this block.
|
|
|
|
Acceptance criteria:
|
|
|
|
- README or architecture doc states MongoDB is the committed persistence target.
|
|
- README or architecture doc states this block does not require a running MongoDB instance.
|
|
- Docs distinguish MongoDB persistence preparation from actual sync or database adapter implementation.
|
|
- Wishlist/future notes contain sync as a later feature, not a V1 requirement.
|
|
|
|
Commit suggestion:
|
|
|
|
```text
|
|
feat(data): prepare MongoDB-friendly persistence interfaces
|
|
```
|