S41 — Regulated stock register (pp_rsr): each market's books as data

A shop selling regulated stock keeps a legal register an inspector can ask for at any time: a pharmacy's poisons and controlled-drug books, a liquor or tobacco register, a duty-free ledger. Today most keep it on paper. This app keeps it for them: one app for any regulated stock, whose books (which book, which items, which movements, which columns, which printed layout) are a data set per market and vertical. A second market, or a second vertical, is a new data set file with no code change.

The first data set is Kenya's three pharmacy books: the Poisons Book (Rules Schedule VIII Form 16), the Prescription Book (Act s. 31(1)(b)) and the NPP Ledger Book (PPB NPP Guidelines Annex II), with the routing Kenya's law asks for: a supply on prescription goes to the Prescription Book, not the Poisons Book (s. 31(2)); every movement of a controlled drug goes to the NPP ledger as well. Seven more markets follow as data sets, with no code change: Jordan, Nigeria, the UAE's Abu Dhabi, Saudi Arabia, Egypt, Ghana and Mexico (the other markets).

⚠ Every layout here is a starting point, not certified for the country. It is read from the instruments named in the data set, and each print says so. A partner certifies it for a market, changes it, or adds a market.

Door: Manifest

When to use it: the shop's law names a book and its columns, and the book must hold every sale or receipt of certain stock, in order, never edited.

The register door: what is here now, and what waits for it

The book itself is a legal record: one line written in the same save as the sale or the receipt, numbered without a gap, with a running balance two tills cannot break, and never edited. An app installed from a manifest cannot write such a record, so the POS app carries a register door for it, and this app declares its books to that door. ⚠ The door is not in the POS app yet. Its specification is written and requested on the POS team's board.

Until the door is there, the shop's books are kept as before. Setting this app up now puts the columns on the documents, so the door's first line has them.

A data set

datasets/ke_pharmacy.json is the whole of Kenya. A data set says:

A column prints one or more of the line's columns (movement_date, item_name, qty, counterparty, authority_no, balance …, the door's line) or a declared detail (detail:occupation), joined with ·. when: "In" or "Out" prints it only on receipts or only on issues (the NPP ledger's two halves); mark: 1 leaves room for a signature on the printed page; in_colour prints received quantities in a colour (Kenya: red ink, s. 8.1(i)).

build.py's check() is the format: it refuses in (a list of classes is the book's classes), a fourth condition, a comparison of a column against a date value (a date is not a number to the condition form; ⚠ it does not yet refuse a date column compared with a number, which never holds: don't write one), a column the line does not have, markup or template text in any label, and the rest, each in words. routing.py models which books a line enters, so you can test a data set before the door is installed.

Kenya's three books

So a prescription supply of pethidine (a Part I poison on one axis, a controlled drug on the other) enters the Prescription Book and the NPP ledger; a counter sale of a Part I poison enters the Poisons Book only; a transfer, an issue or a loss of a poison enters no sales book.

⚠ The two poisons books are kept as printed books. Electronic records are cited for NPP records only (Guidelines s. 8.1): print the day's pages, sign them, and keep them as the book; each print of those two books ends with a line for that signature. ⚠ Form 16 also asks for the purchaser's signature, given at the sale: until this app's next version prints a slip for it, have the purchaser sign the paper book or a slip at the counter (FR-K3-11).

⚠ The classes are the shop's. KE Part I Poison and KE NPP, and the axes KE Poisons and KE Controlled, are working names of the counter-rules app's drug schedules, read from its dated Item Schedule rows on Item (pp_rxc_schedules: schedule, effective_from), or from the Item Group's pp_rxc_schedule where an item has no row; the axis is the schedule's own axis. Rename them in the data set to the shop's own. The door refuses, at setup, a declaration naming a field or table that does not exist. ⚠ Whether every controlled drug is also a Part I poison is not cited (Kenya's narcotics Act, Cap. 245, was not read): the shop gives each drug its schedule on each axis.

⚠ One prescription per sale. The till's sale details belong to the whole sale, so a basket holding a poison on prescription and another sold without one would put both in the Prescription Book. The counter-rules app refuses such a line (its schedule's tick Sold in a sale of its own when not on the prescription): tick it on the Part I poison schedule, and the cashier sells the other as a sale of its own.

The other markets

Each is one file in datasets/. Jordan's and Nigeria's columns are their printed forms, read off the form images; the others are the data their law lists, in its order, because no form is printed. Labels are the instrument's own words, Arabic or Spanish where the instrument is; where a label adds a word (a group, a letter, Abu Dhabi's brand and generic name from s. 7.7, Mexico's entry columns), the data set's notice says so.

⚠ What a data set cannot print yet, so the shop writes it in or waits: the patient's age, ID number and medical file (Saudi Arabia, Egypt) and the prescriptions-book entry number (Egypt) print as empty columns, because the register cannot yet read a value from the customer's record (the counter-rules app keeps the ID and the date of birth there). Mexico's prescription issue date and Jordan's special-prescription date print empty: the counter-rules app does not record a prescription's date on the sale. Nigeria's ingredients of the prescription is a Desk field: a counter sale prints it empty. Abu Dhabi's patient identifier (s. 7.2.1) is not printed. Jordan's Form 7, the daily prescriptions register, is a print of the counter-rules app's dispensing records, not a book here.

⚠ A return, and a loss, print as the register door prints them today. A return follows its original's books, so a customer's return prints in a sales book (Kenya's two poisons books, Nigeria's Part B, Ghana's record) and a return to the supplier in Nigeria's Part A, each as a movement of its own; and a loss, disposal or issue prints in a dispensing half with its prescription and patient cells empty, saying nothing of what it was. Both are requested of the door (PB-4); until then, mark such an entry by hand.

⚠ Returns to the regulator are not set up: Abu Dhabi's monthly and quarterly reports, Saudi Arabia's six-monthly statement and yearly close, and Egypt's six-monthly statement. A book's period gives its reminder a name the shop's install refuses, so no data set declares one yet.

⚠ Every market's books install in every shop. The app builds one declaration from every data set, so a shop installing its next version gets every market's books (27 today), each switched on. Until a shop can choose its data set, a partner keeps only its market's file in datasets/ and builds again.

⚠ Books the law names but these sets leave out: Saudi Arabia's prescriptions register (Art. 21(2)) and Egypt's prescriptions book (Arts. 17, 18(ج)), whose fields the law does not list; Abu Dhabi's PH 18 (wards) and its unified prescribing platform (s. 3.9); Ghana's book for a Class B supplier, for which the Act sets no entry; Mexico's raw materials (Art. 159 IV) and a droguería's magistral book (Art. 124 VI).

⚠ Dubai is not in the UAE set: its register book (DHA) is named in its guidelines, but its columns were not read. Cameroon and Rwanda are not researched.

What the shop does (now)

1. Install the app (the shop's administrator). It adds the Register details section to the Sales Invoice and the Delivery Note, the till's sale details, the role PP RSR Register Approver, the report and the workspace.
2. Give the role to the person responsible for the register (a pharmacist in charge, a licensee).
3. Tell the dispensary's cashiers to fill the sale's details for a regulated sale (the till's sale details: occupation, purpose …). They are never required, so no other till is stopped; the counter-rules app's check before payment is what refuses an incomplete controlled sale.
4. Print the day's register pages at each day's close and keep them at the store, for an outage (from the door's version on; until then, the paper book).

The files

Run it

python3 samples/s41_regulated_register/build.py
python3 tools/check/check.py samples/s41_regulated_register
python3 -m unittest discover -s samples/s41_regulated_register/tests -p 'test_*.py'   # the rendering tests need jinja2

Limits

• No book is written or printed until the door is in the POS app. The book prints name the door's period record type, which the shop's install refuses until it exists.
• A print reads at most 10,000 lines (50 reads of 200) and, in a book printed a page per drug, 2,000 drugs. Print a shorter range for more.
• A correction struck through on this print is matched within the printed range: a correction of an entry printed in an earlier range shows as a correction line only.
• The print is printed by a signed-in person: the print readers answer nothing in a background print or an e-mail, and the print then says so rather than showing an empty book.
• On the ERP's stock-entry path no supplier is carried, so the NPP ledger's Received from prints empty there; Invoice no. is the ERP's own log number.
• The ledger's header shows the drug by its item name: put the strength in the name, as Annex II asks for it.
• The workspace's links show only to someone who may read those record types: a System Manager alone sees none (on our bench, the links appeared once the user had the stock and accounts roles a register keeper has).
• Dates print as the record holds them (2026-10-20). The print's own words are in English: its number column (No.), its notes and its footer. A data set's column labels are in its market's language.
• A book prints left to right, one header row: a right-to-left form (Jordan, Saudi Arabia, Egypt) prints its columns in the form's order, left to right, and a form's grouped header (Jordan's in and out) is carried in each column's label.
• A book printed into the authority's own book (Jordan, Abu Dhabi, Egypt, Mexico) does not follow that book's page and line numbers yet: print it on paper and copy, or keep the register in an approved system where the law allows one.
• A page per drug is headed by the item's name alone: put the strength and the dosage form in the name (Jordan's and Saudi Arabia's page headers ask for both). Nigeria's Form in which obtained prints the item's stock unit: name the unit by its form.

Make it your own

• Another market, or another trade: copy datasets/ke_pharmacy.json, read the market's instrument, and write its books. Run build.py and the tests. Nothing else changes.
• Another prefix: set PREFIX, FPREFIX and ROLE at the top of build.py and build again (or copy the built manifest with tools/manifest/rename.py).
• Certify a layout: set certified: 1 once you have checked it against the market's instrument, and change its notice.

The register door this app declares to is requested of the POS app as PB-4, the regulated-stock register door; its version will be named here when it ships.

This page in the kit