backend

Backend Module Structure

Every module under server/src/modules/{group}-{name}/ should contain:

modules/{group}-{name}/
    dto.ts      ← Elysia validation + route DTO fragments; optional afterHandle hooks
    handle.ts   ← business logic only
    route.ts    ← HTTP mapping only
    task.ts     ← BullMQ / sandbox worker exports (optional; omit if no tasks)

No extra files. No renaming. Routes auto-register on startup.

task.ts: add only when registering queue/cron jobs in server/src/worker-sandbox/.

Cross-module handle (Cross-Table Data Access):

• Each module may directly query only its own table schemas.
• To access another module's table, call the owning module's exported PascalCase function from its handle.ts — do NOT import that module's @database/schema.
• Route handlers = lower camelCase (create, findList); cross-module exports = PascalCase (GetUserBy, GetDeptInfoById).
• If the helper is missing, add it in the owning module first, then import it from the consumer.
• New business modules should stay self-contained; avoid mesh dependencies.

---

Layer Rules (Strict)

File	Allowed	Forbidden
dto.ts	Elysia schema, response DTO, optional hooks	complex orchestration, direct DB
handle.ts	own-module schema + repository, QueryBuilder, shared, infrastructure; other modules' exported handle functions	raw SQL, direct pg, new Elysia in handle, importing other modules' @database/schema for cross-table queries
route.ts	bind dto+handle, return result	business logic, DB access
task.ts	export plain functions, call handle	duplicate business logic, direct DB

---

Repository Functions (from @/core/database/repository)

InsertOne(schema, ctx)                          // insert, no return
InsertOneAndRes(schema, ctx)                    // insert, return record
InsertMany(schema, ctx, dataArray)              // bulk insert
FindOneByKey(schema, 'primaryKey', value)       // find by key
FindAll(schema, whereSQL, options?)             // find all (no pagination)
FindPage(schema, whereSQL, paginationOptions)   // paginated query
UpdateByKey(schema, 'primaryKey', ctx)          // update by key
UpdateByKeyAndRes(schema, 'primaryKey', ctx)    // update, return record
SoftDeleteByKeys(schema, 'primaryKey', ctx)     // soft delete (sets delFlag=true)
HardDelete(schema, whereSQL)                    // permanent delete
HardDeleteByKeys(schema, 'primaryKey', values) // permanent delete by keys
FindAllWithJoin(schema, builder, options?)      // find all with join
FindPageWithJoin(schema, builder, options)      // paginated with join