generated from john/python-template
143 lines
7.1 KiB
Markdown
143 lines
7.1 KiB
Markdown
# V4.1 Scope Boundary
|
|
|
|
This document defines the scope of the first incremental revision to Version 4. V4 remains the product and architecture baseline; V4.1 adds focused usability improvements and one additive Person field.
|
|
|
|
## Purpose
|
|
|
|
- Improve common archival record workflows without redesigning the application.
|
|
- Resolve table overflow, ambiguous person selection, and unnecessary navigation.
|
|
- Add a manually maintained FamilySearch person reference without introducing external API integration.
|
|
|
|
## In Scope
|
|
|
|
### 1. Archival Documents List
|
|
|
|
- Keep every table column within the available page width.
|
|
- Limit and wrap long Document Title values.
|
|
- Left-align Document Title and Type.
|
|
- Add Author and Document Date columns.
|
|
- Display all people linked through the `author` role in the Author column.
|
|
- Display exact document date when present, otherwise approximate date when present, otherwise `Unknown`.
|
|
|
|
### 2. Document Detail and Editing
|
|
|
|
- Use an unambiguous label in person selectors. The label should prefer Display Name, retain Full Name for context, and include the birth year when known.
|
|
- Do not require Display Name to be unique.
|
|
- Link each Related People entry to its Person Detail page.
|
|
- In view mode, display only the populated exact or approximate document date row. Display a single unknown/not-set state when neither exists.
|
|
- Keep both exact and approximate inputs available in create/edit mode.
|
|
- Move source navigation out from beneath the media viewer.
|
|
- Present Pipeline Jobs and Sources together in one related-processing card with counts and actions.
|
|
|
|
### 3. People List
|
|
|
|
- Left-align Display Name and Maiden Name.
|
|
- Display exact birth date when present, otherwise approximate birth date when present, otherwise `Unknown`.
|
|
- Add a Death Date column with the same fallback rule.
|
|
|
|
### 4. Person Detail and Editing
|
|
|
|
- Add a New Document action that opens Document creation with the current person preselected.
|
|
- Preserve the existing Document-first workflow.
|
|
- In view mode, display only the populated exact or approximate row for each of birth and death date. Display a single unknown/not-set state when neither value exists.
|
|
- Keep both exact and approximate inputs available in create/edit mode.
|
|
|
|
### 5. FamilySearch Reference
|
|
|
|
- Add a nullable, unique `family_search_id` field to `Person`.
|
|
- Allow the field to be entered and changed in Person create/edit flows.
|
|
- Trim whitespace, normalize the identifier to uppercase, and validate it against the supported
|
|
`XXXX-XXX` alphanumeric shape before persistence.
|
|
- When an identifier exists, show a FamilySearch action on Person Detail linking to:
|
|
`https://www.familysearch.org/tree/person/details/{family_search_id}`
|
|
- Construct the URL in application code; do not persist the full URL.
|
|
|
|
### 6. Source List and Detail
|
|
|
|
- Keep every Source Asset Records table column within the available page width.
|
|
- Limit and wrap long Document Name, Upload Title, and Error Detail values.
|
|
- Left-align Document Name, Upload Title, and Error Detail.
|
|
- Remove Stored Filename only from the Source Asset Records table. Continue storing it and showing it on Source Detail.
|
|
- On Source Detail, add previous and next navigation for Sources belonging to the same Document, ordered by `page_number`.
|
|
- Disable or omit the previous/next action at the first/last page.
|
|
|
|
### 7. Job Detail
|
|
|
|
- Automatically refresh Job Detail while the job is in a non-terminal state.
|
|
- Use a modest interval in the 3-5 second range.
|
|
- Stop polling when the job reaches a terminal state or the page is no longer active.
|
|
- Preserve manual navigation and existing job actions.
|
|
|
|
### 8. Homepage Storage Decision
|
|
|
|
- Continue treating homepage markdown and images as mutable application data, not prompt artifacts or packaged source assets.
|
|
- Keep homepage content separate from `prompts`.
|
|
- Defer relocation to a configurable application-data root unless the existing location prevents normal installed or deployed operation.
|
|
|
|
## Out of Scope
|
|
|
|
- Source page renumbering or reordering.
|
|
- A Settings page.
|
|
- Editing `.env` or secrets through the UI.
|
|
- Runtime theme editing.
|
|
- FamilySearch authentication, API calls, search, import, synchronization, or conflict resolution.
|
|
- Ancestry references or other genealogy providers.
|
|
- Google Maps links from place fields.
|
|
- Enforcing unique Display Name values.
|
|
- Changes to transcription execution or provider behavior.
|
|
- Changes to the V4 API solely to expose the V4.1 presentation enhancements.
|
|
|
|
## Locked Design Decisions
|
|
|
|
### A. Person Selector Identity
|
|
|
|
- Selection values remain internal Person UUIDs.
|
|
- Display labels provide disambiguating context but are not identity keys.
|
|
- Duplicate Full Name and Display Name values remain valid.
|
|
|
|
### B. Date Presentation
|
|
|
|
- Exact dates take precedence over approximate/raw dates for compact list and view presentation.
|
|
- Create/edit forms retain both fields so either representation can be maintained.
|
|
- V4.1 does not introduce a new mutual-exclusion database constraint.
|
|
|
|
### C. FamilySearch Storage
|
|
|
|
- Store only the FamilySearch person identifier.
|
|
- Treat a FamilySearch person identifier as unique across local Person records.
|
|
- Use one dedicated nullable Person field while FamilySearch is the only supported external genealogy reference.
|
|
- Reconsider a generic external-reference model only when a second provider or multiple references per person are required.
|
|
|
|
### D. Stored Filename
|
|
|
|
- Stored Filename remains part of the Source model and Source Detail diagnostics.
|
|
- Only the list-table column is removed.
|
|
|
|
## Data and Compatibility Policy
|
|
|
|
- The `family_search_id` addition must be nullable and non-destructive for existing Person rows.
|
|
- Existing records, routes, relationships, jobs, Sources, prompt provenance, and uploaded media remain valid.
|
|
- UI changes must preserve both Document-first and Person-first workflows.
|
|
- V4.1 must remain portable across SQLite and PostgreSQL.
|
|
|
|
## Acceptance Criteria
|
|
|
|
1. Document, Person, and Source tables fit their page containers at supported desktop widths without losing requested columns.
|
|
2. Long table text wraps or is constrained without forcing important columns outside the table container.
|
|
3. Duplicate-named people can be distinguished in every document relationship selector.
|
|
4. Related People entries navigate to the correct Person Detail page.
|
|
5. Compact date displays consistently use exact, then approximate, then unknown fallback behavior.
|
|
6. Starting from Person Detail can create a Document with that person preselected without breaking normal Document creation.
|
|
7. A valid FamilySearch ID is persisted and produces the correct Person Detail hyperlink; absent IDs produce no action.
|
|
8. Source previous/next actions remain within the same Document and follow `page_number`.
|
|
9. Active Job Detail pages update without manual refresh and stop polling after terminal status.
|
|
10. Stored Filename is absent from the Source list table but remains available on Source Detail.
|
|
11. Focused automated tests pass and unaffected V4 behavior remains intact.
|
|
|
|
## Related Local References
|
|
|
|
- [V4.1 Implementation Plan](implementation_plan_v4_1.md)
|
|
- [V4 Scope Boundary](../ver4.0/scope_boundary_v4.md)
|
|
- [V4 Architecture](../ver4/architecture_v4.md)
|
|
- [V4 Schema](../ver4/schema_v4.md)
|