From 1ea757555dae7f6eaa5c6486be633000070eec07 Mon Sep 17 00:00:00 2001 From: que01 Date: Wed, 23 Sep 2026 11:07:57 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E6=98=8E=E7=A1=AE=E5=A4=9A?= =?UTF-8?q?=E5=93=81=E7=89=8C=E5=90=8E=E5=8F=B0=E5=B7=A5=E4=BD=9C=E5=8C=BA?= =?UTF-8?q?=E8=AF=AD=E4=B9=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codex-tasks/tenant-architecture-epic/EPIC.md | 20 +++++++++++++ .../tenant-architecture-epic/PROGRESS.md | 13 ++++++++ .../tenant-architecture-epic/SUBTASKS.csv | 4 +++ .../tasks/admin-context/PROGRESS.md | 7 +++++ apps/admin/src/main.tsx | 16 +++++++--- ...006-multibrand-admin-and-api-boundaries.md | 30 +++++++++++++++++++ packages/api-client/src/index.ts | 1 + 7 files changed, 87 insertions(+), 4 deletions(-) create mode 100644 .codex-tasks/tenant-architecture-epic/EPIC.md create mode 100644 .codex-tasks/tenant-architecture-epic/PROGRESS.md create mode 100644 .codex-tasks/tenant-architecture-epic/SUBTASKS.csv create mode 100644 .codex-tasks/tenant-architecture-epic/tasks/admin-context/PROGRESS.md create mode 100644 docs/adr/0006-multibrand-admin-and-api-boundaries.md diff --git a/.codex-tasks/tenant-architecture-epic/EPIC.md b/.codex-tasks/tenant-architecture-epic/EPIC.md new file mode 100644 index 0000000..7ed465b --- /dev/null +++ b/.codex-tasks/tenant-architecture-epic/EPIC.md @@ -0,0 +1,20 @@ +# 多品牌后台与 API 架构收口 + +## 目标 + +让后台明确运行在“当前品牌工作区”上下文中,让品牌内容、模板、业务提供项、信任内容和咨询数据都属于当前品牌;同时拆分 API Controller,避免 `main.ts` 继续成为业务代码集中点。 + +## 原则 + +- `brandId` 来自认证后的 membership,不信任客户端传入。 +- 后台页面表达“当前品牌工作区”,而不是假设系统只有一个品牌。 +- Controller 只做 transport,业务查询和状态逻辑进入 feature service。 +- `main.ts` 只保留应用装配和模块注册。 +- 每次拆分保持现有 API 路径和响应契约不变。 + +## 验收 + +- 后台导航和页面显示当前品牌上下文。 +- 多品牌授权测试继续通过。 +- API Controller 按 public、customer、admin feature 拆分。 +- API、Admin build、miniapp fixture 全量通过。 diff --git a/.codex-tasks/tenant-architecture-epic/PROGRESS.md b/.codex-tasks/tenant-architecture-epic/PROGRESS.md new file mode 100644 index 0000000..afd79a2 --- /dev/null +++ b/.codex-tasks/tenant-architecture-epic/PROGRESS.md @@ -0,0 +1,13 @@ +# 进度 + +- 任务:多品牌后台与 API 架构收口 +- 形态:epic +- 进度:1/3 +- 当前:API Controller 拆分 +- 真相文件:`SUBTASKS.csv` + +## 已完成 + +- 后台导航改为当前品牌工作区语义。 +- Header 显示当前认证品牌名称。 +- 保持 membership 授权和现有 API 契约不变。 diff --git a/.codex-tasks/tenant-architecture-epic/SUBTASKS.csv b/.codex-tasks/tenant-architecture-epic/SUBTASKS.csv new file mode 100644 index 0000000..70a443d --- /dev/null +++ b/.codex-tasks/tenant-architecture-epic/SUBTASKS.csv @@ -0,0 +1,4 @@ +id,title,task_type,depends_on,status,task_dir,acceptance_criteria,validation_command,notes +1,当前品牌工作区语义,single-full,,DONE,tasks/admin-context,后台明确当前品牌并保持 membership 隔离,pnpm --filter @personal-brand/admin build && pnpm --filter @personal-brand/api test:integration,已完成 +2,API Controller 拆分,single-full,1,TODO,tasks/api-split,main.ts 仅保留装配和跨模块基础代码,pnpm --filter @personal-brand/api typecheck && pnpm --filter @personal-brand/api test:integration, +3,架构回归收口,single-full,2,TODO,tasks/regression,Admin 和 miniapp 回归全部通过,pnpm --filter @personal-brand/admin build && pnpm --filter @personal-brand/miniapp test:fixture, diff --git a/.codex-tasks/tenant-architecture-epic/tasks/admin-context/PROGRESS.md b/.codex-tasks/tenant-architecture-epic/tasks/admin-context/PROGRESS.md new file mode 100644 index 0000000..33dfdf3 --- /dev/null +++ b/.codex-tasks/tenant-architecture-epic/tasks/admin-context/PROGRESS.md @@ -0,0 +1,7 @@ +# 当前品牌工作区语义 + +状态:DONE + +- 后台导航使用“当前品牌概览 / 当前品牌表达”。 +- 顶部显示认证会话对应的当前品牌名称。 +- Admin build 和 API 集成测试通过。 diff --git a/apps/admin/src/main.tsx b/apps/admin/src/main.tsx index 2ffc77a..cc05015 100644 --- a/apps/admin/src/main.tsx +++ b/apps/admin/src/main.tsx @@ -1,6 +1,7 @@ import React, { Suspense, useState } from "react"; import { createRoot } from "react-dom/client"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { useQuery } from "@tanstack/react-query"; import { App, Button, Card, Form, Input, Layout, Menu, Space, Typography, message } from "antd"; import { createApiClient } from "./lib/api.js"; const FeatureInquiriesPage = React.lazy(() => @@ -77,10 +78,14 @@ function Login({ onLogin }: { onLogin: () => void }) { function Dashboard({ onLogout }: { onLogout: () => void }) { const navigate = useNavigate(); const location = useLocation(); + const brand = useQuery({ + queryKey: ["admin-shell-brand"], + queryFn: () => createApiClient().getAdminBrand(), + }); const page = location.pathname.split("/")[2] || "overview"; const items = [ - { key: "overview", label: "品牌概览" }, - { key: "brand", label: "品牌表达" }, + { key: "overview", label: "当前品牌概览" }, + { key: "brand", label: "当前品牌表达" }, { key: "trust", label: "信任内容" }, { key: "services", label: "业务提供项" }, { key: "workspace", label: "模板与设置" }, @@ -91,7 +96,7 @@ function Dashboard({ onLogout }: { onLogout: () => void }) { - 个人品牌 + 当前品牌工作区 void }) { alignItems: "center", }} > - 品牌管理后台 + + {brand.data?.name || "当前品牌"} + 品牌工作区 + diff --git a/docs/adr/0006-multibrand-admin-and-api-boundaries.md b/docs/adr/0006-multibrand-admin-and-api-boundaries.md new file mode 100644 index 0000000..2fae078 --- /dev/null +++ b/docs/adr/0006-multibrand-admin-and-api-boundaries.md @@ -0,0 +1,30 @@ +# 0006 多品牌后台上下文与 API 边界 + +## 背景 + +系统已经使用 `BrandMembership` 和认证 identity 的 `brandId` 做数据隔离,但后台导航和页面文案仍然采用单品牌语义;同时 `apps/api/src/main.ts` 聚合了多个领域 Controller,导致新增行业能力时维护成本持续上升。 + +## 决策 + +- 后台所有品牌内容页面都明确属于“当前品牌工作区”。 +- 品牌上下文由管理员 membership 和会话决定,客户端不能提交 `brandId` 覆盖它。 +- API 按 `public`、`customer`、`admin` 领域拆分 Controller;Controller 保持 transport 职责,业务逻辑进入 service。 +- 保持现有 URL 和响应契约,拆分只改变代码 ownership,不改变客户端行为。 + +## 备选方案 + +- 继续向 `main.ts` 添加 Controller:短期快,但会形成不可维护的领域耦合。 +- 在每个页面自行传 `brandId`:容易越权,不采用。 +- 为每个行业复制一套 Controller:破坏模板复用,不采用。 + +## 后果 + +- 会产生一次代码搬迁和测试调整成本。 +- 后续增加品牌切换、品牌成员管理时有清晰入口。 +- 行业模板只影响 Runtime 配置,不影响租户边界。 + +## 迁移计划 + +1. 先完成后台当前品牌上下文语义和回归测试。 +2. 抽离公开、客户、管理员 Controller 文件。 +3. 再把跨 Controller 的查询和状态规则下沉到 feature service。 diff --git a/packages/api-client/src/index.ts b/packages/api-client/src/index.ts index 501b995..8cb1a4e 100644 --- a/packages/api-client/src/index.ts +++ b/packages/api-client/src/index.ts @@ -11,6 +11,7 @@ export type { BookingStatus } from "@personal-brand/types"; export interface BrandProfile { id: string; + slug?: string; name: string; templateKey: BrandTemplateKey; tagline: string | null;