Skip to content

system-architecture.md

Latest commit

 

History

History
345 lines (253 loc) · 7.91 KB

system-architecture.md

File metadata and controls

345 lines (253 loc) · 7.91 KB

TGO Network 总体架构

1. 项目目标

当前项目已经从更宽泛的内容平台方向，收敛为一个更明确的「科技领导者社区 / 组织展示与运营平台」。

当前版本的前台必须包含以下 7 个公开模块：

  • 首页
  • 分会董事会
  • 成员列表与成员详情
  • 活动列表与活动详情/报名
  • 文章列表与文章详情
  • 加入申请说明与申请表
  • 关于我们

当前版本的后台必须包含以下 8 个运营模块：

  • 仪表盘
  • 文章管理
  • 活动管理与报名审核
  • 申请审核
  • 成员管理
  • 工作人员管理
  • 角色与权限配置
  • 审计日志

当前不再把下列能力视为本阶段的一线范围：

  • 主题专题页 topics
  • 独立城市内容页 cities
  • 训练营 / 企业图谱 / 成员中心
  • 支付、发票、复杂工作流引擎

2. 已确认技术栈

前端

  • 公开站点：Astro
  • 管理后台：Vue + Vite

后端

  • API 框架：Hono
  • 数据库：PostgreSQL
  • ORM 与迁移：Drizzle ORM + Drizzle Kit
  • 身份认证：Better Auth
  • 文件存储：S3-compatible object storage

基础设施

  • Monorepo：pnpm workspace
  • 运行时：Node.js
  • 部署：Docker + 任意标准 Node 兼容平台

3. 高层架构

Visitors / Members
  -> apps/site (Astro)

Staff Users
  -> apps/admin (Vue + Vite)

apps/site / apps/admin
  -> apps/api (Hono)
  -> Better Auth routes

apps/api
  -> PostgreSQL
  -> S3-compatible object storage

核心边界：

  • apps/site 负责品牌展示、SEO、公开浏览、低交互页面
  • apps/site 也承担成员侧前台能力，例如成员查看信息、活动报名等
  • apps/admin 负责内部表格、表单、审核、权限化操作
  • apps/api 是唯一业务入口，承载业务规则与鉴权
  • PostgreSQL 保存结构化业务数据
  • S3 保存图片等二进制文件，数据库仅保存元数据

4. 仓库结构

apps/
  site/         Astro 前台
  admin/        Vue + Vite 后台
  api/          Hono API

packages/
  db/           Drizzle schema / migrations / seeds
  shared/       共享 DTO、zod schema、常量
  ui/           可选的共享设计令牌或工具

docs/
  规划与设计文档

结构原则：

  • 不把前台和后台混入同一个前端框架
  • 不把业务规则下沉到前端
  • 共享的是契约，不是把所有实现耦合到一起

5. 前台渲染策略

Astro 继续作为公开站点的主框架，但不同页面的渲染方式需要区分：

  • 首页、加入说明页、关于我们：静态优先
  • 分会董事会页：静态优先，数据更新后重建或按需刷新
  • 成员列表：支持服务端分页或按需渲染，避免大规模静态生成压力
  • 成员详情、文章详情、活动详情：静态优先，必要时支持混合渲染
  • 报名与申请表：页面可静态，提交必须走 API
  • 当前阶段不引入成员认证，活动报名采用开放提交 + 后台审核确认

设计目标：

  • SEO 友好
  • 内容可被后台驱动更新
  • 仅在必要处使用 Astro islands 或客户端交互

6. 后台定位

Vue + Vite 后台是一个典型的内部运营控制台，重点在于：

  • 表格列表
  • 复杂表单
  • 审核流转
  • 权限化导航
  • 审计追踪

后台一级导航以用户要求的 8 个模块为准。

其中部分支持性能力不一定需要独立一级菜单：

  • 首页配置
  • 加入页 / 关于页内容管理
  • 资源上传与图片选择
  • 分会与董事会成员维护

这些能力可以作为成员域或内容域下的二级页面存在。

7. 后端职责

Hono 负责：

  • 公开站点读取 API
  • 后台管理 API
  • Better Auth 挂载与会话校验
  • 参数校验、权限校验、业务规则执行
  • S3 上传签名与文件元数据落库
  • 审计日志记录
  • 健康检查与内部任务接口

推荐 API 分组：

  • /api/public/v1/*
  • /api/admin/v1/*
  • /api/auth/*
  • /api/internal/v1/*

8. 核心业务域

当前版本的核心域应收敛到以下 8 类：

  • 成员与工作人员
    • members
    • users（当前主要用于工作人员认证）
    • staff_accounts
    • roles
    • permissions
  • 站点基础内容
    • site_settings
    • homepage_sections
    • site_pages（join / about）
  • 分会与董事会
    • branches
    • branch_board_members
  • 文章
    • articles
  • 活动
    • events
    • event_registrations
    • event_agenda_items
  • 加入申请
    • join_applications
  • 媒体资源
    • assets
  • 运营审计
    • audit_logs

关键建模约束：

  • members 是成员业务域
  • staff_accounts 是工作人员后台准入域
  • 两者完全分开建模，不做包含关系，不做默认映射
  • users 当前主要服务于工作人员认证，不默认承载成员身份
  • 分会既承担组织展示，也承担活动城市筛选维度
  • 公开页面看到的内容必须全部来源于已发布数据

9. 身份认证与权限

认证与授权继续分离：

  • Better Auth 解决“你是谁”
  • 业务表和中间件解决“你能做什么”

这里必须区分两套完全不同的概念：

  • 人群身份分类
    • 非成员访客
    • 申请人
    • 成员
    • 工作人员
  • 工作人员 RBAC 角色
    • super_admin
    • content_editor
    • event_manager
    • 等后台权限角色

重要说明：

  • “成员”不是后台里的一个 role
  • “角色”菜单只服务于工作人员后台权限管理
  • 非成员提交加入申请，不参与后台角色体系
  • 成员前台能力与工作人员后台权限必须分别建模

当前后台权限最少需要覆盖：

  • 仪表盘查看
  • 页面内容管理
  • 文章管理
  • 分会/董事会管理
  • 成员管理
  • 活动管理
  • 活动报名审核
  • 入会申请审核
  • 工作人员管理
  • 角色权限管理
  • 审计日志查看

未来如切换手机号登录，只应增加一种登录方式，不应重建身份体系。

10. 文件与媒体策略

对象存储主要承载：

  • 首页横幅与精选图片
  • 分会封面图
  • 董事会成员头像
  • 成员头像
  • 文章封面与正文插图
  • 活动海报与嘉宾图片

原则：

  • 二进制文件存 S3
  • 元数据与引用关系存 PostgreSQL
  • 前台永远通过资产元数据推导 URL，不在业务记录里硬编码外链

11. 部署模型

推荐域名拆分：

  • www.example.com：前台
  • admin.example.com：后台
  • api.example.com：API
  • assets.example.com：CDN 或对象存储访问域名

部署方式：

  • apps/site：静态托管或 Astro SSR 容器
  • apps/admin：静态托管
  • apps/api：Docker 化 Node 服务

这样可以保持平台兼容性，不被单一厂商锁死。

12. 当前阶段划分

Phase 0：架构与文档基线

已完成：

  • 技术栈确认
  • 仓库结构确认
  • 系统边界确认
  • 目标站基准分析

Phase 1：运行骨架与基础设施

已完成或基本完成：

  • Monorepo 脚手架
  • API / Site / Admin 基础工程
  • 数据库与认证打通
  • 基础测试与 CI

Phase 2：范围收敛与契约冻结

当前已完成：

  • 将产品范围收敛到 7 个前台模块和 8 个后台模块
  • 以 branches / members / join_applications 为主线重整数据模型和 API
  • 将旧的 topic/city 方向降级为历史探索，不再作为当前交付边界

Phase 3：前台能力对齐

下一步交付：

  • 首页
  • 分会董事会
  • 成员列表/详情
  • 活动列表/详情/报名
  • 文章列表/详情
  • 加入说明/申请
  • 关于我们

Phase 4：后台能力对齐

下一步交付：

  • 仪表盘
  • 文章管理
  • 活动管理与报名审核
  • 申请审核
  • 成员与分会维护
  • 工作人员与角色权限
  • 审计日志

Phase 5：运营加固

后续增加：

  • 更细粒度的审计与告警
  • 缓存与重建策略
  • 备份恢复演练
  • 更完整的发布自动化

13. 已冻结的关键技术决策

  • 不引入 Next.js 作为核心框架
  • 不把前后台合并为单应用
  • 不让前端直接访问数据库作为主路径
  • 不把图片文件直接存进 PostgreSQL