RequestDto 与 ResponseDto

每个后端 API 的请求体与响应都必须使用 @quan-erp/shared-backend-core 的 RequestDto<T> 与 ResponseDto<T>。禁止返回原始载荷或接收未包装的 @Body。

概述

统一信封：payload + status + message + referenceId。控制器读取 body.payload，并用 ResponseDto.ok / okWithEmpty / error 返回。

后端 — @quan-erp/shared-backend-core
前端 — @quan-erp/shared-frontend-core（简化类型）
不要返回原始实体或接受裸 DTO

1. ResponseDto<T>

成功与错误共用同一信封。

ResponseDto.ok — 成功并带 payload
ResponseDto.okWithEmpty — 成功且 payload 为 null
ResponseDto.error — 错误信封

字段	类型	说明
timestamp	string	ISO 时间
status	"success" \| "error"	结果标志
message	string?	面向用户的消息
code	HttpStatus?	可选错误 HTTP 状态
referenceId	string	日志 / 支持追踪 UUID
payload	T	实际数据

TSXcontroller responses

import {
  Delete,
  Get,
  HttpStatus,
  Post,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

@Get("/profile")
async getProfile() {
  const profile = await this.service.getProfile();
  return ResponseDto.ok(profile);
}

@Delete("/history/:id")
async deleteHistory() {
  await this.service.delete(/* … */);
  return ResponseDto.okWithEmpty();
}

@Post("/update")
async update() {
  try {
    return ResponseDto.ok(
      { success: true },
      { message: "Profile updated successfully" },
    );
  } catch {
    return ResponseDto.error(
      "Failed to update profile",
      HttpStatus.INTERNAL_SERVER_ERROR,
    );
  }
}

2. RequestDto<T>

@Body() 期望 RequestDto<T>；从 body.payload 读取真实 DTO。

TSXrequest body

import { Body, Post, RequestDto } from "@quan-erp/shared-backend-core";

@Post("/calculate")
async calculate(@Body() body: RequestDto<LoanCalculationDto>) {
  const data = body.payload;
  return ResponseDto.ok(await this.service.calculate(data));
}

3. 前端配对

客户端用 new RequestDto(dto) 包装，将 response.data 转为 ResponseDto<T>，检查 status 后返回 payload。

POST/PUT — RequestDto 包装
status === "error" 时抛错
GET fetchFn — 只返回 payload
见前端 → Platform APIs → RequestDto & ResponseDto