Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/database/catalog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Food catalog

The catalog is the list of foods Moisson Montréal can receive. Each row is one kind of food. A donation of that food points at the row, and the price grid stores the price of one unit over time. Accounting matches the row through its Business Central code.

food_items is one donation: the donor, the quantity and the date. catalog_items is the food itself.

## Diagram

![Food catalog diagram](images/catalog.png)

The columns in this picture are the catalog item. The quality class column is a link to the quality_classes table: it stores the class code, such as A, B or C. The full database diagram in [schema.md](schema.md) shows that link together with the price grid.

## Tables

### catalog_items

One row per kind of food. The table was created for the price grid, and these columns complete it.

- **id**: code that identifies the catalog item, assigned automatically
- **name**: name of the food, for example Pain
- **category**: group the food belongs to, for example Boulangerie
- **business_central_code**: code of this food in Business Central. Two catalog items cannot share a code
- **unit**: unit used to count the food, such as kg or caisse. Free text for now, until issue #28 decides how the price of one unit works
- **quality_class**: quality class of this food. It must be a class that exists, such as A, B or C. The class is stored on the catalog item
- **created_at**: date and time the item was added, stored in UTC
- **updated_at**: date and time of the last change, stored in UTC. Empty until the item is edited

## Quality class

The quality class belongs to the catalog item, so every donation of that food can use the same class. The classes and their percentages live in the quality_classes table. A catalog item can only use a class that is already there.

A donation still keeps the quality class it was given, on food_items. That value is what a receipt uses.

## Business Central code

The code is how the catalog item is matched with the accounting system. The database rejects a second item with the same code. The comparison is exact, so `BC-PAIN` and `bc-pain` are two different codes.

## Rules enforced by the database

1. A name, a category, a Business Central code and a unit cannot be empty.
2. A Business Central code can belong to only one catalog item.
3. The quality class must be a quality class that exists.
4. A quality class cannot be deleted while a catalog item uses it.

## API

List, create and edit are available at `api/catalog-items`. Any signed-in employee can list the catalog. Creating or editing an item requires the ManagePriceGrid permission, so only an Admin can do it. Creating or editing an item with a Business Central code that is already used returns a conflict. A quality class that does not exist is refused.

## Migration

- Entity Framework migration: [20261117040905_AddCatalogItemDetails](../../src/MoissonMontreal.Api/Data/Migrations/20261117040905_AddCatalogItemDetails.cs)
- Equivalent SQL script: [0006_add_catalog_item_details.sql](sql/0006_add_catalog_item_details.sql)
- Table settings: [CatalogItemConfiguration.cs](../../src/MoissonMontreal.Api/Data/Configurations/CatalogItemConfiguration.cs)
- API: [CatalogItemsController.cs](../../src/MoissonMontreal.Api/Controllers/CatalogItemsController.cs)

Catalog items that existed before this migration get placeholder values, so the new rules can be added: category `To classify`, Business Central code `TO-FIX-` followed by the item id, unit `unit` and quality class A. Fix these items by hand after the migration.

The SQL script must be run after [0005_create_quality_classes.sql](sql/0005_create_quality_classes.sql). It records itself in the migration history, so Entity Framework will not apply it a second time.
Binary file added docs/database/images/catalog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 13 additions & 1 deletion docs/database/prices.dbml
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,27 @@
Table catalog_items {
id uuid [not null, default: `gen_random_uuid()`]
name varchar(255) [not null]
category varchar(100) [not null]
business_central_code varchar(50) [not null, note: 'Unique code used to match the item in Business Central']
unit varchar(20) [not null, note: 'Free text until the price of one unit is decided']
quality_class varchar(1) [not null, note: 'Code of the quality class. The class lives on the catalog item']
created_at timestamptz [not null, default: `now()`, note: 'Stored in UTC']
updated_at timestamptz [null, note: 'Stored in UTC, empty if never changed']

indexes {
id [pk, name: 'pk_catalog_items']
business_central_code [unique, name: 'ix_catalog_items_business_central_code']
quality_class [name: 'ix_catalog_items_quality_class']
}

checks {
`length(name) > 0` [name: 'ck_catalog_items_name_not_empty']
`length(category) > 0` [name: 'ck_catalog_items_category_not_empty']
`length(business_central_code) > 0` [name: 'ck_catalog_items_business_central_code_not_empty']
`length(unit) > 0` [name: 'ck_catalog_items_unit_not_empty']
}

Note: 'Types of food recognized by the app. Category, Business Central code, unit and quality come with #27'
Note: 'Types of food recognized by the app, with the Business Central code and the quality class'
}

Table prices {
Expand Down Expand Up @@ -115,4 +125,6 @@ Ref fk_food_items_catalog_items_catalog_item_id: food_items.catalog_item_id > ca

Ref fk_food_items_quality_classes_quality: food_items.quality > quality_classes.code [delete: restrict]

Ref fk_catalog_items_quality_classes_quality_class: catalog_items.quality_class > quality_classes.code [delete: restrict]

Ref fk_prices_catalog_items_catalog_item_id: prices.catalog_item_id > catalog_items.id [delete: restrict]
17 changes: 10 additions & 7 deletions docs/database/prices.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,16 @@ The donors and food_items tables come from an earlier step. They are shown in th

One row per type of food, such as bread or apples. A donation of bread and the next donation of bread are two different rows in food_items, but they share one catalog item, and so one price history.

| Column | Meaning |
| --- | --- |
| id | Code that identifies the catalog item, assigned automatically |
| name | Name of the food. It cannot be empty. |
| created_at | Date and time the item was added, stored in UTC |
- **id**: code that identifies the catalog item, assigned automatically
- **name**: name of the food. It cannot be empty.
- **category**: group the food belongs to, for example Boulangerie
- **business_central_code**: code of this food in Business Central. Two catalog items cannot share a code
- **unit**: unit used to count the food, such as kg or caisse
- **quality_class**: quality class of this food. It must be a class that exists
- **created_at**: date and time the item was added, stored in UTC
- **updated_at**: date and time of the last change, stored in UTC. Empty until the item is edited

This is the smallest catalog the price grid needs. Issue #27 adds the category, the Business Central code (which will be unique), the unit and the quality to this same table. Until then, two catalog items can have the same name.
The category, the Business Central code, the unit and the quality class are described in [Food catalog](catalog.md).

### prices

Expand Down Expand Up @@ -80,7 +83,7 @@ Adding a new price to the grid therefore never changes a receipt that already ex

## Units and precision

- A price is for one unit of the catalog item, for example 1 kg or 1 case. The unit itself is added to catalog_items in issue #27, following the decision of issue #28.
- A price is for one unit of the catalog item, for example 1 kg or 1 case. The unit is stored on the catalog item as free text until issue #28 decides how the price of one unit is defined.
- unit_price keeps 4 decimal places, the same as receipt_items.unit_price, so a price can be copied onto a receipt without losing anything.
- A price with more than 4 decimals is rounded half away from zero by the database. For example, $0.12345 is stored as $0.1235.
- The largest price allowed is $99,999,999.9999. A larger value is refused.
Expand Down
14 changes: 13 additions & 1 deletion docs/database/quality-classes.dbml
Original file line number Diff line number Diff line change
Expand Up @@ -77,17 +77,27 @@ Table food_items {
Table catalog_items {
id uuid [not null, default: `gen_random_uuid()`]
name varchar(255) [not null]
category varchar(100) [not null]
business_central_code varchar(50) [not null, note: 'Unique code used to match the item in Business Central']
unit varchar(20) [not null, note: 'Free text until the price of one unit is decided']
quality_class varchar(1) [not null, note: 'Code of the quality class. The class lives on the catalog item']
created_at timestamptz [not null, default: `now()`, note: 'Stored in UTC']
updated_at timestamptz [null, note: 'Stored in UTC, empty if never changed']

indexes {
id [pk, name: 'pk_catalog_items']
business_central_code [unique, name: 'ix_catalog_items_business_central_code']
quality_class [name: 'ix_catalog_items_quality_class']
}

checks {
`length(name) > 0` [name: 'ck_catalog_items_name_not_empty']
`length(category) > 0` [name: 'ck_catalog_items_category_not_empty']
`length(business_central_code) > 0` [name: 'ck_catalog_items_business_central_code_not_empty']
`length(unit) > 0` [name: 'ck_catalog_items_unit_not_empty']
}

Note: 'Types of food recognized by the app. Category, Business Central code, unit and quality come with #27'
Note: 'Types of food recognized by the app, with the Business Central code and the quality class'
}

Ref fk_food_items_donors_donor_id: food_items.donor_id > donors.id [delete: restrict]
Expand All @@ -96,6 +106,8 @@ Ref fk_food_items_catalog_items_catalog_item_id: food_items.catalog_item_id > ca

Ref fk_food_items_quality_classes_quality: food_items.quality > quality_classes.code [delete: restrict]

Ref fk_catalog_items_quality_classes_quality_class: catalog_items.quality_class > quality_classes.code [delete: restrict]

Records quality_classes(code, name, percentage, min_percentage, max_percentage) {
'A', 'Grocery quality', 100.00, 100.00, 100.00
'B', 'Imperfect', 50.00, 50.00, 75.00
Expand Down
14 changes: 13 additions & 1 deletion docs/database/receipts.dbml
Original file line number Diff line number Diff line change
Expand Up @@ -77,17 +77,27 @@ Table quality_classes {
Table catalog_items {
id uuid [not null, default: `gen_random_uuid()`]
name varchar(255) [not null]
category varchar(100) [not null]
business_central_code varchar(50) [not null, note: 'Unique code used to match the item in Business Central']
unit varchar(20) [not null, note: 'Free text until the price of one unit is decided']
quality_class varchar(1) [not null, note: 'Code of the quality class. The class lives on the catalog item']
created_at timestamptz [not null, default: `now()`, note: 'Stored in UTC']
updated_at timestamptz [null, note: 'Stored in UTC, empty if never changed']

indexes {
id [pk, name: 'pk_catalog_items']
business_central_code [unique, name: 'ix_catalog_items_business_central_code']
quality_class [name: 'ix_catalog_items_quality_class']
}

checks {
`length(name) > 0` [name: 'ck_catalog_items_name_not_empty']
`length(category) > 0` [name: 'ck_catalog_items_category_not_empty']
`length(business_central_code) > 0` [name: 'ck_catalog_items_business_central_code_not_empty']
`length(unit) > 0` [name: 'ck_catalog_items_unit_not_empty']
}

Note: 'Types of food recognized by the app. Category, Business Central code, unit and quality come with #27'
Note: 'Types of food recognized by the app, with the Business Central code and the quality class'
}

Table receipts {
Expand Down Expand Up @@ -142,6 +152,8 @@ Ref fk_food_items_catalog_items_catalog_item_id: food_items.catalog_item_id > ca

Ref fk_food_items_quality_classes_quality: food_items.quality > quality_classes.code [delete: restrict]

Ref fk_catalog_items_quality_classes_quality_class: catalog_items.quality_class > quality_classes.code [delete: restrict]

Ref fk_receipts_donors_donor_id: receipts.donor_id > donors.id [delete: restrict]

Ref fk_receipt_items_receipts_receipt_id_donor_id: receipt_items.(receipt_id, donor_id) > receipts.(id, donor_id) [delete: cascade]
Expand Down
17 changes: 15 additions & 2 deletions docs/database/schema.dbml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
// Full database schema of the Moisson Montreal receipt app
// Paste this file into https://dbdiagram.io to render the diagram.
// Matches the migrations 20261103000127_CreateUsersAndRoles, 20261105163138_CreateDonorsAndFoodItems,
// 20261107041912_CreateReceipts, 20261110175320_CreateCatalogItemsAndPrices and 20261112060008_CreateQualityClasses.
// 20261107041912_CreateReceipts, 20261110175320_CreateCatalogItemsAndPrices,
// 20261112060008_CreateQualityClasses and 20261117040905_AddCatalogItemDetails.

Project moisson_montreal {
database_type: 'PostgreSQL'
Expand Down Expand Up @@ -164,17 +165,27 @@ Table receipt_items {
Table catalog_items {
id uuid [not null, default: `gen_random_uuid()`]
name varchar(255) [not null]
category varchar(100) [not null]
business_central_code varchar(50) [not null, note: 'Unique code used to match the item in Business Central']
unit varchar(20) [not null, note: 'Free text until the price of one unit is decided']
quality_class varchar(1) [not null, note: 'Code of the quality class. The class lives on the catalog item']
created_at timestamptz [not null, default: `now()`, note: 'Stored in UTC']
updated_at timestamptz [null, note: 'Stored in UTC, empty if never changed']

indexes {
id [pk, name: 'pk_catalog_items']
business_central_code [unique, name: 'ix_catalog_items_business_central_code']
quality_class [name: 'ix_catalog_items_quality_class']
}

checks {
`length(name) > 0` [name: 'ck_catalog_items_name_not_empty']
`length(category) > 0` [name: 'ck_catalog_items_category_not_empty']
`length(business_central_code) > 0` [name: 'ck_catalog_items_business_central_code_not_empty']
`length(unit) > 0` [name: 'ck_catalog_items_unit_not_empty']
}

Note: 'Types of food recognized by the app. Category, Business Central code, unit and quality come with #27'
Note: 'Types of food recognized by the app, with the Business Central code and the quality class'
}

Table prices {
Expand Down Expand Up @@ -212,6 +223,8 @@ Ref fk_receipt_items_food_items_food_item_id_donor_id: receipt_items.(food_item_

Ref fk_prices_catalog_items_catalog_item_id: prices.catalog_item_id > catalog_items.id [delete: restrict]

Ref fk_catalog_items_quality_classes_quality_class: catalog_items.quality_class > quality_classes.code [delete: restrict]

TableGroup accounts {
roles
users
Expand Down
13 changes: 7 additions & 6 deletions docs/database/schema.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,9 +73,9 @@ More detail: [Receipts and their prices](receipts.md).

### catalog_items

The types of food the app knows, such as bread or apples. A donation of bread and the next donation of bread are two different food items, but they share the same catalog item, and so the same price. For now a catalog item only has a name. Its category, Business Central code, unit and quality come with issue #27.
The types of food the app knows, such as bread or apples. A donation of bread and the next donation of bread are two different food items, but they share the same catalog item, and so the same price. Each catalog item has a name, a category, a unique Business Central code, a unit and a quality class.

More detail: [Price grid](prices.md).
More detail: [Food catalog](catalog.md) and [Price grid](prices.md).

### prices

Expand Down Expand Up @@ -119,7 +119,7 @@ The database itself refuses anything that would break these rules, even if there
- A food item cannot be deleted while it is on a receipt.
- A role cannot be deleted while someone has it.
- A catalog item cannot be deleted while it has prices or while a donation points to it.
- A quality class cannot be deleted while a food item uses it.
- A quality class cannot be deleted while a food item or a catalog item uses it.

**Exact amounts**
- All amounts are stored as exact decimal numbers, so no cent is lost along the way.
Expand All @@ -130,11 +130,12 @@ The database itself refuses anything that would break these rules, even if there
**Valid values**
- A quantity and a price must be greater than zero.
- A quality percentage must be between 0 and 100.
- A food item must have a quality class that exists.
- A food item and a catalog item must have a quality class that exists.
- A quality class keeps a default percentage within its own range, and the range stays between 0 % and 100 %.
- Two quality classes cannot have the same code or the same name, and a code is one capital letter from A to Z.
- A receipt total cannot be negative.
- Donor names, food names, catalog item names and units cannot be empty.
- Donor names, food names, catalog item names, categories, Business Central codes and units cannot be empty.
- Two catalog items cannot have the same Business Central code.

**Accounts**
- Two employees cannot have the same email or the same Microsoft account.
Expand All @@ -153,7 +154,6 @@ These parts of the project are planned in their own issues and will add tables l
| Feature | Issue |
| --- | --- |
| Price lookup by date | #25 |
| Food catalog details: category, Business Central code, unit and quality | #27 |
| Calculation of a donation's value | #30 |
| Receipt statuses: prepared, approved at two levels, issued, cancelled and replaced | #31 |
| Receipt numbering, unique and with no gaps | #32 |
Expand Down Expand Up @@ -181,6 +181,7 @@ Each table comes from one of these migrations:
| receipts, receipt_items | [20261107041912_CreateReceipts](../../src/MoissonMontreal.Api/Data/Migrations/20261107041912_CreateReceipts.cs) | [0003_create_receipts.sql](sql/0003_create_receipts.sql) | [receipts.md](receipts.md) |
| catalog_items, prices | [20261110175320_CreateCatalogItemsAndPrices](../../src/MoissonMontreal.Api/Data/Migrations/20261110175320_CreateCatalogItemsAndPrices.cs) | [0004_create_catalog_items_and_prices.sql](sql/0004_create_catalog_items_and_prices.sql) | [prices.md](prices.md) |
| quality_classes | [20261112060008_CreateQualityClasses](../../src/MoissonMontreal.Api/Data/Migrations/20261112060008_CreateQualityClasses.cs) | [0005_create_quality_classes.sql](sql/0005_create_quality_classes.sql) | [quality-classes.md](quality-classes.md) |
| catalog item details | [20261117040905_AddCatalogItemDetails](../../src/MoissonMontreal.Api/Data/Migrations/20261117040905_AddCatalogItemDetails.cs) | [0006_add_catalog_item_details.sql](sql/0006_add_catalog_item_details.sql) | [catalog.md](catalog.md) |

The SQL scripts must be run in order on an empty database.

Expand Down
41 changes: 41 additions & 0 deletions docs/database/sql/0006_add_catalog_item_details.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
START TRANSACTION;
ALTER TABLE catalog_items ADD category character varying(100) NOT NULL DEFAULT '';

ALTER TABLE catalog_items ADD business_central_code character varying(50) NOT NULL DEFAULT '';

ALTER TABLE catalog_items ADD unit character varying(20) NOT NULL DEFAULT '';

ALTER TABLE catalog_items ADD quality_class character varying(1) NOT NULL DEFAULT '';

ALTER TABLE catalog_items ADD updated_at timestamp with time zone;

UPDATE catalog_items
SET category = 'To classify',
business_central_code = 'TO-FIX-' || id::text,
unit = 'unit',
quality_class = 'A';

ALTER TABLE catalog_items ALTER COLUMN category DROP DEFAULT;

ALTER TABLE catalog_items ALTER COLUMN business_central_code DROP DEFAULT;

ALTER TABLE catalog_items ALTER COLUMN unit DROP DEFAULT;

ALTER TABLE catalog_items ALTER COLUMN quality_class DROP DEFAULT;

CREATE UNIQUE INDEX ix_catalog_items_business_central_code ON catalog_items (business_central_code);

CREATE INDEX ix_catalog_items_quality_class ON catalog_items (quality_class);

ALTER TABLE catalog_items ADD CONSTRAINT ck_catalog_items_category_not_empty CHECK (length(category) > 0);

ALTER TABLE catalog_items ADD CONSTRAINT ck_catalog_items_business_central_code_not_empty CHECK (length(business_central_code) > 0);

ALTER TABLE catalog_items ADD CONSTRAINT ck_catalog_items_unit_not_empty CHECK (length(unit) > 0);

ALTER TABLE catalog_items ADD CONSTRAINT fk_catalog_items_quality_classes_quality_class FOREIGN KEY (quality_class) REFERENCES quality_classes (code) ON DELETE RESTRICT;

INSERT INTO "__EFMigrationsHistory" (migration_id, product_version)
VALUES ('20261117040905_AddCatalogItemDetails', '10.0.13');

COMMIT;
Loading
Loading