clhoria-template: Instructions file for Codex

AGENTS.md

Commands

pnpm install/dev/build/start/typecheck/lint/lint:fix/test
pnpm generate/push/migrate/studio/seed  # Database

Stack

Hono + Node.js 25 + PostgreSQL(Drizzle snake_case) + Redis(ioredis) + BullMQ + JWT(admin/client) + Casbin RBAC + Zod(Chinese errors) + OpenAPI 3.1.0(Scalar) + Vitest + vite

Architecture

Route Tiers: /api/public/* (no auth) | /api/client/* (JWT) | /api/admin/* (JWT+RBAC+audit)

Auto-load: import.meta.glob from routes/{tier}/**/*.index.ts

CRUD 模块开发详见 /crud skill

数据库 Schema 开发详见 /db-schema skill

Critical Rules

Response & Logging (MANDATORY)

return c.json(Resp.ok(data), HttpStatusCodes.OK);
return c.json(Resp.fail("error"), HttpStatusCodes.BAD_REQUEST);
logger.info({ userId }, "[Module]: message"); // data object FIRST
// NEVER: console.log/warn/error (except: env validation, singleton, tests, scripts)

Other Rules

• Status codes: HttpStatusCodes constants
• Dates: date-fns library
• Timestamps: timestamp({ mode: "string", precision: 0 })（秒级精度，匹配 yyyy-MM-dd HH:mm:ss 写入格式）
• 时区：DB 写入时间一律用 format(new Date(), "yyyy-MM-dd HH:mm:ss")（date-fns，跟随系统时区，服务器默认 +8）；禁止用 new Date().toISOString() 写 DB（永远 UTC，会差 8 小时）。API 响应里给前端的时间戳不受此限制
• UUID params: IdUUIDParamsSchema
• Naming: PascalCase (classes/types), UPPER_SNAKE_CASE (enum values), kebab-case (files)
• Folder grouping: When multiple files of same type exist (e.g., *.helpers.ts), create a folder (e.g., helpers/)
• Queries: Use enums eq(table.status, Status.ENABLED) not magic values
• Helpers: Route-level ({feature}.helpers.ts) for complex business logic or reuse within module; simple DB operations stay inline in handlers; global (src/services/) for cross-tier shared logic
• Types: Prefer inferring from Zod schemas (z.infer<typeof schema>) over manual definitions
• Simple guard clauses: if (!x) return null; 单行无花括号（适用于 return 单个值、单个变量、单个函数调用等简短表达式，如 return fallbackPath;、return Promise.resolve();）