eliteforge-rust-fe-consensus-spec

EliteForge Rust Frontend-Backend Consensus Specification

§0 Goals

ß Used for interface design, interface review, Axum handler/client implementation, and locating integration issues. Once this skill is triggered, the following rules are mandatory constraints and must not be downgraded to suggestions. If rules conflict, communicate and confirm promptly.

§1 How to Use

When designing an interface, first determine the HTTP method, URL, request DTO, VO, status code, error code, response body, pagination, and internationalization contract, then write the code.
When reviewing an interface, point out violations item by item according to this document and annotate the section number.

§2 Development Consensus

§2.1 Serialization

The fields of interface request parameters and responses must use camelCase JSON

§2.1.1 Time Fields

All interfaces use Unix millisecond timestamps for interaction, and JSON uses number.
The frontend formats the display according to business needs and time zone.

§2.1.2 Enum Fields

Enum protocol values in JSON use PascalCase, for example StreamableHttp
Published enum protocol values must not be modified arbitrarily

§2.1.3 64-bit Integer Precision

The JSON representation is not determined uniformly by Rust type, and it is forbidden to serialize all i64、u64 globally as strings.
Snowflake IDs and other primary keys, foreign keys, and related IDs that may exceed the JavaScript safe integer range ±(2^53 - 1) uniformly use decimal strings in requests and responses; Rust DTO/VO uses String, and after validation at the protocol boundary it is converted to the domain layer i64。
Values that can be guaranteed to be within the JavaScript safe integer range, such as Unix millisecond timestamps, pagination parameters, and quantities, use JSON number.
Open interfaces /open-api/** are forbidden to serialize i64、u64 as strings; keep the original type.

§2.1.4 No Data for Fields

For application/json request bodies and response bodies:

Fields must all appear as JSON properties; omission is forbidden.
The property of a nullable single-value field must exist in JSON, and the value may be null。
When a collection field has no data, the array returns [], and the key-value object returns {}; null must not be used or the field omitted.
The frontend must be compatible with null、[] and {}。

§2.2 Request Methods

Use standard Restful style
GET requests are forbidden from carrying a request body

§2.3 Request URL

URL words use kebab-case, for example /get-unique-data。

§2.4 Request Content

Each request uses an independent request DTO; cross-interface reuse is forbidden.
Request DTOs must not simulate inheritance through composition or traits unless necessary.
Request DTOs are forbidden from having redundant or useless fields.
GET requests are forbidden from passing List.
More than three parameters must use POST Request Body.
The Request Body size must be controlled, and Axum and reverse proxy limits must be considered at the same time.
Pagination request parameters are uniformly current、size。

§2.5 Response Content

Each interface uses an independent VO; returning domain models or database entities directly is prohibited, and VOs of other interfaces must not be reused.
VOs must not simulate inheritance through composition or traits unless necessary.
VOs must not contain redundant or useless fields.
Axum handlers uniformly return Json<ApiResponse<T>> or Result<Json<ApiResponse<T>>, ApiError>; manually writing response shells is prohibited.
Only when the interface call succeeds is the HTTP status code 200;ApiError statuses such as 400, 401, 403, 404, 409, 500, and 502 are uniformly mapped according to error semantics.
Service success and failure use different error codes; error codes must conform to the service status code specification and be returned as a JSON string.
0 represents a successful request.
-1 represents a system exception or unknown exception.
In other cases, return a 9-digit error code: digits 1-3 are the unique product identifier, digits 4-6 are the unique service identifier, and digits 7-9 are the project-defined numeric value; project-defined numeric values must not be duplicated, start from 1 and increase, with leading zeros.
Application errors are maintained uniformly through ApplicationErrorDescriptor with a unique code and the real message_key; the HTTP status and localized text are mapped by the protocol adapter, and storing Chinese and English text in the descriptor is prohibited.
The unified response body must be code、message、data; for error responses, data uses an empty object {}。
For list responses, data is an array; for single-object responses, data is an object; for paginated responses, data uses PageData<T>, containing current、size、total、records; switching to pagination response Headers is prohibited.

List response:

{
  "code": "0",
  "message": "响应消息",
  "data": []
}

Single-object response:

{
  "code": "0",
  "message": "响应消息",
  "data": {}
}

Paginated response:

{
  "code": "0",
  "message": "响应消息",
  "data": {
    "current": 1,
    "size": 20,
    "total": 0,
    "records": []
  }
}

§2.6 Internationalization

Use the standard Accept-Language Header to switch languages.
The Header value format is <语言代码>-<国家或地区代码>, using hyphens, for example zh-CN、en-US; in the current project, en* uses English; missing or unsupported values default to Chinese.
For internationalization on both the frontend and backend, use i18n keys, which must express stable business semantics, for example eliteforge.index.workspace.not_found；

Output Constraints

When designing or reviewing interfaces, this specification must be explicitly applied, and the section number must be indicated.
For clauses of the "prohibited" and "must" type, give a clear conclusion, and do not use weakening wording such as "it is suggested that it can".
Do not extend unified response body fields on your own; put business extensions in data。
For scenarios not covered by the specification, mark "requires user supplement or external confirmation".