new module

Ezzel adhatsz új modult egy projekthez: egyetlen hívással scaffoldolja a belépési pontot, az első surface-t, a kontraktust és a modul-szintű közös vázakat.

go tool gpsystem new module <név> [--surface <név>]

Projekten belül futtasd (a CLI felfelé sétálva megtalálja a gpsystem.yaml-t). A modulnév kisbetű/számjegy: Go csomagnév, mappanév és URL-szegmens lesz belőle. Ugyanez a szabály érvényes az első surface nevére is (--surface, default api).

Mit generál

• cmd/<név>/main.go: a ~20 soros belépési pont, ami a server.Run-t hívja, és egy al-routert mountol az /api/v1 alá
• internal/modules/<név>/register.go: Dependencies struct + surface-enként egy exportált Register<Surface>(router, deps) függvény (pl. RegisterApi, RegisterWeb)
• Egy első surface-t (default api) a surfaces/<surface>/ alatt: a generált szigorú interfészt implementáló handler (a minta List egy minimális service/ varratot hív), policy/ registry-stub, plusz üresen tartott http/mapper/ mappa (.gitkeep) a saját kódodnak
• A modul-szintű közös vázakat: core/ (a surface-ek által megosztott szabályok, entitások és sentinel-hibák helye, benne egy ErrNotFound példával) és repository/ (a modul egyetlen perzisztencia-rétege); ezeket az első surface bélyegzi oda, a későbbi add surface hívások már kihagyják
• spec/typespec/modules/<név>/: <surface>.tsp mintaművelettel + models/<surface>.tsp
• api/oapi-codegen/<név>-<surface>.yaml codegen konfig a projekt template-készletére kötve
• compose.yml-be a modul app-service-e: build a projekt Dockerfile-jából (target: development), bekötve postgres/valkey/migrate depends_on-nal, dupla Traefik router path-alapú routinggal (lásd new project)

Anchor-beszúrások

• main.tsp ← modul-importok (gpsystem:modules)
• cmd/<név>/main.go ← <név>.Register<Surface>(api, deps) hívás (gpsystem:registrations)
• register.go ← surface-enkénti Register<Surface> függvény + importok (renderelve, majd goimports-szal formázva)
• compose.yml ← a modul-service a gpsystem:services anchornál

Compose-beszúrás

A compose.yml és a Dockerfile minden projektben megvan (a new project-től), a new module csak az új modul service-ét szúrja be a gpsystem:services anchornál, depends_on-nal postgres/valkey/migrate-re. Ha a compose.yml-ből hiányzik a networks:/volumes: szekció vagy a postgres pg_isready healthcheck, a modul-service YAML-je csak kiíródik a terminálra, kézi beillesztésre; ilyenkor egyszerűbb lehet az add compose --force-szal futtatása, és a manifestből tiszta compose.yml-t újraépíteni.

Generálás után

mise run generate    # tsp → OpenAPI → szigorú szerverkód → build
go run ./cmd/<név>

A váznak még nincs perzisztenciája: a közös szabályokat a modul core/ csomagjában, a perzisztenciát a modul-szintű repository/-ban építsd fel, és a surface service/ varratán át hívd a handlerből.