Places contain places and stock and space by any field — and #31's document flows, which never reached main

[goetchstone]

Summary

PR 3 of the stock-ledger plan (docs/domains/inventory.md → "Delivery"): phases 12–14, places and space.

This PR also brings PR 2 to main. #31 merged into its stacked base, feat/stock-places-and-journal, 27 seconds after #30 merged that branch into main, so #31's work never reached main. This branch is main plus that same commit (its tree is identical to #31's merge, a4129e1), plus this PR's. One PR and one CI run instead of two. The first commit was already reviewed as #31; the second is new.

• 12. Places contain places. StockLocation.parentId nests places as deep as a store wants: North Barn › Floor 2 › Stock Sofas › Shelf 3. A small store stays flat. A new GROUP type (a building, a floor) holds only places, and the ledger refuses stock into one. One set of rules in lib/inventory/placeTree.ts, used by the routes and the preset (rule 42):

  • a parent is an active place at the same store;
  • a place is never inside itself, however deep the loop;
  • a place holding stock, or one a store lands stock in, never becomes a group, and no landing place can point at a group;
  • a place with active places inside it stays active, and one with any places inside it is not deleted.

  Warehouse › Locations shows each store's places as a tree, with an "Inside" picker. Square footage can now be entered for any place. Before, it was sent only for floor places, so saving any other place wiped its footage.

• The migration (20261018120000_places_contain_places) turns the free-text building/floor columns into GROUP places and nests every place inside them. area was an index that each place's code already carried, so it is dropped. The migration refuses to finish if any place would lose its building or floor.

• 13. Stock and space (Reports › Stock and Space). Look inside every store, a store, or any place, and group by the places inside it, place type, department, category, type, vendor or collection.

  • Each unit counts toward its nearest measured place, and that place's footage is split by unit share.
  • Empty measured places show as "Empty space"; units with no measured place above them show as "Unmeasured units".
  • A measured place inside another measured place is flagged, because that floor would count twice.

• 14. The stock-locations preset says where a place is with inside. It refuses the retired building/floor/area fields rather than dropping them: dropping them would move every place of an old file to the top of its store. An export always applies back unchanged.

What changed

• Migration:
  • adds StockLocation.parentId (FK ON DELETE RESTRICT);
  • creates the GROUP places BLDG-<name> and FLR-[<building>-]<n>, parented to their building;
  • parents every place;
  • drops building, floor and area.
• Lib:
  • new: inventory/placeTree.ts (descendantIds, ancestry, placePath, treeOrder, placeParentProblem, placeTypeProblem, placeDeactivateProblem) and reports/stockBy.ts;
  • locationTypes.ts: GROUP and holdsStock;
  • ledger.ts: assertPlaceAtStore refuses a group;
  • landingPlaces.ts: landingAllows, so "any type" means any type that holds stock, shared by the store route and the screen;
  • config: presetSchema (inside, loop and unknown-code checks, retired fields refused), presetSerialize, dbConfigState (exports inside only for an active parent), applyPreset (parents set after every listed place exists; refuses making a group of a place holding stock).
• Routes:
  • the stock-location create and update routes validate the parent, the type change and deactivation, and delete is refused while places are inside;
  • the store routes and the lean picker send parentId;
  • new: /api/reports/stock-by.
• Screens:
  • Warehouse › Locations: the tree view, plus "Inside" and square footage for every type in the stock-location dialog;
  • new: Reports › Stock and Space (card and page permission reporting.read).
• Docs:
  • inventory.md: "Places contain places"; phases 12–14 ticked; place labels moved to phase 15, where the scanner reads them;
  • config-presets.md: inside and the retired fields;
  • reporting.md: Stock and Space, plus the Oversold row it was missing.

Trace / Verification

• Preflight on a restored deployment database (read-only; numbers only): 60 places; 42 have a building, across 3 buildings; 54 have a floor; every area number also appears in the place's code.
• The migration:
  • on a fresh copy of that database, taken through the earlier migrations and this one, then dropped: 13 GROUP places (8 floors inside a building), 54 of 60 places parented, stock unchanged at 19,317 rows and 43,146 units;
  • on a fresh scratch database built by npm run setup -- --scale=ci (all migrations, then the seed): prisma migrate diff --exit-code printed No difference detected.
• Mutation checks, each restored afterwards:
  • no loop check in placeParentProblem: stockPlaceTree 1/7 failed;
  • the ledger takes stock into a group: 1/7;
  • any place may become a group: stockPlaceTree 2/7, stockLocationsPreset 1/13;
  • space counted only at the unit's own place: splitSpaceBy 2/6, stockBy 4/6;
  • retired fields dropped silently: stockLocationsPreset (unit) 1/13;
  • the preset never sets parents: 5/13;
  • a landing place may be a group: stockPlaceTree 1/7;
  • the export names an inactive parent: stockLocationsPreset 1/13;
  • deactivating a place with places inside: stockPlaceTree 1/7.
• In the browser, on that seeded scratch database:
  • Warehouse › Locations: a GROUP place "North Barn" (5,000 sq ft) was created, and Back Stock was put inside it. The tree shows Back Stock indented under the barn, and its 1,800 sq ft survived the save.
  • This is where I found that the Returns-place picker offered the group. Returns allows "any" type, which now included GROUP; fixed with landingAllows, and after a reload no landing-place picker offers it.
  • Reports › Stock and Space, every store by place: Central Distribution Warehouse 560 units / 25,500 sq ft; Millbrook 275 / 11,000; Wintergreen 312 / 7,500; Empty space 5,000 (the barn); Unmeasured units 8 (in transit). The double-count warning names Back Stock inside North Barn.
  • The same store by department splits Millbrook's floor across eight departments. ?by=colour answers 400 with the list of fields.
  • No console errors on either screen, apart from one hot-reload error caught mid-edit, which cleared on reload.
• Callers:
  • building/floor/area have no readers left in src/, prisma/seed or the shipped config/presets.
  • The landing-place type check had two readers, the store route (landingPlaceProblem) and LocationsView; both now call landingAllows.
  • placeTypeProblem is called from the stock-location update route and applyPreset; placeParentProblem from both stock-location write routes.

Scan / gate state

npm run check:local on the branch:

Step	Result
1 validate	✓ (0 errors; warnings 935, unchanged from #31)
2 test:coverage (all unit + all integration, merged)	✓: statements 69.84%, branches 58.28%, functions 75.09%, lines 71.09% (#31: 69.45 / 57.89 / 74.72 / 70.74)
3 Sonar	not run: no SONAR_TOKEN locally
4 markdownlint	✓
5 Semgrep	✓ 0 findings
6 OSV	skipped (no lockfile change)

The run covered the final code: nothing changed after it except the rebase onto main, whose resulting tree is byte-identical to the tree that was checked. CI has never run on the first commit (#31's work): the workflows run only on PRs into main, and #31 targeted a feature branch. This PR is its first CI run.

Not in this PR, and why

• Place labels (L-<id>) move to phase 15 (PR 4), with the scanner that reads them.
• Space is split by unit share. Splitting by product footprint waits until enough products carry dimensions (rule 41); the choice is noted in stockBy.ts and reporting.md.

Test plan

• CI: Lint/Typecheck/Format/Test, integration, "Migrations match the schema", setup/seed/smoke, Semgrep, osv-scanner
• After merge and the local rebuild: Warehouse › Locations at a local instance with buildings and floors shows the buildings and floors as groups with their places inside; Reports › Stock and Space for one store

🤖 Generated with Claude Code