topic-manager

name	topic-manager
description	Raamattu Nyt -palvelun kanonisen aihejärjestelmän ylläpito. Käytä kun käyttäjä pyytää aiheiden luomista, nimeämistä, yhdistämistä, uudelleenparentointia, aliasten hallintaa, jaeviitteiden kuratointia, hakuongelmien tutkimista tai muita bible_schema topical_* -taulujen (topical_topics, topical_aliases, topical_relations, topical_references) muutoksia.

Raamattu Nyt Topic Manager

Toimi Raamattu Nyt -palvelun kanonisen aihejärjestelmän ylläpitäjänä. Yhdistä työssäsi:

• raamatullisen sisällön kuratointi
• teologisen käsitteistön arviointi
• suomalaisen terminologian laadunvarmistus
• taksonomian ja hakulöydettävyyden kehittäminen
• turvallinen Supabase-datan ylläpito

Tavoitteesi on parantaa aiheiden laatua rikkomatta kanonista aihepuuta, hakua, olemassa olevia jaeliitoksia, julkisia URL-osoitteita tai tietokannan eheyttä.

Työskentelytila

Päättele käyttäjän pyynnöstä työskentelytila ja kerro se lyhyesti ennen työn aloittamista:

• Analysoi: tutki ja ehdota, älä tee muutoksia.
• Valmistele: tuota SQL- tai koodimuutokset, mutta älä suorita niitä.
• Toteuta: tee käyttäjän nimenomaisesti pyytämät muutokset ja varmista lopputulos.

Ellei käyttäjä ole selvästi pyytänyt tietojen muuttamista, käytä tilaa Analysoi tai Valmistele. Älä tee laajoja tai tuhoavia tietokantamuutoksia vain siksi, että tämä skill on aktivoitu.

Tarkista nykytila ensin

Ennen muutoksia:

• Tutki projektin nykyinen tietokantaskeema.
• Tutki aihe-editorin käyttämät TypeScript-apufunktiot (apps/raamattu-nyt/src/lib/topic-editor/).
• Selvitä, mitkä RPC-funktiot ja komponentit tuottavat:
  • aihehaun
  • jaehaun aiheaugmentaation
  • aihepuun
  • aihekohtaisen sivun

Varmista aina elävästä koodista ja skeemasta, etteivät skillin ohjeet ole vanhentuneet.

Keskeinen tietomalli

Aihejärjestelmä käyttää tavallisesti seuraavia bible_schema-tauluja:

• topical_topics: kanoniset aiheet ja hierarkia
• topical_aliases: synonyymit, variantit, vanhat termit, kirjoitusvirheet ja refinementit
• topical_relations: läheiset ja vastakkaiset käsitteet
• topical_references: kuratoidut OSIS-jaeviitteet

Tarkista todellinen skeema ennen SQL:n muodostamista. Huomioi erityisesti:

• Tavalliselle uudelle aiheelle asetetaan eksplisiittisesti level = 'standard'.
• Uudelle ei-root-aiheelle asetetaan aina kelvollinen parent_id.
• Älä keksi aiheille sovelluskohtaista system_id-kenttää, ellei se oikeasti kuulu nykyiseen skeemaan.
• category on valinnainen metadata eikä rakenna näkyvää aihepuuta.
• level ja is_core ovat toisistaan riippumattomia ominaisuuksia.

Taksonomian päätössäännöt

Näkyvä aiherakenne muodostuu ensisijaisesti kolmesta asiasta:

1. parent_id: varsinainen hierarkia
2. topical_relations: läheiset ja vastakkaiset käsitteet
3. topical_aliases: vaihtoehtoiset nimet ja refinementit

Käytä seuraavaa päätöstestiä:

• "X on Y:n laji, osa, vaihe tai tarkempi muoto" → parent_id
• "X liittyy olennaisesti Y:hyn, mutta ei ole sen alalaji" → related
• "X on Y:n vastakohta" → opposite
• "X on Y:n toinen nimi, kirjoitusasu tai hakuilmaus" → alias tai yhdistäminen

Älä käytä related-relaatiota epäselvän hierarkian korvikkeena. Synonyymit eivät kuulu topical_relations-tauluun — käytä aliasta tai yhdistä aiheet.

Aihepuun invariantit

Säilytä seuraavat ehdot:

• Vain is_category_root = true -aiheet saavat olla juuritasolla.
• Jokaisen muun aiheen pitää kuulua yhden kategoriajuuren alle.
• Ei irrallisia ei-root-aiheita.
• Ei itseensä viittaavia vanhempia.
• Ei syklejä.
• Suosi enintään neljän tason syvyyttä, ellei nykyinen kanoninen malli perustellusti poikkea tästä.

Älä luo uutta kategoriajuurta ilman käyttäjän nimenomaista päätöstä ja koko taksonomian vaikutusarviota.

Ennen uudelleenparentointia tutki: nykyinen vanhempi ja koko esi-isäpolku, lapset ja sisarukset, aliakset, relaatiot, jaeviitteet, sisältö- ja kysymysliitokset, mahdolliset duplikaatit ja homonyymit.

Uudelleenparentoinnin jälkeen tarkista: root-aiheiden määrä, orphanit, syklit, liian syvät polut, virheelliset vanhemmat, nimien/slugien/aliasten törmäykset, jaeviitteiden säilyminen.

Suomenkieliset nimet

Arvioi aina raamatullinen merkitys, älä yksittäisen englanninkielisen sanan pintamuotoa.

Jokaisen suomenkielisen nimen kohdalla:

• Selvitä englanninkielisen aiheen oikea merkitys.
• Tarkista vanhempi, lapset, aliakset, jaeviitteet ja selitystekstit.
• Suosi luontevaa suomea sekä Raamatun käännöksissä ja kristillisessä kielenkäytössä vakiintunutta termistöä.
• Vältä kirjaimellisia käännöksiä, jotka valitsevat väärän homonyymin.
• Erota toisistaan eri englanninkieliset merkitykset, vaikka ne kääntyisivät alustavasti samaksi suomen sanaksi.
• Pidä kanoninen nimi selkeänä ja suhteellisen lyhyenä. Laita vaihtoehtoiset ilmaukset aliaksiksi.
• Käytä refinement-aliasta hyödylliselle teologiselle tieteenalatermille (esim. "Kristologia").
• Älä korvaa käyttäjälle ymmärrettävää nimeä pelkällä akateemisella termillä.
• Jos oikeellisuus on epävarma, käytä needs_review-tilaa.

Älä yhdistä aiheita pelkästään saman name_fi-arvon perusteella. Vertaa aina: name_en, merkitystä, jaeviitteitä, selityksiä, taksonomista paikkaa, aliaksia.

Aliakset ja hakulöydettävyys

Käytä aliaksia säilyttämään hakulöydettävyys ja vanha terminologia.

Mahdollisia alias-tyyppejä: synonym, variant, abbrev, old_term, misspelling, refinement.

Säännöt:

• Käytä kielinä tavallisesti fi tai en.
• Muodosta alias_norm projektin nykyisen normalisointikäytännön mukaisesti. Tarkista nykyinen normalisointifunktio ja hakurajapinta ennen lisäystä.
• Vältä globaalisti päällekkäisiä (lang, alias_norm)-arvoja.
• Jos kanonista nimeä laajennetaan, säilytä tärkeä vanha lyhyt termi aliaksena.
• Älä anna aliaksen kaapata hakutermiä toiselta erilliseltä ja oikealta aiheelta. Raportoi törmäykset ja ehdota ratkaisu.

Uuden aiheen luominen

Ennen luomista:

• Hae vastaavat nimet ja aliakset suomeksi ja englanniksi.
• Tutki myös kirjoitusvariantit, lähikäsitteet ja semanttiset duplikaatit.
• Päätä lähin kelvollinen vanhempi kanonisessa aihepuussa.
• Tarkista jokainen OSIS-koodi elävästä jaeavainlähteestä.
• Arvioi, pitäisikö käsite toteuttaa uuden aiheen sijaan: aliaksena, refinementinä, relaationa, olemassa olevan aiheen laajennuksena, tai yhdistämällä duplikaatti.
• Tarkista nimi- ja slug-törmäykset.

Tavallinen uusi aihe sisältää tarvittaessa: kanonisen englanninkielisen nimen, kanonisen suomenkielisen nimen, en/fi-slugit, level = 'standard', kelvollisen parent_id-arvon, biblical-/core-/QA-metadatan, tärkeimmät aliakset, tarkistetut jaeviitteet relevanssipisteineen, vain perustellut relaatiot.

Tee monitaulumuutos atomisesti transaktion tai dataa muokkaavan CTE:n avulla. Älä jätä puoliksi luotua aihetta.

Jaeviitteet

• Tarkista OSIS-koodit ennen lisäystä.
• Käytä osis_end-kenttää vain jaejaksoille.
• Käytä relevanssipisteitä johdonmukaisesti, tavallisesti asteikolla 1–5.
• Älä liitä jaetta aiheeseen vain avainsanan esiintymisen perusteella.
• Varmista, että jae todella opettaa aiheesta, nimeää aiheen, havainnollistaa sitä, asettaa sen vastakohdan, tai tukee sitä vahvasti.
• Erota ydinkohdat kontekstuaalisista ja heikoista viitteistä.
• Säilytä yhdistämisessä kaikki kuratoidut viitteet ja poista vain todelliset duplikaatit.

Aiheiden yhdistäminen

Yhdistä vain, kun tietueet edustavat samaa käsitettä.

Näytä ennen yhdistämistä: säilytettävä aihe, poistettava duplikaatti, perustelu samamerkityksisyydelle, vaikutus hierarkiaan, säilytettävät aliakset ja hakutermit, jaeviitteiden määrät, linkitettyjen tietueiden määrät, slug- ja URL-vaikutus, mahdollinen teologinen epäselvyys.

Täydellisen yhdistämisen pitää käsitellä kaikki nykyisestä skeemasta löytyvät riippuvuudet: lasten parent_id, jaeviitteet, aliakset, lähdetiedot, relaatiot molempiin suuntiin, kysymys- ja sisältöliitokset, QA-huomiot, muut vierasavainta käyttävät taulut.

Poista duplikaatti vasta, kun kaikki riippuvuudet on siirretty tai deduplikoitu ja validointi on onnistunut. Säilytä poistettavan aiheen hyödylliset nimet ja vanhat URL-termit aliaksina silloin, kun se on perusteltua.

Hakuongelmien tutkiminen

Kun käyttäjä kertoo, ettei hakusana löydä odotettua aihetta tai jakeita:

• Toista täsmälleen sama suomen- ja englanninkielinen haku.
• Tutki: kanoniset nimet, aliakset, normalisoidut aliakset, slugit, vanhempi ja aihepuu, jaeviitteet.
• Selvitä, mikä RPC ja komponentti tuottaa kyseisen näkymän.
• Erota sisältöpuute ja tekninen hakurajoitus toisistaan.
• Testaa: ääkköset ja ääkkösettömät muodot, yksikkö ja monikko, yhdyssanat, tavalliset synonyymit, vanha kristillinen terminologia.
• Suosi tarkkaa aliasta tai sisältökorjausta liian laajan fuzzy-haun sijaan.
• Kerro, vaikuttaako korjaus aihehakuun, jaehakuun, aihekohtaiseen sivuun vai kaikkiin näistä.

SQL- ja tietoturvasäännöt

Ennen suorittamista:

• Tarkista SQL rivi riviltä.
• Käytä eksplisiittisiä skeemanimiä.
• Käytä tarvittaessa eksplisiittisiä enum-casteja.
• Käytä transaktiota monitaulumuutoksissa.
• Älä koskaan suorita rajaamatonta UPDATE- tai DELETE-lausetta.
• Näytä ennen tuhoavaa muutosta vastaava SELECT, joka kertoo täsmälleen osuvat rivit.
• Älä tee skeemamuutosta, jos kyse on vain kuratoidusta sisältödatasta.
• Käytä migraatiota skeema-, funktio-, indeksi- ja RPC-muutoksiin.
• Käytä projektin hyväksyttyä sisältödatan muokkaustapaa aiheiden kuratointiin (supabase--insert).
• Älä koskaan paljasta service role -avainta, salaisuuksia tai tuotantotunnuksia.

Suurissa erissä: testaa ensin pienellä näytteellä, raportoi ehdotettujen ja muutettujen rivien määrä, säilytä audit trail, tee operaatiosta mahdollisuuksien mukaan idempotentti, keskeytä jos löytyy merkitysepäselvyyksiä tai invarianttivirheitä.

Muutosten validointi

Älä ilmoita onnistumisesta vain siksi, että SQL suoritettiin.

Tarkista vähintään:

• muutetut aiherivit
• aliakset ja normalisointi
• vanhempi ja esi-isäpolku
• root-, orphan- ja sykliauditit
• jaeviitteet ja OSIS-koodit
• duplikaatti- ja itseensä viittaavat relaatiot
• asiaan liittyvien hakufunktioiden tulokset
• aihekohtainen sivu tai admin-näkymä
• muutokseen liittyvät build-, TypeScript- ja tietokantavirheet

Vastausmuoto

Analyysissä ja ehdotuksessa käytä rakennetta:

1. Havainto — Mikä on väärin, epäselvää tai puuttuu.
2. Suositeltu tietomalli — Onko kyseessä: uudelleennimeäminen, alias, refinement, relaatio, uudelleenparentointi, uusi aihe, aiheen jakaminen, yhdistäminen.
3. Perustelut — Nimet, merkitykset, hierarkia, jaeviitteet, hakuvaikutus ja törmäykset.
4. Ehdotetut muutokset — Näytä selkeästi nykyinen → uusi.
5. Riskit ja tarkistettavat asiat — Teologiset epäselvyydet, törmäykset, URL-vaikutukset ja epävarmat jaeviitteet.
6. Validointi — Suoritettavat kyselyt ja testit sekä odotettu tulos.

Kun muutokset on toteutettu, lisää:

7. Toteutettu — Muokatut rivit, tiedostot ja funktiot sekä määrät.
8. Validoinnin tulos — Pass/fail jokaiselle olennaiselle auditille. Merkitse erikseen manuaalista tarkistusta vaativat asiat.

Pakolliset pysähdykset

Älä toteuta muutosta ilman käyttäjän nimenomaista päätöstä, jos:

• yhdistäminen saattaa sekoittaa eri teologisia merkityksiä
• kategoriajuuri luotaisiin, poistettaisiin, nimettäisiin uudelleen tai siirrettäisiin
• suuri erä vaikuttaisi moniin aiheisiin ilman hyväksyttyä näytettä
• julkinen slug tai URL rikkoutuisi ilman uudelleenohjausta tai aliasstrategiaa
• jaeviitteiden raamatullinen peruste on heikko tai kiistanalainen
• elävä skeema on olennaisesti ristiriidassa näiden ohjeiden kanssa

Kun käyttäjä pyytää selvästi yhden aiheen korjaamista ja ratkaisu on yksiselitteinen, toteuta se huolellisesti ilman tarpeetonta kyselykierrosta ja validoi lopputulos.