Appearance
挖矿配置与币种配置模块
1. 模块目标
统一维护平台支持的 POW 币种及其挖矿运行配置，形成“平台可运行什么币、每个币如何运行、哪些币可进入智能调度范围”的稳定业务输入。
本模块在当前阶段仍作为一个统一配置域存在，但内部明确拆分为两个配置子域：
- 挖矿配置
- 币种配置
其中：
挖矿配置面向当前用户的实际运行配置维护币种配置面向平台级配置资产维护，包含币种管理、矿池管理、脚本管理
这里的拆分只调整信息架构和控制台入口组织，不改变数据与配置服务作为配置主事实承载方的既有边界。
2. 模块边界
对外提供
- 挖矿配置管理
- 币种基础信息管理
- 钱包地址管理
- 矿池配置管理
- 脚本管理
- 启动参数模板管理
- 智能调度支持范围管理
- 机器到币种的适配配置管理
不负责
- 调度决策执行
- 设备命令下发
- 利润主计算
3. 一期最小业务闭环
当前一期先收敛以下最小闭环：
- 平台维护已确认支持的币种范围与矿池/脚本等平台级配置资产
- 用户维护自己的挖矿运行配置
- 平台区分“可接入运行”和“可进入智能调度”两类范围
- 设备控制服务按配置读取运行参数并下发给机器
- 调度核心服务只在“具备智能调度资格”的币种范围内做自动切换判断
这里的重点不是展开配置细节，而是先把业务口径、职责边界和后续输入输出关系定义清楚。
3.1 两个子域的职责
挖矿配置 负责：
- 当前用户可直接用于切币和运行的个人配置维护
- 运行参数与矿池关联后的实际可用配置组织
币种配置 负责：
- 平台支持币种目录
- 矿池目录
- 脚本管理
其中“脚本管理”明确归 币种配置 域，不归 挖矿配置 域，也不单独拆成第三个一级入口。
4. 核心对象
- 挖矿配置
- 币种
- 算法
- 钱包地址
- 矿池地址
- 脚本资产 / 脚本关联关系
- 启动参数包
- 智能调度资格范围
5. 一期最小配置对象
一期围绕已确认币种 xcb、qubic、门罗 收敛最小配置对象。
5.1 币种基础信息
至少需要明确：
- 币种名
- 算法
- 平台内部识别身份
用途：
- 作为配置归档、运行参数归属和调度候选范围识别的基础主对象
5.2 可运行配置
每个币种至少维护以下可运行配置：
- 钱包地址
- 矿池地址
- 启动参数
这里的“可运行配置”只回答“机器如果要运行该币种，平台至少需要准备什么”。 它不等于完整执行协议，也不等于最终前端表单结构。
5.3 智能调度资格配置
并非所有可运行币种都天然具备智能调度资格。
币种进入智能调度范围，至少要能满足以下前提：
- 有可用的钱包、矿池和启动参数配置
- 收益数据与监控模块能够提供该币种所需的核心收益输入
- 该币种具备被平台自动切换和自动执行的基本前提
这一层只定义“能不能进智能调度候选范围”，不在本模块内展开“何时切、切哪一个更赚钱”的调度策略。
5.4 机器适配关系
本模块允许维护“机器到币种的适配配置关系”，用于表达某台机器是否允许运行某个币种，或某类机器是否存在已知适配限制。
该能力当前只作为边界预留：
- 用于避免后续把机器适配规则误写进设备控制服务
- 用于支持调度模块筛选候选币种范围
当前尚未细化适配关系的结构层级和维护方式。
T0044 后，项目智能调度资格设计落在 smart_schedule_resource_eligibilities，机器与项目适配关系设计落在 smart_schedule_machine_project_adaptations。这两类结构只表达候选输入和适配边界，不表达本轮调度决策。
5.5 一期三种币的最小配置口径
当前一期已确认支持的币种为 xcb、qubic、门罗。
这三种币在当前阶段统一按同一类“最小可运行配置”收敛，至少都需要：
- 币种名
- 算法
- 钱包地址
- 矿池地址
- 启动参数
当前文档中已显式确认的是“至少维护这些配置项”，但尚未细化每个币种的字段层级、模板结构和参数校验规则。
可按如下口径理解：
| 币种 | 当前定位 | 最小可运行配置要求 | 智能调度资格口径 |
|---|---|---|---|
xcb | 一期已确认支持币种 | 需要有钱包、矿池、启动参数，且可被设备模块读取后下发 | 只有在收益侧输入可用且自动切换前提成立时，才可进入智能调度候选范围 |
qubic | 一期已确认支持币种 | 需要有钱包、矿池、启动参数，且可被设备模块读取后下发 | 只有在收益侧输入可用且自动切换前提成立时，才可进入智能调度候选范围 |
门罗 | 一期已确认支持币种 | 需要有钱包、矿池、启动参数，且可被设备模块读取后下发 | 只有在收益侧输入可用且自动切换前提成立时，才可进入智能调度候选范围 |
这里的统一口径有两个目的：
- 先把三种币都纳入同一套配置治理边界，避免不同币种走不同的“临时维护方式”
- 明确“支持接入”不等于“默认可智能调度”，防止后续把尚未具备收益输入或自动切换前提的币种强行纳入调度
5.6 当前不展开的内容
以下内容当前明确不在本模块这一阶段展开：
- 不同币种启动参数的字段级模板设计
- 钱包或矿池的多套切换策略
- 不同机器类型对应的参数差异化合成规则
- 控制台上如何展示或编辑这些配置
- 配置变更后的审批、审计和灰度流程
6. 核心流程
- 用户维护自己的挖矿配置
- 平台维护币种、矿池、脚本和支持范围
- 调度模块读取可调度币种范围
- 设备模块读取运行参数包并下发给机器
7. 对外能力
- 用户侧挖矿配置列表
- 可运行币种列表
- 智能调度支持币种列表
- 每个币种的运行参数包
- 币种/矿池/脚本/启动参数配置
8. 配置归属与使用边界
8.1 数据与配置服务
负责：
- 持有币种、钱包、矿池、启动参数和智能调度资格的主事实
- 对外提供统一配置查询能力
不负责：
- 直接向机器下发命令
- 直接决定调度策略
8.1.1 当前主事实承载范围
在一期挖矿配置与币种配置方向，数据与配置服务当前应承载的主事实至少包括：
- 用户侧挖矿运行配置
- 币种基础信息
- 钱包地址配置
- 矿池配置
- 脚本资产或脚本关联关系
- 启动参数配置
- 智能调度资格范围
- 机器与币种适配关系
这里的“承载主事实”指：
- 这些信息的权威来源应收敛在数据与配置服务
- 其它服务可以读取、缓存或聚合展示，但不应各自维护一套独立主版本
- 后续若有配置变更，也应以数据与配置服务视角为准
8.1.2 对外最小提供能力
数据与配置服务在当前阶段至少应对外提供以下类型的能力：
配置查询能力 用于控制台查看当前币种、钱包、矿池、启动参数和资格范围。
配置读取能力 用于设备控制服务和调度核心服务按需读取已确认配置，而不是各自拼装或维护配置副本。
范围判断输入能力 用于支持调度模块判断“哪些币种具备进入智能调度候选范围的前提”，以及支持设备模块判断某机器是否允许运行某个币种。
当前这里说的是“能力边界”，不是接口协议，也不是字段级 API 设计。
8.2 设备控制服务
负责：
- 读取已确认的运行参数
- 将参数转换为实际执行动作并下发给 Agent
不负责：
- 维护钱包、矿池、启动参数的主配置
- 判断某币种是否应进入智能调度范围
8.2.1 作为配置消费方的边界
设备控制服务对配置的使用应收敛在“消费已确认配置”这一层，至少包括：
- 读取某币种的可运行配置
- 读取机器与币种的适配边界
- 将读取到的配置转换为设备执行动作
但设备控制服务不应：
- 自己维护钱包、矿池和启动参数的主版本
- 为了执行方便在服务内沉淀另一套长期配置事实
- 反向决定某币种是否具备智能调度资格
8.3 调度核心服务
负责：
- 读取智能调度资格范围和运行参数
- 在候选范围内做调度判断和执行编排
不负责：
- 直接维护币种配置
- 绕过配置模块自行定义候选币种规则
8.3.1 作为配置消费方的边界
调度核心服务对配置的使用应收敛在“读取候选范围并做调度判断”这一层，至少包括：
- 读取具备智能调度资格的币种范围
- 读取候选币种的运行参数
- 读取必要的机器与币种适配关系
但调度核心服务不应：
- 在服务内维护自己的候选币种主配置副本
- 绕过数据与配置服务自行决定某个币种的资格主事实
- 把调度策略结果反向写成本模块的配置事实
8.4 平台门户服务
负责：
- 作为配置维护入口、展示入口和操作转发入口
不负责：
- 承载币种配置主事实
8.4.1 作为配置入口的边界
平台门户服务可以：
- 展示配置主事实
- 发起新增、编辑和范围调整操作
- 聚合展示配置与设备、调度状态之间的关联结果
但平台门户服务不应：
- 持有配置主版本
- 脱离数据与配置服务直接生成另一套配置副本
9. 依赖关系
- 被平台接入与控制台模块配置
- 被调度与执行编排模块读取，用于决定可切换目标
- 被设备与 Agent 管理模块读取，用于向机器下发运行参数
- 依赖收益数据与监控模块确认币种是否已有产量与价格数据
10. 对后续业务的支撑关系
10.1 对手动切币的支撑
手动切币依赖本模块提供：
- 可运行币种列表
- 对应钱包、矿池和启动参数
- 机器与币种的适配边界
如果这一层没有先收敛，后续手动切币很容易退化为“直接拼 shell 参数”，导致配置事实分散。
10.1.1 手动切币中的配置读取边界
在手动切币场景中，本模块提供的应是统一配置来源，而不是一次性临时参数。
可按如下边界理解：
- 控制台发起“目标机器 + 目标币种”的业务操作
- 数据与配置服务提供该币种的可运行配置和适配边界
- 设备控制服务消费这些已确认配置并生成执行动作
因此，本模块在手动切币链路中的职责是“提供统一配置主事实”，而不是“直接参与命令执行”。
10.2 对智能调度的支撑
智能调度依赖本模块提供：
- 可进入智能调度的币种范围
- 每个候选币种的运行参数
- 必要的机器适配边界
本模块只负责提供“可调度输入”，不负责调度策略本身。
10.2.1 智能调度资格范围的边界
在智能调度场景中，本模块负责回答的是：
- 哪些币种具备进入智能调度候选范围的资格
- 这些币种对应的可运行配置是什么
- 某台机器是否具备运行这些币种的适配前提
本模块不负责回答的是：
- 当前这一轮调度应不应该切换
- 候选币种里哪一个收益更优
- 当前是否需要冻结调度
也就是说，本模块提供的是“候选输入边界”，而不是“调度结果”。
10.2.2 候选范围与调度结果的分离
为保持服务边界稳定，一期必须明确区分两层事实：
资格范围事实 由数据与配置服务承载，回答“哪些币种可以被纳入候选范围”。
调度决策事实 由调度核心服务承载，回答“在当前收益和异常状态下，最终应切换到哪里或是否冻结”。
如果这两层混在一起，后续会把配置模块误写成调度策略模块，或把调度核心服务误扩展为配置主事实持有方。
10.3 对统一配置承载的支撑
本模块之所以需要把主事实收敛到数据与配置服务，是为了避免后续出现以下问题：
- 控制台只知道页面上的配置，设备控制服务只知道执行参数，调度核心服务只知道候选币种，三者互不一致
- 手动切币和智能调度分别维护自己的运行参数版本
- 配置变更后无法判断哪个服务中的版本才是权威事实
因此，一期在业务上应优先坚持：
- 配置主事实统一收敛
- 设备控制服务和调度核心服务按需消费
- 平台门户服务只做入口和展示
11. 约束
- 并非所有接入币种都天然支持智能调度
- 币种进入智能调度范围至少需满足产量、价格、钱包、快速自动切换等前提
- 不负责最终调度编排
- 不得把设备执行细节、shell 命令细节下沉为本模块主内容
- 不得把本模块扩展成收益计算或调度策略文档
- 不得让多个服务分别持有币种配置的主版本
12. 已知问题
- 持久化：一期表结构已收敛在
docs/数据表-v0.0.1.sql；T0015 手动切币读取链路、T0016 智能调度资格/候选边界（见smart_schedule_resource_eligibilities/smart_schedule_policy_candidatespatch）已文档化 - 当前尚未细化不同币种启动参数模板的结构层级
- 当前尚未细化机器适配关系的表达方式
- 当前尚未完全落地控制台“挖矿配置 / 币种配置”两个一级入口下的页面拆分与操作流设计
- 当前尚未细化“智能调度资格”在配置层面的审查与变更流程
- 当前尚未细化数据与配置服务对外查询和读取能力的协议层定义
- 当前尚未细化手动切币场景中配置读取能力的协议层表达
- 当前尚未细化智能调度候选范围读取能力的协议层表达
13. 最近变更
- 2026-06-02：根据 T0044 补充 Go scheduler 数据库结构设计，明确项目资格与机器项目适配分别落在
smart_schedule_resource_eligibilities、smart_schedule_machine_project_adaptations - 2026-04-30：按方案 A 将统一配置域内部拆分为 挖矿配置 与 币种配置 两个子域；明确个人运行配置归挖矿配置，币种/矿池/脚本管理归币种配置，且不改变数据与配置服务的主事实归属
- 2026-04-15：T0027 已完成：
apps/api与apps/portal-web实现三表维护能力；user_pool_configs按门户用户隔离，矿产/矿池表一期为全局共享（与任务文档一致）；详见tasks/done/T0027-币种与配置模块功能最小实现.md - 2026-06-03：T0016 已完成；智能调度资格/候选读取边界见
tasks/done/T0016-智能调度资格范围与候选币种读取边界定义.md - 2026-04-17：T0015 已完成并迁入
tasks/done/；手动切币读取链路边界已收敛 - 2026-04-15：
T0015/T0016任务文档纳入只读对齐docs/数据表-v0.0.1.sql的要求，并标注与业务对象之间的 DDL 缺口 - 2026-04-15：任务 T0012–T0014 标为完成并迁入
tasks/done/；与本文档内容一致，后续推进 T0015、T0016（配置消费链路边界定义） - 2026-04-03：根据系统骨架与需求边界生成模块文档
- 2026-04-10：补充一期最小业务闭环定义，明确可运行配置、智能调度资格边界，以及数据与配置服务、调度核心服务、设备控制服务之间的配置归属和使用关系
- 2026-04-10：补充
xcb、qubic、门罗的一期最小配置口径，明确“支持接入”与“具备智能调度资格”是两层不同边界 - 2026-04-10：补充数据与配置服务的主事实承载边界，明确配置查询、配置读取和范围判断输入三类最小提供能力，以及门户、设备控制、调度核心三方的配置消费边界
- 2026-04-10：补充手动切币中的配置读取边界，明确配置模块在该链路中提供统一配置主事实，由设备控制服务消费后执行
- 2026-04-10：补充智能调度资格范围边界，明确配置模块只提供候选输入边界，不负责收益比较、切换决策和冻结判断