refactor: 收敛公开工作区运行时契约

This commit is contained in:
que01 committed 2026-09-25 12:19:20 +08:00
1 parent d5e63be074
commit 9b61047ec6
13 files changed
+93 -64

No files matched your search

@@ -0,0 +1,18 @@
# 进度
- 任务:public/workspace 契约加固
- 形态:single-full
- 进度:4/4
- 当前:唯一 Runtime Workspace 契约已落地,等待提交
- 真相文件:`TODO.csv`
## 审计结论
当前接口同时返回 Runtime 投影和原始/重复别名:`fields`、`trustContent`、`inquiryForm`、`runtimeCapabilities`、`runtimeModules`。这些字段与 `inquiryForms`、`trustPresentation`、`capabilities`、`modules` 重叠,会使模板消费者误读历史数据。
## 已完成
- `/public/workspace` 只返回 canonical Runtime Workspace 字段。
- Miniapp 已移除 `workspace.fields` 和 `workspace.trustContent` fallback。
- API client 类型与 API 回归断言已同步。
- 验证:全仓 `typecheck`、`format:check`、Miniapp fixture 通过;API integration 36/37,剩余失败是既有测试用例共享品牌草稿状态导致的发布 400,与本轮 workspace 契约断言无关。
@@ -0,0 +1,17 @@
# public/workspace 契约加固
## 目标
让 `/public/workspace` 只返回已发布品牌的单一 Runtime Workspace 契约,移除原始 Prisma 字段和重复别名,避免模板与小程序混用历史数据结构。
## 范围
- 以 `RuntimeWorkspace` 作为公开响应的唯一业务数据模型。
- 保留模板渲染所需的模板元数据和视觉 manifest,但不返回数据库原始实体。
- 更新 Miniapp、共享类型和 API 集成测试。
- 验证草稿不会进入公开接口,品牌数据不会串租户。
## 非目标
- 不新增模板或行业字段。
- 不改变发布快照的数据库存储结构。
@@ -0,0 +1,5 @@
id,task,status,acceptance_criteria,validation_command,completed_at,retry_count,notes
1,定义唯一公开 Runtime Workspace 契约,DONE,响应类型不包含原始 Prisma 重复字段,pnpm --filter @personal-brand/types typecheck,2026-09-25,0,RuntimeWorkspace 成为唯一业务数据模型
2,迁移 API 与 Miniapp 消费者,DONE,小程序只读取 canonical 字段,pnpm --filter @personal-brand/miniapp test:fixture,2026-09-25,0,移除历史字段 fallback
3,补齐 API 隔离与发布回归测试,DONE,三品牌和草稿隔离测试通过,pnpm --filter @personal-brand/api test:integration,2026-09-25,0,契约相关断言通过;全套 36/37,剩余用例为既有发布状态共享失败
4,格式类型检查与记录结果,DONE,format/typecheck 通过并更新 PROGRESS.md,pnpm format:check && pnpm typecheck,2026-09-25,0,全仓 typecheck 与 format 通过
1 id task status acceptance_criteria validation_command completed_at retry_count notes
2 1 定义唯一公开 Runtime Workspace 契约 DONE 响应类型不包含原始 Prisma 重复字段 pnpm --filter @personal-brand/types typecheck 2026-09-25 0 RuntimeWorkspace 成为唯一业务数据模型
3 2 迁移 API 与 Miniapp 消费者 DONE 小程序只读取 canonical 字段 pnpm --filter @personal-brand/miniapp test:fixture 2026-09-25 0 移除历史字段 fallback
4 3 补齐 API 隔离与发布回归测试 DONE 三品牌和草稿隔离测试通过 pnpm --filter @personal-brand/api test:integration 2026-09-25 0 契约相关断言通过;全套 36/37,剩余用例为既有发布状态共享失败
5 4 格式类型检查与记录结果 DONE format/typecheck 通过并更新 PROGRESS.md pnpm format:check && pnpm typecheck 2026-09-25 0 全仓 typecheck 与 format 通过
@@ -46,12 +46,7 @@ export class PublicWorkspaceController {
offerings: [],
inquiryForms: [],
capabilities: [],
runtimeCapabilities: [],
runtimeModules: [],
fields: [],
trustContent: [],
trustPresentation: {},
inquiryForm: null,
navigation: { tabs: [] },
plugins: [],
theme: { colors: {} },
@@ -61,9 +56,6 @@ export class PublicWorkspaceController {
const modulesData = this.jsonArray(releaseSnapshot.modules).filter(
(item) => this.jsonObject(item).isEnabled === true,
) as Array<Record<string, unknown>>;
const fieldsData = this.jsonArray(releaseSnapshot.fields).filter(
(item) => this.jsonObject(item).isVisible === true,
);
const offeringsData = this.jsonArray(releaseSnapshot.offerings).filter(
(item) => this.jsonObject(item).isEnabled === true,
) as Array<Record<string, unknown>>;
@@ -265,7 +257,6 @@ export class PublicWorkspaceController {
},
];
});
const inquiryForm = formsData[0] ?? null;
const trustPresentation = trustData.reduce<Record<string, unknown>>((result, raw) => {
const item = this.jsonObject(raw);
const config = this.jsonObject(item.config);
@@ -350,13 +341,6 @@ export class PublicWorkspaceController {
}
: null,
visualTemplateManifest,
capabilities: runtimeCapabilities,
runtimeCapabilities,
runtimeModules,
fields: fieldsData,
trustContent: trustData,
trustPresentation,
inquiryForm,
};
return response;
}
+13 -10
View File
@@ -8,6 +8,7 @@ import { WechatAuthService } from "../dist/wechat-auth.js";
let app;
const prisma = new PrismaClient();
const brandId = process.env.DEFAULT_BRAND_ID;
const openid = `integration-${Date.now()}`;
let customerToken;
const createdBookingIds = [];
@@ -327,7 +328,7 @@ test("health and public content are available without authentication", async ()
assert.ok(Array.isArray(runtime.plugins));
assert.equal(runtime.brand.founder, "阿成");
assert.ok(runtime.offerings.every((item) => item.coverUrl));
assert.ok(runtime.trustContent.length > 0);
assert.ok(runtime.trustPresentation);
const bySlug = await request("/public/workspace?brandSlug=default-brand");
assert.equal(bySlug.statusCode, 200);
assert.equal(JSON.parse(bySlug.body).brand.id, brandId);
@@ -403,10 +404,8 @@ test("seeded public workspaces keep personal, food, and doors brands isolated",
assert.equal(workspace.navigation.tabs.length, item.templateKey === "food" ? 5 : 3);
assert.equal("templatePackageManifest" in workspace, false);
assert.equal(workspace.brand.founder, item.founder);
assert.ok(workspace.trustContent.length > 0);
assert.ok(workspace.trustPresentation);
assert.ok(workspace.inquiryForm);
assert.equal(workspace.inquiryForm.isEnabled, true);
assert.ok(workspace.inquiryForms.length > 0);
assert.ok(workspace.offerings.length > 0);
assert.ok(workspace.offerings.every((offering) => offering.brandId === undefined));
assert.ok(
@@ -443,7 +442,7 @@ test("public workspace uses brand-scoped capability installations and preserves
const response = await request("/public/workspace");
assert.equal(response.statusCode, 200);
const body = JSON.parse(response.body);
assert.deepEqual(body.runtimeCapabilities, [
assert.deepEqual(body.capabilities, [
{
key: "inquiry",
version: "1.0.0",
@@ -451,7 +450,7 @@ test("public workspace uses brand-scoped capability installations and preserves
config: { source: "integration-test" },
},
]);
assert.notEqual(body.runtimeCapabilities[0].status, "enabled");
assert.notEqual(body.capabilities[0].status, "enabled");
} finally {
await prisma.capabilityInstallation.delete({ where: { id: installation.id } });
}
@@ -831,10 +830,14 @@ test("admin can install a template and public workspace exposes enabled configur
assert.equal(workspaceBody.contractVersion, "1.0");
assert.equal(workspaceBody.template.key, "food");
assert.ok(workspaceBody.modules.length > 0);
assert.equal(workspaceBody.modules.length, workspaceBody.runtimeModules.length);
assert.equal("templateContent" in workspaceBody, false);
assert.equal(workspaceBody.runtimeModules[0].schemaVersion, "1.0");
assert.ok(workspaceBody.inquiryForm);
assert.equal("runtimeModules" in workspaceBody, false);
assert.equal("runtimeCapabilities" in workspaceBody, false);
assert.equal("fields" in workspaceBody, false);
assert.equal("trustContent" in workspaceBody, false);
assert.equal("inquiryForm" in workspaceBody, false);
assert.equal(workspaceBody.modules[0].schemaVersion, "1.0");
assert.ok(workspaceBody.inquiryForms.length > 0);
const conflict = await request("/admin/workspace/install", {
method: "POST",
headers: { authorization: `Bearer ${token}` },
@@ -1087,7 +1090,7 @@ test("admin can create and version an inquiry form", async () => {
assert.equal(JSON.parse(publicOffering.body).inquiryForms[0].id, id);
const publicWorkspace = await request("/public/workspace");
assert.equal(publicWorkspace.statusCode, 200);
assert.equal(JSON.parse(publicWorkspace.body).inquiryForm.id, id);
assert.ok(JSON.parse(publicWorkspace.body).inquiryForms.some((form) => form.key === id));
assert.ok(
JSON.parse(publicWorkspace.body).inquiryForms.some(
(form) => form.key === id && form.targetId === offering.id,
+1 -1
View File
@@ -15,7 +15,7 @@ Page({
.then((workspace) =>
this.setData({
brand: workspace.brand || {},
trustContent: workspace.trustContent || [],
trustContent: workspace.trustPresentation || {},
pageRenderer: workspace.pageRenderers?.profile || "",
records: [],
templateKey: workspace.visualTemplate?.key || "",
+1 -1
View File
@@ -44,7 +44,7 @@ Page({
: {};
this.setData({
brand: activeBrand,
trustContent: workspace.trustContent || [],
trustContent: workspace.trustPresentation || {},
offerings: activeOfferings,
modules: workspace.modules || [],
moduleVariants: workspace.moduleVariants || {},
+1 -1
View File
@@ -32,7 +32,7 @@ Page({
const presentation = workspace.brand?.visualPresentation?.inquiry || {};
this.setData({
offering,
fields: form?.fields || workspace.fields || [],
fields: form?.fields || [],
formId: form?.key || form?.id || "",
title: isQuote ? "获取报价方案" : presentation.title || "需求咨询",
eyebrow: isQuote ? "QUOTE REQUEST" : presentation.eyebrow || "CONSULTATION",
@@ -44,6 +44,19 @@ test("已发布 workspace 正常返回", async () => {
assert.equal(workspace.brand.name, "测试品牌");
});
test("运行时只消费 canonical workspace 字段", async () => {
const workspace = await loadWithResponse({
publication: { status: "published" },
brand: { name: "测试品牌" },
offerings: [],
trustPresentation: { bio: "品牌介绍" },
inquiryForms: [],
});
assert.deepEqual(workspace.trustContent, { bio: "品牌介绍" });
assert.equal(workspace.fields, undefined);
assert.equal(workspace.inquiryForm, undefined);
});
test("模板声明的业务提供项展示字段会保留在小程序 view model", async () => {
const workspace = await loadWithResponse({
publication: { status: "published" },
+21 -32
View File
@@ -5,6 +5,11 @@ import type {
FulfillmentType,
PublicOffering,
BrandTemplateKey,
RuntimeCapability,
RuntimeInquiryForm,
RuntimeModule,
RuntimeOffering,
ThemeManifest,
} from "@personal-brand/types";
export type { PublicOffering } from "@personal-brand/types";
export type { BookingStatus } from "@personal-brand/types";
@@ -273,19 +278,16 @@ export interface CapabilityInstallation {
source?: "template" | "brand";
}
export interface PublicWorkspace {
schemaVersion?: string;
navigation?: { tabs: Array<{ key: string; label: string; page: string }> };
theme?: {
colors: Record<string, string>;
typography?: Record<string, string>;
spacing?: Record<string, string>;
radius?: Record<string, string>;
};
layout?: { home: string[]; offerings: string[]; detail: string[]; profile: string[] };
schemaVersion: string;
contractVersion: string;
brand: BrandProfile | null;
publication: {
status: "published" | "unpublished";
version: number | null;
publishedAt?: string;
};
brand: (BrandProfile & Record<string, unknown>) | null;
template: { key: BrandTemplateKey; version: string; name: string } | null;
visualTemplate?: {
visualTemplate: {
key: string;
version: string;
name: string;
@@ -322,27 +324,14 @@ export interface PublicWorkspace {
dataSlots: Array<Record<string, unknown>>;
capabilities: string[];
};
capabilities: string[];
modules: BrandModule[];
runtimeModules: Array<{
key: string;
type: string;
version?: string;
propsSchema?: string;
dataSource?: string;
source?: string;
title?: string;
schemaVersion?: string;
sortOrder?: number;
config?: Record<string, unknown> | null;
}>;
fields: BrandFieldDefinition[];
offerings: Offering[];
inquiryForm: InquiryForm | null;
runtimeOfferings?: Array<Record<string, unknown>>;
inquiryForms?: Array<Record<string, unknown>>;
trustPresentation?: Record<string, unknown>;
runtimeCapabilities?: Array<{ key: string; version: string; status?: string }>;
capabilities: RuntimeCapability[];
modules: RuntimeModule[];
offerings: RuntimeOffering[];
inquiryForms: RuntimeInquiryForm[];
navigation: { tabs: Array<{ key: string; label: string; page: string }> };
trustPresentation: Record<string, unknown>;
theme: ThemeManifest;
layout?: { home: string[]; offerings: string[]; detail: string[]; profile: string[] };
plugins?: Array<{
key: string;
version: string;
@@ -13,7 +13,7 @@ Page({
.then((workspace) =>
this.setData({
brand: workspace.brand || {},
trustContent: workspace.trustContent || [],
trustContent: workspace.trustPresentation || {},
records: [],
navigation: workspace.navigation || [],
}),
@@ -8,7 +8,7 @@ Page({
this.setData({
brand: workspace.brand || {},
presentation: workspace.brand?.visualPresentation?.home || {},
trustContent: workspace.trustContent || [],
trustContent: workspace.trustPresentation || {},
offerings: workspace.offerings || [],
}),
)
+1 -1
View File
@@ -160,7 +160,7 @@ export function validateTemplatePackageManifest(value: unknown): string[] {
}
if (manifest.sampleContent !== undefined) {
for (const [industryKey, sample] of Object.entries(manifest.sampleContent)) {
if (!manifest.supportedIndustryTemplates.includes(industryKey))
if (!manifest.supportedIndustryTemplates?.includes(industryKey))
errors.push(`sampleContent.${industryKey} is not a supported industry template`);
if (sample.templateKey !== industryKey)
errors.push(`sampleContent.${industryKey}.templateKey must match its key`);