# fwa2 **Repository Path**: chill109/fwa2 ## Basic Information - **Project Name**: fwa2 - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-01 - **Last Updated**: 2026-08-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Lucky bStocks 股票奖励抽奖平台 BNB Chain 上使用 LB 平台币支付的固定概率股票奖励抽奖。本项目是 **功能版(本地 main)** 与 **nextjs-version 前端重构分支** 的合并结果:本地保留完整功能(合约、兑换后台、管理后台、API),前端采用 Next.js 新样式(轮播卡池、稀有度闪卡、卡池一览、抽奖动画)。 ## 项目结构 - `src/`:Next.js 16 前端(`src/app/page.tsx` 首页,`src/components/lbs/` 轮播/活动面板/卡池组件) - `src/lib/lbs.ts`:钱包连接、BNB 网络切换、LB 授权、quote、抽奖、链上兑换的客户端逻辑 - `server.js`:Node API 服务(端口 4173):卡池接口、兑换提交/查询、管理后台会话与审计、`/api/config`、`/api/activity` - `admin.js` / `admin.html`:管理员兑换处理后台(独立于前端,隔离部署) - `contracts/`:`StockRewardDraw.sol` 抽奖合约(Foundry) - `data/prizes.json`:56 张真实卡池(合约地址、稀有度、固定概率 BPS、数量) - `public/images/lbs/pool/`:卡牌 Logo 资源 ## 用户玩法 1. 连接钱包(浏览器钱包或演示钱包) 2. 支付平台币 LB(BNB 仅用于 Gas) 3. 选择 1-5 次,点击抽奖 4. 抽中英伟达、苹果、谷歌、黄金等奖励 5. 在“My Rewards”提交股票兑换申请 6. 等待平台审核发放 ## 本地运行 需要 Node.js 24+(Next.js 16 要求)。Windows 可直接双击 `打开本地预览.bat`,或手动执行: ```powershell # 终端 1:API 与兑换后台(必须配置至少 32 位 ADMIN_KEY) $env:ADMIN_KEY = "replace-with-a-long-random-secret-at-least-32-chars" npm run dev:api # 打开 http://127.0.0.1:4173/admin 查看管理后台 # 终端 2:Next.js 前端 npm run dev # 打开 http://localhost:3000 ``` `next.config.ts` 会把 `/api/*`、`/admin` 代理到 `API_UPSTREAM`(默认 `http://127.0.0.1:4173`),前端无需额外配置即可连接后端。若前端与 API 不同源且不使用代理,可设置 `NEXT_PUBLIC_API_BASE` 指向 API 地址。 ## 卡池数据 - 卡池保存在 `data/prizes.json`,由 `GET /api/prizes` 提供给前端;前端构建时同步生成 `src/data/stock-pool.ts` - 当前共 57 张奖励卡:Logo、股票代码、奖励数量、稀有度、固定概率和颜色均来自该数据源 - 单张概率使用 BPS 保存,全部 57 张合计 `10000 BPS`(100%) - 三档股票稀有度加金卡:Advanced 11.46%(3 张)、Mid 20%(5 张)、Low 65.54%(48 张)、Gold 3%(1 张) `StockRewardDraw.sol` 使用与数据源相同的 57 个奖项目编号和固定概率。修改卡池后必须同步修改合约概率表并重新部署,不能只改前端数据。 ## 抽奖费用 - 奖励成本:`100 LB / 次` - 平台手续费:`5 LB / 次`(5%) - 单次合计:`105 LB` - BNB:仅用于支付链上 Gas,不作为抽奖费用 合约的 `quote()` 是前端授权和支付金额的权威来源。`requestDrawBatch(uint8)` 支持 2 到 5 次抽奖在同一笔钱包交易中提交;过期未开奖订单会退回奖励成本和平台手续费。 ## 管理后台安全配置 后台默认**拒绝启动**:必须配置至少 32 位的 `ADMIN_KEY`,不再提供内置默认密钥。 | 环境变量 | 默认值 | 说明 | | --- | --- | --- | | `ADMIN_KEY` | 无(必填) | 管理员登录密钥,至少 32 位,仅用于换取短期会话令牌 | | `ADMIN_ENCRYPTION_KEY` | 由 ADMIN_KEY 派生 | 64 位十六进制(32 字节)AES-256-GCM 密钥,用于加密兑换资料敏感字段;正式环境请单独生成并备份 | | `ADMIN_SESSION_TTL_MS` | `28800000`(8 小时) | 会话令牌最长有效期 | | `ADMIN_SESSION_IDLE_MS` | `1800000`(30 分钟) | 会话闲置过期时间 | | `ADMIN_LOGIN_MAX_FAILURES` | `5` | 同一 IP 在窗口内允许的失败登录次数 | | `ADMIN_LOGIN_WINDOW_MS` | `900000`(15 分钟) | 登录失败计数窗口,超限后同一 IP 锁定 15 分钟 | | `ADMIN_API_RATE_LIMIT` | `60` | 管理接口每分钟请求上限 | | `ADMIN_IP_ALLOWLIST` | 空(不限制) | 允许访问后台的 IP/CIDR 列表,逗号分隔,例如 `203.0.113.10,192.168.1.0/24` | | `HTTPS_REDIRECT` | 生产环境默认开启 | `true` 时强制跳转 HTTPS(反向代理场景请同时设置 `TRUST_PROXY=true`) | | `TRUST_PROXY` | `false` | 在反向代理后运行时设为 `true`,才会信任 `X-Forwarded-For` / `X-Forwarded-Proto` | | `TRUSTED_PROXY_IPS` | `127.0.0.1,::1,::ffff:127.0.0.1` | 允许提供转发头的受信代理 IP 列表。仅当直连对端是这些 IP 时才读取转发头,且取**最右侧**一跳,客户端无法伪造 `X-Forwarded-For` 绕过限流或后台 IP 白名单。nginx 在前时请加入其 IP | | `AUDIT_LOG_FILE` | `data/audit.jsonl` | 审计日志文件(登录、拒绝、列表、状态变更等) | | `AUDIT_LOG_ROTATION_BYTES` | `10485760`(10MB) | 审计日志达到该大小后自动轮转 | | `AUDIT_LOG_RETENTION_FILES` | `7` | 保留的轮转审计日志份数 | | `CORS_ALLOWED_ORIGINS` | 空(同源部署) | 允许跨域访问 API 的精确 Origin 白名单,逗号分隔;留空时保持同源并拒绝跨域请求 | 生成独立加密密钥: ```powershell node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" ``` 行为说明: - 登录成功后仅返回短时 `token`,前端不再保存明文 `ADMIN_KEY`,所有管理请求使用 `Authorization: Bearer ` - 姓名、邮箱、国家、券商、手机号、收货地址和备注在磁盘上以 AES-256-GCM 加密保存,只有管理员接口解密展示 - 失败登录、IP 白名单拒绝、会话失效和状态变更都会记录到审计日志 - 变更 `ADMIN_KEY` 或 `ADMIN_ENCRYPTION_KEY` 前请先备份 `data/redemptions.json`;密钥丢失后已加密字段无法恢复 ## 上线配置 1. 部署 `contracts/src/LbsBackingVault.sol` + `StockRewardDrawV3.sol`(V4 奖池),并用管理端完成:绑定抽奖控制器 → 添加 VRF consumer → 配置全部股票 → 部署 LB 代币 / 分红引擎 / 回购金库 → **第 4 步启用 15 天只卖不买闸门(configureLaunch,必须在 PancakeSwap 创建 LB/WBNB 交易对后执行)** 2. 将抽奖合约添加为 VRF Subscription Consumer 3. 在 `.env` 配置 `DRAW_CONTRACT_ADDRESS`、`PLATFORM_TOKEN_ADDRESS` 与链上地址(v4 会从 `data/lb-pool-v4.json` 读取) 4. 配置后端 BSC RPC、同一抽奖合约地址和高强度后台密钥 5. 使用持久化磁盘保存 `data/`,并在生产代理层启用 HTTPS、访问控制、限流和备份 LB 链上分红结算所需环境变量(每日太平洋 0 点自动写份额;15 天后自动 `payoutFees → executeBuyback → 分发` 闭环): ```powershell $env:LB_REWARDS_PRIVATE_KEY = "0x..." # 服务账户私钥,须为回购金库 owner/service $env:LB_REWARDS_ENGINE = "0x..." $env:LB_REWARDS_VAULT = "0x..." $env:LB_REWARDS_DRAW = "0x..." $env:LB_REWARDS_TREASURY = "0x..." # 配置后自动执行回购闭环 ``` ```powershell $env:ADMIN_KEY = "replace-with-a-long-random-secret" $env:BSC_RPC_URL = "https://your-bsc-rpc" $env:DRAW_CONTRACT_ADDRESS = "0x..." $env:PLATFORM_TOKEN_ADDRESS = "0x..." $env:ALLOW_DEMO_REDEMPTIONS = "false" npm run build npm start # Next.js 前端(3000) npm run start:api # API 与后台(4173) ``` 后台会核对钱包、抽奖编号、卡池中的奖项目编号、链上状态和兑换资料哈希。正式环境应由多签控制合约 Owner,并在完成线下发放后调用 `markFulfilled`。 ## 检查 ```powershell npm run check # lint + typecheck + build npm run check:api # 语法检查 server/admin/app npm run test:contract ```