generated from john/python-template
105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
# Draft Implementation Plan (Version 4.3)
|
|
|
|
## Goal
|
|
|
|
Prepare a safe implementation path for constrained application settings. This plan remains provisional until the V4.3 scope-freeze decisions are resolved.
|
|
|
|
## Planning Constraints
|
|
|
|
- V4, V4.1, and V4.2 remain the behavioral baseline.
|
|
- Settings must use explicit domain operations rather than direct database, environment-file, or arbitrary filesystem access from UI pages.
|
|
- Prompt changes must preserve historical Job provenance and use a defined safe-write policy.
|
|
|
|
## Expected Project Impact
|
|
|
|
| Area | Expected impact |
|
|
| --- | --- |
|
|
| Documents service | Expand controlled Document Type maintenance operations. |
|
|
| People service | Expand controlled Person Role maintenance operations. |
|
|
| Prompt adapter/service | Add constrained listing, reading, validation, and safe writing of prompt artifacts. |
|
|
| UI composition/navigation | Register Settings routes and navigation without moving persistence into UI code. |
|
|
| Tests | Add registry lifecycle, prompt safety, and UI workflow coverage. |
|
|
|
|
## Proposed Implementation Phases
|
|
|
|
### 1. Resolve Scope-Freeze Decisions
|
|
|
|
- Define prompt atomic-write, backup, and recovery policy.
|
|
- Decide whether prompt creation/deletion is excluded.
|
|
- Finalize registry ordering requirements.
|
|
- Remove the Draft designation only after these decisions are reflected in scope and acceptance criteria.
|
|
|
|
### 2. Define Service Contracts
|
|
|
|
- Define Document Type maintenance commands for create, relabel, sort, activate, and deactivate.
|
|
- Define Person Role maintenance commands for create, relabel, activate, and deactivate.
|
|
- Define a Prompt Store interface for constrained list/read/write behavior.
|
|
- Map validation, conflict, not-found, dependency, and filesystem failures to existing `AppError` categories.
|
|
|
|
### 3. Expand Registry Maintenance Services
|
|
|
|
- Reuse existing Document and People service ownership.
|
|
- Add explicit write methods rather than passing UI-mutated ORM objects directly where practical.
|
|
- Normalize and validate new stable codes.
|
|
- Reject duplicate codes deterministically.
|
|
- Block deletion or omit deletion entirely; use activation state for lifecycle management.
|
|
- Preserve inactive entries for historical reads.
|
|
- Add service tests for create, relabel, activation, deactivation, duplicates, immutable codes, and referenced records.
|
|
|
|
### 4. Add Constrained Prompt Storage
|
|
|
|
- Place filesystem access behind a dedicated Prompt Store/service boundary.
|
|
- Resolve all filenames directly beneath the configured prompt root and reject traversal.
|
|
- Permit only the agreed markdown extension and reject empty content.
|
|
- Implement the approved safe-write strategy, including flush/replace behavior and backup/recovery if selected.
|
|
- Preserve file encoding and provide explicit failures for read-only or unavailable storage.
|
|
- Do not modify any Job row when prompt defaults change.
|
|
- Add unit tests for valid reads/writes, traversal, invalid names, empty content, filesystem failures, and unchanged Job provenance.
|
|
|
|
### 5. Build the Settings UI
|
|
|
|
- Register a Settings landing page and navigation entry.
|
|
- Add separate pages or panels for Document Types, Person Roles, and Prompts.
|
|
- Keep pages responsible for orchestration and notifications only.
|
|
- Use service callbacks for all mutations.
|
|
- Explain stable codes, inactive historical entries, and future-only prompt effects in the UI.
|
|
- Do not render raw environment values or secrets.
|
|
|
|
### 6. Verification and Rollout
|
|
|
|
- Run focused service tests before UI integration tests.
|
|
- Verify inactive registry behavior in both historical display and create/edit selectors.
|
|
- Verify prompt changes are picked up by newly created Jobs while historical Jobs retain frozen content/hash.
|
|
- Run the relevant regression suite.
|
|
|
|
## Migration and Compatibility Notes
|
|
|
|
- Existing registry records remain valid.
|
|
- Prompt editing changes mutable application files, not database provenance already captured on Jobs.
|
|
- V4.3 must not require users to recreate existing Sources, Documents, People, roles, or types.
|
|
|
|
## Proposed Delivery Order
|
|
|
|
1. Freeze the remaining decisions.
|
|
2. Implement registry maintenance service operations.
|
|
3. Implement the Prompt Store and safety policy.
|
|
4. Build Settings pages.
|
|
5. Run integration and regression verification.
|
|
|
|
## Draft Done Criteria
|
|
|
|
- All V4.3 acceptance criteria are testable and satisfied.
|
|
- Settings mutations cross explicit service or adapter boundaries.
|
|
- Registry codes cannot be accidentally changed.
|
|
- Prompt writes cannot escape the configured directory or rewrite historical provenance.
|
|
- No secret or raw environment editor exists.
|
|
- V4.1 and V4.2 workflows remain intact.
|
|
|
|
## Related Local References
|
|
|
|
- [Draft V4.3 Scope Boundary](scope_boundary_v4_3.md)
|
|
- [V4.2 Implementation Plan](../ver4.2/implementation_plan_v4_2.md)
|
|
- [V4.1 Implementation Plan](../ver4.1/implementation_plan_v4_1.md)
|
|
- [V4 Implementation Plan](../ver4/implementation_plan_v4.md)
|
|
- [V4 Error Handling Policy](../ver4/error_handling_v4.md)
|