From 3003e7801d863a32f35e0cf4b40842ad78cd5bf1 Mon Sep 17 00:00:00 2001 From: que01 Date: Mon, 12 Oct 2026 03:08:24 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E5=BB=BA=E7=AB=8B=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E6=A0=87=E5=87=86=E5=B9=B6=E6=8B=86=E5=88=86=E5=93=81?= =?UTF-8?q?=E7=89=8C=E7=BC=96=E8=BE=91=E7=8A=B6=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../src/features/brand/PresentationEditor.tsx | 201 +++------------- .../presentation-editor-record-preview.ts | 39 +++ .../brand/presentation-editor-state.ts | 226 ++++++++++++++++++ docs/code-standards.md | 50 ++++ 4 files changed, 344 insertions(+), 172 deletions(-) create mode 100644 apps/admin/src/features/brand/presentation-editor-record-preview.ts create mode 100644 apps/admin/src/features/brand/presentation-editor-state.ts create mode 100644 docs/code-standards.md diff --git a/apps/admin/src/features/brand/PresentationEditor.tsx b/apps/admin/src/features/brand/PresentationEditor.tsx index 2dfb633..646c56e 100644 --- a/apps/admin/src/features/brand/PresentationEditor.tsx +++ b/apps/admin/src/features/brand/PresentationEditor.tsx @@ -11,9 +11,8 @@ import { Space, Tag, Typography, - message, } from "antd"; -import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { useQueryClient } from "@tanstack/react-query"; import { useCallback, useEffect, useMemo, useState } from "react"; import { useNavigate } from "react-router-dom"; import type { @@ -24,7 +23,6 @@ import type { } from "@personal-brand/api-client"; import type { BrandProfile } from "@personal-brand/api-client"; import { projectBrandAliases, projectTrustPresentation } from "@personal-brand/api-client"; -import { createApiClient } from "../../lib/api.js"; import { TemplateListField } from "../../components/TemplateListField.js"; import { TemplateFieldRenderer } from "../../components/TemplateFieldRenderer.js"; import { MutationError } from "../../components/QueryState.js"; @@ -38,17 +36,20 @@ import { type PreviewTarget, } from "./preview-selection.js"; import { - applyBrandPreviewValues, - applyStandardBrandValues, - applyStandardEntityValues, - applyPresentationValues, filterSectionsForPreviewTarget, presentationFieldName, - readPresentationValue, type PresentationValues, } from "./presentation-bindings.js"; import "./PresentationEditor.css"; import { useEditorDraft } from "./use-editor-draft.js"; +import { + usePresentationRecordQueries, + useBrandPresentationSections, + useBrandSaveMutation, + useBrandPresentationForm, + useBrandPreviewDraft, +} from "./presentation-editor-state.js"; +import { useRecordPreview } from "./presentation-editor-record-preview.js"; interface PresentationEditorProps { templateContent: AdminTemplateContent | null | undefined; @@ -136,7 +137,6 @@ export function PresentationEditor({ error, initialSelection, }: PresentationEditorProps) { - const [form] = Form.useForm(); const queryClient = useQueryClient(); const navigate = useNavigate(); const breakpoints = Grid.useBreakpoint(); @@ -149,45 +149,12 @@ export function PresentationEditor({ id: string; values: PresentationValues; }>(); - const [previewConfig, setPreviewConfig] = useState(config ?? {}); - const [previewBrandValues, setPreviewBrandValues] = useState>({}); const [inquiryDraft, setInquiryDraft] = useState(); const [brandDirty, setBrandDirty] = useState(false); const guardDraft = useEditorDraft(brandDirty || !!recordDraft || !!inquiryDraft); const inquiryRuntime = previewWorkspace?.inquiryForms.find((item) => item.target === "brand"); - const sections = useMemo(() => { - const declaredTemplateFields = (templateContent?.templateFields ?? []).map((field) => ({ - ...field, - binding: field.binding ?? `brand.config.templateData.${field.key}`, - })); - return [ - ...[...new Set(declaredTemplateFields.map((field) => field.page ?? "home"))].map((page) => ({ - key: `template-data:${page}`, - title: "模板专属内容", - description: "这些字段由当前小程序模板定义,保存后发布才会对外展示。", - page, - target: "brand" as const, - fields: declaredTemplateFields.filter((field) => (field.page ?? "home") === page), - })), - ...(templateContent?.admin.sections ?? []), - ].map((section) => ({ - ...section, - fields: section.fields.filter( - (field) => - field.binding.startsWith("brand.config.") || - [ - "brand.name", - "brand.tagline", - "brand.avatarUrl", - "brand.description", - "brand.contactPhone", - "brand.contactWechat", - "brand.address", - ].includes(field.binding), - ), - })); - }, [templateContent]); + const sections = useBrandPresentationSections(templateContent); const pageOptions = useMemo(() => { const pages = new Map(); for (const item of templateContent?.navigation ?? []) pages.set(item.page, item.label); @@ -248,23 +215,10 @@ export function PresentationEditor({ selectedTarget?.source === "offering" || selectedTarget?.source === "trust" ? selectedTarget.source : undefined; - const offeringsQuery = useQuery({ - queryKey: ["admin-offerings"], - queryFn: () => createApiClient().listAdminOfferings(), - enabled: selectedRecordSource === "offering", - refetchOnMount: "always", - }); - const trustQuery = useQuery({ - queryKey: ["trust-content"], - queryFn: () => createApiClient().listAdminTrustContent(), - enabled: selectedRecordSource === "trust", - }); - const selectedRecord = - selectedRecordSource === "offering" - ? offeringsQuery.data?.find((item) => item.id === selection?.recordId) - : selectedRecordSource === "trust" - ? trustQuery.data?.find((item) => item.id === selection?.recordId) - : undefined; + const { offeringsQuery, trustQuery, selectedRecord } = usePresentationRecordQueries( + selectedRecordSource, + selection?.recordId, + ); const editableSections = filterSectionsForPreviewTarget( visibleSections.filter((section) => section.fields.some((field) => field.binding.startsWith("brand.")), @@ -342,58 +296,9 @@ export function PresentationEditor({ return item.target === selectedSection.target; }) : pageLinks; - const initialValues = useMemo(() => { - const values: PresentationValues = {}; - for (const section of sections) { - for (const field of section.fields) { - values[presentationFieldName(section.key, field.key)] = readPresentationValue( - config, - field.binding, - field, - brand as unknown as Record, - ); - } - } - return values; - }, [config, sections]); - - const save = useMutation({ - mutationFn: (values: PresentationValues) => { - const nextConfig = applyPresentationValues(config, sections, values); - // 页面内容编辑不提交模板选择,避免触发切换模板的权限校验。 - const contentConfig = { ...nextConfig }; - delete contentConfig.visualTemplateKey; - const standard = applyStandardBrandValues( - brand as unknown as Record, - sections, - values, - ); - const changed = Object.fromEntries( - Object.entries(standard).filter( - ([key, value]) => - key !== "config" && value !== (brand as unknown as Record)[key], - ), - ); - return createApiClient().updateAdminBrand({ - ...changed, - config: contentConfig, - }); - }, - onSuccess: () => { - setBrandDirty(false); - message.success("页面内容已保存为草稿,发布后小程序才会更新"); - window.dispatchEvent(new Event("template-preview-refresh")); - void queryClient.invalidateQueries({ queryKey: ["admin-brand"] }); - void queryClient.invalidateQueries({ queryKey: ["admin-workspace"] }); - void queryClient.invalidateQueries({ queryKey: ["admin-preview-workspace"] }); - void queryClient.invalidateQueries({ queryKey: ["public-runtime-workspace"] }); - void queryClient.invalidateQueries({ queryKey: ["publication-readiness"] }); - }, - }); - - useEffect(() => { - form.setFieldsValue(initialValues); - }, [form, initialValues]); + const formState = useBrandPresentationForm({ brand, config, sections }); + const { form, initialValues } = formState; + const save = useBrandSaveMutation({ ...formState, brand, config, sections, queryClient }); useEffect(() => { const initialPage = @@ -453,62 +358,16 @@ export function PresentationEditor({ () => setRecordDraft(undefined), [selection?.targetKey, selection?.recordId, selectedPage], ); - useEffect(() => { - setPreviewConfig(config ?? {}); - setPreviewBrandValues({}); - }, [config, initialValues]); - const previewBrand = useMemo( - () => ({ ...brand, ...previewBrandValues, config: previewConfig }), - [brand, previewBrandValues, previewConfig], - ); - const recordPreview = useMemo(() => { - if (!recordDraft || !selectedRecord || !recordSection) return undefined; - const config = applyPresentationValues( - selectedRecord.config, - [recordSection], - recordDraft.values, - ); - return { - config, - standard: applyStandardEntityValues( - selectedRecord as unknown as Record, - recordDraft.source, - [recordSection], - recordDraft.values, - ), - }; - }, [recordDraft, selectedRecord, recordSection]); - const handleValuesChange = useCallback( - (changed: PresentationValues, allValues: PresentationValues) => { - setBrandDirty(true); - const synchronized: PresentationValues = { - ...(form.getFieldsValue(true) as PresentationValues), - ...allValues, - }; - for (const section of sections) { - for (const field of section.fields) { - const name = presentationFieldName(section.key, field.key); - if (!Object.prototype.hasOwnProperty.call(changed, name)) continue; - for (const peer of sections) { - for (const item of peer.fields) { - if (item.binding === field.binding) - synchronized[presentationFieldName(peer.key, item.key)] = changed[name]; - } - } - } - } - form.setFieldsValue(synchronized); - const next = applyBrandPreviewValues( - brand as unknown as Record, - config, - sections, - synchronized, - ); - setPreviewConfig((next.config as Record) ?? {}); - setPreviewBrandValues(next); - }, - [brand, config, sections, form], - ); + const { previewBrand, handleValuesChange, resetPreview } = useBrandPreviewDraft({ + brand, + config, + sections, + form, + onDirty: () => setBrandDirty(true), + }); + const recordPreview = useRecordPreview({ recordDraft, selectedRecord, recordSection }); + useEffect(() => resetPreview(), [config, initialValues, resetPreview]); + const previewConfig = previewBrand.config; const draftWorkspace = useMemo(() => { if (!previewWorkspace) return undefined; const next: RuntimeWorkspace = { @@ -652,8 +511,7 @@ export function PresentationEditor({ guardDraft(() => { setBrandDirty(false); form.setFieldsValue(initialValues); - setPreviewConfig(config ?? {}); - setPreviewBrandValues({}); + resetPreview(); setRecordDraft(undefined); setInquiryDraft(undefined); setActivePage(value); @@ -669,8 +527,7 @@ export function PresentationEditor({ guardDraft(() => { setBrandDirty(false); form.setFieldsValue(initialValues); - setPreviewConfig(config ?? {}); - setPreviewBrandValues({}); + resetPreview(); setRecordDraft(undefined); setInquiryDraft(undefined); setActivePage(String(value)); diff --git a/apps/admin/src/features/brand/presentation-editor-record-preview.ts b/apps/admin/src/features/brand/presentation-editor-record-preview.ts new file mode 100644 index 0000000..533ac9e --- /dev/null +++ b/apps/admin/src/features/brand/presentation-editor-record-preview.ts @@ -0,0 +1,39 @@ +import { useMemo } from "react"; +import type { Offering, TrustContent } from "@personal-brand/api-client"; +import type { TemplateAdminSection } from "@personal-brand/api-client"; +import { applyPresentationValues, applyStandardEntityValues } from "./presentation-bindings.js"; +import type { PresentationValues } from "./presentation-bindings.js"; + +export interface RecordDraft { + source: "offering" | "trust"; + id: string; + values: PresentationValues; +} + +export function useRecordPreview({ + recordDraft, + selectedRecord, + recordSection, +}: { + recordDraft?: RecordDraft | undefined; + selectedRecord?: Offering | TrustContent | undefined; + recordSection?: TemplateAdminSection | undefined; +}) { + return useMemo(() => { + if (!recordDraft || !selectedRecord || !recordSection) return undefined; + const config = applyPresentationValues( + selectedRecord.config, + [recordSection], + recordDraft.values, + ); + return { + config, + standard: applyStandardEntityValues( + selectedRecord as unknown as Record, + recordDraft.source, + [recordSection], + recordDraft.values, + ), + }; + }, [recordDraft, selectedRecord, recordSection]); +} diff --git a/apps/admin/src/features/brand/presentation-editor-state.ts b/apps/admin/src/features/brand/presentation-editor-state.ts new file mode 100644 index 0000000..dee7a9a --- /dev/null +++ b/apps/admin/src/features/brand/presentation-editor-state.ts @@ -0,0 +1,226 @@ +import { Form, message } from "antd"; +import { useMutation, useQuery } from "@tanstack/react-query"; +import type { QueryClient } from "@tanstack/react-query"; +import { useEffect, useMemo, useState } from "react"; +import type { FormInstance } from "antd"; +import type { + AdminTemplateContent, + BrandProfile, + Offering, + TemplateAdminSection, + TrustContent, +} from "@personal-brand/api-client"; +import { createApiClient } from "../../lib/api.js"; +import { + applyBrandPreviewValues, + applyPresentationValues, + applyStandardBrandValues, + presentationFieldName, + readPresentationValue, + type PresentationValues, +} from "./presentation-bindings.js"; + +const standardBrandBindings = [ + "brand.name", + "brand.tagline", + "brand.avatarUrl", + "brand.description", + "brand.contactPhone", + "brand.contactWechat", + "brand.address", +] as const; + +export interface BrandPresentationFormState { + form: FormInstance; + initialValues: PresentationValues; +} + +export function useBrandPresentationSections( + templateContent: AdminTemplateContent | null | undefined, +): TemplateAdminSection[] { + return useMemo(() => { + const declaredTemplateFields = (templateContent?.templateFields ?? []).map((field) => ({ + ...field, + binding: field.binding ?? `brand.config.templateData.${field.key}`, + })); + return [ + ...[...new Set(declaredTemplateFields.map((field) => field.page ?? "home"))].map((page) => ({ + key: `template-data:${page}`, + title: "模板专属内容", + description: "这些字段由当前小程序模板定义,保存后发布才会对外展示。", + page, + target: "brand" as const, + fields: declaredTemplateFields.filter((field) => (field.page ?? "home") === page), + })), + ...(templateContent?.admin.sections ?? []), + ].map((section) => ({ + ...section, + fields: section.fields.filter( + (field) => + field.binding.startsWith("brand.config.") || + (standardBrandBindings as readonly string[]).includes(field.binding), + ), + })); + }, [templateContent]); +} + +export function useBrandPresentationForm({ + brand, + config, + sections, +}: { + brand: BrandProfile; + config: Record | null | undefined; + sections: TemplateAdminSection[]; +}): BrandPresentationFormState { + const [form] = Form.useForm(); + const initialValues = useMemo(() => { + const values: PresentationValues = {}; + for (const section of sections) { + for (const field of section.fields) { + values[presentationFieldName(section.key, field.key)] = readPresentationValue( + config, + field.binding, + field, + brand as unknown as Record, + ); + } + } + return values; + }, [brand, config, sections]); + + useEffect(() => form.setFieldsValue(initialValues), [form, initialValues]); + return { form, initialValues }; +} + +interface BrandSaveMutationOptions extends BrandPresentationFormState { + brand: BrandProfile; + config: Record | null | undefined; + sections: TemplateAdminSection[]; + queryClient: QueryClient; +} + +export function useBrandSaveMutation({ + brand, + config, + sections, + queryClient, +}: BrandSaveMutationOptions) { + return useMutation({ + mutationFn: (values: PresentationValues) => { + const nextConfig = applyPresentationValues(config, sections, values); + const contentConfig = { ...nextConfig }; + delete contentConfig.visualTemplateKey; + const standard = applyStandardBrandValues( + brand as unknown as Record, + sections, + values, + ); + const changed = Object.fromEntries( + Object.entries(standard).filter( + ([key, value]) => + key !== "config" && value !== (brand as unknown as Record)[key], + ), + ); + return createApiClient().updateAdminBrand({ ...changed, config: contentConfig }); + }, + onSuccess: () => { + message.success("页面内容已保存为草稿,发布后小程序才会更新"); + window.dispatchEvent(new Event("template-preview-refresh")); + void queryClient.invalidateQueries({ queryKey: ["admin-brand"] }); + void queryClient.invalidateQueries({ queryKey: ["admin-workspace"] }); + void queryClient.invalidateQueries({ queryKey: ["admin-preview-workspace"] }); + void queryClient.invalidateQueries({ queryKey: ["public-runtime-workspace"] }); + void queryClient.invalidateQueries({ queryKey: ["publication-readiness"] }); + }, + }); +} + +export function useBrandPreviewDraft({ + brand, + config, + sections, + form, + onDirty, +}: { + brand: BrandProfile; + config: Record | null | undefined; + sections: TemplateAdminSection[]; + form: BrandPresentationFormState["form"]; + onDirty: () => void; +}) { + const [previewConfig, setPreviewConfig] = useState(config ?? {}); + const [previewBrandValues, setPreviewBrandValues] = useState>({}); + + useEffect(() => { + setPreviewConfig(config ?? {}); + setPreviewBrandValues({}); + }, [config, form]); + + const handleValuesChange = (changed: PresentationValues, allValues: PresentationValues) => { + onDirty(); + const synchronized: PresentationValues = { + ...(form.getFieldsValue(true) as PresentationValues), + ...allValues, + }; + for (const section of sections) { + for (const field of section.fields) { + const name = presentationFieldName(section.key, field.key); + if (!Object.prototype.hasOwnProperty.call(changed, name)) continue; + for (const peer of sections) { + for (const item of peer.fields) { + if (item.binding === field.binding) + synchronized[presentationFieldName(peer.key, item.key)] = changed[name]; + } + } + } + } + form.setFieldsValue(synchronized); + const next = applyBrandPreviewValues( + brand as unknown as Record, + config, + sections, + synchronized, + ); + setPreviewConfig((next.config as Record) ?? {}); + setPreviewBrandValues(next); + }; + + const previewBrand = useMemo( + () => ({ ...brand, ...previewBrandValues, config: previewConfig }), + [brand, previewBrandValues, previewConfig], + ); + + return { + previewBrand, + handleValuesChange, + resetPreview: () => { + setPreviewConfig(config ?? {}); + setPreviewBrandValues({}); + }, + }; +} + +export function usePresentationRecordQueries( + source: "offering" | "trust" | undefined, + recordId: string | undefined, +) { + const offeringsQuery = useQuery({ + queryKey: ["admin-offerings"], + queryFn: () => createApiClient().listAdminOfferings(), + enabled: source === "offering", + refetchOnMount: "always", + }); + const trustQuery = useQuery({ + queryKey: ["trust-content"], + queryFn: () => createApiClient().listAdminTrustContent(), + enabled: source === "trust", + }); + const selectedRecord = + source === "offering" + ? offeringsQuery.data?.find((item: Offering) => item.id === recordId) + : source === "trust" + ? trustQuery.data?.find((item: TrustContent) => item.id === recordId) + : undefined; + return { offeringsQuery, trustQuery, selectedRecord }; +} diff --git a/docs/code-standards.md b/docs/code-standards.md new file mode 100644 index 0000000..b2f233e --- /dev/null +++ b/docs/code-standards.md @@ -0,0 +1,50 @@ +# 代码结构与重构标准 + +这份标准用于控制现有模块继续膨胀,并约束后续大文件重构。它不是替代 `docs/engineering-delivery-checklist.md`,而是补充结构边界。 + +## 通用规则 + +- 页面、Controller、Service 只保留一个明确入口;独立业务规则、数据映射、授权判断和视图状态必须拆出命名模块。 +- 单文件超过 500 行必须提供拆分计划;超过 800 行应拆分。拆分要按职责,不按行数机械切分。 +- 禁止在页面组件内内联完整 API 调用、复杂 JSON 转换和多层级业务规则。 +- 禁止新增全局工具函数堆积文件;按领域模块导出,不建 `utils.ts` 黑洞。 +- 迁移、DTO、API Client 类型、页面、测试和文档随行为一起变更。 + +## Admin React 标准 + +- 页面组件负责组合布局和路由;不直接实现超过一个相关领域的业务逻辑。 +- 一个页面由以下边界组成: + - 页面组件:布局、路由、页面状态组合。 + - hooks:数据查询、mutation、表单初始化、草稿与预览状态。 + - 领域工具:纯函数,可单测,不调用 `fetch`。 + - feature 组件:局部 UI 区块。 + - shared components:跨 feature 使用的表单字段、状态和基础控件。 +- React Query 的 query key、失效和成功提示统一放在 hooks 中;页面不要散落 `invalidateQueries`。 +- 表单初始化、同步字段、脏检查和失败恢复不能重复实现;优先复用同一模块。 +- 类型边界使用 API Client 导出类型,不在页面重建后端响应形状。 + +## API NestJS 标准 + +- Controller 只处理认证入口、DTO、状态码、响应形状和路由。 +- 授权、Prisma、模板安装、快照组装、工作流推进必须进入 Service 或 Guard。 +- 同一个领域不要分散在根目录和 modules 中;新代码必须归入领域模块,旧 Controller 重构时逐步迁移。 +- DTO 是唯一输入边界;禁止 `Partial`、`any`、未验证 JSON 和 Controller 内私有 schema。 +- 授权测试、成功行为、失败路径和品牌隔离测试是结构重构不可删除的回归线。 + +## API Client 标准 + +- 按资源拆分方法模块和类型模块;`index.ts` 只做聚合导出和 Client 组装。 +- 一个资源定义一组类型、一组方法、一致的错误语义,不在 Client 内做页面专用逻辑。 + +## Config 与模板包标准 + +- manifest、runtime、admin 契约、示例内容分别放独立模块;避免一个大索引文件同时承载所有契约。 +- 模板字段必须声明 binding、输入类型和预览目标;模板键使用 allow-list,不接受任意字符串。 + +## 重构流程 + +1. 先建立或修改标准,再动代码。 +2. 每轮只处理一个高影响热点,保持外部行为不变。 +3. 重构后运行 `pnpm format:check`、`pnpm lint`、`pnpm typecheck`、相关测试和生产构建。 +4. 行为变化必须有测试;纯结构重构也必须保留所有授权、品牌隔离和关键 UI 状态测试。 +5. 在分支完成并全量验证后合并回 `main`。