auv/AGENTS.md

A股走势追踪应用 - 技术上下文

Dependencies

• recharts - K线图表库（已内置）
• lucide-react - 图标库（已内置）
• sonner - Toast通知组件（已内置）

Architecture

路由结构

• / - 首页：搜索股票、创建集合、管理股票
• /stock/$code - 股票详情页：K线图、实时行情、涨幅显示
• /share/$code - 分享页面：通过短链查看公开的股票集合

数据库表

• stock_collections - 股票集合（名称、描述、user_id、last_accessed_at）
• collection_stocks - 集合中的股票记录（股票代码、名称、添加时间、添加价格）
• share_links - 分享短链（短链码、关联集合ID）

用户管理

• 每个匿名用户生成永久 userid 存储到 localStorage
• 集合通过 user_id 隔离，RLS 策略基于 user_id 控制访问
• 3个月未访问的集合自动删除（通过 Edge Function 定时清理）

数据源

• Edge Function stock-quote 代理腾讯财经API获取A股实时行情
• Edge Function stock-history 双数据源获取历史K线：主源腾讯 fqkline（前复权），腾讯返回数据少于2条时降级新浪 getKLineData（北交所920开头新股腾讯常只返回1条，新浪能返回完整90天）
• Edge Function stock-search 代理腾讯智能搜索API（smartbox.gtimg.cn）支持名称/代码/拼音模糊搜索
• Edge Function stock-fund-flow 获取近30日资金流向数据，主数据源为东方财富妙想MX API（mkapi2.dfcfs.com，每日150次调用限制，需配置 MX_APIKEY 环境变量），回退方案为东方财富 push2his.eastmoney.com
  • MX API 数据特性：返回数据按日期降序（最新在前），Edge Function 内必须 sort 为正序后再计算累计值；只返回主力净流入和成交额，不提供散户/中单/小单数据
  • 日期格式标准化：MX API 返回日期格式可能不统一（2026/07/04、07-04），Edge Function 内统一为 YYYY-MM-DD 以匹配 K 线数据
  • 数值解析：MX API rawTable 字段可能是字符串（如 "1.432亿元"），需用 parseAmount 函数解析
  • JWT 鉴权：stock-fund-flow 必须部署为 -j false（匿名可访问），否则前端调用被拒绝
  • 回退方案东方财富API字段（索引0-18）：日期,主力净流入,超大单流入/流出,大单流入/流出,中单流入/流出,小单流入/流出,主力净流入%,超大单流入/流出%,大单流入/流出%,中单流入/流出%,小单流入/流出%
  • 腾讯K线API字段：[日期, 开, 收, 高, 低, 成交量, 成交额]（第7个字段是成交额）
  • ❌ 东方财富K线API（kline/get）不稳定，可能返回 data:null，已弃用改用腾讯
• 前端通过 /sb-api/functions/v1/stock-quote?code={6位代码} 调用实时行情
• 前端通过 /sb-api/functions/v1/stock-history?code={6位代码}&days={天数} 调用历史数据
• 前端通过 /sb-api/functions/v1/stock-search?keyword={关键词} 调用搜索（腾讯返回UTF-8+\u转义，类型字段GP-A/GP-A-KCB/GP-A-BJB区分主板/科创板/北交所）
• 前端通过 /sb-api/functions/v1/stock-fund-flow?code={6位代码}&name={股票名称}&days={天数} 调用资金流向数据（name 参数用于MX API查询）
• 市场标识：688/60开头为SH（上海主板/科创板），920/8/4开头为BJ（北交所），其他为SZ（深圳主板/创业板）

What Didn't Work

• ❌ 新浪财经API直接在前端调用 → 跨域限制 → 改用Edge Function代理
• ❌ 腾讯财经历史API直接在前端调用 → 跨域限制 → 改用Edge Function代理
• ❌ 百度股市通API → 返回格式不稳定 → 改用腾讯+新浪双数据源
• ❌ Python mootdx库 → 沙箱环境无法安装C++依赖 → 放弃Python方案

Patterns / Constraints

• RLS策略设置为匿名可读写，支持分享链接公开访问
• 股票代码格式：6位数字（如600519）
• 分享短链生成：随机8位字母数字组合
• 集合卡片股票列表格式：名称/代码（左）+ 添加价/涨跌%/最新价（右三列）
• 添加股票时 added_price 保存为当日实时价格；若无历史数据则显示当前价和 0.00%
• 分享链接区域点击自动复制到剪贴板，通过 Sonner Toaster 显示提示；复制失败时降级为 textarea 方案或提示手动复制
• 生成分享链接时复用已有短链，避免每次生成新链接
• 全页面适配移动端：响应式字体、间距、布局断点（sm/md/lg）
• K线图历史数据获取失败时直接报错，禁止使用模拟数据降级（避免"刷新数据变化"问题）
• K线天数逻辑：默认3个月（90天），自选日期到现在超过3个月则从自选日期开始
• K线图使用 recharts Brush 组件实现移动端缩放和滑动查看
• 板块标记：688开头=科创(红)、300/301开头=创业(紫)、920/8/4开头=北交(橙)，主板不显示标签；标记位置：搜索候选、详情页标题、集合卡片股票列表、分享页股票卡片标题
• 详情页右上角外部跳转按钮：①"东方财富" https://wap.eastmoney.com/quote/stock/{market}.{code}.html?appfenxiang=1，market映射 688→6/60→1/其他→0；②"金十数据" https://search.jin10.com/?keyword={股票名称URL编码}（按名称搜索金十资讯）
• 详情页资金流向模块：展示近30日资金流向分析，包含：
  • 资金流向概览：主力总净流入、大单流入资金（≈主买资金）、日均主力流入、主力流入/流出天数统计
  • 主力资金流向：柱状图展示每日主力净额
  • 累计主力资金趋势：折线图展示累计主力资金的走势变化
• 每日行情明细表：独立于资金流向模块，默认显示7日数据，支持切换7日/21日；表格列包含日期、涨幅、主力净流入、成交额，颜色遵循A股惯例（红涨绿跌）
• 每日行情明细表数据截取：使用 chartData.slice(-dailyTableDays).reverse() 获取最近N个交易日的倒序数据（最新日期在前）
• 每日行情明细表资金流向匹配：K线 dateObj 转 YYYY-MM-DD 时必须用本地时区（getFullYear/getMonth/getDate），禁止用 toISOString().split('T')[0]（UTC 偏移会导致中国时区日期错位一天，资金流向数据匹配失败）；匹配字段为 mainForceNet（主力净额=超大单+大单净流入）和 turnover（成交额）
• 成交额备用计算：当资金流向API获取失败时，使用 chartData 的 volume × close 近似计算成交额（单位：元）
• 资金流向数据获取失败时，前端通过 fundFlowError 状态显示错误信息，便于排查问题
• ❌ 东方财富 API（push2his.eastmoney.com）在 Edge Function 环境被拒绝访问（peer closed connection），主力净流入数据无法获取，显示为 "-"
• ✅ 替代方案：使用腾讯实时行情API的外盘(索引7)和内盘(索引8)数据计算净主动买入额 = (外盘 - 内盘) × 当前价 × 100（单位：元）