UMHelper 技术说明（面向非 CS 背景同学）
这份文档的目标不是把大家训练成工程师，而是帮助非计算机背景的同学理解：
- 这个项目大致是怎么运作的
- 各个第三方平台分别负责什么
- 哪些改动是“低风险”的，哪些改动需要非常谨慎
- 遇到技术问题时，应该先问 AI 什么，应该找谁确认什么
如果你来自数据分析、金融、运营、产品等背景，这份文档应该足够支撑你理解项目全貌，并和技术同学高效协作。
1. 先讲结论
UMHelper 当前本质上是一个：
- 用
Next.js写的网页前端 - 用
Supabase / PostgreSQL存数据 - 用
Clerk做登录 - 部署在
Vercel - 配合
Cloudflare、Google 平台、Clarity 等第三方服务运行的项目
它不是一个“只有网页”的简单站点，而是一套由多个平台共同组成的线上系统。
2. 如果你不熟悉技术，哪些内容可以直接问 AI
以下内容，不建议花很多时间自己硬啃，可以直接问 AI：
Git是什么，怎么提交代码，怎么切换分支npm/pnpm是什么，怎么安装依赖- 什么是
Next.js、React、TypeScript - 什么是 API、数据库、环境变量
- 某个报错信息是什么意思
- 某段代码大概在做什么
推荐做法：
- 不要只问“这是什么”
- 要把你的目标一起告诉 AI
例如：
我不是 CS 背景，我只想把首页文案改掉，不想影响别的页面，请告诉我应该看哪个文件。
又例如：
我看到了
git pull报错，我不想理解 Git 原理，只想知道现在下一步该怎么做。
这类问题 AI 很擅长。
3. 这个项目可以粗略理解成什么
可以把它理解成一家小店：
Next.js是门店前台Supabase / PostgreSQL是仓库和账本Clerk是门禁和会员系统Vercel是店面所在的物业Cloudflare是路由和门牌系统Google Analytics / Clarity是摄像头和客流统计Google Search Console是搜索引擎沟通窗口Google Adsense是广告收入系统GitHub是源代码仓库
如果只看网页，就像只看到了店面；但真正维持运行的是后面的整套系统。
4. 各个平台分别负责什么
4.1 GitHub
作用：
- 存放代码
- 记录修改历史
- 支持多人协作
你可以把它理解为“项目源码的主仓库”。
非技术同学最常见的接触方式：
- 看 issue
- 看文档
- 看某次改动是为什么做的
如果你只是想知道“这段功能在哪个文件里”，可以直接问 AI，不一定要自己学 Git。
4.2 Vercel
作用：
- 部署网页
- 托管线上运行版本
- 处理构建、发布、域名绑定等流程
简单说，代码写完后，要有一个地方把网站真正跑起来，Vercel 现在就在做这件事。
要注意：
- 高峰期 Vercel 的免费套餐可能会有额度压力
- 所以未来可以探索别的部署方案，例如
Coolify、Dokploy、CapRover
4.3 Supabase
作用：
- 托管数据库
- 提供读写接口
- 管理部分数据权限能力
Supabase 底层核心其实还是 PostgreSQL 数据库。
可以把 Supabase 理解成“数据库 + 一层更好用的云平台界面”。
4.4 PostgreSQL
作用：
- 真正存放结构化数据
例如：
- 课程信息
- 教师与课程的对应关系
- 评论
- 投票
- 时间表
如果没有数据库，网页就无法展示内容，也无法记录用户提交的数据。
4.5 Clerk
作用：
- 用户注册 / 登录
- 身份验证
- 账户体系
如果以后要做更完整的用户体系、权限体系，Clerk 会变得更重要。
4.6 Cloudflare
作用：
- DNS
- 代理
- 边缘层能力
对非技术同学来说，可以简单理解成：
- 用户输入域名时，Cloudflare 负责把访问引导到正确地方
- 也可以承担部分网络层保护和优化工作
4.7 Google Analytics
作用：
- 看访问量
- 看来源
- 看页面表现
它回答的问题通常是：
- 有多少人来过
- 他们从哪里来
- 他们看了哪些页面
4.8 Google Search Console
作用：
- 看 Google 是否收录了网站
- 看搜索关键词
- 看搜索相关健康状态
它更偏“网站在搜索引擎里的表现”。
4.9 Google Adsense
作用：
- 广告投放
- 广告收入结算
目前这部分和收入直接相关。
4.10 Clarity
作用：
- 看用户行为回放
- 看页面交互过程
和 GA 的区别是：
- GA 更偏统计
- Clarity 更偏“用户具体是怎么操作页面的”
5. 当前项目大致怎么运行
可以用下面这个思路理解：
- 用户打开网页
- 网页前端向后端 / 数据库请求内容
- 数据库返回课程、评论、教师等信息
- 页面把内容展示出来
- 用户如果提交评论、投票、登录，会触发新的写入或鉴权流程
更具体一点：
- 课程页会读取课程、教师、是否开课等信息
- 评论页会读取评论列表、投票记录、时间表等信息
- 评论提交会往数据库写新评论，并更新相关统计
6. 从代码里能看出的几个真实技术点
这一部分不要求你会写代码，但建议理解，因为它会影响未来的演进方向。
6.1 这不是一个“纯前端项目”
虽然用户看到的是网页，但它实际包含：
- 页面渲染
- 数据读取
- 数据写入
- 用户鉴权
- 第三方平台联动
所以很多改动不是“改改文案”那么简单。
6.2 评论系统已经是核心业务系统的一部分
评论不是附属功能，它已经影响：
- 页面内容
- 教师评分
- 用户体验
- 数据可信度
这意味着评论相关的改动要特别谨慎。
6.3 当前项目还保留了不少历史技术包袱
从代码里可以看到一些典型现象：
- 数据命名存在历史痕迹
- 数据访问和页面逻辑耦合比较紧
- 某些统计逻辑还在应用层手工处理
- 部分外部数据拉取还在用户请求链路上
这些都不是“项目坏掉了”，而是很典型的“业务先跑起来，后面再整理”的状态。
7. 数据库要怎么理解
7.1 什么是数据库
数据库就是系统的“事实记录中心”。
网页只是显示层。
真正的课程、评论、投票、排课信息都在数据库里。
7.2 为什么数据库结构重要
因为数据库结构决定了：
- 后续加功能难不难
- 查数据快不快
- 容不容易出错
- 有没有办法做权限控制
7.3 为什么 RLS 很重要
RLS 全称是 Row Level Security，可以理解成“数据库按行做权限控制”。
对非技术同学来说，最简单的理解是：
- 哪些人能读
- 哪些人能写
- 哪些数据不能让普通用户直接碰
如果这层做不好，后面就容易出现：
- 不该写的数据被写了
- 不该改的数据被改了
- 数据安全边界模糊
8. 部署要怎么理解
8.1 什么叫部署
部署就是：
把本地代码变成线上真正可以访问的网站。
8.2 为什么部署不只是“点一下按钮”
因为部署通常还会牵涉：
- 环境变量
- 域名
- 数据库连接
- 构建过程
- 线上报错
8.3 为什么未来要考虑 Vercel 之外的部署方式
主要有几个现实原因：
- 控制成本
- 降低平台绑定
- 在高峰期拥有更灵活的资源配置方式
适合了解但不必深究的开源平替包括：
CoolifyDokployCapRover
如果你只是想知道“它们是什么”，可以直接问 AI：
Coolify / Dokploy / CapRover 分别适合什么场景？和 Vercel 相比差异是什么？
9. 流量与成本要怎么理解
UMHelper 的流量有明显季节性：
- 平时较平稳
- 选课相关时期会明显冲高
这意味着：
- 高峰期和低峰期的成本压力完全不同
- 免费套餐平时够用，不代表高峰期也够用
当前需要特别注意：
VercelSupabase
在高峰期存在套餐额度压力。
这类问题的本质不是“网站坏了”，而是：
- 请求量太高
- 查询太多
- 页面缓存策略不够细
- 基础设施留给高峰的余量不够
10. 哪些改动风险低，哪些改动风险高
10.1 相对低风险
- 文案修改
- 静态说明页修改
- 新增说明性内容
- 页面布局小改
- 增加数据看板或只读分析页面
10.2 中风险
- 搜索逻辑修改
- 评论展示规则修改
- 页面缓存策略调整
- 新增数据来源
10.3 高风险
- 数据库结构修改
- 评论写入逻辑修改
- 权限策略修改
- 登录鉴权链路修改
- 部署方式切换
- 域名 / DNS / 环境变量调整
高风险改动的建议是：
- 一定先让 AI 帮你梳理影响范围
- 再让技术同学 review
11. 如果你不是 CS 背景，最推荐的工作方式
11.1 把自己当成“能提出清晰需求的人”
你不一定要会写代码，但你应该尽量会说清楚：
- 用户是谁
- 想解决什么问题
- 输入是什么
- 输出是什么
- 成功标准是什么
这比“会不会写一段代码”更重要。
11.2 先让 AI 帮你整理问题
例如不要只说：
我想优化评论系统
而是说：
我想优化评论系统，目标是减少低质量评论，提高课程评价可信度。请从产品、数据、技术风险三个角度帮我拆解方案。
11.3 让 AI 做第一轮技术翻译
当你看到：
- 报错信息
- 环境变量
- 数据表名
- 部署日志
先把它丢给 AI，请它翻译成人话，再决定要不要找技术同学深入处理。
12. 很适合非 CS 同学用 AI 做的事情
- 把想法整理成需求文档
- 把模糊问题拆成执行步骤
- 把报错信息翻译成人话
- 帮你找某个功能可能在哪些文件里
- 帮你写测试文案、埋点方案、页面草稿
- 帮你比较几个部署方案或第三方平台
- 帮你整理会议纪要、技术讨论结论
13. 不建议完全交给 AI 的事情
- 直接修改生产数据库
- 直接改权限策略
- 直接切换部署平台
- 直接改支付 / 计费 / 广告相关配置
- 在没有 review 的情况下合并高风险代码
AI 适合提速，不适合代替验收。
14. 建议大家常用的提问模板
14.1 想理解一个平台
我不是 CS 背景，请用通俗语言解释
Supabase / Clerk / Vercel / Cloudflare在这个项目里分别负责什么。
14.2 想理解一个错误
这是我现在看到的报错，请先用人话解释原因，再告诉我最安全的下一步操作。
14.3 想改一个功能
我想改这个功能，但不想影响别的页面。请告诉我最可能涉及哪些文件、哪些风险点、如何验证没有改坏。
14.4 想提产品需求
目标用户是谁： 想解决的问题是什么： 输入有哪些： 输出是什么： 成功标准是什么： 请把这个想法整理成一个适合和工程同学讨论的需求草案。
15. 最后一句
在 AI 时代，非技术同学不需要都学会写代码；
但大家越来越需要学会：
- 看懂系统大致怎么运作
- 知道哪些平台各自负责什么
- 识别高风险改动
- 借助 AI 把想法讲清楚
这就是这份文档真正想解决的问题。