Clinical input suggestions

Doctor exposes two authenticated GET queries. Prescription implements catalog behavior and storage; Admin owns catalog management HTTP. Shared models, commands, queries, errors and validation live in pkg/types/domain; pkg/types/ports contains AdminClinicalSuggestionService, DoctorClinicalService, and repository interfaces. Doctor receives one service with the two queries; Admin receives one service with all ten management operations. HTTP DTOs and their explicit mappers remain in Doctor/Admin presentation packages. This feature adds no contracts to Prescription's public package.

Doctor queries

GET /api/v1/doctors/suggestions/chief-complaints?search=fever&limit=10
GET /api/v1/doctors/suggestions/history?category=medical&search=diabetes&limit=10

Require an active persistent doctor session and account/profile. These global choices require no organization or patient context. search is optional (255 Unicode characters); blank search returns curated defaults. limit defaults to 20 and accepts 1–100. History requires one category. Unknown query parameters return 422.

Search applies Unicode NFC, case folding and whitespace normalization to titles and individual aliases, preserving Bengali marks. Bengali aliases and English synonyms match literally; % and _ are not wildcards. Rank exact title, exact alias, title prefix, alias prefix, then substring, with display priority/title/ID as deterministic ties. Default order uses display priority/title/ID. Inactive and deleted terms are excluded.

{
  "message": "Chief complaints fetched successfully",
  "status_code": 200,
  "data": [{
    "id": "<catalog UUID>",
    "title": "Fever",
    "aliases": ["জ্বর", "Pyrexia"],
    "associated": ["Chills & rigor", "Headache", "Convulsion"]
  }]
}

History items contain id, category, title, aliases, and attributes. An allergy entry can have "attributes":{"allergyKind":"Drug"}. The supported classifications are Drug, Food, Other, and Unspecified; they belong only to the allergy category. Other attributes are not accepted. Patient dates, findings, doses, reactions, severity and other patient-specific values are entered by the doctor.

Categories: medical, surgical, medication, allergy, family, social, present-illness, obstetric, pediatric, immunization, adverse-reaction, other. A medical query cannot return allergy entries.

Empty results return data: []; aliases and associations always serialize as arrays, and empty attributes as {}. Associations arrive inline. Doctor has no mutation or detail routes. These lists have no pagination envelope.

Admin CRUD

Use active platform-admin credentials at /api/v1/admin/suggestions/chief-complaints and /api/v1/admin/suggestions/history:

Method	Suffix	Grant	Result
GET	collection	admin.clinical_suggestion.read	200, management page
GET	/{id}	admin.clinical_suggestion.read	200, one record including deleted state
POST	collection	admin.clinical_suggestion.manage	201, created record
PATCH	/{id}	admin.clinical_suggestion.manage	200, edited record
DELETE	/{id}	admin.clinical_suggestion.manage	200, data: {}

Create accepts title (required, maximum 500 characters), aliases (up to 50 nonblank strings of maximum 255 characters), status (active default or inactive), and sort_order (0 default through 1,000,000). Chief complaints additionally accept associated (up to 30 strings). History requires category and accepts attributes. Lists/objects default to empty. Normalized duplicate list entries and unknown fields are rejected.

PATCH updates supplied fields only. Arrays and attributes replace their entire value; []/{} clear them. Explicit null and empty patches return 422. Zero priority remains a valid update. A category change must clear incompatible attributes in the same patch. Changes preserve IDs and become visible to subsequent Doctor queries. Concurrent edits merge against the latest locked record. Actual writes and audit entries commit or roll back together; no-op patches and repeat deletes do not create extra audit entries.

Admin responses add status, sort_order, created_at, updated_at, and nullable deleted_at. IDs are server-created UUIDs and timestamps use RFC 3339 UTC. Soft deletion retains the record without modifying existing prescription content. Deleted terms cannot be edited; a replacement may use the same title with a new ID. No restore endpoint is provided.

Management lists accept search, limit, cursor, optional status, and deletion=live|deleted|all (default live). History's management category filter is optional. Order is creation time/ID descending. The top-level pagination.next_cursor is empty at the last page. Cursors bind resource and normalized filters; a mismatch returns 422.

Missing/invalid credentials return 401; inactive/non-doctor/non-admin accounts or denied grants return 403; missing Admin IDs return 404; duplicate live title or deleted-edit conflicts return 409; invalid input returns 422; unavailable capabilities return 503. Errors use the existing Huma problem format.

Migrations, seeds and replacement

go run ./tools/cli database migrate --service prescription
go run ./tools/cli database migrate --service authorization
go run ./tools/cli database seed --items clinical-suggestions

Grant read/manage permissions using existing Admin role tools, or rerun development Admin seeds to refresh their fixture grants. The new catalog contains 301 chief complaints and 800 history suggestions, with all 12 categories represented. seed --all and the interactive seed selector include this dataset. Runtime seeding is offline and transactional.

Seed keys and IDs stay stable. Reruns preserve administrator edits, reclassification, status, and deletion. A matching live Admin-created term is reused with its original ID/content and receives only a private seed reservation. Conflicting reservations fail the entire seed. Updates to existing terms should use Admin rather than expecting seeds to overwrite them.

The former /api/v1/prescriptions/suggestions/history list/detail/CRUD routes are removed. Their rx_history_suggestions rows remain private for recovery; no category is inferred and they are not returned by the new API. The old suggestion CSV/command now loads diagnosis, advice, and investigation only. Prescription-derived patient history is a separate workflow.

Operation DTOs and service/repository port signatures describe every request, response and internal boundary. The checked-in OpenAPI is generated from the implemented Huma DTOs.