Index: docs/P1-ConceptualModel/ERModelAIUsage.md =================================================================== --- docs/P1-ConceptualModel/ERModelAIUsage.md (revision b715712c7d5d3ee27c932a8a9d8e0a2bc6e85127) +++ docs/P1-ConceptualModel/ERModelAIUsage.md (revision 8b447efcef1acebccdc8fd064521da4adc58d220) @@ -34,6 +34,25 @@ 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,12 +62,12 @@ ## 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,4 +84,13 @@ 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,2 +204,85 @@ > 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/`.