diff --git a/.codex-tasks/public-workspace-contract-hardening/PROGRESS.md b/.codex-tasks/public-workspace-contract-hardening/PROGRESS.md new file mode 100644 index 0000000..3e23bf5 --- /dev/null +++ b/.codex-tasks/public-workspace-contract-hardening/PROGRESS.md @@ -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 契约断言无关。 diff --git a/.codex-tasks/public-workspace-contract-hardening/SPEC.md b/.codex-tasks/public-workspace-contract-hardening/SPEC.md new file mode 100644 index 0000000..0e0d4d1 --- /dev/null +++ b/.codex-tasks/public-workspace-contract-hardening/SPEC.md @@ -0,0 +1,17 @@ +# public/workspace 契约加固 + +## 目标 + +让 `/public/workspace` 只返回已发布品牌的单一 Runtime Workspace 契约,移除原始 Prisma 字段和重复别名,避免模板与小程序混用历史数据结构。 + +## 范围 + +- 以 `RuntimeWorkspace` 作为公开响应的唯一业务数据模型。 +- 保留模板渲染所需的模板元数据和视觉 manifest,但不返回数据库原始实体。 +- 更新 Miniapp、共享类型和 API 集成测试。 +- 验证草稿不会进入公开接口,品牌数据不会串租户。 + +## 非目标 + +- 不新增模板或行业字段。 +- 不改变发布快照的数据库存储结构。 diff --git a/.codex-tasks/public-workspace-contract-hardening/TODO.csv b/.codex-tasks/public-workspace-contract-hardening/TODO.csv new file mode 100644 index 0000000..7bd4481 --- /dev/null +++ b/.codex-tasks/public-workspace-contract-hardening/TODO.csv @@ -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 通过 diff --git a/apps/api/src/modules/public/public-workspace.controller.ts b/apps/api/src/modules/public/public-workspace.controller.ts index 898115e..baa2100 100644 --- a/apps/api/src/modules/public/public-workspace.controller.ts +++ b/apps/api/src/modules/public/public-workspace.controller.ts @@ -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>; - 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>; @@ -265,7 +257,6 @@ export class PublicWorkspaceController { }, ]; }); - const inquiryForm = formsData[0] ?? null; const trustPresentation = trustData.reduce>((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; } diff --git a/apps/api/test/http.integration.test.js b/apps/api/test/http.integration.test.js index 08545ca..40b0f71 100644 --- a/apps/api/test/http.integration.test.js +++ b/apps/api/test/http.integration.test.js @@ -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, diff --git a/apps/miniapp/pages/bookings/index.js b/apps/miniapp/pages/bookings/index.js index 4ceed06..f97ce15 100644 --- a/apps/miniapp/pages/bookings/index.js +++ b/apps/miniapp/pages/bookings/index.js @@ -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 || "", diff --git a/apps/miniapp/pages/index/index.js b/apps/miniapp/pages/index/index.js index 267fd9d..8f1e853 100644 --- a/apps/miniapp/pages/index/index.js +++ b/apps/miniapp/pages/index/index.js @@ -44,7 +44,7 @@ Page({ : {}; this.setData({ brand: activeBrand, - trustContent: workspace.trustContent || [], + trustContent: workspace.trustPresentation || {}, offerings: activeOfferings, modules: workspace.modules || [], moduleVariants: workspace.moduleVariants || {}, diff --git a/apps/miniapp/pages/inquiry/index.js b/apps/miniapp/pages/inquiry/index.js index c78cfa4..184f9b0 100644 --- a/apps/miniapp/pages/inquiry/index.js +++ b/apps/miniapp/pages/inquiry/index.js @@ -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", diff --git a/apps/miniapp/test/runtime-workspace.test.cjs b/apps/miniapp/test/runtime-workspace.test.cjs index 24916d0..52ecbb5 100644 --- a/apps/miniapp/test/runtime-workspace.test.cjs +++ b/apps/miniapp/test/runtime-workspace.test.cjs @@ -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" }, diff --git a/packages/api-client/src/index.ts b/packages/api-client/src/index.ts index 733a57f..bb34a12 100644 --- a/packages/api-client/src/index.ts +++ b/packages/api-client/src/index.ts @@ -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; - typography?: Record; - spacing?: Record; - radius?: Record; - }; - 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) | 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>; 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 | null; - }>; - fields: BrandFieldDefinition[]; - offerings: Offering[]; - inquiryForm: InquiryForm | null; - runtimeOfferings?: Array>; - inquiryForms?: Array>; - trustPresentation?: Record; - 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; + theme: ThemeManifest; + layout?: { home: string[]; offerings: string[]; detail: string[]; profile: string[] }; plugins?: Array<{ key: string; version: string; diff --git a/packages/template-acheng-campus-food/miniapp/pages/bookings/index.js b/packages/template-acheng-campus-food/miniapp/pages/bookings/index.js index c454ab5..ee11ed4 100644 --- a/packages/template-acheng-campus-food/miniapp/pages/bookings/index.js +++ b/packages/template-acheng-campus-food/miniapp/pages/bookings/index.js @@ -13,7 +13,7 @@ Page({ .then((workspace) => this.setData({ brand: workspace.brand || {}, - trustContent: workspace.trustContent || [], + trustContent: workspace.trustPresentation || {}, records: [], navigation: workspace.navigation || [], }), diff --git a/packages/template-acheng-campus-food/miniapp/pages/index/index.js b/packages/template-acheng-campus-food/miniapp/pages/index/index.js index c66a3a8..8d2c13d 100644 --- a/packages/template-acheng-campus-food/miniapp/pages/index/index.js +++ b/packages/template-acheng-campus-food/miniapp/pages/index/index.js @@ -8,7 +8,7 @@ Page({ this.setData({ brand: workspace.brand || {}, presentation: workspace.brand?.visualPresentation?.home || {}, - trustContent: workspace.trustContent || [], + trustContent: workspace.trustPresentation || {}, offerings: workspace.offerings || [], }), ) diff --git a/packages/template-contract/src/index.ts b/packages/template-contract/src/index.ts index 1bbad6d..7860bd3 100644 --- a/packages/template-contract/src/index.ts +++ b/packages/template-contract/src/index.ts @@ -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`);