feat: 接通后台渲染异常上报与响应契约校验

This commit is contained in:
que01 committed 2026-10-21 11:43:41 +08:00
1 parent 330d67adc1
commit adcaa12970
22 files changed
+845 -33

No files matched your search

+2 -1
View File
@@ -15,6 +15,7 @@
"clean": "rimraf dist"
},
"dependencies": {
"@personal-brand/types": "workspace:*"
"@personal-brand/types": "workspace:*",
"zod": "^3.25.0"
}
}
+39 -5
View File
@@ -1,3 +1,4 @@
import type { ZodType } from "zod";
import type { ApiErrorBody } from "../types/common.js";
export interface FetchResponse {
@@ -17,15 +18,20 @@ export interface ApiClientOptions {
token?: string;
}
export type RequestFn = <T>(
path: string,
options?: { method?: string; body?: unknown; rawBody?: unknown },
) => Promise<T>;
export interface RequestOptions {
method?: string;
body?: unknown;
rawBody?: unknown;
/** 响应体的运行时契约;不匹配时抛出 ApiClientContractError,而不是把脏数据交给页面。 */
expect?: ZodType<unknown>;
}
export type RequestFn = <T>(path: string, options?: RequestOptions) => Promise<T>;
export async function request<T>(
state: { baseUrl: string; fetcher: FetchLike; token?: string | undefined },
path: string,
options: { method?: string; body?: unknown; rawBody?: unknown } = {},
options: RequestOptions = {},
): Promise<T> {
const headers: Record<string, string> = { accept: "application/json" };
if (options.rawBody === undefined && options.body !== undefined)
@@ -48,9 +54,37 @@ export async function request<T>(
)(`${state.baseUrl}${path}`, init);
const body = await response.json();
if (!response.ok) throw new ApiClientError(response.status, body as ApiErrorBody);
if (options.expect) assertResponseContract(options.expect, body, path);
return body as T;
}
/** 接口返回结构不符合客户端契约:携带请求路径与首个校验问题,方便定位。 */
export class ApiClientContractError extends Error {
constructor(
readonly path: string,
readonly issues: string[],
) {
super(`接口返回数据结构不符合契约:${path}${issues.length > 0 ? `(${issues[0]})` : ""}`);
this.name = "ApiClientContractError";
}
}
export function assertResponseContract(
schema: ZodType<unknown>,
value: unknown,
path: string,
): void {
const result = schema.safeParse(value);
if (result.success) return;
throw new ApiClientContractError(
path,
result.error.issues.map((issue) => {
const location = issue.path.length > 0 ? issue.path.join(".") + ":" : "";
return location + issue.message;
}),
);
}
export class ApiClientError extends Error {
constructor(
readonly status: number,
+20 -7
View File
@@ -1,5 +1,15 @@
export { ApiClientError } from "./client/request.js";
export type { ApiClientOptions, FetchLike, FetchResponse, RequestFn } from "./client/request.js";
export {
ApiClientContractError,
ApiClientError,
assertResponseContract,
} from "./client/request.js";
export type {
ApiClientOptions,
FetchLike,
FetchResponse,
RequestFn,
RequestOptions,
} from "./client/request.js";
export type {
AdminBooking,
Booking,
@@ -66,7 +76,11 @@ export const apiClientName = "personal-brand-api-client";
import { bookingMethods } from "./resources/booking.js";
import { brandMethods } from "./resources/brand.js";
import { request as createRequest, type ApiClientOptions } from "./client/request.js";
import {
request as createRequest,
type ApiClientOptions,
type RequestFn,
} from "./client/request.js";
import { inquiryMethods } from "./resources/inquiry.js";
import { mediaMethods } from "./resources/media.js";
import { offeringMethods } from "./resources/offering.js";
@@ -103,10 +117,7 @@ export class ApiClient
TrustMethods
{
private readonly state: ClientState;
private readonly requestFn: <T>(
path: string,
options?: { method?: string; body?: unknown; rawBody?: unknown },
) => Promise<T>;
private readonly requestFn: RequestFn;
private resources!: {
booking: BookingMethods;
brand: BrandMethods;
@@ -172,6 +183,8 @@ export class ApiClient
this.resources.session.logoutAdmin(...arguments_);
logoutCustomer = (...arguments_: Parameters<SessionMethods["logoutCustomer"]>) =>
this.resources.session.logoutCustomer(...arguments_);
reportAdminClientError = (...arguments_: Parameters<SessionMethods["reportAdminClientError"]>) =>
this.resources.session.reportAdminClientError(...arguments_);
listCustomerBookings = (...arguments_: Parameters<BookingMethods["listCustomerBookings"]>) =>
this.resources.booking.listCustomerBookings(...arguments_);
createCustomerBooking = (...arguments_: Parameters<BookingMethods["createCustomerBooking"]>) =>
+5 -2
View File
@@ -1,5 +1,6 @@
import type { BookingStatus } from "@personal-brand/types";
import type { RequestFn } from "../client/request.js";
import { adminBookingListSchema, adminBookingTagListSchema } from "../schemas/admin-collections.js";
import type {
AdminBooking,
Booking,
@@ -38,7 +39,9 @@ export function bookingMethods({ request }: { request: RequestFn }): BookingMeth
if (filters.unreadOnly !== undefined) params.push(`unreadOnly=${filters.unreadOnly}`);
if (filters.tagId) params.push(`tagId=${encodeURIComponent(filters.tagId)}`);
const query = params.join("&");
return request(`/admin/bookings${query ? `?${query}` : ""}`);
return request(`/admin/bookings${query ? `?${query}` : ""}`, {
expect: adminBookingListSchema,
});
},
getAdminBooking: (id) => request(`/admin/bookings/${encodeURIComponent(id)}`),
getAdminUnreadCount: () => request("/admin/bookings/unread-count"),
@@ -49,7 +52,7 @@ export function bookingMethods({ request }: { request: RequestFn }): BookingMeth
}),
markAdminBookingRead: (id) =>
request(`/admin/bookings/${encodeURIComponent(id)}/read`, { method: "POST" }),
listAdminTags: () => request("/admin/bookings/tags"),
listAdminTags: () => request("/admin/bookings/tags", { expect: adminBookingTagListSchema }),
createAdminTag: (name) => request("/admin/bookings/tags", { method: "POST", body: { name } }),
};
}
+12 -4
View File
@@ -1,4 +1,10 @@
import type { RequestFn } from "../client/request.js";
import {
adminBrandMemberListSchema,
adminBrandMembershipListSchema,
adminMiniAppReleaseListSchema,
adminReleaseListSchema,
} from "../schemas/admin-collections.js";
import type {
AdminBrandMember,
AdminBrandMembership,
@@ -80,12 +86,13 @@ export interface BrandMethods {
export function brandMethods({ request }: { request: RequestFn }): BrandMethods {
return {
getAdminBrand: () => request("/admin/config/brand"),
listAdminBrands: () => request("/admin/brands"),
listAdminBrands: () => request("/admin/brands", { expect: adminBrandMembershipListSchema }),
getAdminBrandCreationOptions: () => request("/admin/brands/creation-options"),
createAdminBrand: (body) => request("/admin/brands", { method: "POST", body }),
switchAdminBrand: (brandId) =>
request(`/admin/brands/${encodeURIComponent(brandId)}/switch`, { method: "POST" }),
listAdminMembers: () => request("/admin/brands/members"),
listAdminMembers: () =>
request("/admin/brands/members", { expect: adminBrandMemberListSchema }),
createAdminMember: (body) => request("/admin/brands/members", { method: "POST", body }),
updateAdminMember: (id, body) =>
request(`/admin/brands/members/${encodeURIComponent(id)}`, {
@@ -95,7 +102,7 @@ export function brandMethods({ request }: { request: RequestFn }): BrandMethods
updateAdminBrand: (body) => request("/admin/config/brand", { method: "PATCH", body }),
updateAdminBrandPresentation: (body) =>
request("/admin/config/presentation", { method: "PATCH", body }),
listAdminReleases: () => request("/admin/releases"),
listAdminReleases: () => request("/admin/releases", { expect: adminReleaseListSchema }),
getAdminReleaseReadiness: () => request("/admin/releases/readiness"),
publishAdminRelease: (note) =>
request("/admin/releases/publish", {
@@ -108,7 +115,8 @@ export function brandMethods({ request }: { request: RequestFn }): BrandMethods
body: note === undefined ? {} : { note },
}),
revokeAdminRelease: () => request("/admin/releases/revoke", { method: "POST" }),
listAdminMiniAppReleases: () => request("/admin/miniapp-releases"),
listAdminMiniAppReleases: () =>
request("/admin/miniapp-releases", { expect: adminMiniAppReleaseListSchema }),
getLatestAdminMiniAppRelease: () => request("/admin/miniapp-releases/latest"),
createAdminMiniAppRelease: (releaseId) =>
request("/admin/miniapp-releases", {
+8 -2
View File
@@ -1,4 +1,8 @@
import type { RequestFn } from "../client/request.js";
import {
adminInquiryFormListSchema,
adminInquirySubmissionListSchema,
} from "../schemas/admin-collections.js";
import type { BrandFieldDefinition } from "../types/field.js";
import type { InquiryForm, InquirySubmission } from "../types/inquiry.js";
@@ -42,8 +46,10 @@ export function inquiryMethods({ request }: { request: RequestFn }): InquiryMeth
createAdminField: (body) => request("/admin/workspace/fields", { method: "POST", body }),
deleteAdminField: (id) =>
request(`/admin/workspace/fields/${encodeURIComponent(id)}`, { method: "DELETE" }),
listAdminInquiryForms: () => request("/admin/workspace/forms"),
listAdminInquirySubmissions: () => request("/admin/workspace/submissions"),
listAdminInquiryForms: () =>
request("/admin/workspace/forms", { expect: adminInquiryFormListSchema }),
listAdminInquirySubmissions: () =>
request("/admin/workspace/submissions", { expect: adminInquirySubmissionListSchema }),
updateAdminInquirySubmission: (id, body) =>
request(`/admin/workspace/submissions/${encodeURIComponent(id)}`, {
method: "PATCH",
@@ -1,4 +1,5 @@
import type { RequestFn } from "../client/request.js";
import { adminOfferingListSchema } from "../schemas/admin-collections.js";
import type { Offering } from "../types/offering.js";
export interface OfferingMethods {
@@ -17,7 +18,8 @@ export function offeringMethods({ request }: { request: RequestFn }): OfferingMe
return {
getPublicOffering: (id) => request(`/public/offerings/${encodeURIComponent(id)}`),
listPublicOfferings: () => request("/public/offerings"),
listAdminOfferings: () => request("/admin/workspace/offerings"),
listAdminOfferings: () =>
request("/admin/workspace/offerings", { expect: adminOfferingListSchema }),
createAdminOffering: (body) => request("/admin/workspace/offerings", { method: "POST", body }),
updateAdminOffering: (id, body) =>
request(`/admin/workspace/offerings/${encodeURIComponent(id)}`, {
@@ -16,6 +16,12 @@ export interface SessionMethods {
changeAdminPassword(currentPassword: string, newPassword: string): Promise<{ changed: true }>;
logoutAdmin(): Promise<{ loggedOut: true }>;
logoutCustomer(): Promise<{ loggedOut: true }>;
reportAdminClientError(input: {
errorId: string;
message: string;
route: string;
componentStack?: string;
}): Promise<{ received: true; duplicate: boolean }>;
}
export function sessionMethods({ request }: { request: RequestFn }): SessionMethods {
@@ -30,5 +36,7 @@ export function sessionMethods({ request }: { request: RequestFn }): SessionMeth
}),
logoutAdmin: () => request("/admin/session/logout", { method: "POST", body: {} }),
logoutCustomer: () => request("/customer/session/logout", { method: "POST", body: {} }),
reportAdminClientError: (input) =>
request("/admin/client-errors", { method: "POST", body: input }),
};
}
+15 -3
View File
@@ -1,5 +1,11 @@
import type { BrandTemplateKey, RuntimeWorkspace } from "@personal-brand/types";
import type { RequestFn } from "../client/request.js";
import {
adminCapabilityListSchema,
adminTemplateOperationFailuresSchema,
adminTemplatePackageAuditListSchema,
adminTemplatePackageListSchema,
} from "../schemas/admin-collections.js";
import type { BrandPageSchemeOptions, BrandProfile } from "../types/brand.js";
import type { CapabilityWithMetadata } from "../types/capability.js";
import type { BrandFieldDefinition } from "../types/field.js";
@@ -319,7 +325,9 @@ export function templateMethods({ request }: { request: RequestFn }): TemplateMe
? null
: `pageSize=${encodeURIComponent(String(params.pageSize))}`,
].filter((item): item is string => item !== null);
return request(`/admin/templates${query.length ? `?${query.join("&")}` : ""}`);
return request(`/admin/templates${query.length ? `?${query.join("&")}` : ""}`, {
expect: adminTemplatePackageListSchema,
});
},
importAdminTemplatePackage: (body) =>
request("/admin/templates/import", { method: "POST", rawBody: body }),
@@ -328,7 +336,9 @@ export function templateMethods({ request }: { request: RequestFn }): TemplateMe
retireAdminTemplatePackage: (id) =>
request(`/admin/templates/${encodeURIComponent(id)}/retire`, { method: "POST" }),
listAdminTemplatePackageAudit: (id) =>
request(`/admin/templates/${encodeURIComponent(id)}/audit`),
request(`/admin/templates/${encodeURIComponent(id)}/audit`, {
expect: adminTemplatePackageAuditListSchema,
}),
previewAdminTemplatePackage: (id, industry, session) =>
request(
`/admin/templates/${encodeURIComponent(id)}/preview?industry=${encodeURIComponent(industry)}${session ? `&session=${encodeURIComponent(session)}` : ""}`,
@@ -383,7 +393,8 @@ export function templateMethods({ request }: { request: RequestFn }): TemplateMe
}),
selectAdminTemplateVersion: (input) =>
request("/admin/workspace/template/select-version", { method: "POST", body: input }),
listAdminCapabilities: () => request("/admin/workspace/capabilities"),
listAdminCapabilities: () =>
request("/admin/workspace/capabilities", { expect: adminCapabilityListSchema }),
updateAdminCapability: (key, body) =>
request(`/admin/workspace/capabilities/${encodeURIComponent(key)}`, {
method: "PATCH",
@@ -409,6 +420,7 @@ export function templateMethods({ request }: { request: RequestFn }): TemplateMe
getAdminTemplateOperationFailures: (params = {}) =>
request(
`/admin/template-operations/failures${params.days === undefined ? "" : `?days=${encodeURIComponent(String(params.days))}`}`,
{ expect: adminTemplateOperationFailuresSchema },
),
};
}
+3 -1
View File
@@ -1,4 +1,5 @@
import type { RequestFn } from "../client/request.js";
import { adminTrustContentListSchema } from "../schemas/admin-collections.js";
import type { TrustContent, TrustContentInput } from "../types/trust.js";
export interface TrustMethods {
@@ -10,7 +11,8 @@ export interface TrustMethods {
export function trustMethods({ request }: { request: RequestFn }): TrustMethods {
return {
listAdminTrustContent: () => request("/admin/config/trust-content"),
listAdminTrustContent: () =>
request("/admin/config/trust-content", { expect: adminTrustContentListSchema }),
createAdminTrustContent: (body) =>
request("/admin/config/trust-content", { method: "POST", body }),
updateAdminTrustContent: (id, body) =>
@@ -0,0 +1,199 @@
import { z } from "zod";
/**
* Admin 列表接口的运行时契约。
*
* 这些 schema 只用于校验,不参与数据转换:请求层在通过校验后返回原始响应体,
* 因此新增字段不会被裁剪。缺少关键字段或字段类型错误时抛出 ApiClientContractError,
* 由页面已有的错误态展示,而不是让 React 在渲染阶段崩溃。
*/
const record = z.record(z.string(), z.unknown());
const nullableText = z.string().nullish();
export const adminBrandMembershipListSchema = z.array(
z.object({
id: z.string(),
role: z.string(),
brand: z.object({
id: z.string(),
name: z.string(),
slug: z.string(),
templateKey: z.string(),
}),
}),
);
export const adminBrandMemberListSchema = z.array(
z.object({
id: z.string(),
role: z.string(),
isEnabled: z.boolean(),
adminUser: z.object({
id: z.string(),
username: z.string(),
displayName: z.string(),
isEnabled: z.boolean(),
}),
}),
);
export const adminReleaseListSchema = z.array(
z.object({
id: z.string(),
version: z.number(),
status: z.string(),
actorId: z.string(),
createdAt: z.string(),
note: nullableText,
revokedAt: nullableText,
}),
);
export const adminMiniAppReleaseListSchema = z.array(
z.object({
id: z.string(),
version: z.number(),
status: z.enum([
"built",
"uploaded",
"under_review",
"rejected",
"approved",
"published",
"failed",
]),
createdAt: z.string(),
updatedAt: z.string(),
}),
);
export const adminTrustContentListSchema = z.array(
z.object({
id: z.string(),
type: z.string(),
title: z.string(),
content: z.string(),
sortOrder: z.number(),
isPublished: z.boolean(),
summary: nullableText,
coverUrl: nullableText,
config: record.nullish(),
}),
);
export const adminOfferingListSchema = z.array(
z.object({
id: z.string(),
kind: z.enum(["service", "product", "package", "subscription"]),
name: z.string(),
isEnabled: z.boolean(),
sortOrder: z.number(),
}),
);
export const adminInquiryFormListSchema = z.array(
z.object({
id: z.string(),
name: z.string(),
version: z.number(),
isEnabled: z.boolean(),
fieldsSnapshot: z.array(z.unknown()),
purpose: z.enum(["inquiry", "booking", "quote-request"]),
targetType: z.enum(["brand", "offering"]),
submissionAction: z.enum(["create-inquiry", "create-booking", "create-quote"]),
}),
);
export const adminInquirySubmissionListSchema = z.array(
z.object({
id: z.string(),
inquiryFormId: z.string(),
formVersion: z.number(),
fieldsSnapshot: z.array(z.unknown()),
values: record,
activeFields: record,
createdAt: z.string(),
status: z.enum(["new", "reviewing", "replied", "qualified", "converted", "closed"]),
}),
);
export const adminBookingListSchema = z.array(
z.object({
id: z.string(),
bookingNo: z.string(),
status: z.enum(["received", "contacting", "confirmed", "completed", "cancelled"]),
estimatedAmount: z.number().nullable(),
createdAt: z.string(),
customerName: z.string(),
}),
);
export const adminBookingTagListSchema = z.array(
z.object({
id: z.string(),
name: z.string(),
isPreset: z.boolean(),
isEnabled: z.boolean(),
}),
);
export const adminCapabilityListSchema = z.array(
z.object({
id: z.string().nullable(),
capabilityKey: z.string(),
capabilityVersion: z.string(),
status: z.enum(["enabled", "disabled", "degraded"]),
updatedAt: z.string().nullable(),
}),
);
const templatePackageVersionSchema = z.object({
id: z.string(),
templatePackageId: z.string(),
packageKey: z.string(),
version: z.string(),
displayName: z.string(),
status: z.enum(["imported", "published", "retired", "disabled"]),
contentChecksum: z.string(),
archiveChecksum: z.string(),
importedAt: z.string(),
updatedAt: z.string(),
validationReport: record,
importedBy: z.object({
id: z.string(),
username: z.string(),
displayName: z.string(),
}),
});
export const adminTemplatePackageListSchema = z.object({
items: z.array(templatePackageVersionSchema),
page: z.number(),
pageSize: z.number(),
total: z.number(),
});
export const adminTemplatePackageAuditListSchema = z.array(
z.object({
id: z.string(),
action: z.string(),
fromStatus: z.enum(["imported", "published", "retired", "disabled"]).nullish(),
toStatus: z.enum(["imported", "published", "retired", "disabled"]).nullish(),
requestId: nullableText,
createdAt: z.string(),
actor: z.object({
id: z.string(),
username: z.string(),
displayName: z.string(),
}),
}),
);
export const adminTemplateOperationFailuresSchema = z.object({
since: z.string(),
until: z.string(),
days: z.number(),
backfilled: z.boolean(),
failures: z.array(z.object({ action: z.string(), count: z.number() })),
});
+119 -2
View File
@@ -1,6 +1,14 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { ApiClient, ApiClientError, type FetchResponse } from "../src/index.js";
import {
ApiClient,
ApiClientContractError,
ApiClientError,
assertResponseContract,
type FetchResponse,
} from "../src/index.js";
import { adminTrustContentListSchema } from "../src/schemas/admin-collections.js";
import { z } from "zod";
function response(body: unknown, status = 200): FetchResponse {
return { status, ok: status >= 200 && status < 300, json: async () => body };
@@ -14,7 +22,7 @@ test("客户端发送认证头、查询参数和 JSON 请求体", async () => {
token: "token-1",
fetcher: async (url, init) => {
calls.push({ url, init });
return response({ count: 2 });
return response(url.includes("/admin/bookings?") ? [] : { count: 2 });
},
});
await client.listAdminBookings({ status: "received", unreadOnly: true, tagId: "tag/1" });
@@ -303,3 +311,112 @@ test("模板运营失败指标客户端发送查询窗口", async () => {
{ url: "http://api.test/admin/template-operations/failures?days=14", method: "GET" },
]);
});
test("响应契约通过时保留原始数据,包含 schema 未声明的字段", async () => {
const body = [
{
id: "trust-1",
type: "credential",
title: "从业十年",
content: "长期服务本地客户",
sortOrder: 0,
isPublished: true,
summary: null,
coverUrl: null,
config: { sections: [] },
futureField: "保留",
},
];
const client = new ApiClient({
baseUrl: "http://api.test",
fetcher: async () => response(body),
});
const result = await client.listAdminTrustContent();
assert.deepEqual(result, body);
});
test("响应契约不匹配时抛出带接口路径的 ApiClientContractError", async () => {
const client = new ApiClient({
baseUrl: "http://api.test",
fetcher: async () => response([null]),
});
await assert.rejects(
() => client.listAdminTrustContent(),
(error: unknown) => {
assert.ok(error instanceof ApiClientContractError);
assert.equal(error.path, "/admin/config/trust-content");
assert.match(error.message, /\/admin\/config\/trust-content/);
assert.ok(error.issues.length > 0);
return true;
},
);
});
test("契约校验只接受对象数组且拒绝缺少关键字段的记录", () => {
assert.throws(
() =>
assertResponseContract(
z.array(z.object({ id: z.string() })),
[{ id: "ok" }, { id: 1 }],
"/admin/example",
),
(error: unknown) => {
assert.ok(error instanceof ApiClientContractError);
assert.match(error.issues[0] ?? "", /^1\.id:/);
return true;
},
);
assert.doesNotThrow(() =>
assertResponseContract(adminTrustContentListSchema, [], "/admin/config/trust-content"),
);
});
test("错误响应仍抛 ApiClientError,而不是契约错误", async () => {
const client = new ApiClient({
baseUrl: "http://api.test",
fetcher: async () =>
response(
{ data: null, error: { code: "HTTP_500", message: "服务异常" }, requestId: "req-2" },
500,
),
});
await assert.rejects(
() => client.listAdminTrustContent(),
(error: unknown) => {
assert.ok(error instanceof ApiClientError);
assert.equal(error instanceof ApiClientContractError, false);
return true;
},
);
});
test("后台渲染异常上报提交白名单字段", async () => {
const calls: Array<{ url: string; method?: string; body?: string }> = [];
const client = new ApiClient({
baseUrl: "http://api.test",
token: "brand-token",
fetcher: async (url, init) => {
calls.push({ url, method: init?.method, body: init?.body });
return response({ received: true, duplicate: false });
},
});
const receipt = await client.reportAdminClientError({
errorId: "admin-abc-123",
message: "boom",
route: "/admin/trust?tab=1",
componentStack: "at TrustContentPage",
});
assert.deepEqual(receipt, { received: true, duplicate: false });
assert.deepEqual(calls, [
{
url: "http://api.test/admin/client-errors",
method: "POST",
body: JSON.stringify({
errorId: "admin-abc-123",
message: "boom",
route: "/admin/trust?tab=1",
componentStack: "at TrustContentPage",
}),
},
]);
});