mystocks_spec 项目全景：A 股量化交易终端

一句话定位：面向个人/小型量化投资者的 A 股桌面端 Web 量化研究、监控、分析与交易辅助平台，采用 Vue 3 + FastAPI + ArtDeco 架构，以功能树、测试门禁和文档真相源分层管理持续演进。

一、项目定位与边界

核心定位（来自 CLAUDE.md §1）：

• 面向个人/小团队的本地化部署量化工具，非企业级 SaaS
• 仅桌面端 Web（最小 1280×720），明确拒绝移动端/平板适配
• 以「先路由、再下钻」的文档方法降低新人和 AI 在大型仓库的搜索成本

设计边界（严格区分"适合"与"过度设计"）：

新增功能评估准则：必要性 → 简洁性 → 维护成本 → 适用性。

二、技术栈与端口

端口（必须通过 .env 注入，禁止硬编码）：

三、项目结构

mystocks_spec/
├── architecture/          # 架构红线、域边界、治理规则（STANDARDS.md 真相源）
├── config/                # PM2、部署、运行配置
├── deps/openstock/        # OpenStock submodule（数据源契约同步）
├── docs/                  # 文档系统：FUNCTION_TREE / guides / reports / operations
├── openspec/              # Proposal/spec 工作流（变更管理）
├── scripts/               # 开发、生成、验证、自动化脚本
├── src/                   # Python 核心业务与数据层
│   ├── adapters/          # 多数据源适配器（待退役 → OpenStock）
│   ├── core/              # 核心分类、路由、管理器
│   ├── data_access/       # 数据库访问层
│   ├── governance/        # 风控与治理
│   ├── monitoring/        # 监控与告警
│   └── gpu/               # GPU 与加速能力
├── tests/                 # 后端、集成、性能、安全测试
├── web/
│   ├── backend/           # FastAPI 后端（app/main.py 入口）
│   │   ├── app/api/       # API 路由
│   │   ├── app/services/  # 应用服务层（含 openstock_client.py）
│   │   └── app/schemas/   # 请求/响应 schema
│   └── frontend/          # Vue 3 + ArtDeco 前端
└── README.md

四、业务功能域（FUNCTION_TREE 1.1.7）

10 大功能域，版本 1.1.7（2026-06-15）：

前端路由域（router/index.ts 真相源）：market / data / watchlist / strategy / trade / risk / system。

五、真相源分层（关键设计决策）

mystocks_spec 最大的工程特色是严格的真相源（Single Source of Truth）分层，避免大型仓库常见的"文档漂移"问题：

推荐阅读顺序（新人/AI 入仓必走）： 1. docs/guides/ai-tools/AI_QUICK_START.md — 任务路由入口 2. docs/FUNCTION_TREE.md — 定位目标功能域 3. architecture/STANDARDS.md — 规则与审批 4. openspec/AGENTS.md — proposal/spec 工作流

六、ArtDeco 设计系统

前端视觉主线是 ArtDeco 金融设计系统（不是旧 Element Plus 叙述）：

• 品牌 DNA：对角交叉影线、金色光晕（非投影）、Cinzel 大写衬线标题、双框与分隔线语言、罗马数字/旋转菱形点缀
• A 股语义：红涨绿跌（不可覆盖），价格颜色绝不能是唯一信号
• 永久暗色模式，强制 color-scheme: dark
• 几何装饰：数据区 0px 圆角，交互区 8px
• 两套间距系统：标准（13 级，4-128px）用于舒适视图；紧凑（4 级，4-16px）用于数据密集面板
• 并行系统：fintech-design-system.scss 服务监控组件（蓝黑+科技蓝），token 独立，禁止与 ArtDeco 混用

使用边界： - 数据密集与执行关键面（交易/风控/监控）→ 克制装饰，优先可扫描性 - 品牌前向面（总览/空状态/功能介绍）→ 可用更强 ArtDeco 动机 - 金融语义永远优先于装饰

七、与其他系统的关系

mystocks_spec 是用户量化生态中的业务终端层，与数据层、执行层、复盘层分工明确：

OpenStock (数据提供者, NAS:8040)
    ↑ HTTP REST 消费
    │
mystocks_spec (业务终端) ── 用户交互、策略/风控/交易 UI
    │
    ├── 数据落地: TDengine (时序缓存) + PostgreSQL (结构化)
    │
    └── 同一用户的其他工具:
        ├── MPW-hermes (策略编排/回测引擎, /opt/claude/MPW-hermes)
        ├── daily-stock skill (每日持仓工作流)
        ├── trade-audit skill (交易复盘审计)
        └── market-review skill (市场复盘报告)

详细对比见 mystocks_spec vs MPW-hermes vs daily-stock 定位对比。

八、关键运行入口

# 后端
cd web/backend
uvicorn app.main:app --host 0.0.0.0 --port "${BACKEND_PORT:-8020}" --reload

# 前端
cd web/frontend
npm run dev -- --port "${FRONTEND_PORT:-3020}"

# PM2 生产运行（一等公民）
pm2 list   # 关注 mystocks-frontend / mystocks-backend

# 验证
pytest && ruff check src/ web/backend/app/ && black --check .
cd web/frontend && npx stylelint "src/**/*.{vue,scss,css}"  # 零错误
cd web/frontend && npx vue-tsc --noEmit                      # TS 类型检查

访问地址：前端 http://localhost:3020 / 后端 http://localhost:8020 / Swagger http://localhost:8020/docs。

九、项目演进里程碑

• 早期（2025 Q3-Q4）：多代 akshare 适配器并行（Gen1 扁平/Gen2 modules/Gen3 market_adapter），累计 ~5,525 LOC、31 文件
• 2026 Q1：引入 OpenSpec 工作流、ArtDeco 设计系统主线确立
• 2026 Q2：B4.013 Runtime Mainline Bring-Up，确立"主线对齐与结果可见准则"
• 2026-06-29：OpenStock 消费者边界 SOT V1.0 生效，正式开启数据源统一收口
• 当前（2026-07-03）：分支 feat/b4-014-fundflow-mixin-openspec-proposal，主线 B4.014 OpenStock routes 迁移，Phase 1 六批业务域分批进行中

迁移路线与治理细节见 OpenStock 消费者边界与数据源迁移路线 和 mystocks_spec 治理体系。