Fee check & rules

modules/purchase_trade/docs_source/business/sql/README.md

@@ -45,3 +45,44 @@ Main columns:
 Cross-category UoM rows are reported as manual-review diagnostics because the
 Python code may pass explicit conversion factors that cannot be inferred safely
 from SQL alone.
+
+## fee_quantity_consistency_checks.sql
+
+Checks the fee quantity invariant documented in `fees.md` and `fees.en.md`.
+
+The script ignores `mode = 'ppack'` because Per packing follows a packing
+quantity, not the lot net/gross weight.
+
+For every other fee, it recomputes the expected quantity from the effective
+`fee.lots`:
+
+- physical lots if at least one physical lot is linked;
+- otherwise virtual lots;
+- `fee.qt_state` when filled, capped by the contract `weight basis`;
+- otherwise the contract `weight basis`;
+- closest previous `lot.qt.hist` state by `lot.qt.type.sequence` when the exact
+  state is missing;
+- `lot.qt.hist.quantity` for net fees and `lot.qt.hist.gross_quantity` for gross
+  fees.
+
+Run it on a restored test database:
+
+```sql
+\i modules/purchase_trade/docs/business/sql/fee_quantity_consistency_checks.sql
+```
+
+The script returns rows only when it finds a potential issue.
+
+Main columns:
+
+- `check_name`: failed invariant or manual-review diagnostic.
+- `fee_id`: `fee.fee` id.
+- `purchase_id` / `purchase_number`: related purchase contract when available.
+- `sale_id` / `sale_number`: related sale contract when available.
+- `observed_value`: current `fee.quantity`.
+- `expected_value`: recomputed quantity from effective lots.
+- `diff`: observed minus expected.
+- `detail`: human-readable explanation.
+
+Rows reported as `fee_quantity_uom_manual_review` need manual analysis because
+SQL cannot safely infer cross-category conversion factors.