# https://github.com/SebastianBO/quant-platform 项目说明书 生成时间：2026-06-02 10:20:03 UTC ## 目录 - [平台介绍](#page-introduction) - [项目目录结构](#page-project-structure) - [系统架构设计](#page-architecture) - [股票分析核心功能](#page-stock-analysis) - [AI功能与智能代理](#page-ai-features) - [UI组件库](#page-ui-components) - [Fey设计系统](#page-design-system) - [API路由结构](#page-api-routes) - [外部数据源集成](#page-data-sources) - [数据库架构](#page-database-schema) ## 平台介绍 ### 相关页面 相关主题：[系统架构设计](#page-architecture), [项目目录结构](#page-project-structure)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/SebastianBO/quant-platform/blob/main/README.md) - [src/lib/seo.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/seo.ts) - [src/lib/sectors.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sectors.ts) - [src/components/seo/README.md](https://github.com/SebastianBO/quant-platform/blob/main/src/components/seo/README.md) - [src/lib/scoring/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/index.ts) - [src/lib/ai/agent/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/index.ts) - [src/lib/ai/agent/prompts.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/prompts.ts) - [GROWTH_ANALYSIS_README.md](https://github.com/SebastianBO/quant-platform/blob/main/GROWTH_ANALYSIS_README.md) - [mcp-server/README.md](https://github.com/SebastianBO/quant-platform/blob/main/mcp-server/README.md)
# 平台介绍 ## 概述 Lician 是一个由 AI 驱动的股票研究与分析平台，托管于 lician.com。该平台提供全面的股票分析功能，包括增长分析、估值分析、SEO 优化内容生成等核心模块。平台基于 Next.js 14+ 构建，采用 App Router 架构，支持服务端渲染以优化搜索引擎排名。 ## 技术架构 ### 技术栈 | 技术分类 | 技术选型 | 说明 | |---------|---------|------| | 框架 | Next.js 14+ | React 框架，支持 App Router 服务端渲染 | | 语言 | TypeScript | 类型安全的 JavaScript 超集 | | 样式 | Tailwind CSS | 原子化 CSS 框架 | | 图表 | Recharts | React 图表库 | | UI 组件 | shadcn/ui | 基于 Radix UI 的组件库 | | 图标 | lucide-react | 开源图标库 | ### 项目结构 ``` 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 **数据结构展示：** ```mermaid 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 是平台的核心评分系统，从多个维度对股票进行综合评级。 **评分维度：** | 维度 | 说明 | 计算函数 | |------|------|----------| | Value Score | 价值评分 | `calculateValueScore` | | Growth Score | 成长评分 | `calculateGrowthScore` | | Quality Score | 质量评分 | `calculateQualityScore` | | Momentum Score | 动量评分 | `calculateMomentumScore` | | Safety Score | 安全评分 | `calculateSafetyScore` | **导出模块：** ```typescript 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 优化系统，包含元数据生成和结构化数据组件。 #### 结构化数据组件 | 组件 | Schema 类型 | 用途 | |------|-------------|------| | `FAQSchema` | FAQPage | 常见问题富摘要 | | `BreadcrumbSchema` | BreadcrumbList | 面包屑导航 | | `ArticleSchema` | Article | 文章内容标记 | | `HowToSchema` | HowTo | 操作指南标记 | | `CombinedSchema` | Combined | 多 Schema 组合 | #### SEO 元数据生成器 ```typescript // 股票页面元数据 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 研究代理 平台集成了自主金融研究代理系统。 **核心特性：** - 多阶段研究流程：理解 → 规划 → 执行 → 反思 - 智能工具选择 - 股票代码规范化 - 任务结果格式化 **导出模块：** ```typescript 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) 服务器提供标准化的股票数据访问接口。 **可用工具：** | 工具分类 | 工具名称 | 功能 | |---------|---------|------| | 价格数据 | `get_stock_price` | 实时股价快照 | | | `get_stock_prices` | 多只股票价格 | | | `get_historical_prices` | 历史价格数据 | | 财务报表 | `get_income_statement` | 损益表 | | | `get_balance_sheet` | 资产负债表 | | | `get_cash_flow_statement` | 现金流量表 | | | `get_financial_ratios` | 财务比率 | | 估值指标 | `get_company_fundamentals` | 估值比率、债务指标 | | 内部交易 | `get_insider_trades` | 内部人士交易 | | 分析师数据 | `get_analyst_ratings` | 评级和目标价 | | | `get_analyst_estimates` | EPS 和营收预测 | | 公司信息 | `get_company_info` | 基本信息 | | 新闻 | `get_stock_news` | 最新新闻 | | | `get_sec_filings` | SEC 文件 | | 加密/宏观 | `get_crypto_prices` | 加密货币价格 | | | `get_interest_rates` | 利率数据 | 资料来源：[mcp-server/README.md:1-100]() ## 行业板块系统 平台基于 GICS（全球行业分类标准）构建板块体系。 ### 支持的板块 | 板块标识 | 中文名称 | |---------|---------| | technology | Technology | | healthcare | Healthcare | | financials | Financials | | consumer-discretionary | Consumer Discretionary | | consumer-staples | Consumer Staples | | industrials | Industrials | | energy | Energy | | utilities | Utilities | | real-estate | Real Estate | | materials | Materials | | communication-services | Communication Services | ### 排名指标体系 平台支持多维度股票排名： ```typescript 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 进行基础设施即代码部署。 ```bash # 构建发布工具 make publisher # 使用 MCP 发布器 ./bin/mcp-publisher --help ``` ### 环境与版本 | 环境 | 分支 | 版本格式 | |------|------|---------| | 生产环境 | `main` | 持续构建 | | 开发环境 | `main--` | 特定提交 | ## 未来增强方向 根据项目规划，以下功能正在考虑中： 1. **行业对比基准** - 与行业平均水平的比较 2. **同行对比图表** - 可视化竞争对手分析 3. **前瞻增长预测** - 3-5 年增长预测模型 4. **季度趋势分析** - 季度数据深度分析 5. **增长质量评分** - 定性增长评估 6. **历史与预测对比** - 实际 vs 预期分析 7. **PDF 导出功能** - 报告导出 8. **收藏/书签功能** - 用户个性化保存 --- ## 项目目录结构 ### 相关页面 相关主题：[平台介绍](#page-introduction), [系统架构设计](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [src/app](https://github.com/SebastianBO/quant-platform/blob/main/src/app) - [src/components](https://github.com/SebastianBO/quant-platform/blob/main/src/components) - [src/lib](https://github.com/SebastianBO/quant-platform/blob/main/src/lib) - [supabase](https://github.com/SebastianBO/quant-platform/blob/main/supabase) - [scripts](https://github.com/SebastianBO/quant-platform/blob/main/scripts) - [n8n-workflows](https://github.com/SebastianBO/quant-platform/blob/main/n8n-workflows)
# 项目目录结构 ## 概述 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 路由和布局文件。 ### 核心页面模块 | 目录路径 | 功能描述 | |---------|---------| | `analysis/[ticker]/growth/` | 股票增长分析页面 | | `analysis/[ticker]/valuation/` | 股票估值分析页面 | | `stock/[ticker]/` | 股票详情页面 | | `learn/` | 教育内容页面（投资指南、技术分析等） | | `compare/` | 股票对比页面 | ### 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 结构化数据，支持以下类型： | 组件名称 | 功能 | 适用场景 | |---------|------|---------| | `FAQSchema` | 生成 FAQPage 结构化数据 | 常见问题页面 | | `BreadcrumbSchema` | 生成面包屑导航数据 | 所有页面 | | `ArticleSchema` | 生成文章结构化数据 | 博客、分析文章 | | `HowToSchema` | 生成操作指南数据 | 教程页面 | | `CombinedSchema` | 合并多个 Schema | 高效输出 | 资料来源：[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 创建功能。 **核心导出函数：** | 函数名 | 功能 | |-------|------| | `generateSEOMetadata()` | 生成页面元数据（标题、描述、关键词） | | `getOrganizationSchema()` | 生成组织 Schema | | `getWebSiteSchema()` | 生成网站 Schema | | `getArticleSchema()` | 生成文章 Schema | | `getFinancialProductSchema()` | 生成股票产品 Schema | | `generateStockMetadata()` | 生成股票页面元数据 | | `generateComparisonMetadata()` | 生成对比页面元数据 | **常量定义：** ```typescript 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，实现五阶段工作流： ```mermaid graph TD A[用户查询] --> B[理解阶段
Understand] B --> C[规划阶段
Plan] C --> D[执行阶段
Execute] D --> E[反思阶段
Reflect] E --> F{是否完成?} F -->|否| D F -->|是| G[回答阶段
Answer] G --> H[最终响应] ``` **核心模块：** | 文件 | 职责 | |-----|------| | `orchestrator.ts` | 五阶段工作流编排，实现理解→规划→执行→反思→回答 | | `prompts.ts` | 包含各阶段的系统提示词和用户提示词模板 | | `types.ts` | 定义 AgentState、Understanding、Plan、Task 等类型 | | `index.ts` | 统一导出模块接口 | **支持的工具类型：** - **Supabase 工具 (1-16)**: 获取美国上市股票的财务数据、历史数据、估值指标 - **SEC Filing 工具**: 获取 10-K、10-Q、8-K 等监管文件 - **Firecrawl 工具**: 抓取最新新闻和事件 - **欧洲公司工具**: 获取欧洲股票数据 资料来源：[src/lib/ai/agent/index.ts:1-30]()[src/lib/ai/agent/orchestrator.ts:1-50]() ### 评分系统 (scoring/) Lician Score 是平台的股票评分系统，从多个维度评估股票价值。 **评分维度：** | 维度 | 计算函数 | 考量因素 | |-----|---------|---------| | Value（价值） | `calculateValueScore()` | PE、PB、PS 等估值指标 | | Growth（增长） | `calculateGrowthScore()` | 收入增长、盈利增长 | | Quality（质量） | `calculateQualityScore()` | 利润率、ROE、ROA | | Momentum（动量） | `calculateMomentumScore()` | 价格走势、收益率 | | Safety（安全） | `calculateSafetyScore()` | Beta、波动性、债务 | **类型定义：** ```typescript type LicianScore = { overall: number dimensions: { value: DimensionScore growth: DimensionScore quality: DimensionScore momentum: DimensionScore safety: DimensionScore } } ``` 资料来源：[src/lib/scoring/index.ts:1-50]() ### 行业与排名 (sectors.ts) 定义行业分类和用于排名页面的指标体系。 **排名指标分类：** | 类别 | 指标 | |-----|------| | 估值 | 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]() ## 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 脚本目录包含部署、构建和开发辅助脚本。 **常用命令：** | 命令 | 功能 | |-----|------| | `make publisher` | 构建 MCP 发布工具 | | `./bin/mcp-publisher` | 发布 MCP 服务器 | | `make check` | 运行代码检查、单元测试和集成测试 | | `make help` | 显示所有可用命令 | 资料来源：[README.md:100-130]() ## MCP Server MCP（Model Context Protocol）服务器模块提供 AI 工具接口。 ``` mcp-server/ ├── README.md # MCP 服务文档 └── 实现代码 ``` **MCP 工具分类：** | 类别 | 工具示例 | |-----|---------| | 股票价格 | `get_stock_price` | | 财务数据 | `get_company_fundamentals`, `get_financial_statements` | | 分析师数据 | `get_analyst_ratings`, `get_analyst_estimates` | | 公司信息 | `get_company_info` | | 新闻与公告 | `get_stock_news`, `get_sec_filings` | | 加密与宏观 | `get_crypto_prices`, `get_interest_rates` | 资料来源：[mcp-server/README.md:20-60]() ## 技术栈总结 | 层级 | 技术选型 | 用途 | |-----|---------|------| | 前端框架 | Next.js 14+ (App Router) | 页面渲染、SSR/SSG | | UI 组件 | shadcn/ui | 基础 UI 组件库 | | 样式 | Tailwind CSS | 原子化 CSS 样式 | | 图表 | Recharts | 数据可视化 | | 数据库 | Supabase (PostgreSQL) | 数据存储与查询 | | AI 框架 | Vercel AI SDK | AI 代理与大语言模型集成 | | 协议 | MCP (Model Context Protocol) | AI 工具接口标准 | | 自动化 | n8n | 业务流程自动化 | | 部署 | Pulumi | 基础设施即代码 | | 图标 | lucide-react | React 图标库 | ## 目录结构关系图 ```mermaid 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
src/lib/ai/agent] end subgraph 自动化层 H[n8n-workflows] --> E I[scripts] --> J[部署配置
deploy] end K[用户请求] --> A G --> L[AI 响应] ``` ## 开发与部署 ### 开发环境 ```bash npm run dev ``` ### 页面测试 | 页面类型 | URL 示例 | |---------|---------| | 增长分析 | `/analysis/aapl/growth` | | 估值分析 | `/analysis/aapl/valuation` | | 股票对比 | `/compare/aapl-vs-msft` | | 学习中心 | `/learn/how-to-invest` | 资料来源：[GROWTH_ANALYSIS_README.md:150-180]() ## 总结 quant-platform 采用现代化的分层架构，将前端展示、AI 代理、数据服务和业务流程自动化清晰地分离。`src/` 目录是核心开发区域，`src/lib/` 提供了 SEO 优化、AI 代理、评分系统等关键业务能力，`src/components/` 提供了可复用的 UI 组件。外部服务（Supabase、n8n、MCP Server）则承担了数据持久化和复杂业务流程处理的责任。 --- ## 系统架构设计 ### 相关页面 相关主题：[平台介绍](#page-introduction), [API路由结构](#page-api-routes)
相关源码文件 以下源码文件用于生成本页说明： - [src/lib/api.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/api.ts) - [src/lib/supabase-client.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/supabase-client.ts) - [src/middleware.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/middleware.ts) - [next.config.ts](https://github.com/SebastianBO/quant-platform/blob/main/next.config.ts)
# 系统架构设计 ## 1. 架构概述 quant-platform 是一个基于 Next.js 构建的金融量化分析平台，集成了 AI 智能研究代理、股票评分系统和 SEO 优化功能。该平台采用现代化的全栈架构设计，充分利用服务端渲染、API 路由和中间件机制，为用户提供实时金融数据分析与可视化服务。 平台的整体架构遵循客户端-服务端分离模式，前端基于 React 组件化开发，后端通过 Next.js API Routes 提供数据接口，同时集成了 Supabase 作为数据存储层。这种架构设计确保了应用的可扩展性、安全性和高性能表现。 ### 1.1 技术栈概览 | 层级 | 技术选型 | 说明 | |------|----------|------| | 前端框架 | Next.js 14+ (App Router) | 服务端渲染与客户端交互 | | UI 组件库 | shadcn/ui | 基于 Radix UI 的组件库 | | 图表库 | Recharts | 数据可视化图表 | | 后端服务 | Next.js API Routes | 无服务器函数 | | 数据库 | Supabase | PostgreSQL + 实时订阅 | | AI 代理 | Vercel AI SDK | 多阶段自主研究代理 | | 图标库 | lucide-react | 现代图标系统 | ## 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 代理模块是平台的核心智能组件，采用多阶段自主工作流设计。代理通过五个阶段完成金融研究任务：理解用户意图、制定研究计划、执行工具调用、反思结果完整性、生成最终答案。 ```mermaid 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/orchestrator.ts` | 代理编排器，实现五阶段工作流 | | `src/lib/ai/agent/types.ts` | TypeScript 类型定义 | | `src/lib/ai/agent/prompts.ts` | 各阶段提示词模板 | | `src/lib/ai/tools.ts` | 工具函数导出入口 | 代理模块的设计遵循单一职责原则，每个阶段由独立的处理函数和专门的提示词模板驱动，确保了代码的可维护性和可测试性。资料来源：[src/lib/ai/agent/index.ts:1-12]() ### 2.3 评分系统模块 Lician Score 评分系统提供多维度股票评级能力，涵盖价值、成长、质量、动量和安全五个核心维度。该系统通过整合财务报表、现金流和分析师评级等数据，生成综合评分帮助投资者做出决策。 ```mermaid 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 ``` **评分维度说明：** | 维度 | 计算函数 | 数据来源 | |------|----------|----------| | 价值 Score | `calculateValueScore` | 市盈率、市净率、EV/EBITDA | | 成长 Score | `calculateGrowthScore` | 营收增长、EPS 增长、利润率变化 | | 质量 Score | `calculateQualityScore` | ROE、ROA、现金流质量 | | 动量 Score | `calculateMomentumScore` | 价格趋势、成交量变化 | | 安全 Score | `calculateSafetyScore` | 债务比率、波动性、β系数 | 资料来源：[src/lib/scoring/index.ts:1-43]() ## 3. API 与数据流架构 ### 3.1 API 层设计 平台通过 Next.js API Routes 提供统一的 API 接口层，所有外部数据请求和内部服务调用都经过这一层处理。API 层采用模块化设计，每个功能域对应独立的 API 模块。 ```mermaid 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 中间件机制实现全局请求拦截和处理。 **中间件核心功能：** | 功能 | 描述 | 实现位置 | |------|------|----------| | 身份验证 | JWT Token 验证与用户识别 | `src/middleware.ts` | | 路由保护 | 未授权访问重定向 | `src/middleware.ts` | | 请求日志 | 访问日志记录 | `src/middleware.ts` | | CORS 处理 | 跨域资源共享配置 | `src/middleware.ts` | 中间件在请求到达 API 路由之前执行，确保所有请求都经过统一的安全检查。这种设计避免了重复的身份验证代码，提高了系统的安全性和可维护性。资料来源：[src/middleware.ts]() ### 3.3 Supabase 集成架构 Supabase 作为平台的数据持久层，提供数据库、实时订阅和认证服务。客户端通过专门的封装模块与 Supabase 进行交互，隐藏了底层实现细节。 ```mermaid 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 格式嵌入页面，帮助搜索引擎更好地理解页面内容。 ```mermaid 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 组件清单：** | 组件 | Schema 类型 | 使用场景 | |------|------------|----------| | `FAQSchema` | FAQPage | 学习页面常见问题 | | `BreadcrumbSchema` | BreadcrumbList | 导航路径显示 | | `ArticleSchema` | Article | 分析报告页面 | | `HowToSchema` | HowTo | 投资指南步骤 | 资料来源：[src/components/seo/README.md:1-89]() ### 4.2 元数据生成系统 平台实现了动态元数据生成系统，根据页面内容自动生成标题、描述、关键词等 SEO 相关标签。该系统支持 OpenGraph、Twitter Card 和 Canonical URL 等高级特性。 **元数据配置选项：** | 选项 | 类型 | 说明 | |------|------|------| | `title` | string | 页面标题 | | `description` | string | meta 描述 | | `keywords` | string[] | 关键词数组 | | `image` | string | 社交分享图片 URL | | `type` | website \| article \| profile | 页面类型 | | `publishedTime` | string | 文章发布时间 | | `modifiedTime` | string | 内容修改时间 | | `canonical` | string | 规范 URL | 资料来源：[src/lib/seo.ts:1-120]() ## 5. 分析页面架构 ### 5.1 增长分析模块 增长分析模块是平台的核心功能之一，提供股票营收和盈利增长趋势的深入分析。模块采用服务端组件和客户端组件分离的架构，优化了 SEO 效果和交互体验。 ```mermaid 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[结构化数据] ``` **服务端数据获取：** | 数据类型 | 刷新策略 | 缓存时间 | |----------|----------|----------| | 损益表 (5年) | ISR | 1小时 | | 财务指标 (5年) | ISR | 1小时 | | 公司基本面 | ISR | 1小时 | | 分段营收 | ISR | 1小时 | 资料来源：[GROWTH_ANALYSIS_README.md:1-150]() ### 5.2 MCP 服务器架构 MCP (Model Context Protocol) 服务器为 Claude 等 AI 助手提供股票数据访问能力，扩展了平台的 AI 集成能力。服务器实现了多种工具函数，覆盖股票行情、公司信息、财务数据和新闻等方面。 **MCP 工具分类：** | 类别 | 工具函数 | 数据来源 | |------|----------|----------| | 行情 | `get_stock_price`, `get_stock_quotes` | 实时市场数据 | | 公司 | `get_company_info`, `get_company_fundamentals` | 财务数据库 | | 财务 | `get_financial_statements`, `get_earnings` | SEC 文件 | | 分析师 | `get_analyst_ratings`, `get_analyst_estimates` | 券商评级 | | 新闻 | `get_stock_news`, `get_sec_filings` | 新闻 API | | 加密 | `get_crypto_prices`, `get_interest_rates` | 加密货币 API | 资料来源：[mcp-server/README.md:1-100]() ## 6. Next.js 配置架构 ### 6.1 构建配置 Next.js 配置文件定义了应用的构建和运行时行为，包括图片优化、国际化、实验性功能等高级配置选项。 **关键配置项：** | 配置项 | 说明 | 默认值 | |--------|------|--------| | `images.domains` | 允许加载图片的域名 | 自定义 | | `i18n` | 国际化配置 | 可选 | | `experimental.serverActions` | 服务端动作支持 | true | | `logging.level` | 日志级别配置 | configurable | ### 6.2 环境变量架构 平台使用环境变量管理敏感配置和生产环境差异。关键环境变量包括数据库连接、API 密钥和第三方服务凭证。 ```mermaid 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` 命令快速启动完整开发栈。 **部署架构：** ```mermaid graph TD A[Docker Compose] --> B[Next.js 应用容器] A --> C[PostgreSQL 容器] A --> D[缓存服务容器] B --> C B --> D C --> E[持久化存储] D --> F[内存存储] ``` ### 7.2 开发环境 本地开发环境通过容器化确保一致性： | 组件 | 版本要求 | 用途 | |------|----------|------| | Docker | 最新稳定版 | 容器化 | | Node.js | 18+ | 运行构建 | | Go | 1.24.x | MCP 服务器 | | ko | 最新版 | 容器镜像构建 | 资料来源：[README.md:1-80]() ## 8. 安全性设计 ### 8.1 认证与授权 平台采用多层认证机制： - **JWT Token**: 用于 API 请求认证 - **Supabase Auth**: 第三方认证支持 - **中间件验证**: 请求级别的身份检查 - **API 路由保护**: 敏感接口的访问控制 ### 8.2 数据安全 | 安全措施 | 实现方式 | 保护层级 | |----------|----------|----------| | HTTPS | 强制 SSL | 传输层 | | 敏感变量 | 环境变量管理 | 配置层 | | SQL 注入防护 | 参数化查询 | 应用层 | | CORS 配置 | 白名单域名 | 网络层 | ## 9. 总结 quant-platform 采用现代化的分层架构设计，将展示层、业务逻辑层和数据层清晰分离。核心设计特点包括：基于 Next.js App Router 的服务端渲染架构、支持多阶段工作流的 AI 研究代理、完整的 SEO 优化体系，以及通过 MCP 协议实现的 AI 助手扩展能力。 平台的架构设计充分考虑了可扩展性、可维护性和安全性，为后续功能迭代和性能优化提供了良好的技术基础。 --- ## 股票分析核心功能 ### 相关页面 相关主题：[AI功能与智能代理](#page-ai-features), [UI组件库](#page-ui-components)
相关源码文件 以下源码文件用于生成本页说明： - [src/components/FinancialStatements.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/components/FinancialStatements.tsx) - [src/components/TechnicalAnalysis.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/components/TechnicalAnalysis.tsx) - [src/components/InsiderTrading.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/components/InsiderTrading.tsx) - [src/components/InstitutionalOwnership.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/components/InstitutionalOwnership.tsx) - [src/app/stock/[ticker]/page.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/app/stock/[ticker]/page.tsx) - [src/lib/seo.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/seo.ts) - [src/lib/scoring/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/index.ts) - [src/lib/sectors.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sectors.ts)
# 股票分析核心功能 ## 概述 股票分析核心功能是量化平台的核心模块，提供了全面的股票数据展示与分析能力。该模块整合了财务报表分析、技术分析、内幕交易追踪、机构持仓分析等多个维度的数据，帮助投资者做出更明智的投资决策。 平台采用 Next.js 14+ App Router 架构，所有分析组件均为服务端渲染（Server Components）或客户端组件（Client Components），确保了 SEO 友好性和良好的用户体验。 ## 系统架构 ```mermaid 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` #### 主要功能 | 功能 | 描述 | |------|------| | 收入报表 | 展示营业收入、毛利、净利润等指标 | | 资产负债表 | 展示资产、负债、权益结构 | | 现金流量表 | 展示经营、投资、融资现金流 | | 财务比率 | 计算关键财务比率指标 | #### 数据结构 ```typescript 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` #### 支持的技术指标 | 指标类型 | 指标名称 | |----------|----------| | 趋势指标 | 移动平均线 (MA)、MACD、ADX | | 动量指标 | RSI、随机指标、CCI | | 波动指标 | 布林带 ATR、肯特纳通道 | | 量价指标 | OBV、成交量加权平均价 | #### 图表功能 - **实时价格图表**：展示股票历史价格走势 - **技术指标叠加**：支持多指标叠加显示 - **交互式工具提示**：悬停显示详细数据 - **时间范围选择**：支持日、周、月视图切换 ### 3. 内幕交易追踪 (InsiderTrading) 内幕交易组件追踪公司内部人员的买卖活动，作为投资决策的重要参考信号。 **文件位置：** `src/components/InsiderTrading.tsx` #### 追踪的交易类型 | 交易类型 | 代码 | 信号含义 | |----------|------|----------| | 内部人员买入 | P-Purchase | 内部人员买入股票，看涨信号 | | 内部人员卖出 | S-Sale | 内部人员卖出股票，看跌信号 | | 内部人员卖出期权 | S-Sale+Op | 内部人员卖出期权合约 | #### 显示信息 - 内部人员姓名与职位 - 交易日期与类型 - 交易数量与金额 - 交易方式（公开市场、私募等） 资料来源：[src/components/InsiderTrading.tsx]() ### 4. 机构持仓分析 (InstitutionalOwnership) 机构持仓组件展示主要机构投资者对某股票的持仓情况与变动趋势。 **文件位置：** `src/components/InstitutionalOwnership.tsx` #### 关键指标 | 指标 | 描述 | |------|------| | 机构持股比例 | 机构投资者持有的股份占总股本的比例 | | 机构数量变化 | 持有该股票的机构数量增减 | | 持股集中度 | 前十大机构的持股占比 | | 新进/退出机构 | 季度内新进或退出的机构列表 | #### 数据来源 机构持仓数据来源于 SEC 13F 文件披露，季度更新。 ### 5. 机构所有权指标 (InstitutionalOwnership) ```mermaid graph LR A[机构投资者] --> B[13F Filing 数据] B --> C[数据聚合] C --> D[持股比例计算] C --> E[机构排名] D --> F[持股变化趋势] E --> G[主要机构列表] ``` ## Lician Score 评分系统 评分系统是平台的核心分析引擎，从多个维度对股票进行综合评分。 **文件位置：** `src/lib/scoring/index.ts` ### 评分维度 | 维度 | 描述 | 计算函数 | |------|------|----------| | 价值 (Value) | 估值是否偏低 | `calculateValueScore` | | 成长 (Growth) | 收入与盈利增长 | `calculateGrowthScore` | | 质量 (Quality) | 盈利质量与效率 | `calculateQualityScore` | | 动量 (Momentum) | 价格趋势强度 | `calculateMomentumScore` | | 安全 (Safety) | 风险与波动性 | `calculateSafetyScore` | ### 数据类型定义 ```typescript 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` ### 元数据生成流程 ```mermaid graph TD A[请求股票页面 /stock/AAPL] --> B[generateMetadata] B --> C[generateSEOMetadata] C --> D[OpenGraph 配置] C --> E[结构化数据] D --> F[社交分享卡片] E --> G[Google 富媒体摘要] ``` ### 股票页面元数据生成 ```typescript 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 结构化数据类型： | Schema 类型 | 用途 | 适用页面 | |-------------|------|----------| | Article | 文章/分析内容 | 所有分析页面 | | BreadcrumbList | 面包屑导航 | 所有页面 | | FAQPage | 常见问题 | 学习类页面 | | HowTo | 操作指南 | 教程页面 | 资料来源：[src/components/seo/README.md]() ## 行业分类体系 平台采用 GICS（全球行业分类标准）进行股票分类。 **文件位置：** `src/lib/sectors.ts` ### 支持的行业板块 | 板块 | 中文名称 | 子行业数量 | |------|----------|------------| | Technology | 科技 | 8 | | Healthcare | 医疗保健 | 9 | | Financials | 金融 | 6 | | Consumer Discretionary | 非必需消费 | 12 | | Consumer Staples | 必需消费 | 6 | | Industrials | 工业 | 10 | | Energy | 能源 | 4 | | Utilities | 公用事业 | 4 | | Real Estate | 房地产 | 7 | | Materials | 原材料 | 6 | | Communication Services | 通信服务 | 6 | ### 排名指标体系 ```typescript 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/` ### 增长分析页面结构 ```mermaid 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 结论] ``` ### 关键指标展示 | 指标 | 描述 | 数据来源 | |------|------|----------| | 最新营收 | 当期收入金额 | 利润表 | | YoY 增长 | 同比增长百分比 | 计算得出 | | 5年 CAGR | 5年复合年增长率 | 历史数据 | | 净利润率 | 净利润/营业收入 | 财务指标 | ### 增长分析关键词优化 页面针对以下搜索关键词进行 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` ### 核心数据工具 | 工具名称 | 功能描述 | |----------|----------| | `get_stock_price` | 实时股价与行情 | | `get_company_fundamentals` | 公司基本面数据 | | `get_financial_statements` | 财务报表（收入/资产/现金流） | | `get_insider_trades` | 内幕交易记录 | | `get_institutional_ownership` | 机构持仓数据 | | `get_analyst_ratings` | 分析师评级与目标价 | | `get_analyst_estimates` | 分析师盈利预测 | | `get_sec_filings` | SEC 文件披露 | 资料来源：[mcp-server/README.md]() ## AI 智能分析代理 平台集成了自主研发的金融研究 AI 代理，支持自然语言查询股票相关信息。 **文件位置：** `src/lib/ai/agent/` ### 代理工作流程 ```mermaid graph TD A[用户查询] --> B[理解阶段 Understand] B --> C[规划阶段 Plan] C --> D[执行阶段 Execute] D --> E[反思阶段 Reflect] E --> F{任务完成?} F -->|否| D F -->|是| G[回答阶段 Answer] G --> H[最终响应] ``` ### 代理类型定义 ```typescript export type Phase = 'understand' | 'plan' | 'execute' | 'reflect' | 'answer' | 'complete' export interface Understanding { intent: string entities: Entity[] timeframe?: string complexity: 'simple' | 'moderate' | 'complex' } ``` ### 实体类型支持 | 实体类型 | 示例 | 归一化处理 | |----------|------|------------| | ticker | AAPL | AAPL | | company | Apple | AAPL | | date | 2024-01-15 | ISO 8601 | | metric | PE Ratio | pe-ratio | | period | Q4 2024 | 2024-Q4 | 资料来源：[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 (页脚) │ └─────────────────────────────────────────┘ ``` ## 技术栈总结 | 技术类别 | 使用的技术 | |----------|------------| | 框架 | Next.js 14+ (App Router) | | 语言 | TypeScript | | 样式 | Tailwind CSS | | 图表 | Recharts | | UI 组件 | shadcn/ui | | 图标 | lucide-react | | 数据获取 | Server Components + fetch + cache | | AI 集成 | Vercel AI SDK | ## 总结 股票分析核心功能构成了量化平台的数据展示与分析基础，通过模块化的组件设计实现了： 1. **多维度分析**：财务报表、技术指标、内幕交易、机构持仓全覆盖 2. **SEO 友好**：自动生成元数据与结构化数据，提升搜索可见性 3. **AI 增强**：自然语言查询与智能研究代理 4. **评分体系**：Lician Score 多维度股票评分 5. **用户体验**：响应式设计与交互式图表 --- ## AI功能与智能代理 ### 相关页面 相关主题：[股票分析核心功能](#page-stock-analysis), [API路由结构](#page-api-routes)
相关源码文件 以下源码文件用于生成本页说明： - [src/lib/ai/agent/orchestrator.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/orchestrator.ts) - [src/lib/ai/agent/types.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/types.ts) - [src/lib/ai/agent/prompts.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/prompts.ts) - [src/lib/ai/agent/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/index.ts) - [src/lib/ai/tools.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/tools.ts) - [src/lib/scoring/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/index.ts)
# AI功能与智能代理 ## 概述 Lician平台的AI功能模块为用户提供智能化的股票研究和投资分析能力。该模块采用多阶段自主代理架构，灵感来源于virattt/dexter项目，通过理解用户意图、规划研究任务、自主执行工具调用、反思结果并生成综合回答的完整流程，实现深度的金融研究自动化。 AI代理系统的核心职责包括： - **自然语言理解**：解析用户查询中的股票代码、公司名称、指标和时间范围 - **任务规划**：将复杂研究请求分解为可执行的任务序列 - **工具编排**：智能选择和调用金融数据API、内部搜索和外部数据源 - **反思评估**：评估研究结果完整性，必要时补充信息 - **综合回答**：生成结构化的投资分析报告和投资建议 资料来源：[src/lib/ai/agent/orchestrator.ts:1-20]() ## 系统架构 ### 整体架构图 ```mermaid graph TD User[用户查询] --> ChatAPI[API路由
api/chat/route.ts] ChatAPI --> Orchestrator[Agent Orchestrator
五阶段工作流] Orchestrator --> Understand[1. Understand
理解阶段] Understand --> Plan[2. Plan
规划阶段] Plan --> Execute[3. Execute
执行阶段] Execute --> Reflect[4. Reflect
反思阶段] Reflect -->|不完整| Execute Reflect -->|完整| Answer[5. Answer
回答阶段] Answer --> Response[结构化投资报告] Execute --> Tools[AI Tools] Tools --> CoreTools[核心工具
getCompanyFundamentals
getFinancialStatements
getStockQuote] Tools --> RAG[RAG工具
searchFinancialDocuments] Tools --> External[外部API
SEC Filings
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]() ## 代理编排器详解 ### 五阶段工作流 代理编排器实现了完整的五阶段研究工作流，每个阶段都有明确的系统提示词和用户提示词模板。 ```mermaid graph LR A[用户查询] --> B[理解阶段
Extract Intent] B --> C[规划阶段
Create Tasks] C --> D[执行阶段
Run Tools] D --> E[反思阶段
Evaluate] E -->|不足| D E -->|充足| F[回答阶段
Generate] F --> G[最终报告] subgraph 理解阶段 B1[提取实体] --> B2[识别意图] B2 --> B3[确定复杂度] end subgraph 规划阶段 C1[分解任务] --> C2[确定依赖] C2 --> C3[排序执行] end subgraph 执行阶段 D1[选择工具] --> D2[调用API] D2 --> D3[收集结果] end ``` #### 阶段详解 | 阶段 | 英文名 | 核心功能 | 输出 | |------|--------|----------|------| | 1. 理解 | Understand | 提取查询中的股票实体、指标、时间范围，判断复杂度和用户意图 | `Understanding`对象 | | 2. 规划 | Plan | 将研究任务分解为原子任务序列，确定任务依赖关系 | `Plan`对象 | | 3. 执行 | Execute | 根据任务类型选择合适工具，调用金融数据API获取结果 | `TaskResult[]` | | 4. 反思 | Reflect | 评估研究结果完整性，判断是否需要补充信息 | `Reflection`对象 | | 5. 回答 | Answer | 综合所有信息生成结构化投资分析报告 | 最终回复文本 | 资料来源：[src/lib/ai/agent/orchestrator.ts:12-20]() ### 核心类型定义 代理系统使用TypeScript进行强类型约束，主要类型定义如下： ```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]() ### 工具调用结构 ```typescript // 工具调用接口 export interface ToolCall { id: string toolName: string args: Record status: 'pending' | 'running' | 'completed' | 'failed' result?: unknown error?: string } // 任务结果 export interface TaskResult { taskId: string output: string toolResults?: Record[] } // 代理完整状态 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]() ## 提示词工程 ### 提示词模板架构 系统为每个阶段定义了系统提示词和用户提示词，通过模板函数动态生成。 ```mermaid graph TD P[Prompts Module] --> PS[系统提示词] P --> PU[用户提示词] PS --> PSU[UNDERSTAND_SYSTEM_PROMPT
理解系统提示] PS --> PSP[PLAN_SYSTEM_PROMPT
规划系统提示] PS --> PSS[TOOL_SELECTION_SYSTEM_PROMPT
工具选择提示] PS --> PSE[EXECUTE_SYSTEM_PROMPT
执行系统提示] PS --> PSR[REFLECT_SYSTEM_PROMPT
反思系统提示] PS --> PSA[ANSWER_SYSTEM_PROMPT
回答系统提示] PU --> PUU[UNDERSTAND_USER_PROMPT
理解用户提示] PU --> PUP[PLAN_USER_PROMPT
规划用户提示] PU --> PUE[EXECUTE_USER_PROMPT
执行用户提示] PU --> PUR[REFLECT_USER_PROMPT
反思用户提示] PU --> PUA[ANSWER_USER_PROMPT
回答用户提示] ``` ### 关键提示词策略 #### 工具选择策略 ```typescript 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│ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 工具导出结构 ```typescript /** * 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评分系统从五个维度综合评估股票： | 维度 | 计算函数 | 指标说明 | |------|----------|----------| | 价值 | `calculateValueScore` | P/E、P/B、EV/EBITDA等估值指标 | | 成长 | `calculateGrowthScore` | 营收增长、盈利增长、EPS增长 | | 质量 | `calculateQualityScore` | ROE、ROIC、毛利率、净利润率 | | 动能 | `calculateMomentumScore` | YTD回报、52周回报、动量指标 | | 安全 | `calculateSafetyScore` | Beta、波动性、债务比率 | ```mermaid 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[股票评级输出] ``` ### 导出结构 ```typescript 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状态机 ```mermaid 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" ``` ### 关键数据流 | 阶段 | 输入 | 处理 | 输出 | |------|------|------|------| | 理解 | 用户原始查询 | LLM解析意图和实体 | `Understanding` | | 规划 | `Understanding` | 任务分解与依赖分析 | `Plan` | | 执行 | `Plan` | 工具调用与结果收集 | `TaskResult[]` | | 反思 | `TaskResult[]` | 完整性评估 | `Reflection` | | 回答 | 所有中间结果 | 综合生成报告 | 最终回复 | ## 扩展与集成 ### 添加新工具 在 `./tools/` 目录下的相应模块中添加工具函数，然后在 `./tools/index.ts` 中导出。代理系统会自动识别新工具并可用于工具选择阶段。 ### 添加新评分维度 在 `lician-score.ts` 中添加新的评分计算函数，并在 `index.ts` 中导出。确保新函数签名与现有函数一致。 ### 自定义提示词 修改 `./prompts.ts` 中对应的提示词模板，可以调整代理在各阶段的行为策略。 ## 相关文件索引 | 文件路径 | 用途 | |----------|------| | `src/lib/ai/agent/orchestrator.ts` | 五阶段代理编排器主实现 | | `src/lib/ai/agent/types.ts` | TypeScript类型定义 | | `src/lib/ai/agent/prompts.ts` | 各阶段提示词模板 | | `src/lib/ai/agent/index.ts` | 模块导出入口 | | `src/lib/ai/tools.ts` | 工具系统导出入口 | | `src/lib/scoring/index.ts` | Lician评分系统导出 | | `src/lib/scoring/lician-score.ts` | 评分算法实现 | --- ## UI组件库 ### 相关页面 相关主题：[Fey设计系统](#page-design-system), [股票分析核心功能](#page-stock-analysis)
相关源码文件 以下源码文件用于生成本页说明： - [src/components/seo/README.md](https://github.com/SebastianBO/quant-platform/blob/main/src/components/seo/README.md) - [src/lib/seo.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/seo.ts) - [src/lib/scoring/index.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/index.ts) - [src/lib/scoring/lician-score.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/lician-score.ts) - [src/lib/ai/tools.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/tools.ts) - [src/app/analysis/[ticker]/growth/page.tsx](https://github.com/SebastianBO/quant-platform/blob/main/src/app/analysis/[ticker]/growth/page.tsx)
# UI组件库 ## 概述 UI组件库是量化交易平台的核心视觉层，提供了一套完整的React组件系统，用于构建股票分析、投资组合管理、期权交易等专业金融界面。该组件库基于现代前端技术栈构建，包括Next.js 14+、TypeScript、Tailwind CSS和shadcn/ui组件库，旨在为用户提供专业且流畅的金融数据可视化体验。 组件库的设计理念围绕金融应用的核心需求展开，强调数据的清晰呈现、交互的即时响应以及专业分析功能的完整性。从交互式股票图表到投资组合分析器，每个组件都经过精心设计，以满足投资者和专业交易员的各种需求。组件库采用模块化架构，允许开发者根据具体业务场景灵活组合使用不同组件，同时保持了整体设计风格的一致性和代码的可维护性。 ## 核心组件架构 ### 组件分类概览 UI组件库按功能可分为以下几个核心类别，每个类别承担特定的用户界面职责： | 组件类别 | 主要功能 | 核心组件 | |---------|---------|---------| | 数据可视化 | 股票图表、K线图、趋势线 | InteractiveStockChart | | 搜索与导航 | 股票搜索、过滤、导航 | StockSearch | | 分析工具 | 投资组合分析、评分系统 | PortfolioAnalyzer | | 交易功能 | 期权链、交易界面 | OptionsChain | | SEO优化 | 结构化数据、SEO元数据 | FAQSchema, BreadcrumbSchema | | 通用UI | 基础UI组件库 | shadcn/ui组件 | ### 股票搜索组件 (StockSearch) 股票搜索组件是用户与平台交互的主要入口点，提供了快速定位和检索股票信息的能力。该组件支持按股票代码、公司名称或行业进行搜索，并提供自动补全功能帮助用户快速找到目标股票。 搜索组件的设计考虑了金融应用的特殊需求，包括： - **实时搜索建议**：用户输入时即时显示匹配结果 - **历史搜索记录**：记住用户最近的搜索偏好 - **多维度过滤**：支持按行业、市值、板块等条件筛选 - **快捷操作**：支持直接跳转到分析页面或添加自选股 搜索组件与后端API紧密集成，通过`/api/stock/search`端点获取搜索结果，确保搜索结果的实时性和准确性。组件还支持键盘导航，方便高级用户提高操作效率。 ### 交互式股票图表 (InteractiveStockChart) 交互式股票图表是组件库中最核心的可视化组件，采用了Recharts图表库实现丰富的金融数据展示功能。该组件支持多种图表类型和时间周期选择，能够满足不同分析场景的需求。 图表组件的主要特性包括： ```typescript // 核心图表配置 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) 期权链组件提供了完整的期权交易界面，支持查看和筛选期权合约、计算期权希腊值、评估期权价值等核心功能。该组件是平台期权分析功能的核心展示窗口。 期权链的数据结构定义如下： | 字段 | 类型 | 描述 | |-----|------|------| | strike | number | 行权价格 | | expiration | Date | 到期日 | | callPrice | number | 看涨期权价格 | | putPrice | number | 看跌期权价格 | | volume | number | 成交量 | | openInterest | number | 未平仓合约数 | | impliedVolatility | number | 隐含波动率 | | delta | number | Delta值 | | gamma | number | Gamma值 | | theta | number | Theta值 | | vega | number | Vega值 | 组件支持按行权价格、到期日、隐含波动率等多维度过滤和排序，帮助交易员快速定位感兴趣的期权合约。界面采用双栏布局，左侧展示看涨期权，右侧展示看跌期权，中间显示行权价格。 ## SEO组件系统 ### 结构化数据组件 SEO组件系统为页面提供Schema.org结构化数据支持，帮助搜索引擎更好地理解和索引页面内容。系统包含以下核心组件： | 组件名称 | Schema类型 | 主要用途 | |---------|-----------|---------| | FAQSchema | FAQPage | 常见问题富媒体片段 | | BreadcrumbSchema | BreadcrumbList | 面包屑导航展示 | | ArticleSchema | Article | 文章和博客内容 | | HowToSchema | HowTo | 分步骤指南内容 | | CombinedSchema | 组合 | 多Schema合并输出 | 结构化数据组件采用JSON-LD格式输出，自动注入到页面头部。以FAQSchema为例，组件接收问答数据数组，生成符合Google富媒体片段要求的结构化数据： ```tsx ``` 组件生成的JSON-LD脚本会被搜索引擎爬取，支持在搜索结果中显示富媒体片段，从而提高点击率。每个组件都提供了完整的TypeScript类型定义和详细的JSDoc文档，确保使用的便捷性和代码的健壮性。 ### SEO元数据生成 `src/lib/seo.ts`模块提供了完整的SEO元数据生成函数，支持为不同类型的页面生成优化的元数据配置： - **标题生成**：动态生成包含关键词和品牌的页面标题 - **描述优化**：根据页面内容自动生成描述性元标签 - **OpenGraph标签**：支持社交媒体分享预览 - **Twitter卡片**：优化Twitter分享效果 - **Canonical URL**：避免重复内容问题 - **结构化关键词**：提供搜索引擎友好的关键词列表 元数据生成函数支持覆盖和扩展，允许开发者根据具体页面需求进行定制。所有生成的元数据都遵循SEO最佳实践，包括合理的标题长度、描述长度控制等。 ## 评分系统集成 ### Lician评分体系 Lician评分系统是平台的核心分析引擎，提供五维度的股票综合评分： | 评分维度 | 权重 | 主要指标 | |---------|------|---------| | 价值 | 20% | P/E、P/B、EV/EBITDA等 | | 成长 | 25% | 收入增长、盈利增长、CAGR | | 质量 | 25% | ROE、ROIC、利润率 | | 动量 | 15% | 价格趋势、相对强弱 | | 安全 | 15% | 债务水平、波动性、流动性 | 评分系统导出了完整的计算函数和数据类型定义： ```typescript export { calculateLicianScore, calculateValueScore, calculateGrowthScore, calculateQualityScore, calculateMomentumScore, calculateSafetyScore, getSectorMedians, type LicianScore, type DimensionScore, type ScoreFactor, type SectorMedians } ``` 每个维度的评分都包含详细的数据点分析和置信度评估，帮助用户理解评分背后的逻辑。评分计算时会自动获取行业基准数据，确保评分的相对公平性和可比性。 ## 技术栈与依赖 ### 核心技术依赖 | 技术 | 版本要求 | 用途说明 | |-----|---------|---------| | Next.js | 14+ | React框架和App Router | | TypeScript | 最新稳定版 | 类型安全开发 | | Tailwind CSS | 3.x+ | 原子化CSS样式 | | Recharts | 最新版 | 图表可视化 | | shadcn/ui | 最新版 | UI基础组件库 | | lucide-react | 最新版 | 图标库 | | Zod | 最新版 | 类型验证和Schema定义 | 组件库充分利用了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基础组件 ``` ## 组件使用指南 ### 基本用法示例 以下是各核心组件的基本使用方式： **股票搜索组件**： ```tsx import { StockSearch } from '@/components/StockSearch' export default function SearchPage() { return ( router.push(`/stock/${stock.ticker}`)} placeholder="搜索股票代码或名称..." showFilters={true} /> ) } ``` **交互式图表组件**： ```tsx import { InteractiveStockChart } from '@/components/InteractiveStockChart' ``` **投资组合分析器**： ```tsx import { PortfolioAnalyzer } from '@/components/PortfolioAnalyzer' ``` ### 响应式设计 所有组件都采用移动优先的响应式设计策略，确保在各种屏幕尺寸下都能正常显示： - **移动端**：单列布局，简化交互 - **平板端**：双列布局，平衡信息密度 - **桌面端**：多列布局，最大化信息展示 组件使用Tailwind CSS的响应式工具类实现布局调整，图表会根据容器宽度自动缩放，确保数据的可读性不受影响。 ## 数据流架构 组件库采用统一的数据流管理架构，确保数据在各组件间的一致性传递： ```mermaid 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变量定义颜色，使得主题切换变得简单： ```typescript // 自定义主题配置 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/](https://github.com/SebastianBO/quant-platform/tree/main/src/components) - SEO组件文档：[src/components/seo/README.md](https://github.com/SebastianBO/quant-platform/blob/main/src/components/seo/README.md) - 评分系统文档：[src/lib/scoring/](https://github.com/SebastianBO/quant-platform/tree/main/src/lib/scoring) - Next.js官方文档：https://nextjs.org/docs - shadcn/ui组件库：https://ui.shadcn.com/ --- ## Fey设计系统 ### 相关页面 相关主题：[UI组件库](#page-ui-components)
相关源码文件 以下源码文件用于生成本页说明： - [src/components/fey-ui/base](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/base) - [src/components/fey-ui/composite](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/composite) - [src/components/fey-ui/animations](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/animations) - [src/components/fey-ui/tokens/design-tokens.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/tokens/design-tokens.ts)
# Fey设计系统 ## 概述 Fey设计系统（Fey UI）是一个现代化、可复用的前端组件库，旨在为量化平台提供一致的用户界面体验。该系统基于TypeScript开发，采用组件化架构，支持动态主题定制和动画效果管理。 --- ## 系统架构 ### 目录结构 Fey设计系统按照功能划分为以下几个核心模块： ``` src/components/fey-ui/ ├── tokens/ # 设计令牌（Design Tokens） ├── base/ # 基础组件 ├── composite/ # 复合组件 └── animations/ # 动画配置 ``` ### 架构层级 ```mermaid graph TD A[Fey设计系统] --> B[设计令牌层] A --> C[基础组件层] A --> D[复合组件层] A --> E[动画系统] B --> C C --> D style A fill:#e1f5fe style B fill:#b3e5fc style C fill:#81d4fa style D fill:#4fc3f7 style E fill:#29b6f6 ``` --- ## 设计令牌（Design Tokens） 设计令牌是Fey设计系统的基础层，定义了颜色、间距、字体、阴影等视觉属性的核心值。 ### 核心令牌类别 | 令牌类别 | 说明 | 用途 | |---------|------|------| | `colors` | 颜色系统 | 主色、辅助色、语义色 | | `spacing` | 间距规范 | 组件内外边距 | | `typography` | 字体系统 | 字号、行高、字重 | | `shadows` | 阴影效果 | 层级深度表现 | | `radii` | 圆角规范 | 按钮、卡片圆角 | | `transitions` | 过渡动画 | 状态切换时长 | ### 主题支持 设计令牌支持亮色/暗色主题切换，通过CSS变量实现动态主题切换。 资料来源：[src/components/fey-ui/tokens/design-tokens.ts:1-50]() --- ## 基础组件（Base Components） 基础组件是构建复杂界面的最小单元，提供原子化的UI元素。 ### 组件列表 | 组件名称 | 功能描述 | |---------|---------| | `Button` | 交互按钮，支持多种状态和变体 | | `Input` | 表单输入框 | | `Card` | 卡片容器 | | `Badge` | 标签徽章 | | `Avatar` | 用户头像 | ### 组件状态 基础组件通常支持以下状态： - **默认状态（Default）**：组件的初始展示 - **悬停状态（Hover）**：鼠标悬停时的反馈 - **激活状态（Active）**：点击/按下时的状态 - **禁用状态（Disabled）**：不可交互状态 - **加载状态（Loading）**：异步操作进行中 资料来源：[src/components/fey-ui/base](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/base) --- ## 复合组件（Composite Components） 复合组件由多个基础组件组合而成，实现更复杂的业务功能。 ### 组件列表 | 组件名称 | 说明 | 组成示例 | |---------|------|---------| | `SearchBar` | 搜索框组件 | Input + Button + Dropdown | | `DataTable` | 数据表格 | Card + 基础表格元素 | | `StockCard` | 股票信息卡片 | Card + Badge + 价格展示 | | `ChartContainer` | 图表容器 | Card + 图例 + 工具栏 | ### 组件组合模式 ```mermaid graph LR A[基础组件] --> B[复合组件] C[设计令牌] --> B B --> D[业务组件] B --> E[页面模块] style A fill:#b3e5fc style B fill:#81d4fa style C fill:#b3e5fc style D fill:#4fc3f7 style E fill:#4fc3f7 ``` 资料来源：[src/components/fey-ui/composite](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/composite) --- ## 动画系统（Animations） 动画系统负责管理组件的过渡效果和动态表现，提供流畅的用户体验。 ### 动画类型 | 动画类别 | 描述 | 使用场景 | |---------|------|---------| | `fade` | 淡入淡出 | 模态框、提示信息 | | `slide` | 滑动效果 | 侧边栏、折叠面板 | | `scale` | 缩放效果 | 弹出层、工具提示 | | `bounce` | 弹跳效果 | 按钮点击反馈 | ### 动画配置参数 ```typescript interface AnimationConfig { duration: number; // 持续时间（毫秒） easing: string; // 缓动函数 delay?: number; // 延迟时间（毫秒） iterations?: number; // 重复次数 } ``` ### 预设动画时长 | 动画场景 | 推荐时长 | |---------|---------| | 微交互反馈 | 100-150ms | | 组件状态切换 | 200-300ms | | 页面过渡 | 300-500ms | | 大型元素动画 | 500-800ms | 资料来源：[src/components/fey-ui/animations](https://github.com/SebastianBO/quant-platform/blob/main/src/components/fey-ui/animations) --- ## 组件开发规范 ### 命名规范 - 组件文件使用PascalCase命名（如 `StockCard.tsx`） - 样式文件使用kebab-case命名（如 `stock-card.css`） - 类型定义文件使用 `.types.ts` 后缀 ### Props设计原则 ```typescript interface ComponentProps { // 必填属性 required: string; // 可选属性带默认值 variant?: 'primary' | 'secondary'; size?: 'sm' | 'md' | 'lg'; // 事件处理器 onChange?: (value: string) => void; } ``` ### 无障碍性（Accessibility） - 所有交互元素支持键盘导航 - 使用语义化HTML标签 - 提供适当的ARIA属性 - 确保颜色对比度符合WCAG标准 --- ## 与平台其他模块的集成 ### 数据展示组件 Fey设计系统的复合组件与平台数据层紧密集成： - **股票数据展示**：使用 `StockCard` 组件展示实时行情 - **图表集成**：通过 `ChartContainer` 包装Recharts图表库 - **表格组件**：支持金融数据的高性能表格渲染 ### AI组件集成 AI代理系统的响应展示也基于Fey组件： - 对话气泡使用基础卡片组件 - 数据结果通过复合表格组件展示 - 分析报告使用结构化布局组件 资料来源：[src/lib/scoring/index.ts:1-30]() --- ## 使用示例 ### 基础按钮使用 ```tsx import { Button } from '@/components/fey-ui/base/Button'; ``` ### 股票卡片使用 ```tsx import { StockCard } from '@/components/fey-ui/composite/StockCard'; ``` ### 主题切换 ```tsx import { useTheme } from '@/components/fey-ui/tokens'; const { theme, toggleTheme } = useTheme(); // 切换到暗色主题 toggleTheme('dark'); ``` --- ## 总结 Fey设计系统通过模块化架构和标准化设计令牌，为量化平台提供了统一、美观且易维护的用户界面。系统采用TypeScript开发，保证了类型安全；通过设计令牌的抽象，实现了主题灵活切换；组件化的设计使得界面开发更加高效和一致。 --- ## API路由结构 ### 相关页面 相关主题：[系统架构设计](#page-architecture), [外部数据源集成](#page-data-sources)
相关源码文件 以下源码文件用于生成本页说明： - [src/app/api/stock/route.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/app/api/stock/route.ts) - [src/app/api/earnings/route.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/app/api/earnings/route.ts) - [src/app/api/v1/financials/route.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/app/api/v1/financials/route.ts) - [src/app/api/stripe/webhook/route.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/app/api/stripe/webhook/route.ts) - [src/app/api/portfolio/route.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/app/api/portfolio/route.ts)
# API路由结构 ## 概述 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 方法处理器。 ```mermaid 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 调用成本。 ```typescript // 典型查询参数结构 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、组合名称、创建时间戳、最后修改时间以及持仓列表。持仓记录则关联股票代码、持仓数量、成本均价、买入日期等交易细节。 ```typescript // 投资组合数据结构 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 事件类型，包括支付成功、订阅创建、订阅更新、订阅取消、支付失败等。每种事件触发后，系统执行相应的业务逻辑：更新用户订阅状态、发送通知邮件、记录交易日志等。 ```mermaid 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/` 目录下。该系统采用分层设计，核心工具与外部服务工具分离，便于维护和扩展。 ```mermaid 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 端点采用统一的响应格式封装返回数据，确保前端处理逻辑的一致性。 ```typescript // 成功响应 { success: true, data: T, meta?: { cached: boolean, timestamp: string, count?: number } } // 错误响应 { success: false, error: { code: string, message: string, details?: unknown } } ``` ### 分页支持 列表类接口支持分页查询，通过 `page` 和 `limit` 参数控制返回范围。响应 meta 信息中包含 `total` 字段指示总记录数，便于前端实现分页导航。 ```typescript interface PaginatedResponse { success: true, data: T[], meta: { page: number, limit: number, total: number, totalPages: number } } ``` ## 错误处理机制 ### 错误分类 API 层将错误分为四类：客户端参数错误、数据源超时错误、业务逻辑错误以及未授权访问错误。每类错误对应特定的 HTTP 状态码和错误码，便于客户端区分处理。 | 错误类型 | HTTP 状态码 | 错误码前缀 | 示例场景 | |---------|-------------|-----------|---------| | 参数错误 | 400 | `INVALID_` | 无效的股票代码 | | 认证错误 | 401 | `UNAUTHORIZED` | 缺失或过期令牌 | | 权限错误 | 403 | `FORBIDDEN` | 超出订阅配额 | | 未找到 | 404 | `NOT_FOUND` | 不存在的资源 | | 服务器错误 | 500 | `INTERNAL_` | 内部服务异常 | ### 重试策略 对于网络相关的临时性故障，系统实现指数退避重试机制。默认配置下，工具层会在首次失败后等待 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路由结构](#page-api-routes)
相关源码文件 以下源码文件用于生成本页说明： - [src/lib/data-sources.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/data-sources.ts) - [src/lib/sec-edgar/client.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sec-edgar/client.ts) - [src/lib/websocket/finnhub.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/websocket/finnhub.ts) - [src/lib/websocket/yahoo-finance.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/websocket/yahoo-finance.ts) - [src/lib/seo.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/seo.ts) - [src/lib/sectors.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sectors.ts) - [src/lib/ai/tools.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/tools.ts)
# 外部数据源集成 ## 概述 外部数据源集成是量化平台的核心模块，负责从多个金融数据提供商获取股票市场数据、财务数据、实时报价以及监管文件。该模块采用模块化架构设计，支持灵活的数据源切换和统一的API接口抽象。 平台集成的外部数据源包括： | 数据源 | 类型 | 主要功能 | |--------|------|----------| | SEC EDGAR | 监管文件 | 上市公司年报、季报、8-K文件 | | Finnhub | WebSocket实时数据 | 实时报价、新闻、情绪分析 | | Yahoo Finance | WebSocket实时数据 | 股票报价、期权数据 | 资料来源：[src/lib/data-sources.ts]() ## 架构设计 ### 整体架构 ```mermaid 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` 中定义了统一的数据源接口，提供了标准化的数据获取方法。 ```typescript // 数据源配置接口 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客户端提供了以下核心功能： ```typescript // 构建公司搜索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财务数据的财年期间解析功能： ```typescript 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 实时数据 ### 实时数据架构 ```mermaid graph LR A[客户端] -->|WebSocket连接| B[Finnhub] A -->|WebSocket连接| C[Yahoo Finance] B -->|实时报价| A C -->|实时报价| A A -->|心跳检测| B A -->|心跳检测| C ``` ### Finnhub WebSocket Finnhub提供实时股票报价、新闻和市场情绪数据。 ```typescript // 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提供期权数据和实时报价。 ```typescript // Yahoo Finance WebSocket配置 interface YahooFinanceConfig { url: string reconnect: boolean heartbeat: boolean rateLimit: number } ``` **数据流处理：** ```mermaid 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（全球行业分类标准）进行行业分类，支持以下板块和行业： ### 板块映射 | 板块标识 | 板块名称 | 行业数量 | |----------|----------|----------| | technology | 科技 | 8 | | healthcare | 医疗保健 | 9 | | financials | 金融 | 6 | | consumer-discretionary | 非必需消费 | 6 | | consumer-staples | 必需消费 | 5 | | industrials | 工业 | 8 | | energy | 能源 | 3 | | utilities | 公用事业 | 4 | | real-estate | 房地产 | 4 | | materials | 材料 | 3 | | communication-services | 通信服务 | 5 | 资料来源：[src/lib/sectors.ts:1-30]() ### 排名指标体系 平台支持多维度股票排名，涵盖以下指标类别： ```typescript 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 集成 平台通过结构化数据提升搜索引擎可见性，定义了两类主要模式： | Schema类型 | 用途 | 应用页面 | |------------|------|----------| | Organization | 网站信息 | 全站 | | WebSite | 搜索框优化 | 全站 | | Article | 文章内容 | 分析页面 | | BreadcrumbList | 面包屑导航 | 各分析页面 | | FAQPage | 常见问题 | 学习页面 | | HowTo | 操作指南 | 教程页面 | | Dataset | 数据集 | 金融数据页面 | ```typescript 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生成 ```typescript 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工具模块提供了金融研究的自动化能力，通过统一的工具接口封装底层数据源： ```typescript // 工具模块导出结构 export * from './tools/index' ``` 模块化的工具组织包括： | 工具模块 | 功能描述 | |----------|----------| | core.ts | 股票报价、公司基本面、财务报表、内部交易、机构持仓 | | firecrawl.ts | 网页抓取和研究工具 | | external-api.ts | SEC文件、价格数据、新闻、分段收入 | | eu.ts | 欧洲公司数据 | | rag.ts | 语义搜索和RAG功能 | | utils.ts | 共享工具（重试、超时、数据库客户端） | 资料来源：[src/lib/ai/tools.ts:1-22]() ### 代理类型系统 ```typescript 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]() ## 配置管理 ### 数据源配置 ```typescript interface DataSourceConfig { name: string apiKey: string baseUrl: string rateLimit: { requestsPerSecond: number burstSize: number } timeout: number retry: { maxAttempts: number backoffMultiplier: number } } ``` ### 环境变量配置 | 变量名 | 描述 | 必需 | |--------|------|------| | FINNHUB_API_KEY | Finnhub API密钥 | 是 | | SEC_API_KEY | SEC EDGAR API密钥 | 否 | | DATABASE_URL | 数据库连接URL | 是 | ## 最佳实践 ### 数据获取策略 1. **优先级策略**：优先使用实时WebSocket数据，回退到REST API 2. **缓存策略**：静态数据（如公司信息）使用1小时缓存，动态数据（如报价）使用实时更新 3. **错误处理**：实现指数退避重试机制 ### 性能优化 ```mermaid 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](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/data-sources.ts) - 数据源抽象层 - [src/lib/sec-edgar/client.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sec-edgar/client.ts) - SEC EDGAR客户端 - [src/lib/websocket/finnhub.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/websocket/finnhub.ts) - Finnhub实时数据 - [src/lib/websocket/yahoo-finance.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/websocket/yahoo-finance.ts) - Yahoo Finance实时数据 - [src/lib/sectors.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/sectors.ts) - 行业分类体系 - [src/lib/seo.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/seo.ts) - SEO结构化数据 - [src/lib/ai/tools.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/tools.ts) - AI工具集成 --- ## 数据库架构 ### 相关页面 相关主题：[外部数据源集成](#page-data-sources)
相关源码文件 以下源码文件用于生成本页说明： - [supabase/migrations/20251210000001_financial_statements.sql](https://github.com/SebastianBO/quant-platform/blob/main/supabase/migrations/20251210000001_financial_statements.sql) - [supabase/migrations/20251210000002_insider_trades.sql](https://github.com/SebastianBO/quant-platform/blob/main/supabase/migrations/20251210000002_insider_trades.sql) - [supabase/migrations/20251209100000_add_plaid_tink_tables.sql](https://github.com/SebastianBO/quant-platform/blob/main/supabase/migrations/20251209100000_add_plaid_tink_tables.sql) - [src/lib/supabase-client.ts](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/supabase-client.ts)
# 数据库架构 ## 概述 quant-platform 是一个量化金融分析平台，其数据库架构基于 **Supabase**（PostgreSQL）构建，用于存储和管理股票分析所需的核心财务数据。数据库设计遵循模块化原则，将不同类型的金融数据（财务报表、内部交易、银行账户集成）分离到独立的表中，通过标准化的 ticker 标识符实现数据关联。 平台的数据库主要包含三大核心模块： | 模块 | 说明 | |------|------| | 财务报表模块 | 存储上市公司的财务数据（损益表、资产负债表、现金流量表） | | 内部交易模块 | 记录内部人士（高管、董事）的股票交易活动 | | 银行集成模块 | 支持 Plaid/Tink 的银行账户数据接入 | ## 技术栈 平台采用 Supabase 作为后端即服务（BaaS）解决方案，提供以下核心能力： - **PostgreSQL 数据库**：关系型数据存储，支持复杂查询和事务 - **实时订阅**：数据库变更实时推送至客户端 - **行级安全策略（RLS）**：数据访问权限控制 - **API 自动生成**：基于表结构自动生成 RESTful 和 GraphQL API ## 核心数据模型 ### 财务报表模块 财务报表模块是平台分析功能的基石，存储上市公司历史和当前的财务数据。该模块的数据结构支持量化评分系统的多维度分析需求。 ```mermaid 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](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/scoring/index.ts) 导出的类型定义 平台使用以下 TypeScript 接口类型访问财务报表数据： | 类型 | 用途 | |------|------| | `IncomeStatement` | 损益表数据（收入、净利润、毛利润等） | | `BalanceSheet` | 资产负债表数据（资产、负债、权益等） | | `CashFlowStatement` | 现金流量表数据（经营、投资、融资现金流） | | `FinancialMetrics` | 财务比率指标（P/E、ROE、利润率等） | | `PriceData` | 股票价格历史数据 | | `AnalystRating` | 分析师评级和目标价 | ### 内部交易模块 内部交易模块跟踪公司内部人士的股票交易活动，这些数据是评估公司管理层信心和内部治理的重要信号。 ```mermaid 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](https://github.com/SebastianBO/quant-platform/blob/main/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](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/ai/agent/prompts.ts) ### 银行集成模块 银行集成模块支持通过 Plaid 和 Tink API 接入用户的银行账户数据，用于个人投资组合管理和资产追踪。 ```mermaid 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](https://github.com/SebastianBO/quant-platform/blob/main/supabase/migrations/20251209100000_add_plaid_tink_tables.sql) ## 客户端集成 ### Supabase 客户端配置 平台通过统一的 Supabase 客户端模块管理所有数据库连接和操作： ```typescript // 核心连接模式（伪代码示意） 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](https://github.com/SebastianBO/quant-platform/blob/main/src/lib/supabase-client.ts) 客户端模块的设计特点： | 特性 | 说明 | |------|------| | 环境变量配置 | 通过 `NEXT_PUBLIC_SUPABASE_URL` 和密钥配置连接 | | 类型安全 | 使用 TypeScript 泛型支持类型推断 | | 实时订阅 | 支持数据库变更的实时监听 | | 认证集成 | 与 Supabase Auth 无缝集成实现用户认证 | ### 数据查询模式 平台的数据库查询遵循以下模式以确保性能和安全性： 1. **服务端优先**：敏感查询在服务端组件中执行，避免暴露客户端密钥 2. **缓存策略**：使用 Next.js 的 `fetch` 缓存机制减少数据库压力 3. **行级安全**：通过 Supabase RLS 策略限制数据访问范围 ## 数据流程架构 ```mermaid 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 密钥管理 | 密钥类型 | 用途 | 暴露风险 | |----------|------|----------| | `NEXT_PUBLIC_SUPABASE_URL` | 数据库端点 | 低（公开客户端代码） | | `NEXT_PUBLIC_SUPABASE_ANON_KEY` | 匿名访问 | 中（用于公开数据读取） | | `SUPABASE_SERVICE_ROLE_KEY` | 服务端权限 | 高（仅服务端使用） | ## 扩展与维护 ### 添加新数据表 新增数据表的标准流程： 1. 在 `supabase/migrations/` 目录下创建迁移文件 2. 使用 `CREATE TABLE` 定义表结构 3. 添加必要的索引和约束 4. 配置行级安全策略 5. 创建相关 TypeScript 类型定义 ### 数据验证 所有入库数据需经过验证层处理： - 类型检查：确保字段类型符合预期 - 范围验证：数值字段在合理范围内 - 完整性检查：必填字段非空 - 格式验证：日期、货币等格式正确 ## 总结 quant-platform 的数据库架构采用 Supabase/PostgreSQL 作为核心存储解决方案，通过模块化的表设计支持财务分析、内部交易追踪和银行账户集成三大功能。架构设计注重数据完整性、查询性能和安全性，为平台的量化分析和 AI 代理功能提供了坚实的数据基础。 --- --- ## Doramagic 踩坑日志 项目：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