🛡️ Nimeäminen-luokittelu¶

Tämä dokumentti määrittelee ekosysteemin yhtenäisen nimeämisstandardin. Standardi mahdollistaa dokumentaation automaattisen rakentamisen, projektien tarkan luokittelun ja saumattoman hallinnan kaikilla infrastruktuurin tasoilla.

Ydinperiaate: Projektin nimi on sen ensisijainen metadata-lähde. Jos nimeäminen epäonnistuu, automaattinen luokittelu ja haku portaalissa eivät toimi oikein.

Nimeämistyylien vertailu (Naming Conventions)¶

Tämä taulukko auttaa ymmärtämään eri koodaus- ja järjestelmästandardien välisiä eroja. Repostage-projektissa käytämme ensisijaisesti kebab-case-muotoa.

Tyyli	Esimerkki	Kuvaus
kebab-case	`tool-bash-script`	Sanat erotettu väliviivalla. Suosittu URL-osoitteissa, tiedostonimissä ja pilvi-infrastruktuurissa.
snake_case	`tool_bash_script`	Sanat erotettu alaviivalla. Yleinen erityisesti Python-ohjelmoinnissa ja tietokantojen sarakkeissa.
camelCase	`toolBashScript`	Sanat alkavat isolla kirjaimella, paitsi ensimmäinen. Yleisin tyyli JavaScript- ja Java-muuttujissa.
PascalCase	`ToolBashScript`	Jokainen sana alkaa isolla kirjaimella. Käytetään yleisesti luokkien nimissä (esim. Java, C#, Python).

Miksi kebab-case?¶

URL-yhteensopivuus: Väliviivat ovat selainystävällisiä ja helposti luettavia.
Selkeys: Erottuu selvästi koodin sisäisistä muuttujista (jotka ovat usein snake tai camel).
Moderni standardi: Käytetään lähes kaikissa pilvipalveluissa (Docker, Kubernetes, AWS) resurssien nimeämiseen.

graph TD
    %% Sisääntulo
    subgraph Repot [Repositoriot: GitLab & GitHub]
        NIMI[<b>Nimi:</b> kebab-case-rakenne]
        META[<b>Metadata:</b> Topics/Tagit]
    end

    %% Automaatiokerros
    subgraph Engine [Python Automaatio: main.py]
        API[API-haku: requests]
        REG[Regex: CATEGORY_REGEX]
        DOC[Paikallinen README-analyysi]
    end

    %% Prosessi
    NIMI --> API
    META --> API
    API --> REG
    API --> DOC

    %% Lopputulos
    subgraph Output [Generointi]
        TABLE[AutoEcosystem.md -taulukko]
        PAGES[.pages navigaatio]
    end

    REG --> TABLE
    DOC --> TABLE
    TABLE --> PAGES
    PAGES --> WEB[🌐 Dokumentaatiosivusto]

    %% Tyylittely
    style Engine fill:#fff4dd,stroke:#d97706,stroke-width:2px
    style Output fill:#dcfce7,stroke:#166534
    style Repot fill:#f1f5f9,stroke:#475569

1. Repositorion nimen rakenne¶

Käytetään kebab-case-muotoa (pienet kirjaimet, väliviiva erottimena).

Malli: [kategoria]-[aihe]-[tarkenne/vuosi]

Malli: study-fullstack-jamk2025

Readme.md: meta: JAMK ohjelmistotuotannon -kurssikokonaisuus.

Repositori-tagit: Täsmentävät sisältöä

Jokaisen repositorion README.md sisältää lyhyen, yhden rivin metatiedon, joka kuvaa projektin tarkoituksen, taustan tai alkuperän.

GitLab/GitHub‑tagit ovat manuaalisesti lisättäviä luokittelutietoja, joita automaatio käyttää täydentämään repositorion nimeä ja README.md:n meta:‑kenttää. Ne eivät muuta nimeämismallia, mutta tarjoavat lisäinformaatiota projektin teknologiasta, aiheesta ja tasosta automaation tuottamiin koosteisiin.

2. Kategoriat ja kuvaukset¶

Study- (opintokokonaisuudet)¶

Selite: Käytetään laajoille, monivuotisille tai useasta moduulista koostuville kokonaisuuksille, kuten tutkinnoille, sertifikaattipoluille tai laajoille ammatillisille kursseille. Tämä kategoria toimii "kotina" opintopoluille, jotka voivat sisältää useita konsepteja ja labroja.

Esimerkkejä: * study-softwareengineering-jamk2025 Meta: Ammattikorkeakoulun ohjelmistotuotannon koulutuskokonaisuus.

study-azuresolutions-architect Meta: Sertifikaattiin tähtäävä laaja opintopolku materiaaleineen.
study-fullstack-hel2028 Meta: Laaja Full Stack opintokokonaisuus, muistiinpanot ja harjoitukset.

Concept- (teoria ja arkkitehtuuri)¶

Selite: Sisältää teoreettista osaamista, muistiinpanoja ja teknologiavertailuja. Painopiste on syvässä ymmärryksessä ja dokumentaatiossa.

concept-aiprompt-engineering Meta: Dokumentaatio ja testit promptien optimoinnista.
concept-virtualization-basics Meta: Selvitys virtualisoinnin eri muodoista.

Lab- (harjoitukset ja kokeilut)¶

Selite: Pieniä teknisiä kokeiluja tai kurssitehtäviä. Tarkoituksena on kokeilla uutta teknologiaa käytännössä (esim. koodi-labrat).

lab-linuxpermissions-audit: Meta: Harjoitus Linuxin tiedosto-oikeuksien hallinnasta.
lab-javaoop-patterns: Meta: Harjoituskokoelma Java-suunnittelumalleista.

Project- (sovellukset ja kokonaisuudet)¶

Selite: Täysimittaiset ohjelmistoprojektit, joilla on selkeä käyttötarkoitus ja valmis lopputuote.

project-fastapi-inventoryapi Meta: Varastonhallinnan taustajärjestelmä.
project-pythonllm-rag Meta: Tekoälysovellus omalla tietokannalla (RAG).

Tool- (skriptit ja apuvälineet)¶

Selite: Käytännön työkaluja (Bash, PowerShell, Python), jotka automatisoivat rutiinitehtäviä tai ylläpitoa.

tool-bashlog-analyzer Meta: Skripti palvelimen virhelokien parsimiseen.
tool-powershelluser-onboarding Meta: Automaatio uusien AD-käyttäjien luontiin.

Config- (infrastruktuuri ja IaC)¶

Selite: Järjestelmien, palvelimien ja pilviympäristöjen konfigurointi (Ansible, Terraform, Docker Compose).

config-linuxnginx-hardened Meta: Kiristetty Nginx-konfiguraatio.
config-docker-fullstack Meta: Docker Compose -kokonaisuus verkkokaupalle.

Engine- (Ydinjärjestelmät)¶

Selite: Projektin omat "metajärjestelmät", jotka pyörittävät tätä automaatiota.

engine-repostage-v2 Meta: Projektin nykyiset automaatiomoottorit.

3. Käytettävät tagit ja tilan merkitseminen (Tags)¶

Kategoria	Tagi-esimerkkejä	Selite
Osaamistaso	`level-100`, `level-200`, `level-300`, `level-400`	Osaamisen syvyys (Perusteet -> Arkkitehtuuri).
Projektin tila	`state-discovery`, `state-prototype`, `state-stable`	Projektin kypsyysaste.
Kielet	`lang-python`, `lang-bash`, `lang-powershell`, `lang-js`, `lang-sql`	Ensisijainen käytetty ohjelmointi- tai skriptauskieli.
Käyttöjärjestelmät	`os-linux`, `os-windows`, `os-debian`, `os-rhel`, `os-active-directory`	Kohdejärjestelmä tai hallittava ympäristö.
AI & LLM	`ai-llm`, `ai-rag`, `ai-agents`, `ai-prompting`, `lib-langchain`	Tekoälyintegraatiot ja kielimalliteknologiat.
Infra & Pilvi	`tech-docker`, `tech-kubernetes`, `cloud-aws`, `cloud-azure`, `srv-proxmox`	Kontitus, virtualisointi ja pilvialustat.
Automaatio (IaC)	`sys-ansible`, `sys-terraform`, `sys-powershell-dsc`, `devops-pipeline`	Infrastruktuuri koodina ja CI/CD-automaatio.
Verkko & Sec	`net-vpn`, `net-firewalls`, `sec-hardening`, `sec-owasp`	Verkkoasetukset ja tietoturvan kiristäminen.
Fullstack	`fs-frontend`, `fs-backend`, `lib-react`, `lib-fastapi`	Sovelluskerrokset ja käytetyt kirjastot.

4. Automaatio ja Rakenne¶

study- kategoriassa automaatio voi kerätä kaikki kyseiseen opintopolkuun liittyvät lab- ja project- työt yhteen näkymään.

Näin voidaan osoittaa, miten yksittäiset harjoitukset muodostavat suuren kokonaisuuden ja johtavat lopulta esimerkiksi sertifikaattiin.

Tiivistys¶

Tämä rakenne mahdollistaa sen, että voidaan esitellä sekä pieniä täsmätaitoja (tool-) että valtavia, vuosia kestäneitä kehitysprojekteja (project-) samassa järjestelmässä loogisesti.

Dokumentin tila: Luonnos — Pvm: 11.01.2026