Agent 编程课 16：全栈应用从 0 到上线

本文是 Agentic Coding 实战系列的一篇，也是实战部分的收官之作：把一个本地脚本升级成完整上线的 Web 产品。套路仍是熟悉的节奏：先写规格，再做分解，然后验证加 commit，只是这一次要从前端、后端、数据库一路做到部署。

从本地脚本到 Web 产品

一位律师学员此前做了一个"合同危险条款检测器"的本地 demo，律所负责人看后很满意，问了一句：能给所有律师都用上吗？

要把本地脚本升级成 Web 产品，至少要补上四件事：多用户能访问、数据能保存、有登录系统、全天候运行。

技术选型在这里是产品决策，不完全是技术决策。面向"快速验证"的场景，推荐 Next.js 加 Vercel 加 Supabase 的组合：

Next.js：前后端一体化，一个项目搞定；
Vercel：免费托管，一键部署；
Supabase：免费 PostgreSQL 数据库，自带用户登录。

选这套的逻辑很简单：需求方要的是快速验证产品，不是企业级架构，这套组合一天就能上线。

合同卫士处理流水线：上传、解析、切分、分析、入库、展示

项目规格：R F C 三件套

动手之前先写规格。要做一个简化但真实的合同检测 SaaS，规格长这样：

R 背景：律所内部工具，律师上传合同 PDF，系统标出"危险条款"，约 30 名律师使用。

F 功能分四块。用户系统：邮箱加密码登录（Supabase Auth），每个用户有自己的合同列表。核心功能：上传 PDF、提取文本、用 LLM 按 27 条规则分析危险条款、标红显示原文加风险等级加修改建议、一键导出修订报告。数据表：users 由 Auth 自带，contracts 存 id、user_id、filename、upload_date，risks 存 id、contract_id、clause_text、level、suggestion。界面：列表页、详情页（原文加标红加侧边栏建议）、上传页（拖拽上传）。

C 验收标准：能注册登录；上传一份测试合同 30 秒内出结果；业务验证是 27 条规则中至少检测出已知 5 个危险点；部署后手机能访问。

任务分解：5 个模块

这是系列实战中难度最高的一个项目，L2 层拆成 5 个模块：项目脚手架与数据库、用户认证、合同上传与解析、风险分析（核心业务）、界面与部署。

L3 任务清单按模块展开。例如模块一有初始化项目、配置 Supabase、设计 schema、写迁移脚本；模块四有把 27 条规则编码进 prompt、调用 Claude API、解析结果入库、业务验证。

MVP 路径也很清晰：脚手架、数据库、认证、上传解析、风险分析、列表页、部署，串起来就能先跑一个简版。

模块一：脚手架与数据库

初始化项目：

bash

npx create-next-app@latest contract-guardian
cd contract-guardian
git init

选项选 TypeScript、Tailwind CSS、App Router。然后去 supabase.com 注册（GitHub 登录免费），新建项目，拿到 NEXT_PUBLIC_SUPABASE_URL 和 NEXT_PUBLIC_SUPABASE_ANON_KEY 两个 key，存进 .env.local，注意不要提交进 Git。

设计 schema 可以让 Agent 起草，但业务字段必须自己拍板。比如面向律师的工作习惯：合同要有"对方公司名"字段；风险等级用 1、2、3 数字，而不是 low、medium、high；必须有 created_at，方便按时间排序。Agent 生成的迁移文件大致如下：

sql

-- supabase/migrations/001_init.sql
create table contracts (
  id uuid primary key default gen_random_uuid(),
  user_id uuid references auth.users not null,
  filename text not null,
  counterparty text,
  content text,
  upload_date timestamptz default now(),
  created_at timestamptz default now()
);

create table risks (
  id uuid primary key default gen_random_uuid(),
  contract_id uuid references contracts on delete cascade,
  clause_text text not null,
  clause_index int,
  level int not null check (level in (1,2,3)),
  rule_id text,
  suggestion text,
  created_at timestamptz default now()
);

-- RLS：用户只能看自己的合同
alter table contracts enable row level security;
create policy "用户看自己合同" on contracts
  for select using (auth.uid() = user_id);
create policy "用户插自己合同" on contracts
  for insert with check (auth.uid() = user_id);

注意看，schema 里全是业务判断：用 1、2、3 而不是枚举类型，加 counterparty 字段，这些 Agent 不知道，是律师的工作习惯。在 Supabase SQL Editor 里跑完这段 SQL，数据库就建好了。最后 git commit 存档。

模块二：用户认证

给 Agent 的任务描述包括：安装 @supabase/ssr 包；创建浏览器端与服务端两个客户端文件；实现登录与注册页面；用 middleware 保护 /dashboard 等页面；提供退出登录按钮。业务规则有三条：注册不需要邮箱验证（律所内部信任邮箱）；登录失败给清晰提示；用 Tailwind 做简洁界面。

Agent 生成的核心代码并不复杂，浏览器端客户端长这样：

typescript

// src/lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr'

export const createClient = () =>
  createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  )

看不懂 TypeScript 语法没关系，你只要知道这两个文件实现了登录页。验证方式是跑起来：npm run dev，打开 localhost:3000/login，注册一个账号，能登录成功就算过关，然后 git commit 存档。

模块三：合同上传与解析

上传模块的任务：/upload 页面支持拖拽上传 PDF；POST /api/upload 接收文件存 Supabase Storage；用 pdf-parse 提取文本；按业务规则分段；把合同记录插入数据库。

这里有一个典型的业务规则：中文合同通常按"第一条、第二条"组织，用正则 /第[一二三四五六七八九十百]+条/ 切分；没有"第X条"就按空行分段兜底；每段保留原文，不做任何"清洗"，因为律师要看原话。关键实现：

typescript

// src/app/api/upload/route.ts（关键部分）
const buffer = Buffer.from(await file.arrayBuffer())
const pdf = await pdfParse(buffer)
const content = pdf.text

// 业务规则：按"第X条"切分
const clauses = content.split(/第[一二三四五六七八九十百]+条[、，。\s]/)
  .filter(c => c.trim().length > 0)

const { data: contract } = await supabase
  .from('contracts')
  .insert({ user_id: user.id, filename: file.name, counterparty, content })
  .select()
  .single()

await analyzeContract(contract.id, clauses)

业务验证：上传一份真实合同，确认文本提取完整不是乱码、切分点按"第X条"正确、数据库里有记录。

模块四：风险分析，核心业务

这是最能体现需求方专业价值的模块。把多年的合同审查经验整理成一份规则书 rulebook.md，共 27 条，按三级分层：高危（如 R001 自动续约、R002 单方变更权）、中危、提醒，每条写清模式、风险、修改建议。

分析任务的要点：读取规则书；对每一段条款调用 Claude API，用 27 条规则逐条匹配；命中则返回 rule_id、level、clause_text、suggestion；结果批量插入 risks 表；异步执行并加节流，避免触发限流。

Prompt 设计的关键约束有三条：严格按规则书匹配，不要发明规则；没命中就返回空数组；一次只分析一段，不跨段。

业务验证是这个模块的核心关卡：故意构造一份包含 5 条已知风险的测试合同（比如 R001 自动续约、R005 管辖权、R012 违约金过高），跑完分析后核对，5 条全部命中才算过关。如果漏检，通常是 prompt 不够明确，让 Agent 加强规则描述再迭代，这是正常过程。

模块五：界面与部署

列表页 /dashboard 显示当前用户的所有合同，按时间倒序，每张卡片展示文件名、对方公司、上传日期和红黄蓝三色的风险数，点击进入详情。详情页左侧是合同原文，命中条款按风险等级标色（重为深红、中为橙、轻为黄），右侧 sticky 侧边栏列出风险明细与修改建议。标色用背景色而非文字色，方便律师扫读。顶部提供导出报告按钮。

部署到 Vercel 只要四步：用 GitHub 登录 vercel.com；点 New Project 选仓库；配置 Supabase 两个环境变量和 Anthropic API key；点 Deploy。两分钟后就能拿到一个 xxx.vercel.app 的网址。这就是零运维部署，不需要懂服务器。

一笔成本账

按 30 名律师、每人每天 5 份合同估算，这个产品的月成本：

项目	用量	月成本
Vercel 部署	免费档够用	$0
Supabase 数据库	免费档 500MB	$0
域名（可选）	vercel.app 子域名免费	$0 到 $10
Claude API	约 200 万 token/月	约 $8
合计		约 $8/月，约 55 元

对比商业版合同审核 SaaS，30 用户的月费通常 2000 美元起步，自建版本便宜约 250 倍，这就是"自己会做"的经济意义。

成本对比：商业合同审核 SaaS 月费约 2000 美元，自建版约 8 美元

五个常见的坑

本地能跑、部署后报错：最常见是环境变量没配到 Vercel，去项目设置的 Environment Variables 全部配一遍。
Supabase RLS 报错：行级安全默认拒绝所有访问，要明确配置 policy，例如 for all using (auth.uid() = user_id)。
API 超时：Vercel 免费版 API 限制 10 秒，长合同分析会超时，改异步方案：上传接口立刻返回，分析放后台跑（Vercel Cron、Inngest 或 QStash），前端轮询状态。
PDF 解析中文乱码：pdf-parse 对中文 PDF 支持一般，换 pdf2json 或 unpdf。
用户密码安全：永远不要自己实现密码系统，用 Supabase Auth，哈希、加盐、重置流程它都处理好了。