From 413413efda8d77e0f8123d97d8eabbb52cb13c24 Mon Sep 17 00:00:00 2001 From: que01 Date: Fri, 16 Oct 2026 16:34:24 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90=E6=A8=A1=E6=9D=BF?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=AF=BC=E5=85=A5=E4=B8=8E=E7=94=9F=E5=91=BD?= =?UTF-8?q?=E5=91=A8=E6=9C=9F=E7=AE=A1=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 1 + apps/admin/src/app/Dashboard.tsx | 17 +- apps/admin/src/app/Root.tsx | 7 +- apps/admin/src/app/routes.tsx | 5 + apps/admin/src/features/auth/AuthPages.tsx | 7 +- .../TemplateManagementPage.tsx | 252 ++++++++++ .../migration.sql | 46 ++ .../migration.sql | 28 ++ apps/api/prisma/schema.prisma | 66 +++ apps/api/prisma/seed.ts | 3 +- apps/api/src/admin-access.service.ts | 25 +- apps/api/src/admin-auth.service.ts | 9 +- apps/api/src/admin-membership.guard.ts | 3 + .../admin-template-package.controller.ts | 43 ++ .../admin/admin-template-package.dto.ts | 17 + .../admin/admin-template-package.service.ts | 463 ++++++++++++++++++ apps/api/src/modules/admin/admin.module.ts | 4 + .../src/modules/session/session.controller.ts | 10 +- apps/api/test/http.integration.test.js | 140 +++++- docs/template-management-delivery-plan.md | 24 +- packages/api-client/src/client/request.ts | 23 +- packages/api-client/src/index.ts | 25 +- packages/api-client/src/resources/session.ts | 1 + packages/api-client/src/resources/template.ts | 92 ++++ packages/api-client/test/client.test.ts | 26 + 25 files changed, 1313 insertions(+), 24 deletions(-) create mode 100644 apps/admin/src/features/template-management/TemplateManagementPage.tsx create mode 100644 apps/api/prisma/migrations/20261016000000_add_template_package_catalog/migration.sql create mode 100644 apps/api/prisma/migrations/20261016010000_add_template_catalog_lifecycle/migration.sql create mode 100644 apps/api/src/modules/admin/admin-template-package.controller.ts create mode 100644 apps/api/src/modules/admin/admin-template-package.dto.ts create mode 100644 apps/api/src/modules/admin/admin-template-package.service.ts diff --git a/.env.example b/.env.example index 20e17be..e4f22a7 100644 --- a/.env.example +++ b/.env.example @@ -9,6 +9,7 @@ API_PREFIX= ADMIN_PORT=3000 SESSION_SECRET=replace-with-a-long-random-value DEFAULT_BRAND_ID=00000000-0000-0000-0000-000000000001 +TEMPLATE_ARTIFACT_ROOT=/var/lib/personal-brand/template-artifacts SEED_ADMIN_PASSWORD=change-me-now-123 OBJECT_STORAGE_ENDPOINT=http://localhost:9000 OBJECT_STORAGE_PUBLIC_URL=http://localhost:9000/personal-brand-media diff --git a/apps/admin/src/app/Dashboard.tsx b/apps/admin/src/app/Dashboard.tsx index b6b14ea..05c2dac 100644 --- a/apps/admin/src/app/Dashboard.tsx +++ b/apps/admin/src/app/Dashboard.tsx @@ -21,6 +21,7 @@ import { FeatureMembersPage, FeatureOverviewPage, FeaturePublicationPage, + FeatureTemplateManagementPage, FeatureServicesPage, FeatureTrustContentPage, FeatureWorkspacePage, @@ -35,7 +36,15 @@ import { Route, Routes } from "react-router-dom"; import { AdminOverviewRedirect } from "./AdminRouter.js"; import { Suspense } from "react"; -export function Dashboard({ onLogout, role }: { onLogout: () => void; role: string }) { +export function Dashboard({ + onLogout, + role, + platformTemplateRole, +}: { + onLogout: () => void; + role: string; + platformTemplateRole: string; +}) { const navigate = useNavigate(); const location = useLocation(); const brand = useQuery({ @@ -79,6 +88,9 @@ export function Dashboard({ onLogout, role }: { onLogout: () => void; role: stri children: [ { key: "capabilities", label: "能力插件", icon: }, { key: "members", label: "团队成员", icon: }, + ...(platformTemplateRole === "template_admin" + ? [{ key: "templates", label: "模板管理", icon: }] + : []), ], }, ]), @@ -143,6 +155,9 @@ export function Dashboard({ onLogout, role }: { onLogout: () => void; role: stri <> } /> } /> + {platformTemplateRole === "template_admin" ? ( + } /> + ) : null} )} } /> diff --git a/apps/admin/src/app/Root.tsx b/apps/admin/src/app/Root.tsx index ca8a4aa..9a8a511 100644 --- a/apps/admin/src/app/Root.tsx +++ b/apps/admin/src/app/Root.tsx @@ -7,6 +7,9 @@ import { adminMessage as message } from "../components/AdminMessage.js"; export function Root() { const [loggedIn, setLoggedIn] = useState(Boolean(localStorage.getItem("adminToken"))); const [role, setRole] = useState(localStorage.getItem("adminRole") || "owner"); + const [platformTemplateRole, setPlatformTemplateRole] = useState( + localStorage.getItem("adminPlatformTemplateRole") || "none", + ); const [mustChangePassword, setMustChangePassword] = useState( localStorage.getItem("adminMustChangePassword") === "true", ); @@ -21,6 +24,7 @@ export function Root() { const logout = () => { localStorage.removeItem("adminToken"); localStorage.removeItem("adminRole"); + localStorage.removeItem("adminPlatformTemplateRole"); localStorage.removeItem("adminMustChangePassword"); setLoggedIn(false); }; @@ -29,6 +33,7 @@ export function Root() { { setRole(session.role); + setPlatformTemplateRole(session.platformTemplateRole); setMustChangePassword(session.mustChangePassword); setLoggedIn(true); }} @@ -37,7 +42,7 @@ export function Root() { if (mustChangePassword) return setMustChangePassword(false)} />; return ( - + ); } diff --git a/apps/admin/src/app/routes.tsx b/apps/admin/src/app/routes.tsx index cd1ea7a..e14c50f 100644 --- a/apps/admin/src/app/routes.tsx +++ b/apps/admin/src/app/routes.tsx @@ -43,3 +43,8 @@ export const FeaturePublicationPage = React.lazy(() => default: module.PublicationPage, })), ); +export const FeatureTemplateManagementPage = React.lazy(() => + import("../features/template-management/TemplateManagementPage.js").then((module) => ({ + default: module.TemplateManagementPage, + })), +); diff --git a/apps/admin/src/features/auth/AuthPages.tsx b/apps/admin/src/features/auth/AuthPages.tsx index 9838f60..2814dc4 100644 --- a/apps/admin/src/features/auth/AuthPages.tsx +++ b/apps/admin/src/features/auth/AuthPages.tsx @@ -9,7 +9,11 @@ import { AdminForm, AdminInput } from "../../components/AdminForm.js"; export function Login({ onLogin, }: { - onLogin: (session: { role: string; mustChangePassword: boolean }) => void; + onLogin: (session: { + role: string; + mustChangePassword: boolean; + platformTemplateRole: "none" | "template_admin"; + }) => void; }) { const [form] = AdminForm.useForm(); const [loading, setLoading] = useState(false); @@ -19,6 +23,7 @@ export function Login({ const result = await createApiClient().loginAdmin(values.username, values.password); localStorage.setItem("adminToken", result.token); localStorage.setItem("adminRole", result.role); + localStorage.setItem("adminPlatformTemplateRole", result.platformTemplateRole); localStorage.setItem("adminMustChangePassword", String(result.mustChangePassword)); onLogin(result); } catch (error) { diff --git a/apps/admin/src/features/template-management/TemplateManagementPage.tsx b/apps/admin/src/features/template-management/TemplateManagementPage.tsx new file mode 100644 index 0000000..7025b6b --- /dev/null +++ b/apps/admin/src/features/template-management/TemplateManagementPage.tsx @@ -0,0 +1,252 @@ +import { useRef, useState } from "react"; +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { Alert, Button, List, Modal, Table, Tag, Typography, message } from "antd"; +import { ReloadOutlined, UploadOutlined } from "@ant-design/icons"; +import type { TemplatePackageVersion } from "@personal-brand/api-client"; +import { createApiClient } from "../../lib/api.js"; +import { AdminPageHeader } from "../../components/AdminPageHeader.js"; +import { AdminSection } from "../../components/AdminSection.js"; +import { EmptyState } from "../../components/EmptyState.js"; +import { ErrorNote, QueryState } from "../../components/QueryState.js"; + +const client = createApiClient(); + +function formatBytes(value: unknown): string { + const bytes = typeof value === "number" ? value : 0; + if (bytes < 1024) return `${bytes} B`; + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`; + return `${(bytes / 1024 / 1024).toFixed(1)} MB`; +} + +export function TemplateManagementPage() { + const inputRef = useRef(null); + const [page, setPage] = useState(1); + const [pageSize, setPageSize] = useState(20); + const [auditId, setAuditId] = useState(null); + const queryClient = useQueryClient(); + const packages = useQuery({ + queryKey: ["admin-template-packages", page, pageSize], + queryFn: () => client.listAdminTemplatePackages({ page, pageSize }), + }); + const audit = useQuery({ + queryKey: ["admin-template-package-audit", auditId], + queryFn: () => client.listAdminTemplatePackageAudit(auditId as string), + enabled: Boolean(auditId), + }); + const lifecycle = useMutation({ + mutationFn: async ({ id, action }: { id: string; action: "publish" | "retire" }) => + action === "publish" + ? client.publishAdminTemplatePackage(id) + : client.retireAdminTemplatePackage(id), + onSuccess: (result) => { + void queryClient.invalidateQueries({ queryKey: ["admin-template-packages"] }); + message.success(result.changed ? "模板目录状态已更新" : "模板目录状态未变化"); + }, + }); + const importing = useMutation({ + mutationFn: (file: File) => { + const form = new FormData(); + form.append("archive", file, file.name); + return client.importAdminTemplatePackage(form); + }, + onSuccess: () => { + void queryClient.invalidateQueries({ queryKey: ["admin-template-packages"] }); + }, + }); + const chooseFile = () => inputRef.current?.click(); + const onFileChange = (event: React.ChangeEvent) => { + const file = event.target.files?.[0]; + event.target.value = ""; + if (!file) return; + if (!file.name.endsWith(".tar.gz")) { + importing.reset(); + return; + } + importing.mutate(file); + }; + const rows = packages.data?.items ?? []; + return ( +
+ + + + + } + /> + + {importing.isError ? : null} + {importing.isSuccess ? ( + + ) : null} + {lifecycle.isError ? : null} + + void packages.refetch()} + > + {rows.length ? ( + + rowKey="id" + dataSource={rows} + pagination={{ + current: packages.data?.page ?? page, + pageSize: packages.data?.pageSize ?? pageSize, + total: packages.data?.total ?? 0, + showSizeChanger: true, + onChange: (nextPage, nextPageSize) => { + setPage(nextPageSize === pageSize ? nextPage : 1); + setPageSize(nextPageSize); + }, + }} + scroll={{ x: 980 }} + columns={[ + { + title: "模板", + key: "template", + render: (_, item) => ( +
+ {item.displayName} +
{item.packageKey}
+
+ ), + }, + { title: "版本", dataIndex: "version", key: "version" }, + { + title: "状态", + dataIndex: "status", + key: "status", + render: (value: TemplatePackageVersion["status"]) => ( + + {value === "published" + ? "已发布" + : value === "imported" + ? "待发布" + : value === "retired" + ? "已撤回" + : "已停用"} + + ), + }, + { + title: "文件", + key: "report", + render: (_, item) => { + const report = item.validationReport; + return `${String(report.fileCount ?? "-")} 个,${formatBytes(report.extractedBytes)}`; + }, + }, + { + title: "内容 checksum", + dataIndex: "contentChecksum", + key: "contentChecksum", + render: (value: string) => ( + {value.slice(0, 16)}… + ), + }, + { + title: "导入人", + key: "importedBy", + render: (_, item) => item.importedBy.displayName, + }, + { + title: "操作", + key: "actions", + render: (_, item) => ( + + + + + ), + }, + ]} + /> + ) : ( + + )} +
+
+ {packages.isError ? ( + + ) : null} + setAuditId(null)} + > + void audit.refetch()} + > + ( + + ${item.toStatus ?? "-"} · ${new Date(item.createdAt).toLocaleString()}`} + /> + + )} + /> + + +
+ ); +} diff --git a/apps/api/prisma/migrations/20261016000000_add_template_package_catalog/migration.sql b/apps/api/prisma/migrations/20261016000000_add_template_package_catalog/migration.sql new file mode 100644 index 0000000..2ffe6a0 --- /dev/null +++ b/apps/api/prisma/migrations/20261016000000_add_template_package_catalog/migration.sql @@ -0,0 +1,46 @@ +CREATE TYPE "PlatformTemplateRole" AS ENUM ('none', 'template_admin'); +CREATE TYPE "TemplatePackageVersionStatus" AS ENUM ('imported', 'disabled'); + +ALTER TABLE "AdminUser" +ADD COLUMN "platformTemplateRole" "PlatformTemplateRole" NOT NULL DEFAULT 'none'; + +CREATE TABLE "TemplatePackage" ( + "id" TEXT NOT NULL, + "packageKey" TEXT NOT NULL, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + CONSTRAINT "TemplatePackage_pkey" PRIMARY KEY ("id") +); + +CREATE TABLE "TemplatePackageVersion" ( + "id" TEXT NOT NULL, + "templatePackageId" TEXT NOT NULL, + "packageKey" TEXT NOT NULL, + "version" TEXT NOT NULL, + "displayName" TEXT NOT NULL, + "visualTemplateKey" TEXT, + "status" "TemplatePackageVersionStatus" NOT NULL DEFAULT 'imported', + "manifestSnapshot" JSONB NOT NULL, + "validationReport" JSONB NOT NULL, + "contentChecksum" TEXT NOT NULL, + "archiveChecksum" TEXT NOT NULL, + "artifactPath" TEXT NOT NULL, + "importedById" TEXT NOT NULL, + "importedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + "updatedAt" TIMESTAMP(3) NOT NULL, + CONSTRAINT "TemplatePackageVersion_pkey" PRIMARY KEY ("id") +); + +CREATE UNIQUE INDEX "TemplatePackage_packageKey_key" ON "TemplatePackage"("packageKey"); +CREATE UNIQUE INDEX "TemplatePackageVersion_templatePackageId_version_key" ON "TemplatePackageVersion"("templatePackageId", "version"); +CREATE INDEX "TemplatePackageVersion_packageKey_status_idx" ON "TemplatePackageVersion"("packageKey", "status"); +CREATE INDEX "TemplatePackageVersion_importedById_importedAt_idx" ON "TemplatePackageVersion"("importedById", "importedAt"); + +ALTER TABLE "TemplatePackageVersion" +ADD CONSTRAINT "TemplatePackageVersion_templatePackageId_fkey" +FOREIGN KEY ("templatePackageId") REFERENCES "TemplatePackage"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +ALTER TABLE "TemplatePackageVersion" +ADD CONSTRAINT "TemplatePackageVersion_importedById_fkey" +FOREIGN KEY ("importedById") REFERENCES "AdminUser"("id") ON DELETE RESTRICT ON UPDATE CASCADE; diff --git a/apps/api/prisma/migrations/20261016010000_add_template_catalog_lifecycle/migration.sql b/apps/api/prisma/migrations/20261016010000_add_template_catalog_lifecycle/migration.sql new file mode 100644 index 0000000..bec7a21 --- /dev/null +++ b/apps/api/prisma/migrations/20261016010000_add_template_catalog_lifecycle/migration.sql @@ -0,0 +1,28 @@ +ALTER TYPE "TemplatePackageVersionStatus" ADD VALUE 'published'; +ALTER TYPE "TemplatePackageVersionStatus" ADD VALUE 'retired'; + +CREATE TABLE "TemplatePackageAuditLog" ( + "id" TEXT NOT NULL, + "templatePackageVersionId" TEXT NOT NULL, + "actorId" TEXT NOT NULL, + "action" TEXT NOT NULL, + "fromStatus" "TemplatePackageVersionStatus", + "toStatus" "TemplatePackageVersionStatus", + "requestId" TEXT, + "metadata" JSONB, + "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + CONSTRAINT "TemplatePackageAuditLog_pkey" PRIMARY KEY ("id") +); + +CREATE INDEX "TemplatePackageAuditLog_templatePackageVersionId_createdAt_idx" +ON "TemplatePackageAuditLog"("templatePackageVersionId", "createdAt" DESC); +CREATE INDEX "TemplatePackageAuditLog_actorId_createdAt_idx" +ON "TemplatePackageAuditLog"("actorId", "createdAt" DESC); + +ALTER TABLE "TemplatePackageAuditLog" +ADD CONSTRAINT "TemplatePackageAuditLog_templatePackageVersionId_fkey" +FOREIGN KEY ("templatePackageVersionId") REFERENCES "TemplatePackageVersion"("id") ON DELETE CASCADE ON UPDATE CASCADE; + +ALTER TABLE "TemplatePackageAuditLog" +ADD CONSTRAINT "TemplatePackageAuditLog_actorId_fkey" +FOREIGN KEY ("actorId") REFERENCES "AdminUser"("id") ON DELETE RESTRICT ON UPDATE CASCADE; diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma index e236389..5b153f9 100644 --- a/apps/api/prisma/schema.prisma +++ b/apps/api/prisma/schema.prisma @@ -139,6 +139,18 @@ enum MiniAppBuildStatus { failed } +enum PlatformTemplateRole { + none + template_admin +} + +enum TemplatePackageVersionStatus { + imported + published + retired + disabled +} + model CapabilityAuditLog { id String @id @default(uuid()) brandId String @@ -385,12 +397,66 @@ model AdminUser { passwordHash String displayName String role String @default("admin") + platformTemplateRole PlatformTemplateRole @default(none) isEnabled Boolean @default(true) mustChangePassword Boolean @default(false) lastLoginAt DateTime? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt memberships BrandMembership[] + importedTemplateVersions TemplatePackageVersion[] @relation("TemplatePackageImportedBy") + templateAuditLogs TemplatePackageAuditLog[] @relation("TemplatePackageAuditActor") +} + +model TemplatePackage { + id String @id @default(uuid()) + packageKey String @unique + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + versions TemplatePackageVersion[] +} + +model TemplatePackageVersion { + id String @id @default(uuid()) + templatePackageId String + templatePackage TemplatePackage @relation(fields: [templatePackageId], references: [id], onDelete: Cascade) + packageKey String + version String + displayName String + visualTemplateKey String? + status TemplatePackageVersionStatus @default(imported) + manifestSnapshot Json + validationReport Json + contentChecksum String + archiveChecksum String + artifactPath String + importedById String + importedBy AdminUser @relation("TemplatePackageImportedBy", fields: [importedById], references: [id], onDelete: Restrict) + auditLogs TemplatePackageAuditLog[] + importedAt DateTime @default(now()) + createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt + + @@unique([templatePackageId, version]) + @@index([packageKey, status]) + @@index([importedById, importedAt]) +} + +model TemplatePackageAuditLog { + id String @id @default(uuid()) + templatePackageVersionId String + templatePackageVersion TemplatePackageVersion @relation(fields: [templatePackageVersionId], references: [id], onDelete: Cascade) + actorId String + actor AdminUser @relation("TemplatePackageAuditActor", fields: [actorId], references: [id], onDelete: Restrict) + action String + fromStatus TemplatePackageVersionStatus? + toStatus TemplatePackageVersionStatus? + requestId String? + metadata Json? + createdAt DateTime @default(now()) + + @@index([templatePackageVersionId, createdAt]) + @@index([actorId, createdAt]) } model BrandMembership { diff --git a/apps/api/prisma/seed.ts b/apps/api/prisma/seed.ts index 28fee45..df9c27c 100644 --- a/apps/api/prisma/seed.ts +++ b/apps/api/prisma/seed.ts @@ -852,11 +852,12 @@ async function main(): Promise { } const admin = await prisma.adminUser.upsert({ where: { username: "admin" }, - update: {}, + update: { platformTemplateRole: "template_admin" }, create: { username: "admin", passwordHash: await bcrypt.hash(process.env.SEED_ADMIN_PASSWORD ?? "change-me-now-123", 12), displayName: "品牌管理员", + platformTemplateRole: "template_admin", mustChangePassword: true, }, }); diff --git a/apps/api/src/admin-access.service.ts b/apps/api/src/admin-access.service.ts index 28b1f86..6bda8c8 100644 --- a/apps/api/src/admin-access.service.ts +++ b/apps/api/src/admin-access.service.ts @@ -21,9 +21,9 @@ export class AdminAccessService { if (identity.role !== "admin") throw new ForbiddenException("无管理员权限"); const user = await this.prisma.adminUser.findUnique({ where: { id: identity.subject }, - select: { mustChangePassword: true }, + select: { mustChangePassword: true, isEnabled: true }, }); - if (!user || user.mustChangePassword) + if (!user?.isEnabled || user.mustChangePassword) throw new ForbiddenException("请先完成初始密码修改后再访问管理后台"); const membership = await this.prisma.brandMembership.findUnique({ where: { adminUserId_brandId: { adminUserId: identity.subject, brandId: identity.brandId } }, @@ -39,4 +39,25 @@ export class AdminAccessService { } return true; } + + async requireTemplateAdmin(request: FastifyRequest): Promise<{ subject: string }> { + const token = request.headers.authorization?.replace(/^Bearer\s+/i, ""); + if (!token) throw new UnauthorizedException("缺少管理员登录态"); + let identity; + try { + identity = readIdentity(token); + } catch { + throw new UnauthorizedException("管理员登录态无效或已过期"); + } + if (identity.role !== "admin") throw new ForbiddenException("无管理员权限"); + const user = await this.prisma.adminUser.findUnique({ + where: { id: identity.subject }, + select: { isEnabled: true, mustChangePassword: true, platformTemplateRole: true }, + }); + if (!user?.isEnabled || user.mustChangePassword) + throw new ForbiddenException("请先完成初始密码修改后再访问管理后台"); + if (user.platformTemplateRole !== "template_admin") + throw new ForbiddenException("当前账号没有模板管理权限"); + return { subject: identity.subject }; + } } diff --git a/apps/api/src/admin-auth.service.ts b/apps/api/src/admin-auth.service.ts index d0caa01..883b6dc 100644 --- a/apps/api/src/admin-auth.service.ts +++ b/apps/api/src/admin-auth.service.ts @@ -10,7 +10,13 @@ export class AdminAuthService { async login( username: string, password: string, - ): Promise<{ token: string; displayName: string; mustChangePassword: boolean; role: string }> { + ): Promise<{ + token: string; + displayName: string; + mustChangePassword: boolean; + role: string; + platformTemplateRole: string; + }> { const user = await this.prisma.adminUser.findUnique({ where: { username } }); if (!user || !user.isEnabled || !(await bcrypt.compare(password, user.passwordHash))) { throw new UnauthorizedException("账号或密码错误"); @@ -41,6 +47,7 @@ export class AdminAuthService { displayName: user.displayName, mustChangePassword: user.mustChangePassword, role: activeMembership.role, + platformTemplateRole: user.platformTemplateRole, }; } diff --git a/apps/api/src/admin-membership.guard.ts b/apps/api/src/admin-membership.guard.ts index b20258e..48bf9e3 100644 --- a/apps/api/src/admin-membership.guard.ts +++ b/apps/api/src/admin-membership.guard.ts @@ -17,6 +17,9 @@ export class AdminMembershipGuard implements CanActivate { if (routePath === "admin/session/login") return Promise.resolve(true); if (routePath === "admin/session/change-password") return Promise.resolve(true); if (!routePath.startsWith("admin/")) return Promise.resolve(true); + if (routePath === "admin/templates" || routePath.startsWith("admin/templates/")) { + return this.access.requireTemplateAdmin(request).then(() => true); + } if ( /^admin\/workspace\/(install|capabilities(?:\/|$)|template(?:\/|$)|fields(?:\/|$))/.test( routePath, diff --git a/apps/api/src/modules/admin/admin-template-package.controller.ts b/apps/api/src/modules/admin/admin-template-package.controller.ts new file mode 100644 index 0000000..9620447 --- /dev/null +++ b/apps/api/src/modules/admin/admin-template-package.controller.ts @@ -0,0 +1,43 @@ +import { Controller, Get, Param, Post, Query, Req } from "@nestjs/common"; +import type { FastifyRequest } from "fastify"; +import { AdminAccessService } from "../../admin-access.service.js"; +import { ListTemplatePackagesQueryDto } from "./admin-template-package.dto.js"; +import { AdminTemplatePackageService } from "./admin-template-package.service.js"; + +@Controller("admin/templates") +export class AdminTemplatePackageController { + constructor( + private readonly access: AdminAccessService, + private readonly templates: AdminTemplatePackageService, + ) {} + + @Get() + list( + @Query() query: ListTemplatePackagesQueryDto, + ): ReturnType { + return this.templates.list(query.page, query.pageSize); + } + + @Post("import") + async import(@Req() request: FastifyRequest) { + const { subject } = await this.access.requireTemplateAdmin(request); + return this.templates.importArchive(request, subject); + } + + @Post(":id/publish") + async publish(@Req() request: FastifyRequest, @Param("id") id: string) { + const { subject } = await this.access.requireTemplateAdmin(request); + return this.templates.publish(id, subject, request.headers["x-request-id"]?.toString()); + } + + @Post(":id/retire") + async retire(@Req() request: FastifyRequest, @Param("id") id: string) { + const { subject } = await this.access.requireTemplateAdmin(request); + return this.templates.retire(id, subject, request.headers["x-request-id"]?.toString()); + } + + @Get(":id/audit") + audit(@Param("id") id: string): ReturnType { + return this.templates.audit(id); + } +} diff --git a/apps/api/src/modules/admin/admin-template-package.dto.ts b/apps/api/src/modules/admin/admin-template-package.dto.ts new file mode 100644 index 0000000..4c677e6 --- /dev/null +++ b/apps/api/src/modules/admin/admin-template-package.dto.ts @@ -0,0 +1,17 @@ +import { Type } from "class-transformer"; +import { IsInt, IsOptional, Max, Min } from "class-validator"; + +export class ListTemplatePackagesQueryDto { + @IsOptional() + @Type(() => Number) + @IsInt() + @Min(1) + page = 1; + + @IsOptional() + @Type(() => Number) + @IsInt() + @Min(1) + @Max(100) + pageSize = 20; +} diff --git a/apps/api/src/modules/admin/admin-template-package.service.ts b/apps/api/src/modules/admin/admin-template-package.service.ts new file mode 100644 index 0000000..ea49a03 --- /dev/null +++ b/apps/api/src/modules/admin/admin-template-package.service.ts @@ -0,0 +1,463 @@ +import { + BadRequestException, + ConflictException, + Injectable, + PayloadTooLargeException, +} from "@nestjs/common"; +import { validateTemplatePackageManifest } from "@personal-brand/config"; +import { Prisma } from "@prisma/client"; +import type { FastifyRequest } from "fastify"; +import { createHash } from "node:crypto"; +import { execFile } from "node:child_process"; +import { promises as fs } from "node:fs"; +import path from "node:path"; +import { promisify } from "node:util"; +import { PrismaService } from "../../prisma.service.js"; + +const execFileAsync = promisify(execFile); +const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024; +const MAX_EXTRACTED_BYTES = 200 * 1024 * 1024; +const MAX_FILES = 5_000; +const PACKAGE_KEY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/; + +type Manifest = { + packageKey: string; + version: string; + displayName: string; + visualTemplateKey?: string; +}; + +type ChecksumFile = { + formatVersion: string; + packageKey: string; + version: string; + contentChecksum: string; + files: Array<{ path: string; bytes: number; sha256: string }>; +}; + +function sha256(value: Buffer | string): string { + return createHash("sha256").update(value).digest("hex"); +} + +function canonical(value: unknown): unknown { + if (Array.isArray(value)) return value.map(canonical); + if (!value || typeof value !== "object") return value; + return Object.fromEntries( + Object.entries(value) + .sort(([left], [right]) => left.localeCompare(right)) + .map(([key, item]) => [key, canonical(item)]), + ); +} + +function jsonObject(value: unknown, label: string): Record { + if (!value || typeof value !== "object" || Array.isArray(value)) + throw new BadRequestException(`${label} 必须是 JSON 对象`); + return value as Record; +} + +function safeEntryName(input: string): string { + if (!input || input.includes("\\") || input.startsWith("/") || /^[A-Za-z]:/.test(input)) + throw new BadRequestException("模板包包含不安全的文件路径"); + const withoutTrailingSlash = input.endsWith("/") ? input.slice(0, -1) : input; + const normalized = path.posix.normalize(withoutTrailingSlash); + if (!withoutTrailingSlash || normalized !== withoutTrailingSlash || normalized === ".") + throw new BadRequestException("模板包包含不安全的文件路径"); + if (normalized.split("/").some((segment) => segment === ".." || segment === ".")) + throw new BadRequestException("模板包包含不安全的文件路径"); + return normalized; +} + +async function listArchiveEntries(archivePath: string): Promise { + let list: string; + let verbose: string; + try { + ({ stdout: list } = await execFileAsync("tar", ["-tzf", archivePath], { + maxBuffer: 4 * 1024 * 1024, + })); + ({ stdout: verbose } = await execFileAsync("tar", ["-tvzf", archivePath], { + maxBuffer: 4 * 1024 * 1024, + })); + } catch { + throw new BadRequestException("模板包不是有效的 gzip tar archive"); + } + const entries = list + .split("\n") + .map((item) => item.trimEnd()) + .filter(Boolean) + .map(safeEntryName); + if (!entries.length || entries.length > MAX_FILES) + throw new BadRequestException("模板包文件数量超出限制"); + const typeLines = verbose + .split("\n") + .map((item) => item.trimEnd()) + .filter(Boolean); + if ( + typeLines.length !== entries.length || + typeLines.some((line) => !["-", "d"].includes(line[0] ?? "")) + ) + throw new BadRequestException("模板包只允许包含普通文件和目录,不允许链接或特殊文件"); + if (new Set(entries).size !== entries.length) throw new BadRequestException("模板包包含重复路径"); + return entries; +} + +async function walkFiles( + directory: string, + relative = "", +): Promise> { + const result: Array<{ path: string; bytes: number }> = []; + for (const entry of await fs.readdir(directory, { withFileTypes: true })) { + const current = relative ? `${relative}/${entry.name}` : entry.name; + const absolute = path.join(directory, entry.name); + if (entry.isSymbolicLink()) throw new BadRequestException("模板包解压后包含符号链接"); + if (entry.isDirectory()) result.push(...(await walkFiles(absolute, current))); + else if (entry.isFile()) result.push({ path: current, bytes: (await fs.stat(absolute)).size }); + else throw new BadRequestException("模板包包含不支持的文件类型"); + } + return result; +} + +@Injectable() +export class AdminTemplatePackageService { + constructor(private readonly prisma: PrismaService) {} + + async list(page = 1, pageSize = 20) { + const [total, versions] = await this.prisma.$transaction([ + this.prisma.templatePackageVersion.count(), + this.prisma.templatePackageVersion.findMany({ + orderBy: { importedAt: "desc" }, + skip: (page - 1) * pageSize, + take: pageSize, + select: { + id: true, + packageKey: true, + version: true, + displayName: true, + visualTemplateKey: true, + status: true, + contentChecksum: true, + archiveChecksum: true, + validationReport: true, + importedAt: true, + updatedAt: true, + templatePackage: { select: { id: true } }, + importedBy: { select: { id: true, username: true, displayName: true } }, + }, + }), + ]); + return { + items: versions.map(({ templatePackage, ...version }) => ({ + ...version, + templatePackageId: templatePackage.id, + })), + page, + pageSize, + total, + }; + } + + async importArchive(request: FastifyRequest, actorId: string) { + const part = await request.file({ limits: { files: 1, fileSize: MAX_ARCHIVE_BYTES } }); + if (!part) throw new BadRequestException("请上传模板 archive 文件"); + if (part.fieldname !== "archive") throw new BadRequestException("上传字段必须是 archive"); + const chunks: Buffer[] = []; + let bytes = 0; + let storedArtifactPath: string | null = null; + try { + for await (const chunk of part.file) { + const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk); + bytes += buffer.length; + if (bytes > MAX_ARCHIVE_BYTES) throw new PayloadTooLargeException("模板包超过 50 MB 限制"); + chunks.push(buffer); + } + } catch (error) { + if (error instanceof PayloadTooLargeException) throw error; + throw new BadRequestException("读取模板 archive 失败"); + } + if (part.file.truncated) throw new PayloadTooLargeException("模板包超过 50 MB 限制"); + const archive = Buffer.concat(chunks); + const archiveChecksum = sha256(archive); + const temporaryRoot = await fs.mkdtemp(path.join(process.cwd(), ".template-import-")); + const archivePath = path.join(temporaryRoot, "package.tar.gz"); + const extractedRoot = path.join(temporaryRoot, "extracted"); + try { + await fs.writeFile(archivePath, archive, { mode: 0o600 }); + const entries = await listArchiveEntries(archivePath); + const roots = new Set(entries.map((entry) => entry.split("/")[0])); + if (roots.size !== 1) throw new BadRequestException("模板包必须只有一个根目录"); + const rootName = [...roots][0]; + if ( + !rootName || + entries.some((entry) => entry !== rootName && !entry.startsWith(`${rootName}/`)) + ) + throw new BadRequestException("模板包根目录结构无效"); + await fs.mkdir(extractedRoot, { recursive: true }); + try { + await execFileAsync( + "tar", + [ + "-xzf", + archivePath, + "--directory", + extractedRoot, + "--no-same-owner", + "--no-same-permissions", + ], + { maxBuffer: 4 * 1024 * 1024 }, + ); + } catch { + throw new BadRequestException("模板包解压失败"); + } + const packageRoot = path.join(extractedRoot, rootName); + const files = await walkFiles(packageRoot); + if (files.length > MAX_FILES) throw new BadRequestException("模板包文件数量超出限制"); + if (files.reduce((total, file) => total + file.bytes, 0) > MAX_EXTRACTED_BYTES) + throw new PayloadTooLargeException("模板包解压后超过 200 MB 限制"); + const manifest = (await this.readJson( + path.join(packageRoot, "template.json"), + "template.json", + )) as Manifest; + const packageJson = jsonObject( + await this.readJson(path.join(packageRoot, "package.json"), "package.json"), + "package.json", + ) as { name?: unknown; version?: unknown }; + const checksums = jsonObject( + await this.readJson(path.join(packageRoot, "checksums.json"), "checksums.json"), + "checksums.json", + ) as unknown as ChecksumFile; + this.validateManifest(manifest, packageJson, checksums); + await this.validateChecksums(packageRoot, files, checksums); + const packageKey = manifest.packageKey; + const existingPackage = await this.prisma.templatePackage.findUnique({ + where: { packageKey }, + }); + const existingVersion = existingPackage + ? await this.prisma.templatePackageVersion.findUnique({ + where: { + templatePackageId_version: { + templatePackageId: existingPackage.id, + version: manifest.version, + }, + }, + }) + : null; + if (existingVersion) { + if (existingVersion.contentChecksum === checksums.contentChecksum) + return { + imported: false, + idempotent: true, + version: this.publicVersion(existingVersion), + }; + throw new ConflictException(`${packageKey}@${manifest.version} 已存在不同内容的版本`); + } + const artifactRoot = path.resolve( + process.env.TEMPLATE_ARTIFACT_ROOT ?? + path.join(process.cwd(), "storage", "template-artifacts"), + ); + const artifactPath = path.join( + artifactRoot, + packageKey, + manifest.version, + `${archiveChecksum}.tar.gz`, + ); + await fs.mkdir(path.dirname(artifactPath), { recursive: true }); + await fs.copyFile(archivePath, artifactPath); + storedArtifactPath = artifactPath; + const version = await this.prisma.$transaction(async (tx) => { + const packageRecord = + existingPackage ?? (await tx.templatePackage.create({ data: { packageKey } })); + const created = await tx.templatePackageVersion.create({ + data: { + templatePackageId: packageRecord.id, + packageKey, + version: manifest.version, + displayName: manifest.displayName, + visualTemplateKey: manifest.visualTemplateKey ?? null, + manifestSnapshot: manifest as unknown as Prisma.InputJsonValue, + validationReport: { + formatVersion: "1", + errors: [], + fileCount: files.length, + extractedBytes: files.reduce((total, file) => total + file.bytes, 0), + } as Prisma.InputJsonValue, + contentChecksum: checksums.contentChecksum, + archiveChecksum, + artifactPath, + importedById: actorId, + }, + }); + await tx.templatePackageAuditLog.create({ + data: { + templatePackageVersionId: created.id, + actorId, + action: "imported", + toStatus: "imported", + metadata: { + contentChecksum: checksums.contentChecksum, + archiveChecksum, + }, + }, + }); + return created; + }); + return { imported: true, idempotent: false, version: this.publicVersion(version) }; + } catch (error) { + if (storedArtifactPath) await fs.rm(storedArtifactPath, { force: true }); + throw error; + } finally { + await fs.rm(temporaryRoot, { recursive: true, force: true }); + } + } + + async publish(id: string, actorId: string, requestId?: string) { + return this.transition(id, actorId, "published", requestId); + } + + async retire(id: string, actorId: string, requestId?: string) { + return this.transition(id, actorId, "retired", requestId); + } + + async audit(id: string) { + const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } }); + if (!version) throw new BadRequestException("模板版本不存在"); + return this.prisma.templatePackageAuditLog.findMany({ + where: { templatePackageVersionId: id }, + orderBy: { createdAt: "asc" }, + include: { actor: { select: { id: true, username: true, displayName: true } } }, + }); + } + + private async transition( + id: string, + actorId: string, + target: "published" | "retired", + requestId?: string, + ) { + const version = await this.prisma.templatePackageVersion.findUnique({ where: { id } }); + if (!version) throw new BadRequestException("模板版本不存在"); + if (version.status === target) return { changed: false, version: this.publicVersion(version) }; + const valid = + target === "published" ? version.status === "imported" : version.status === "published"; + if (!valid) throw new ConflictException(`模板版本当前状态为 ${version.status},不能执行此操作`); + const updated = await this.prisma.$transaction(async (tx) => { + const changed = await tx.templatePackageVersion.updateMany({ + where: { id, status: version.status }, + data: { status: target }, + }); + if (changed.count !== 1) { + const current = await tx.templatePackageVersion.findUnique({ where: { id } }); + if (current?.status === target) return { next: current, changed: false }; + throw new ConflictException("模板版本状态已被其他操作修改,请刷新后重试"); + } + const next = await tx.templatePackageVersion.findUniqueOrThrow({ where: { id } }); + await tx.templatePackageAuditLog.create({ + data: { + templatePackageVersionId: id, + actorId, + action: target, + fromStatus: version.status, + toStatus: target, + ...(requestId ? { requestId } : {}), + }, + }); + return { next, changed: true }; + }); + return { changed: updated.changed, version: this.publicVersion(updated.next) }; + } + + private async readJson(filePath: string, label: string): Promise { + try { + return JSON.parse(await fs.readFile(filePath, "utf8")) as unknown; + } catch { + throw new BadRequestException(`${label} 不是有效的 JSON 文件`); + } + } + + private validateManifest( + manifest: Manifest, + packageJson: { name?: unknown; version?: unknown }, + checksums: ChecksumFile, + ) { + if (!manifest || typeof manifest !== "object") + throw new BadRequestException("template.json 无效"); + if (!PACKAGE_KEY_PATTERN.test(manifest.packageKey)) + throw new BadRequestException("模板 packageKey 无效"); + if (typeof manifest.version !== "string" || !manifest.version.trim()) + throw new BadRequestException("模板 version 无效"); + if (typeof manifest.displayName !== "string" || !manifest.displayName.trim()) + throw new BadRequestException("模板 displayName 无效"); + if (packageJson.name !== `@personal-brand/template-${manifest.packageKey}`) + throw new BadRequestException("package.json name 与 template.json packageKey 不一致"); + if (packageJson.version !== manifest.version) + throw new BadRequestException("package.json version 与 template.json version 不一致"); + let errors: string[]; + try { + errors = validateTemplatePackageManifest(manifest as never); + } catch { + throw new BadRequestException("template.json 不符合模板契约"); + } + if (errors.length) + throw new BadRequestException(`template.json 不符合模板契约:${errors.join(";")}`); + if ( + checksums.formatVersion !== "1" || + checksums.packageKey !== manifest.packageKey || + checksums.version !== manifest.version + ) + throw new BadRequestException("checksums.json 元数据不一致"); + } + + private async validateChecksums( + packageRoot: string, + files: Array<{ path: string; bytes: number }>, + checksums: ChecksumFile, + ) { + if (!Array.isArray(checksums.files) || checksums.files.length !== files.length - 1) + throw new BadRequestException("checksums.json 文件清单不完整"); + const comparePath = (left: { path: string }, right: { path: string }) => + left.path < right.path ? -1 : left.path > right.path ? 1 : 0; + const actualFiles = files.filter((file) => file.path !== "checksums.json").sort(comparePath); + const checksumFiles = [...checksums.files].sort(comparePath); + if (checksumFiles.some((item, index) => item.path !== actualFiles[index]?.path)) + throw new BadRequestException("checksums.json 文件清单与 archive 不一致"); + for (const item of checksumFiles) { + safeEntryName(item.path); + if ( + !Number.isSafeInteger(item.bytes) || + item.bytes < 0 || + !/^[a-f0-9]{64}$/.test(item.sha256) + ) + throw new BadRequestException("checksums.json 文件摘要格式无效"); + const content = fs.readFile(path.join(packageRoot, item.path)); + if (item.bytes !== actualFiles.find((file) => file.path === item.path)?.bytes) + throw new BadRequestException("模板文件大小校验失败"); + if (sha256(await content) !== item.sha256) + throw new BadRequestException("模板文件摘要校验失败"); + } + const expected = sha256(JSON.stringify(canonical(checksumFiles))); + if (checksums.contentChecksum !== expected || !/^[a-f0-9]{64}$/.test(checksums.contentChecksum)) + throw new BadRequestException("模板内容摘要校验失败"); + } + + private publicVersion(version: { + id: string; + packageKey: string; + version: string; + displayName: string; + visualTemplateKey: string | null; + status: string; + contentChecksum: string; + archiveChecksum: string; + importedAt: Date; + }) { + return { + id: version.id, + packageKey: version.packageKey, + version: version.version, + displayName: version.displayName, + visualTemplateKey: version.visualTemplateKey, + status: version.status, + contentChecksum: version.contentChecksum, + archiveChecksum: version.archiveChecksum, + importedAt: version.importedAt, + }; + } +} diff --git a/apps/api/src/modules/admin/admin.module.ts b/apps/api/src/modules/admin/admin.module.ts index 19db742..8afa961 100644 --- a/apps/api/src/modules/admin/admin.module.ts +++ b/apps/api/src/modules/admin/admin.module.ts @@ -13,6 +13,8 @@ import { AdminMiniAppUploadService } from "./admin-miniapp-upload.service.js"; import { AdminReleaseController } from "./admin-release.controller.js"; import { AdminUploadService } from "./admin-upload.service.js"; import { AdminUploadController } from "./admin-upload.controller.js"; +import { AdminTemplatePackageController } from "./admin-template-package.controller.js"; +import { AdminTemplatePackageService } from "./admin-template-package.service.js"; @Module({ imports: [InfrastructureModule, BookingModule], @@ -23,6 +25,7 @@ import { AdminUploadController } from "./admin-upload.controller.js"; AdminUploadController, AdminLocalUploadController, AdminBookingController, + AdminTemplatePackageController, ], providers: [ AdminBrandConfigService, @@ -31,6 +34,7 @@ import { AdminUploadController } from "./admin-upload.controller.js"; AdminMiniAppSettingsService, AdminMiniAppUploadService, AdminUploadService, + AdminTemplatePackageService, ], }) export class AdminModule {} diff --git a/apps/api/src/modules/session/session.controller.ts b/apps/api/src/modules/session/session.controller.ts index 7b7e6cf..241e1e1 100644 --- a/apps/api/src/modules/session/session.controller.ts +++ b/apps/api/src/modules/session/session.controller.ts @@ -29,9 +29,13 @@ export class AdminSessionController { constructor(private readonly auth: AdminAuthService) {} @Post("login") - login( - @Body() body: AdminLoginDto, - ): Promise<{ token: string; displayName: string; mustChangePassword: boolean; role: string }> { + login(@Body() body: AdminLoginDto): Promise<{ + token: string; + displayName: string; + mustChangePassword: boolean; + role: string; + platformTemplateRole: string; + }> { return this.auth.login(body.username, body.password); } diff --git a/apps/api/test/http.integration.test.js b/apps/api/test/http.integration.test.js index 16f00b8..f4ecf60 100644 --- a/apps/api/test/http.integration.test.js +++ b/apps/api/test/http.integration.test.js @@ -1,5 +1,9 @@ import assert from "node:assert/strict"; import { randomUUID } from "node:crypto"; +import { execFileSync } from "node:child_process"; +import { mkdtempSync, readFileSync, readdirSync } from "node:fs"; +import os from "node:os"; +import path from "node:path"; import { after, before, test } from "node:test"; import { PrismaClient } from "@prisma/client"; import { getVisualTemplateManifest } from "@personal-brand/config"; @@ -16,12 +20,140 @@ let customerToken; const createdBookingIds = []; before(async () => { + process.env.TEMPLATE_ARTIFACT_ROOT = mkdtempSync( + path.join(os.tmpdir(), "personal-brand-template-artifacts-"), + ); await prisma.customerUser.create({ data: { brandId, openid } }); customerToken = signIdentity({ subject: openid, brandId, role: "customer" }); app = await createApp(); await app.init(); }); +function multipartArchive(archive) { + const boundary = "----personal-brand-template-test"; + const prefix = Buffer.from( + `--${boundary}\r\nContent-Disposition: form-data; name="archive"; filename="template.tar.gz"\r\nContent-Type: application/gzip\r\n\r\n`, + ); + const suffix = Buffer.from(`\r\n--${boundary}--\r\n`); + return { + payload: Buffer.concat([prefix, archive, suffix]), + headers: { "content-type": `multipart/form-data; boundary=${boundary}` }, + }; +} + +function createTemplateArchive() { + const output = mkdtempSync(path.join(os.tmpdir(), "personal-brand-template-pack-")); + execFileSync( + process.execPath, + [ + path.resolve(process.cwd(), "../../scripts/template-pack.cjs"), + "--template", + "acheng-campus-food", + "--out", + output, + ], + { cwd: path.resolve(process.cwd(), "../.."), stdio: "ignore" }, + ); + const filename = readdirSync(output).find((item) => item.endsWith(".tar.gz")); + assert.ok(filename); + return readFileSync(path.join(output, filename)); +} + +test("模板目录只允许平台模板管理员访问,并支持安全、幂等导入", async () => { + const missing = await request("/admin/templates"); + assert.equal(missing.statusCode, 401); + const customer = await request("/admin/templates", { + headers: { authorization: `Bearer ${customerToken}` }, + }); + assert.equal(customer.statusCode, 403); + const ordinaryUser = await prisma.adminUser.create({ + data: { + username: `template-viewer-${Date.now()}`, + passwordHash: "not-used-by-this-test", + displayName: "普通管理员", + platformTemplateRole: "none", + mustChangePassword: false, + }, + }); + try { + const ordinary = await request("/admin/templates", { + headers: { + authorization: `Bearer ${signIdentity({ subject: ordinaryUser.id, brandId, role: "admin" })}`, + }, + }); + assert.equal(ordinary.statusCode, 403); + } finally { + await prisma.adminUser.delete({ where: { id: ordinaryUser.id } }); + } + const login = await request("/admin/session/login", { + method: "POST", + payload: { username: "admin", password: process.env.SEED_ADMIN_PASSWORD }, + }); + assert.equal(login.statusCode, 201); + const headers = { authorization: `Bearer ${JSON.parse(login.body).token}` }; + const empty = await request("/admin/templates", { headers }); + assert.equal(empty.statusCode, 200); + assert.deepEqual(JSON.parse(empty.body).items, []); + assert.equal(JSON.parse(empty.body).total, 0); + + const archive = createTemplateArchive(); + const imported = await request("/admin/templates/import", { + method: "POST", + headers: { ...headers, ...multipartArchive(archive).headers }, + rawPayload: multipartArchive(archive).payload, + }); + assert.equal(imported.statusCode, 201); + assert.equal(JSON.parse(imported.body).imported, true); + const repeated = await request("/admin/templates/import", { + method: "POST", + headers: { ...headers, ...multipartArchive(archive).headers }, + rawPayload: multipartArchive(archive).payload, + }); + assert.equal(repeated.statusCode, 201); + assert.equal(JSON.parse(repeated.body).idempotent, true); + const listed = await request("/admin/templates", { headers }); + const listedBody = JSON.parse(listed.body); + assert.equal(listedBody.items.length, 1); + assert.equal(listedBody.items[0].status, "imported"); + const versionId = listedBody.items[0].id; + const publishMissing = await request(`/admin/templates/${versionId}/publish`, { method: "POST" }); + assert.equal(publishMissing.statusCode, 401); + const publishCustomer = await request(`/admin/templates/${versionId}/publish`, { + method: "POST", + headers: { authorization: `Bearer ${customerToken}` }, + }); + assert.equal(publishCustomer.statusCode, 403); + const published = await request(`/admin/templates/${versionId}/publish`, { + method: "POST", + headers, + }); + assert.equal(published.statusCode, 201); + assert.equal(JSON.parse(published.body).version.status, "published"); + const repeatedPublish = await request(`/admin/templates/${versionId}/publish`, { + method: "POST", + headers, + }); + assert.equal(JSON.parse(repeatedPublish.body).changed, false); + const audit = await request(`/admin/templates/${versionId}/audit`, { headers }); + assert.equal(audit.statusCode, 200); + assert.deepEqual( + JSON.parse(audit.body).map((item) => item.action), + ["imported", "published"], + ); + const retired = await request(`/admin/templates/${versionId}/retire`, { + method: "POST", + headers: { ...headers, "x-request-id": "template-retire-test" }, + }); + assert.equal(retired.statusCode, 201); + assert.equal(JSON.parse(retired.body).version.status, "retired"); + const invalidRetire = await request(`/admin/templates/${versionId}/retire`, { + method: "POST", + headers, + }); + assert.equal(invalidRetire.statusCode, 201); + assert.equal(JSON.parse(invalidRetire.body).changed, false); +}); + test("admin routes remain guarded when an API prefix is configured", async () => { process.env.API_PREFIX = "api"; try { @@ -1126,10 +1258,16 @@ function errorMessage(body) { } async function request(url, options = {}) { + const { rawPayload, ...injectOptions } = options; return app .getHttpAdapter() .getInstance() - .inject({ method: "GET", url, ...options }); + .inject({ + method: "GET", + url, + ...injectOptions, + ...(rawPayload ? { payload: rawPayload } : {}), + }); } async function publishReleaseForTests(note = "集成测试发布") { diff --git a/docs/template-management-delivery-plan.md b/docs/template-management-delivery-plan.md index a4dec12..4f8d9a0 100644 --- a/docs/template-management-delivery-plan.md +++ b/docs/template-management-delivery-plan.md @@ -2,7 +2,7 @@ > 任务 ID:TMP-PLATFORM-001 > -> 状态:规划已固化,分阶段实施尚未完成 +> 状态:实施中,Phase 0/1 已完成,Phase 2 导入基础链路已完成,目录发布与独立预览待继续推进 > > 唯一任务入口:本文档 > @@ -370,15 +370,27 @@ Phase 0 执行记录(2026-10-16): ### Phase 2:线上导入、校验和模板目录 -- [ ] 增加 TemplatePackage、TemplatePackageVersion、validation run 和 artifact 引用; -- [ ] 实现临时存储、安全检查、checksum 幂等和冲突拒绝; +- [x] 增加 TemplatePackage、TemplatePackageVersion、生命周期审计和 artifact 引用; +- [x] 实现临时存储、安全检查、checksum 幂等和冲突拒绝; - [ ] 完成 manifest、runtime、renderer、industry、capability、资源和 fixture 诊断; -- [ ] 实现目录发布、撤回、分页、审计和旧资源保留; -- [ ] 增加独立平台模板权限; -- [ ] API、DTO、shared client 和 integration test 一起交付。 +- [x] 实现目录发布、撤回、分页、审计和旧资源保留; +- [x] 增加独立平台模板权限; +- [x] API、DTO、shared client 和 integration test 一起交付。 退出门禁:非法包不会进入可用目录;重复导入不重复建版本;同版本不同 checksum 明确失败;未发布版本不能被品牌管理员安装。 +Phase 2 当前进度(2026-10-16): + +- 已增加 `TemplatePackage`、`TemplatePackageVersion`、版本状态和 `AdminUser.platformTemplateRole`,artifact 路径独立于 release 目录; +- 已实现平台模板管理员 guard、`GET /admin/templates` 和 `POST /admin/templates/import`;普通品牌管理员和 customer 均不能访问; +- 已实现临时文件导入、archive 路径/链接/重复项检查、文件数和解压体积限制、manifest/package metadata/checksum 校验、幂等和版本冲突拒绝;不执行包内脚本; +- 已同步 shared client 和 Admin `/admin/templates` 的导入、版本列表、loading/empty/error/retry/success 状态; +- 已通过 `51/51` API HTTP integration tests 和 `2/2` upload tests; +- 已补充 `imported -> published -> retired` 生命周期、重复操作幂等、状态竞争保护、分页、审计查询和 Admin 页面发布/撤回/审计操作; +- 已将模板包和版本及审计写入同一数据库事务,数据库失败时清理已落盘 artifact,避免留下半版本; +- 已通过 `51/51` API HTTP integration tests、`2/2` upload tests 和 `6/6` API client tests; +- 尚未完成:独立 validation run / renderer / capability / fixture 诊断、独立 preview session、品牌精确版本安装;因此 Phase 2 目录基础闭环已完成,完整任务继续进入 Phase 3/4。 + ### Phase 3:独立预览和模板管理页面 - [ ] 增加 preview session 或同等短期隔离上下文; diff --git a/packages/api-client/src/client/request.ts b/packages/api-client/src/client/request.ts index bc2bf51..6098aa5 100644 --- a/packages/api-client/src/client/request.ts +++ b/packages/api-client/src/client/request.ts @@ -19,22 +19,33 @@ export interface ApiClientOptions { export type RequestFn = ( path: string, - options?: { method?: string; body?: unknown }, + options?: { method?: string; body?: unknown; rawBody?: unknown }, ) => Promise; export async function request( state: { baseUrl: string; fetcher: FetchLike; token?: string | undefined }, path: string, - options: { method?: string; body?: unknown } = {}, + options: { method?: string; body?: unknown; rawBody?: unknown } = {}, ): Promise { const headers: Record = { accept: "application/json" }; - if (options.body !== undefined) headers["content-type"] = "application/json"; + if (options.rawBody === undefined && options.body !== undefined) + headers["content-type"] = "application/json"; if (state.token) headers.authorization = `Bearer ${state.token}`; - const response = await state.fetcher(`${state.baseUrl}${path}`, { + const init = { method: options.method ?? "GET", headers, - ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }), - }); + ...(options.rawBody !== undefined + ? { body: options.rawBody } + : options.body === undefined + ? {} + : { body: JSON.stringify(options.body) }), + }; + const response = await ( + state.fetcher as unknown as ( + input: string, + init?: { method?: string; headers?: Record; body?: unknown }, + ) => Promise + )(`${state.baseUrl}${path}`, init); const body = await response.json(); if (!response.ok) throw new ApiClientError(response.status, body as ApiErrorBody); return body as T; diff --git a/packages/api-client/src/index.ts b/packages/api-client/src/index.ts index 5876956..b701521 100644 --- a/packages/api-client/src/index.ts +++ b/packages/api-client/src/index.ts @@ -36,6 +36,14 @@ export type { TemplateAdminField, TemplateAdminSection, } from "./types/template.js"; +export type { + TemplateMethods, + TemplatePackageActionResult, + TemplatePackageAuditEntry, + TemplatePackageImportResult, + TemplatePackageList, + TemplatePackageVersion, +} from "./resources/template.js"; export type { TrustContent, TrustContentInput } from "./types/trust.js"; export type { PublicWorkspace } from "./types/workspace.js"; export { projectBrandAliases, projectTrustPresentation } from "@personal-brand/types"; @@ -90,7 +98,7 @@ export class ApiClient private readonly state: ClientState; private readonly requestFn: ( path: string, - options?: { method?: string; body?: unknown }, + options?: { method?: string; body?: unknown; rawBody?: unknown }, ) => Promise; private resources!: { booking: BookingMethods; @@ -229,6 +237,21 @@ export class ApiClient updateAdminMiniAppSettings = ( ...arguments_: Parameters ) => this.resources.brand.updateAdminMiniAppSettings(...arguments_); + listAdminTemplatePackages = ( + ...arguments_: Parameters + ) => this.resources.template.listAdminTemplatePackages(...arguments_); + importAdminTemplatePackage = ( + ...arguments_: Parameters + ) => this.resources.template.importAdminTemplatePackage(...arguments_); + publishAdminTemplatePackage = ( + ...arguments_: Parameters + ) => this.resources.template.publishAdminTemplatePackage(...arguments_); + retireAdminTemplatePackage = ( + ...arguments_: Parameters + ) => this.resources.template.retireAdminTemplatePackage(...arguments_); + listAdminTemplatePackageAudit = ( + ...arguments_: Parameters + ) => this.resources.template.listAdminTemplatePackageAudit(...arguments_); getPublicTemplate = (...arguments_: Parameters) => this.resources.template.getPublicTemplate(...arguments_); listPublicTemplates = (...arguments_: Parameters) => diff --git a/packages/api-client/src/resources/session.ts b/packages/api-client/src/resources/session.ts index ed89cbb..98a91f7 100644 --- a/packages/api-client/src/resources/session.ts +++ b/packages/api-client/src/resources/session.ts @@ -9,6 +9,7 @@ export interface SessionMethods { displayName: string; mustChangePassword: boolean; role: string; + platformTemplateRole: "none" | "template_admin"; }>; changeAdminPassword(currentPassword: string, newPassword: string): Promise<{ changed: true }>; } diff --git a/packages/api-client/src/resources/template.ts b/packages/api-client/src/resources/template.ts index 7480117..544b547 100644 --- a/packages/api-client/src/resources/template.ts +++ b/packages/api-client/src/resources/template.ts @@ -8,6 +8,14 @@ import type { AdminTemplateContent } from "../types/template.js"; import type { BrandTemplateDefinition } from "../types/template-definition.js"; export interface TemplateMethods { + listAdminTemplatePackages(params?: { + page?: number; + pageSize?: number; + }): Promise; + importAdminTemplatePackage(body: unknown): Promise; + publishAdminTemplatePackage(id: string): Promise; + retireAdminTemplatePackage(id: string): Promise; + listAdminTemplatePackageAudit(id: string): Promise; getPublicTemplate(key: BrandTemplateKey): Promise; listPublicTemplates(): Promise<{ industries: BrandTemplateDefinition[]; @@ -86,8 +94,92 @@ export interface TemplateMethods { rollbackAdminTemplate(): Promise; } +export interface TemplatePackageVersion { + id: string; + templatePackageId: string; + packageKey: string; + version: string; + displayName: string; + visualTemplateKey: string | null; + status: "imported" | "published" | "retired" | "disabled"; + contentChecksum: string; + archiveChecksum: string; + validationReport: Record; + importedAt: string; + updatedAt: string; + importedBy: { id: string; username: string; displayName: string }; +} + +export interface TemplatePackageList { + items: TemplatePackageVersion[]; + page: number; + pageSize: number; + total: number; +} + +export interface TemplatePackageActionResult { + changed: boolean; + version: Pick< + TemplatePackageVersion, + | "id" + | "packageKey" + | "version" + | "displayName" + | "visualTemplateKey" + | "status" + | "contentChecksum" + | "archiveChecksum" + | "importedAt" + >; +} + +export interface TemplatePackageAuditEntry { + id: string; + action: string; + fromStatus: TemplatePackageVersion["status"] | null; + toStatus: TemplatePackageVersion["status"] | null; + requestId: string | null; + metadata: Record | null; + createdAt: string; + actor: { id: string; username: string; displayName: string }; +} + +export interface TemplatePackageImportResult { + imported: boolean; + idempotent: boolean; + version: Pick< + TemplatePackageVersion, + | "id" + | "packageKey" + | "version" + | "displayName" + | "visualTemplateKey" + | "status" + | "contentChecksum" + | "archiveChecksum" + | "importedAt" + >; +} + export function templateMethods({ request }: { request: RequestFn }): TemplateMethods { return { + listAdminTemplatePackages: (params = {}) => { + const query = [ + params.page === undefined ? null : `page=${encodeURIComponent(String(params.page))}`, + params.pageSize === undefined + ? null + : `pageSize=${encodeURIComponent(String(params.pageSize))}`, + ].filter((item): item is string => item !== null); + return request(`/admin/templates${query.length ? `?${query.join("&")}` : ""}`); + }, + importAdminTemplatePackage: (body) => + request("/admin/templates/import", { method: "POST", rawBody: body }), + publishAdminTemplatePackage: (id) => + request(`/admin/templates/${encodeURIComponent(id)}/publish`, { method: "POST" }), + retireAdminTemplatePackage: (id) => + request(`/admin/templates/${encodeURIComponent(id)}/retire`, { method: "POST" }), + listAdminTemplatePackageAudit: (id) => + request(`/admin/templates/${encodeURIComponent(id)}/audit`), getPublicTemplate: (key) => request(`/public/templates/${key}`), listPublicTemplates: () => request<{ diff --git a/packages/api-client/test/client.test.ts b/packages/api-client/test/client.test.ts index 09f417b..bed74ef 100644 --- a/packages/api-client/test/client.test.ts +++ b/packages/api-client/test/client.test.ts @@ -95,3 +95,29 @@ test("小程序上传配置会提交请求地址", async () => { }, ]); }); + +test("模板目录客户端发送分页并支持版本发布和审计", async () => { + const calls: Array<{ url: string; method?: string }> = []; + const client = new ApiClient({ + baseUrl: "http://api.test", + token: "template-admin-token", + fetcher: async (url, init) => { + calls.push({ url, method: init?.method }); + return response( + url.includes("/audit") + ? [] + : url.endsWith("/publish") + ? { changed: true, version: { id: "version-1", status: "published" } } + : { items: [], page: 2, pageSize: 10, total: 0 }, + ); + }, + }); + await client.listAdminTemplatePackages({ page: 2, pageSize: 10 }); + await client.publishAdminTemplatePackage("version/1"); + await client.listAdminTemplatePackageAudit("version/1"); + assert.deepEqual(calls, [ + { url: "http://api.test/admin/templates?page=2&pageSize=10", method: "GET" }, + { url: "http://api.test/admin/templates/version%2F1/publish", method: "POST" }, + { url: "http://api.test/admin/templates/version%2F1/audit", method: "GET" }, + ]); +});