generated from john/python-template
V4.1 Mostly UI adjustments by GC
This commit is contained in:
Jim Lancaster
@@ -0,0 +1,137 @@
|
||||
# Draft Implementation Plan (Version 4.2)
|
||||
|
||||
## Goal
|
||||
|
||||
Prepare a safe implementation path for Source page reordering and constrained application settings. This plan remains provisional until the V4.2 scope-freeze decisions are resolved.
|
||||
|
||||
## Planning Constraints
|
||||
|
||||
- V4 and V4.1 remain the behavioral baseline.
|
||||
- Reordering must be atomic and service-owned.
|
||||
- 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 |
|
||||
| --- | --- |
|
||||
| Sources service | Add validated, transactional set-based page reordering. |
|
||||
| Documents/Sources UI | Add a reorder entry point and interaction for one Document. |
|
||||
| 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 transaction, conflict, registry lifecycle, prompt safety, and UI workflow coverage. |
|
||||
|
||||
## Proposed Implementation Phases
|
||||
|
||||
### 1. Resolve Scope-Freeze Decisions
|
||||
|
||||
- Select and document the reorder interaction.
|
||||
- Define whether active Jobs block reorder.
|
||||
- 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 a Source reorder command containing `document_id`, the complete ordered Source ID list, and a concurrency token or equivalent stale-write guard if supported by the current model.
|
||||
- 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. Implement Transactional Source Reordering
|
||||
|
||||
- Load all Sources for the target Document in the same transaction.
|
||||
- Reject missing, extra, duplicate, or foreign Source IDs.
|
||||
- Reject stale writes using the selected concurrency policy.
|
||||
- Apply a collision-safe renumbering strategy suitable for both SQLite and PostgreSQL.
|
||||
- Finish with contiguous `page_number` values beginning at 1.
|
||||
- Roll back the entire operation on any failure.
|
||||
- Add service tests for valid reorder, no-op, reverse order, invalid membership, duplicates, stale submissions, rollback, and backend-compatible SQL behavior.
|
||||
|
||||
### 4. Implement the Reorder UI
|
||||
|
||||
- Add a Reorder Pages action from a Document-scoped Source view or Document Detail.
|
||||
- Render Source labels/previews sufficient to identify each page.
|
||||
- Capture the complete intended order.
|
||||
- Require explicit Save and provide Cancel without mutation.
|
||||
- Surface validation and conflict errors through the shared error presenter.
|
||||
- Return to a Document-scoped ordered view after success.
|
||||
- Verify keyboard-accessible controls for any drag-and-drop interaction.
|
||||
|
||||
### 5. 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.
|
||||
|
||||
### 6. 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.
|
||||
|
||||
### 7. 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.
|
||||
|
||||
### 8. Verification and Rollout
|
||||
|
||||
- Run focused service tests before UI integration tests.
|
||||
- Verify reorder behavior against Documents with one and many Sources.
|
||||
- Verify ordered transcription rendering and V4.1 previous/next navigation after reorder.
|
||||
- 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
|
||||
|
||||
- No new table is expected solely for reordering; `Source.page_number` remains authoritative.
|
||||
- A uniqueness constraint on `(document_id, page_number)` should be evaluated before scope freeze. If added, migration and collision-safe update behavior must be designed for both supported databases.
|
||||
- Existing registry records remain valid.
|
||||
- Prompt editing changes mutable application files, not database provenance already captured on Jobs.
|
||||
- V4.2 must not require users to recreate existing Sources, Documents, People, roles, or types.
|
||||
|
||||
## Proposed Delivery Order
|
||||
|
||||
1. Freeze the remaining decisions.
|
||||
2. Implement and verify Source reorder service semantics.
|
||||
3. Build the reorder UI.
|
||||
4. Implement registry maintenance service operations.
|
||||
5. Implement the Prompt Store and safety policy.
|
||||
6. Build Settings pages.
|
||||
7. Run integration and regression verification.
|
||||
|
||||
## Draft Done Criteria
|
||||
|
||||
- All V4.2 acceptance criteria are testable and satisfied.
|
||||
- Reordering is atomic, conflict-aware, contiguous, and cross-database compatible.
|
||||
- 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 workflows remain intact.
|
||||
|
||||
## Related Local References
|
||||
|
||||
- [Draft V4.2 Scope Boundary](scope_boundary_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)
|
||||
|
||||
@@ -0,0 +1,130 @@
|
||||
# Draft V4.2 Scope Boundary
|
||||
|
||||
This document defines the proposed boundary for the second incremental revision to Version 4. It is intentionally a draft until V4.1 has been used and the remaining workflows have been validated.
|
||||
|
||||
## Purpose
|
||||
|
||||
- Allow correction of Source page order after import.
|
||||
- Provide a constrained Settings area for safe maintenance of selected application-managed configuration.
|
||||
- Avoid exposing secrets, restart-sensitive settings, or unrestricted filesystem editing through the UI.
|
||||
|
||||
## Proposed In Scope
|
||||
|
||||
### 1. Source Page Reordering
|
||||
|
||||
- Allow Sources within one Document to be reordered after import.
|
||||
- Present the current order using page number and a recognizable source label or preview.
|
||||
- Persist the complete intended order atomically.
|
||||
- Renumber the affected Document's Sources to a contiguous sequence beginning at 1.
|
||||
- Keep all Sources attached to their existing Document.
|
||||
- Ensure transcription rendering and previous/next navigation use the updated order.
|
||||
- Detect stale or invalid reorder submissions and fail without partial mutation.
|
||||
|
||||
### 2. Settings Navigation
|
||||
|
||||
- Add a Settings entry to application navigation.
|
||||
- Provide separate, clearly described settings areas rather than a raw configuration editor.
|
||||
- Restrict V4.2 settings to application-managed values that can be validated and safely changed at runtime.
|
||||
|
||||
### 3. Document Type Maintenance
|
||||
|
||||
- List active and inactive Document Types.
|
||||
- Add new types with a stable unique code and user-facing label.
|
||||
- Edit mutable labels and sort order.
|
||||
- Activate or deactivate types without invalidating historical Documents.
|
||||
- Do not allow changing a stable code after creation.
|
||||
- Do not delete types that are referenced by Documents.
|
||||
|
||||
### 4. Person Role Maintenance
|
||||
|
||||
- List active and inactive Person Roles.
|
||||
- Add new roles with a stable unique code and user-facing label.
|
||||
- Edit mutable labels.
|
||||
- Activate or deactivate roles without invalidating historical links.
|
||||
- Do not allow changing a stable code after creation.
|
||||
- Do not delete roles that are referenced by document-person links.
|
||||
|
||||
### 5. Prompt Maintenance
|
||||
|
||||
- List prompt markdown files from the configured prompt directory.
|
||||
- View a prompt with a concise explanation of its purpose and use.
|
||||
- Edit an existing prompt as plain markdown text.
|
||||
- Validate the filename boundary and reject empty prompt content.
|
||||
- Save changes explicitly and report filesystem failures.
|
||||
- Preserve submission-time prompt text and hash already frozen on existing Jobs.
|
||||
- Define a safe-write and recovery approach before this feature is considered final scope.
|
||||
|
||||
## Proposed Out of Scope
|
||||
|
||||
- Viewing or editing raw `.env` files.
|
||||
- Displaying or changing provider API keys and other secrets.
|
||||
- Editing host, port, database connection, upload paths, or other restart-sensitive runtime settings.
|
||||
- Arbitrary file browsing or arbitrary prompt paths.
|
||||
- Runtime theme/CSS editing.
|
||||
- Installing themes or plugins.
|
||||
- Source movement between Documents as part of reordering.
|
||||
- Automatic ordering based on filenames, OCR, or image content.
|
||||
- FamilySearch API synchronization.
|
||||
- A generic external-reference registry.
|
||||
- Ancestry references and Google Maps links.
|
||||
|
||||
## Proposed Design Decisions
|
||||
|
||||
### A. Reordering Is Set-Based
|
||||
|
||||
- The client submits the full ordered list of Source IDs for one Document.
|
||||
- The service validates membership, completeness, duplicates, and authorization/context before writing.
|
||||
- All page-number updates occur in one transaction.
|
||||
|
||||
### B. Registry Codes Are Immutable
|
||||
|
||||
- Document Type and Person Role codes are stable identifiers.
|
||||
- Labels and active state remain mutable.
|
||||
- Historical references remain valid when a registry entry is inactive.
|
||||
|
||||
### C. No Raw Environment Editor
|
||||
|
||||
- `.env` may contain secrets and values that are not safely reloadable.
|
||||
- V4.2 exposes only purpose-built forms backed by explicit validation and service methods.
|
||||
|
||||
### D. Prompt Editing Is Constrained
|
||||
|
||||
- Prompt maintenance is limited to direct children of the configured prompt directory.
|
||||
- Existing Job provenance is never rewritten when a prompt file changes.
|
||||
- The UI must distinguish editing the default for future submissions from inspecting historical Job prompts.
|
||||
|
||||
## Decisions Required Before Scope Freeze
|
||||
|
||||
1. Choose the reorder interaction: move-up/down controls, drag-and-drop, or both.
|
||||
2. Decide whether reordering is allowed while the Document has a queued or processing Job.
|
||||
3. Define prompt backup, atomic-write, and recovery behavior.
|
||||
4. Decide whether prompt creation and deletion are needed or whether V4.2 edits existing prompts only.
|
||||
5. Confirm whether registry sort-order maintenance is needed for Person Roles as well as Document Types.
|
||||
6. Confirm that settings changes remain local to the current installation and do not require an API surface.
|
||||
|
||||
## Draft Acceptance Criteria
|
||||
|
||||
1. Reordering a Document's Sources produces contiguous page numbers and updates every ordered view consistently.
|
||||
2. Invalid, incomplete, duplicate, cross-Document, or stale reorder requests make no changes.
|
||||
3. Document Type and Person Role maintenance preserves stable codes and historical references.
|
||||
4. Inactive registry entries remain visible on historical records but are excluded from default create selectors.
|
||||
5. Prompt edits are restricted to valid markdown files in the configured prompt directory.
|
||||
6. A prompt edit affects future Jobs only and leaves stored Job provenance unchanged.
|
||||
7. No Settings page exposes secrets or unrestricted filesystem access.
|
||||
8. Focused service and UI tests pass without regressing V4.1 workflows.
|
||||
|
||||
## Scope Freeze Gate
|
||||
|
||||
V4.2 implementation should not begin until:
|
||||
|
||||
- V4.1 has been used sufficiently to validate priorities.
|
||||
- The six open decisions above are resolved.
|
||||
- The prompt-write safety policy is documented.
|
||||
- The implementation plan is revised from draft to committed delivery plan.
|
||||
|
||||
## Related Local References
|
||||
|
||||
- [Draft V4.2 Implementation Plan](implementation_plan_v4_2.md)
|
||||
- [V4.1 Scope Boundary](../ver4.1/scope_boundary_v4_1.md)
|
||||
- [V4 Architecture](../ver4/architecture_v4.md)
|
||||
- [V4 Schema](../ver4/schema_v4.md)
|
||||
Reference in New Issue
Block a user