智研星河 InvestEd Lab

AI × 教师协同的多租户仿真投资者教育平台。

智研星河 InvestEd Lab 面向中学、大学通识课、财经素养社团与机构投教场景，把实时行情仿真、AI 市场叙事、教师运营管理、学生交易实践和复盘评价放在同一个闭环里。当前版本进一步提供 SaaS 多租户运营、租户前端交付和可选 iframe 免登接入；它不是一个单纯的模拟炒股小游戏，而是一套可部署、可运营、可调参、可复盘的投资者教育实验室。

本项目用于金融素养与投资者教育，不提供真实证券投资建议。

平台定位

维度	设计目标
教学对象	学生、初学投资者、财经素养课程参与者
核心模式	AI 生成市场叙事 + 教师人工干预 + 学生仿真交易 + 数据化复盘
市场环境	可配置虚拟公司与板块、实时价格、宏观事件、财报季、新闻冲击
教学闭环	观察市场 → 做出决策 → 承担结果 → 记录反思 → 教师讲评
SaaS 形态	运营方统一托管后端与 SaaS 控制台，租户独立激活、配置、交付或嵌入前端
技术形态	React/Vite 双前端 + Node/Express 后端 + 共享仿真引擎 + MySQL + Socket.IO

当前仓库以 SaaS 租户交付版 为主：平台运营方管理租户、凭证、引擎、用户上限和目录配置；租户使用 License Key 激活，通过 API Key 识别租户，并部署、直接使用或嵌入学生前端。整套系统交付给客户自部署的模式是另一种交付形态，详见 TENANT-HANDOVER-DELIVERY.md。

核心亮点

AI 市场叙事中枢

• 支持 OpenAI-compatible 与 Anthropic Messages 风格的 HTTP 接口。
• 可生成市场新闻、行情分析、机构行为、参数建议和教学叙事。
• 支持牛市、熊市、震荡、反弹、泡沫、危机、算法驱动等市场风格预设。
• 内置限流、队列、超时与失败兜底；未配置 AI 或调用失败时，市场仍按内置规则运行。

教师共创驾驶舱

• 教师可以暂停或恢复行情，手动触发新闻、宏观事件和黑天鹅事件。
• 支持班级统计、学生管理、账户重置、冻结交易、角色权限与注册控制。
• 可调节波动率、情绪、流动性、交易成本、价格、新闻与算法参数。
• 支持维护股票、板块和新闻模板，并控制教学界面是否直接展示情绪或新闻倾向。

仿真交易实验室

• 实时行情推送，学生可观察指数、板块、个股、新闻与持仓变化。
• 模拟 T+1、涨跌停、手续费、滑点、融券保证金、持仓成本和收益曲线等机制。
• 支持个股详情、买卖与挂单、资产分析、投资日记、排行榜和交易复盘。
• 引入黑天鹅、财报、政策、通胀、利率、板块轮动与产业链传导等市场扰动。

学习成长系统

• 投资知识问答、每日任务、成就徽章、交易比赛与价格预测。
• 排行榜、社区动态和盲盒作为辅助激励，服务于学习过程而非替代教学目标。
• 投资日记沉淀交易理由、错误模式和复盘素材。
• 教师可将系统数据转化为课堂讨论、案例复盘和风险教育。

SaaS 租户交付

• 独立的 saas-admin/ 运营控制台用于创建、暂停、恢复和管理租户。
• 每个租户拥有隔离的用户、业务数据、参数、目录和 TenantEngineBundle 市场引擎。
• License Key 用于首次激活和租户管理员登录；X-API-Key 用于识别业务请求所属租户。
• REST 受保护操作同时使用用户 JWT；实时连接使用租户命名空间 /t/<tenantId>。
• 支持租户域名白名单、用户上限、凭证轮换和引擎启停。
• 支持直接使用交付前端、iframe 嵌入或租户自研前端三种接入方式。

简单 iframe 嵌入不等于单点登录。可选免登流程由租户后端创建默认 120 秒有效、仅能消费一次的短码；API Secret 只能保存在租户服务端，绝不能写入浏览器代码、公开配置或 iframe URL。完整流程见 SSO-EMBED-INTEGRATION-SAAS.md。

功能矩阵

模块	能力
行情与市场	市场指数、板块轮动、市场温度计、恐惧贪婪指数、宏观线索、财报与新闻
交易与资产	买入、卖出、挂单、T+1、涨跌停、费用、滑点、融券、持仓与资产曲线
AI 引擎	新闻生成、行情分析、机构动作、参数建议、市场风格控制、规则兜底
教学运营	学生管理、角色权限、邀请码、批量导入、班级统计、比赛与参数管理
学习任务	知识问答、每日任务、价格预测、投资日记、成就徽章、社区动态
风险教育	黑天鹅、市场崩盘/暴涨、流动性、泡沫、危机与政策冲击场景
SaaS 运营	租户创建、License 激活、凭证轮换、状态与配额、引擎生命周期、操作日志
租户接入	交付前端、iframe、一次性短码免登、自研前端、域名白名单
实时通信	默认 Socket.IO 命名空间与租户命名空间，推送价格、新闻、成就和通知
持久化	MySQL 存储租户、凭证哈希、用户、交易、配置、日志与 SSO 短码

技术架构

stock-simulator/
├── client/                         # 租户/学生端：React 18 + TypeScript + Vite
│   └── src/
│       ├── App.tsx                 # License 初始化、认证、路由与主应用壳
│       ├── pages/                  # 行情、持仓、问答、比赛、教师后台等
│       ├── hooks/                  # Socket.IO 与前端状态
│       └── api/                    # 租户 REST API 封装
├── saas-admin/                     # 平台运营控制台：React + Vite
├── server/                         # Express + Socket.IO SaaS 后端
│   └── src/
│       ├── index.ts                # 非租户路由、租户路由与静态资源入口
│       ├── engine/
│       │   ├── TenantEngineBundle.ts
│       │   └── tenantEngineRegistry.ts
│       ├── middleware/tenant.ts    # X-API-Key、来源域名和租户状态校验
│       ├── routes/                 # SaaS、License、SSO、交易与管理 API
│       ├── sockets/                # 默认及 /t/<tenantId> 实时命名空间
│       ├── services/               # AI、邮件及业务服务
│       └── store/mysql.ts          # 多租户 MySQL 持久化
├── packages/engine/                # 共享市场仿真与教学机制引擎
│   └── src/
│       ├── data/                   # stocks/sectors/newsTemplates 配置
│       ├── market.ts               # 行情主循环
│       ├── aiEngine.ts             # AI 市场叙事与调控
│       ├── news.ts                 # 新闻与事件
│       └── blackswan.ts            # 极端事件
├── scripts/                        # 构建、打包和租户交付脚本
├── TENANT-HANDOVER-SAAS.md         # SaaS 租户交接
├── SSO-EMBED-INTEGRATION-SAAS.md   # iframe 免登接入
└── README.html                     # 独立维护的交互式产品文档

关键边界：

• TenantEngineBundle 封装单个租户的市场、新闻、任务、比赛和其他运行态引擎。
• tenantEngineRegistry 负责租户引擎的创建、查找和释放。
• requireTenant 根据 X-API-Key 建立租户上下文，并校验租户状态与请求来源。
• MySQL 保存租户配置、凭证哈希、用户与业务数据；各租户仿真运行态通过独立引擎包管理。
• 默认行情目录位于 packages/engine/src/data/，字段说明见 packages/engine/src/data/README.md。

快速启动

环境要求：

• Node.js >= 18
• npm
• MySQL >= 8.0

git clone <your-authorized-repository-url>
cd Stock-Simulator
npm install
cp server/.env.example server/.env

创建数据库：

mysql -u root -p -e "CREATE DATABASE stock_simulator CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

编辑 server/.env，至少设置数据库连接、两个 JWT 密钥、允许来源和 SaaS 管理员密码哈希，然后启动：

npm run dev

npm run dev 同时启动后端、租户前端和 SaaS 运营控制台。Vite 若发现默认端口被占用会选择其他端口，请以终端输出为准；后端默认监听 http://localhost:3000。

关键配置

以 server/.env.example 为准，下面只列出主要配置组：

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=
DB_NAME=stock_simulator
DB_POOL_SIZE=10

# Security
JWT_SECRET=<strong-random-user-jwt-secret>
SAAS_JWT_SECRET=<different-strong-saas-jwt-secret>
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:4000,http://localhost:4173
PUBLIC_APP_URL=http://localhost:4173
BCRYPT_SALT_ROUNDS=10

# Initial application super admin (optional, created when all three are set)
SUPERADMIN_NICKNAME=admin
SUPERADMIN_EMAIL=admin@example.com
SUPERADMIN_PASSWORD=<strong-initial-password>

# SaaS operator login
SAAS_ADMIN_USER=saas_admin
SAAS_ADMIN_PASS_HASH=<bcrypt-hash>

# Optional AI integration
AI_BASE_URL=
AI_API_KEY=
AI_MODEL=<provider-model-id>
AI_MAX_TOKENS=1024
AI_RATE_LIMIT=30
AI_RATE_WINDOW=600000

安全与配置说明：

• JWT_SECRET 与 SAAS_JWT_SECRET 必须使用不同的高强度随机值。
• SAAS_ADMIN_PASS_HASH 只接受 bcrypt 哈希，不应填写明文密码。
• ALLOWED_ORIGINS 是浏览器 API 与 Socket.IO 的来源白名单；PUBLIC_APP_URL 用于生成可信 OAuth 回调跳转。
• AI_BASE_URL 可填写 OpenAI-compatible /v1 或 /v1/chat/completions 地址，也可填写 Anthropic 主机或 /v1/messages 地址。
• AI 地址或密钥为空时，服务跳过外部 AI 调用并使用内置市场规则。
• SMTP、第三方 OAuth、交易成本、初始资金、成就和比赛配置见 server/.env.example。

常用命令

任务	命令	说明
安装依赖	npm install	安装根工作区，并通过 postinstall 安装 saas-admin
本地开发	npm run dev	启动 server、client、saas-admin
全部测试	npm test	运行 server 与 client 测试
常规构建	npm run build	构建 engine、server、saas-admin；不包含租户 client
构建租户前端	npm run build:client	单独构建 client/dist
完整构建与打包	npm run build:all	执行 scripts/build.sh，构建全部应用并生成交付物
启动已构建后端	npm start	启动 server/dist/index.js
SaaS 前端集成包	npm run build:client && bash scripts/build-delivery-saas.sh	先构建最新租户前端，再生成不含后端源码的 SaaS 交付包
完整交付包	bash scripts/package-all.sh	重新安装依赖、构建全部子项目并汇总完整交付包

npm run build 不会构建租户前端。需要完整产物时使用 npm run build:all；只更新租户前端时使用 npm run build:client。

部署摘要

SaaS 平台运营方

npm install
npm run build:all

scripts/build.sh 会构建引擎、后端、SaaS 控制台和租户前端，并在 dist/ 下生成：

• tenant-delivery.tar.gz：租户前端交付包。
• saas-platform/：运营方后端、引擎、SaaS 控制台与环境变量模板。

后端由平台运营方统一运维。租户开通、凭证交接、域名白名单和验收步骤见 TENANT-HANDOVER-SAAS.md。

SaaS 租户前端集成包

npm run build:client
bash scripts/build-delivery-saas.sh

该脚本会复用现有 client/dist，因此先执行 npm run build:client 以避免打包旧产物。生成结果只包含前端及集成文档，不包含后端源码；它假设后端继续由平台运营方托管。iframe 复用租户登录态时，按 SSO-EMBED-INTEGRATION-SAAS.md 由租户后端创建一次性短码。

完整自部署交付

完整前端、后端和数据库均由租户管理的交付方式，不使用 SaaS License/API Key/API Secret 流程，具体差异见 TENANT-HANDOVER-DELIVERY.md。当前租户引擎是进程内运行态，生产后端必须使用单实例进程，禁止 PM2 cluster 或多副本部署；本仓库暂未提供可直接使用的 Docker Compose 部署文件。Nginx 反代和数据库备份可参考 DEPLOYMENT.md，但其中旧的 PM2 cluster 与 Docker 示例不适用于当前版本。

使用 Nginx 或其他反向代理时，必须支持 Socket.IO 的 WebSocket 升级：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;

API 速览

当前 SaaS 版 API 分为非租户入口和租户作用域入口：

认证层	典型路径	用途
公开健康检查	GET /api/health	服务健康状态
SaaS 运营方 token	/api/saas/*	登录、仪表盘、租户、状态、凭证和引擎管理
License 流程	/api/license/*	激活、状态检查、租户管理员登录、API 凭证校验
X-API-Key	GET /api/tenant/validate、公告、新闻等	建立并验证租户上下文
X-API-Key + 用户 JWT	/api/stocks、/api/trade、/api/portfolio、/api/quiz 等	用户行情、交易、资产和学习功能
X-API-Key + 管理权限	/api/admin/*	教师与租户业务管理
X-API-Key + X-API-Secret	POST /api/embed-sso/code	仅由租户服务端创建免登短码
X-API-Key + 一次性短码	POST /api/embed-sso/exchange	iframe 页面换取用户 JWT

常用 License 入口：

方法	路径	用途
POST	/api/license/check	检查 License 与激活状态
POST	/api/license/activate	首次激活并初始化租户管理员
POST	/api/license/login	租户管理员登录
POST	/api/license/validate-api	初始化阶段校验 API Key 与 API Secret

认证关系：

• License Key 是租户授权与管理员初始化凭证，不是普通用户密码。
• X-API-Key 标识租户，但不能替代用户 JWT 或管理员权限。
• Authorization: Bearer <user JWT> 用于用户级受保护操作。
• X-API-Secret 仅用于服务端或特权初始化流程，绝不能交给普通浏览器业务代码。

Socket.IO：

命名空间	鉴权	用途
/	用户 JWT	默认实例实时连接
/t/<tenantId>	租户 API Key + 用户 JWT	SaaS 租户隔离的价格、新闻、成就与通知

完整租户接入契约见 TENANT-HANDOVER-SAAS.md 与 SSO-EMBED-INTEGRATION-SAAS.md。

适用场景

• 学校金融素养课程与大学通识课
• 投资者教育公开课和机构投教项目
• 社团模拟交易活动与财经训练营
• 风险教育、行为金融案例课和教师共创课堂
• 校内财经竞赛、阶段性测评与交易复盘
• 面向多所学校、培训组织或合作机构的统一 SaaS 运营
• 嵌入现有校园平台、学习平台或会员系统的投教模块

合规与版权

• 本系统为教学仿真平台，不构成任何真实投资建议。
• 虚拟公司、行情和事件用于教学模拟，不应被解释为真实证券、收益承诺或交易指引。
• 仓库 package.json 标记为 UNLICENSED，未经授权不得复制、分发、转售或商用部署。
• 真实部署时请按所在地区的教育、未成年人保护、数据与隐私要求配置账号、邮件、日志、OAuth 和数据库权限。
• SaaS 运营方与租户应分别妥善管理 JWT 密钥、License、API Secret 和管理员凭证，并执行最小权限、来源白名单和凭证轮换。