平台接入与控制台模块

1. 模块目标

作为运维与负责人使用的统一正式入口，承接账号注册登录、机器管理、调度管理、挖矿配置、币种配置、告警查看、维修日志录入等操作。

2. 模块边界

对外提供

• 登录与权限入口
• email 注册与邮箱验证入口
• 机器管理控制台
• 智能调度控制台
• 挖矿配置入口
• 币种配置入口
• 告警与异常查看
• 维修日志录入与查询

不负责

• 智能调度核心策略
• 设备主状态管理
• 与 Agent 的直接通信

3. 一期配置入口边界

围绕一期挖矿配置与币种配置模块，控制台侧当前应承接的是“配置维护入口”，而不是配置主事实本身。

一期建议至少承接以下入口类型：

1. 挖矿配置入口
2. 币种基础信息配置入口
3. 矿池配置入口
4. 脚本管理入口
5. 启动参数配置入口
6. 智能调度资格范围查看或维护入口
7. 机器与币种适配关系查看或维护入口

这里的“入口”强调三件事：

• 负责把用户操作组织成可审查、可提交的业务操作
• 负责展示已有配置和变更结果
• 负责将读写请求转发给对应后端服务

控制台不因为具备编辑入口，就成为这些配置的主数据持有方。

3.1 两类一级入口的职责

挖矿配置 入口负责：

• 我的币种配置维护
• 面向手动切币与运行参数录入的个人配置维护

币种配置 入口负责：

• 币种管理
• 矿池管理
• 脚本管理

其中“脚本管理”归 币种配置 入口，不单独拆第三个入口。

4. 入口类型说明

4.1 展示类入口

用于查看当前配置事实和关联状态，例如：

• 当前平台支持哪些币种
• 某币种是否具备智能调度资格
• 某机器允许运行哪些币种

4.2 录入与编辑类入口

用于录入或调整配置，例如：

• 新增或修改钱包地址
• 新增或修改矿池配置
• 新增或修改启动参数
• 调整币种是否进入智能调度候选范围

4.3 操作转发类入口

用于把用户提交的配置变更转发到后端服务并展示结果，例如：

• 提交配置保存
• 提交资格范围调整
• 提交适配关系调整

4.4 当前不展开的入口内容

以下内容当前不在本任务中展开：

• 页面信息架构
• 表单字段设计
• 页面交互流程
• 权限细节
• 审批或灰度发布机制

5. 核心对象

• 登录会话
• email 账号
• 邮箱验证状态
• 控制台查询视图
• 用户操作指令
• 手动控制命令
• 配置维护入口
• 配置查询视图

6. 正式入口定位

一期产品中，控制台应被视为用户完成所有正式业务操作的统一入口。

这意味着：

• 用户注册、登录、邮箱验证从控制台进入
• 设备管理、配置管理、手动切币、调度启停、维修记录等正式操作从控制台进入
• 命令行工具、数据库预置和临时脚本只允许用于开发联调，不应继续作为正式产品入口

控制台作为统一入口，并不改变既有服务边界：

• 页面展示、会话承接、用户操作提交仍归平台门户服务
• 配置主事实、设备执行事实、调度状态主事实仍归对应后端服务

7. 控制台与后端服务的边界关系

6.1 与数据与配置服务

控制台负责：

• 展示币种、钱包、矿池、启动参数和智能调度资格相关信息
• 提交新增、编辑、启停或范围调整等配置操作

控制台不负责：

• 自行持久化这些配置主事实
• 自行解释配置之间的最终一致性规则

6.2 与设备控制服务

控制台可以：

• 发起手动切币或其他设备操作
• 查看操作结果和设备反馈

控制台不应：

• 在配置入口中承接 shell 参数拼装逻辑
• 在页面侧定义最终下发给 Agent 的执行细节

6.2.1 手动切币发起边界

在手动切币场景中，控制台的职责应收敛为：

• 让用户选择目标机器和目标币种
• 发起手动切币操作
• 展示切币结果和相关状态

控制台不应：

• 直接拼装钱包、矿池、启动参数并下发
• 绕过统一配置主事实直接构造执行参数
• 让手动切币走一套独立于智能调度之外的临时配置来源

6.3 与调度核心服务

控制台可以：

• 展示智能调度范围、开关状态和冻结状态
• 提交启停或范围调整类操作

控制台不应：

• 自行做调度收益比较
• 自行判断某次切换是否应执行

6.4 与账号入口的关系

控制台负责：

• 承接 email 注册、登录、登出与邮箱验证操作
• 展示当前账号是否已完成邮箱验证
• 将账号相关读写请求转发给对应 PHP API 后端

控制台不负责：

• 自行持有账号主事实
• 自行完成邮件投递或验证码校验逻辑
• 在前端绕过后端直接完成验证闭环

8. 统一技术形态约束

除矿机端 Agent 外，一期正式后端能力均应以 PHP API 形式对控制台提供服务。

这里的约束包括：

• 控制台通过 API 使用后端能力
• 账号入口、配置入口、设备管理入口、调度入口最终都落到 PHP API 后端
• Agent 保持 Go 技术栈，不受该约束影响

9. 账号入口的最小闭环

一期账号体系的最小闭环应至少包括：

1. 用户使用 email 注册
2. 平台向该 email 发起验证
3. 用户完成邮箱验证后获得正式可用账号状态
4. 用户使用 email 登录控制台

当前阶段，这里只定义最小闭环边界，不展开：

• 邮件服务商选型
• 验证码与链接协议细节
• 密码策略细节
• 更复杂的权限或多因子方案

9.1 Google 快捷登录（增量，T0070）

登录页在既有邮箱登录之外，支持 Google 快捷登录（前端 Google Identity Services 获取 id_token，后端 POST /api/auth/google/login 验签并签发与邮箱登录相同结构的会话）：

• 首次 Google 授权且 email_verified=true 时 自动注册 平台账号；Google 已验证邮箱 等价于完成邮箱验证，无需再走邮箱验证码流程
• 已绑定 Google 身份的用户可直接登录
• 同邮箱已通过密码/验证码注册且 未绑定 Google 时 不做静默绑定，接口返回 409，提示用户使用原方式登录
• 功能开关与 Client ID 通过环境变量配置：
  • 后端：BLSFLOW_GOOGLE_OAUTH_ENABLED、BLSFLOW_GOOGLE_CLIENT_ID
  • 前端：VITE_GOOGLE_OAUTH_ENABLED、VITE_GOOGLE_CLIENT_ID（未启用时登录页不展示 Google 按钮）

10. 核心流程

1. 用户登录系统
2. 查看机器、收益、调度、维修等聚合信息
3. 提交控制、配置、启停、调度相关操作
4. 将操作转发给对应后端服务
5. 返回执行结果或状态视图

11. 对外能力

• 控制台聚合查询
• email 注册与验证入口
• email 登录入口
• 手动操作提交
• 智能调度启停操作
• 配置管理入口
• 维修日志录入入口

12. 配置入口的最小业务范围

在挖矿配置与币种配置方向，控制台当前最小业务范围可理解为：

1. 能通过 挖矿配置 入口维护当前用户自己的运行配置
2. 能通过 币种配置 入口查看平台支持币种
3. 能通过 币种配置 入口查看和维护矿池、脚本、启动参数
4. 能查看和维护哪些币种进入智能调度范围
5. 能查看和维护机器与币种的适配边界
6. 能把这些操作稳定转发到对应后端服务

这里仍然不包含：

• 页面细节
• 接口字段
• 数据库存储模型
• 最终命令执行协议

10. 手动切币的最小链路定位

当前阶段，控制台在手动切币链路中的定位应理解为：

1. 用户在控制台发起手动切币
2. 控制台把“目标机器 + 目标币种”的操作意图转发给后端服务
3. 后端基于统一配置主事实读取该币种的可运行配置
4. 设备控制服务消费配置并执行切币动作
5. 控制台展示执行结果

这里强调的是：

• 控制台负责“发起和展示”
• 不负责“拼装和执行”

13. 依赖关系

• 依赖设备与 Agent 管理模块提供机器状态与控制能力
• 依赖挖矿配置与币种配置模块提供币种、矿池、钱包、脚本、启动参数
• 依赖收益数据与监控模块提供产量、价格、功耗、利润展示
• 依赖调度与执行编排模块提供调度开关、冻结状态、执行结果
• 依赖维修记录模块提供日志写入与查询
• 依赖 PHP API 后端提供账号注册、登录和邮箱验证能力

14. 约束

• 只做入口、展示、聚合、转发
• 不直接持有调度主状态
• 不直接与 Agent 通信
• 不直接持有币种、钱包、矿池、启动参数等配置主事实
• 不承载调度资格判断逻辑
• 不承载设备执行细节和 shell 运行细节
• 是用户完成正式业务操作的统一入口
• 不得将数据库预置、命令行脚本或临时接口继续作为正式产品入口

15. 已知问题

• 当前尚未展开页面结构与操作流设计
• 当前已进入“用户生成设备注册 token -> 安装 Agent -> 设备注册”的后端链路阶段，但控制台页面和正式操作入口尚未实现；在控制台未落地前，联调阶段通过数据库预置或外部写入 token
• 当前尚未完全落地“挖矿配置 / 币种配置”两个一级入口下的页面层组织方式
• 当前尚未细化配置维护入口与权限模型之间的关系
• 当前尚未细化 email 注册、登录和邮箱验证的页面流程与后端协议
• 当前尚未细化账号体系与设备注册 token 管理入口之间的联动边界

16. 最近变更

• 2026-04-03：根据系统骨架与服务边界生成模块文档
• 2026-04-08：为正式设备注册流程补齐后端 token 主链路，控制台侧后续需承接 token 的生成、作废与删除入口
• 2026-04-08：移除设备控制服务仓库内的内部 token 工具，进一步明确 token 生成职责归控制台系统
• 2026-04-10：补充控制台侧币种与挖矿配置入口边界，明确控制台只负责配置入口、展示和操作转发，不持有配置主事实，也不承载设备执行细节与调度策略逻辑
• 2026-04-30：控制台配置域按方案 A 调整为 挖矿配置 与 币种配置 两个一级入口；其中个人运行配置归挖矿配置，币种/矿池/脚本管理归币种配置
• 2026-04-10：补充手动切币发起边界，明确控制台在手动切币场景中只负责发起操作与展示结果，不负责拼装执行参数或直接下发 shell 细节
• 2026-04-10：补充统一正式入口约束，明确控制台是用户完成所有正式业务操作的统一入口；除 Agent 外的后端统一以 PHP API 提供能力；账号体系采用 email 注册登录并包含邮箱验证闭环
• 2026-04-13：补齐控制台侧设备注册 token 管理最小闭环，登录用户可在控制台中创建、查看、作废和删除注册 token；PHP 账号服务负责承接入口并把 token 主事实写入设备控制服务实际识别的 device_registration_tokens
• 2026-04-13：补齐控制台设备管理列表最小入口，登录用户可查看自己名下设备的基础状态、IP、硬件容量和最近功耗/系统指标摘要；当前仍不包含设备控制动作
• 2026-04-13：完成 PHP 账号服务的 Microframe API 风格代码结构重构，入口与路由从单文件条件分发收敛为 public/index.php + router/api.php + lib/Route.php + app/Controllers 结构，既有账号与设备管理最小接口语义保持不变
• 2026-04-13：控制台账号相关业务逻辑迁入 services/api，统一由 services/api 承接 auth、device-registration-tokens 与 machines 接口；账号主库连接改为 MySQL 环境变量配置
• 2026-04-14：登录后会话路由收敛为 /console/* 统一壳层（侧栏分组、顶栏标题与面包屑）；总览页提供 KPI、示意趋势与最近设备表，列表页采用说明区 + 卡片内表格；币种/调度/维修为占位导航
• 2026-04-15：T0027 落地「币种与配置」：/console/coin-config（侧栏「配置」分组），对接 GET/POST/PUT /api/mineral-resources、/api/mineral-pools、/api/user-pool-configs（含删除用户配置）；旧路径 /console/coming/coin-config 重定向至新路由
• 2026-04-14（补充）：注册、登录、邮箱验证页与控制台对齐为深色 SaaS 双栏 + portal-card 表单区，整站启用 html.dark
• 2026-06-16：账号入口按 UI/premium_white_tech* 设计升级为白色科技风；登录、注册与重置密码页按设计稿 HTML 原生结构还原；App.vue 按路由切换主题，账号入口使用白色主题。
• 2026-06-16：控制台会话后壳层按 UI/账号基础信息/code.html 切换为浅色侧栏/顶栏框架，账号基础信息页按设计稿还原；左侧导航按已确认映射保留跳转，未确认项暂留空。
• 2026-06-16：/console/billing/seats 按 UI/订阅与席位/code.html 迁移，订阅购买/取消/恢复/减席与邀请摘要/记录继续走既有 PHP API；原席位与设备绑定/释放拆至 /console/billing/seat-activation；新增 /console/account/security 按 UI/安全设置/code.html 迁移，并保留注销账号危险区。
• 2026-04-14：设备列表页接入集群运维维度：apps/api 提供集群列表/创建/删除、machines 支持 cluster_id 筛选及单台设备集群分配；数据使用设备库表 clusters、machine_cluster_rels（与数据表文档一致），不改变 Agent/设备控制协议
• 2026-04-14：设备列表支持多选批量设置集群（POST /api/machines/batch-cluster）、设备详情页 /console/machines/:id（GET /api/machines/{id} 只读聚合硬件与指标）；发送 Shell 仅为占位弹窗/禁用按钮，不发起远程执行
• 2026-04-17：设备列表改为展示最近 1 小时算力趋势图（替换“设备编码”列，无数据为空）；设备详情页补齐基于 metric_miners.hashrate 的完整算力图表，并支持 1h / 6h / 24h / 7d 时间范围切换（默认 24h）；算力事实仍由设备控制服务持有，控制台只读聚合展示
• 2026-04-20：设备列表页新增设备标签运维维度：apps/api 提供标签列表/创建/删除、machines 支持 tag_id 单标签筛选、单台 PUT /api/machines/{id}/tags 与批量 POST /api/machines/batch-tags；数据使用设备库既有表 tags、machine_tag_rels，保持标签为控制台侧运维标记，不进入 Agent 协议与设备主事实
• 2026-05-27：设备列表页改为首批最多加载 500 条设备，并在滚动到底部时继续分页续载；当前复用既有 GET /api/machines?page=&per_page= 门户接口，不改变设备状态归属与 Agent/设备控制协议，优先缓解上千设备时的前端首屏渲染卡顿
• 2026-05-28：GET /api/machines 后端第一阶段优化：默认分页路径改为 SQL 先分页，页内批量补集群/标签/最新指标/Redis 心跳；status=online/offline 与依赖最新指标或 Redis 心跳的排序场景暂保留保守回退，以保持现有展示口径不变
• 2026-06-18：T0075 分时电价迁出智能调度独立页，改在 /console/clusters 与设备列表「管理集群」创建/编辑时配置；移除 /console/smart-schedule/tariffs；策略详情不再选择 tariff_id，profit_guard readiness 提示缺失集群电价
• 2026-06-05：T0068 智能调度门户 Phase 2：分时电价（原 /console/smart-schedule/tariffs，已由 T0075 迁至集群管理）、调度资格、策略时间窗与基准只读 Tab；PHP API /api/smart-schedule/time-windows|resource-eligibilities|benchmarks
• 2026-06-05：T0067 智能调度门户 Phase 1：/console/smart-schedule 策略列表与详情（参数、候选/设备范围、启停/解冻、dry-run/execute、SSE 实时日志、tick 决策历史）；PHP API /api/smart-schedule/policies/* 聚合读写并代理 Go scheduler tick/SSE；新策略默认停用
• 2026-06-15：T0070 登录页 Google 快捷登录（GIS + 后端 id_token 验签）；首次授权自动注册、已验证邮箱免验证码；同邮箱密码账号冲突 409；环境变量 BLSFLOW_GOOGLE_* / VITE_GOOGLE_*

17. 会话后壳层与导航（实现口径）

• 会话前：/login、/register、/reset-password、/verify 使用 AuthLayout，采用白色科技风品牌区 + 表单卡片，设计来源记录在 docs/ui-upgrade-log.md。
• 会话后：/console 嵌套路由，根布局承担导航与顶栏；子路由包括 overview（总览）、device-tokens、machines 及 coming/* 占位页。
• 主题：App.vue 按路由切换根节点主题；/console 与 /dashboard 启用 Element Plus 深色 CSS 变量（html.dark），账号入口启用 html.auth-light。
• 占位：「即将开放」菜单对应页面仅展示说明，不冒充已接入后端能力。