tkmind_go/documentation/docs/guides/plaza/01-architecture.md

sidebar_position, title, sidebar_label, description

sidebar_position	title	sidebar_label	description
2	系统架构	系统架构	Plaza 的整体架构、技术选型、部署结构和服务边界

系统架构

总体架构

┌─────────────────────────────────────────────────────────────────┐
│                        用户访问层                                │
│                                                                 │
│   游客/浏览者              登录用户               运营人员        │
│   /plaza, /u/:slug        /space, /chat          /ops           │
└───────────┬────────────────────┬──────────────────┬────────────┘
            │                   │                  │
            ▼                   ▼                  ▼
┌───────────────────────────────────────────────────────────────┐
│                    Nginx 统一入口（go.tkmind.cn）              │
│                                                               │
│  /plaza, /u/  →  Next.js :3001    /ops  →  Ops SPA :3002     │
│  /api         →  Node.js :18006   /     →  H5 SPA :8080      │
└───────────────────────────┬───────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │  Plaza 前端  │ │ MindSpace H5 │ │   运营后台   │
    │  Next.js SSR │ │  Vite CSR   │ │  Vite CSR   │
    │  ui/plaza/  │ │  ui/h5/     │ │  ui/ops/    │
    └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
           │                │                │
           └────────────────┼────────────────┘
                            │  HTTP /api/*
                            ▼
            ┌───────────────────────────────┐
            │       Node.js 后端服务        │
            │                               │
            │  /api/mindspace/v1/*          │
│  /api/plaza/v1/*    （新增，plaza-*.mjs）│
│  /api/ops/v1/*      （新增，ops-*.mjs）  │
            │  /auth/*                      │
            └───────────────┬───────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │    MySQL     │ │  文件存储    │ │    Redis     │
    │  共用数据库  │ │  本地/OSS   │ │  热度计数    │
    │  + plaza_*表 │ │  + 缩略图   │ │  + feed缓存  │
    └──────────────┘ └──────────────┘ └──────────────┘

技术选型

Plaza 前端（ui/plaza/）

技术	选型	原因
框架	Next.js 14+ App Router	原生 SSR/SSG，SEO 最佳实践
语言	TypeScript	与现有 H5 保持一致
样式	Tailwind CSS	快速开发，与 H5 互不干扰
状态管理	React Server Components + SWR	服务端数据优先，客户端增量更新
图片优化	next/image	自动 WebP、懒加载、尺寸优化
分析	自建埋点（复用后端 analytics API）	不依赖第三方

运营后台（ui/ops/）

技术	选型	原因
框架	Vite + React	与 H5 工具链一致，快速启动
UI 组件库	复用现有组件风格	不引入新依赖
权限	独立 ops_role 中间件	与普通 admin 权限隔离

后端扩展

模块	实现方式
Plaza API	在现有 Node 服务中新增 /api/plaza/v1/ 路由模块
热度计数	Redis INCR + 定时回写 MySQL
缩略图生成	发布时异步截图任务（Puppeteer worker）
内容审核队列	MySQL 任务表（与现有 upload scan 模式一致）

服务边界原则

Plaza 可以做的

• 读取 h5_publish_records 表（逻辑名 publications）判断帖子来源是否 online。
• 读取 h5_users 表（逻辑名 users）获取创作者基础信息（id、slug、display_name、avatar_url）。
• 在同一 MySQL 实例内，通过定时任务将广场计数回写到 h5_publish_records.plaza_view_count / plaza_like_count（不调用 MindSpace service 函数，但字段由 MindSpace 侧迁移脚本统一定义）。

Plaza 不能做的

• 直接 JOIN h5_user_spaces、h5_page_records、h5_assets 等 MindSpace 核心表。
• 调用 MindSpace 的内部 service 函数（如 mindspace_service.getPage()）。
• 绕过 MindSpace 发布流程直接操作 publications 状态。

跨模块通信方式

Plaza 需要 MindSpace 数据时：
  ① 读 plaza_posts 中的冗余快照字段（title, cover_url, user_slug 等）
  ② 调用 /api/mindspace/v1/ 公开接口（只读场景）
  ③ 通过共用数据库字段或异步任务表传递事件（不 import MindSpace service 模块）

MindSpace 下线 publication 时：
  → 在 mindspace-publications 的同一数据库事务内 UPDATE plaza_posts SET status = 'hidden'

Plaza 回写 publication 广场统计时：
  → 独立定时任务 UPDATE h5_publish_records（见 04-backend-api「互动数据回写」）

部署结构

进程列表

进程	端口	启动命令	说明
Nginx	443	systemd	统一入口，SSL 终止
Node.js 后端	18006	node server.mjs	现有服务，扩展新路由
MindSpace H5	8080	pnpm preview	现有 Vite SPA
Plaza Next.js	3001	pnpm start	新建，SSR
运营后台	3002	pnpm preview	新建，CSR SPA，仅内网
Redis	6379	systemd	新增

Nginx 配置核心

server {
    server_name go.tkmind.cn;

    # 广场和用户主页 → Next.js SSR
    location ~ ^/(plaza|u/) {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 运营后台 → 内网限制
    location /ops {
        allow 10.0.0.0/8;   # 内网 IP 段
        deny all;
        proxy_pass http://127.0.0.1:3002;
    }

    # 所有 API → 共用后端
    location /api {
        proxy_pass http://127.0.0.1:18006;
    }

    # 其余 → MindSpace H5
    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

Cookie 共享策略

三个前端应用同 host（go.tkmind.cn），Nginx 按路径转发到不同端口。Session Cookie 使用 host-only（不设置 Domain 属性），则 /、/plaza、/ops 天然共享登录态，无需 SSO。

Set-Cookie: session_id=xxx; Path=/; HttpOnly; Secure; SameSite=Lax

若未来拆到子域（如 plaza.go.tkmind.cn），再改为 Domain=.go.tkmind.cn 并统一调整各前端 API 基址。

目录结构

ui/
├── h5/          # 现有 MindSpace，不动
├── plaza/       # 新建 Next.js 广场
│   ├── app/
│   │   ├── plaza/           # 广场首页和分类
│   │   │   ├── page.tsx     # /plaza SSR
│   │   │   └── cat/[slug]/page.tsx
│   │   ├── plaza/p/[id]/    # 帖子详情
│   │   │   └── page.tsx
│   │   └── u/[slug]/        # 用户主页
│   │       └── page.tsx
│   ├── components/
│   │   ├── PostCard.tsx     # 卡片组件
│   │   ├── PostGrid.tsx     # 瀑布流
│   │   ├── CategoryNav.tsx  # 分类导航
│   │   └── UserProfile.tsx  # 用户主页
│   ├── lib/
│   │   └── api.ts           # 调用 /api/plaza/v1/
│   └── types/
│       └── plaza.ts
└── ops/         # 新建运营后台
    └── src/
        ├── pages/
        │   ├── ReviewQueue.tsx
        │   ├── FeaturedManager.tsx
        │   └── Analytics.tsx
        └── api/
            └── client.ts    # 调用 /api/ops/v1/

扩展路径

当以下信号出现时，将 Plaza 拆出为独立后端服务：

信号	行动
广场流量是 MindSpace 的 10 倍+	将 plaza_* 表迁移到独立数据库，后端服务拆分
推荐算法需要 Python ML 服务	新建推荐微服务，后端调用其接口
内容审核需要独立合规团队	运营后台独立部署，API 拆分
广场开放第三方内容（非 MindSpace）	数据模型不再依赖 publications 外键，彻底解耦

拆分时要搬走的只有：plaza_* 表、/api/plaza/v1/ 路由、ui/plaza/，其他不动。