A股棱镜 (DeepStock) 开发文档 v1.0

1. 项目概览 (Project Overview)

2. 技术栈架构 (Tech Stack)

3. 视觉设计系统 (Design System)

系统采用统一的 CSS 变量定义在 base.html 中。

色彩规范

• --bg-body: #0f172a (午夜蓝背景)
• --bg-card: rgba(30, 41, 59, 0.6) (玻璃卡片背景)
• --text-highlight: #38bdf8 (极客蓝/品牌色)
• --text-sub: #94a3b8 (次级文本，高对比度灰)
• Text-Up: #f87171 (A股涨/利好/高风险)
• Text-Down: #34d399 (A股跌/利空/低风险)

UI 组件特征

• 玻璃拟态 (Glassmorphism)：使用 backdrop-filter: blur(12px) 和半透明边框。
• 微光特效：按钮和卡片使用 box-shadow 和渐变边框模拟发光。
• 呼吸灯：使用 CSS Keyframes (pulse-green, pulse-red) 指示实时状态。

4. 前端模块详解

所有页面均位于 templates/ 目录下，核心逻辑由 base.html 继承。

4.1 基础骨架 (base.html)

• SEO 优化：包含动态 Title, Description, Keywords block，以及 OG/Twitter Cards 标签。
• 组件拆分：
  • components/header.html：响应式导航栏，Logo (芯片+K线组合)，SEO 语义化标签。
  • components/footer.html：多列布局，包含订阅框（玻璃质感）、社交链接、版权信息。
• 资源加载：预加载 (Preconnect) CDN 资源，统一引入 Bootstrap/FontAwesome。

4.2 分析终端 (analysis.html)

核心功能 模拟专业金融终端的交互体验。

• 悬浮控制台：顶部输入框，支持回车搜索。
• 状态机：待机 -> 等待服务端响应 (真实) -> 流式生成中 (真实) -> 完成。
• 真实事件驱动进度：进度条只由真实事件推进 —— 请求发出 8% → 服务端响应头到达 35% → 收到首个流式分片 60% → 按已输出字数渐进至 95% → 流结束 100%。早期版本的固定时间轴假进度（未返回就显示 95%、文案写死上游数据源名称）已移除。
• 流式渲染：使用 fetch 读取流，TextDecoder 解码，Marked.js 实时渲染 Markdown。
• PDF 导出：调用后端接口将当前 HTML 转为 PDF 下载。

4.3 市场全景 (market_overview.html)

• 指数看板：三大指数（上证/深证/创业板）卡片，集成 Chart.js Sparkline (迷你图)，数据为 index_daily 近 20 日真实收盘序列，线条颜色按当日真实涨跌取红/绿。
• 成交额 / 龙虎榜家数：来自 index_daily.amount 与 top_list 当日条数，均为真实值。
• 情绪指数：Chart.js 橙色渐变曲线，横轴为近 30 个交易日（T-N ~ 最新），数据为上证指数真实收盘；右上角徽章为服务端计算的真实情绪值（0-100）与标签。
• 资金流向：柱状图展示北向资金（沪股通/深股通/合计）真实净流入，单位亿元。
• 涨跌家数：当前数据接口未提供全市场涨跌家数，页面已明确标注并以「沪/深成交额 + 北向资金 + 龙虎榜家数」呈现市场活跃度，不使用估算值冒充。

4.4 热门个股 (hot_stocks.html)

• 双榜单设计：
  • 左侧：用户热度榜（平台内搜索次数），前三名金银铜徽章。
  • 右侧：市场行情榜（龙虎榜净买入排名），价格/涨跌幅由 daily 最新日线补全。
• 无价格模拟：早期版本存在的 startLiveSimulation()（每 1.5s 随机微调价格并闪烁）已删除——它会伪造行情跳动，与"全部真实数据"原则冲突。
• 概念云：展示当前热门概念（如人形机器人、低空经济）。

4.5 机会捕捉 (opportunities.html)

• AI 机会卡片：结构化展示（逻辑 + 确信度徽章 + 关联个股）。
• 仪表盘动画：CSS 实现的半圆仪表盘，指针加载时带摆动动画。
• 互动投票：看涨/看跌投票按钮。
• 板块/概念排行：带涨跌幅和主力资金数据的列表。

4.6 市场快讯 (news_flash.html)

• 时间轴布局：左侧线条串联新闻流。
• AI 增强：每条新闻附带 ai-analysis-box，包含情感标签（利好/利空/中性）和 DeepSeek 简评。
• 定时刷新：页面每 5 分钟重新调用 /api/news 真实刷新一次，并把「更新于 HH:MM:SS」写回顶部；不再使用每秒跳动的本地时钟冒充实时。

4.7 风险预警 (risk_warning.html)

• DEFCON 仪表盘：顶部展示高危/中危/政策风险数量，高危卡片带红色呼吸灯。
• 风险卡片：顶部色条区分等级（红/橙/蓝），底部附带 AI 风险评估结论。
• 瀑布流加载：卡片带 slideUp 进场动画。

4.8 用户系统

• 登录 (login.html) / 注册 (register.html)：
  • 独立页面，不继承 base.html。
  • 沉浸式深蓝背景 + 玻璃拟态表单。
  • 交互：密码明文切换、验证码倒计时、协议强制勾选。
• 个人中心 (profile.html)：
  • Dashboard 布局：展示头像、VIP 等级、积分。
  • 权益进度条：双色进度条展示普通/深度分析剩余次数。
  • 分析记录：最近分析过的股票列表。
• 价格方案 (pricing.html)：
  • 三列卡片布局（免费/VIP1/VIP2）。
  • VIP2 推荐高亮（缩放+发光）。
  • FAQ 折叠面板。

5. 后端 API 规范 (FastAPI)

基于 main.py 的路由定义。

页面路由 (Page Routes)

功能接口 (Functional APIs)

• 分析接口 POST /api/analyze
  输入: { query: "600519" }
  输出: StreamingResponse (text/html) - 流式返回 Markdown 片段。
• PDF 导出 POST /api/export-pdf
  输入: { html_content: "...", stock_name: "..." }
  输出: { download_url: "/api/export-pdf/download/{filename}" }
  下载: GET /api/export-pdf/download/{filename}（需登录）

6. AI 提示词工程 (Prompt Engineering)

这是生成研报的灵魂，在 ai_service.py 中实现。

7. 部署与配置

环境变量 (.env)

DATA_API_KEY=your_data_api_key
DATA_CHANNEL=default
AI_API_KEY=your_ai_api_key
AI_ENDPOINT=your_endpoint_id

启动命令

uvicorn main:app --host 0.0.0.0 --port 8000 --reload