fluopath · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/.github/workflows/android.yml b/.github/workflows/android.yml
@@ -0,0 +1,57 @@
+name: Android APK
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main, "agent/**"]
+    paths:
+      - "src/**"
+      - "public/**"
+      - "packages/**"
+      - "apps/native/**"
+      - "package*.json"
+      - "vite.config.ts"
+      - ".github/workflows/android.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build-debug-apk:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      NDK_VERSION: "29.0.14206865"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: gradle
+      - uses: android-actions/setup-android@v3
+      - name: Install Android SDK packages
+        run: sdkmanager "platform-tools" "platforms;android-36" "build-tools;36.0.0" "ndk;$NDK_VERSION"
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: aarch64-linux-android
+      - run: npm ci
+      - name: Build installable ARM64 debug APK
+        run: |
+          export NDK_HOME="$ANDROID_HOME/ndk/$NDK_VERSION"
+          npm run android:build:debug --workspace @nexus/native
+      - name: Collect APK
+        run: |
+          mkdir -p artifacts/android
+          find apps/native/src-tauri/gen/android/app/build/outputs/apk -type f -name '*.apk' -exec cp {} artifacts/android/NEXUS-Quant-v0.7.0-arm64-debug.apk \;
+          test -f artifacts/android/NEXUS-Quant-v0.7.0-arm64-debug.apk
+      - uses: actions/upload-artifact@v4
+        with:
+          name: NEXUS-Quant-Android-v0.7.0
+          path: artifacts/android/*.apk
+          if-no-files-found: error
+          retention-days: 30
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
@@ -0,0 +1,23 @@
+name: Quality Gate
+
+on:
+  pull_request:
+  push:
+    branches: [main, "agent/**"]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+
diff --git a/.gitignore b/.gitignore
@@ -15,6 +15,7 @@ dist-ssr
 .env.*
 !.env.example
 apps/native/src-tauri/target
+artifacts/
 
 # Editor directories and files
 .vscode/*

diff --git a/PROJECT_HANDOFF.md b/PROJECT_HANDOFF.md
@@ -0,0 +1,306 @@
+# NEXUS Quant 项目接手手册
+
+> 最后核对：2026-08-08 · 应用版本：`0.7.0`  
+> 本文面向新开发者、产品负责人和接手项目的 AI。先阅读“安全边界”和“第一天接手清单”，再开始修改。
+
+## 1. 项目是什么
+
+NEXUS Quant 是一个面向个人学习与研究的跨资产量化金融实验室。目前把以下能力放在同一个工作空间中：
+
+- 分级金融课程、术语库和学习进度；
+- A 股、港股、美股、期货、黄金、原油及大宗商品观察；
+- A 股规则模拟、T+1 可卖数量、费用和模拟账户；
+- 双均线回测、样本外分析、参数敏感性和走步验证；
+- 因子研究、Rank IC、逆波动组合和组合风险分析；
+- 基本面研究清单、投资论点、估值情景和权威披露入口；
+- Web、Windows、Android、iOS 共用的领域核心与 API SDK。
+
+这仍是学习和研究产品，不是实盘交易系统。演示行情、部分市场参数、回测数据和估值数字均为仿真或示例，不构成投资建议。
+
+## 2. 当前交付状态
+
+### 已经实现
+
+- React 19 + TypeScript 6 + Vite 8 单页应用，共 8 个主要模块；
+- Fastify API、REST 快照、SSE 行情流、安全响应头、CORS 和限流；
+- 有容量和并发约束的异步研究任务，支持取消与状态统计；
+- `@nexus/core`：跨端领域类型、工具目录、交易规则、回测、稳健性和因子函数；
+- `@nexus/sdk`：行情、研究、风险、工具目录和订单 API 客户端；
+- 仿真券商连接器、预交易检查、幂等订单、条件单撮合、撤单和脱敏审计；
+- 移动优先界面：底部主导航、全部功能面板、44px 触控目标、安全区、手机底部弹层；
+- PWA manifest、离线应用壳和可安装快捷入口；
+- Tauri 2 原生壳、已生成的 Android Studio 工程和全套 adaptive icon；
+- GitHub Actions Web 质量门禁与 ARM64 Android APK 构建；
+- Dockerfile、Compose、API/架构/实盘安全文档；
+- Windows 双击启动脚本 `start-nexus.cmd`；
+- 29 个测试以及 API、浏览器冒烟脚本。
+
+### 尚未生产化
+
+- 行情提供者当前默认为内置仿真；没有购买或接入任何商业实时数据授权；
+- 研究任务保存在单进程内存中，服务重启后任务消失；
+- 用户、课程、订单和研究数据主要保存在浏览器本地，没有账户体系和数据库；
+- `paper_broker` 与 `live` 环境在服务端默认拒绝；没有真实券商连接器；
+- 组合风险使用学习用途的简化相关性假设；
+- Android 当前交付调试签名 ARM64 APK；Google Play 发布签名、AAB 与商店材料尚未配置；
+- 当前开发机已有 Rust、Android Studio、API 36、Build Tools、ADB 与 NDK，但因无管理员权限缺少 MSVC；本地 Android 编译应使用有 MSVC 的 Windows 或 GitHub Actions；
+- 已有基础 CI，但没有生产部署 CD、生产域名、TLS、监控告警和灾难恢复。
+
+## 3. 安全边界（必须遵守）
+
+1. 不要把数据商 Token、券商密钥、Cookie、身份证件或银行卡数据写入前端、日志、Git 或 `localStorage`。
+2. `.env` 和 `.env.*` 已被 Git 忽略；只有无密钥的 `.env.example` 可以提交。
+3. 实盘环境不得由前端参数直接开启。必须有服务端开关、账户授权、重新认证、逐笔确认、审计和紧急停止。
+4. 外部行情和工具参数必须携带来源、时间戳、新鲜度和延迟标记。`indicativeOnly=true` 的参数不能直接用于真实下单。
+5. 未经授权不得抓取、缓存或再分发交易所及数据商实时行情。
+6. 回测必须显式处理费用、滑点、未来数据、复权、停牌、涨跌停、退市和幸存者偏差；当前引擎只覆盖其中一部分。
+7. 不要宣称 VaR、压力测试或回测收益代表最大损失、未来收益或实盘承诺。
+
+更完整的实盘边界见 [`docs/BROKER_CONNECTORS.md`](docs/BROKER_CONNECTORS.md)。
+
+## 4. 技术架构
+
+```text
+React UI（Web / Tauri Windows / Android / iOS）
+   ├── Zustand 持久化状态
+   ├── @nexus/core 领域模型与纯计算
+   ├── @nexus/sdk 跨端 API 客户端
+   └── MarketDataProvider
+          ├── SimulationMarketProvider
+          └── NexusApiMarketProvider（REST / SSE）
+                         │
+                    Fastify API
+          ├── 标准化行情网关
+          ├── 异步研究任务
+          ├── 组合风险分析
+          └── 仿真券商与审计
+```
+
+关键原则：页面不理解供应商私有格式；交易和回测规则尽量放在无 React、DOM、网络依赖的 `packages/core`；跨端网络协议放在 `packages/sdk`。
+
+## 5. 目录导航
+
+| 路径 | 责任 |
+| --- | --- |
+| `src/pages/` | 8 个业务页面：总览、学习、市场、期货、模拟盘、策略、研究、风险 |
+| `src/components/` | 应用壳、共享组件、错误边界、基本面研究组件 |
+| `src/services/` | 行情提供者与研究 API 适配 |
+| `src/store.ts` | Zustand 本地账户、持仓、订单和课程状态 |
+| `packages/core/src/` | 领域类型、交易规则、工具目录、回测、稳健性、因子和结算函数 |
+| `packages/sdk/src/` | 跨端 API SDK 和 SSE 适配器 |
+| `server/app.ts` | API 路由、输入校验和安全中间件 |
+| `server/researchJobs.ts` | 有界内存研究队列 |
+| `server/broker.ts` | 仿真券商连接器参考实现 |
+| `server/risk.ts` | 组合风险计算 |
+| `apps/native/` | Tauri 2 Windows/Android/iOS 壳、Android Studio 工程与图标 |
+| `scripts/` | API 与浏览器冒烟测试 |
+| `docs/` | API、架构、数据源、多平台和实盘安全说明 |
+
+## 6. 本地启动
+
+### Windows 最简方式
+
+双击仓库根目录的 `start-nexus.cmd`。脚本会在需要时安装依赖，启动 Web 与 API，并打开浏览器。
+
+- Web：`http://localhost:5173/#overview`
+- API：`http://127.0.0.1:8787`
+- 健康检查：`http://127.0.0.1:8787/api/health`
+
+标题为 `NEXUS Quant Services` 的窗口必须保持打开；关闭窗口即停止服务。
+
+### 命令行方式
+
+```bash
+npm install
+npm run dev:full
+```
+
+只启动前端：`npm run dev`  
+只启动 API：`npm run server:dev`
+
+如果端口被占用，在 Windows PowerShell 中检查：
+
+```powershell
+Get-NetTCPConnection -State Listen | Where-Object LocalPort -In 5173,8787
+```
+
+不要通过结束所有 Node 进程来解决端口问题；应确认 PID 后只停止本项目的进程。
+
+## 7. 环境配置
+
+复制 `.env.example` 中需要的配置，不要直接修改或提交真实密钥。
+
+| 变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `VITE_NEXUS_API_BASE` | 前端 API 基址；同源或 Vite 代理时留空 | 空 |
+| `PORT` | API 端口 | `8787` |
+| `HOST` | API 监听地址 | `127.0.0.1` |
+| `NEXUS_ALLOWED_ORIGIN` | 逗号分隔的 CORS 白名单 | 本地 Vite 地址 |
+
+生产容器示例：`docker compose up --build`。当前机器未验证 Docker 构建，部署前必须在安装 Docker 的环境执行镜像构建和健康检查。
+
+## 8. 必跑质量门禁
+
+提交前运行：
+
+```bash
+npm run check
+```
+
+它依次执行：
+
+1. `npm run lint`
+2. `npm test`
+3. `npm run build`
+4. `npm run qa:api`
+5. `npm run qa:e2e`
+
+当前基线为 9 个测试文件、29 个测试。数量增加是正常的，减少时必须解释原因。浏览器冒烟覆盖 8 个桌面路由、8 个手机路由、7 个关键交互、全局横向溢出检查和两张视觉快照；新增页面或关键流程时必须同步扩展 `scripts/smoke.mjs`。
+
+额外检查：
+
+```bash
+npm audit
+git diff --check
+git status -sb
+```
+
+## 9. API 快速索引
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/api/health` | 服务状态和版本 |
+| GET | `/api/v1/system/capabilities` | 客户端能力发现 |
+| GET | `/api/v1/instruments` | 跨资产工具目录 |
+| GET | `/api/v1/markets/snapshot` | 行情快照 |
+| GET | `/api/v1/markets/stream` | SSE 行情流 |
+| POST | `/api/v1/research/jobs` | 创建回测或稳健性任务 |
+| GET | `/api/v1/research/jobs/:id` | 查询任务 |
+| DELETE | `/api/v1/research/jobs/:id` | 取消排队任务 |
+| GET | `/api/v1/research/stats` | 任务队列统计 |
+| POST | `/api/v1/portfolio/risk` | 组合风险分析 |
+| POST | `/api/v1/trading/orders/preview` | 预交易检查 |
+| POST | `/api/v1/trading/orders` | 提交仿真订单 |
+| GET | `/api/v1/trading/orders` | 订单列表 |
+| DELETE | `/api/v1/trading/orders/:id` | 撤单 |
+| GET | `/api/v1/trading/audit` | 脱敏审计事件 |
+
+详细请求与响应见 [`docs/API.md`](docs/API.md)。
+
+## 10. 浏览器持久化状态
+
+当前以下数据保存在浏览器本地，清理站点数据会丢失：
+
+- `nexus-quant-state`：账户、持仓、订单和课程完成状态；
+- `nexus-data-source`：行情源选择；
+- `nexus-research-note`：量化研究笔记；
+- `nexus-fundamental-checks`：基本面研究清单；
+- `nexus-investment-thesis`：投资论点；
+- `nexus-learning-level`：解释深度。
+
+修改 Zustand 持久化结构时需要设计迁移，不能假设用户一定是全新状态。
+
+## 11. 常见扩展方式
+
+### 新增行情提供者
+
+1. 在 `src/services/marketData.ts` 实现相同 provider 生命周期；
+2. 服务端完成供应商字段到统一行情结构的转换；
+3. 密钥只放服务端；
+4. 保留仿真回退和延迟/错误状态；
+5. 扩展 API 与浏览器冒烟测试。
+
+### 新增资产或交易规则
+
+1. 扩展 `packages/core/src/domain.ts`；
+2. 在 `packages/core/src/instruments.ts` 增加带来源和生效日的工具定义；
+3. 在纯函数层实现校验并增加单元测试；
+4. 再接入 API、SDK 和页面；
+5. 动态保证金、港股整手和期货合约参数必须标记为需要刷新。
+
+### 新增研究分析
+
+1. 优先在 `packages/core` 编写可复现纯函数和确定性测试；
+2. 大计算通过研究任务协议运行，不阻塞请求线程；
+3. SDK 返回紧凑、跨端稳定的结果；
+4. 页面必须显示样本、费用、参数和方法边界。
+
+## 12. Git 与 GitHub 工作流
+
+远端仓库：`https://github.com/fluopath/Nexus-Quant-lab`
+
+本文创建时的状态：
+
+- 分支：`agent/initial-nexus-quant-platform`
+- 初始平台提交：`932017b`
+- Draft PR：`https://github.com/fluopath/Nexus-Quant-lab/pull/1`
+
+开始工作前先执行：
+
+```bash
+git status -sb
+git fetch origin
+```
+
+确认 PR #1 是否已经合并。如果已合并，从最新 `main` 创建新的 `agent/<description>` 分支；不要继续在已合并的旧分支堆叠无关改动。禁止 force-push、`git reset --hard` 或静默覆盖他人改动。
+
+提交原则：一次提交只表达一个清晰意图；提交前检查 staged diff；通过 PR 合并到 `main`。
+
+## 13. 已知技术债与建议优先级
+
+### P0：生产基础
+
+1. 在现有 GitHub Actions 之上增加发布签名、SBOM、依赖审查和生产部署审批；
+2. 增加用户认证、PostgreSQL 数据模型、迁移和备份；
+3. 建立数据授权清单、供应商接口和行情质量监控；
+4. 增加结构化日志、指标、追踪、错误上报和健康/就绪探针；
+5. 安全评审后再开始真实券商适配。
+
+### P1：研究和交易真实性
+
+1. Redis/消息队列 + 独立研究 Worker，替换内存任务；
+2. 历史行情版本、参数哈希、代码版本和结果对象存储；
+3. 复权、停牌、涨跌停、退市、连续合约和交易日历；
+4. 模拟盘统一使用服务端订单生命周期，而不是部分逻辑仍在前端即时成交；
+5. 风险模型加入协方差、货币、行业、期限和衍生品 Greeks。
+
+### P2：体验扩展
+
+1. 观察列表、提醒、任务中心和研究工作流；
+2. 课程 CMS、错题本、练习沙箱和学习推荐；
+3. Python 研究服务与 TypeScript 结果交叉验证；
+4. 完成 Windows 安装包、iOS 真机构建，以及 Android 稳定发布签名与 Play AAB；
+5. 无障碍、视觉回归和性能预算。
+
+## 14. Definition of Done
+
+一个功能只有同时满足以下条件才算完成：
+
+- 需求和不支持范围写清楚；
+- 核心规则位于正确层，不在多个页面复制；
+- 输入校验、错误状态、加载状态和离线/失败路径完整；
+- 关键逻辑有测试，关键用户流程有冒烟覆盖；
+- `npm run check` 通过；
+- 没有提交密钥、个人数据、构建产物或无授权数据；
+- README/API/架构或本接手文档已同步；
+- 金融结果显示数据时间、费用、方法假设和风险提示。
+
+## 15. 第一天接手清单
+
+1. 阅读 `README.md`、本文、`docs/ARCHITECTURE.md` 和 `docs/BROKER_CONNECTORS.md`。
+2. 确认 PR #1 和当前分支状态，避免基于过期分支开发。
+3. 运行 `npm install` 与 `npm run check`，记录自己的环境差异。
+4. 用 `npm run dev:full` 打开 8 个模块，完成一次课程、模拟交易和回测。
+5. 阅读 `packages/core/src/domain.ts`、`server/app.ts` 和 `src/store.ts`。
+6. 从 P0/P1 中选择一个边界明确的任务，先写验收标准再改代码。
+7. 所有真实数据、账户或实盘相关工作先做安全与合规审查。
+
+## 16. 延伸文档
+
+- [`README.md`](README.md)：产品功能和快速启动；
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)：架构和数据路径；
+- [`docs/API.md`](docs/API.md)：API 协议；
+- [`docs/DATA_PROVIDER_GUIDE.md`](docs/DATA_PROVIDER_GUIDE.md)：行情提供者接入；
+- [`docs/BROKER_CONNECTORS.md`](docs/BROKER_CONNECTORS.md)：实盘连接器与安全边界；
+- [`docs/MULTIPLATFORM.md`](docs/MULTIPLATFORM.md)：Windows/Android/iOS 交付策略；
+- [`apps/native/README.md`](apps/native/README.md)：Tauri 构建入口。