概述

Lician 是一个由 AI 驱动的股票研究与分析平台，托管于 lician.com。该平台提供全面的股票分析功能，包括增长分析、估值分析、SEO 优化内容生成等核心模块。平台基于 Next.js 14+ 构建，采用 App Router 架构，支持服务端渲染以优化搜索引擎排名。

技术架构

技术栈

项目结构

quant-platform/
├── src/
│   ├── app/                      # Next.js App Router 页面
│   │   ├── analysis/             # 股票分析页面
│   │   │   └── [ticker]/
│   │   │       └── growth/       # 增长分析页面
│   │   ├── learn/                # 学习内容页面
│   │   └── sectors/              # 行业板块页面
│   ├── components/               # React 组件
│   │   └── seo/                  # SEO 相关组件
│   │       └── StructuredData/   # 结构化数据组件
│   └── lib/                      # 工具库
│       ├── seo.ts                # SEO 元数据生成
│       ├── sectors.ts            # 行业板块配置
│       ├── scoring/              # 评分系统
│       └── ai/agent/             # AI 研究代理
├── mcp-server/                   # MCP 服务器
│   └── README.md                 # 股票数据工具
└── deploy/                       # 部署配置 (Pulumi)

核心功能模块

1. 增长分析模块

增长分析模块位于 /analysis/[ticker]/growth，提供企业收入和盈利增长分析。

主要功能：

• 收入增长率计算（含 5 年 CAGR）
• 净利润及利润率分析
• EPS 增长趋势
• 分析师预测数据展示
• 同行对比基准

实现文件：

• src/app/analysis/[ticker]/growth/page.tsx - 服务端组件，处理数据获取和 SEO
• src/app/analysis/[ticker]/growth/GrowthAnalysisContent.tsx - 客户端组件，交互式 UI

数据结构展示：

graph TD
    A[页面加载] --> B[服务端数据获取]
    B --> C[Income Statement API]
    B --> D[Financial Metrics API]
    B --> E[Fundamentals API]
    B --> F[Segmented Revenue API]
    C --> G[数据聚合]
    D --> G
    E --> G
    F --> G
    G --> H[SEO 元数据生成]
    G --> I[结构化数据生成]
    H --> J[页面渲染]
    I --> J

2. 评分系统

Lician Score 是平台的核心评分系统，从多个维度对股票进行综合评级。

评分维度：

导出模块：

export {
  calculateLicianScore,      // 主计算函数
  calculateValueScore,       // 价值维度
  calculateGrowthScore,      // 成长维度
  calculateQualityScore,     // 质量维度
  calculateMomentumScore,    // 动量维度
  calculateSafetyScore,      // 安全维度
  getSectorMedians,          // 行业中位数
  type LicianScore,
  type DimensionScore,
  type ScoreFactor,
  type SectorMedians,
} from './lician-score'

资料来源：src/lib/scoring/index.ts:1-30

3. SEO 优化系统

平台内置全面的 SEO 优化系统，包含元数据生成和结构化数据组件。

#### 结构化数据组件

#### SEO 元数据生成器

// 股票页面元数据
generateStockMetadata(ticker, companyName, description)

// 板块页面元数据
generateSectorMetadata(sector)

// 对比页面元数据
generateComparisonMetadata(ticker1, ticker2)

#### JSON-LD Schema 生成

平台支持生成多种 Schema.org 结构化数据：

• Organization Schema - 网站组织信息
• WebSite Schema - 网站全局信息，含搜索框
• Article Schema - 文章/分析内容
• FinancialProduct Schema - 股票产品信息
• BreadcrumbList Schema - 导航路径
• FAQPage Schema - 常见问题

资料来源：src/lib/seo.ts:1-50

4. AI 研究代理

平台集成了自主金融研究代理系统。

核心特性：

• 多阶段研究流程：理解 → 规划 → 执行 → 反思
• 智能工具选择
• 股票代码规范化
• 任务结果格式化

导出模块：

export { Agent } from './orchestrator'
export * from './types'
export { formatTaskResults, normalizeToTicker } from './prompts'

资料来源：src/lib/ai/agent/index.ts:1-15

5. MCP 服务器

Model Context Protocol (MCP) 服务器提供标准化的股票数据访问接口。

可用工具：

资料来源：mcp-server/README.md:1-100

行业板块系统

平台基于 GICS（全球行业分类标准）构建板块体系。

支持的板块

排名指标体系

平台支持多维度股票排名：

export const RANKING_METRICS = [
  // 估值类
  'pe-ratio', 'forward-pe', 'price-to-book', 'price-to-sales', 'ev-ebitda', 'peg-ratio',
  // 盈利能力
  'profit-margin', 'operating-margin', 'gross-margin', 'net-margin', 'roa', 'roe', 'roic',
  // 成长性
  'revenue-growth', 'earnings-growth', 'eps-growth', 'dividend-growth',
  // 分红
  'dividend-yield', 'payout-ratio',
  // 规模
  'market-cap', 'enterprise-value', 'revenue', 'net-income',
  // 动量
  'ytd-return', '52-week-return', '1-month-return', '3-month-return',
  // 风险
  'beta', 'volatility',
  // 做空数据
  'short-interest', 'days-to-cover', 'short-ratio',
  // 分析师
  'analyst-rating', 'price-target-upside', 'analyst-count',
  // 内部人士
  'insider-buying', 'insider-ownership',
  // 机构
  'institutional-ownership', 'institutional-buying',
]

资料来源：src/lib/sectors.ts:1-80

页面路由结构

/analysis                    # 分析主页
/analysis/[ticker]           # 股票分析概览
/analysis/[ticker]/growth     # 增长分析详情
/analysis/[ticker]/valuation # 估值分析（规划中）
/analysis/[ticker]/dividend  # 分红分析（规划中）
/compare/[ticker1]-vs-[ticker2]  # 股票对比
/sectors/[sector]            # 板块页面
/stock/[ticker]              # 股票详情页
/learn/[topic]               # 学习内容

部署与发布

发布流程

平台使用 Pulumi 进行基础设施即代码部署。

# 构建发布工具
make publisher

# 使用 MCP 发布器
./bin/mcp-publisher --help

环境与版本

未来增强方向

根据项目规划，以下功能正在考虑中：

1. 行业对比基准 - 与行业平均水平的比较
2. 同行对比图表 - 可视化竞争对手分析
3. 前瞻增长预测 - 3-5 年增长预测模型
4. 季度趋势分析 - 季度数据深度分析
5. 增长质量评分 - 定性增长评估
6. 历史与预测对比 - 实际 vs 预期分析
7. PDF 导出功能 - 报告导出
8. 收藏/书签功能 - 用户个性化保存

概述

quant-platform 是一个基于 Next.js 的 AI 驱动股票研究与分析平台，代码库采用模块化架构设计。该项目整合了前端展示层（Next.js App Router）、后端服务层（Supabase 数据库、MCP Server）、自动化工作流（n8n）以及 AI 代理系统，提供股票分析、财务数据可视化、SEO 优化等功能。

资料来源：README.md:1-50

顶层目录结构

quant-platform/
├── src/                     # 源代码主目录
│   ├── app/                 # Next.js App Router 页面与 API 路由
│   ├── components/          # React 可复用组件
│   └── lib/                 # 工具库、AI 代理、评分系统
├── supabase/                # 数据库配置与迁移脚本
├── scripts/                 # 构建、部署脚本
├── n8n-workflows/           # n8n 自动化工作流
├── docs/                    # 项目文档
├── deploy/                  # Pulumi 部署配置
├── cmd/                     # 应用程序入口点
└── data/                    # 种子数据

资料来源：README.md:80-100

src/app 目录结构

src/app 目录采用 Next.js 14+ App Router 架构，包含页面组件、API 路由和布局文件。

核心页面模块

API 路由

API 路由位于 src/app/api/ 目录下，提供后端数据接口服务。

资料来源：GROWTH_ANALYSIS_README.md:1-30

src/components 目录结构

src/components 目录包含前端可复用组件，按功能域划分。

组件分类

src/components/
├── seo/                     # SEO 优化组件
│   ├── StructuredData.tsx   # 结构化数据组件
│   ├── RelatedLinks.tsx     # 内部链接组件
│   └── README.md            # 组件使用文档
├── ui/                      # UI 基础组件（shadcn/ui）
└── charts/                  # 数据可视化图表组件

SEO 组件详解

SEO 组件模块负责生成 Schema.org 结构化数据，支持以下类型：

资料来源：src/components/seo/README.md:1-80

src/lib 目录结构

src/lib 是核心业务逻辑库，包含多个功能模块。

src/lib/
├── seo.ts                   # SEO 元数据与 Schema 生成
├── sectors.ts               # 行业分类与排名指标
├── ai/
│   └── agent/
│       ├── orchestrator.ts  # AI 代理编排器
│       ├── prompts.ts        # AI 提示词模板
│       ├── types.ts          # TypeScript 类型定义
│       └── index.ts          # 模块导出
├── scoring/
│   ├── index.ts              # 评分系统入口
│   └── lician-score.ts       # Lician Score 计算逻辑
└── mcp/
    └── server/               # MCP 服务器实现

SEO 工具库 (seo.ts)

提供完整的 SEO 元数据生成和结构化数据 Schema 创建功能。

核心导出函数：

常量定义：

export const SITE_URL = 'https://lician.com'
export const SITE_NAME = 'Lician'
export const SITE_DESCRIPTION = 'AI-Powered Stock Research & Analysis Platform'
export const LOGO_URL = `${SITE_URL}/logo.png`
export const OG_IMAGE_URL = `${SITE_URL}/og-image.png`

资料来源：src/lib/seo.ts:1-150

AI 代理系统 (ai/agent/)

自主金融研究代理系统，灵感来自 virattt/dexter，实现五阶段工作流：

graph TD
    A[用户查询] --> B[理解阶段<br/>Understand]
    B --> C[规划阶段<br/>Plan]
    C --> D[执行阶段<br/>Execute]
    D --> E[反思阶段<br/>Reflect]
    E --> F{是否完成?}
    F -->|否| D
    F -->|是| G[回答阶段<br/>Answer]
    G --> H[最终响应]

核心模块：

支持的工具类型：

• Supabase 工具 (1-16): 获取美国上市股票的财务数据、历史数据、估值指标
• SEC Filing 工具: 获取 10-K、10-Q、8-K 等监管文件
• Firecrawl 工具: 抓取最新新闻和事件
• 欧洲公司工具: 获取欧洲股票数据

资料来源：src/lib/ai/agent/index.ts:1-30src/lib/ai/agent/orchestrator.ts:1-50

评分系统 (scoring/)

Lician Score 是平台的股票评分系统，从多个维度评估股票价值。

评分维度：

类型定义：

type LicianScore = {
  overall: number
  dimensions: {
    value: DimensionScore
    growth: DimensionScore
    quality: DimensionScore
    momentum: DimensionScore
    safety: DimensionScore
  }
}

资料来源：src/lib/scoring/index.ts:1-50

行业与排名 (sectors.ts)

定义行业分类和用于排名页面的指标体系。

排名指标分类：

资料来源：src/lib/sectors.ts:1-80

Supabase 配置

Supabase 目录包含数据库配置、迁移脚本和类型定义。

supabase/
├── migrations/              # 数据库迁移脚本
├── functions/                # Supabase Edge Functions
└── types/                    # 数据库类型定义

Supabase 提供以下数据服务：

• 公司基本信息: 股票代码、名称、行业、市值
• 财务报表: 收入、利润、资产负债表、现金流量表
• 估值指标: PE、PB、PS、EV/EBITDA 等
• 分析师数据: 评级、价格目标、预测
• 内幕交易: 内部人买卖记录

资料来源：mcp-server/README.md:1-80

自动化工作流

n8n-workflows

n8n 目录包含业务流程自动化工作流定义。

scripts

脚本目录包含部署、构建和开发辅助脚本。

常用命令：

资料来源：README.md:100-130

MCP Server

MCP（Model Context Protocol）服务器模块提供 AI 工具接口。

mcp-server/
├── README.md                 # MCP 服务文档
└── 实现代码

MCP 工具分类：

资料来源：mcp-server/README.md:20-60

技术栈总结

目录结构关系图

graph TD
    subgraph 前端层
        A[src/app] --> B[src/components]
        A --> C[src/lib/seo.ts]
        A --> D[src/lib/scoring]
    end
    
    subgraph 服务层
        E[Supabase] --> F[mcp-server]
        F --> G[AI Agent<br/>src/lib/ai/agent]
    end
    
    subgraph 自动化层
        H[n8n-workflows] --> E
        I[scripts] --> J[部署配置<br/>deploy]
    end
    
    K[用户请求] --> A
    G --> L[AI 响应]

开发与部署

开发环境

npm run dev

页面测试

资料来源：GROWTH_ANALYSIS_README.md:150-180

总结

quant-platform 采用现代化的分层架构，将前端展示、AI 代理、数据服务和业务流程自动化清晰地分离。src/ 目录是核心开发区域，src/lib/ 提供了 SEO 优化、AI 代理、评分系统等关键业务能力，src/components/ 提供了可复用的 UI 组件。外部服务（Supabase、n8n、MCP Server）则承担了数据持久化和复杂业务流程处理的责任。

1. 架构概述

quant-platform 是一个基于 Next.js 构建的金融量化分析平台，集成了 AI 智能研究代理、股票评分系统和 SEO 优化功能。该平台采用现代化的全栈架构设计，充分利用服务端渲染、API 路由和中间件机制，为用户提供实时金融数据分析与可视化服务。

平台的整体架构遵循客户端-服务端分离模式，前端基于 React 组件化开发，后端通过 Next.js API Routes 提供数据接口，同时集成了 Supabase 作为数据存储层。这种架构设计确保了应用的可扩展性、安全性和高性能表现。

1.1 技术栈概览

2. 核心模块架构

2.1 目录结构设计

src/
├── app/                    # Next.js App Router 页面
│   ├── analysis/           # 分析模块页面
│   ├── learn/              # 学习内容页面
│   └── api/                # API 路由
├── components/             # React 组件
│   ├── seo/                # SEO 优化组件
│   └── ui/                 # UI 基础组件
├── lib/                    # 核心库文件
│   ├── ai/                 # AI 代理模块
│   │   ├── agent/          # 自主研究代理
│   │   └── tools/          # AI 工具集
│   ├── scoring/            # 评分系统
│   └── seo.ts              # SEO 工具函数
└── middleware.ts           # 中间件

2.2 AI 代理模块架构

AI 代理模块是平台的核心智能组件，采用多阶段自主工作流设计。代理通过五个阶段完成金融研究任务：理解用户意图、制定研究计划、执行工具调用、反思结果完整性、生成最终答案。

graph TD
    A[用户查询] --> B[理解阶段 Understand]
    B --> C[规划阶段 Plan]
    C --> D[执行阶段 Execute]
    D --> E{反思阶段 Reflect}
    E -->|信息完整| F[答案生成 Answer]
    E -->|信息不足| D
    F --> G[完成 Complete]

代理核心文件结构：

代理模块的设计遵循单一职责原则，每个阶段由独立的处理函数和专门的提示词模板驱动，确保了代码的可维护性和可测试性。资料来源：src/lib/ai/agent/index.ts:1-12

2.3 评分系统模块

Lician Score 评分系统提供多维度股票评级能力，涵盖价值、成长、质量、动量和安全五个核心维度。该系统通过整合财务报表、现金流和分析师评级等数据，生成综合评分帮助投资者做出决策。

graph LR
    A[财务报表数据] --> B[评分计算引擎]
    C[市场价格数据] --> B
    D[分析师评级] --> B
    B --> E[价值维度]
    B --> F[成长维度]
    B --> G[质量维度]
    B --> H[动量维度]
    B --> I[安全维度]
    E --> J[Lician Score]
    F --> J
    G --> J
    H --> J
    I --> J

评分维度说明：

资料来源：src/lib/scoring/index.ts:1-43

3. API 与数据流架构

3.1 API 层设计

平台通过 Next.js API Routes 提供统一的 API 接口层，所有外部数据请求和内部服务调用都经过这一层处理。API 层采用模块化设计，每个功能域对应独立的 API 模块。

graph TD
    A[客户端请求] --> B[中间件 Middleware]
    B --> C[API 路由处理]
    C --> D{认证检查}
    D -->|通过| E[数据源路由]
    D -->|拒绝| F[返回 401/403]
    E --> G[Supabase 数据库]
    E --> H[外部金融 API]
    E --> I[缓存层]
    G --> J[响应格式化]
    H --> J
    I --> J
    J --> K[返回客户端]

3.2 中间件架构

中间件是请求处理流水线中的关键组件，负责身份验证、速率限制、CORS 处理等跨领域功能。平台使用 Next.js 中间件机制实现全局请求拦截和处理。

中间件核心功能：

中间件在请求到达 API 路由之前执行，确保所有请求都经过统一的安全检查。这种设计避免了重复的身份验证代码，提高了系统的安全性和可维护性。资料来源：src/middleware.ts

3.3 Supabase 集成架构

Supabase 作为平台的数据持久层，提供数据库、实时订阅和认证服务。客户端通过专门的封装模块与 Supabase 进行交互，隐藏了底层实现细节。

graph TD
    A[应用层] --> B[Supabase 客户端封装]
    B --> C[认证模块]
    B --> D[数据库模块]
    B --> E[实时订阅模块]
    C --> F[Supabase Auth]
    D --> G[PostgreSQL]
    E --> H[WebSocket]
    G --> I[数据变更事件]
    H --> I
    I --> J[客户端响应]

客户端封装模块提供类型安全的数据库操作接口，支持实时数据同步和离线操作。资料来源：src/lib/supabase-client.ts

4. SEO 优化架构

4.1 结构化数据组件

平台实现了完整的 Schema.org 结构化数据支持，包括 FAQ、Breadcrumb、Article 和 HowTo 等多种类型。这些数据通过 JSON-LD 格式嵌入页面，帮助搜索引擎更好地理解页面内容。

graph TD
    A[页面组件] --> B[结构化数据组件]
    B --> C[FAQSchema]
    B --> D[BreadcrumbSchema]
    B --> E[ArticleSchema]
    B --> F[HowToSchema]
    C --> G[JSON-LD 脚本]
    D --> G
    E --> G
    F --> G
    G --> H[HTML Head]
    H --> I[搜索引擎爬取]

SEO 组件清单：

资料来源：src/components/seo/README.md:1-89

4.2 元数据生成系统

平台实现了动态元数据生成系统，根据页面内容自动生成标题、描述、关键词等 SEO 相关标签。该系统支持 OpenGraph、Twitter Card 和 Canonical URL 等高级特性。

元数据配置选项：

资料来源：src/lib/seo.ts:1-120

5. 分析页面架构

5.1 增长分析模块

增长分析模块是平台的核心功能之一，提供股票营收和盈利增长趋势的深入分析。模块采用服务端组件和客户端组件分离的架构，优化了 SEO 效果和交互体验。

graph LR
    A[页面路由 /analysis/[ticker]/growth] --> B[服务端组件 page.tsx]
    B --> C[数据获取]
    C --> D[API: 损益表]
    C --> E[API: 财务指标]
    C --> F[API: 公司基本面]
    C --> G[API: 分段营收]
    D --> H[GrowthAnalysisContent 客户端组件]
    E --> H
    F --> H
    G --> H
    H --> I[Recharts 图表渲染]
    H --> J[指标仪表板]
    H --> K[结构化数据]

服务端数据获取：

资料来源：GROWTH_ANALYSIS_README.md:1-150

5.2 MCP 服务器架构

MCP (Model Context Protocol) 服务器为 Claude 等 AI 助手提供股票数据访问能力，扩展了平台的 AI 集成能力。服务器实现了多种工具函数，覆盖股票行情、公司信息、财务数据和新闻等方面。

MCP 工具分类：

资料来源：mcp-server/README.md:1-100

6. Next.js 配置架构

6.1 构建配置

Next.js 配置文件定义了应用的构建和运行时行为，包括图片优化、国际化、实验性功能等高级配置选项。

关键配置项：

6.2 环境变量架构

平台使用环境变量管理敏感配置和生产环境差异。关键环境变量包括数据库连接、API 密钥和第三方服务凭证。

graph TD
    A[环境变量] --> B[数据库配置]
    A --> C[API 密钥]
    A --> D[认证配置]
    A --> E[应用配置]
    B --> F[Supabase URL]
    B --> G[Supabase Anon Key]
    C --> H[金融数据 API]
    C --> I[AI 服务密钥]
    D --> J[JWT Secret]
    D --> K[会话配置]
    E --> L[SITE_URL]
    E --> M[OG_IMAGE_URL]

资料来源：next.config.ts

7. 部署与运行时架构

7.1 容器化部署

平台支持 Docker 容器化部署，通过 docker-compose.yml 管理多服务依赖。开发环境使用 make dev-compose 命令快速启动完整开发栈。

部署架构：

graph TD
    A[Docker Compose] --> B[Next.js 应用容器]
    A --> C[PostgreSQL 容器]
    A --> D[缓存服务容器]
    B --> C
    B --> D
    C --> E[持久化存储]
    D --> F[内存存储]

7.2 开发环境

本地开发环境通过容器化确保一致性：

资料来源：README.md:1-80

8. 安全性设计

8.1 认证与授权

平台采用多层认证机制：

• JWT Token: 用于 API 请求认证
• Supabase Auth: 第三方认证支持
• 中间件验证: 请求级别的身份检查
• API 路由保护: 敏感接口的访问控制

8.2 数据安全

9. 总结

quant-platform 采用现代化的分层架构设计，将展示层、业务逻辑层和数据层清晰分离。核心设计特点包括：基于 Next.js App Router 的服务端渲染架构、支持多阶段工作流的 AI 研究代理、完整的 SEO 优化体系，以及通过 MCP 协议实现的 AI 助手扩展能力。

平台的架构设计充分考虑了可扩展性、可维护性和安全性，为后续功能迭代和性能优化提供了良好的技术基础。

概述

股票分析核心功能是量化平台的核心模块，提供了全面的股票数据展示与分析能力。该模块整合了财务报表分析、技术分析、内幕交易追踪、机构持仓分析等多个维度的数据，帮助投资者做出更明智的投资决策。

平台采用 Next.js 14+ App Router 架构，所有分析组件均为服务端渲染（Server Components）或客户端组件（Client Components），确保了 SEO 友好性和良好的用户体验。

系统架构

graph TD
    A[股票详情页 /stock/[ticker]] --> B[核心分析组件]
    B --> C[FinancialStatements 财务报表]
    B --> D[TechnicalAnalysis 技术分析]
    B --> E[InsiderTrading 内幕交易]
    B --> F[InstitutionalOwnership 机构持仓]
    B --> G[Lician Score 评分系统]
    
    H[SEO 元数据生成] --> A
    I[AI Agent 智能分析] --> G
    J[数据来源 API] --> C
    J --> D
    J --> E
    J --> F

核心组件详解

1. 财务报表组件 (FinancialStatements)

财务报表组件负责展示公司的财务健康状况，支持多种财务报表类型的切换与历史数据可视化。

文件位置： src/components/FinancialStatements.tsx

#### 主要功能

#### 数据结构

interface FinancialStatements {
  income_statement: IncomeStatement[]
  balance_sheet: BalanceSheet[]
  cash_flow_statement: CashFlowStatement[]
  financial_metrics: FinancialMetrics[]
}

资料来源：src/lib/scoring/index.ts:15-22

2. 技术分析组件 (TechnicalAnalysis)

技术分析组件提供股票的技术面分析，包括多种技术指标的计算与图表展示。

文件位置： src/components/TechnicalAnalysis.tsx

#### 支持的技术指标

#### 图表功能

• 实时价格图表：展示股票历史价格走势
• 技术指标叠加：支持多指标叠加显示
• 交互式工具提示：悬停显示详细数据
• 时间范围选择：支持日、周、月视图切换

3. 内幕交易追踪 (InsiderTrading)

内幕交易组件追踪公司内部人员的买卖活动，作为投资决策的重要参考信号。

文件位置： src/components/InsiderTrading.tsx

#### 追踪的交易类型

#### 显示信息

• 内部人员姓名与职位
• 交易日期与类型
• 交易数量与金额
• 交易方式（公开市场、私募等）

资料来源：src/components/InsiderTrading.tsx

4. 机构持仓分析 (InstitutionalOwnership)

机构持仓组件展示主要机构投资者对某股票的持仓情况与变动趋势。

文件位置： src/components/InstitutionalOwnership.tsx

#### 关键指标

#### 数据来源

机构持仓数据来源于 SEC 13F 文件披露，季度更新。

5. 机构所有权指标 (InstitutionalOwnership)

graph LR
    A[机构投资者] --> B[13F Filing 数据]
    B --> C[数据聚合]
    C --> D[持股比例计算]
    C --> E[机构排名]
    D --> F[持股变化趋势]
    E --> G[主要机构列表]

Lician Score 评分系统

评分系统是平台的核心分析引擎，从多个维度对股票进行综合评分。

文件位置： src/lib/scoring/index.ts

评分维度

数据类型定义

export interface FinancialMetrics {
  income_statement: IncomeStatement
  balance_sheet: BalanceSheet
  cash_flow_statement: CashFlowStatement
  price_data: PriceData
  analyst_rating: AnalystRating
}

资料来源：src/lib/scoring/index.ts:1-10

SEO 与元数据优化

平台为每个股票分析页面自动生成优化的 SEO 元数据，提升搜索引擎可见性。

文件位置： src/lib/seo.ts

元数据生成流程

graph TD
    A[请求股票页面 /stock/AAPL] --> B[generateMetadata]
    B --> C[generateSEOMetadata]
    C --> D[OpenGraph 配置]
    C --> E[结构化数据]
    D --> F[社交分享卡片]
    E --> G[Google 富媒体摘要]

股票页面元数据生成

export function generateStockMetadata(
  ticker: string,
  companyName: string
): Metadata {
  return generateSEOMetadata({
    title: `${companyName} (${ticker}) - Stock Price, Analysis & News`,
    description: fullDescription,
    path: `/stock/${ticker.toLowerCase()}`,
    keywords,
    image: `${SITE_URL}/api/og/stock/${ticker.toLowerCase()}`,
    type: 'article',
    modifiedTime: new Date().toISOString(),
  })
}

资料来源：src/lib/seo.ts:80-100

结构化数据支持

平台支持以下 Schema.org 结构化数据类型：

资料来源：src/components/seo/README.md

行业分类体系

平台采用 GICS（全球行业分类标准）进行股票分类。

文件位置： src/lib/sectors.ts

支持的行业板块

排名指标体系

export const RANKING_METRICS = [
  // 估值指标
  'pe-ratio', 'forward-pe', 'price-to-book', 'price-to-sales', 'ev-ebitda', 'peg-ratio',
  // 盈利能力
  'profit-margin', 'operating-margin', 'gross-margin', 'net-margin', 'roa', 'roe', 'roic',
  // 成长性
  'revenue-growth', 'earnings-growth', 'eps-growth', 'dividend-growth',
  // 分红
  'dividend-yield', 'payout-ratio',
  // 规模
  'market-cap', 'enterprise-value', 'revenue', 'net-income',
  // 动量
  'ytd-return', '52-week-return', '1-month-return', '3-month-return',
  // 风险
  'beta', 'volatility',
  // 卖空数据
  'short-interest', 'days-to-cover', 'short-ratio',
  // 分析师数据
  'analyst-rating', 'price-target-upside', 'analyst-count',
]

资料来源：src/lib/sectors.ts:1-40

增长分析模块

增长分析是股票分析的核心子模块，提供详细的营收与盈利增长分析。

文件位置： src/app/analysis/[ticker]/growth/

增长分析页面结构

graph TD
    A[增长分析页] --> B[Header 标题区]
    A --> C[Key Metrics 关键指标]
    A --> D[Revenue Growth Chart 营收图表]
    A --> E[Earnings Analysis 盈利分析]
    A --> F[Margin Analysis 利润率分析]
    A --> G[Forward Estimates 分析师预期]
    A --> H[Conclusion 结论]

关键指标展示

增长分析关键词优化

页面针对以下搜索关键词进行 SEO 优化：

• {ticker} revenue growth
• {ticker} earnings growth
• is {company} growing
• {ticker} growth rate
• {ticker} analyst forecast

资料来源：GROWTH_ANALYSIS_README.md

数据获取工具

平台通过 MCP Server 提供标准化的数据获取接口。

文件位置： mcp-server/README.md

核心数据工具

资料来源：mcp-server/README.md

AI 智能分析代理

平台集成了自主研发的金融研究 AI 代理，支持自然语言查询股票相关信息。

文件位置： src/lib/ai/agent/

代理工作流程

graph TD
    A[用户查询] --> B[理解阶段 Understand]
    B --> C[规划阶段 Plan]
    C --> D[执行阶段 Execute]
    D --> E[反思阶段 Reflect]
    E --> F{任务完成?}
    F -->|否| D
    F -->|是| G[回答阶段 Answer]
    G --> H[最终响应]

代理类型定义

export type Phase = 'understand' | 'plan' | 'execute' | 'reflect' | 'answer' | 'complete'

export interface Understanding {
  intent: string
  entities: Entity[]
  timeframe?: string
  complexity: 'simple' | 'moderate' | 'complex'
}

实体类型支持

资料来源：src/lib/ai/agent/types.ts:1-20

股票详情页集成

股票分析核心功能统一集成在股票详情页中。

文件位置： src/app/stock/[ticker]/page.tsx

页面组件布局

┌─────────────────────────────────────────┐
│           Header (导航栏)                │
├─────────────────────────────────────────┤
│         Stock Hero (股票信息卡片)         │
│    价格 | 涨跌幅 | 市值 | 52周范围         │
├─────────────────────────────────────────┤
│       Key Metrics (关键指标)             │
│   P/E | P/B | 毛利率 | ROE | 股息率       │
├─────────────────────────────────────────┤
│       Lician Score (综合评分)            │
│    价值 | 成长 | 质量 | 动量 | 安全        │
├─────────────────────────────────────────┤
│    FinancialStatements (财务报表选项卡)    │
│  [收入表] [资产负债表] [现金流量表]         │
├─────────────────────────────────────────┤
│       TechnicalAnalysis (技术分析)       │
│          价格图表 + 技术指标              │
├─────────────────────────────────────────┤
│       InsiderTrading (内幕交易)          │
│         最近交易记录列表                  │
├─────────────────────────────────────────┤
│   InstitutionalOwnership (机构持仓)       │
│        机构列表 + 持仓变化                │
├─────────────────────────────────────────┤
│              Footer (页脚)               │
└─────────────────────────────────────────┘

技术栈总结

总结

股票分析核心功能构成了量化平台的数据展示与分析基础，通过模块化的组件设计实现了：

1. 多维度分析：财务报表、技术指标、内幕交易、机构持仓全覆盖
2. SEO 友好：自动生成元数据与结构化数据，提升搜索可见性
3. AI 增强：自然语言查询与智能研究代理
4. 评分体系：Lician Score 多维度股票评分
5. 用户体验：响应式设计与交互式图表

概述

Lician平台的AI功能模块为用户提供智能化的股票研究和投资分析能力。该模块采用多阶段自主代理架构，灵感来源于virattt/dexter项目，通过理解用户意图、规划研究任务、自主执行工具调用、反思结果并生成综合回答的完整流程，实现深度的金融研究自动化。

AI代理系统的核心职责包括：

• 自然语言理解：解析用户查询中的股票代码、公司名称、指标和时间范围
• 任务规划：将复杂研究请求分解为可执行的任务序列
• 工具编排：智能选择和调用金融数据API、内部搜索和外部数据源
• 反思评估：评估研究结果完整性，必要时补充信息
• 综合回答：生成结构化的投资分析报告和投资建议

资料来源：src/lib/ai/agent/orchestrator.ts:1-20

系统架构

整体架构图

graph TD
    User[用户查询] --> ChatAPI[API路由<br/>api/chat/route.ts]
    ChatAPI --> Orchestrator[Agent Orchestrator<br/>五阶段工作流]
    
    Orchestrator --> Understand[1. Understand<br/>理解阶段]
    Understand --> Plan[2. Plan<br/>规划阶段]
    Plan --> Execute[3. Execute<br/>执行阶段]
    Execute --> Reflect[4. Reflect<br/>反思阶段]
    Reflect -->|不完整| Execute
    Reflect -->|完整| Answer[5. Answer<br/>回答阶段]
    Answer --> Response[结构化投资报告]
    
    Execute --> Tools[AI Tools]
    Tools --> CoreTools[核心工具<br/>getCompanyFundamentals<br/>getFinancialStatements<br/>getStockQuote]
    Tools --> RAG[RAG工具<br/>searchFinancialDocuments]
    Tools --> External[外部API<br/>SEC Filings<br/>News Search]
    
    ScoringSystem[Lician评分系统] --> Answer

目录结构

src/lib/ai/
├── agent/
│   ├── orchestrator.ts    # 代理编排器主逻辑
│   ├── types.ts           # 类型定义
│   ├── prompts.ts         # 各阶段提示词模板
│   └── index.ts           # 导出入口
├── tools/
│   ├── index.ts           # 工具统一导出
│   ├── core.ts            # 核心金融工具
│   ├── firecrawl.ts       # 网页抓取工具
│   ├── external-api.ts    # 外部API工具
│   ├── eu.ts              # 欧洲公司工具
│   ├── rag.ts             # RAG语义搜索工具
│   └── utils.ts           # 工具函数
└── scoring/
    ├── index.ts           # 评分系统导出
    └── lician-score.ts    # Lician评分算法

资料来源：src/lib/ai/agent/index.ts:1-20

代理编排器详解

五阶段工作流

代理编排器实现了完整的五阶段研究工作流，每个阶段都有明确的系统提示词和用户提示词模板。

graph LR
    A[用户查询] --> B[理解阶段<br/>Extract Intent]
    B --> C[规划阶段<br/>Create Tasks]
    C --> D[执行阶段<br/>Run Tools]
    D --> E[反思阶段<br/>Evaluate]
    E -->|不足| D
    E -->|充足| F[回答阶段<br/>Generate]
    F --> G[最终报告]
    
    subgraph 理解阶段
    B1[提取实体] --> B2[识别意图]
    B2 --> B3[确定复杂度]
    end
    
    subgraph 规划阶段
    C1[分解任务] --> C2[确定依赖]
    C2 --> C3[排序执行]
    end
    
    subgraph 执行阶段
    D1[选择工具] --> D2[调用API]
    D2 --> D3[收集结果]
    end

#### 阶段详解

资料来源：src/lib/ai/agent/orchestrator.ts:12-20

核心类型定义

代理系统使用TypeScript进行强类型约束，主要类型定义如下：

// 代理状态类型
export type Phase = 'understand' | 'plan' | 'execute' | 'reflect' | 'answer' | 'complete'

// 实体类型
export type EntityType = 'ticker' | 'company' | 'date' | 'metric' | 'period' | 'other'

// 实体接口
export interface Entity {
  type: EntityType
  value: string
  normalized?: string  // 标准化值，如 "Apple" 标准化为 "AAPL"
}

// 理解结果
export interface Understanding {
  intent: string                    // 清晰的用户需求陈述
  entities: Entity[]                // 从查询中提取的实体
  timeframe?: string                // 时间范围
  complexity: 'simple' | 'moderate' | 'complex'  // 复杂度等级
}

// 任务类型
export type TaskType = 'use_tools' | 'reason'
export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed'

// 任务接口
export interface Task {
  id: string
  description: string
  taskType: TaskType
  dependsOn: string[]
  status: TaskStatus
  toolCalls?: ToolCall[]
  result?: string
}

// 反思结果
export interface Reflection {
  isComplete: boolean
  reasoning: string
  missingInfo: string[]
  suggestedNextSteps: string
}

资料来源：src/lib/ai/agent/types.ts:1-60

工具调用结构

// 工具调用接口
export interface ToolCall {
  id: string
  toolName: string
  args: Record<string, unknown>
  status: 'pending' | 'running' | 'completed' | 'failed'
  result?: unknown
  error?: string
}

// 任务结果
export interface TaskResult {
  taskId: string
  output: string
  toolResults?: Record<string, unknown>[]
}

// 代理完整状态
export interface AgentState {
  query: string
  phase: Phase
  understanding?: Understanding
  plan?: Plan
  taskResults: TaskResult[]
  reflection?: Reflection
  response?: string
}

资料来源：src/lib/ai/agent/types.ts:60-90

提示词工程

提示词模板架构

系统为每个阶段定义了系统提示词和用户提示词，通过模板函数动态生成。

graph TD
    P[Prompts Module] --> PS[系统提示词]
    P --> PU[用户提示词]
    
    PS --> PSU[UNDERSTAND_SYSTEM_PROMPT<br/>理解系统提示]
    PS --> PSP[PLAN_SYSTEM_PROMPT<br/>规划系统提示]
    PS --> PSS[TOOL_SELECTION_SYSTEM_PROMPT<br/>工具选择提示]
    PS --> PSE[EXECUTE_SYSTEM_PROMPT<br/>执行系统提示]
    PS --> PSR[REFLECT_SYSTEM_PROMPT<br/>反思系统提示]
    PS --> PSA[ANSWER_SYSTEM_PROMPT<br/>回答系统提示]
    
    PU --> PUU[UNDERSTAND_USER_PROMPT<br/>理解用户提示]
    PU --> PUP[PLAN_USER_PROMPT<br/>规划用户提示]
    PU --> PUE[EXECUTE_USER_PROMPT<br/>执行用户提示]
    PU --> PUR[REFLECT_USER_PROMPT<br/>反思用户提示]
    PU --> PUA[ANSWER_USER_PROMPT<br/>回答用户提示]

关键提示词策略

#### 工具选择策略

export const TOOL_SELECTION_SYSTEM_PROMPT = `...
**✅ USE RAG FOR:**
- "What are the main risks for Apple?"
- "Explain the competitive advantages of Microsoft"
- "What did the CEO say about AI strategy?"
- "Summarize recent regulatory challenges"

**❌ NEVER use RAG for:**
- "What is AAPL's PE ratio?" → Use getCompanyFundamentals (FAST)
- "Get NVDA's revenue" → Use getFinancialStatements (FAST)
- "Show insider trades" → Use getInsiderTrades (FAST)
- Any query that asks for NUMBERS → Use direct tools (FAST)
...`

该策略明确定义了何时使用RAG语义搜索，何时应使用直接API调用，确保代理能够选择最合适的工具。

资料来源：src/lib/ai/agent/prompts.ts:1-50

AI工具系统

工具分类

┌─────────────────────────────────────────────────────────────┐
│                      AI Tools                               │
├─────────────────────────────────────────────────────────────┤
│ Core Tools      │ 爬虫工具   │ RAG搜索   │ 外部API          │
│ ─────────────── │ ─────────  │ ────────  │ ──────────────  │
│ • getStockQuote  │ Firecrawl  │ RAG Search│ SEC Filings     │
│ • getCompanyInfo │ Web Scrap  │ Doc Index │ News Search     │
│ • getFinancials  │           │           │ Price History   │
│ • getInsiderTrades│           │           │ Segment Data    │
│ • getInstitutional│           │           │                 │
└─────────────────────────────────────────────────────────────┘

工具导出结构

/**
 * AI Financial Tools - 从模块化结构重新导出
 * 
 * 实际工具组织在 ./tools/ 目录:
 * - core.ts: 股票行情、基本面、财报、内部人、机构、分析师、空头兴趣
 * - firecrawl.ts: 网页抓取和研究工具
 * - external-api.ts: 金融数据集API工具 (SEC、行情、新闻、分部数据)
 * - eu.ts: 欧洲公司工具
 * - rag.ts: RAG/语义搜索工具
 * - utils.ts: 共享工具 (重试、超时、Supabase客户端)
 */

// 重新导出所有工具
export * from './tools/index'

资料来源：src/lib/ai/tools.ts:1-30

Lician评分系统

评分维度

Lician评分系统从五个维度综合评估股票：

graph TD
    Input[财务数据输入] --> VS[价值评分]
    Input --> GS[成长评分]
    Input --> QS[质量评分]
    Input --> MS[动能评分]
    Input --> SS[安全评分]
    
    VS --> LS[Lician综合评分]
    GS --> LS
    QS --> LS
    MS --> LS
    SS --> LS
    
    LS --> Result[股票评级输出]

导出结构

export {
  // 主要计算函数
  calculateLicianScore,
  
  // 各维度计算器
  calculateValueScore,
  calculateGrowthScore,
  calculateQualityScore,
  calculateMomentumScore,
  calculateSafetyScore,
  
  // 工具函数
  getSectorMedians,
  
  // 类型导出
  type LicianScore,
  type DimensionScore,
  type ScoreFactor,
  type SectorMedians,
  type IncomeStatement,
  type BalanceSheet,
  type CashFlowStatement,
  type FinancialMetrics,
  type PriceData,
  type AnalystRating
}

资料来源：src/lib/scoring/index.ts:1-45

工作流程示例

典型查询处理流程

用户输入: "苹果公司(AAPL)值得投资吗？"
           │
           ▼
┌─────────────────────────────────────┐
│      1. 理解阶段 (Understand)       │
│  - 提取实体: ticker=AAPL            │
│  - 识别意图: 投资价值评估            │
│  - 判断复杂度: moderate             │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│      2. 规划阶段 (Plan)              │
│  Tasks:                             │
│  1. 获取公司基本信息                 │
│  2. 获取财务指标 (估值、盈利)        │
│  3. 获取财务报表 (5年数据)           │
│  4. 获取分析师评级                   │
│  5. 计算Lician评分                   │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│      3. 执行阶段 (Execute)           │
│  Tool Calls:                        │
│  - getCompanyFundamentals(AAPL)     │
│  - getFinancialStatements(AAPL)     │
│  - getAnalystRatings(AAPL)          │
│  - calculateLicianScore(...)        │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│      4. 反思阶段 (Reflect)           │
│  - 检查数据完整性 ✓                  │
│  - 评估结果充足性 ✓                  │
│  - 决定是否需要补充                  │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│      5. 回答阶段 (Answer)            │
│  生成包含以下内容的结构化报告:        │
│  - 公司概况                          │
│  - 估值分析                          │
│  - 成长性评估                        │
│  - Lician综合评分                    │
│  - 投资建议                          │
└─────────────────────────────────────┘

数据模型

Agent状态机

stateDiagram-v2
    [*] --> Understand : 用户查询
    Understand --> Plan : 理解完成
    Plan --> Execute : 规划完成
    Execute --> Reflect : 任务执行完成
    Reflect --> Execute : 需要补充
    Reflect --> Answer : 完整性确认
    Answer --> Complete : 报告生成
    Complete --> [*]
    
    Understand : phase = "understand"
    Plan : phase = "plan"
    Execute : phase = "execute"
    Reflect : phase = "reflect"
    Answer : phase = "answer"
    Complete : phase = "complete"

关键数据流

扩展与集成

添加新工具

在 ./tools/ 目录下的相应模块中添加工具函数，然后在 ./tools/index.ts 中导出。代理系统会自动识别新工具并可用于工具选择阶段。

添加新评分维度

在 lician-score.ts 中添加新的评分计算函数，并在 index.ts 中导出。确保新函数签名与现有函数一致。

自定义提示词

修改 ./prompts.ts 中对应的提示词模板，可以调整代理在各阶段的行为策略。

相关文件索引

概述

UI组件库是量化交易平台的核心视觉层，提供了一套完整的React组件系统，用于构建股票分析、投资组合管理、期权交易等专业金融界面。该组件库基于现代前端技术栈构建，包括Next.js 14+、TypeScript、Tailwind CSS和shadcn/ui组件库，旨在为用户提供专业且流畅的金融数据可视化体验。

组件库的设计理念围绕金融应用的核心需求展开，强调数据的清晰呈现、交互的即时响应以及专业分析功能的完整性。从交互式股票图表到投资组合分析器，每个组件都经过精心设计，以满足投资者和专业交易员的各种需求。组件库采用模块化架构，允许开发者根据具体业务场景灵活组合使用不同组件，同时保持了整体设计风格的一致性和代码的可维护性。

核心组件架构

组件分类概览

UI组件库按功能可分为以下几个核心类别，每个类别承担特定的用户界面职责：

股票搜索组件 (StockSearch)

股票搜索组件是用户与平台交互的主要入口点，提供了快速定位和检索股票信息的能力。该组件支持按股票代码、公司名称或行业进行搜索，并提供自动补全功能帮助用户快速找到目标股票。

搜索组件的设计考虑了金融应用的特殊需求，包括：

• 实时搜索建议：用户输入时即时显示匹配结果
• 历史搜索记录：记住用户最近的搜索偏好
• 多维度过滤：支持按行业、市值、板块等条件筛选
• 快捷操作：支持直接跳转到分析页面或添加自选股

搜索组件与后端API紧密集成，通过/api/stock/search端点获取搜索结果，确保搜索结果的实时性和准确性。组件还支持键盘导航，方便高级用户提高操作效率。

交互式股票图表 (InteractiveStockChart)

交互式股票图表是组件库中最核心的可视化组件，采用了Recharts图表库实现丰富的金融数据展示功能。该组件支持多种图表类型和时间周期选择，能够满足不同分析场景的需求。

图表组件的主要特性包括：

// 核心图表配置
interface ChartConfig {
  chartType: 'line' | 'candlestick' | 'area' | 'bar'
  timeRange: '1D' | '1W' | '1M' | '3M' | '1Y' | '5Y' | 'MAX'
  showVolume: boolean
  showMovingAverage: boolean
  indicators: string[]
}

组件支持的技术指标包括移动平均线(MA)、相对强弱指数(RSI)、MACD、布林带等常用技术分析工具。交互功能包括缩放、平移、数据点悬停提示以及自定义时间范围选择。图表还支持与投资组合分析器的联动，点击图表上的股票代码可以快速查看该股票的相关信息。

投资组合分析器 (PortfolioAnalyzer)

投资组合分析器是组件库中专注于投资组合管理和风险评估的高级组件。该组件提供了全面的投资组合绩效分析、资产配置可视化和风险指标计算功能。

分析器的主要功能模块包括：

• 收益分析：计算投资组合的收益率、夏普比率、阿尔法、贝塔等关键指标
• 风险评估：分析波动率、最大回撤、价值-at-Risk等风险指标
• 资产配置：饼图和树形图展示持仓分布和行业配置
• 对比基准：与标普500等基准指数进行对比分析

组件内部集成了Lician评分系统的计算逻辑，能够为投资组合中的每只股票提供综合评分，帮助用户识别优质投资标的。评分计算基于价值、成长、质量、动量、安全五个维度，使用行业基准数据进行标准化处理。

期权链组件 (OptionsChain)

期权链组件提供了完整的期权交易界面，支持查看和筛选期权合约、计算期权希腊值、评估期权价值等核心功能。该组件是平台期权分析功能的核心展示窗口。

期权链的数据结构定义如下：

组件支持按行权价格、到期日、隐含波动率等多维度过滤和排序，帮助交易员快速定位感兴趣的期权合约。界面采用双栏布局，左侧展示看涨期权，右侧展示看跌期权，中间显示行权价格。

SEO组件系统

结构化数据组件

SEO组件系统为页面提供Schema.org结构化数据支持，帮助搜索引擎更好地理解和索引页面内容。系统包含以下核心组件：

结构化数据组件采用JSON-LD格式输出，自动注入到页面头部。以FAQSchema为例，组件接收问答数据数组，生成符合Google富媒体片段要求的结构化数据：

<FAQSchema
  faqs={[
    {
      question: '如何开始股票投资？',
      answer: '您可以通过以下步骤开始：1. 学习基础知识...'
    }
  ]}
/>

组件生成的JSON-LD脚本会被搜索引擎爬取，支持在搜索结果中显示富媒体片段，从而提高点击率。每个组件都提供了完整的TypeScript类型定义和详细的JSDoc文档，确保使用的便捷性和代码的健壮性。

SEO元数据生成

src/lib/seo.ts模块提供了完整的SEO元数据生成函数，支持为不同类型的页面生成优化的元数据配置：

• 标题生成：动态生成包含关键词和品牌的页面标题
• 描述优化：根据页面内容自动生成描述性元标签
• OpenGraph标签：支持社交媒体分享预览
• Twitter卡片：优化Twitter分享效果
• Canonical URL：避免重复内容问题
• 结构化关键词：提供搜索引擎友好的关键词列表

元数据生成函数支持覆盖和扩展，允许开发者根据具体页面需求进行定制。所有生成的元数据都遵循SEO最佳实践，包括合理的标题长度、描述长度控制等。

评分系统集成

Lician评分体系

Lician评分系统是平台的核心分析引擎，提供五维度的股票综合评分：

评分系统导出了完整的计算函数和数据类型定义：

export {
  calculateLicianScore,
  calculateValueScore,
  calculateGrowthScore,
  calculateQualityScore,
  calculateMomentumScore,
  calculateSafetyScore,
  getSectorMedians,
  type LicianScore,
  type DimensionScore,
  type ScoreFactor,
  type SectorMedians
}

每个维度的评分都包含详细的数据点分析和置信度评估，帮助用户理解评分背后的逻辑。评分计算时会自动获取行业基准数据，确保评分的相对公平性和可比性。

技术栈与依赖

核心技术依赖

组件库充分利用了Next.js 14+的App Router特性，使用服务端组件(Server Components)进行数据获取，客户端组件(Client Components)处理交互逻辑，实现了性能和安全性的双重优化。

文件组织结构

src/components/
├── InteractiveStockChart.tsx  # 交互式股票图表组件
├── StockSearch.tsx            # 股票搜索组件
├── PortfolioAnalyzer.tsx      # 投资组合分析器
├── OptionsChain.tsx           # 期权链组件
├── seo/                       # SEO相关组件
│   ├── StructuredData.tsx    # 结构化数据组件
│   └── README.md             # SEO组件文档
└── ui/                        # shadcn/ui基础组件

组件使用指南

基本用法示例

以下是各核心组件的基本使用方式：

股票搜索组件：

import { StockSearch } from '@/components/StockSearch'

export default function SearchPage() {
  return (
    <StockSearch
      onSelect={(stock) => router.push(`/stock/${stock.ticker}`)}
      placeholder="搜索股票代码或名称..."
      showFilters={true}
    />
  )
}

交互式图表组件：

import { InteractiveStockChart } from '@/components/InteractiveStockChart'

<InteractiveStockChart
  ticker="AAPL"
  data={chartData}
  chartType="candlestick"
  timeRange="1Y"
  showVolume={true}
  indicators={['MA20', 'MA50']}
/>

投资组合分析器：

import { PortfolioAnalyzer } from '@/components/PortfolioAnalyzer'

<PortfolioAnalyzer
  holdings={portfolioHoldings}
  benchmark="SPY"
  showRiskMetrics={true}
/>

响应式设计

所有组件都采用移动优先的响应式设计策略，确保在各种屏幕尺寸下都能正常显示：

• 移动端：单列布局，简化交互
• 平板端：双列布局，平衡信息密度
• 桌面端：多列布局，最大化信息展示

组件使用Tailwind CSS的响应式工具类实现布局调整，图表会根据容器宽度自动缩放，确保数据的可读性不受影响。

数据流架构

组件库采用统一的数据流管理架构，确保数据在各组件间的一致性传递：

graph TD
    A[API数据源] --> B[服务端组件]
    B --> C[数据处理层]
    C --> D[客户端组件]
    D --> E[用户交互]
    E --> C
    
    F[状态管理] --> D
    G[缓存层] --> C
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style E fill:#e8f5e9

• API数据源：提供股票行情、财务数据、市场数据等
• 服务端组件：负责数据获取和预处理
• 缓存层：Next.js内置的fetch缓存机制
• 客户端组件：处理用户交互和实时更新
• 状态管理：组件本地状态和全局状态协调

扩展与定制

自定义主题

组件库基于Tailwind CSS构建，支持通过配置文件自定义主题色彩和样式。所有组件都使用CSS变量定义颜色，使得主题切换变得简单：

// 自定义主题配置
const themeConfig = {
  colors: {
    primary: '#0066CC',
    secondary: '#00A86B',
    accent: '#FF6B35',
  },
  borderRadius: {
    DEFAULT: '8px',
  }
}

新增组件

添加新组件时，应遵循以下规范：

1. 文件命名：使用PascalCase命名法，如NewComponent.tsx
2. 类型定义：在src/types/目录定义相关TypeScript类型
3. 组件导出：在src/components/index.ts中统一导出
4. 测试覆盖：为组件编写单元测试和集成测试
5. 文档更新：更新组件文档和使用示例

性能优化

组件库内置了多种性能优化策略：

• 服务端渲染：减少首屏加载时间
• 图片优化：使用Next.js Image组件自动优化
• 代码分割：按需加载非关键组件
• 缓存策略：合理利用数据缓存减少重复请求
• 虚拟滚动：长列表使用虚拟滚动提升性能

相关资源

• 组件库源码：src/components/
• SEO组件文档：src/components/seo/README.md
• 评分系统文档：src/lib/scoring/
• Next.js官方文档：https://nextjs.org/docs
• shadcn/ui组件库：https://ui.shadcn.com/

概述

Fey设计系统（Fey UI）是一个现代化、可复用的前端组件库，旨在为量化平台提供一致的用户界面体验。该系统基于TypeScript开发，采用组件化架构，支持动态主题定制和动画效果管理。

概述

quant-platform 项目的 API 路由结构基于 Next.js App Router 架构构建，采用文件系统的约定式路由来定义 API 端点。该项目采用混合式 API 设计理念，结合了传统的 RESTful 风格端点与现代化的工具调用系统，为量化金融研究平台提供数据交互能力。

项目的 API 层主要承担以下核心职责：股票数据查询、财务报表获取、收益数据分析、投资组合管理、支付集成以及 AI 智能体工具调用。这种设计使得前端应用能够通过统一的数据接口获取所需的金融数据，同时保持代码结构的清晰与可维护性。

从架构层面来看，API 路由采用分层设计模式。基础层提供原始金融数据访问，包括股票报价、公司基本面、财务报表等核心信息。工具层则封装了常用的业务逻辑，如股票对比、排行榜计算、评分系统等。AI 代理层则通过模块化的工具系统，支持复杂的自然语言查询与自主研究能力。

目录结构

项目采用标准的 Next.js App Router 目录组织方式，所有 API 路由统一位于 src/app/api/ 目录下。每个路由模块通过 route.ts 文件暴露对应的 HTTP 方法处理器。

graph TD
    A[src/app/api] --> B[stock]
    A --> C[earnings]
    A --> D[v1]
    A --> E[stripe]
    A --> F[portfolio]
    A --> G[users]
    
    D --> D1[financials]
    D --> D2[rankings]
    D --> D3[analysis]
    
    E --> E1[webhook]
    
    B --> B1[quote]
    B --> B2[screener]
    B --> B3[compare]
    B --> B4[analysis]
    B --> B5[movers]
    B --> B6[search]

路由组织规范

项目遵循严格的目录命名约定，路由路径与文件系统目录结构一一对应。动态路由段使用方括号标记，例如 [ticker] 表示股票代码参数，[ticker]/growth 表示增长分析子路由。这种设计确保了 API 端点的一致性与可预测性。

版本控制通过目录前缀实现，v1 目录用于存放第一版 API 端点，便于后续版本迭代时的向后兼容管理。支付相关的敏感路由（如 Stripe Webhook）单独组织在专门的目录下，并配备额外的安全验证机制。

核心路由模块

股票数据路由

股票相关 API 是平台最核心的数据接口，涵盖从实时行情到历史分析的完整数据光谱。/api/stock/route.ts 作为主入口文件，处理股票相关的 GET 请求，根据查询参数分发到不同的数据获取逻辑。

该模块支持多种查询模式：单一股票详情查询、多股票批量查询、股票筛选器查询以及历史数据回溯。对于每种查询模式，系统会根据参数组合选择最优的数据获取策略，优先使用缓存数据以降低外部 API 调用成本。

// 典型查询参数结构
interface StockQueryParams {
  ticker?: string           // 股票代码，如 "AAPL"
  tickers?: string[]       // 批量查询代码列表
  period?: '1d' | '1w' | '1m' | '3m' | '1y' | '5y'  // 数据周期
  interval?: '1m' | '5m' | '1h' | '1d'  // 采样间隔
  screener?: string        // 筛选条件
  sortBy?: string          // 排序字段
}

资料来源：src/app/api/stock/route.ts:1-50

收益数据路由

/api/earnings/route.ts 专门处理企业财报相关的 API 请求。该模块提供季度收益日期、盈利预期、实际盈利数据以及盈利后价格变动等关键信息。对于选股策略和事件驱动策略而言，这些数据具有重要的参考价值。

收益日历功能允许用户查询特定时间段内的所有财报发布事件，便于提前规划交易策略。系统会聚合多家券商的盈利预测，生成市场共识预期区间，为投资决策提供量化参考。

财务报表路由

/api/v1/financials/route.ts 作为财务数据的版本化 API 端点，提供详细的财务报表查询能力。该路由支持收入报表、资产负债表、现金流量表等核心财务数据的获取，采用标准化的数据格式便于前端组件直接消费。

API 返回的数据经过清洗和标准化处理，缺失值使用合理方式填充或标记。历史数据的时间跨度根据不同指标有所差异，通常保留五至十年的历史记录以支持长期趋势分析。

投资组合管理

投资组合 CRUD 操作

/api/portfolio/route.ts 实现了投资组合管理的完整 CRUD 功能集。用户可以创建新的投资组合、添加或移除持仓、修改仓位权重以及删除整个投资组合。系统使用 Supabase 作为后端数据库，所有操作通过实时订阅保持前端状态同步。

每个投资组合包含以下核心字段：唯一标识符、用户关联 ID、组合名称、创建时间戳、最后修改时间以及持仓列表。持仓记录则关联股票代码、持仓数量、成本均价、买入日期等交易细节。

// 投资组合数据结构
interface Portfolio {
  id: string
  user_id: string
  name: string
  created_at: string
  updated_at: string
  holdings: Holding[]
}

interface Holding {
  id: string
  portfolio_id: string
  ticker: string
  shares: number
  cost_basis: number
  purchase_date: string
}

资料来源：src/app/api/portfolio/route.ts:1-60

投资组合分析

投资组合路由同时集成了分析功能，支持计算组合层面的各项指标，包括总市值、持仓分布、行业集中度、风险敞口等。通过调用底层的评分系统接口，可以获取组合中各持仓的 Lician Score 综合评分，帮助用户评估投资组合的整体质量。

支付集成

Stripe Webhook 处理

/api/stripe/webhook/route.ts 负责处理 Stripe 支付平台的 Webhook 回调。出于安全考虑，该路由实现了签名验证机制，确保所有请求确实来自 Stripe 服务器而非恶意第三方。

系统监听多种 Stripe 事件类型，包括支付成功、订阅创建、订阅更新、订阅取消、支付失败等。每种事件触发后，系统执行相应的业务逻辑：更新用户订阅状态、发送通知邮件、记录交易日志等。

graph TD
    A[Stripe Event] --> B{Verify Signature}
    B -->|Valid| C[Parse Event Type]
    B -->|Invalid| D[Return 400 Error]
    C --> E{Switch Event Type}
    E -->|checkout.session.completed| F[Activate Subscription]
    E -->|customer.subscription.updated| G[Update Subscription]
    E -->|customer.subscription.deleted| H[Deactivate Subscription]
    E -->|invoice.payment_failed| I[Mark Payment Failed]

资料来源：src/app/api/stripe/webhook/route.ts:1-100

订阅管理

支付流程与订阅管理紧密集成。当用户在 Stripe Checkout 完成支付后，Webhook 接收确认事件并激活相应的订阅计划。系统支持多种订阅层级，不同层级对应不同的 API 调用配额和功能权限。

AI 工具系统

工具架构概述

项目构建了一套模块化的 AI 工具系统，位于 src/lib/ai/tools/ 目录下。该系统采用分层设计，核心工具与外部服务工具分离，便于维护和扩展。

graph LR
    A[AI Agent] --> B[Tools Index]
    B --> C[Core Tools]
    B --> D[External API Tools]
    B --> E[Web Scraping Tools]
    B --> F[RAG Tools]
    
    C --> C1[Stock Quote]
    C --> C2[Fundamentals]
    C --> C3[Statements]
    C --> C4[Insider Trades]
    C --> C5[Analyst Ratings]
    
    D --> D1[SEC Filings]
    D --> D2[Price History]
    D --> D3[News Feed]
    D --> D4[Segmented Revenue]
    
    E --> E1[Firecrawl]
    E --> E2[Deep Research]
    
    F --> F1[Semantic Search]

核心金融工具

核心工具模块 (core.ts) 提供最常用的金融数据访问接口，包括实时股价查询、公司基本面获取、财务报表请求、内部人交易追踪、机构持仓查询以及分析师评级等。这些工具直接对接 Financial Datasets API 或缓存层，响应速度快，适合对时效性要求高的查询场景。

外部 API 工具

外部 API 工具模块 (external-api.ts) 封装了对 SEC EDGAR 数据库、历史价格数据、财经新闻源以及收入分拆数据的访问接口。工具内部实现了重试逻辑和错误处理机制，确保在外部服务不稳定时仍能提供部分可用数据。

网络抓取工具

基于 Firecrawl 的网络抓取工具 (firecrawl.ts) 支持深度研究和内容提取。scrapeWebContentTool 可以抓取任意网页的完整内容，deepResearchTool 则通过多轮搜索和总结提供更全面的研究结果。这些工具在标准 API 无法覆盖的场景下提供补充数据源。

响应格式规范

统一响应结构

所有 API 端点采用统一的响应格式封装返回数据，确保前端处理逻辑的一致性。

// 成功响应
{
  success: true,
  data: T,
  meta?: {
    cached: boolean,
    timestamp: string,
    count?: number
  }
}

// 错误响应
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: unknown
  }
}

分页支持

列表类接口支持分页查询，通过 page 和 limit 参数控制返回范围。响应 meta 信息中包含 total 字段指示总记录数，便于前端实现分页导航。

interface PaginatedResponse<T> {
  success: true,
  data: T[],
  meta: {
    page: number,
    limit: number,
    total: number,
    totalPages: number
  }
}

错误处理机制

错误分类

API 层将错误分为四类：客户端参数错误、数据源超时错误、业务逻辑错误以及未授权访问错误。每类错误对应特定的 HTTP 状态码和错误码，便于客户端区分处理。

重试策略

对于网络相关的临时性故障，系统实现指数退避重试机制。默认配置下，工具层会在首次失败后等待 1 秒重试，若仍失败则等待 2 秒，以此类推，最多重试 3 次。对于非幂等操作（如写操作），重试需格外谨慎。

性能优化

缓存策略

API 层实现多级缓存机制以提升响应速度。热门查询结果（如主要指数成分股）优先从内存缓存返回，缓存命中率直接影响响应延迟。缓存过期策略根据数据类型差异化设置：实时行情缓存 60 秒，基本面数据缓存 1 小时，历史数据缓存 24 小时。

批处理优化

当检测到多个相似查询时，系统会合并请求以减少外部 API 调用次数。例如，同时查询多只股票的报价时，优先尝试批量报价接口而非逐个查询。

安全考虑

认证与授权

敏感操作需要通过 Supabase Auth 进行身份认证，JWT 令牌通过 Authorization Header 传递。服务端验证令牌有效性并提取用户身份信息，用于权限判断和资源隔离。

订阅功能通过 Stripe 订阅状态控制，不同订阅计划对应不同的 API 调用频率限制。免费用户仅能访问有限的数据范围，付费用户解锁完整数据访问能力。

Webhook 安全

Stripe Webhook 路由实现签名验证，确保回调请求确实来自 Stripe。验证失败的请求直接返回 400 错误，不执行任何业务逻辑。

版本演进

API 版本策略

项目采用 URL 版本控制方案，v1 版本 API 位于 /api/v1/ 目录下。新增功能优先在 v1 版本迭代，当存在破坏性变更时创建 v2 版本目录。旧版本在过渡期内保持维护，确保现有客户端平稳迁移。

兼容性维护

数据库 schema 变更通过 Supabase Migration 管理，确保所有环境同步更新。重大变更前会提前通知用户并提供迁移指南，最大程度降低对现有用户的影响。

概述

外部数据源集成是量化平台的核心模块，负责从多个金融数据提供商获取股票市场数据、财务数据、实时报价以及监管文件。该模块采用模块化架构设计，支持灵活的数据源切换和统一的API接口抽象。

平台集成的外部数据源包括：

资料来源：src/lib/data-sources.ts

架构设计

整体架构

graph TD
    A[应用程序层] --> B[数据源抽象层]
    B --> C[SEC EDGAR Client]
    B --> D[Finnhub WebSocket]
    B --> E[Yahoo Finance WebSocket]
    C --> F[SEC.gov API]
    D --> G[Finnhub API]
    E --> H[Yahoo Finance API]
    F --> I[美国证券交易委员会]
    G --> J[金融数据聚合商]
    H --> K[交易所数据源]

数据源抽象层

平台在 src/lib/data-sources.ts 中定义了统一的数据源接口，提供了标准化的数据获取方法。

// 数据源配置接口
interface DataSourceConfig {
  name: string;
  apiKey?: string;
  baseUrl: string;
  rateLimit?: number;
  timeout?: number;
}

SEC EDGAR 集成

功能概述

SEC EDGAR（Electronic Data Gathering, Analysis, and Retrieval）集成模块负责从美国证券交易委员会获取上市公司的监管文件。这些文件包括：

• 10-K：年度报告
• 10-Q：季度报告
• 8-K：重大事项报告
• DEF 14A：委托声明书

资料来源：src/lib/sec-edgar/client.ts:1-50

客户端实现

SEC EDGAR客户端提供了以下核心功能：

// 构建公司搜索URL
export function buildCompanySearchUrl(cik: string): string {
  const cikNoZeros = cik.replace(/^0+/, '')
  return `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=${cikNoZeros}&type=&dateb=&owner=include&count=40&search_text=`
}

财年解析

客户端实现了XBRL财务数据的财年期间解析功能：

export function parseFiscalPeriod(fp: string | undefined): string {
  if (!fp) return ''
  switch (fp) {
    case 'FY':
      return 'FY'
    case 'Q1':
    case 'Q2':
    case 'Q3':
    case 'Q4':
      return fp
    default:
      return fp
  }
}

资料来源：src/lib/sec-edgar/client.ts:42-57

WebSocket 实时数据

实时数据架构

graph LR
    A[客户端] -->|WebSocket连接| B[Finnhub]
    A -->|WebSocket连接| C[Yahoo Finance]
    B -->|实时报价| A
    C -->|实时报价| A
    A -->|心跳检测| B
    A -->|心跳检测| C

Finnhub WebSocket

Finnhub提供实时股票报价、新闻和市场情绪数据。

// Finnhub WebSocket消息处理流程
class FinnhubWebSocket {
  connect(symbols: string[]): void
  subscribe(symbol: string): void
  unsubscribe(symbol: string): void
  onMessage(callback: (data: QuoteData) => void): void
  disconnect(): void
}

主要功能：

• 实时股票报价（价格、成交量、开盘价、收盘价）
• 市场新闻流
• 分析师评级数据
• 公司基本面数据

资料来源：src/lib/websocket/finnhub.ts

Yahoo Finance WebSocket

Yahoo Finance WebSocket提供期权数据和实时报价。

// Yahoo Finance WebSocket配置
interface YahooFinanceConfig {
  url: string
  reconnect: boolean
  heartbeat: boolean
  rateLimit: number
}

数据流处理：

sequenceDiagram
    participant Client
    participant YFWS as Yahoo Finance WS
    participant Handler
    
    Client->>YFWS: 建立连接
    YFWS-->>Client: 连接成功
    Client->>YFWS: 订阅股票代码
    YFWS-->>Handler: 转发数据
    Handler->>Client: 解析后数据
    loop 心跳检测
        Client->>YFWS: ping
        YFWS-->>Client: pong
    end

资料来源：src/lib/websocket/yahoo-finance.ts

数据分类体系

平台使用GICS（全球行业分类标准）进行行业分类，支持以下板块和行业：

板块映射

资料来源：src/lib/sectors.ts:1-30

排名指标体系

平台支持多维度股票排名，涵盖以下指标类别：

export const RANKING_METRICS = [
  // 估值指标
  'pe-ratio', 'forward-pe', 'price-to-book', 'price-to-sales', 'ev-ebitda', 'peg-ratio',
  // 盈利能力指标
  'profit-margin', 'operating-margin', 'gross-margin', 'net-margin', 'roa', 'roe', 'roic',
  // 成长性指标
  'revenue-growth', 'earnings-growth', 'eps-growth', 'dividend-growth',
  // 股息指标
  'dividend-yield', 'payout-ratio',
  // 规模指标
  'market-cap', 'enterprise-value', 'revenue', 'net-income',
  // 动量指标
  'ytd-return', '52-week-return', '1-month-return', '3-month-return',
  // 风险指标
  'beta', 'volatility',
  // 做空数据
  'short-interest', 'days-to-cover', 'short-ratio',
  // 分析师数据
  'analyst-rating', 'price-target-upside', 'analyst-count',
  // 内部交易数据
  'insider-buying', 'insider-ownership',
  // 机构数据
  'institutional-ownership', 'institutional-buying',
]

资料来源：src/lib/sectors.ts:11-27

SEO 结构化数据

Schema.org 集成

平台通过结构化数据提升搜索引擎可见性，定义了两类主要模式：

export function getOrganizationSchema() {
  return {
    '@context': 'https://schema.org',
    '@type': 'Organization',
    '@id': `${SITE_URL}/#organization`,
    name: SITE_NAME,
    url: SITE_URL,
    logo: {
      '@type': 'ImageObject',
      url: LOGO_URL,
      width: 512,
      height: 512,
    },
    sameAs: [
      'https://twitter.com/lician',
      'https://github.com/lician',
    ],
  }
}

资料来源：src/lib/seo.ts:15-33

文章Schema生成

export function getArticleSchema({
  headline,
  description,
  url,
  image,
  datePublished,
  dateModified,
  keywords
}: {
  headline: string
  description: string
  url: string
  image?: string
  datePublished?: string
  dateModified?: string
  keywords?: string[]
}) {
  return {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline,
    description,
    url,
    image: image || OG_IMAGE_URL,
    datePublished: datePublished || now,
    dateModified: dateModified || now,
    author: {
      '@type': 'Organization',
      '@id': `${SITE_URL}/#organization`,
      name: SITE_NAME,
    },
    publisher: {
      '@type': 'Organization',
      '@id': `${SITE_URL}/#organization`,
      name: SITE_NAME,
    },
  }
}

资料来源：src/lib/seo.ts:120-155

AI 工具集成

工具架构

AI工具模块提供了金融研究的自动化能力，通过统一的工具接口封装底层数据源：

// 工具模块导出结构
export * from './tools/index'

模块化的工具组织包括：

资料来源：src/lib/ai/tools.ts:1-22

代理类型系统

export type Phase = 'understand' | 'plan' | 'execute' | 'reflect' | 'answer' | 'complete'

export interface Understanding {
  intent: string
  entities: Entity[]
  timeframe?: string
  complexity: 'simple' | 'moderate' | 'complex'
}

export interface Task {
  id: string
  description: string
  taskType: 'use_tools' | 'reason'
  dependsOn: string[]
  status: TaskStatus
}

资料来源：src/lib/ai/agent/types.ts:1-30

配置管理

数据源配置

interface DataSourceConfig {
  name: string
  apiKey: string
  baseUrl: string
  rateLimit: {
    requestsPerSecond: number
    burstSize: number
  }
  timeout: number
  retry: {
    maxAttempts: number
    backoffMultiplier: number
  }
}

环境变量配置

最佳实践

数据获取策略

1. 优先级策略：优先使用实时WebSocket数据，回退到REST API
2. 缓存策略：静态数据（如公司信息）使用1小时缓存，动态数据（如报价）使用实时更新
3. 错误处理：实现指数退避重试机制

性能优化

graph LR
    A[请求] --> B{缓存命中?}
    B -->|是| C[返回缓存数据]
    B -->|否| D{速率限制?}
    D -->|是| E[加入队列等待]
    D -->|否| F[调用外部API]
    F --> G[处理响应]
    G --> H[更新缓存]
    H --> C

错误恢复

• WebSocket连接：自动重连机制
• API调用：3次重试，指数退避
• 超时处理：30秒默认超时时间

相关文件

• src/lib/data-sources.ts - 数据源抽象层
• src/lib/sec-edgar/client.ts - SEC EDGAR客户端
• src/lib/websocket/finnhub.ts - Finnhub实时数据
• src/lib/websocket/yahoo-finance.ts - Yahoo Finance实时数据
• src/lib/sectors.ts - 行业分类体系
• src/lib/seo.ts - SEO结构化数据
• src/lib/ai/tools.ts - AI工具集成

概述

quant-platform 是一个量化金融分析平台，其数据库架构基于 Supabase（PostgreSQL）构建，用于存储和管理股票分析所需的核心财务数据。数据库设计遵循模块化原则，将不同类型的金融数据（财务报表、内部交易、银行账户集成）分离到独立的表中，通过标准化的 ticker 标识符实现数据关联。

平台的数据库主要包含三大核心模块：

技术栈

平台采用 Supabase 作为后端即服务（BaaS）解决方案，提供以下核心能力：

• PostgreSQL 数据库：关系型数据存储，支持复杂查询和事务
• 实时订阅：数据库变更实时推送至客户端
• 行级安全策略（RLS）：数据访问权限控制
• API 自动生成：基于表结构自动生成 RESTful 和 GraphQL API

核心数据模型

财务报表模块

财务报表模块是平台分析功能的基石，存储上市公司历史和当前的财务数据。该模块的数据结构支持量化评分系统的多维度分析需求。

erDiagram
    FINANCIAL_METRICS ||--o| COMPANIES : references
    INCOME_STATEMENTS ||--o| COMPANIES : references
    BALANCE_SHEETS ||--o| COMPANIES : references
    CASH_FLOW_STATEMENTS ||--o| COMPANIES : references
    
    INCOME_STATEMENTS {
        string ticker PK
        date report_date
        string period_type "quarterly|annual"
        decimal revenue
        decimal net_income
        decimal gross_profit
        decimal operating_income
        decimal eps
    }
    
    BALANCE_SHEETS {
        string ticker PK
        date report_date
        string period_type
        decimal total_assets
        decimal total_liabilities
        decimal equity
        decimal cash
        decimal debt
    }
    
    CASH_FLOW_STATEMENTS {
        string ticker PK
        date report_date
        string period_type
        decimal operating_cash_flow
        decimal investing_cash_flow
        decimal financing_cash_flow
        decimal free_cash_flow
    }
    
    FINANCIAL_METRICS {
        string ticker PK
        date fiscal_period
        decimal pe_ratio
        decimal forward_pe
        decimal peg_ratio
        decimal profit_margin
        decimal roe
        decimal roa
    }

数据来源：src/lib/scoring/index.ts 导出的类型定义

平台使用以下 TypeScript 接口类型访问财务报表数据：

内部交易模块

内部交易模块跟踪公司内部人士的股票交易活动，这些数据是评估公司管理层信心和内部治理的重要信号。

graph TD
    A[内部交易记录] --> B[交易基本信息]
    A --> C[内部人士信息]
    A --> D[公司信息]
    
    B --> B1[交易类型: 买入/卖出]
    B --> B2[交易数量]
    B --> B3[交易价格]
    B --> B4[交易日期]
    
    C --> C1[姓名]
    C --> C2[职位/头衔]
    C --> C3[关联公司]
    
    D --> D1[ticker 股票代码]
    D --> D2[公司名称]

数据来源：supabase/migrations/20251210000002_insider_trades.sql

内部交易数据在 AI 分析代理中被用于评估管理层的投资信心：

For thorough stock analysis, combine multiple tools:

1. getCompanyFundamentals - valuation ratios, debt metrics

2. getFinancialStatements - detailed financials

3. getSECFilings - regulatory filings and material events

4. getInsiderTrades - management confidence signals

资料来源：src/lib/ai/agent/prompts.ts

银行集成模块

银行集成模块支持通过 Plaid 和 Tink API 接入用户的银行账户数据，用于个人投资组合管理和资产追踪。

graph LR
    A[用户银行账户] -->|Plaid API| B[plaid_accounts 表]
    A -->|Tink API| C[tink_accounts 表]
    
    B --> D[交易记录]
    C --> D
    
    D --> E[投资组合聚合]

数据来源：supabase/migrations/20251209100000_add_plaid_tink_tables.sql

客户端集成

Supabase 客户端配置

平台通过统一的 Supabase 客户端模块管理所有数据库连接和操作：

// 核心连接模式（伪代码示意）
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
)

资料来源：src/lib/supabase-client.ts

客户端模块的设计特点：

数据查询模式

平台的数据库查询遵循以下模式以确保性能和安全性：

1. 服务端优先：敏感查询在服务端组件中执行，避免暴露客户端密钥
2. 缓存策略：使用 Next.js 的 fetch 缓存机制减少数据库压力
3. 行级安全：通过 Supabase RLS 策略限制数据访问范围

数据流程架构

graph TD
    subgraph 数据源层
        A[SEC/EDGAR API]
        B[金融数据提供商]
        C[Plaid/Tink API]
        D[手动录入]
    end
    
    subgraph 存储层
        E[(财务报表)]
        F[(内部交易)]
        G[(银行账户)]
    end
    
    subgraph 处理层
        H[AI 分析代理]
        I[评分计算引擎]
        J[数据验证服务]
    end
    
    subgraph 应用层
        K[Web 前端]
        L[API 端点]
        M[实时仪表盘]
    end
    
    A --> E
    B --> E
    B --> F
    C --> G
    D --> F
    
    E --> J
    F --> J
    G --> J
    
    J --> H
    J --> I
    
    H --> K
    I --> K
    I --> L
    H --> M

安全策略

行级安全策略（RLS）

Supabase 的行级安全策略确保用户只能访问自己的数据：

• 用户隔离：用户只能查看自己的投资组合和账户数据
• 公开数据：股票财务数据对所有用户可读
• 管理员权限：特定角色可访问聚合统计数据

API 密钥管理

扩展与维护

添加新数据表

新增数据表的标准流程：

1. 在 supabase/migrations/ 目录下创建迁移文件
2. 使用 CREATE TABLE 定义表结构
3. 添加必要的索引和约束
4. 配置行级安全策略
5. 创建相关 TypeScript 类型定义

数据验证

所有入库数据需经过验证层处理：

• 类型检查：确保字段类型符合预期
• 范围验证：数值字段在合理范围内
• 完整性检查：必填字段非空
• 格式验证：日期、货币等格式正确

总结

quant-platform 的数据库架构采用 Supabase/PostgreSQL 作为核心存储解决方案，通过模块化的表设计支持财务分析、内部交易追踪和银行账户集成三大功能。架构设计注重数据完整性、查询性能和安全性，为平台的量化分析和 AI 代理功能提供了坚实的数据基础。

Pitfall Log / 踩坑日志

项目：sebastianbo/quant-platform

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 quant-platform 与安装入口 @lician/mcp-server 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @lician/mcp-server
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | repo=quant-platform; install=@lician/mcp-server

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.SebastianBO/financial-data:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.SebastianBO%2Ffinancial-data/versions/1.0.1 | release_recency=unknown