05 · 技术资料：前端、上传与解析流水线

npx create-next-app@latest baton --typescript --tailwind --app --no-src-dir --import-alias "@/*"

npx shadcn@latest init          # Tailwind config 路径问项时【留空】（v4 用 CSS @theme，不再有 tailwind.config.js）
npx shadcn@latest add button card table sheet dialog badge switch progress tabs command sonner \
                       input label select separator skeleton avatar tooltip scroll-area checkbox

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // 这三个包体积大 / 有动态 require，必须让 Next 走运行时 require 而不是打包
  serverExternalPackages: ['unpdf', 'mammoth', 'exceljs'],
}

export default nextConfig

npm i @vercel/blob

// 客户端直传的看门人：不接收文件本体，只签令牌 + 接收完成回调
import { handleUpload, type HandleUploadBody } from '@vercel/blob/client'
import { NextResponse } from 'next/server'

export const runtime = 'nodejs'

export async function POST(request: Request): Promise<NextResponse> {
  const body = (await request.json()) as HandleUploadBody
  try {
    const json = await handleUpload({
      body,
      request,
      onBeforeGenerateToken: async () => {
        // 🔴 必须鉴权。不做这一步 = 把 Blob 库对全网开放。
        // Baton 走的是密码门 Cookie，这里校验会话 Cookie 是否有效。
        // （proxy.ts 已经拦了未登录请求，但这里要再确认一次，不能只靠中间件。）
        return {
          allowedContentTypes: [
            'application/pdf',
            'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
            'text/plain', 'text/markdown',
          ],
          addRandomSuffix: true,
          maximumSizeInBytes: 20 * 1024 * 1024,   // 20MB，对应 AC-2.1.3
        }
      },
      onUploadCompleted: async ({ blob }) => {
        // ⚠️ 本地开发收不到这个回调（Vercel Blob 回调不到 localhost）。
        // 所以【建档不要只依赖这个回调】—— 前端拿到 blob.url 后再显式调一次建档接口。
        void blob
      },
    })
    return NextResponse.json(json)
  } catch (e) {
    return NextResponse.json({ error: e instanceof Error ? e.message : String(e) }, { status: 400 })
  }
}

import { upload } from '@vercel/blob/client'

const blob = await upload(`baton/${employeeId}/${Date.now()}-${file.name}`, file, {
  access: 'public',                     // 私有资料理论上要 private；若 private 读取要签名 URL，今晚可先 public + 路径含随机后缀
  handleUploadUrl: '/api/blob/upload',
  multipart: file.size > 10 * 1024 * 1024,
  onUploadProgress: ({ percentage }) => setProgress(percentage),
})
// 拿到 blob.url 后显式调建档接口（不要只靠 onUploadCompleted，本地收不到）
await fetch('/api/files', { method: 'POST', body: JSON.stringify({ url: blob.url, ... }) })

cp .env.local .env.local.bak     # ⛔ 不做这步不许跑那条命令

npm i unpdf mammoth exceljs

// lib/parse/pdf.ts —— 逐页提取，同时检测"疑似扫描件"
import { extractText, getDocumentProxy } from 'unpdf'

export async function parsePdf(buffer: ArrayBuffer) {
  const pdf = await getDocumentProxy(new Uint8Array(buffer))
  const { totalPages, text } = await extractText(pdf, { mergePages: false })
  const pages = text.map((t, i) => ({ pageNumber: i + 1, text: t }))

  // 扫描件（图片型 PDF）没有文字层，提取出来几乎是空的。
  // 判据：超过 60% 的页面非空白字符数 < 20 → 判定扫描件，不做 OCR，直接报错态。
  const empty = pages.filter(p => p.text.replace(/\s/g, '').length < 20).length
  const likelyScanned = totalPages > 0 && empty / totalPages > 0.6

  return { totalPages, pages, likelyScanned }
}

pending  → parsing   （下载 + 解析 + 切片 + 落 chunk，embedding_status 全 pending）
parsing  → chunking  （落库完成）
chunking → embedding
embedding→ embedding （每次取 N=40 条 pending chunk 做 embedding，取不到就转 done）
         → done
任何一步异常 → failed（保留 parse_error）

// app/api/files/[id]/step/route.ts 的骨架
export const runtime = 'nodejs'
export const preferredRegion = 'hnd1'   // 东京，就近连 Leo-hub
export const maxDuration = 300

export async function POST(_req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params          // Next 16：必须 await
  // ...按当前 parse_status 分支处理一小步，返回 { status, progress }
}

// lib/embed.ts —— 批量 + 指数退避 + 全抖动
const BASE = process.env.YUNWU_API_BASE!      // https://yunwu.ai/v1
const KEY  = process.env.YUNWU_API_KEY!
const MODEL = process.env.EMBEDDING_MODEL || 'text-embedding-3-small'

export async function embedBatch(texts: string[]): Promise<number[][]> {
  if (!texts.length) return []
  let lastErr: unknown
  for (let attempt = 0; attempt <= 5; attempt++) {
    try {
      const res = await fetch(`${BASE}/embeddings`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ model: MODEL, input: texts }),
      })
      if (res.status === 429 || res.status >= 500) throw new Error(`embedding ${res.status}`)
      if (!res.ok) {
        const t = await res.text()
        throw Object.assign(new Error(`embedding ${res.status}: ${t}`), { retryable: false })
      }
      const data = await res.json()
      return (data.data as { embedding: number[] }[]).map(d => d.embedding)
    } catch (e) {
      lastErr = e
      if ((e as { retryable?: boolean }).retryable === false || attempt === 5) break
      // 全抖动退避：random(0, min(500 * 2^n, 15000))
      await new Promise(r => setTimeout(r, Math.random() * Math.min(500 * 2 ** attempt, 15000)))
    }
  }
  throw lastErr
}