2025年09月15日 web

使用 TypeScript 构建 AI 驱动的自由职业者发票自动化后端

针对自由职业者，介绍如何用 TypeScript 和 Supabase 集成 AI 实现自动化发票处理、时间追踪和文件对账的后台系统。

内容加载中...

自由职业者常常面临时间追踪、发票生成和财务对账的繁琐工作。构建一个 AI 驱动的 TypeScript 后端，可以自动化这些流程，提高效率。本文聚焦于使用 Next.js 和 Supabase 搭建核心架构，并集成 OpenAI 等模型实现文件对账和财务概述功能。

首先，理解需求：自由职业者需要实时追踪项目时间、自动生成发票、匹配收据与交易记录，以及提供财务洞察。Midday 项目提供了一个开源参考，它使用 TypeScript 作为核心语言，结合 Supabase 处理数据库和认证。这允许我们快速构建一个可扩展的后端，而无需从零开始管理基础设施。

架构概述

后端采用 monorepo 结构，使用 Bun 作为包管理器和运行时，以提升开发速度。核心框架是 Next.js，支持 API 路由和服务器端渲染。数据库选择 Supabase，它提供 PostgreSQL、实时订阅和存储服务，完美适合处理财务数据。

安装依赖：

Bun: bun init
Next.js: bun add next react react-dom
Supabase: bun add @supabase/supabase-js
TypeScript: 已内置

配置 Supabase：在项目根目录创建 .env 文件，添加你的 Supabase URL 和 Anon Key：

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_anon_key

在 lib/supabase.ts 中初始化客户端：

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.SUPABASE_URL!;
const supabaseAnonKey = process.env.SUPABASE_ANON_KEY!;

export const supabase = createClient(supabaseUrl, supabaseAnonKey);

这个设置确保了安全的数据库访问，支持行级安全（RLS）来保护用户财务数据。

时间追踪集成

时间追踪是基础功能。使用 Supabase 的实时功能，允许用户启动/停止计时器，并同步到数据库。

创建表结构：在 Supabase SQL 编辑器运行：

CREATE TABLE time_entries (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id),
  project_id UUID,
  start_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  end_time TIMESTAMP WITH TIME ZONE,
  duration INTEGER,  -- 秒
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

API 路由 /api/time/track：

import { NextRequest, NextResponse } from 'next/server';
import { supabase } from '@/lib/supabase';
import { createServerComponentClient } from '@supabase/auth-helpers-nextjs';

export async function POST(request: NextRequest) {
  const supabaseServer = createServerComponentClient({ cookies: () => new Headers() });
  const { data: { user } } = await supabaseServer.auth.getUser();

  if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });

  const { projectId, action } = await request.json();  // action: 'start' or 'stop'

  if (action === 'start') {
    const { data, error } = await supabase
      .from('time_entries')
      .insert({ user_id: user.id, project_id: projectId, start_time: new Date() })
      .select()
      .single();

    if (error) return NextResponse.json({ error }, { status: 500 });
    return NextResponse.json(data);
  } else if (action === 'stop') {
    // 查询最新未结束的条目，计算持续时间并更新
    const { data: entry } = await supabase
      .from('time_entries')
      .select('*')
      .eq('user_id', user.id)
      .eq('end_time', null)
      .order('start_time', { ascending: false })
      .limit(1)
      .single();

    if (entry) {
      const duration = Math.floor((new Date().getTime() - new Date(entry.start_time).getTime()) / 1000);
      await supabase
        .from('time_entries')
        .update({ end_time: new Date(), duration })
        .eq('id', entry.id);
    }

    return NextResponse.json({ success: true });
  }
}

这个实现使用 Supabase 的实时订阅，在前端通过 WebSocket 监听变化，确保多设备同步。参数建议：设置最大追踪时长阈值 8 小时，避免异常数据；使用 RLS 策略仅允许用户访问自己的记录。

AI 驱动的文件对账

文件对账是 AI 集成的关键，使用 OCR 和 LLM 匹配收据与交易。Midday 的 Magic Inbox 功能参考了此点。

集成 OpenAI：在 .env 添加 OPENAI_API_KEY。

创建服务 lib/ai.ts：

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function reconcileFile(fileBuffer: Buffer, transactions: any[]) {
  // 假设使用 Tesseract.js 或 Supabase Storage 上传文件后提取文本
  const extractedText = await extractTextFromImage(fileBuffer);  // 自定义 OCR 函数

  const prompt = `Match this receipt text to transactions: ${extractedText}. Transactions: ${JSON.stringify(transactions)}. Output matched transaction ID or 'unmatched'.`;

  const completion = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 100,
    temperature: 0.1  // 低温度确保确定性
  });

  return completion.choices[0].message.content;
}

在 API /api/reconcile 中调用：

export async function POST(request: NextRequest) {
  // ... 认证

  const formData = await request.formData();
  const file = formData.get('file') as File;
  const { data: transactions } = await supabase.from('transactions').select('*').eq('user_id', user.id);

  const buffer = Buffer.from(await file.arrayBuffer());
  const matchResult = await reconcileFile(buffer, transactions);

  // 存储匹配结果到 Supabase
  await supabase.from('reconciliations').insert({
    user_id: user.id,
    file_path: 'uploaded_file_path',
    matched_transaction_id: matchResult,
    ai_response: matchResult
  });

  return NextResponse.json({ match: matchResult });
}

落地参数：

OCR 工具：集成 Tesseract.js，阈值置信度 > 80% 才提交 AI。
AI 提示工程：限制 tokens 至 200，避免成本；使用 gpt-4o-mini 模型，费用约 $0.00015/1K tokens。
错误处理：如果匹配置信度 < 70%，标记为手动审核；集成队列如 Trigger.dev 处理后台任务。
监控：使用 OpenPanel 追踪 API 调用率，设置每日限额 100 次/用户。

引用 Midday 项目，它展示了如何用 Supabase Storage 安全上传文件，并通过 AI 提供洞察（GitHub: midday-ai/midday）。

发票生成与财务概述

发票生成基于时间追踪数据。使用 pdf-lib 生成 PDF。

安装：bun add pdf-lib

API /api/invoice/generate：

import { PDFDocument, rgb } from 'pdf-lib';

export async function POST(request: NextRequest) {
  // ... 认证

  const { projectId, period } = await request.json();
  const { data: entries } = await supabase
    .from('time_entries')
    .select('duration')
    .eq('project_id', projectId)
    .gte('start_time', period.start)
    .lte('end_time', period.end);

  const totalHours = entries.reduce((sum, e) => sum + e.duration / 3600, 0);
  const amount = totalHours * hourlyRate;  // 从用户设置获取

  const pdfDoc = await PDFDocument.create();
  const page = pdfDoc.addPage([500, 600]);
  page.drawText(`Invoice for ${totalHours} hours: $${amount}`, { x: 50, y: 500, size: 12, color: rgb(0, 0, 0) });

  const pdfBytes = await pdfDoc.save();

  // 上传到 Supabase Storage
  const { data } = await supabase.storage.from('invoices').upload(`${user.id}/${Date.now()}.pdf`, pdfBytes);

  return NextResponse.json({ url: data.path });
}

对于财务概述，集成 Gemini 或 Mistral 生成报告。

服务 lib/finance.ts：

import { GoogleGenerativeAI } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);

export async function generateOverview(transactions: any[]) {
  const prompt = `Summarize spending patterns from these transactions: ${JSON.stringify(transactions.slice(0, 10))}. Suggest cost-saving tips.`;

  const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });
  const result = await model.generateContent(prompt);
  return result.response.text();
}

参数：限制输入数据至最近 30 天，输出长度 < 500 字；回滚策略：如果 AI 失败，使用简单聚合如总收入/支出。

部署与安全

部署到 Vercel：连接 GitHub，设置环境变量。使用 Fly.io for API if needed。

安全要点：

启用 Supabase RLS：create policy "User owns time_entries" on time_entries for all using (auth.uid() = user_id);
加密敏感数据：使用 Supabase 的 pg_crypto 扩展。
银行集成：参考 Plaid SDK，处理 OAuth 流，存储 token 在 Vault。
限流：Next.js 中间件限制 API 调用 < 60/min。

监控：集成 OpenPanel 追踪事件，设置警报阈值如对账失败率 > 5%。

实施清单

设置 Supabase 项目，创建必要表。
实现时间追踪 API，支持实时更新。
集成 OCR + AI 对账，测试准确率 > 90%。
构建发票生成器，支持导出 CSV/PDF。
添加财务 AI 概述，优化提示以减少幻觉。
测试端到端流程，处理边缘案例如文件上传失败。
部署并监控生产环境。

这个后端系统可扩展，支持更多 AI 功能如预测收入。通过 TypeScript 的类型安全，确保代码可靠。总字数约 1200，聚焦于可操作实现，帮助自由职业者自动化财务管理。