数据 API 化方案

01 现状摸底

当前所有数据硬编码在 site/assets/js/cases-data.js 和 analysis-data.js 两个 JS 文件里。下面是 77 条案例的完整画像。

行业分布 Top 8

地区分布

规模分布

发布年分布

02 数据库结构

基于数据画像,设计 7 张表。主表只存元数据,长文本/数组拆表,字典外键管理。

表结构总览

核心 Schema (SQLite)

-- 主表
CREATE TABLE cases (
  id TEXT PRIMARY KEY,              -- 'tampa'
  num TEXT NOT NULL,                -- '08'
  slug TEXT UNIQUE,                 -- URL 友好
  title TEXT NOT NULL,
  subtitle TEXT,
  industry TEXT NOT NULL,           -- '医疗' 显示用
  cat TEXT NOT NULL,                -- 'med' 短码
  scale TEXT NOT NULL,
  type TEXT,
  region TEXT NOT NULL,             -- '亚洲' | '北美' | '欧洲'
  country CHAR(2),                  -- ISO 3166-1 alpha-2
  year INTEGER,
  month INTEGER,
  intro_name TEXT,
  intro_desc TEXT,                  -- 长文本
  result TEXT,                      -- 长文本
  cover_css TEXT,                   -- linear-gradient(...)
  cover_img TEXT,
  highlight TEXT,
  kpi_value REAL,
  kpi_unit TEXT,
  kpi_label TEXT,
  published_at DATE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  verified_by TEXT
);
CREATE INDEX idx_cases_year ON cases(year);
CREATE INDEX idx_cases_region ON cases(region);
CREATE INDEX idx_cases_cat ON cases(cat);

-- 引用表(返工目标)
CREATE TABLE refs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  case_id TEXT NOT NULL REFERENCES cases(id) ON DELETE CASCADE,
  ord INTEGER DEFAULT 0,
  url TEXT NOT NULL,
  label TEXT,
  title TEXT,                       -- ★ 待返工
  author TEXT,                      -- ★ 待返工
  published_at DATE,                -- ★ 待返工
  publisher TEXT,                   -- ★ 待返工
  type TEXT,                        -- article | press-release | blog | paper | tweet
  language CHAR(2),
  fetched_at TIMESTAMP,
  verified INTEGER DEFAULT 0
);

设计要点

• 主表窄:cases 只存元数据,长文本/数组全部拆出 → 查询快、缓存友好
• refs 是返工目标:title/author/published_at/publisher/type 字段都是空的,等你批量补
• 字典表 + 外键:行业/地区/规模用字典,而不是裸字符串 → 国际化、改名、加分类都安全
• slug 字段:现有 /case-detail.html?id=tampa 不友好,API 可用 /cases/tampa-general-hospital-palantir
• sources 表:信源审计,一手访谈 vs 二手报道 vs 自媒体 → 提升案例质量

03 项目结构

不建议改 Monorepo。静态站和 API 部署频率不同,前端零成本部署到 CDN,API 独立部署。保留 Monorepo 迁移路径:schema/ 目录放共用 TS 类型。

04 技术选型

前端

后端 — 三方案对比

数据库 — 双轨

数据返工 — Python

你的需求里"抓 ref 元数据"Python 生态最强:trafilatura / metascraper / httpx / beautifulsoup4。

推荐双语言:API 服务用 Node.js + TS,数据返工用 Python。

05 API 路由设计

REST 路由

输出规范

{
  "data": [...],
  "meta": { "total": 77, "limit": 20, "offset": 0 },
  "links": { "next": "/api/v1/cases?offset=20" }
}

调用示例

# 列表,筛选 2025 年亚太区的企业 AI 案例
curl 'https://api.fd-go.com/v1/cases?year=2025®ion=%E4%BA%9A%E6%B4%B2&cat=entai'

# 单条详情
curl https://api.fd-go.com/v1/cases/tampa

# 案例的引用
curl https://api.fd-go.com/v1/cases/tampa/refs

06 改造路径(分阶段,不爆雷)

07 部署形态

08 ref 元数据批处理

77 条引用了 60+ 域名,Top 来源:linkedin.com 10 篇 · openai.com 5 篇 · databricks.com 3 篇 · 中文新闻媒体若干。

返工脚本骨架

# tools/enrich-refs.py
import httpx, metascraper, sqlite3
from datetime import datetime

def enrich_url(url: str) -> dict:
    """抓 URL 元数据 → {title, author, published_at, publisher, language}"""
    html = httpx.get(url, follow_redirects=True).text
    meta = metascraper.scrape(url=url, html=html)
    return {
        'title':        meta.get('title'),
        'author':       meta.get('author'),
        'published_at': meta.get('published_date'),
        'publisher':    meta.get('publisher') or meta.get('site_name'),
        'language':     'zh' if is_chinese(meta.get('title','')) else 'en',
    }

db = sqlite3.connect('data/fde.sqlite')
for ref_id, url in db.execute(
    "SELECT id, url FROM refs WHERE title IS NULL"):
    try:
        meta = enrich_url(url)
        db.execute("""UPDATE refs SET
            title=?, author=?, published_at=?, publisher=?,
            language=?, fetched_at=? WHERE id=?""",
            [*meta.values(), datetime.now(), ref_id])
        print(f'OK #{ref_id}: {meta["title"][:50]}')
    except Exception as e:
        print(f'FAIL #{ref_id}: {e}')
db.commit()

预期

• 耗时:77 条 × 3 秒 ≈ 4 分钟
• 成功率:LinkedIn 大概率失败留人工补,公司官网/博客 80%+,中文新闻 90%+
• 失败留 verified=0,人工补一次

09 LLM 接入策略

未来 LLM(Claude / GPT / 自定义 Agent)会大量查询我们的数据。两种形式互补,不冲突:md/json 适合快照/RAG,API 适合实时/查询。

主通道 vs 辅助通道

MCP (Model Context Protocol) — 2026 新趋势

Anthropic 推的 MCP 是 LLM-first API 标准,把 API 直接变成 LLM 可调用的工具。一次集成,所有 MCP-兼容 LLM(Claude / Cursor / 自定义)都能用。

API 的 LLM 友好性要求

API 路由 — 增 LLM 端点

GET    /api/v1/cases                     # 人类用,完整字段
GET    /api/v1/llm/cases                 # LLM 用,精简字段
                                        #   ?include=summary,keywords
                                        #   ?max_tokens=2000 自动截断
GET    /api/v1/llm/cases/:id/summary     # LLM 看单条摘要
GET    /api/v1/llm/search?q=xxx          # LLM 语义检索入口
GET    /api/v1/openapi.json              # 自动生成,LLM 看 schema

Schema 加 LLM-friendly 字段(为未来预留)

ALTER TABLE cases ADD COLUMN summary TEXT;
  -- 一句话摘要(LLM 检索第一眼看这个)
ALTER TABLE cases ADD COLUMN keywords TEXT[];
  -- 关键词数组(LLM/RAG 检索用)
ALTER TABLE cases ADD COLUMN embedding vector(1536);
  -- pgvector,后续做语义检索

10 1 万条规模扩展

从 77 条到 1 万条(130 倍),很多"轻量"假设会失效。

必须改的项

数据库:SQLite → Postgres / Supabase

前端:Vanilla JS → Next.js SSR / ISR

1 万条架构图

真实成本预估 (1 万条)

11 风险与决策点

12 下一步

完整 Markdown 文档:docs/architecture/api-architecture-proposal.md