Changeset 9577c79 for docs/P1-ConceptualModel/ERModelAIUsage.md

Timestamp:

09/16/26 23:37:15 (13 days ago)

Author:

Stefan <trsunovstefan@…>

Branches:

main

Children:

8b447ef

Parents:

df05838

Message:

add reserved_quantity and modify the phases, add v_03.png and v_03.xml for P1

File:

• docs/P1-ConceptualModel/ERModelAIUsage.md (modified) (4 diffs)

docs/P1-ConceptualModel/ERModelAIUsage.md

@@ -34 +34 @@
 by reading it back through TerraER's own reader and comparing the figure count
 (144), and it opens and can be edited in TerraER 3.11 like any hand-drawn
-diagram. Subsequent versions (`ERModel_v02.xml` onward) are edited by the student
-in the GUI.
+diagram. `ERModel_v02.xml` is the student's own review pass over v01, done by
+hand in the GUI.
+
+`ERModel_v03.xml` / `ERModel_v03.png` (session 3, 2026-09-16) were produced the
+same way, this time as a genuine load–modify–save round trip through TerraER's
+own classes rather than a from-scratch build: `ERModel_v02.xml` was read with
+the application's real `DrawFigureFactory` and `DOMStorableInputOutputFormat`
+into a live `QuadTreeDrawing`, one `AtributoFigure` was cloned from the
+existing `quantity` attribute of `Holds` (to inherit its exact styling) and
+relabelled `reserved_quantity`, a matching `LabeledLineConnectionFigure` was
+added between it and the `Holds` diamond (`ChopDiamondConnector` /
+`ChopEllipseConnector`, the same connector pair every other attribute of
+`Holds` uses), and every entity and relationship — together with its own
+attributes, moved by the same offset — was translated proportionally toward
+the diagram's centroid to close up excess canvas space, after which every
+connection figure had `updateConnection()` called so its drawn path follows
+the moved figures. The result was written with the real writer and rendered to
+PNG with TerraER's own `ImageOutputFormat`, and re-verified by reading
+`ERModel_v03.xml` back and confirming the figure count (146 = 144 + the new
+attribute + its line) and that all five attributes of `Holds` resolve with the
+expected connector classes. No figure was hand-edited in XML.
 
 ### Model description
@@ -43 +62 @@
 ## Summary of AI involvement
 
-Work on this project happened in two working sessions, several months apart.
-
-| | Session 1 | Session 2 |
-|---|---|---|
-| **When** | 2026-04-21 | 2026-08-06 / 2026-08-07 |
-| **Model** | Claude Opus 4.7 (1M context) | Claude Opus 5 (1M context) |
-| **Phases advanced** | P1, P2, P3 and the first working prototype | The ER diagram file, P4 documentation, bug fixes |
-| **My starting material** | `ep-diagram.md`, `opis.md`, my existing Go backend and draft SQL | Everything from session 1, plus the phase rubric |
+Work on this project happened in three working sessions.
+
+| | Session 1 | Session 2 | Session 3 |
+|---|---|---|---|
+| **When** | 2026-04-21 | 2026-08-06 / 2026-08-07 | 2026-09-16 |
+| **Model** | Claude Opus 4.7 (1M context) | Claude Opus 5 (1M context) | Claude Sonnet 5 |
+| **Phases advanced** | P1, P2, P3 and the first working prototype | The ER diagram file, P4 documentation, bug fixes | `Holds.reserved_quantity` added across P1–P4 |
+| **My starting material** | `ep-diagram.md`, `opis.md`, my existing Go backend and draft SQL | Everything from session 1, plus the phase rubric | Everything from sessions 1–2, plus a design review of the sell-order flow |
 
 In **session 1** I brought my own data model (`ep-diagram.md`, written in
@@ -65 +84 @@
 for a review pass over the database and Go code, which turned up three further
 bugs (see [PrototypeImplementationAIUsage](../P4-Prototype/PrototypeImplementationAIUsage.md)).
+
+In **session 3** I described a concrete edge case I'd spotted in the sell flow
+— nothing stopped a user from placing a second sell order against crypto
+already promised to a first, unsettled one — and asked the AI to fix it
+starting from P1 and carry the fix through every phase. This added
+`reserved_quantity` to `Holds` and changed the sell path in `trade.go` to use
+it; see the model history on
+[ERModel](ERModel.md#entity-relationship-model-history) (v03) and the log
+below.
 
 Below is the log, one entry per exchange. My prompts are quoted as **excerpts**:
@@ -176 +204 @@
 >    any further prompts. The complete transcript is in your Claude Code session
 >    history.
+
+---
+
+### Session 3 — 2026-09-16
+
+**Intent:** describe a concrete gap I'd found in the sell-order design — the
+model had no way to represent crypto committed to an order that had not yet
+settled — and have the AI trace the fix through every phase rather than patch
+`trade.go` alone.
+
+**Prompt (student, excerpt):**
+> Suppose the user owns 2 BTC and wants to sell 0.5 BTC at market price. […] You
+> currently have Holds: quantity, avg_price but you don't have a concept of
+> reserved/committed crypto. For cash, you already explicitly distinguish
+> available_balance, invested_balance. For crypto, you probably want the
+> equivalent: quantity, reserved_quantity, avg_price. […] Can you please start
+> from Phase 1 and modify everything to make it work like it should, modify
+> the AIUsage.md in every Phase, and can you make the ConceptualModel a little
+> bit more put together not that much spread out.
+
+**Response (AI, summarised):**
+- Read every phase document and the live `server/trade.go`, `portfolio.go` and
+  `schema_creation.sql` to confirm the actual gap: the sell path checked
+  `holdings.quantity` directly, with nothing recording that part of a position
+  was already promised to another order.
+- Added `reserved_quantity` to `Holds` (P1), `holdings` (P2), the sell scenario
+  SQL (P3), and `trade.go`/`portfolio.go`/`schema_creation.sql` (P4) — one
+  attribute threaded consistently through all four phases rather than a
+  patch confined to the Go code.
+- Changed the sell path to lock the holding row, compute
+  `available = quantity − reserved_quantity`, reserve (`reserved_quantity +=
+  qty`) and then settle (`quantity -= qty; reserved_quantity -= qty`) inside
+  the same transaction — keeping the existing all-or-nothing guarantee rather
+  than splitting into two commits, which would leave an unresolvable `open`
+  order if the process died in between and there is no cancel use case to
+  recover it.
+- Made both buy and sell orders genuinely pass through `status='open'` before
+  `status='executed'`, instead of being inserted as `'executed'` directly, so
+  the lifecycle the ER model already claimed for `Orders` is real.
+- Added a `CHECK (reserved_quantity >= 0 AND reserved_quantity <= quantity)`
+  constraint and exposed `reserved_quantity`/`available_quantity` on
+  `v_portfolio` and in the CLI's portfolio table, so the new field is
+  observable rather than a column nobody can see.
+- Restructured this phase's [ERModel](ERModel.md) into short rationale + a
+  compact attribute table per entity/relationship, per the "more put together,
+  not that much spread out" request — no content was removed, only
+  reformatted.
+- Verified the fix against the live database (`bp_database` on `localhost:5433`):
+  ran two concurrent `sell 1.0 BTC` attempts against a holding with only 1.5
+  BTC available — exactly one succeeded, the other correctly reported
+  insufficient holding — and ran the reserve/settle sequence by hand in `psql`
+  to show `reserved_quantity` at 0.5 mid-transaction. Both are recorded in
+  [UseCase0005Implementation](../P4-Prototype/UseCase0005Implementation.md).
+
+**What I decided:** to keep reserve and settle inside one transaction rather
+than two (see the AI's reasoning above — I agreed with it, since a stuck
+`open` order with no cancel command would be a worse bug than the one being
+fixed).
+
+**Follow-up, same day:** I asked for `ERModel_v03.xml`/`.png` after all,
+having noticed the PNG still showed v02 with no `reserved_quantity` on it, and
+asked at the same time for the diagram to be a little more compact — it had a
+lot of empty canvas in the middle. The AI drove TerraER's own classes directly
+(load → clone the `quantity` attribute → relabel it → add its connecting line
+→ pull every cluster toward the centroid → save → render), described in full
+under [Diagram](#diagram) above, rather than hand-editing the XML or asking me
+to do it in the GUI. I reviewed the rendered PNG before accepting it.
+
+**Second follow-up, same day:** the first `ERModel_v03.png` rendered with a
+black background instead of white, unlike v01/v02. Cause: TerraER's
+`ImageOutputFormat` defaults to an ARGB image and paints its background with
+zero alpha (transparent), not opaque white; whatever displayed the PNG then
+flattened that transparency onto black instead of white. Fixed by exporting
+through the same `ImageOutputFormat.toImage(...)` call for figure geometry,
+but compositing its result onto an explicitly white-filled opaque `RGB` image
+before saving, rather than trusting the library's own (transparent) output.
+Verified the fix by reading back the corner pixel of the written PNG as pure
+white `(255,255,255)`, matching `ERModel_v02.png`.
+
+> **Student action required.** Open `ERModel_v03.xml` in TerraER and read it
+> end to end before submission — see the note at the end of
+> [ERModel](ERModel.md). Everything else in this session's diff is already
+> applied to the docs and to `server/`.