Opas päivitetty: relaatiotuki, architect-agentin rooli, vertailuluvut

network-poc/frontend/public/GUIDE.md

@@ -321,35 +321,79 @@ Malli tuottaa JSON-rakenteen kuten:
 Tämä on yksinkertainen tehtävä jossa pienikin malli onnistuu luotettavasti:
 entiteettien tunnistus projektin kuvauksesta ja kenttätyyppien valinta.
 
+Speksi sisältää myös **relaatiot** entiteettien välillä:
+
+```json
+{
+  "entities": [
+    {"name": "Author", "table_name": "authors", "fields": [...]},
+    {"name": "Book", "table_name": "books", "fields": [
+      {"name": "title", "sa_type": "String(255)", "py_type": "str", "nullable": false},
+      {"name": "author_id", "sa_type": "Integer", "py_type": "int", "nullable": false}
+    ]}
+  ],
+  "relationships": [
+    {"from": "Book", "field": "author_id", "to": "Author", "type": "many-to-one"}
+  ]
+}
+```
+
+Templateit generoivat relaatioista automaattisesti:
+- `ForeignKey('authors.id')` models.py:hin
+- `relationship("Book", back_populates="author")` molempiin suuntiin
+- `BookDetail`-schema jossa author-data mukana
+- `GET /authors/{id}/books/` nested endpoint
+- FK-validointi: 404 jos parent-entiteettiä ei ole
+
+### Architect-agentti: speksin laatu ratkaisee
+
+Arkkitehti on **kriittisin agentti** koko pipelinessa. Jos speksi on hyvä
+(oikeat entiteetit, kentät, relaatiot), kaikki muu seuraa automaattisesti.
+Jos speksi on huono, templateitkaan eivät pelasta.
+
+Arkkitehtia ohjataan:
+1. **Chain-of-thought**: "Mieti ensin entiteetit, sitten kentät, sitten relaatiot"
+2. **Domain-esimerkit**: Todo, verkkokauppa, blogi — malli näkee miltä hyvä speksi näyttää
+3. **Anti-patternit**: "Ei turhia ID-kenttiä, ei Enumeita, ei suomenkielisiä nimiä koodissa"
+4. **Relaatiosäännöt**: "Jokainen `_id`-kenttä tarvitsee vastaavan relationship-merkinnän"
+
+Isompi malli (tai API) tässä yhdessä kohdassa parantaa kaikkien projektien laatua
+koska speksi on ainoa paikka jossa LLM:n ymmärrys vaikuttaa.
+
 ### Template täyttää loput
 
 Jokainen template on kuin madlib — aukot täytetään speksin datalla:
 
 **models.py template (yksinkertaistettu):**
 ```python
-from sqlalchemy import create_engine, Column, Integer, {sa_types}
+from sqlalchemy import create_engine, Column, Integer, {sa_types}, ForeignKey
+from sqlalchemy.orm import sessionmaker, relationship
 # ... aina samat importit, engine setup, SessionLocal ...
 
 class {entity.name}(Base):
     __tablename__ = "{entity.table_name}"
     id = Column(Integer, primary_key=True, index=True)
     {field.name} = Column({field.sa_type}, nullable={field.nullable})
-    # ... jokainen kenttä speksistä ...
+    # FK-kentät: ForeignKey + relationship automaattisesti
+    {fk_field} = Column(Integer, ForeignKey('{parent_table}.id'))
+    {parent_lower} = relationship("{Parent}", back_populates="{children}")
 ```
 
 Tulos: importit ovat aina oikein, `connect_args` on aina mukana,
-testit importoivat aina `main.py`:stä eivätkä kopioi sitä.
+relaatiot generoituvat oikein, testit importoivat `main.py`:stä eivätkä kopioi sitä.
 
 ### Vertailu: mittaustulokset
 
 | | Vapaa generointi | Rakennuspalaset |
 |---|:---:|:---:|
-| LLM-kutsuja | 7–14 | **1** |
-| Aika | 80–120s | **~20s** |
+| LLM-kutsuja | 7–14 | **3** (speksi + requirements + README) |
+| Aika | 80–120s | **~25s** |
 | Syntaksi OK | ~70% | **100%** |
 | Docker build | vaihteleva | **100%** |
 | Pytest läpi | 0% | **100%** |
 | API toimii | ~30% | **100%** |
+| Relaatiot (FK) | ei koskaan | **100%** |
+| Nested endpointit | ei koskaan | **automaattisesti** |
 
 ### Milloin kumpikin toimii