From a2932b113457480962d9ecd2576f5943aee4ad17 Mon Sep 17 00:00:00 2001 From: que01 Date: Sat, 10 Oct 2026 10:20:14 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E6=95=B4=E7=90=86=E5=93=81?= =?UTF-8?q?=E7=89=8C=E9=85=8D=E7=BD=AE=E4=B8=8E=E5=B0=8F=E7=A8=8B=E5=BA=8F?= =?UTF-8?q?=E7=BC=96=E8=BE=91=E5=B7=A5=E4=BD=9C=E5=8C=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex-tasks/admin-editor-workspace/EPIC.md | 30 +++++ .../admin-editor-workspace/PROGRESS.md | 20 ++++ .../admin-editor-workspace/SUBTASKS.csv | 6 + .../tasks/01-baseline/BASELINE.md | 32 ++++++ apps/admin/src/features/brand/BrandPage.css | 60 ++++++++++ apps/admin/src/features/brand/BrandPage.tsx | 106 ++++++++++++------ .../brand/ComponentTemplatePreview.css | 9 ++ .../brand/ComponentTemplatePreview.tsx | 10 +- .../features/brand/InquiryPreviewEditor.tsx | 10 +- .../src/features/brand/PresentationEditor.css | 104 +++++++++++++++++ .../src/features/brand/PresentationEditor.tsx | 48 ++++---- apps/taro/test/browser/admin-editor.spec.ts | 17 ++- docs/adr/0021-admin-editor-workspace.md | 27 +++++ 13 files changed, 416 insertions(+), 63 deletions(-) create mode 100644 .codex-tasks/admin-editor-workspace/EPIC.md create mode 100644 .codex-tasks/admin-editor-workspace/PROGRESS.md create mode 100644 .codex-tasks/admin-editor-workspace/SUBTASKS.csv create mode 100644 .codex-tasks/admin-editor-workspace/tasks/01-baseline/BASELINE.md create mode 100644 apps/admin/src/features/brand/BrandPage.css create mode 100644 apps/admin/src/features/brand/PresentationEditor.css create mode 100644 docs/adr/0021-admin-editor-workspace.md diff --git a/.codex-tasks/admin-editor-workspace/EPIC.md b/.codex-tasks/admin-editor-workspace/EPIC.md new file mode 100644 index 0000000..4f0e576 --- /dev/null +++ b/.codex-tasks/admin-editor-workspace/EPIC.md @@ -0,0 +1,30 @@ +# Admin 编辑工作区重构 + +## 目标 + +把 Admin 的品牌配置与小程序页面编辑整理成一个层级清晰、可持续扩展的工作区。用户能够明确区分品牌基础资料、模板内容、业务记录和页面预览;页面预览、区域选择和字段编辑保持统一行为。 + +## 交付边界 + +- 品牌资料页面减少 Card 堆叠,形成连续的配置分组。 +- 小程序页面配置成为主要编辑工作区,使用页面导航、预览画布和编辑面板的稳定布局。 +- 详情页只提供业务记录选择和动态预览,不出现品牌级详情编辑表单。 +- 预览选区、高亮、编辑状态、空状态和错误状态保持一致。 +- 不改变后端数据模型和小程序业务语义;模板仍通过 manifest 声明页面、区域和字段。 + +## 设计原则 + +- 基础品牌事实只提供一个编辑入口。 +- 模板专属字段由模板 manifest 驱动,不在共享页面中写行业逻辑。 +- 预览是编辑上下文的一部分,不单独启动每个模板服务。 +- 详情页数据来自选中的业务记录,视觉文案只能作为模板配置存在。 +- 页面区块使用平面分组和分隔线,只有真正需要独立操作的区域使用 Card。 + +## 验收标准 + +- 1920、1280、1024、768 和 390 宽度下布局无横向溢出。 +- 品牌资料、页面配置和发布状态的层级可以在首屏理解。 +- 首页、业务、服务、详情、咨询、成功和记录页面均可切换并保持稳定高度。 +- 点击模板区域后,选区高亮和右侧编辑面板始终同步。 +- 详情页只能选择业务记录并预览,不能出现品牌级详情字段编辑。 +- 通过 Admin/Taro typecheck、模板契约测试、生产构建和关键浏览器交互测试。 diff --git a/.codex-tasks/admin-editor-workspace/PROGRESS.md b/.codex-tasks/admin-editor-workspace/PROGRESS.md new file mode 100644 index 0000000..b645e2a --- /dev/null +++ b/.codex-tasks/admin-editor-workspace/PROGRESS.md @@ -0,0 +1,20 @@ +# Progress + +## 2026-10-10 + +- 建立 Admin 编辑工作区重构 Epic。 +- 当前已知问题:品牌资料上方存在多个连续 Card;小程序页面配置仍是普通 Card;预览区和编辑面板层级不够明确;详情页需要保持动态只读预览;选区高亮需要继续验证真实鼠标路径。 +- 当前基线能力:模板 manifest、Taro renderer、RuntimeWorkspace 和 Admin 字段绑定已经形成契约;本 Epic 主要调整 Admin 信息架构与视觉层。 +- 第 1 项已完成:确认 `BrandPage` 的两列 Card 结构、页面配置固定最小高度、模板说明右栏和编辑器内部重复导航。 +- 第 2 项开始:先整理品牌资料页面层级,减少 Card 作为页面区块容器的使用。 +- 第 2 项阶段性完成:`BrandPage` 已将品牌身份、联系合作、模板视觉改为连续分组,模板说明改为右侧辅助 `Alert`,并增加移动端断点。 +- 验证:Admin typecheck 通过,`admin-editor.spec.ts` 2 项通过。 +- 第 2 项完成,第 3 项开始:`PresentationEditor` 已移除外层 Card 和固定最小高度,改为独立工作区标题区;下一步处理工作区内部布局和视觉状态。 + +- 工作区完成:品牌配置使用连续分组;模板辅助信息移入基础资料尾部;编辑器使用完整宽度两栏布局,窄屏上下排列。 +- 未选中时显示引导,详情页目标列表为空且不显示点选工具。 +- 新增 1920/1280/1024/768/390 宽度无溢出断言和截图,已人工查看 1280 与 390 截图。 +- 验证通过:Admin/Taro typecheck、Admin lint、全仓 format:check、19 项模板契约测试、Admin build、2 项浏览器测试。 +- lint 暴露已有 InquiryPreviewEditor 类型问题,已通过 Form 泛型和普通对象传入修复。 +- 保留已知构建 api chunk 超过 500 kB 提示,后续由 Admin 前端打包优化任务负责;记录在 ADR 0021。 +- 本轮不涉及新增 API 或数据迁移。 diff --git a/.codex-tasks/admin-editor-workspace/SUBTASKS.csv b/.codex-tasks/admin-editor-workspace/SUBTASKS.csv new file mode 100644 index 0000000..064ce0d --- /dev/null +++ b/.codex-tasks/admin-editor-workspace/SUBTASKS.csv @@ -0,0 +1,6 @@ +id,title,status,task_type,depends_on,acceptance_criteria,validation_command,task_dir,notes +1,建立现状基线与页面覆盖清单,DONE,single-full,,记录当前布局层级、Card 使用、响应式问题和关键交互,测试基线截图与 DOM 检查,.codex-tasks/admin-editor-workspace/tasks/01-baseline/,已完成代码结构基线与验证记录 +2,重构品牌配置的信息架构,DONE,single-full,1,品牌资料按身份联系模板视觉分组且减少卡片嵌套,Admin typecheck; browser brand page test,.codex-tasks/admin-editor-workspace/tasks/02-information-architecture/,已完成分组与模板说明层级调整 +3,重构小程序页面编辑工作区,DONE,single-full,1;2,页面导航预览画布编辑面板形成稳定三栏或响应式两栏布局,Admin build; browser editor test,.codex-tasks/admin-editor-workspace/tasks/03-workspace-ui/,完整宽度两栏工作区,窄屏堆叠;详情页只读;未选中显示引导 +4,统一编辑器视觉系统与状态样式,DONE,single-full,3,间距层级按钮选区空状态错误状态统一且无 Card 堆叠,Prettier; Admin build; screenshot review,.codex-tasks/admin-editor-workspace/tasks/04-visual-system/,统一导航工具条、画布边界、区域按钮和面板间距;已检查 1280 与 390 截图 +5,全页面回归与交付验收,DONE,single-full,2;3;4,关键页面交互和响应式检查通过并记录残余风险,validate:templates; typecheck; build; browser tests,.codex-tasks/admin-editor-workspace/tasks/05-regression/,5 种宽度无溢出;浏览器 2 项、契约 19 项、格式、lint、类型和构建通过 diff --git a/.codex-tasks/admin-editor-workspace/tasks/01-baseline/BASELINE.md b/.codex-tasks/admin-editor-workspace/tasks/01-baseline/BASELINE.md new file mode 100644 index 0000000..ae82b19 --- /dev/null +++ b/.codex-tasks/admin-editor-workspace/tasks/01-baseline/BASELINE.md @@ -0,0 +1,32 @@ +# 当前基线 + +## 页面结构 + +- `BrandPage` 使用两列布局:左侧 `xl=16`,右侧 `xl=8`。 +- 左侧依次渲染“我是谁”“如何联系与合作”“模板与品牌视觉”三个 `Card`。 +- 左侧表单之后渲染“小程序页面配置” `Card`。 +- 右侧单独渲染“模板说明” `Card`。 +- 页面配置内部还有页面导航、页面预览、详情业务选择器、预览目标按钮和右侧编辑表单。 + +## 已确认问题 + +- 配置 Card 与页面编辑 Card 在视觉上处于同一层级,用户难以判断基础资料和页面编辑的关系。 +- “模板说明”占据右侧固定列,但对编辑流程帮助有限,造成首屏空间浪费。 +- 页面配置使用 `minHeight: 760/620`,内容较少的页面会出现大面积空白。 +- 页面配置内部的预览目标按钮与画布选区重复表达同一件事。 +- 详情页已经改为动态预览提示,但页面整体仍沿用通用编辑器的表单布局。 +- 品牌资料表单保存按钮位于所有配置分组之后,长页面中不够容易发现。 + +## 现有可复用能力 + +- 模板 manifest 声明页面、区域、字段和 preview target。 +- `RuntimeWorkspace` 为组件预览提供品牌、业务记录、信任内容和咨询表单数据。 +- `ComponentTemplatePreview` 支持点选、高亮、组合区域和浏览模式。 +- `PresentationEditor` 已支持业务记录编辑、信任内容编辑和咨询字段编辑。 + +## 基线验证 + +- `pnpm --filter @personal-brand/admin typecheck`:通过。 +- `pnpm --filter @personal-brand/taro typecheck`:通过。 +- `pnpm validate:templates`:19 项模板契约测试通过。 +- 已有 `admin-editor.spec.ts` 覆盖页面切换、预览选区、业务记录、信任内容、咨询表单和详情页动态预览。 diff --git a/apps/admin/src/features/brand/BrandPage.css b/apps/admin/src/features/brand/BrandPage.css new file mode 100644 index 0000000..2c2a741 --- /dev/null +++ b/apps/admin/src/features/brand/BrandPage.css @@ -0,0 +1,60 @@ +.brand-page__content { + max-width: 960px; +} + +.brand-page__settings { + min-width: 0; +} + +.brand-settings-section { + padding: 24px 0; + border-top: 1px solid #f0f0f0; +} + +.brand-settings-section:first-child { + padding-top: 8px; + border-top: 0; +} + +.brand-settings-section__header { + display: flex; + align-items: flex-start; + justify-content: space-between; + gap: 16px; + margin-bottom: 20px; +} + +.brand-settings-section__header .ant-typography { + margin: 0; +} + +.brand-settings-section__header .ant-typography + .ant-typography { + display: block; + margin-top: 4px; +} + +.brand-page__template-note { + margin-top: 24px; +} + +@media (max-width: 1199px) { + .brand-page__content { + display: block; + } + + .brand-page__template-note { + position: static; + margin-top: 24px; + } +} + +@media (max-width: 575px) { + .brand-settings-section__header { + display: block; + } + + .brand-settings-section__header .ant-tag { + display: inline-block; + margin-top: 10px; + } +} diff --git a/apps/admin/src/features/brand/BrandPage.tsx b/apps/admin/src/features/brand/BrandPage.tsx index 58cd10a..a8d7371 100644 --- a/apps/admin/src/features/brand/BrandPage.tsx +++ b/apps/admin/src/features/brand/BrandPage.tsx @@ -1,4 +1,16 @@ -import { Button, Card, Col, Form, Input, Row, Select, Space, Tag, Typography, message } from "antd"; +import { + Alert, + Button, + Col, + Form, + Input, + Row, + Select, + Space, + Tag, + Typography, + message, +} from "antd"; import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; import type { BrandProfile } from "@personal-brand/api-client"; import { createApiClient } from "../../lib/api.js"; @@ -6,6 +18,7 @@ import { AdminPageHeader } from "../../components/AdminPageHeader.js"; import { ImageUrlField } from "../../components/ImageUrlField.js"; import { MutationError, QueryState } from "../../components/QueryState.js"; import { PresentationEditor } from "./PresentationEditor.js"; +import "./BrandPage.css"; export function BrandPage() { const client = createApiClient(); @@ -38,21 +51,31 @@ export function BrandPage() { <> {template.data?.name ?? "当前模板"}} /> - - +
+
save.mutate(values)} > - 公开展示} - > +
+
+
+ + 我是谁 + + 公开展示的品牌身份和定位。 +
+ 品牌基础信息 +
- - +
+
+
+
+ + 如何联系与合作 + + + 让访客知道联系渠道、服务范围和响应预期。 + +
+
@@ -108,8 +141,18 @@ export function BrandPage() { > - - +
+
+
+
+ + 模板与品牌视觉 + + + 模板负责业务表达,品牌信息仍由你统一维护。 + +
+
- +
- + {template.data ? ( + - - - {template.data && ( - - {template.data.description} - - 服务分类:{template.data.serviceCategories.join("、")} - - - )} - - + ) : null} +
+ )} diff --git a/apps/admin/src/features/brand/ComponentTemplatePreview.css b/apps/admin/src/features/brand/ComponentTemplatePreview.css index a2ddfb4..8d48e6b 100644 --- a/apps/admin/src/features/brand/ComponentTemplatePreview.css +++ b/apps/admin/src/features/brand/ComponentTemplatePreview.css @@ -133,3 +133,12 @@ text-overflow: ellipsis; white-space: nowrap; } + +.component-template-preview__tools[hidden] { + display: none; +} + +.component-template-preview-shell:has(.component-template-preview__tools[hidden]) + .component-template-preview { + height: 100%; +} diff --git a/apps/admin/src/features/brand/ComponentTemplatePreview.tsx b/apps/admin/src/features/brand/ComponentTemplatePreview.tsx index eaa18dd..8fb8d45 100644 --- a/apps/admin/src/features/brand/ComponentTemplatePreview.tsx +++ b/apps/admin/src/features/brand/ComponentTemplatePreview.tsx @@ -129,7 +129,11 @@ export function ComponentTemplatePreview({ return ; return (
-
+