Catalogue & Contracts Back-office PRD

日常业务与测试阅读请使用Catalogue 中文业务 PRD。本页保留工程细节、历史变更与取数参考；已知冲突见实现记录。

Canonical product contract · Confirmed through 2026-09-03 · Owner: Operations / Finance / Insurance / Platform

1. Outcome

Catalogue & Contracts is the governed maintenance centre for commercial master data consumed by Consultation, Billing, Packages, Benefits and Inventory. It replaces the placeholder admin-master-data surface while retaining that App ID.

The current iteration changes the frontend structure and may adapt existing APIs, but must not introduce or migrate underlying catalogue pricing tables. Every missing persistence model is recorded in the Backend Adaptation Ledger in section 12 and must not be presented as completed.

2. Confirmed navigation

1. Service Items
2. Lab & Imaging
3. Products
4. Consultation Pricing
5. Service Packages
6. Coupons
7. Insurance Cards
8. Other Settings
9. Change History & Controls

Fees & Offerings is hidden from current-phase navigation. Its code and data remain available for compatibility and migration analysis; it is not repurposed as a Discount page and is not deleted.

There is no Overview or explanatory bridge page. Insurance & Benefit Programmes opens card management directly.

3. Scope and ownership

4. Shared catalogue rules

4.1 Canonical identity

Service, Lab, Imaging and Product share clinic_service_items.id. item_kind controls the domain view:

• service — professional service or procedure;
• lab — laboratory Test Item;
• imaging — imaging Test Item;
• product — non-drug physical product.

Drug Master remains separate because dosage, route, interaction, controlled-drug and dispensing rules are materially different.

4.2 Lifecycle and historical integrity

• New records are Draft.
• Publish and deactivate require a reason and separate permission.
• A used record is deactivated, not hard-deleted.
• Signed Consultation, sold Package, Benefit quote, order and Invoice retain the item, applied price and resolver snapshot captured at the time.
• This phase does not require second-person approval.

4.3 List Price and Cost

List Price and Cost are separate concepts and separate columns:

• List Price is the patient-facing reference selling price.
• Cost is the internal cost basis.

For Service and Product, both values are unified across clinics. Clinic selection controls availability only and cannot override either price.

For Lab & Imaging, List Price is unified per Test Item. Cost varies by Vendor, Clinic and Doctor according to section 6; Clinic never changes List Price.

5. Service Items

5.1 List

Columns:

Service Code, Service Name, Category, List Price, Cost, Available Clinics, Status, Actions.

Filters:

• search by Service Code or Service Name;
• Category;
• Available Clinic;
• Status.

5.2 Editor

Fields include Service Code, Service Name, Category, List Price, Cost, Available Clinics, Description and lifecycle metadata.

Available Clinics is a searchable multi-select dropdown with checkbox rows, All Clinics, select-all and clear behavior. A new Service defaults to All Clinics. An explicit empty selection means unavailable everywhere; it must never be silently interpreted as All Clinics.

6. Lab & Imaging — Test Catalogue

6.1 Page structure

The area is one Test Catalogue page. The previous four-tab proposal is superseded. Request Form Mapping is removed from this workspace.

The main table has one row per canonical Test Item:

Unique Code, Test Item Name, Category, Type, List Price, Vendors, Cost Coverage, Status, Actions.

Filters cover search, Category, Lab/Imaging type, Vendor and Status.

Lab & Imaging Test Items are available to all clinics by definition, so this area has no Available Clinics field or filter.

6.2 Test Item detail Drawer

Clicking a row opens a wide right-side Drawer. It is a detail surface, not a second table permanently squeezed beside the catalogue.

The Drawer contains:

1. Basic Test Item information and unified List Price.
2. Vendor & Code Mapping: Vendor, Vendor Item Name, Vendor Code, Vendor Default Cost, lifecycle/effective information.
3. Clinic / Doctor Cost Schedule: Vendor, Clinic, optional Doctor, Cost, effective information and Status.

One Test Item may be offered by multiple Vendors. Vendor Code and Vendor Cost belong to a specific Vendor mapping, not to the canonical Test Item row.

6.3 Diagnostic cost key and resolution

The Cost key is:

Test Item + Vendor + Clinic + Doctor(optional).

Resolution order:

1. Doctor + Clinic + Vendor;
2. Clinic + Vendor;
3. Vendor Default Cost;
4. Cost unavailable.

Different Clinics cannot define a different List Price. Different Clinics and Doctors may define a Cost override only.

7. Products

Columns:

SKU / Code, Product Name, Category, List Price, Cost, Available Clinics, Inventory Tracking, Status, Actions.

Filters cover search, Category, Available Clinic, Inventory Tracking and Status.

The editor supports SKU, barcode, unit of measure and Inventory Tracking in addition to the shared fields. Availability uses the same searchable checkbox multi-select as Service Items. Quantity, lots, purchasing and stock movement remain in Inventory.

8. Consultation Pricing

8.1 Main list

The label is Consultation Pricing, not Doctor Consultation Fees.

Columns:

Doctor, Standard Price, Clinic Exceptions, Insurance Rates, Status, Actions.

Every doctor has one Standard Consultation Price. It is the doctor's base consultation price across consultation types and clinics.

8.2 Exceptions

• A Doctor may have a Clinic-specific exception for the same consultation price.
• An Insurance rate is keyed by Doctor + Insurance Card/Policy and applies to all clinics by default.
• A Doctor + Insurance rate may optionally have a Clinic-specific exception.

Resolution order:

1. Doctor + Policy + Clinic;
2. Doctor + Policy;
3. Doctor + Clinic;
4. Doctor Standard Price;
5. Default consultation price: HKD 1,000.00 (confirmed 2026-09-08).

The current backend has no authoritative model or Billing resolver for this contract. All edit/import actions in this section remain explicitly marked pending until section 12 is implemented.

The executable interim fallback is in ordinary Consultation Billing & Finish: an unbound Visit receives the server-owned HKD 1,000.00 default, while an explicit valid Service Offering remains authoritative, including a zero price. An explicitly bound invalid/expired/cross-clinic/non-HKD Offering still requires correction; other charge lines never inherit this default. The applied default code/version is retained in existing signed snapshots, and signed history is not repriced. This does not implement the pending doctor-standard and Policy/Clinic exception tables or their editing/import UI.

9. Coupons

Coupon Campaign supports code/name, discount type/value, minimum spend, optional maximum discount, dates, redemption limits, target, description and stacking.

Coupon does not stack with a Contract or Benefit discount unless stackable = true is explicitly configured.

Campaign maintenance and import do not imply Cashier redemption is integrated. Cashier must eventually store the applied campaign/version and reversal history.

10. Insurance Cards and Policies

10.1 Insurance Card master

Card master inherits the existing policy_card mapping:

• Insurance Company → provider_name;
• Card Name → name;
• Plan Name → plan_name;
• Card Class → clazz;
• Status → status;
• linked Policy → contract_id;
• programme type → metadata.programme_type (insurance, corporate_membership, or staff_benefit);
• linked enterprise cooperation plan → metadata.benefit_contract_uuid referencing benefit_contracts.contract_uuid;
• front/back card face → image1 / image2.

The source contract is mutually exclusive by programme type:

• insurance may link the existing policy_contract through policy_card.contract_id;
• corporate_membership must link a Benefit Contract whose contract_type = corporate_membership;
• staff_benefit must link a Benefit Contract whose contract_type = staff_benefit.

Corporate membership and Staff benefit are the only enterprise cooperation types available here. Promotion and Insurance-type Benefit Contracts are not selectable for this purpose. The card master stores only the source identity in metadata; contract rules, plans, eligibility, limits and utilization remain authoritative in Benefit Contracts and are not copied into policy_card. Existing cards without metadata.programme_type are interpreted as insurance for backward compatibility.

The page renders a card-face gallery even when the list is empty, with a real New Card action. It never inserts demo cards.

Front/back JPEG, PNG or WebP files up to 5 MB can be uploaded, previewed, replaced or removed. Bytes are stored in the existing private file registry and the resulting private file URL is written to policy_card.image1/image2.

Insurance Card does not provide bulk Excel import. A usable card requires reviewed card-face files and an intentional Policy link, so Card creation and maintenance remains one record at a time. Policy master data may still be imported in bulk.

10.2 Policy management

Manage Policies opens a wide Drawer on the Insurance Cards page. The current phase supports simple Policy number/name, effective/expiry dates, holder type, contract type, insurance type and Billing visibility on the existing policy_contract table.

The card detail displays one source preview: linked Policy for an Insurance card, or linked Benefit Contract code/name, sponsor, type, effective period and status for Corporate membership / Staff benefit. Complex benefit rules, caps, beneficiaries, rotating QR, utilization and advanced pricing remain hidden.

11. Bulk Excel import — shared product contract

Every bulk-import-eligible area that creates master data must provide the following contract. Insurance Card is the confirmed exception in this phase because each card requires image and Policy-link review:

The list page exposes one compact secondary Bulk import launcher only. It is placed in the page-title header at the upper right, immediately before the page's primary New … action; the stable action order is Refresh → Bulk import → New …. A Policy-management Drawer applies the same rule to its Drawer header. Template download and file selection must not remain as large permanent page actions, separate body rows or controls inside a search/filter toolbar. The launcher opens the platform-standard right-side Bulk Import Drawer containing the complete import flow, so search, filters and record tables keep visual priority. This is a shared administrator-maintenance pattern, not a rule imposed on clinical or task-oriented pages: every approved executable admin import must reuse the shared Drawer component, while pending persistence models may only show a clearly non-executable requirement preview in the same pattern. Insurance Card itself has no launcher; the separate Policy manager may use the shared Drawer.

1. Download Excel Template specific to that module;
2. upload .xlsx or .csv;
3. full-file validation before write;
4. preview with Pass / Warning / Error counts and sample rows;
5. explicit duplicate policy (UPDATE or SKIP where permitted);
6. user confirmation before execution;
7. batch execution with partial-success reporting;
8. row-level validation messages and downloadable error detail;
9. refresh of the list after success;
10. import job audit with actor, permission, time, source filename, result counts and status.

Imports create Draft records unless the target model has an explicitly approved alternative. Import does not bypass publish permission or lifecycle rules.

Template download requires read permission. Preview and execute require the corresponding non-assumed manage permission. A disabled or missing persistence model must display Backend adaptation pending; it must not simulate a successful import.

12. Backend Adaptation Ledger

This ledger is part of the approved product contract. Current describes verified reuse; Required / Recommended is future work and is not authorized for schema implementation in this frontend iteration.

12.1 Required rollout order

1. Approve table design and constraints separately.
2. Create migrations and import callbacks.
3. Backfill legacy Offerings into new availability/vendor/cost models with reconciliation reports.
4. Implement resolvers with unit and precedence tests.
5. Run dual-read comparison without changing charges.
6. Cut over write/read consumers by feature flag.
7. Verify Billing snapshots, import audit and rollback path.
8. Only then remove Backend adaptation pending labels or deprecate legacy Offering paths.

13. Permissions and audit

Assumed/restricted support roles cannot mutate, publish or execute imports. Role, permission, test-account and membership bootstrap data must not be deleted while simplifying this workspace.

14. Acceptance criteria

1. The nine confirmed navigation entries and ordering match section 2; Fees & Offerings and complex Benefit Contracts are hidden but retained.
2. Service and Product show separate List Price and Cost, confirmed filters and searchable checkbox Clinic multi-select.
3. No Clinic can change a Service/Product List Price or Cost.
4. Lab & Imaging renders one Test Catalogue and one detail Drawer; Request Form Mapping is absent.
5. Test Items have unified List Price and all-clinic availability; Vendor/Clinic/Doctor variation applies only to Cost.
6. Consultation Pricing shows every Doctor with Standard Price, Clinic exception and Insurance rate structure, while pending persistence is explicit.
7. Insurance Cards opens direct card management, supports private front/back upload, exposes Insurance policy / Corporate membership / Staff benefit types, and shows the matching Policy or typed Benefit Contract source preview.
8. Policies are created/edited/imported from an in-page Drawer using existing policy_contract; there is no new top-level Policy page.
9. Service, Test Item, Product, Coupon and Policy each provide one compact Bulk import launcher in the page/Drawer header right, immediately before the primary New action, and open a right-side Drawer with module-specific template download and preview/validate/confirm import. No duplicate launcher remains in the page body or filter toolbar. Insurance Card is the confirmed exception and is maintained one card at a time.
10. Pending models show pending import status rather than fake data or fake success.
11. Publish/deactivate reason, permissions, import audit and historical snapshots follow this PRD.
12. PRD publication, application deployment, end-to-end integration and UAT are reported separately.
13. Corporate membership and Staff benefit cards cannot save without a matching Benefit Contract; changing type clears the incompatible Policy / Benefit Contract reference instead of keeping two active sources.

15. Delivery status at this revision

• Implemented / adapted without new tables: Service/Product/Test Item lists; confirmed filters; clinic multi-select UI; one Test Catalogue Drawer; hidden Fees & Offerings; Consultation Pricing review UI; direct single-card Insurance Card management with mutually exclusive Policy or typed Benefit Contract source; card image upload; simple Policy Drawer/CRUD; compact Bulk import launchers and the shared right-side template/preview/confirm Drawer for Service, Test Item, Product, Coupon and Policy; permission-protected import routes.
• Existing and reused: canonical catalogue items, Coupons, policy_card, policy_contract, Package Setup, Patient Insurance Cards, Drug Catalogue, Users, Units, Templates, Workflow settings and shared Excel engine.
• Explicitly pending backend: clinic availability mapping, Diagnostic Vendor mapping, Diagnostic Cost schedules/resolver, Consultation pricing tables/resolver, Package import and downstream Billing integration.
• Retained but hidden: Fees & Offerings UI/code/data and complex Benefit Contracts administration; existing Corporate membership / Staff benefit contracts remain readable as governed card sources.
• Not claimed: database redesign, production deployment, end-to-end pricing cutover or UAT acceptance.

Insurance & Benefit Programmes

名称、卡片详情、双语说明、HTML净化与来源边界统一见 Catalogue 业务 PRD。本文件仅补充底表与迁移设计，不重复维护后续界面变更或发布流水。