geo/docs/geo-platform-ops-admin-tech-architecture-v1.md

GEO 双后台与后端技术架构方案 V1

工作记录说明：本文仍保留作为历史架构记录。其中涉及浏览器插件执行链路、/api/callback/plugin/*、plugin_sessions、installation_token 的相关章节，自 2026-04-20 起视为旧版设计；当前实现请以 desktop client 方案和最新代码为准。

1. 文档信息

项目	内容
文档名称	GEO 双后台与后端技术架构方案 V1
文档版本	V1.0
文档状态	待评审
创建日期	2026-03-25
适用范围	admin-web、ops-admin-web 与 Go 后端整体架构设计
关联文档	docs/geo-platform-prd-v1.md
关联文档	docs/geo-platform-ops-admin-prd-v1.md
关联文档	docs/geo-platform-tech-architecture-v1-50k.md

2. 目标与结论

2.1 建设目标

本方案用于明确 GEO 平台在 V1 阶段的双后台形态与后端落地方式，满足以下目标：

• 面向租户提供独立的业务后台 admin-web
• 面向平台内部提供独立的管理后台 ops-admin-web
• 后端统一采用 Go 实现，控制复杂度，同时保留后续拆分能力
• 支撑内容生成、知识学习、任务运维、额度管理、平台配置和审计能力
• 在 V1 阶段做到“结构清晰、实现收敛、可持续演进”

2.2 核心结论

V1 推荐采用以下架构策略：

• 前端采用 pnpm workspace + Vue 3 + TypeScript + ant-design-vue + Vite 8（截至 2026-03 官方稳定主线）

• 前端拆分为两个独立应用：apps/admin-web 和 apps/ops-admin-web

• 公共能力通过 packages/* 复用，而不是让两个应用互相引用业务代码

• 后端采用 Go + Gin + PostgreSQL + Redis + RabbitMQ + Qdrant + 对象存储

• 对象存储支持双实现：公有云部署推荐 阿里云 OSS + CDN，私有化部署推荐 MinIO + Nginx / CDN

• 工程脚手架可使用 sponge，但仅用于项目初始化、基础设施接线与简单样板生成；不直接生成业务 handler/service/dao 主体代码，领域边界仍以本文的 transport -> app -> domain -> repository 分层为准

• 后端拆分为 gateway + tenant-api + platform-api + scheduler + 多个 Worker，其中 gateway 必须保持超薄

• API 按路由前缀隔离：/api/tenant/* 与 /api/platform/*

• 权限按两层建模：tenant_role 与 platform_role

• 重任务统一异步化，任务进度通过 SSE 或短轮询回写

2.3 架构边界

维度	admin-web	ops-admin-web
服务对象	租户用户	平台内部人员
数据范围	当前租户	全平台或指定租户
核心目标	生成、发布、查看内容与数据	管租户、管配置、管任务、管风险
权限模型	tenant_role	platform_role
API 前缀	/api/tenant/*	/api/platform/*

3. 仓库结构方案

3.1 推荐目录

D:\project\geo
├─ apps
│  ├─ admin-web
│  ├─ ops-admin-web
│  └─ browser-extension
├─ packages
│  ├─ ui
│  ├─ shared-types
│  ├─ http-client
│  ├─ utils
│  ├─ eslint-config
│  └─ tsconfig
├─ server
│  ├─ cmd
│  │  ├─ gateway
│  │  ├─ tenant-api
│  │  ├─ platform-api
│  │  ├─ scheduler
│  │  ├─ worker-generate
│  │  ├─ worker-knowledge
│  │  ├─ worker-analytics
│  │  └─ worker-publish-callback
│  ├─ internal
│  ├─ migrations
│  ├─ sql
│  └─ pkg
├─ deploy
│  ├─ docker-compose
│  └─ k8s
└─ docs

3.2 前端共享包建议

• packages/ui
  • 通用布局、表格筛选栏、状态标签、详情抽屉、权限按钮
• packages/shared-types
  • 前后端共用 DTO、分页结构、状态枚举、角色枚举
• packages/http-client
  • Axios 实例、鉴权拦截器、错误处理、统一响应解包
• packages/utils
  • 时间、金额、脱敏、下载、表格导出等工具
• packages/eslint-config
  • 统一 ESLint 规则
• packages/tsconfig
  • 统一 TS 配置基线

3.3 是否需要第三个前端应用

当前双后台方案覆盖了租户侧和平台侧的控制面，但租户侧 V1 的媒体绑定与手动发布还依赖独立执行面。

因此 V1 建议同步建设：

• apps/browser-extension

该应用不属于当前“双后台”主体，但属于 V1 必选执行端，负责真实登录检测、绑定回传、图片上传、手动发布和状态校验。

4. 前端完整方案

4.1 apps/admin-web 定位

租户端后台，主要服务于租户管理员与编辑，负责：

• 工作台
• 文章生成与管理
• 品牌与知识库管理
• 媒体账号绑定与手动发布
• 数据追踪与套餐额度查看

4.1.1 路由建议

/login
/workspace
/articles
/articles/:id
/brands
/knowledge
/media
/tracking
/account

4.1.2 页面特点

• 业务操作多
• 任务状态多
• 详情页和表单较多
• 需要关注生成与发布的过程反馈

4.2 apps/ops-admin-web 定位

平台管理员端，主要服务于超级管理员、平台运营、客服支持、财务运营、审核风控与技术运维，负责：

• 平台工作台
• 租户中心
• 套餐与额度
• 平台用户与角色
• 模型中心
• 内容配置
• 任务运维
• 监控告警
• 审计中心

4.2.1 路由建议

/login
/platform/dashboard
/platform/tenants
/platform/tenants/:id
/platform/plans
/platform/platform-users
/platform/models
/platform/content
/platform/tasks
/platform/monitoring
/platform/audit

4.2.2 页面特点

• 列表、筛选、统计卡片较多
• 高风险操作较多
• 权限粒度更细
• 更偏运维、审计、治理和配置管理

4.3 前端技术栈建议

• vue
• typescript
• vite
• pnpm
• ant-design-vue
• vue-router
• pinia
• @tanstack/vue-query
• axios
• zod
• @vueuse/core
• dayjs
• vitest

4.4 前端工程规范

• 每个应用独立 src，共享能力全部进入 packages
• 菜单、按钮、路由权限全部由权限配置表驱动
• 页面模式统一为：筛选区 + 表格区 + 详情抽屉 / 详情页
• 长任务状态统一使用 状态标签 + 默认轮询，仅在存在运行中任务的活跃页面临时升级为 SSE
• 高风险按钮统一带确认弹窗和原因输入框

4.5 前端部署建议

• admin-web 和 ops-admin-web 独立构建、独立发布
• 推荐独立域名或子路径：
  • admin.xxx.com
  • ops.xxx.com
• 两套前端都走 CDN，后端统一走 API 域名

5. 后端完整方案

5.1 V1 后端总体策略

V1 推荐：

• 1 个统一网关出口
• 2 个 Go API 服务
• 1 个 Scheduler
• 4 类异步 Worker
• 1 个浏览器插件执行端
• 1 套统一基础设施

其中：

• tenant-api 负责租户侧核心业务
• platform-api 负责平台治理与内部管理
• gateway 负责统一接入、路由转发、公共鉴权、租户级限流与 request_id 注入

V1 保留 gateway，但必须满足以下硬约束：

• 只做 route + auth + rate limit + request_id/trace_id 注入 + 错误响应封装
• 不承载任何 tenant/* 或 platform/* 业务逻辑
• 不直接写 PostgreSQL 业务表，不发 MQ 业务消息，不做任务编排
• 若未来部署环境极简，可由 Ingress / Nginx 直接分流到 tenant-api 与 platform-api；本文默认仍保留超薄 gateway

这样可以避免：

• 过早微服务化
• 大量跨服务联调
• 权限和数据边界复杂化
• 运维成本提前爆炸

同时，V1 不建议把 worker-generate / worker-knowledge / worker-analytics / worker-publish-callback 合并成单一 Worker 进程，因为：

• 交互式生成链路的时延目标高于知识学习和统计聚合
• LLM、Embedding、统计聚合的资源模型不同
• 回调补偿链路需要与用户生成链路故障隔离
• 运维简化更适合通过共享容器基座、统一 Helm 模板和统一日志规范实现，而不是牺牲任务隔离

5.2 Go 后端目录结构

server
├─ cmd
│  ├─ gateway
│  ├─ tenant-api
│  ├─ platform-api
│  ├─ scheduler
│  ├─ worker-generate
│  ├─ worker-knowledge
│  ├─ worker-analytics
│  └─ worker-publish-callback
├─ internal
│  ├─ bootstrap
│  ├─ shared
│  │  ├─ auth
│  │  ├─ config
│  │  ├─ middleware
│  │  ├─ observability
│  │  ├─ plugin
│  │  ├─ retrieval
│  │  ├─ scheduler
│  │  ├─ sse
│  │  ├─ repository
│  │  │  ├─ postgres
│  │  │  ├─ redis
│  │  │  ├─ rabbitmq
│  │  │  ├─ qdrant
│  │  │  └─ objectstorage
│  │  └─ dto
│  ├─ tenant
│  │  ├─ transport
│  │  ├─ app
│  │  ├─ domain
│  │  └─ repository
│  ├─ platform
│  │  ├─ transport
│  │  ├─ app
│  │  ├─ domain
│  │  └─ repository
│  ├─ jobs
│  └─ gateway
├─ migrations
├─ sql
└─ pkg

5.3 API 路由分层建议

5.3.1 公共接口

• /api/health/*
• /api/auth/*

5.3.2 租户端接口

• /api/tenant/workspace/*
• /api/tenant/articles/*
• /api/tenant/brands/*
• /api/tenant/knowledge/*
• /api/tenant/media/*
• /api/tenant/tracking/*
• /api/tenant/account/*

5.3.3 平台管理员端接口

• /api/platform/dashboard/*
• /api/platform/tenants/*
• /api/platform/plans/*
• /api/platform/platform-users/*
• /api/platform/models/*
• /api/platform/content/*
• /api/platform/integrations/*
• /api/platform/tasks/*
• /api/platform/monitoring/*
• /api/platform/audit/*

5.3.4 回调与内部接口

• /api/callback/plugin/*
• /api/internal/metrics/*
• /api/internal/task-events/*

5.3.5 网关转发关系

• /api/auth/* -> gateway 或共享认证模块
• /api/tenant/* -> tenant-api
• /api/platform/* -> platform-api
• /api/callback/* -> tenant-api

5.4 后端二进制职责

二进制	作用
cmd/gateway	统一 API 出口、无状态路由分发、基础鉴权、租户级限流、request_id/trace_id 注入与统一错误响应封装
cmd/tenant-api	提供租户端业务接口、任务状态接口、按需 SSE、插件会话与插件回调接口
cmd/platform-api	提供平台管理员端接口、租户治理、模型配置、审计与监控查询
cmd/scheduler	扫描定时生成、数据监控等到期任务，生成调度批次并入队
cmd/worker-generate	处理模板生成、Prompt 生成、批量生成与文章优化任务，并负责 RAG 检索、LLM 超时/限流/并发池控制
cmd/worker-knowledge	处理知识学习、解析、批量 Embedding、Qdrant 写入与 chunk 元数据维护
cmd/worker-analytics	处理问题采集、分析快照、统计聚合、缓存刷新；默认走低优先级模型通道
cmd/worker-publish-callback	处理发布回调、状态回写、失败补偿

5.5 后端模块职责

5.5.1 shared/auth

• 登录
• Token 颁发与校验
• 用户身份识别
• 平台角色 / 租户角色装载

5.5.2 shared/retrieval

• 统一封装 query rewrite、filter 构造、Qdrant 检索、rerank 与上下文拼装
• 为 worker-generate 暴露品牌知识 RAG 检索入口
• V1 将 retrieval_logs 和 badcase 采样先写文件日志或对象存储，后续再升级为数据库评测体系

5.5.3 tenant

• 租户基础资料
• 租户状态
• 租户成员与租户角色

5.5.4 platform

• 平台管理员用户
• 平台角色
• 平台配置与平台级查询

5.5.5 tenant/article / tenant/brand / tenant/knowledge

• 租户业务核心能力
• 生成内容、品牌资料、知识库管理

5.5.6 platform/quota / platform/plan

• 套餐配置
• 配额消耗
• 配额补量
• 到期与重置规则

5.5.7 platform/model

• LLM 配置
• Embedding 配置
• 限流策略
• 默认模型策略

5.5.8 tenant/task + platform/task

• 任务入队
• 状态查询
• 重试与终止
• 死信处理

5.5.9 platform/monitoring

• 服务健康
• 队列状态
• Worker 状态
• 告警汇总

5.5.10 platform/audit

• 操作日志
• 配置变更日志
• 额度变更日志
• 风险操作日志

5.5.11 shared/observability

• 统一结构化日志规范与日志字段
• 统一 request_id、trace_id、task_batch_id 透传
• Prometheus 指标、健康检查、慢查询与队列深度观测
• 为 API、MQ、Worker 共用的错误码与告警标签提供基础设施

5.6 服务边界建议

5.6.1 tenant-api 负责

• 租户工作台
• 品牌、文章、知识库
• 媒体绑定与发布记录
• 生成任务提交与状态查询
• 租户侧额度消耗校验
• 发布回调接收

5.6.2 platform-api 负责

• 平台工作台
• 租户管理
• 套餐与额度策略
• 平台用户与平台角色
• 模型配置与模板规则
• 任务运维查询与重试控制
• 监控告警与审计中心

5.6.3 两服务协作原则

• platform-api 不直接承载租户高频业务流量
• tenant-api 不同步依赖 platform-api 完成核心链路
• 平台侧对租户业务的控制，优先通过数据库规则、缓存配置或内部命令完成
• 需要重试或控制任务时，由 platform-api 写控制记录并重新入队或调用内部接口

6. 认证与权限架构

6.1 统一身份模型

建议统一 users 主表，但角色绑定拆分：

• platform_user_roles
• tenant_memberships

这样一个账号可以：

• 既是平台内部用户
• 也可能是某个租户的成员

但两种权限链路必须分开校验。

6.2 权限模型

6.2.1 平台角色 platform_role

• super_admin
• ops
• sre

6.2.2 租户角色 tenant_role

• tenant_admin
• editor

6.2.3 租户角色能力边界

角色	主要能力	明确限制
tenant_admin	租户设置、成员管理、模板/Prompt/品牌/知识/媒体、发布、配额查看、风险操作确认	无平台级治理权限
editor	创建与编辑文章、模板、Prompt、品牌、知识、媒体发布、查看追踪数据	不能管理成员、套餐策略、平台级配置

V1 权限模型按当前产品裁剪口径收敛为 tenant_admin + editor 两种租户角色；viewer 暂不单列，若后续出现严格只读协作者场景，可再由 editor 细分。

6.2.4 Prompt 分享身份 kol_profile

• kol 不是权限角色，而是用户在 Prompt 分享场景下的作者/达人身份
• kol 用户可生成分享码，供普通用户导入新的“文章模板类型”
• 分享内容本质上是“模板卡片 + 变量槽位定义 + 使用说明 + 受保护 Prompt 资产引用”的快照，而不是裸 Prompt 文本
• 导入后会在工作台或模板页形成新的模板卡片，作为平台预设模板之外的扩展文章类型
• 公司名、地址、品牌名、联系方式等租户专属字段仍由导入方在变量槽位中自行填写或绑定
• KOL 的原始 Prompt 正文对普通用户不可见，不可导出，不可在前端编辑，用于保护 Prompt 版权
• kol_profile 通过 prompt_share_profiles 与 prompt_share_codes 建模，不参与 RBAC 鉴权

6.3 鉴权中间件顺序

1. Token 校验
2. 用户身份解析
3. 路由前缀识别
4. 平台角色或租户角色装载
5. 资源范围校验
6. 风险操作校验
7. 审计上下文注入

6.4 风险操作要求

以下操作建议统一纳入风险操作：

• 冻结 / 解冻租户
• 调整套餐额度
• 修改模型默认策略
• 修改敏感词规则
• 批量重试任务
• 修改平台适配器配置

这些操作至少具备：

• 二次确认
• 操作原因
• 审计日志

7. 数据与中间件方案

7.1 PostgreSQL

负责：

• 用户、租户、成员、角色关系
• 品牌、文章、发布记录
• 套餐、额度、账期
• 模型配置、模板配置
• 任务记录
• 告警记录
• 审计日志
• 配额预扣与调度租约
• 知识 chunk 元数据

7.2 Redis

负责：

• 登录黑名单
• 高频查询缓存
• 仪表盘热点数据
• 任务短期状态缓存
• 限流计数
• SSE 跨 Pod 广播

7.3 RabbitMQ

负责：

• 文章生成任务
• 知识学习任务
• 分析聚合任务
• 发布回调任务
• 死信队列

7.4 Qdrant

负责：

• 知识库向量存储
• RAG 检索

7.5 对象存储

负责：

• 原始文档
• 图片素材
• 导入导出文件
• 原始抓取结果
• 原始模型回答与插件回调归档

8. 双后台与后端交互图

以下为主架构的宏观交互图，细化后的闭环版本以 §13.5.1 为准。

flowchart LR
    subgraph FE["前端应用"]
        AW["admin-web<br/>租户端"]
        OW["ops-admin-web<br/>平台管理员端"]
        EXT["browser-extension<br/>V1 发布执行端"]
    end

    AW --> CDN["CDN / Nginx"]
    OW --> CDN

    CDN --> ING["Ingress / API Gateway"]
    EXT --> ING

    ING --> GW["gateway"]
    GW --> TA["tenant-api"]
    GW --> PA["platform-api"]
    SCH["scheduler"] --> PG["PostgreSQL"]
    SCH --> MQ["RabbitMQ"]

    TA --> PG["PostgreSQL"]
    TA --> REDIS["Redis"]
    TA --> MQ["RabbitMQ"]
    TA --> OBJ["Object Storage"]
    TA --> QD["Qdrant"]

    PA --> PG
    PA --> REDIS
    PA --> MQ

    MQ --> WG["worker-generate"]
    MQ --> WK["worker-knowledge"]
    MQ --> WA["worker-analytics"]
    MQ --> WP["worker-publish-callback"]

    WG --> PG
    WG --> REDIS
    WG --> QD

    WK --> PG
    WK --> QD
    WK --> OBJ

    WA --> PG
    WA --> REDIS
    WA --> OBJ

    WP --> PG
    WP --> REDIS
    PA --> TA

9. 后端结构图

以下为主架构的模块示意图；二进制职责、共享模块和运行约束以 §13.5 与 §13.13 为准。

flowchart TB
    subgraph CMD["cmd"]
        GWBIN["gateway"]
        TENBIN["tenant-api"]
        PLTBIN["platform-api"]
        SCHBIN["scheduler"]
        GENBIN["worker-generate"]
        KBBIN["worker-knowledge"]
        ANABIN["worker-analytics"]
        PUBBIN["worker-publish-callback"]
    end

    subgraph SHARED["internal/shared"]
        SAUTH["auth"]
        SMIDDLE["middleware"]
        SPLUGIN["plugin"]
        SRET["retrieval"]
        SSCHED["scheduler"]
        SREPO["shared repositories"]
        SSSE["sse"]
        SOBS["observability"]
    end

    subgraph TENANT["internal/tenant"]
        TTRANS["transport"]
        TAPP["app"]
        TDOMAIN["domain"]
        TREPO["repository"]
    end

    subgraph PLATFORM["internal/platform"]
        PTRANS["transport"]
        PAPP["app"]
        PDOMAIN["domain"]
        PREPO["repository"]
    end

    subgraph JOBS["internal/jobs"]
        JGEN["generate job"]
        JKB["knowledge job"]
        JANA["analytics job"]
        JPUB["publish callback job"]
    end

    subgraph INFRA["infra"]
        PGREPO["postgres"]
        REDISREPO["redis"]
        MQREPO["rabbitmq"]
        QDREPO["qdrant"]
        OBJREPO["objectstorage"]
    end

    GWBIN --> SAUTH
    GWBIN --> SMIDDLE

    TENBIN --> TTRANS
    TENBIN --> SAUTH
    TENBIN --> SPLUGIN
    TENBIN --> SSSE
    TENBIN --> SOBS

    PLTBIN --> PTRANS
    PLTBIN --> SAUTH
    PLTBIN --> SOBS

    SCHBIN --> SSCHED
    SCHBIN --> SOBS

    TTRANS --> TAPP
    TAPP --> TDOMAIN
    TAPP --> TREPO

    PTRANS --> PAPP
    PAPP --> PDOMAIN
    PAPP --> PREPO

    GENBIN --> JGEN
    KBBIN --> JKB
    ANABIN --> JANA
    PUBBIN --> JPUB

    JGEN --> SRET
    JGEN --> TREPO
    JKB --> TREPO
    JANA --> PREPO
    JPUB --> TREPO
    JPUB --> PREPO

    TREPO --> SREPO
    PREPO --> SREPO

    SRET --> SREPO
    SREPO --> PGREPO
    SREPO --> REDISREPO
    SREPO --> MQREPO
    SREPO --> QDREPO
    SREPO --> OBJREPO

10. 核心链路设计

10.1 租户端生成链路

1. admin-web 提交生成请求
2. API 校验租户身份、额度、参数
3. tenant-api 在同一 PostgreSQL 事务内完成“额度预扣 / 保留 + generation_tasks / task_records 创建 + 文章占位记录初始化”
4. 事务提交后写入 RabbitMQ
5. worker-generate 消费任务，先经 shared/retrieval 执行 query rewrite -> filter -> Qdrant 检索 -> rerank -> 上下文拼装
6. worker-generate 在超时、限流、并发池保护下调用模型
7. 成功时在同一 PostgreSQL 事务内写入 article_versions、更新 articles、确认额度消耗；失败时写失败状态并按条退还额度
8. 结果写入 Redis，前端通过 SSE 或轮询感知任务进度

10.2 平台端额度调整链路

1. ops-admin-web 发起额度变更
2. API 校验 platform_role
3. 写入额度变更记录
4. 更新租户额度表与缓存
5. 写入审计日志
6. 租户端下一次请求按新额度生效

10.3 平台端任务排查链路

1. ops-admin-web 查询失败任务列表
2. API 聚合 PostgreSQL 任务信息、错误信息与重试信息
3. 平台人员发起重试
4. API 写入重试记录并重新入队
5. Worker 执行后回写结果
6. 审计中心记录操作人和结果

10.4 监控与告警链路

1. Go API 与 Worker 暴露指标
2. 监控系统采集服务、队列、缓存、数据库指标
3. 告警服务生成异常记录
4. ops-admin-web 查询并展示告警状态

11. 部署建议

11.1 本地开发

• 前端：pnpm 工作区本地联调
• 基础设施：docker compose 仅启动 PostgreSQL、Redis、RabbitMQ、Qdrant、MinIO
• 后端服务建议本地 go run，按需启动：
  • go run ./server/cmd/gateway
  • go run ./server/cmd/tenant-api
  • go run ./server/cmd/platform-api
  • go run ./server/cmd/scheduler
  • go run ./server/cmd/worker-generate
  • go run ./server/cmd/worker-knowledge
  • go run ./server/cmd/worker-analytics
  • go run ./server/cmd/worker-publish-callback
• 建议提供 make dev-init 或等价任务脚本，统一完成：
  • 执行 migration
  • 创建 RabbitMQ 队列 / exchange / routing key
  • 初始化 MinIO bucket
  • 写入最小种子数据与本地模型通道配置

11.2 测试与预发

• 前端独立构建产物
• API 与 Worker 独立容器
• 使用共享测试基础设施或云托管实例

11.3 线上生产

• admin-web 与 ops-admin-web 独立发布到 CDN
• API 与 Worker 部署到 Kubernetes
• PostgreSQL、Redis、RabbitMQ、Qdrant 使用高可用或托管方案

12. 演进路线

12.1 V1

• 两个前端应用
• 一个浏览器插件执行端
• 一个统一网关出口
• 两个 Go API 服务
• 一个 Scheduler
• 四类 Worker
• 平台端与租户端路由隔离

12.2 V1.5

• 抽离统一审计模块
• 抽离模型网关模块
• 增加平台接入配置中心

12.3 V2

• 按压力拆分平台 API 与租户 API
• 单独拆出 ops-bff 或 platform-api
• 单独拆出 analytics-service

13. V1 闭环补齐方案

13.1 适用说明

本节结合以下材料对前文进行补齐修订，并作为 V1 详细落地的统一口径：

• docs/refer/*
• docs/geo-platform-prd-v1.md
• docs/geo-platform-ops-admin-prd-v1.md
• docs/media-binding-and-publish-v1.md
• docs/question-driven-monitoring-design-v1.md
• docs/Claude_architecture_review.md

若本节与前文较早的抽象表述存在冲突，以本节为准。

13.2 修订结论

为保证 docs/refer 中 8 个页面在 V1 阶段形成“页面 -> 路由 -> API -> 对象 -> 任务 -> 存储 -> 状态回传”的完整闭环，V1 对总体架构做如下修订：

• apps/browser-extension 从“后续可选”提升为 V1 必选执行端
• 后端实际形态明确为：gateway + tenant-api + platform-api + scheduler + 4 类 Worker + browser-extension
• tenant-api 按业务拆分为 workspace / template / prompt-rule / schedule / article / optimization / brand / knowledge / media / tracking / account
• worker-generate 同时承载 模板生成 / Prompt 生成 / 批量生成 / 文章优化
• 工作台模板卡片支持“平台预设 + 租户自建 + KOL 分享码导入”三种来源，导入后统一物化为租户模板
• 数据追踪 采用“问题驱动监控”模型，最小采集单元为 question_version x model x run_time
• 工作台、数据追踪、任务状态统一提供聚合接口，避免前端首屏发起过多散请求
• 所有长任务统一接入 task_records + SSE + 轮询兜底

13.3 功能闭环矩阵

功能页	核心路由	核心 API 组	核心对象	异步/执行组件
工作台	/workspace	/api/tenant/workspace/*	articles article_templates brands platform_accounts tenant_plan_subscriptions	worker-generate worker-publish-callback
模板创作	/articles/template	/api/tenant/templates/* /api/tenant/prompt-shares/* /api/tenant/articles/*	article_templates prompt_share_codes articles generation_tasks	worker-generate
自定义生成	/articles/custom/*	/api/tenant/prompt-rules/* /api/tenant/schedules/* /api/tenant/articles/*	prompt_rules schedule_tasks generation_tasks	scheduler worker-generate
文章优化	/articles/optimize	/api/tenant/optimizations/* /api/tenant/articles/*	optimization_tasks article_versions	worker-generate
媒体管理	/media	/api/tenant/media/* /api/callback/plugin/*	media_platforms platform_accounts plugin_sessions publish_records	browser-extension worker-publish-callback
品牌词库	/brands /brands/:id	/api/tenant/brands/*	brands brand_keywords brand_questions brand_question_versions competitors	worker-analytics
知识库	/knowledge	/api/tenant/knowledge/*	knowledge_groups knowledge_items knowledge_parse_tasks	worker-knowledge
数据追踪	/tracking/overview /tracking/detail	/api/tenant/tracking/*	question_monitor_runs question_monitor_parse_results keyword_model_daily_metrics keyword_model_top_questions_daily keyword_model_citation_rank_daily	scheduler worker-analytics

13.4 细化前端路由

13.4.1 admin-web

/login
/workspace
/articles/template
/articles/template/create
/articles/custom
/articles/custom/instant
/articles/custom/scheduled
/articles/custom/prompts
/articles/optimize
/articles/:id
/articles/:id/publish-records
/brands
/brands/:id
/knowledge
/media
/tracking/overview
/tracking/detail
/account

13.4.2 ops-admin-web

/login
/platform/dashboard
/platform/tenants
/platform/tenants/:id
/platform/plans
/platform/platform-users
/platform/platform-roles
/platform/models/llm
/platform/models/embedding
/platform/models/channels
/platform/models/limits
/platform/content/templates
/platform/content/prompts
/platform/content/tags
/platform/content/sensitive-rules
/platform/integrations/media-platforms
/platform/integrations/adapters
/platform/integrations/publish-policies
/platform/tasks/generation
/platform/tasks/knowledge
/platform/tasks/publish
/platform/tasks/analytics
/platform/tasks/dead-letter
/platform/monitoring/services
/platform/monitoring/queues
/platform/monitoring/workers
/platform/monitoring/storage
/platform/monitoring/alerts
/platform/audit/operations
/platform/audit/config-changes
/platform/audit/quota-changes
/platform/audit/risk-actions

13.5 服务、二进制与模块补齐

13.5.1 修订后的整体交互图

flowchart LR
    AW["admin-web"] --> CDN["CDN / Nginx"]
    OW["ops-admin-web"] --> CDN
    EXT["browser-extension"] <---> AW

    CDN --> GW["gateway"]
    GW --> TA["tenant-api"]
    GW --> PA["platform-api"]

    SCH["scheduler"] --> PG["PostgreSQL"]
    SCH --> MQ["RabbitMQ"]

    TA --> PG
    TA --> REDIS["Redis"]
    TA --> MQ
    TA --> OBJ["Object Storage"]
    TA --> QD["Qdrant"]

    PA --> PG
    PA --> REDIS
    PA --> MQ

    EXT --> CB["/api/callback/plugin/*"]
    CB --> TA

    MQ --> WG["worker-generate"]
    MQ --> WK["worker-knowledge"]
    MQ --> WA["worker-analytics"]
    MQ --> WP["worker-publish-callback"]

    WG --> QD
    WA --> OBJ

13.5.2 二进制职责补齐

二进制/执行端	职责
cmd/gateway	统一入口、公共鉴权、限流、request_id/trace_id 注入与统一错误响应封装；保持无状态，支持水平扩容
cmd/tenant-api	承载租户侧全部业务接口、SSE、插件会话管理、回调落库
cmd/platform-api	承载平台治理、套餐额度、平台用户、模型中心、平台接入、监控审计
cmd/scheduler	扫描 schedule_tasks 和数据监控计划，按到期窗口生成调度批次并入队
cmd/worker-generate	执行模板生成、Prompt 生成、批量生成、文章优化；通过 shared/retrieval 做 RAG 检索，并使用独立 LLM 并发池控制交互任务
cmd/worker-knowledge	执行文档解析、URL 抓取、文本切片、批量 Embedding、Qdrant 写入、chunk 元数据维护
cmd/worker-analytics	执行问题驱动监控、回答解析、日级聚合、排行榜刷新、缓存刷新；采集任务默认走低优先级模型通道
cmd/worker-publish-callback	处理发布回调补偿、账号状态检测结果、失败重放与死信回写
apps/browser-extension	真实登录检测、账号绑定、图片上传、手动发布、状态检查、本地 adapter 执行

13.5.3 租户侧模块补齐

模块	职责
tenant/workspace	工作台聚合指标、最近生成、额度摘要、模板卡片下发；卡片来源支持平台预设、租户自建与 KOL 分享导入
tenant/template	模板定义、模板 schema、模板版本、模板生成入口、KOL 分享模板的变量定制与落库；不向导入方暴露受保护 Prompt 正文
tenant/prompt-rule	Prompt 规则 CRUD、启停、默认语气/字数配置、作者身份信息、分享码导出与导入；支持变量槽位定义与版权保护
tenant/schedule	定时生成计划 CRUD、启停、下一次执行时间维护
tenant/article	文章主记录、详情、预览、复制、删除、发布前读取
tenant/optimization	优化任务、优化方向、版本保存、未完成任务入口
tenant/brand	品牌、关键词、问题集、问题版本、竞品库
tenant/knowledge	分组、知识条目、来源类型、学习任务状态
tenant/media	平台清单、平台账号、插件会话、发送记录、状态检测
tenant/tracking	数据概览、趋势图、高频问题、引用排行、品牌关键词模型筛选
tenant/account	套餐、额度、重置时间、升级入口占位

13.5.4 平台侧模块补齐

模块	职责
platform/tenant	租户开通、冻结解冻、套餐关联、额度治理
platform/plan + platform/quota	套餐档位、额度策略、补量、账期重置
platform/model	LLM、Embedding、渠道密钥、限流、默认策略
platform/content	平台级模板、Prompt 规则、分类标签、敏感词规则
platform/integration	媒体平台清单、平台分类、adapter 注册、发布策略
platform/task	任务运维、批量重试、死信处理、执行历史
platform/monitoring	服务、队列、Worker、存储、告警
platform/audit	操作日志、配置变更、额度变更、风险操作

13.6 核心 API 补齐

13.6.1 租户侧 API

• /api/tenant/workspace/overview
• /api/tenant/workspace/recent-articles
• /api/tenant/workspace/quota-summary
• /api/tenant/workspace/template-cards
• /api/tenant/templates
• /api/tenant/templates/{id}
• /api/tenant/templates/{id}/schema
• /api/tenant/templates/{id}/generate
• /api/tenant/prompt-rules
• /api/tenant/prompt-rules/{id}
• /api/tenant/prompt-rules/{id}/share-code
• /api/tenant/prompt-shares/resolve/{shareCode}
• /api/tenant/prompt-shares/import
• /api/tenant/prompt-share-profiles/me
• /api/tenant/schedules
• /api/tenant/schedules/{id}
• /api/tenant/schedules/{id}/enable
• /api/tenant/schedules/{id}/disable
• /api/tenant/articles
• /api/tenant/articles/{id}
• /api/tenant/articles/{id}/versions
• /api/tenant/articles/{id}/publish-records
• /api/tenant/optimizations
• /api/tenant/optimizations/{id}
• /api/tenant/brands
• /api/tenant/brands/{id}
• /api/tenant/brands/{id}/keywords
• /api/tenant/brands/{id}/questions
• /api/tenant/brands/{id}/competitors
• /api/tenant/knowledge/groups
• /api/tenant/knowledge/items
• /api/tenant/knowledge/parse-tasks
• /api/tenant/media/platforms
• /api/tenant/media/platform-accounts
• /api/tenant/media/platform-accounts/{id}/check
• /api/tenant/media/plugin-sessions
• /api/tenant/media/publish-records
• /api/tenant/tracking/summary
• /api/tenant/tracking/trend
• /api/tenant/tracking/top-questions
• /api/tenant/tracking/citation-rank
• /api/tenant/account/plan
• /api/tenant/account/quota

13.6.2 平台侧 API

• /api/platform/dashboard/*
• /api/platform/tenants/*
• /api/platform/plans/*
• /api/platform/platform-users/*
• /api/platform/models/*
• /api/platform/content/*
• /api/platform/integrations/*
• /api/platform/tasks/*
• /api/platform/monitoring/*
• /api/platform/audit/*

13.6.3 插件回调与内部接口

• /api/callback/plugin/bind
• /api/callback/plugin/publish
• /api/callback/plugin/check
• /api/internal/task-events
• /api/internal/scheduler/dispatch

13.6.4 统一错误响应与错误码

所有 API 建议统一返回：

{
  "code": 40301,
  "message": "quota_insufficient",
  "detail": "生成额度不足，请升级套餐或等待额度重置",
  "request_id": "req_xxx"
}

错误码段建议如下：

错误码段	含义
400xx	参数校验与请求格式错误
401xx	认证失败、Token 失效
403xx	权限不足、额度不足、功能未开通
404xx	资源不存在
409xx	状态冲突、幂等冲突、重复提交
429xx	频率限制、队列拥塞
500xx	内部错误
503xx	下游依赖不可用，如 LLM / Embedding / Qdrant / ObjectStorage

gateway 与各 API 服务必须共用同一套错误码枚举和响应封装，避免前后端联调时出现多种格式。

13.6.5 KOL 分享码解析边界

• /api/tenant/prompt-shares/resolve/{shareCode} 只返回模板卡片信息、变量槽位、使用说明、作者展示信息，不返回底层 Prompt 正文
• /api/tenant/prompt-shares/import 在服务端完成模板物化，前端只提交变量定制结果，不接触受保护 Prompt 资产
• /api/tenant/templates/{id} 对 origin_type=kol_share 的模板仅返回可定制字段与运行配置，不返回 prompt_template
• 真正参与生成的受保护 Prompt 仅由 tenant-api / worker-generate 在服务端读取，前端与浏览器插件都不可见

13.7 异步任务、调度与幂等设计

13.7.1 队列与任务类型

队列	任务类型	说明
q.generate.interactive	article.generate.template article.generate.prompt article.optimize	交互式任务，高优先级，服务工作台、模板创作、自定义生成即时任务与文章优化
q.generate.batch	article.generate.batch_item article.generate.schedule_item	批量与定时任务，低优先级，避免堵塞交互任务
q.knowledge	knowledge.parse.file knowledge.parse.url knowledge.parse.text	不同来源共用解析入口，按来源类型走不同解析器
q.analytics.collect	analytics.collect.question	采集任务，低于用户直触发生成任务优先级，默认使用独立模型通道或更小并发池
q.analytics.aggregate	analytics.aggregate.daily analytics.refresh.cache	聚合与缓存刷新任务，不占用 LLM 通道
q.publish-callback	publish.persist platform-account.check.persist	插件执行结果、账号检测结果入队补偿
q.dead-letter	dead_letter.*	统一兜底失败任务

13.7.2 调度器设计

• scheduler 每分钟扫描一次 schedule_tasks，条件为 status=enabled and next_run_at <= now()
• 使用数据库行级锁或租约字段 dispatch_lease_until + lease_owner 防止多实例重复派发
• 每次派发生成一个 task_batch_id，并为批量任务拆分出多个 generation_tasks
• 数据追踪监控计划同样由 scheduler 生成 analytics.collect.question 任务
• 计划任务创建时默认写入 dispatch_jitter_minutes，将大批同时到期任务平滑散布到 5~10 分钟 窗口内
• scheduler 重启后按 task_batch_id + request_hash 幂等追回漏派发任务，避免重复投递
• V1 不依赖 RabbitMQ Delay Queue，统一采用“数据库到期扫描 + 普通消息队列”方式，降低实现复杂度

13.7.3 事务、幂等与补偿

• 任务提交路径必须在单个 PostgreSQL 事务内完成“额度预扣 / 保留 + 任务创建 + 任务记录写入”
• Worker 成功路径必须在单个 PostgreSQL 事务内完成“结果写入 + 主记录状态更新 + 额度确认”
• Worker 失败路径必须在单个 PostgreSQL 事务内完成“失败状态更新 + 额度退还 / 释放”
• 批量生成采用“提交时按批次预扣 + 单条失败退款 + 定期对账”模式，批次维度以 task_batch_id 管理
• 生成任务按 tenant_id + source_type + request_hash + schedule_slot 做幂等
• 插件回调按 plugin_session_id + callback_stage 做幂等
• publish_records 保留请求与响应摘要，支持补偿重放
• Worker 默认重试 3 次，超过阈值进入死信；平台端允许人工批量重试

13.8 浏览器插件执行面闭环

13.8.1 插件会话模型

为避免“页面一关结果丢失”，V1 引入 plugin_sessions：

1. 前端先调用 /api/tenant/media/plugin-sessions 创建一次性会话
2. 后端返回 plugin_session_id + session_token + expire_at
3. 前端将会话信息交给 browser-extension
4. 插件执行绑定、检测或发布动作
5. 插件将结果：
   • 回传给前端用于即时交互
   • 同时回调 /api/callback/plugin/* 用于可靠落库
6. tenant-api 校验 session_token 后写入 platform_accounts 或 publish_records
7. 系统通过 SSE 广播结果，列表页和详情页实时刷新

13.8.2 绑定/发布状态流转

• 平台账号状态：pending -> active -> invalid/expired
• 发布状态：unpublished -> publishing -> success/failed/pending_review
• 回调接口不直接信任浏览器 Cookie，只信任后端签发的短期 session_token

13.8.3 安全约束

• 服务端不保存第三方平台 Cookie 与登录态
• 插件仅允许注入受信后台域名
• 所有 postMessage / runtime.sendMessage 必须校验来源域名与会话 token
• 所有绑定、重检、发布、失败补偿动作写入审计日志

13.8.4 插件检测与降级

• packages/shared-types 维护 MIN_BROWSER_EXTENSION_VERSION 常量，作为前后端与插件共享的最低兼容版本
• 媒体页加载时，admin-web 先通过 plugin.ping / postMessage 握手检测插件是否安装、版本是否满足要求、能力清单是否齐备
• 未安装、被禁用或版本过低时，页面将“去绑定 / 重新检测 / 发布”按钮置灰，并展示安装或升级引导
• 插件回调会把 client_version 回传到 plugin_sessions 审计字段，便于排查兼容问题
• 降级场景下不走伪成功逻辑，统一保持前端只读提示，避免产生无法落库的假状态

13.9 数据追踪闭环

13.9.1 采集模型

数据追踪采用 问题驱动监控，最小采集单元为：

1 question_version x 1 model x 1 run_time = 1 条原始监控记录

含义如下：

• 品牌 是租户下的监控主体
• 关键词 是问题集合容器与聚合维度
• 问题版本 保证历史口径稳定
• 模型 是对比维度
• 页面只查日级聚合表，不直接扫描原始回答

13.9.2 数据链路

1. 用户在品牌词库维护 brand_keywords 与 brand_questions
2. scheduler 按每日频率为启用的问题版本和目标模型派发监控任务
3. worker-analytics 调用模型得到原始回答，原文写入对象存储
4. 解析回答是否提及品牌、是否首位提及、是否首选推荐、是否正向提及、是否引用文章
5. 结果写入 question_monitor_runs 与 question_monitor_parse_results
6. 日级聚合刷新 question_model_daily_metrics、keyword_model_daily_metrics、keyword_model_top_questions_daily、keyword_model_citation_rank_daily
7. Redis 缓存 30 天摘要、趋势图、高频问题、引用排行
8. /api/tenant/tracking/* 统一从聚合表和缓存读取

13.9.3 V1 控制策略

• 每个问题每天默认执行 1 次
• 重要品牌或更高套餐可配置为 2 次
• 同品牌、同模型、同日、相同 question_hash 可做采集去重
• 原始回答落对象存储，PostgreSQL 仅保存结构化解析与聚合结果
• 原始运行记录保留 30 ~ 90 天，解析结果保留 90 天，日级汇总保留 180 天+
• brand_question_versions 仅在“启用 / 发布新监控口径”时生成新版本；编辑态默认做 10 分钟 debounce，避免碎片化

13.10 SSE 与轮询策略

13.10.1 SSE 适用场景

以下场景在“存在运行中任务”期间可临时升级为 SSE：

• 文章生成进度
• 文章优化进度
• 知识学习状态
• 平台账号检测状态
• 发布状态变更
• 配额刷新提醒

13.10.2 事件类型

• task.updated
• article.generated
• article.optimized
• knowledge.updated
• platform_account.updated
• publish.updated
• quota.updated

统一负载字段建议：

• event_id
• tenant_id
• event_type
• resource_type
• resource_id
• task_id
• status
• message
• occurred_at

13.10.3 连接策略

• 工作台、列表页、数据页默认使用 10s 轮询
• 仅当页面存在 queued/running/publishing/checking 状态的资源时，前端才建立 SSE 连接
• 单用户单租户默认只保留 1 条 SSE 连接；页面空闲 60s 且无运行中任务时主动关闭
• tenant-api 通过 Redis Pub/Sub 做跨 Pod 事件广播，不依赖 Sticky Session；任一 Pod 写事件后，所有订阅 Pod 都能向本地连接转发
• SSE heartbeat 调整为 30s
• 客户端断线后按 3s / 5s / 10s 退避重连
• 若浏览器或网络环境不支持 SSE，则保持 10s 轮询
• 页面不直接监听 RabbitMQ，统一由 tenant-api 聚合并对前端推送

13.11 核心数据模型与最小 Schema

13.11.1 身份、租户与额度

表	关键字段	关键约束/索引
tenants	id name status created_at frozen_at	uk_tenant_name
users	id email phone status created_at	uk_users_email
tenant_memberships	id tenant_id user_id tenant_role	uk_tenant_user
platform_user_roles	id user_id platform_role	uk_platform_user_role
plans	id plan_code name quota_policy_json status	uk_plan_code
tenant_plan_subscriptions	id tenant_id plan_id start_at end_at status	idx_tenant_plan_active
tenant_quota_ledgers	id tenant_id quota_type delta balance_after reason	idx_tenant_quota_tenant_type_created
quota_reservations	id tenant_id quota_type resource_type resource_id reserved_amount consumed_amount refunded_amount status expire_at	idx_quota_reservation_tenant_status

13.11.2 模板、Prompt、文章与优化

表	关键字段	关键约束/索引
article_templates	id scope tenant_id origin_type share_code_id template_key template_name schema_json prompt_template prompt_visibility protected_prompt_asset_key card_config_json status version_no	uk_template_scope_key_version
prompt_rules	id tenant_id name prompt_content scene default_tone default_word_count status	idx_prompt_rule_tenant_status
prompt_share_profiles	id user_id display_name bio avatar_url share_enabled status	uk_prompt_share_profile_user
prompt_share_codes	id tenant_id source_template_id owner_user_id share_code snapshot_json protected_prompt_asset_key status expire_at	uk_prompt_share_code
schedule_tasks	id tenant_id prompt_rule_id target_platform_id cron_expr next_run_at dispatch_jitter_minutes lease_owner dispatch_lease_until last_dispatch_at status	idx_schedule_due
articles	id tenant_id source_type template_id prompt_rule_id current_version_id generate_status publish_status	idx_article_tenant_created
article_versions	id article_id version_no title html_content markdown_content word_count source_label	uk_article_version_no
generation_tasks	id tenant_id article_id task_batch_id quota_reservation_id task_type request_hash status error_message	idx_generation_task_status_created
optimization_tasks	id tenant_id article_id source_version_id target_version_id optimization_type status	idx_optimization_task_status

其中：article_templates.scope=platform 时 tenant_id 为空；scope=tenant 时 tenant_id 必填。

导入 KOL 分享码后，系统会把快照物化为当前租户自己的 article_templates 记录，并标记 origin_type=kol_share。

article_templates.prompt_visibility=sealed 时，模板的 Prompt 正文只允许服务端读取，前端接口不得返回。

prompt_share_codes.snapshot_json 只保存模板卡片信息、变量占位和使用说明；真正的 Prompt 正文通过 protected_prompt_asset_key 以受保护资产方式保存，不复制导出方租户的品牌、地址、媒体账号等私有数据。

13.11.3 品牌与问题集

表	关键字段	关键约束/索引
brands	id tenant_id name description status	uk_brand_tenant_name
brand_keywords	id tenant_id brand_id name status	uk_brand_keyword_name
brand_questions	id tenant_id brand_id keyword_id current_version_id status	idx_brand_questions_keyword
brand_question_versions	id question_id question_text question_hash version_no is_active	uk_question_version_no idx_question_hash
competitors	id tenant_id brand_id name website description product_lines_json	idx_competitor_brand

13.11.4 知识库

表	关键字段	关键约束/索引
knowledge_groups	id tenant_id name parent_id sort_order	uk_knowledge_group_name
knowledge_items	id tenant_id group_id source_type name storage_key status size_bytes	idx_knowledge_item_group_status
knowledge_parse_tasks	id tenant_id knowledge_item_id source_type status error_message	idx_parse_task_status
knowledge_chunks_meta	id tenant_id knowledge_item_id chunk_index token_count qdrant_point_id item_version status	idx_chunk_item_version

V1 的 retrieval_logs 与 rag_eval_cases 先不落数据库表，统一写文件日志或对象存储采样归档，待评测体系成熟后再升级。

13.11.5 媒体平台与插件执行

表	关键字段	关键约束/索引
media_platforms	id platform_code name category adapter_key status	uk_media_platform_code
platform_accounts	id tenant_id user_id platform_id platform_uid nickname avatar_url status last_check_at	uk_platform_account_identity
plugin_sessions	id tenant_id user_id action_type platform_id session_token client_version expire_at status	uk_plugin_session_token idx_plugin_session_expire
publish_records	id tenant_id article_id platform_account_id platform_id status external_article_id error_message request_payload_json response_payload_json	idx_publish_record_article_created

13.11.6 数据追踪

表	关键字段	关键约束/索引
question_monitor_runs	id tenant_id brand_id keyword_id question_id question_version_id model_id run_date run_at task_batch_id status raw_answer_storage_key	idx_monitor_runs_query
question_monitor_parse_results	id run_id mentioned_brand top1_mentioned first_recommended positive_mentioned citation_article_count citation_platform_count parser_version	uk_parse_result_run
question_model_daily_metrics	tenant_id brand_id keyword_id question_id question_version_id model_id date ask_count mention_count top1_mention_count first_recommend_count positive_mention_count citation_count	uk_question_model_daily
keyword_model_daily_metrics	tenant_id brand_id keyword_id model_id date ask_count mention_rate positive_mention_rate	uk_keyword_model_daily
keyword_model_top_questions_daily	tenant_id brand_id keyword_id model_id date question_id score	idx_top_questions_daily
keyword_model_citation_rank_daily	tenant_id brand_id keyword_id model_id date cited_article_id citation_count	idx_citation_rank_daily

保留策略建议与专项监控方案对齐：原始运行记录 30 ~ 90 天、解析结果 90 天、日级汇总 180 天或更久。

13.11.7 平台任务与审计

表	关键字段	关键约束/索引
task_records	id tenant_id task_type resource_type resource_id status retry_count task_batch_id	idx_task_record_status_type
audit_logs	id operator_id tenant_id module action before_json after_json result created_at	idx_audit_module_created
config_change_logs	id operator_id scope_type scope_id change_type diff_json	idx_config_change_scope
quota_change_logs	id operator_id tenant_id quota_type delta reason	idx_quota_change_tenant
risk_action_logs	id operator_id tenant_id risk_type reason result	idx_risk_action_tenant_created

13.12 闭环验收标准

以下标准满足时，可认为主技术架构已从“宏观方案”补齐为“可开发闭环方案”：

• 工作台 有独立聚合 API，不依赖前端拼装多个分散接口
• 模板创作 有模板定义、schema、批量生成和任务状态落点
• 自定义生成 有 Prompt 规则、定时任务、Scheduler 和幂等派发设计
• 文章优化 有优化任务、版本表、保存结果与回看路径
• 媒体管理 有插件执行端、插件会话、绑定回调、发布回调和状态同步
• 品牌词库 有关键词、问题、问题版本、竞品库与追踪关联
• 知识库 有分组、多来源解析策略、学习任务和对象存储落点
• 数据追踪 有明确采集单元、聚合表、缓存策略和查询口径
• 所有长任务都有 task_records、SSE 事件和轮询兜底
• 所有高风险操作、配置变更、额度变更、发布失败补偿都有审计记录

13.13 面向 5 万并发与简单运维的运行策略

13.13.1 Gateway 水平扩展与负载均衡

• gateway 必须保持无状态，允许多实例水平扩展
• 线上入口通过 Ingress / Nginx 做 L7 负载均衡，前端无需感知后端实例
• Kubernetes 建议为 gateway 配置 HPA，核心观测指标为：CPU、RPS、active_connections
• gateway 到 tenant-api / platform-api 之间通过集群内部 Service 直连，V1 不引入额外服务网格
• gateway 只允许承担统一入口职责，不允许沉淀业务编排、任务控制、数据聚合与数据库业务写入

13.13.2 Scheduler 故障恢复策略

• V1 默认采用 单活 scheduler + 健康检查 + 自动重启
• scheduler 重启后必须重新扫描 next_run_at <= now() 的计划任务，并按幂等键自动追回漏派发任务
• 若计划任务已超出允许追赶窗口，则记录为 skipped/expired 并写入审计日志
• 派发状态需保留 lease_owner、dispatch_lease_until、last_dispatch_at，便于故障排查和追赶

13.13.3 PostgreSQL 分区、索引与归档

• audit_logs、config_change_logs、quota_change_logs、risk_action_logs 按月分区
• question_monitor_runs、question_monitor_parse_results、question_model_*、keyword_model_* 按日期分区
• articles 至少提供 (tenant_id, created_at desc)、(tenant_id, generate_status, publish_status, created_at desc) 复合索引
• 原始回答正文保留在对象存储 30~90 天，解析结果保留 90 天，聚合表保留 180 天+
• V1 先使用单 PostgreSQL 主实例；若读压升高，优先增加只读副本而不是立即拆库

13.13.4 限流、队列保护与熔断

• gateway 层增加基于 Redis 的租户级令牌桶限流，维度为 tenant_id + route_group
• tenant-api 在任务提交前校验：套餐额度、租户当日提交量、当前排队深度、模型通道状态
• worker-generate 对下游 LLM 调用统一使用 context.WithTimeout(30s)，并以 semaphore 控制单 consumer 组最大并发，V1 默认建议 50
• 交互式生成、批量生成、监控采集使用独立令牌桶；worker-analytics 默认只占用小比例低优先级通道，不能反压用户实时生成
• worker-generate 与 worker-analytics 的上游调用按 3s / 10s / 30s 做有限退避重试；熔断打开后只允许少量探测请求恢复
• worker-knowledge 的 Embedding 请求按 chunk 批量提交，建议单次 16 ~ 32 个 chunk，失败时自动拆批重试
• RabbitMQ 为生成队列配置最大长度和溢出策略，超过阈值时拒绝低优先级批量任务
• 平台端的强制重试、强制补量、限流豁免必须写审计日志

13.13.5 Redis 缓存与对象存储分发策略

• 工作台聚合、趋势图、高频问题、引用排行等热点查询使用 TTL + 抖动 + 异步刷新
• 对不存在的数据维度使用空值缓存，避免缓存穿透
• 高热点品牌数据在凌晨批量预热，避免白天冷启动击穿数据库
• 公有云部署推荐 OSS + CDN；私有化部署推荐 MinIO + Nginx / CDN
• 图片、封面、知识库原文件通过带签名的对象存储 URL 输出，走 CDN 分发
• 已删除知识文档的对象文件按 T+7 清理，原始模型回答按监控策略保留 30 ~ 90 天
• 发布请求/响应原始 payload 建议按审计需求保留 30 ~ 90 天，并由 GC 任务定期扫描孤儿文件

13.13.6 配置管理与动态加载

• V1 配置层级采用：base YAML -> 环境变量覆盖 -> 动态配置覆盖
• 动态配置仅用于可热更新项：限流阈值、功能开关、模型通道权重、adapter 开关、轮询/SSE 策略
• 结构性配置如数据库 DSN、MQ 地址、端口等仍通过重启生效，避免隐藏复杂度
• 所有动态配置变更进入 config_change_logs

13.13.7 Sponge 使用原则

• sponge 仅作为脚手架初始化工具使用，不采用其默认的业务 handler/service/dao 全量代码生成
• 如需复用少量样板代码，生成代码也必须按本文分层映射：handler -> transport、service/logic -> app、dao -> repository、domain 由业务手工维护
• tenant 与 platform 的双域拆分优先于代码生成习惯，架构设计始终先于框架约束

13.13.8 Migration 与 Schema 变更策略

• V1 推荐统一使用 golang-migrate 管理 Schema 版本，目录固定为 server/migrations/
• 命名规则建议：YYYYMMDDHHMMSS_description.up.sql 与对应 down.sql
• 线上 DDL 采用 expand / migrate / contract 三阶段，避免单次发布中直接删列、改类型或重建大索引
• 分区表、索引和长耗时 DDL 必须走预发演练；高风险变更在低峰窗口执行并保留回滚脚本

13.13.9 租户隔离与关键事务边界

• Repository 层必须提供 TenantScope(ctx) 或等价封装，租户侧查询默认自动注入 tenant_id
• 平台侧跨租户查询只允许出现在 platform/* 域；禁止在租户域直接手写绕过租户条件的 SQL
• CI 应增加静态检查或代码评审规则，重点扫描缺少 tenant_id 过滤的查询
• 关键事务边界至少包括：任务提交预扣额度、Worker 成功确认额度、Worker 失败退还额度、插件回调幂等落库

13.13.10 错误码、日志与链路追踪

• 所有进程统一使用结构化 JSON 日志，建议使用 zap
• gateway 为入口请求生成 request_id；若上游已带可信 request_id 则复用，并同时补充内部 trace_id
• API -> MQ -> Worker 全链路透传 request_id、trace_id、tenant_id、task_batch_id
• RabbitMQ 消息头必须包含上述追踪字段，Worker 落日志时原样打印
• V1 最低要求是“统一错误码 + 结构化日志 + request_id 贯通”；V1.5 再引入 OpenTelemetry / Jaeger
• 所有告警规则统一绑定 service、queue、tenant_scope、error_code 标签，便于聚合排查

13.13.11 本地开发、归档与运维模板

• 本地开发默认模式为“中间件容器化，Go 服务本地运行”，避免 docker compose up 同时拉起全部业务进程
• 提供统一的 make dev-init、make dev-api、make dev-workers 或等价任务入口，降低新人启动门槛
• 4 类 Worker 保持独立二进制，但共享同一套容器基座、健康检查协议、日志格式和 Helm 模板
• 审计表与监控表分区需配套归档脚本或定时作业，按月导出历史分区并清理超期数据
• 对象存储 GC、分区归档、死信队列巡检建议统一纳入 scheduler 的低频运维作业或独立运维 CronJob

14. 最终建议

如果当前目标是尽快落地并保持后续可扩展，最推荐的方案是：

• 前端采用双应用：apps/admin-web 与 apps/ops-admin-web
• V1 同步建设执行端：apps/browser-extension
• 共享能力全部沉淀到 packages/*
• 后端采用 gateway + tenant-api + platform-api + scheduler + 多 Worker 结构
• 统一使用 PostgreSQL + Redis + RabbitMQ + Qdrant + 对象存储
• 权限严格按 platform_role 与 tenant_role 分层
• 高风险操作统一纳入审计

这个方案的优点是：

• 前端边界清晰
• 后端复杂度可控
• 权限模型不混乱
• 既适合 V1，也方便未来演进到更细的服务拆分