---
name: api-feature
description: Implement or review an end-to-end gocron HTTP API change. Use when adding or changing Gin routes, handlers, request or response payloads, authorization, audit behavior, frontend API clients, API types, OpenAPI-style documentation, or API tests.
---

# Build a gocron API feature

Keep the route, authorization rule, handler, frontend client, types,
translations, documentation, and tests as one change.

## Compatibility invariants

- When the contract changes, preserve both deployment orders: an `N`
  frontend/client must tolerate an `N-1` backend, and an `N` backend must serve
  `N-1` frontends/clients.
- Keep routes, methods, accepted requests, response fields and types, status
  codes, pagination, and SSE event contracts stable. New response fields must
  be optional; new request fields must have compatible defaults.
- Detect new server capabilities before depending on them. If `N-1` lacks an
  endpoint, field, or stream behavior, retain a safe legacy path or hide it.
- Never repurpose an existing field or error code. Breaking contracts require
  explicit approval, a major version, and migration/rollout/rollback plans.

## Performance invariants

- Bound every collection response and expensive input. Require pagination,
  maximum page sizes, upload/body limits, and bounded filters where applicable.
- Prevent N+1 queries and per-row remote calls. Capture query counts for list
  endpoints and inspect query plans for new filters, sorting, or joins.
- For polling and SSE, bound connection/resource use, clean up on disconnect,
  avoid per-client database polling where sharing is safe, and apply
  backpressure or a documented drop/coalescing policy.
- Do not return or retain unbounded task output/logs. Use paging, cursors,
  bounded chunks, or streaming with cancellation.
- Benchmark materially affected high-traffic or high-volume endpoints with
  representative data and report applicable metrics.

## Trace the existing path

- Inspect neighboring registrations in `internal/routers/routers.go`, handlers
  under `internal/routers`, models/services called by the handler, and the
  matching frontend module under `web/gocronx-admin/src/api`.
- Identify every middleware applied to the route group. Classify the endpoint
  as public, authenticated, admin-only, API-token accessible, or agent-facing.
- Search path allowlists and permission maps before adding a route. Never make
  an endpoint public merely to make a request succeed.
- Preserve the response conventions in `internal/routers/base`. Do not expose
  raw database, filesystem, command, provider, or secret errors to clients.

## Implement the complete contract

- Use the appropriate HTTP method. Mutating operations must not use `GET`.
- Bind into an explicit request type, validate required fields and bounds, and
  reject unknown or dangerous input where the existing API pattern permits.
- Enforce authorization server-side before loading or mutating protected data.
  For resource ids, verify access to the resource rather than only validating
  that the caller is logged in.
- Use transactions for multi-write operations. Add an audit event for
  security-sensitive or administrative mutations following existing patterns.
- Update the frontend API wrapper and `src/types/api/api.d.ts` when the UI uses
  the endpoint. Keep backend and frontend field names/types aligned.
- Add both Chinese and English strings when user-visible text changes:
  backend `internal/modules/i18n/{zh_cn,en_us}.go`, frontend
  `src/locales/langs/{zh,en}.json`.
- Update `docs/zh/guide/api.md` for a public API contract. Include auth,
  parameters, example response, error behavior, and compatibility impact.

## Test risk, not just success

Add focused tests for:

- valid requests and stable response shape;
- missing, malformed, boundary, and nonexistent-resource input;
- unauthenticated and unauthorized callers;
- ownership or tenant boundary where applicable;
- duplicate submissions or retry behavior for mutations;
- secret/error redaction for sensitive endpoints.
- `N-1` requests/responses and both frontend/backend deployment orders when
  the feature crosses that boundary.

Run the changed router package with race detection, then relevant service/model
tests. Run frontend type checking when the contract is consumed by the UI.
Finally invoke `$verify` before committing.

Report the route and method, authorization class, contract changes, backward
compatibility, tests added, performance evidence when relevant, and any
documentation or i18n files intentionally left unchanged.