返回主页

新火平台全模块汇总详细开发规划

本文件为单文件合并版详细规划，不再按“四个阶段”拆成四份文档，而是按业务能力、系统边界、研发职责和上线路径进行统一展开。

目标不是做一份概要，而是直接形成可供产品、后端、前端、测试、运维共同执行的开发任务底稿。所有已提出的需求点，必须能在下方找到对应模块、对应职责、对应数据结构、对应接口、对应权限和对应验收口径。

规划目标 形成一份真正可执行的全量研发拆解文档

覆盖范围 基础架构、卡商端、托管模式、C端大厅、开放 API、财务闭环

角色划分 按前端、后端、测试三个角色拆分任务与验收

执行要求 细化到字段、按钮、状态、接口、任务流和验收标准

1. 总体目标与设计原则 2. 基础底座与数据体系 3. 卡商端重构与菜单体系 4. 上卡方式与设备接入 5. 号码管理与统计分析 6. 项目管理与专属对接 7. 托管模式与财务体系 8. C端用户系统与开放 API 9. 权限、风控、并发与审计 10. 联调、测试、迁移与上线 11. 总体验收口径 12. 开发任务 Checklist

1. 总体目标与设计原则

数据模型重构业务逻辑重构前端交互重构联调验收重构

本次新火平台改造，本质上不是“加几个页面”，而是把现有系统从单平台、弱配置、弱隔离、弱财务模型，升级成一个具备多来源上卡、多项目映射、多用户接码、多角色分账、多终端开放的完整平台。

1.1 本次改造必须同时达成的业务目标

目标	明确要求	完成后的可见结果
1. 建立新火独立项目主数据	项目必须以新火自己的主项目表为核心，不再依赖“所属平台”字段驱动主流程。	所有页面、接口、统计、取号流程都先识别新火项目，再按需要读取火狐狸、推码、沃玛、sms 的映射信息。
2. 建立多平台项目映射能力	同一个新火项目要能挂接多个外部平台项目 ID，并支持持续维护和补录。	后台项目管理页可查看和维护各平台映射 ID，后端同步逻辑可以平滑读取这些映射。
3. 补齐项目关键词与搜索能力	除了项目名称，还要维护关键词、别名、搜索关键字，因为火狐狸项目很多，仅靠项目名不足以支撑专属对接和项目管理。	创建专属对接、服务项目检索、卡商项目勾选时，都能通过项目 ID、项目名、关键字快速定位项目。
4. 重构卡商默认配置中心	原“用户配置”必须改造成真正的“卡商配置中心”，页面直接显示表单，不再保留旧列表式配置交互。	卡商打开页面后直接编辑默认配置，并能清楚知道哪些配置是全局默认值、会应用到哪些上卡方式。
5. 建立单设备覆盖配置机制	卡池、网关、猫池、第三方批次等每条上卡记录都要允许独立配置；未独立配置的字段自动继承卡商默认配置。	同一卡商的不同设备可以使用不同策略；系统取配置时能按“设备配置优先，默认配置兜底”的规则生效。
6. 建立上卡前强校验机制	如果卡商既没有填写默认配置，也没有设备独立配置，则系统必须阻止上卡，不能让不完整配置的号码进入业务流。	无效配置不会进入正式号码池，减少后续异常号码、错误路由和计费争议。
7. 重构卡商端菜单与权限结构	上卡方式、号码管理、火团卡商中心、数据统计、ESPS、业务配置、财务管理等菜单必须重新编排，并按管理员、卡商、用户角色限制页面和按钮可见性。	菜单分组清晰、权限边界明确，管理员页面不会暴露给普通卡商，普通卡商也能快速找到核心功能。
8. 打通多来源上卡方式	现有卡池、网关、比比熊要继续可用，同时新增猫池上卡、第三方上卡、API 上卡、sms 上卡等入口。	不同来源的号码都能进入新火平台，并最终被统一检索、统一统计、统一分发。
9. 建立统一号码主域与状态模型	不管号码来自哪种上卡方式，都必须进入统一的号码主域，具备统一的在线状态、项目状态、回码状态、导出状态、冻结状态。	号码列表、供卡明细、取号接口、专属对接、托管模式都能基于同一套号码状态运行。
10. 建立专属对接与混池取号机制	客户 API 取号时不显式传专属对接码；系统应根据用户对某项目加入的专属对接关系，自动决定从大厅取号还是从专属池取号；多个专属对接要混合随机取号。	专属对接真正成为项目级路由规则，而不是额外手工参数；客户脚本迁移成本低，卡商资源池也能按授权共享。
11. 建立托管模式全闭环	托管模式必须覆盖菜单隔离、项目勾选、平台自动接管、托管号标记、后台统一运营、收益入账、退出提醒。	卡商开启托管后，不再手工对接第三方平台，平台可直接使用托管号做业务并给卡商分润。
12. 建立双账户财务体系	至少拆分消费余额和可提现收益两套账户，并打通卡密充值、转码费扣费、托管分润、专属对接收入、提现申请审核等环节。	消费资金和收益资金分开管理，账单清晰，提现逻辑不再和消费逻辑混在一起。
13. 建立 C 端网页业务闭环	要提供完整的用户页面，包括服务项目、专属对接、接码业务、数据统计、API 对接、自助充值、使用帮助等。	不依赖 API 的普通用户也能完整使用新火平台。
14. 建立开放 API 并兼容火狐狸使用习惯	用户 API 和卡商 API 的语义、参数、返回结构要尽量贴近火狐狸生态，降低现有脚本迁移成本。	已有用户脚本尽量少改即可迁移到新火。
15. 建立高并发与延迟结算底座	取号、释放、冻结、反馈、自动成功结算、卡密核销、提现审核等关键流程必须具备锁、幂等、延迟任务和补偿机制。	系统不会出现号码超卖、重复计费、冻结不释放、重复核销等严重问题。
16. 完成页面国际化与文案统一	所有新页面、新按钮、新状态、新 Tooltip、新错误提示都要纳入国际化检查，不能只开发功能不补文案。	上线前所有页面语言一致，避免出现中英文混杂、旧词未改、新字段无翻译的情况。

1.2 关键业务原则

规则主题	必须遵守的业务规则
大厅取号	公共大厅取号不扣卡商的钱，只收用户端通道费 0.03；与专属对接模式分开核算。
专属对接码	同一个项目可以创建多个专属对接码；同一个项目如果用户加入多个专属对接，取号时按授权池混合抽取。
禁用与暂停	“禁用/未禁用”只能由专属对接的创建卡商控制；“暂停接入/继续接入”是加入方自己的参与状态控制，两者不能混淆。
卡商项目限制	卡商配置可限制“接新火”和“托管模式”下做哪些项目，但无法强行限制外部第三方平台自身的业务逻辑，sms 保持独立选择逻辑。
托管模式	托管模式只能全局开关，不能按单设备单独开关；开启后要隐藏第三方对接配置并提醒卡商选择项目对接。
财务账户	卡商系统内至少要拆成“消费余额”和“可提现收益”两套账户，严禁混在一个余额字段里。
API 反馈计费	开通反馈计费权限时，收到验证码后先冻结用户资金，等反馈成功再结算给卡商；失败则退回；5 分钟未反馈按成功处理。

1.2.1 火狐狸参考机制：客户取号逻辑

客户通过 API 使用项目 ID 取号，API 请求中不体现专属对接码。
如果客户某个项目没有加入专属对接，则后台根据项目 ID 从大厅公共号池取号。
如果客户某个项目加入了一个专属对接，则客户仍然只传项目 ID，后台自动改为从这个专属对接对应的号池取号。
如果客户某个项目加入了多个专属对接，则后台在该项目已授权的所有专属对接号池中随机混合取号，而不是固定取某一个对接码。

1.2.2 火狐狸参考机制：卡商端上号逻辑

卡商必须先在火团卡商中心勾选自己要做的项目；勾选后，上号进入对应项目的号池，用户才能取到这些号码。
如果某个项目加入了专属对接，并且卡商开启了这个项目，则该项目上来的号码会自动进入对应专属对接的池子，而不是继续只留在大厅池。
如果同一个卡商有多个专属对接同时指向同一个项目，则这些专属对接底层看到的是同一份项目号码视图。假设存在 a、b 两个专属对接，a 中和 b 中的号码是同步的；a 中某个号被做了业务，b 中就不能再取到这个号，因此 a 和 b 的在线数量、当前可用数量应保持一致。

1.3 业务逻辑答疑

问题点	统一解释	研发落地要求
专属对接里显示的“卡商数/接入人数”是什么意思	一个专属对接码可以被多个主体共享使用，创建卡商还可以授权其他卡商加入，因此这里本质上统计的是当前加入并处于可接入状态的主体数量。	前端展示时建议统一命名为“当前接入人数”或“当前接入主体数”，避免误解成“仅卡商数量”。
禁用与暂停接入是否一样	不一样。禁用是对接池级别总开关，由创建方控制；暂停接入是某个加入方临时不参与，由加入方自己控制。	后端状态必须拆成两个维度，不能用一个字段混表示。
同一项目加入多个专属对接后怎么取号	混在一起取号，不按卡商硬隔离。	取号服务必须按“用户有效加入的对接集合”聚合资源池，而不是只取一个对接码。
为什么卡商端也有“加入专属对接”	因为卡商也可能加入别的卡商创建的专属对接码，形成共享供卡关系。	成员关系表不能只支持 C 端用户，也要支持卡商主体。
同一卡商同一项目能否创建多个专属对接	可以，允许价格不同，也允许价格相同但分开统计。	唯一约束应限制对接码本身唯一，而不是“卡商 + 项目”唯一。
大厅取号和专属对接的核心差异	大厅取号仅收用户通道费 0.03，不扣卡商；专属对接则按卡商设置收入进行分账。	财务结算服务必须按场景类型分支处理，不可混算。

1.4 研发角色分工建议

前端

负责菜单重排、卡商配置表单化、号码列表六大 Tab、专属对接页、统计页、财务页和 C 端页面落地。
负责字段更名、Tooltip 展示、状态字典呈现、按钮权限显隐、国际化补漏。
负责把复杂交互做成可复用组件，避免同类页面重复开发。

后端

负责项目体系、号码主域、配置继承、专属对接、托管模式、财务双账户、开放 API、锁与延迟任务。
负责数据库迁移、状态机、权限拦截、幂等控制、外部设备接口和报表聚合。
负责保障取号、计费、结算、回滚这些关键链路的正确性和可补偿性。

测试

负责功能回归、并发压测、权限渗透检查、财务核对、异常补偿验证和国际化检查。
重点覆盖号码超卖、冻结不释放、重复结算、重复核销、专属对接混池错误、托管模式绕过等风险点。
负责上线前按 checklist 做逐项勾验，并形成问题闭环。

重要说明： 当前仓库内主要是后端 Java 模块，未直接看到完整前端工程目录。因此本文中涉及的前端任务，默认按现有独立前端项目或后续新建前端仓执行，但接口设计、权限模型、页面结构必须与本仓后端改造同步推进。

2. 基础底座与数据体系

数据库后端缓存/队列/任务

2.1 Redis 与并发底座

后续所有的取号、占号、冻结、回码、反馈、释放、延迟自动结算，本质上都依赖一套高并发基础设施。如果这里做得不严，后面所有页面都会出现“看似能用，实则不可控”的问题。

层级	详细任务
依赖接入	在 Maven 中引入 Redis 组件和 Redisson；在公共配置中增加 Redis 连接、线程池、序列化策略和 key 前缀规范；统一定义缓存键命名规则，避免后续不同功能随意拼 key。
锁机制	提供统一的 Redis 锁工具或注解；支持指定 key、超时时间、重试策略；所有取号、退号、冻结结算、收益发放、卡密核销、提现审核必须显式加锁。
队列与延迟任务	用于 5 分钟自动计费、号码过期下线、项目释放重投、心跳超时检查、短信发送任务轮询等；可以用 Redis 延迟、Quartz 或消息队列，但必须保证至少一次触发并可补偿。
缓存对象	号码候选池、在线状态、专属对接实时供卡数、项目缓存、卡商配置缓存、API token 信息、冻结订单等待态等都应优先缓存，而不是高频直查数据库。

2.2 独立项目体系重构

现有“所属平台”思路必须拆掉，新火要以自己的项目主表为中心，各平台 ID 只作为映射字段存在。

建议的数据表及字段

表名	核心字段建议	用途说明
`tb_project_base`	`id`、`project_code`、`project_name`、`project_keyword`、`firefox_id`、`tuima_id`、`woma_id`、`sms_id`、`success_release_days`、`fail_release_days`、`profit_share_amount`、`status`	新火独立项目主表，所有业务都从这里取主项目。
`tb_project_platform_mapping`	`project_id`、`platform_type`、`platform_project_id`、`platform_project_name`、`sync_status`	如果后续平台映射变复杂，可从主表中拆出扩展映射表。
`tb_merchant_project_selection`	`merchant_id`、`project_id`、`scene_type`、`status`	卡商选中项目表，仅用于托管模式和接新火平台时的项目过滤。
保留原 sms 项目选择表	保留原逻辑和数据，不强行并库	避免一次性改穿 sms 逻辑，降低风险。

后端必须完成的重构点

所有原来按 platform_type 直接查项目的代码，必须改为先定位新火主项目，再按需要读取某个平台映射 ID。
项目检索接口要同时支持“按项目 ID 搜索”和“按项目名称关键字搜索”，因为专属对接创建时需要两种输入方式。
项目表要支持未来持续扩展新的平台映射，不能把字段和逻辑写死在多个 if-else 中。
项目初始化脚本要合并火狐狸和 sms 的历史项目，并做去重回填。
项目表新增的成功释放天数、失败释放天数、分成金额，后续必须真正被取号释放逻辑、托管分润逻辑读取到，不能只停留在字段层。

2.3 卡商配置体系重构

“用户配置”必须整体改造成“卡商配置”，并且不再是列表页，而是一个直接可编辑、可分类展示、可继承的配置中心。

配置层级	说明	必须实现的行为
卡商全局配置	卡商账号级默认配置	如果单设备无独立配置，则继承这里；如果这里也为空，则禁止上卡。
单设备独立配置	卡池/网关/猫池/第三方批次等记录级覆盖配置	仅覆盖有填写的字段；支持“恢复继承”按钮。
托管模式总开关	卡商级全局状态	开启后隐藏第三方对接配置并提示选择项目；不能按单设备单独开关。

字段更名与前端提示文案必须完全落地

原名称	新名称	交互要求
清空数据	下线所有号码	作为按钮动作展示，点击后需有确认弹窗与一分钟等待说明。
取号失败重试次数	获取号码重试次数	Tooltip 需说明只适用于池上卡和 goip 上卡。
等待信号时长	等待信号时长	Tooltip 需说明仅适用于卡池上卡。
短信过期时间	移除	前端彻底隐藏，后端不再参与保存和读取。
号码过期时间	号码保留时间	Tooltip 需解释对火狐狸、沃玛、推码以及卡池上卡生效。
SP 过期时间	卡池上卡周期	Tooltip 需写明 9999999 代表持续在线。
标记	下卡标记	Tooltip 需解释项目完成后自动下线，用于快速释放天线。
天数	成功检测天数	与下卡标记联动。
天数2	失败检测天数	与下卡标记联动。
通知用户	Tg 通知	Tooltip 需说明填写 tg user_id 后上卡下卡会收到通知。

配置相关数据库任务

将原用户配置表平滑迁移为卡商全局配置表，保留历史数据映射。
对所有上卡记录表增加独立配置扩展字段，建议采用 JSON 覆盖列或独立子表。
增加配置版本号或更新时间，支持缓存失效和审计。

配置相关后端任务

提供获取“最终生效配置”的统一服务，内部按“单设备覆盖 -> 卡商默认 -> 系统默认”顺序合并。
配置保存时做数值合法性校验，如重试次数、保留时间、卡池周期不能为负值。
托管模式开启时，接口层拦截所有第三方对接相关保存动作，防止前端绕过。

3. 卡商端重构与菜单体系

前端后端菜单与权限验收

卡商端不是只加几个菜单，而是整个操作流要重构。页面导航、列表入口、管理中心、统计中心、财务中心必须重新组织。尤其是“火团卡商中心”和“数据统计”要作为新的核心入口，而不是散落在原页面里。

3.1 目标菜单结构

上卡方式
  - 卡池上卡
  - 网关上卡
  - 比比熊上卡
  - 猫池上卡（新增）
  - 第三方上卡（新增）
  - API上卡（新增）
  - sms上卡（新增）

号码管理
  - 号码列表
  - 任务记录
  - 号码匹配查询
  - 号码拦截
  - ICCID-手机号（仅管理员）
  - API导出记录

火团卡商中心（新增）
  - 专属对接（新增）
  - 项目管理（新增）
  - 供卡明细（新增）
  - 供卡日统计（新增）
  - API对接(新增)

数据统计（新增）
  - 供卡明细（新增）
  - 供卡日统计（新增）

ESPS
  - 卡池上卡（与上卡方式中的卡池上卡同页面）
  - 天线设备（仅管理员）
  - 天线列表
  - 天线分配记录（仅管理员）
  - 每日数据
  - 插卡记录
  - 插卡统计

业务配置
  - 卡商配置（原用户配置）
  - 服务项目
  - HEROSMS项目（原 sms 项目选择表迁移过来，保持独立）

财务管理
  - 账单明细 （原账单页面）
  - 自助充值（新增）
  - 提现申请（新增）

3.2 前端页面拆分任务

重构菜单渲染数据源，所有菜单名、分组名、图标、权限码、路由路径都统一调整。
“卡池上卡”在上卡方式和 ESPS 中必须指向同一页面，不要复制成两个独立页面，避免逻辑分叉。
“HEROSMS 项目”取消二级菜单后，一级菜单直接进入目标页面。
所有页面文案统一做国际化补漏，尤其是新增字段、按钮、状态字典、Tooltip 内容。
管理员专属页面必须在路由守卫、按钮层级、接口层级同时做权限限制，不能只在前端隐藏。

3.3 后端菜单与权限任务

更新 sys_menu 和角色菜单绑定数据，提供初始化脚本或升级脚本。
补全权限标识，例如：查看 ICCID、查看天线设备、审核提现、管理卡密、托管总控、项目初始化等。
对“任务记录删除”补充权限控制，允许卡商处理自己的记录，管理员可全局处理。

3.4 卡商配置页的具体交互要求

页面结构

不再使用列表页，改为整页表单。
建议拆成“基础参数、周期参数、拦截规则、通知规则、托管模式”五个区块。
每个字段都需要稳定的默认值提示和是否继承标识。

交互细节

每个字段右侧有问号图标，悬停显示完整解释。
托管模式开关切换后，立即联动隐藏第三方平台配置区域。
保存时要提示“此配置为默认配置，未单独设置的上卡记录将继承此配置”。

4. 上卡方式与设备接入

设备表/任务表通信接口管理页面

4.1 共通要求：所有上卡方式最终都要落到统一号码域

无论来源是卡池、网关、比比熊、猫池、第三方还是 API，上卡后的号码都要落入统一号码主表或统一号码视图中。
号码主记录至少要携带：来源类型、设备/批次标识、所属卡商、国家、手机号、是否首次、是否在线、当前状态、最近来码时间、项目统计快照。
所有号码都要支持后续被统一检索、统一导出 API、统一进入专属对接或托管模式。

4.2 卡池上卡 / 网关上卡 / 比比熊上卡

模块	详细任务
卡池上卡	保持现有能力，但需要接入新的“卡商配置继承体系”、新的项目选择体系、托管模式判断、号码导出统计和专属对接过滤能力。
网关上卡	与卡池上卡共享配置规则，如获取号码重试次数、第三方分发配置、托管模式拦截；需支持单条网关记录独立配置。
比比熊上卡	新增国家与分组名称为必填项；对应列表展示要带比比熊分组名称；后端数据结构中补充国家和分组名称字段。

4.3 猫池上卡体系

猫池是本次改造中最像“外部子系统接入”的部分，不能只做页面，必须同时规划设备注册、心跳、上传、短信监听、下发任务、回执闭环。

建议新增数据表

表名	字段建议	说明
`tb_modem_device`	`merchant_id`、`country_code`、`device_name`、`device_secret`、`status`、`last_heartbeat_time`、`client_version`	猫池设备主表，保存设备身份与在线状态。
`tb_modem_card_snapshot`	`device_id`、`slot_no`、`phone_number`、`iccid`、`operator_name`、`signal_status`	记录设备端读取到的卡槽快照。
`tb_sms_send_task`	`task_no`、`target_phone`、`send_content`、`task_status`、`callback_result`、`retry_times`	短信发送任务表，供猫池 PC 端轮询和回执。

后端接口建议

POST /modem/client/login：设备用密钥登录，返回 token、心跳周期、轮询间隔。
POST /modem/client/heartbeat：上报设备在线、版本、槽位摘要。
POST /modem/client/upload-cards：一键读取上传号码，默认接入新火平台。
POST /modem/client/report-sms：设备接到短信后立即推送平台，用于匹配任务记录。
GET /modem/client/pull-send-task：设备端长轮询是否存在待发短信任务。
POST /modem/client/send-task-callback：回传发送结果，更新任务表状态。

前端页面任务

新增猫池设备列表页，支持创建、查看密钥、复制密钥、查看在线状态。
在新增猫池时，填写国家、设备名称，保存后立即生成一条对接记录。
支持查看设备基本信息、当前连接状态、最近心跳时间、软件版本。
提供号码提取规则配置区：USSD 命令、短信取号命令、正则模板。

4.4 第三方上卡（先留口子，后续再实现）

第三方上卡的核心不是“保存一批手机号”，而是要支持“手机号 + 链接”这类半结构化资源进入平台，再由平台做二次包装。

页面与按钮要求

点击“新建”时，必须输入“对接自定义批次名称”和“国家”。
每条记录必须有四个按钮：导入数据、修改配置、导出 API、删除对接。
导入数据时支持上传 TXT，格式严格要求为“一行一个：手机号----链接”。
如果卡商处于托管模式，则“修改配置”区域不显示第三方平台对接配置。

后端处理要求

上传文件后先做格式预校验，再异步入库，避免一次性导入大文件卡死请求。
每个链接资源都要形成单独记录，并绑定所属批次、卡商、国家、可用状态。
导出 API 的本质是平台再包装一层 API，将第三方资源转成新火标准读取方式，并对调用收取少量转码费。
删除对接时要级联删除批次下所有资源记录和相关缓存，但保留审计日志。

4.5 API 上卡与 sms 上卡

API 上卡页面以展示文档和个人密钥管理为主，不做复杂卡池交互。
sms上卡对接herosms的用户接口，从sms平台取号上到新火平台，做个二道贩子。
卡商 API 上传号码时如果无法限定项目，应明确在文案和配置中说明：只能保障接入新火侧的项目控制，无法约束火狐狸等外部平台的全部行为。

5. 号码管理与统计分析

动态检索统一查询服务导出与统计验收

5.1 号码列表必须重构成六大 Tab

在现有号码管理页面上优化，顶部加上6个tab来做切换

Tab	搜索条件（列表列也显示）	列表列
卡池上卡	批次、是否首次、是否在线、运营商、ICCID、状态、手机号	来码数、tg 数量、ws 数量、本批 tg 成功数、本批 ws 成功数、查看项目
网关上卡	与卡池上卡一致	与卡池上卡一致
比比熊上卡	批次、是否首次、是否在线、比比熊分组名称、手机号	来码数、tg 数量、ws 数量、本批 tg 成功数、本批 ws 成功数、查看项目
猫池上卡	批次、是否首次、是否在线、国家、猫池设备名称、手机号	来码数、tg 数量、ws 数量、本批 tg 成功数、本批 ws 成功数、查看项目
第三方上卡	批次名称、是否在线、是否首次、国家、批次/设备名称、手机号	来码数、tg 数量、ws 数量、本批 tg 成功数、本批 ws 成功数、查看项目
API 上卡	国家、手机号、是否在线	来码数、最近一次来码时间、tg 数量、ws 数量、本批 tg 成功数、本批 ws 成功数、查看项目

前端任务

使用统一的动态检索配置驱动 Tab，不要为六个来源写六套重复页面。
切换 Tab 时自动切换表单项、表头列、空数据提示文案。
所有 Tab 的在线号码都支持批量导出 API 和单条导出 API。

后端任务

统一封装号码查询服务，对外可按来源类型切换不同查询策略，但返回统一 DTO。
为高频检索项建立索引：手机号、是否在线、批次、国家、设备、最近来码时间、卡商 ID。
API 导出功能要单独记账，叫做“卡商转码服务费”；用户系统取号时，若使用“导出为 API 链接”，不额外收费。

5.2 任务记录、号码拦截、号码匹配查询

任务记录页需要支持卡商自行删除历史记录，解决原平台删除困难问题（并设计为软删除，若成功记录删除，则卡对于用户来说就能取到了）。
号码匹配查询需支持从项目、手机号、卡商、专属对接码等维度倒查使用关系。
号码拦截页的功能保持现状，支持卡商自定义导入号码做拦截，拦截后号码不上传，一般适用于ESPS模式。
ICCID-手机号页面保持现状，仅管理员可见，除前端隐藏外，接口必须做权限校验。

5.3 供卡明细与供卡日统计（火团卡商中心）

这里的统计不应混入外部平台数据，应重点反映“对接火团/新火自身业务”的真实供卡表现。

统计页	搜索条件	返回字段
供卡明细	时间、上卡方式、上卡设备、国家、项目、对接码、手机号	设备、上卡方式、国家、项目、上卡时间、手机号、对接码、提取时间、回码时间、验证码内容
供卡日统计	日期范围、项目、对接码	日期、项目、对接码、已回码数、未回码数、号码总数、回码率

实现细节

默认供卡明细和供卡日统计页面不显示内容，只有选择了条件后点击查询才能显示结果。
供卡明细和供卡日统计页面支持导出功能，导出数据与页面显示一致。
供卡明细里不支持查询全部（数据太多），至少要选择一个项目查询
供卡明细建议直接从“号码使用单据 + 短信回执 + 对接关系”组合查询。
供卡日统计建议做按日汇总表或定时汇总任务，避免每次页面打开都直接扫明细大表。
“回码率”应统一公式：已回码数 / 号码总数，保留两位百分比。

6. 项目管理与专属对接

项目与对接表取号路由创建与管理页面

6.1 火团卡商中心里的项目管理

项目管理页必须展示新火独立项目，不再展示“所属平台”单维度视图。
卡商支持项目 ID、项目名称、关键字、状态、的检索和勾选做与不做。不显示三方平台的 ID
管理员支持修改新增项目，编辑项目信息，维护成功释放天数、失败释放天数、托管分成金额。
支持卡商选择“我做哪些项目”，“火团卡商对接”在这里选择要做的项目；托管模式不支持选择项目
项目关键词需要独立维护，因为当前已知问题是火狐狸项目很多，但关键词并不完整；因此应在项目管理页提供关键词编辑、导入和补录能力。

6.2 专属对接主流程

创建对接

卡商创建专属对接时，需要选择国家、搜索项目、设置收入、自动计算用户支付价、选择是否开启 API 反馈计费权限、选择私密或公开。
系统自动生成唯一对接码；同一卡商、同一项目可以创建多个对接码，允许价格不同，便于分别统计。
创建弹窗中要展示提示内容，包括：先搜索并选择项目、创建后把对接码发给用户、该项目卡需勾选上卡、卡商价为 0 表示线下结算且平台不负责纠纷。
如果选择公开，则用户在创建专属对接时可以搜索到该对接码并申请加入；如果选择私密，则用户无法搜索到该对接码，只能通过私下联系卡商提供的对接码链接加入。
如果选择开启 API 反馈计费权限，那么用户可以通过api来反馈号码是否可用，来决定是否扣费；反之系统来码会自动扣费。
对接创建成功后，系统会生成一个专属对接码，格式仿照火狐狸，例如：zaf-1000-04494huo；格式为：国家代码-项目ID-随机码。

对接表设计建议

表名	核心字段	说明
`tb_exclusive_docking`	`docking_code`、`merchant_id`、`country_code`、`project_id`、`merchant_income`、`user_price`、`feedback_enabled`、`private_flag`、`disabled_flag`	专属对接主表。
`tb_exclusive_docking_member`	`docking_id`、`joiner_type`、`joiner_id`、`join_status`	加入对接的用户或卡商成员关系表。
`tb_exclusive_docking_bill`	`docking_id`、`user_pay_amount`、`merchant_income_amount`、`channel_fee`、`settle_status`	用于专属对接收入支出统计，避免页面实时跑重 SQL。

管理与展示要求

专属对接列表必须显示：序号、当前接入人数、项目、对接码、国家、是否禁用、是否私密、是否开启反馈、供卡情况、卡商收入、用户支出。
项目字段展示必须带项目号和项目名称，不可只显示一个名字。
供卡情况按“在线数量 / 可用数量”展示，例如“在线：100 / 可用：100”。
点击对接码应直接复制，并提示“复制成功！”。
支持删除对接、暂停接入、继续接入、退出对接等动作，但要区分动作主体和权限边界。（参考本文档1.3）

6.3 取号路由重构

这是整个专属对接能力的真正难点，不在页面，而在取号核心。

同一项目下，如果用户加入了多个专属对接码，取号时应从所有有效对接池中混合抽取，而不是固定绑死一个卡商的专属对接。
只有创建专属对接的卡商可以禁用整个对接；加入此对接的卡商只能暂停自己接入。
如果卡商授权其他卡商加入该专属对接码，则这些加入方的号源也进入同一个专属对接的号池。
对接码私密/公开影响的是“是否允许被检索/被加入”，不影响其本身的计费逻辑。

7. 托管模式与财务体系

双账户体系托管路由充值提现页面结算验收

7.1 托管模式开关与页面隔离

当卡商开启托管模式后，前端必须隐藏所有第三方平台对接菜单或配置区，且后端必须阻断相关保存行为。
托管模式下，该卡商所有上卡方式上的号码都要自动打上“托管号”标记。
退出托管模式时必须给出风险警告，提示退出后可能失去平台自动运营收益、第三方配置重新显现等影响。
要给出卡商用户提示：托管模式要求号码尽可能保持在线。

7.2 托管后台总控

管理员需要拥有托管号码管理页面，能看到实时在线托管号、来源设备、所属卡商、当前项目、最近状态。
管理员需要维护系统级的外部平台密钥配置，例如火狐狸等平台的托管上传密钥。可以专门新增表来管理
当托管号上线后，系统应根据管理员配置自动路由到指定平台，而不是要求卡商手工上传。
托管号码的使用结果必须能回流平台，以便计算卡商收益。

7.3 双账户财务模型

账户类型	用途	来源	是否可提现
消费余额	卡商或用户消费、接口调用、转码费、通道费等	充值、卡密核销	否
可提现收益	托管项目分成、专属对接收入等	业务结算	是

建议新增表

tb_account_wallet：主钱包表，至少拆消费余额和提现收益。
tb_account_bill：账单明细，记录充值、扣费、返还、冻结、解冻、分润、提现等所有事件。
tb_withdraw_apply：提现申请表。
tb_card_secret：卡密库，保存面值、状态、批次、核销信息。

7.4 自助充值与卡密平台

用户或卡商前端提供“填写卡密 -> 校验 -> 充值成功”的极简页面。
管理员后台要有卡密管理页，支持按金额和数量批量生成卡密。
卡密需要支持批次导出，方便上传到独角兽等售卖平台。
卡密核销必须幂等，不能重复核销；建议在数据库唯一约束基础上加锁控制。

7.5 提现申请工作流

卡商从“可提现收益”账户发起提现申请，不可直接从消费余额提现。
提交申请后，先冻结收益金额，避免重复申请。
管理员可审核通过或驳回；通过后进入打款状态，驳回后解冻返还。
管理员页面要支持按时间、用户、状态筛选所有提现申请。

8. C端用户系统与开放 API

用户端页面开放接口高并发取号

8.1 用户端网页功能矩阵

用户端不是只有一个“取号页面”，而是要形成完整的业务入口集合，整体风格与火狐狸一致或接近，以降低用户学习成本。

联系客服
使用帮助
自助充值
服务项目
专属对接
接码业务
数据统计
API 对接
推广代理（先留口子）
我的需求（先留口子）

这里参考火狐狸

用户登录：https://www.firefox.fun/user/login.aspx
账号：nanfei1@qq.com
密码：nimabi123

卡商登录：https://www.firefox.fun/seller/login.aspx
账号：wangxiaoer852@gmail.com
密码：963852AAa@@

8.2 高并发取号与释放机制

号码上线后要进入 Redis 对应资源池，按“公共池 / 专属池 / 托管池 / 项目 / 国家”等维度拆分 key。
取号时使用 Redis 原子操作或分布式锁，从候选集合中取出号码，立即落任务单并标记占用状态。
用户释放号码时，号码进入冷却期，并累计释放次数。
同一号码释放达到 3 次后，按黑名单逻辑处理，并结合项目表中的成功释放天数/失败释放天数决定多久后再次放出。
所有释放、拉黑、回池动作都必须同步更新数据库和缓存，防止状态漂移。

8.3 API 反馈计费与 5 分钟法则

这是整个 C 端和开放 API 的计费核心。如果只实现“收到验证码立刻扣钱”，一定会引发纠纷。

步骤（卡商开启了API反馈）	系统动作
收到验证码	平台将短信提交给用户，同时冻结用户需要支付的费用，不立即结算给卡商。
用户反馈成功	将冻结资金转为实际扣费，并结算卡商收入。
用户反馈失败	释放号码或进入失败处理，同时把冻结资金返还给用户，卡商不计费。
5 分钟无反馈	系统自动视为成功，完成扣费和结算，避免冻结单长期堆积。

步骤（未开启API反馈）	系统动作
收到验证码	平台将短信提交给用户，直接给用户扣费，并且结算给卡商。

后端必须具备的能力

冻结资金单据表与状态机。
反馈接口幂等控制，避免重复提交成功/失败导致重复结算。
5 分钟延迟自动处理任务，可追踪、可补偿。
卡商是否开启“API 反馈计费权限”的开关校验，不是所有对接都要走此流程。

8.4 开放 API 设计目标

卡商 API 与用户 API 都尽量向火狐狸靠拢，让用户已有脚本只改域名和密钥就能迁移。接口是否完全同名可根据现有系统约束调整，但语义和参数尽量保持一致。

建议核心接口完全模仿火狐狸：
1. 火狐狸用户api：https://www.firefox.fun/user/apis/apidoc_chn.aspx
2. 火狐狸卡商api：https://ks.firefox.fun/ksapidoc.aspx#PhoneDeleteCountry

8.5 租号链接 / 短链能力

支持为某个号码生成带签名的临时短链，不要求访问者先注册登录。
短链可查看号码、读取短信、执行结束操作，但必须限定有效期和一次性/有限次访问策略。
短链一旦完成终结动作或超时，应自动失效，避免长期暴露资源。

9. 权限、风控、并发与审计

权限并发与补偿风控验收

9.1 权限矩阵必须明确

（部分已经实现，要再次核对，因为要开放用户端，不能有风险漏洞）

功能	管理员	卡商	C端用户	加入专属对接的其他主体
查看 ICCID-手机号	可	不可	不可	不可
天线设备/分配记录	可	按需求限制	不可	不可
禁用专属对接	可	仅创建者可	不可	不可
暂停/继续接入	可	创建者或加入者对自己可控	若为加入者可控	可控自身状态
审核提现	可	不可	不可	不可
管理员充值（用户信息修改）	可	不可	不可	不可
其他可能存在风险的接口	可	不可	不可	不可

9.2 风控与幂等要求

卡密核销必须幂等，同一卡密不可重复使用。
冻结单处理必须幂等，同一订单不能既被“失败返还”又被“超时自动成功”。
取号必须保证同一号码不会在同一时间给到多个用户。
专属对接删除、退出、暂停要做状态校验，不能删除仍有活跃业务的对接码。
短信发送任务要支持重试和死信处理，防止设备端长时间不回执。

9.3 审计日志

记录卡商配置变更日志，特别是托管模式开关、项目选择变更。
记录专属对接创建、禁用、删除、加入、退出、暂停、继续事件。
记录财务关键动作：卡密生成、卡密核销、冻结、解冻、结算、提现审核。
记录管理员托管配置修改日志，防止后续收益归属争议。

10. 联调、测试、迁移与上线

结构迁移联调顺序测试矩阵上线回滚

10.1 推荐实施顺序

先做 Redis、锁、延迟任务和统一状态枚举。
再做项目主表、卡商配置表、钱包表、专属对接表、短信任务表等数据结构。
然后重构号码主域和取号路由，让新旧来源先能进入统一模型。
再做卡商端菜单、卡商配置页、号码列表六大 Tab、项目管理页。
然后接入猫池、第三方上卡、托管模式后台。
最后开放 C 端页面、开放 API、租号短链和卡密/提现闭环。

10.2 数据迁移任务

编写 SQL 升级脚本，保留旧字段，不要直接删列，先做兼容期。
对旧项目数据做合并去重和映射回填。
对旧用户配置数据回填到新卡商配置表。
对已有余额数据拆分时，默认迁入消费余额；收益余额按业务规则单独迁移或初始为 0。
菜单升级脚本要支持重复执行，避免测试环境多次导入出错。

10.3 联调检查清单

前后端联调

卡商配置字段名、Tooltip 文案、默认值完全一致。
号码列表六大 Tab 的条件和列完全一致。
专属对接创建页中的用户支付价实时计算与后端计算结果一致。
托管模式开关切换后，前端显示与后端权限限制一致。

外部系统联调

猫池 PC 端模拟登录、心跳、上传、短信推送、任务拉取、结果回传。
第三方 TXT 导入样例验证。
开放 API 使用现有脚本进行兼容性测试。
托管模式对接外部平台密钥的实际推号闭环验证。

10.4 上线与回滚建议

先在测试环境完成结构升级和数据回填，再在预发布环境做一次完整演练。
上线前预热 Redis key 规范和延迟任务配置，避免正式环境首批请求触发未知分支。
关键表变更要有回滚 SQL 和字段保留方案，尤其是项目表、钱包表、配置表。
开放 API 建议先灰度给少量测试用户，再逐步开放，防止外部脚本把新接口瞬间打爆。

11. 总体验收口径

判断标准： 本次改造验收不能只看“页面能打开”，而要看“业务闭环是否真正跑通”。以下口径建议作为正式验收用例的主清单。

项目体系完成独立化改造，旧数据成功合并，所有原依赖项目查询的功能仍可运行。
卡商配置页不再是列表页，字段命名、Tooltip、托管模式联动全部符合要求；单设备不配时能够正确继承卡商默认配置。
菜单结构与权限结构完全匹配需求，管理员专属菜单和普通卡商菜单边界清晰。
猫池设备能完成登录、心跳、上传号码、上报短信、拉取发信任务、回传结果的完整闭环。
第三方上卡支持 TXT 批量导入、修改配置、导出 API、删除对接；托管模式下隐藏不该出现的配置。
号码列表六大 Tab 的搜索条件和列表列准确无误；在线号码可批量导出 API 和单条导出 API。
专属对接支持创建、复制对接码、查看当前接入人数、查看供卡情况、禁用、暂停、继续、删除；同项目多对接码场景下取号能混合分发。
托管模式下，卡商的号码自动变成托管号，管理员能统一查看和路由，业务完成后收益进入可提现收益账户。
卡密自助充值可用，重复核销会被拒绝；提现申请工作流完整，审核通过与驳回都能正确更新状态和余额。
C 端取号接口在高并发下无重复分配；释放三次会进入黑名单或冷却逻辑；项目成功/失败释放天数真正生效。
开启反馈计费权限后，短信到达先冻结，成功再结算，失败则退回，5 分钟无反馈自动按成功处理。
开放 API 能被现有接码脚本基本兼容调用，至少能走通登录、取号、轮询短信、释放、反馈的一整套链路。
所有页面完成后，必须逐页检查国际化是否完善，重点核对菜单、按钮、状态、Tooltip、错误提示、空数据提示和弹窗文案，查漏补缺后方可验收。

12. 开发任务 Checklist

使用方式： 建议开发人员直接复制下面这份 Markdown 清单到本地文档、飞书任务、Jira 子任务或仓库 issue 中。完成一项就打勾一项，避免遗漏。

# 新火平台开发任务 Checklist

## 一、基础底座与公共能力
- [ ] 在 Maven 中引入 Redis 依赖
- [ ] 在 Maven 中引入 Redisson 依赖
- [ ] 在配置文件中补齐 Redis 连接信息
- [ ] 在配置文件中补齐 Redis 连接池参数
- [ ] 统一定义 Redis key 命名规范
- [ ] 实现统一的 Redis 分布式锁工具或注解
- [ ] 为取号流程接入分布式锁
- [ ] 为释放号码流程接入分布式锁
- [ ] 为冻结结算流程接入分布式锁
- [ ] 为托管分润流程接入分布式锁
- [ ] 为卡密核销流程接入分布式锁
- [ ] 为提现审核流程接入分布式锁
- [ ] 定义统一状态枚举：号码状态
- [ ] 定义统一状态枚举：对接状态
- [ ] 定义统一状态枚举：提现状态
- [ ] 定义统一状态枚举：冻结单状态
- [ ] 定义统一状态枚举：短信任务状态
- [ ] 定义统一状态枚举：托管状态
- [ ] 建立延迟任务方案，用于 5 分钟自动结算
- [ ] 建立延迟任务方案，用于号码过期下线
- [ ] 建立延迟任务方案，用于项目释放回池
- [ ] 建立延迟任务方案，用于设备心跳超时检查
- [ ] 建立统一审计日志入口

## 二、项目体系与项目管理
- [ ] 新增或改造新火项目主表
- [ ] 在项目主表增加 firefox_id 字段
- [ ] 在项目主表增加 tuima_id 字段
- [ ] 在项目主表增加 woma_id 字段
- [ ] 在项目主表增加 sms_id 字段
- [ ] 在项目主表增加 success_release_days 字段
- [ ] 在项目主表增加 fail_release_days 字段
- [ ] 在项目主表增加 profit_share_amount 字段
- [ ] 在项目主表增加 project_keyword 或关键词字段
- [ ] 评估是否拆分项目平台映射表
- [ ] 保留原 sms 项目选择表逻辑
- [ ] 新增卡商选中项目表
- [ ] 区分托管模式项目选择和新火接码项目选择
- [ ] 编写旧项目数据初始化与合并脚本
- [ ] 编写火狐狸项目导入逻辑
- [ ] 编写 sms 项目导入逻辑
- [ ] 完成项目名称去重逻辑
- [ ] 完成项目关键词补录逻辑
- [ ] 提供项目按 ID 搜索接口
- [ ] 提供项目按名称搜索接口
- [ ] 提供项目按关键词搜索接口
- [ ] 提供项目多平台映射维护接口
- [ ] 提供项目管理页面查询接口
- [ ] 提供项目编辑页面保存接口
- [ ] 排查并替换所有旧的 platform_type 项目查询逻辑

## 三、卡商配置体系
- [ ] 将“用户配置”统一更名为“卡商配置”
- [ ] 移除原列表式配置页面
- [ ] 新建整页表单式卡商配置页面
- [ ] 将卡商配置拆分为基础参数区块
- [ ] 将卡商配置拆分为周期参数区块
- [ ] 将卡商配置拆分为拦截规则区块
- [ ] 将卡商配置拆分为通知规则区块
- [ ] 将卡商配置拆分为托管模式区块
- [ ] 实现卡商默认配置表保存逻辑
- [ ] 实现卡商默认配置表读取逻辑
- [ ] 实现单设备独立配置存储逻辑
- [ ] 实现单设备独立配置读取逻辑
- [ ] 实现“单设备覆盖 -> 卡商默认 -> 系统默认”的配置合并逻辑
- [ ] 未配置默认配置时阻止上卡
- [ ] “清空数据”字段更名为“下线所有号码”
- [ ] “取号失败重试次数”字段更名为“获取号码重试次数”
- [ ] “号码过期时间”字段更名为“号码保留时间”
- [ ] “SP过期时间”字段更名为“卡池上卡周期”
- [ ] “标记”字段更名为“下卡标记”
- [ ] “天数”字段更名为“成功检测天数”
- [ ] “天数2”字段更名为“失败检测天数”
- [ ] “通知用户”字段更名为“Tg通知”
- [ ] 删除“短信过期时间”字段的前端展示
- [ ] 删除“短信过期时间”字段的后端保存逻辑
- [ ] 为每个配置字段补齐 Tooltip 文案
- [ ] 为“下线所有号码”按钮补齐确认弹窗
- [ ] 为“下线所有号码”按钮补齐一分钟等待提示
- [ ] 实现托管模式全局开关
- [ ] 托管模式开启后隐藏第三方平台配置
- [ ] 托管模式开启后提醒卡商选择项目
- [ ] 实现设备配置“恢复继承”按钮

## 四、菜单、路由与权限
- [ ] 重构左侧菜单分组结构
- [ ] 新增“火团卡商中心”顶级菜单
- [ ] 新增“数据统计”顶级菜单
- [ ] 新增“猫池上卡”菜单
- [ ] 新增“第三方上卡”菜单
- [ ] 新增“API上卡”菜单
- [ ] 新增“sms上卡”菜单
- [ ] 新增“自助充值”菜单
- [ ] 新增“提现申请”菜单
- [ ] 新增“API导出记录”菜单
- [ ] 保证 ESPS 下的“卡池上卡”和上卡方式中的“卡池上卡”指向同一页面
- [ ] 移除“运营商”菜单
- [ ] HEROSMS 项目取消二级菜单
- [ ] 更新 sys_menu 初始化脚本
- [ ] 更新角色与菜单绑定关系
- [ ] 限制 ICCID-手机号页面仅管理员可见
- [ ] 限制天线设备页面仅管理员可见
- [ ] 限制天线分配记录页面仅管理员可见
- [ ] 配置任务记录删除权限
- [ ] 配置提现审核权限
- [ ] 配置卡密管理权限
- [ ] 配置托管后台管理权限

## 五、上卡方式与设备接入
- [ ] 适配卡池上卡到新配置体系
- [ ] 适配卡池上卡到新项目体系
- [ ] 适配网关上卡到新配置体系
- [ ] 适配网关上卡到新项目体系
- [ ] 比比熊上卡增加国家字段
- [ ] 比比熊上卡增加供应商字段
- [ ] 比比熊上卡列表显示分组名称
- [ ] 新增猫池设备主表
- [ ] 新增猫池卡槽快照表或等价结构
- [ ] 新增短信发送任务表
- [ ] 实现猫池设备创建页面
- [ ] 实现猫池设备密钥生成逻辑
- [ ] 实现猫池设备密钥复制交互
- [ ] 实现猫池设备状态展示页面
- [ ] 实现猫池设备基本信息展示
- [ ] 实现猫池设备登录接口
- [ ] 实现猫池设备心跳接口
- [ ] 实现猫池一键上传号码接口
- [ ] 实现猫池短信上报接口
- [ ] 实现猫池短信任务长轮询接口
- [ ] 实现猫池短信任务回执接口
- [ ] 实现 USSD 取号命令配置
- [ ] 实现短信取号命令配置
- [ ] 实现正则模板配置
- [ ] 新增第三方上卡批次主表
- [ ] 实现第三方上卡批次新增页面
- [ ] 实现第三方上卡 TXT 导入
- [ ] 为 TXT 导入做“手机号----链接”格式校验
- [ ] 实现第三方上卡“修改配置”功能
- [ ] 实现第三方上卡“导出API”功能
- [ ] 实现第三方上卡“删除对接”功能
- [ ] 托管模式下隐藏第三方上卡配置项
- [ ] 实现 API 上卡文档页
- [ ] 实现 API 上卡个人密钥管理页
- [ ] 适配 sms 上卡进入统一号码域

## 六、统一号码主域与号码管理
- [ ] 建立统一号码主表或统一号码视图
- [ ] 为号码记录补充来源类型字段
- [ ] 为号码记录补充设备/批次标识字段
- [ ] 为号码记录补充是否首次字段
- [ ] 为号码记录补充是否在线字段
- [ ] 为号码记录补充状态字段
- [ ] 为号码记录补充最近来码时间字段
- [ ] 为号码记录补充项目统计快照字段或聚合结构
- [ ] 实现号码列表六大 Tab 的统一查询 API
- [ ] 实现号码列表六大 Tab 的动态搜索表单
- [ ] 实现号码列表六大 Tab 的动态列配置
- [ ] 实现在线号码单条导出 API
- [ ] 实现在线号码批量导出 API
- [ ] 实现 API 导出记录页面
- [ ] 实现任务记录查询页
- [ ] 实现任务记录删除功能
- [ ] 实现号码匹配查询页面
- [ ] 实现号码拦截页面
- [ ] 实现 ICCID-手机号查询页面
- [ ] 为号码列表相关查询加索引

## 七、供卡明细与统计分析
- [ ] 实现供卡明细查询接口
- [ ] 供卡明细支持按时间筛选
- [ ] 供卡明细支持按上卡方式筛选
- [ ] 供卡明细支持按上卡设备筛选
- [ ] 供卡明细支持按国家筛选
- [ ] 供卡明细支持按项目筛选
- [ ] 供卡明细支持按对接码筛选
- [ ] 供卡明细支持按手机号筛选
- [ ] 供卡明细返回验证码内容字段
- [ ] 实现供卡日统计聚合接口
- [ ] 供卡日统计支持按日期范围筛选
- [ ] 供卡日统计支持按项目筛选
- [ ] 供卡日统计支持按对接码筛选
- [ ] 计算并展示回码率
- [ ] 评估并实现按日汇总表或定时聚合任务

## 八、项目管理与专属对接
- [ ] 实现火团卡商中心项目管理页
- [ ] 支持项目 ID 查询
- [ ] 支持项目名称查询
- [ ] 支持项目关键词查询
- [ ] 支持成功释放天数维护
- [ ] 支持失败释放天数维护
- [ ] 支持分成金额维护
- [ ] 支持卡商项目勾选保存
- [ ] 区分托管模式项目勾选和新火接码项目勾选
- [ ] 新增专属对接主表
- [ ] 新增专属对接成员关系表
- [ ] 新增专属对接结算表或统计表
- [ ] 实现专属对接创建页面
- [ ] 创建页支持按项目 ID 搜索
- [ ] 创建页支持按项目名称搜索
- [ ] 创建页支持国家选择
- [ ] 创建页支持卡商收入输入
- [ ] 实现“用户实际支付价格 = 卡商收入 + 0.03”自动计算
- [ ] 实现“API反馈计费权限”开关
- [ ] 实现“私密/公开”开关
- [ ] 实现对接码自动生成逻辑
- [ ] 实现对接码复制交互
- [ ] 实现对接码列表页
- [ ] 列表显示当前接入人数
- [ ] 列表显示项目号和项目名
- [ ] 列表显示在线数量/当前可用数量
- [ ] 列表显示卡商收入和用户支出
- [ ] 区分“禁用/未禁用”和“暂停接入/继续接入”两套状态
- [ ] 实现加入专属对接功能
- [ ] 实现退出专属对接功能
- [ ] 实现暂停接入功能
- [ ] 实现继续接入功能
- [ ] 实现删除对接功能
- [ ] 实现客户按项目自动路由到专属池的逻辑
- [ ] 实现客户加入多个专属对接时混合随机取号逻辑
- [ ] 实现同一卡商多个专属对接指向同一项目时的同步号池逻辑
- [ ] 保证 a、b 两个对接中的在线数量和可用数量保持一致

## 九、托管模式与财务闭环
- [ ] 在卡商配置中落地托管模式开关
- [ ] 为号码记录增加托管号标记
- [ ] 托管模式下隐藏第三方平台菜单或配置区
- [ ] 托管模式下阻止第三方配置保存接口
- [ ] 实现托管号码管理页面
- [ ] 实现托管后台总控页面
- [ ] 实现管理员托管平台密钥配置
- [ ] 实现托管号自动路由到外部平台逻辑
- [ ] 实现托管业务结果回流逻辑
- [ ] 新增消费余额字段或钱包结构
- [ ] 新增可提现收益字段或钱包结构
- [ ] 新增账单明细表
- [ ] 新增提现申请表
- [ ] 新增卡密库表
- [ ] 实现卡密批量生成功能
- [ ] 实现卡密批次导出功能
- [ ] 实现自助充值页面
- [ ] 实现卡密核销接口
- [ ] 实现卡密重复核销拦截
- [ ] 实现提现申请页面
- [ ] 实现提现申请冻结金额逻辑
- [ ] 实现管理员审核提现页面
- [ ] 实现提现通过逻辑
- [ ] 实现提现驳回解冻逻辑
- [ ] 实现托管项目分润入账逻辑
- [ ] 实现专属对接收入入账逻辑
- [ ] 保证消费余额和收益余额不能混算

## 十、C端用户系统与开放 API
- [ ] 实现 C 端服务项目页面
- [ ] 实现 C 端专属对接页面
- [ ] 实现 C 端接码业务主页面
- [ ] 实现 C 端数据统计页面
- [ ] 实现 C 端自助充值页面
- [ ] 实现 C 端使用帮助页面
- [ ] 实现 C 端联系客服页面
- [ ] 实现 C 端 API 对接页面
- [ ] 预留推广代理页面入口
- [ ] 实现“我的需求”页面或入口
- [ ] 实现 /user/apis/login 接口
- [ ] 实现 /user/apis/get_projects 接口
- [ ] 实现 /user/apis/get_mobile 接口
- [ ] 实现 /user/apis/get_sms 接口
- [ ] 实现 /user/apis/free_mobile 接口
- [ ] 实现 /user/apis/add_blacklist 接口
- [ ] 实现 /user/apis/api_feedback 或等价反馈接口
- [ ] 实现卡商上传号码 API
- [ ] 实现卡商项目列表 API
- [ ] 实现开放 API 文档页
- [ ] 让 API 使用项目 ID 取号，不要求显式传专属对接码
- [ ] 实现租号短链或分享短链能力
- [ ] 为短链增加有效期控制
- [ ] 为短链增加失效回收逻辑

## 十一、并发、释放与计费控制
- [ ] 按项目、国家、场景建立 Redis 号码池
- [ ] 大厅号码进入公共号码池
- [ ] 专属号码进入专属对接号码池
- [ ] 托管号码进入托管场景逻辑池
- [ ] 取号时使用原子操作或锁保证不超卖
- [ ] 生成取号单据并记录占用状态
- [ ] 实现号码释放逻辑
- [ ] 实现释放次数累计逻辑
- [ ] 实现释放三次进入黑名单或冷却逻辑
- [ ] 实现成功释放天数逻辑
- [ ] 实现失败释放天数逻辑
- [ ] 新增冻结单据表
- [ ] 收到验证码时生成冻结单据
- [ ] 开启反馈计费时先冻结不直接结算
- [ ] 实现反馈成功结算逻辑
- [ ] 实现反馈失败退款逻辑
- [ ] 实现 5 分钟无反馈自动成功逻辑
- [ ] 未开启反馈计费时走直接扣费直结逻辑
- [ ] 为反馈接口做幂等校验
- [ ] 为自动成功任务做幂等校验

## 十二、测试、国际化与上线
- [ ] 编写项目体系迁移测试用例
- [ ] 编写卡商配置继承测试用例
- [ ] 编写专属对接混池取号测试用例
- [ ] 编写托管模式菜单隔离测试用例
- [ ] 编写双账户财务测试用例
- [ ] 编写卡密核销幂等测试用例
- [ ] 编写提现审核流程测试用例
- [ ] 编写猫池接口联调测试用例
- [ ] 编写第三方 TXT 导入测试用例
- [ ] 编写号码六大 Tab 查询测试用例
- [ ] 编写开放 API 兼容性测试用例
- [ ] 编写高并发取号压测脚本
- [ ] 验证高并发下无重复分配号码
- [ ] 验证高并发下无重复结算
- [ ] 验证 5 分钟自动成功任务正常运行
- [ ] 验证专属对接多个池随机混合取号
- [ ] 验证同项目多个专属对接的在线数量同步
- [ ] 验证所有管理员专属接口不可被普通角色调用
- [ ] 逐页检查国际化菜单文案
- [ ] 逐页检查国际化按钮文案
- [ ] 逐页检查国际化状态文案
- [ ] 逐页检查 Tooltip 文案是否齐全
- [ ] 逐页检查错误提示和空数据提示是否齐全
- [ ] 完成测试环境数据迁移演练
- [ ] 完成预发布环境全链路联调
- [ ] 准备上线 SQL 脚本
- [ ] 准备回滚 SQL 脚本
- [ ] 准备上线检查清单
- [ ] 准备灰度开放 API 计划
- [ ] 完成最终上线验收签字