From 0c023331f289459864adf7bc0a0e12ce497d97e7 Mon Sep 17 00:00:00 2001 From: karilint Date: Thu, 21 May 2026 11:34:42 +0300 Subject: [PATCH] Add entity documentation for people and museums --- documentation/README.md | 3 ++ documentation/entities/README.md | 32 +++++++++++++++++++ documentation/entities/museum.md | 44 ++++++++++++++++++++++++++ documentation/entities/people.md | 54 ++++++++++++++++++++++++++++++++ 4 files changed, 133 insertions(+) create mode 100644 documentation/entities/README.md create mode 100644 documentation/entities/museum.md create mode 100644 documentation/entities/people.md diff --git a/documentation/README.md b/documentation/README.md index b5317a34..60bf01b5 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -54,7 +54,10 @@ This folder is the canonical home for repository documentation. - [`devops/setup.md`](devops/setup.md) - [`devops/write-guard.md`](devops/write-guard.md) - [`entities/locality.md`](entities/locality.md) +- [`entities/README.md`](entities/README.md) +- [`entities/museum.md`](entities/museum.md) - [`entities/occurrence.md`](entities/occurrence.md) +- [`entities/people.md`](entities/people.md) - [`entities/project.md`](entities/project.md) - [`entities/reference.md`](entities/reference.md) - [`entities/reference_types.md`](entities/reference_types.md) diff --git a/documentation/entities/README.md b/documentation/entities/README.md new file mode 100644 index 00000000..58916ff9 --- /dev/null +++ b/documentation/entities/README.md @@ -0,0 +1,32 @@ +# Entity Documentation + +This folder documents the main domain entities used by NOW Database. The goal is to keep a short, practical map of how each user-facing concept relates to Prisma models, API routes, and common frontend usage. + +## Primary entities + +- [Localities](locality.md): locality records, dating methods, age fields, coordinates, and locality tabs. +- [Species](species.md): taxonomy records, required taxonomy fields, and species synonyms. +- [Occurrences](occurrence.md): locality-species relationships and occurrence-specific editable fields. +- [References](reference.md): reference records, reference types, authors, journals, and entity-reference links. +- [Time Units](time_unit.md): named geologic time units and sequence/rank data. +- [Time Bounds](time_bound.md): lower and upper bounds used by time units and locality dating. + +## Supporting entities + +- [Museums](museum.md): museum lookup records and locality-museum links. +- [People](people.md): person records, optional user accounts, roles, and coordinator/contact links. +- [Projects](project.md): projects, project contacts, project people, and locality/project links. +- [Regions](region.md): named regions, countries, and coordinators. +- [Reference Types](reference_types.md): available reference type definitions. + +## Coverage notes + +The Prisma schema also contains lower-level join, update-log, synonym, and lookup tables. Those should usually be documented inside the closest user-facing entity page unless they become independently editable in the UI. + +When adding an entity page, include: + +- the main Prisma model/table name +- important relation tables +- the routes used by the UI +- the permission model, if it differs from the default authenticated read/edit flow +- any known implementation caveats that would help the next change diff --git a/documentation/entities/museum.md b/documentation/entities/museum.md new file mode 100644 index 00000000..9dc271e8 --- /dev/null +++ b/documentation/entities/museum.md @@ -0,0 +1,44 @@ +# Museums + +Museums are institution lookup records that can be linked to localities. The museum record itself describes the institution; the locality tab stores which museums are connected to a locality. + +## Database model + +The main museum lookup record is `com_mlist`: + +- `museum` (primary key, museum code) +- `institution` +- `alt_int_name` +- `city` +- `state_code` +- `state` +- `country` +- `used_morph` +- `used_now` +- `used_gene` + +Locality links are stored in `now_mus`: + +- `lid` references `now_loc.lid` +- `museum` references `com_mlist.museum` +- composite primary key: `lid` + `museum` + +Deleting a locality cascades its `now_mus` rows. Deleting or renaming a museum code needs care because the code is part of the link-table key. + +## API endpoints + +- `GET /museum/all`: list museums +- `GET /museum/:id`: read museum details and linked localities +- `PUT /museum`: create or update a museum; requires an edit role + +The detail endpoint supports tabular query options for the linked locality list. + +## Frontend usage + +- `/museum/:id?` routes to the museum detail page. +- Locality edit views use the museum lookup list when linking museums to a locality. +- The Museum tab in locality details edits `now_mus` rows through the locality edit payload rather than by editing the museum record directly. + +## Validation notes + +Museum codes are treated as stable identifiers. Backend tests cover creation, update, empty-code validation, and duplicate-code checks that differ only by case. diff --git a/documentation/entities/people.md b/documentation/entities/people.md new file mode 100644 index 00000000..dc671a49 --- /dev/null +++ b/documentation/entities/people.md @@ -0,0 +1,54 @@ +# People + +People represent contributors, coordinators, contacts, and optionally application users. A person can exist without a login account. + +## Database model + +The main person record is `com_people`: + +- `initials` (primary key) +- `first_name` +- `surname` +- `full_name` +- `format` +- `email` +- `user_id` +- `organization` +- `country` +- `password_set` +- `used_morph` +- `used_now` +- `used_gene` + +If `user_id` is set, it links the person to a `com_users` row: + +- `user_id` (primary key) +- `user_name` +- `password` +- `newpassword` +- `last_login` +- `now_user_group` +- `mor_user_group` +- `gen_user_group` + +Person initials are also used in coordinator, authorizer, contact, and membership relations, including project people, region coordinators, species coordinators, stratigraphy coordinators, and update-log coordinator/authorizer fields. + +## API endpoints + +- `GET /person/all`: list all people; admin-only +- `GET /person/:id`: read person details; admin users can read any person and non-admin users can read only their own person record +- `PUT /person`: update a person; admin users can update any person and non-admin users can update only their own person record + +Creating new people is not implemented through `PUT /person`; the route returns an error when `initials` is missing. + +## Frontend usage + +- `/person` shows the people table for admins. +- `/person/:id?` shows person details when the signed-in user is authorized. +- Person lookup data is reused by coordinator/contact selectors, such as project and region editing. + +## Permission notes + +The person routes intentionally do not use only the shared role middleware because self-service profile access is allowed. Route-level checks compare `req.user.initials` with the requested or edited person initials. + +Admin-only user-group edits are handled during person update when the payload includes a valid `user_id` and `now_user_group`.