1. 背景
我们要做什么：我们用 Supabase 和 Claude Code 教大家怎么从零搭建一个”工资社保计算网站”。
最终成品展示：一个可以上传/预设一些员工工资，然后一键计算出简化版”社保公积金”并展示结果的页面。
学习的核心：从最基本的概念和逻辑出发，只关心一件事：如何借助 Claude Code，让我们的网站和外部数据库 Supabase 对话。
这个案例的帮助：这个案例的真正价值，不在于教大家怎么计算五险一金。重点是让大家学会如何搭建数据库、编写后端处理逻辑、并在前端完成交互，体验完整网站开发的流程。有了这套思路和能力，大家以后可以根据自己的实际需求，快速搭建出各类实用的前后端网站。
学完你会真正掌握”前端 + 后端 + 数据库”完整开发链路，能把业务逻辑和数据管理结合起来，为自己或团队搭建各种实用的工具和网站。
1.1 案例分为三大部分，每一部分都必不可少：
数据仓库（后端存储）
需要有地方存放业务数据。我们用三张表（数据库）：
- 城市标准表：放各种城市的社保基数和比例，像政策规则库。
- 员工工资表：存每个员工每月工资，是所有计算的起点。
- 计算结果表：存最终算出来的结果，比如每个人各该交多少，方便后续展示。
后台逻辑（处理引擎）
也就是所有自动计算的”流水线”。流程很直接：
- 先拿到员工工资数据，算出平均工资；
- 再去城市标准查相应的社保政策（上下限）比较，选出合适的缴费基数；
- 根据不同比例公式，分别算公司和个人应交的钱；
- 把所有结果保存进数据库
前端展示（用户操作界面）
数据、算法都在幕后，用户需要看得见、用得着的页面。这个网站做了两个基础页面：
- 操作页面：可以上传工资数据、点击按钮发起计算
- 结果页面：把刚才算出来的所有结果一目了然地展示出来，让用户一看就懂
2. 创建数据库
2.1 注册并创建 Supabase
Supabase 可以类比为”装备齐全的乐高式云端数据中心”。它不仅有数据库这个”仓库”，还自带 API（对外开放的服务窗口）、身份验证（安全门禁系统）、实时数据同步等多功能。用它，你不仅能方便地存储和管理数据，还能快速为你的网站或应用搭建一套完整的数据服务，不需要自己拼凑复杂的后端。
访问 supabase.com 并完成账号注册。
登录后，点击创建新组织（New Organization）。
- 在 Name 中填入你的组织名称，这就像是给你的虚拟公司起个名字。
- 在 Type 中选择 Personal，因为我们目前是个人学习或测试使用。
- 在 Plan 中务必选择 Free – $0/month。Supabase 的免费计划非常良心，提供的资源足够我们在初期开发和测试阶段使用，不需要支付任何费用。
2.2 创建一个新项目
项目是我们存放具体数据和逻辑的地方。每个项目都拥有独立的数据库实例和 API 接口。
需要注意的是，免费账户最多可以创建两个项目，而且如果项目在 7 天内没有任何访问活动，会被系统自动暂停以节省资源（再次使用时手动激活即可）。长期不用会被系统删除。
在组织页面点击 Create a new project。
- 在 Organization 中选择刚才创建的组织。
- 在 Name 中填入项目名称，例如”社保计算器”。
- 在 Database Password 中输入一个强密码。请务必记住这个密码，它是你直接连接数据库的最高权限凭证，如果丢失可能需要重置。
- 在 Region（地区）中选择 Northeast Asia (Tokyo)、首尔或新加坡。这样做是因为物理距离越近，数据的传输延迟就越低，我们在国内访问时的速度和稳定性会更好。
侧边栏常用的菜单包括：Table Editor、SQL Editor、Project Settings
2.3 获取项目连接凭证（API Keys）
创建好项目后，我们需要获取几把关键的”钥匙”，以便后续让我们的程序能够连接到这个云端仓库。
获取 Project ID（如下图所示）：
进入项目面板，点击左侧侧边栏底部的 Project Settings（齿轮图标）。
在 General 页面中，找到 Project ID。这是一串由字母和数字组成的唯一标识符，就像是这个项目的”身份证号”，请复制并保存它，后续配置代码时需要通过它来定位你的项目。
获取 API Keys（如下图所示）：
继续在 Project Settings 菜单中，点击 API 选项。
这里你会看到两把钥匙：
- 第一把是 anon key：这是一把”访客钥匙”，它的权限受到严格限制。我们通常把它放在前端代码中，用于执行普通的查询任务，它是相对安全的。
- 第二把是 service_role key：这是一把”万能钥匙”，拥有绕过所有安全策略的最高读写权限。切记：这把钥匙绝对不能暴露在任何公开的代码或前端文件中，只能存储在服务器端或本地的安全环境里，否则任何人拿到了它都能随意篡改你的数据库。
请将这两把钥匙都复制下来妥善保存。
Claude Code 通过 anon key 和 service_role key 来跟 Supabase 数据库交互。
如何安全地保管”万能钥匙”？ 使用 .env.local 文件，这是 Next.js 中存放秘密信息的地方（后续章节展开）
2.4 准备 Excel 形式的初始数据
我们需要准备两张基础表：一张是城市社保基数表，另一张是员工工资表。
我们准备一份 Excel 格式的初始数据，主要是城市表和工资表这两项原始数据表，需要导入到网站，结果表是后面根据业务逻辑计算后输出展示的内容，不需要导入。
提前下载数据表：
准备城市表 (cities.xlsx)（如下图所示）：
新建一个 Excel 文件，命名为 cities，这张表的作用是为计算器提供各地的政策标准数据。
我们需要定义以下列：
- id：这是唯一的编号，用于区分每一行数据。
- city_name：填写城市名称，如”佛山”。
- year：填写适用年度，如”2024″。
- rate：填写该城市的社保计算比例，例如 0.014。
- base_min：填写社保缴费基数的下限，例如 4546。
- base_max：填写社保缴费基数的上限，例如 26421。
准备工资表 (salaries.xlsx)（如下图所示）：
新建另一个 Excel 文件，命名为 salaries，这张表代表了我们需要处理的原始业务数据。
我们需要定义以下列：
- id：同样作为唯一编号。
- employee_id：填写员工工号，如”0001″。
- employee_name：填写员工姓名，如”张三”。
- month：填写工资发放月份，如”202401″。
- salary_amount：填写该月实际发放的工资金额。
关于结果表 (results)：
我们还需要规划一张结果表，包含员工姓名、年度平均工资、计算出的应缴金额等字段。但这张表不需要现在创建 Excel，因为它将由我们的程序根据前两张表的数据计算后自动生成并写入数据库。
准备好这两个 Excel 文件后，我们在后续步骤中就可以直接将它们导入到 Supabase 中。
我们需要定义以下列：
- id （编号）
- employee_id （员工工号）
- employee_name （员工姓名）
- avg_salary （年度平均工资）
- calculated_fee （计算出的养老保险应缴纳金额）
3. 跟 AI 聊清楚需求，与 CC 进行对话
3.1 先跟 AI 聊清楚，经裁剪后形成一套需求提示词
（最好在提示词结尾加上一句：复述我的需求，提出你的问题。）
你好，我需要你扮演一位资深的 Web 全栈开发工程师。我们将一起合作，从零开始构建一个Web应用。在开始编写任何代码之前，你的首要任务是完全理解我的需求，然后为我们接下来的工作制定一个清晰的计划。
请仔细阅读下面的项目需求说明，然后生成文件：
claude.md: 这个文件将作为我们整个项目的"上下文管理中枢"。它应该清晰地总结项目的目标、技术栈、数据结构、核心逻辑和前端功能。当我们后续进行开发时，你会始终参考这个文件，以确保不会偏离方向。其中非常重要的一部分是todolist，这是一个详细的、分步骤的开发任务清单。它应该列出从环境搭建到最终功能实现的所有具体步骤。
### 项目需求说明
1. **项目目标**
我们要构建一个迷你的"五险一金"计算器Web应用。核心功能是根据预设的员工工资数据和城市社保标准，计算出公司为每位员工应缴纳的社保公积金费用，并将结果清晰地展示出来。
2. **技术栈**
- 前端框架: Next.js
- UI/样式: Tailwind CSS
- 数据库/后端: Supabase
3. **数据库设计 (Supabase)**
我们需要在 Supabase 中建立三张数据表：
**cities (城市标准表)**
- id (主键, int)
- city_name (城市名, text)
- year（年份，text）
- base_min (社保基数下限, int)
- base_max (社保基数上限, int)
- rate (简化的综合缴纳比例, float, 例如 0.15)
**salaries (员工工资表)**
- id (主键, int)
- employee_id (员工工号，text)
- employee_name (员工姓名, text)
- month (年份月份, YYYYMM，text)
- salary_amount (该月工资金额, int)
**results (计算结果表)**
- id (主键, int)
- employee_name (员工姓名, text)
- avg_salary (年度月平均工资, float)
- contribution_base (最终缴费基数, float)
- company_fee (公司缴纳金额, float)
4. **核心业务逻辑**
我们需要一个核心的计算函数，它的执行步骤如下：
- 从 salaries 表中读取所有数据。
- 按员工姓名 (employee_name) 分组，计算出每位员工的"年度月平均工资"。
- 以"佛山"为例，从 cities 表中获取其 year、base_min, base_max, 和 rate。
- 对于每位员工，将其"年度月平均工资"与佛山的基数上下限进行比较，以确定"最终缴费基数"。规则是：低于下限用下限，高于上限用上限，在中间则用平均工资本身。
- 根据"最终缴费基数"和 rate，计算出"公司应缴纳金额"。
- 将每位员工的计算结果（姓名、平均工资、缴费基数、公司应缴纳金额）存入 results 表。
5. **前端页面功能**
我们需要构建一个拥有三个独立页面的前端应用：
**/** (主页)
- 定位: 这是应用的入口页面和导航中枢。
- 布局: 页面核心是两个并排或垂直排列的功能卡片（Card），风格类似参考图片。
- 卡片一："数据上传": 卡片内有标题"数据上传"和简要说明。整个卡片是一个可点击的链接，点击后会跳转到 /upload 页面。
- 卡片二："结果查询": 卡片内有标题"结果查询"和简要说明。整个卡片也是一个可点击的链接，点击后会跳转到 /results 页面。
**/upload** (数据上传与操作页)
- 定位: 这是后台操作的控制面板，用于数据准备和计算触发。
- 功能: 页面上需要放置两个功能按钮：
- 按钮一："上传数据": 点击后，可以从本地电脑选择 excel 表，并向 Supabase 的 cities 表和 salaries 表中插入数据，方便我们进行后续的计算和测试。
- 按钮二："执行计算并存储结果": 点击后，会触发执行 【4. 核心业务逻辑】 中定义的所有计算步骤，并将最终计算出的所有员工数据存入 results 表。
**/results** (结果查询与展示页)
- 定位: 这是计算成果的最终展示页面。
- 功能:
- 当页面加载时，它需要自动从 Supabase 的 results 表中获取所有已存入的计算结果。
- 使用一个结构清晰、样式简洁的表格 (使用 Tailwind CSS) 将所有结果数据展示出来。表格的表头应与 results 表的字段（如 employee_name, avg_salary 等）一一对应。
### 你的任务：
请根据以上全部需求，首先生成 claude.md 这个计划文件。不要生成任何代码。等待我审查并确认计划后，我们再开始具体的编码工作。
复述我的需求，提出你的问题。
3.2 本地新建文件夹，在 VS Code 中打开这个文件夹，并启动 CC
把聊好的提示词粘贴给 CC。我们在提示词最后补充一句”复述我的需求，提出你的问题”，便于跟 CC 对齐工作任务的理解。
CC 会提出它需要你进一步澄清的问题，很多可能确实当时没有考虑到或者 CC 没有完全理解，需要进行澄清。
CC 按要求创建了 CLAUDE.MD 的文件：
3.3 跟 CC 一起干活完成编程
在正式让 CC 写代码之前，建议先用 plan 模式，让 CC 给出他的计划，如果没问题了，就切换到 edit automatically 干活。
如果心大对 AI 很放心，启动 CC 的时候也可以直接用 YOLO 模式打开（这个模式下 AI 在整个过程中操作基本都不会再找你确认）。打开方式是终端启动的时候输入 claude --dangerously-skip-permissions
以下是跟 CC 干活对话的截图：
此时，CC 已经初步完成开发：
3.4 完成 Supabase 的配置
我们看到 CC 需要我们完成 Supabase 的配置，要给它提供必要的 Supabase 相关信息，包括：
- 项目 URL：这个项目 URL 就是我们在初始配置的时候拿到的 Project ID 然后配上一个固定的地址（.supabase.co），类似这种： https://ilhxfqshrutkkoyukabf.supabase.co
- Anon Key：我们之前已经获取到的 Anon Key
然后把这两个信息配置到 .env.local 文档中：
3.5 完成 Supabase 的建表
我们还要在 Supabase 中完成建表，一般是在 SQL Editor 这个位置用 SQL 指令建表，CC 已经给我们准备好了整体的建表语句：按照 README.md 中的 SQL 语句在 Supabase 中创建三张表，我们只需要在 SQL Editor 中执行即可：
在 Supabase 中执行，把语句粘到 SQL Editor 里运行一下，点右下角的 RUN：
运行成功后，在 Table Editor 中发现已经成功创建三张表：
3.6 测试和调试改 BUG
让 CC 启动运行服务，CC 启动完成后，在浏览器中打开 localhost:3000
首页：
数据上传页：
结果查询页：
过程中可能出现很多报错，如果报错了，也不要紧张，这个是很正常的情况，需要耐心与 CC 交流解决。把问题截图或者报错的文字信息粘贴给 CC，让 CC 改错直到成功。
另外去 Supabase 数据库里检查一下，数据是否正常，尤其是中文能否正常显示：
过程中不断出现 bug，这是正常现象，要耐心解决。可以按 F12 或是鼠标右键选择检查，在 console 页签下找到具体报错的描述，把这个描述复制下来，粘贴给 CC。
4. 部署到 Vercel
部署到 Vercel 之前，请先把代码提交到 GitHub 上，这里就先省略了…
4.1 部署到 Vercel 上
如果我们想把 GitHub 上的代码部署到网站上，让其他人通过网址也能访问到。我们就需要使用 Vercel 这样的部署网站来操作。
打开 vercel.com（此处需要能够访问外网环境），用 GitHub 账号登录。
登录后新建项目：
找到我们在 GitHub 中要部署的仓库，点击 import：
简单的网站这里基本上是不需要设置的，直接点 Deploy 按钮：
过程中可能会出现部署错误，不要紧张，把错误信息贴给 CC，让他帮忙解决。顺利解决后，重新部署，成功后会出现提示页面：
成功部署后的网站 https://wuxianyijin1115-7e76.vercel.app/（也需要能够访问外网）：
以上便是使用 Claude Code + Supabase 搭建一个带数据库的网站应用的方法和步骤，学会了这个方法，你可以结合自己的业务场景，做一个符合自身需求的拥有前后端的网站，并把它上传到 GitHub 上，还可以部署到 Vercel 上。大家赶快去试一下吧。