xxk-proxy/开发交接-当前进度说明.md

开发交接 - 当前进度说明

更新时间：2026-06-09

当前目标

当前系统从原 IPNux 上游适配改造为齐云 IP 上游适配，主要服务静态/长效住宅代理业务，并保留后续扩展其它 IP 平台的 adapter 能力。

已完成内容

后端

• 已删除 IPNux 上游适配代码：
  • IPNuxApiSupport
  • IPNuxStaticProxyClient
  • IPNuxDynamicProxyClient
• 已新增齐云适配包：
  • java/src/main/java/com/youlai/boot/proxy/integration/qiyun/QiYunApiSupport.java
  • QiYunStaticProxyClient.java
  • QiYunProductType.java
  • QiYunPeriod.java
  • QiYunPeriodMapper.java
• 齐云供应商类型为 QIYUN。
• 齐云认证使用 Header：apikey = upstreamProvider.authToken。
• 齐云接口基础地址当前按文档默认配置为 https://www.qiyunip.com，存储在后台“上游供应商”的 baseUrl 字段。
• 如果调用项目/地区/节点接口出现 Connection refused，优先检查：
  • 后台上游供应商基础地址是否误填、是否带了错误端口。
  • 运行后端的服务器是否能访问 https://www.qiyunip.com/api/agent/getproject?product_type=staticA。
  • 本机/服务器防火墙、代理、DNS、运营商网络是否拦截该域名的 HTTPS 连接。
• 后端已将齐云网络连接异常转换为业务异常，前端会提示“齐云接口连接失败”，并继续写入上游请求日志。
• 系统平台商品类型仍保留原数据库值：
  • STATIC_RESIDENTIAL：当前用于齐云静态/长效代理下单、地区价格、资产开通和资产管理。
  • DYNAMIC_RESIDENTIAL：动态代理旧结构预留，齐云当前没有动态通道接口，不作为 MVP 主流程使用。
• 不建议直接修改 product_type 枚举值，因为订单、价格、资产、会员套餐目录都依赖该值分流。
• 齐云商品类型使用 Product.upstreamProductCode 存储：
  • staticA
  • staticB
  • home
  • custom
• custom 独享长效已纳入齐云静态长效模型，按齐云文档不传 pid。
• 商品新增通用上游扩展字段：
  • upstreamParams
  • upstreamCapabilities
• upstreamParams 用于保存齐云差异参数，例如：

{
  "pid": "1",
  "areaId": "-1",
  "nodeId": "-1",
  "nodeValue": "随机地区"
}

• 已改造上游 facade / client 静态接口，使续费、改密、调换节点都带 upstreamProductCode，方便不同平台识别自己的商品类型。
• 齐云已实现的上游能力：
  • 购买：/api/agent/buy
  • 节点库存：/api/agent/getnode
  • 节点列表：/api/agent/proxy
  • 续费：/api/agent/renew
  • 修改密码：/api/agent/editpass
  • 调换节点 adapter 能力：/api/agent/batchchange
• 齐云暂不支持的能力：
  • 远端白名单
  • 远端自动续费开关
  • 动态代理通道
• 会员端和 OpenAPI 端已取消 IPNux 的用途标签必填限制。
• 订单创建前已增加齐云商品配置兜底校验：
  • 历史商品即使没有经过最新后台保存校验，也会在下单前校验齐云产品类型。
  • staticA/staticB/home 必须有 pid。
  • 所有齐云静态商品必须有 nodeId/nodeValue。
  • 静态订单已允许 purposeWeb 为空，避免齐云下单被旧 IPNux 用途参数阻断。
• 静态库存查询已传入通用上游参数：
  • product_type
  • pid
  • area_id
• 静态资产 VO 已增加 providerType，前端可根据供应商类型隐藏不支持的功能。
• 静态资产调换节点业务接口已完成：
  • 管理端：POST /api/v1/proxy/static-assets/change-node
  • 会员端：POST /api/v1/member/static-assets/change-node
  • 当前仅允许 QIYUN 供应商调用。
  • 默认目标节点可使用商品 upstreamParams.nodeId/nodeValue，也允许请求覆盖。
• 静态资产单资产同步上游节点已完成：
  • 管理端：POST /api/v1/proxy/static-assets/sync
  • 会员端：POST /api/v1/member/static-assets/sync
  • 当前通过齐云 /api/agent/proxy 按资产 upstreamProxyId 或 IP 搜索节点。
  • 同步成功后会更新本地资产 IP、端口、账号、密码、协议、地区、状态、到期时间和 rawData。
• 静态资产批量同步上游节点已完成：
  • 管理端：POST /api/v1/proxy/static-assets/batch-sync
  • 会员端：POST /api/v1/member/static-assets/batch-sync
  • 支持传 assetIds 批量同步。
  • 支持传 orderId 按订单同步该订单下的静态资产。
  • 批量同步单个资产失败不会中断整体流程，接口返回成功同步数量。
• 静态资产定时同步上游节点已完成：
  • 定时任务：StaticProxyUpstreamSyncJob
  • 默认每小时执行一次：proxy.static-upstream-sync.cron=0 0 * * * ?
  • 默认每轮最多同步 100 条：proxy.static-upstream-sync.limit=100
  • 默认启用，可通过 proxy.static-upstream-sync.enabled=false 关闭。
  • 同步范围为启用状态、未过期、齐云供应商下的静态资产，按 lastSyncTime 升序优先同步较久未刷新的资产。
• 静态资产同步失败日志已接入现有上游请求日志表：
  • 复用表：xxk_upstream_request_log
  • 本地同步业务类型：STATIC_SYNC_NODE
  • 本地同步接口名：StaticProxyAssetSync
  • 齐云接口请求失败仍由 QiYunApiSupport 自动记录原始接口日志。
  • 本地失败场景包括资产商品缺失、上游供应商缺失、上游返回节点无法匹配、本地资产更新失败等。
  • 批量同步和定时同步中单资产失败会沉淀日志，不中断其它资产同步。
  • 本地同步成功也会写入 STATIC_SYNC_NODE 成功日志，用于覆盖旧失败状态。
• 会员前台 v2 批量购买下单链路已联动后端：
  • MemberStaticRegionInventoryVO 已补充 qiyunIsp，用于前台运营商筛选和订单快照。
  • MemberStaticPackagePurchaseForm 已支持 items[] 多节点下单参数，每项包含齐云地区、节点、运营商和购买数量。
  • MemberPackageCenterServiceImpl.purchaseStaticPackage 已支持多节点批量下单，事务内逐节点校验库存并创建订单。
  • 批量下单折扣按购物车总购买数量计算，单个节点订单按各自数量拆单。
  • “全部地区”已按随机地区处理，不再向齐云库存/下单接口传 area_id=-1。
  • 代理账号设置已支持随机生成/指定账号；指定账号时校验账号和密码。
  • 端口设置后端仍保留兼容字段，但前台暂不开放指定端口，当前按随机端口提交。
  • QiYunStaticProxyClient 仅在指定账号/指定端口模式下向齐云传 user、pass、port，随机模式不传这些参数。

后台 UI

• 上游供应商页面默认供应商类型已改为 QIYUN。
• 上游供应商默认基础地址已改为 https://www.qiyunip.com。
• 供应商鉴权字段文案已调整为 Header apikey。
• 上游供应商新增表单已按 MVP 调整为齐云优先：
  • 供应商类型下拉只保留 齐云 IP(QIYUN)。
  • 新增默认编码：QIYUN01。
  • 新增默认名称：齐云IP。
  • 新增默认成功码：1。
  • 选择 QIYUN 时会自动兜底填充基础地址和成功码。
• 商品页面新增齐云产品类型选择：
  • 静态长效A (高带宽) staticA
  • 静态长效B（特惠） staticB
  • 住宅长效 home
  • 独享长效 custom
• 商品页面“商品类型”已改文案为“平台商品类型”：
  • STATIC_RESIDENTIAL 显示为“齐云静态长效IP”。
  • DYNAMIC_RESIDENTIAL 显示为“动态住宅IP（预留）”。
  • 齐云具体产品 staticA/staticB/home/custom 不在这里选择，而是在“齐云产品类型”中选择。
• 商品页面新增 上游扩展参数 JSON 输入框。
• 商品页面已新增齐云项目/地区/节点联动选择：
  • 供应商为 QIYUN 且选择齐云产品类型后启用。
  • custom 独享长效自动隐藏/禁用项目选择。
  • 选择项目、地区、节点后自动生成 upstreamParams JSON。
• 静态资产页面已对齐云资产隐藏白名单入口。
• 静态资产页面已对齐云资产新增“调换”按钮和弹窗。
• 调换弹窗已升级为齐云项目/地区/节点联动选择器，同时保留目标节点 ID/名称手动输入兜底。
• 静态资产列表已返回调换节点联动所需字段：
  • upstreamProviderId
  • upstreamProductCode
  • upstreamParams
• 静态资产页面已对齐云资产新增“同步”按钮，可单资产从齐云刷新节点信息。
• 静态资产页面已增加多选和“批量同步”按钮，仅同步选中的齐云资产。
• 静态资产页面已增加“最近同步失败”列：
  • 后端从 xxk_upstream_request_log 聚合每个资产最近一次 STATIC_SYNC_NODE 同步日志。
  • 如果最近一次同步日志为失败，则展示失败原因和时间。
  • 如果失败后又同步成功，则列表不再显示旧失败。
  • 点击失败原因可跳转到上游请求日志页，并自动筛选 STATIC_SYNC_NODE + 失败 + assetId。
  • 失败列已增加“重试同步”按钮，复用单资产同步接口；重试成功后刷新列表并隐藏旧失败。
• 上游请求日志页面已增加业务类型选项：静态节点同步(STATIC_SYNC_NODE)。
• 开放 API 申请审核页“查看账户”跳转路径已统一为 /open-api-manage/open-api-account：
  • 后台静态路由 ProxyOpenApiAccount 已注册在 open-api-manage/open-api-account。
  • 按钮跳转继续携带 memberUserId 和标题参数。
  • proxy/open-api-account/index 是 Vue 组件文件路径，不作为页面访问 URL。
• 会员前台购买闭环 MVP 已补：
  • member-web/src/views/console/BuyView.vue 已从套餐目录读取静态套餐。
  • 支持选择商品、地区、时长、数量。
  • 支持刷新静态库存。
  • 提交后调用 POST /api/v1/member/package-center/static-orders 创建静态订单。
  • 创建成功后逐个调用 POST /api/v1/member/orders/{orderNo}/pay，使用 BALANCE 钱包余额支付。
  • 支付成功后跳转到 /console/static-assets 查看资产。
• 会员前台静态资产页已补实际使用字段：
  • 展示代理地址、端口、账号、密码、协议、地区、状态、到期时间。
  • 支持复制代理地址、账号、密码。
• 会员前台登录/注册方式已接入后台配置：
  • 前台调用 GET /api/v1/member/auth/config 自动读取后台开启的 ACCOUNT/MOBILE/EMAIL。
  • 登录页按 loginMethods 自动展示账号、手机号、邮箱登录 Tab。
  • 注册页按 registerMethods 自动展示账号、手机号、邮箱注册 Tab。
  • 手机号/邮箱如果后台开启验证码，则主表单展示验证码输入和发送按钮；点击发送时弹出图形验证码弹窗，图形验证码正确后再发送手机号/邮箱验证码。
  • 微信小程序登录不适合当前 Web 会员前台，未接入页面展示。
• 上游供应商已增加测试连接能力：
  • 后端：POST /api/v1/proxy/upstream-providers/{id}/test-connection
  • 后台 UI：上游供应商列表新增“测试”按钮。
  • 当前齐云测试连接通过调用 staticA 项目列表接口做轻量探活。
• 商品保存已增加齐云配置强校验：
  • 齐云产品类型必须是 staticA/staticB/home/custom。
  • staticA/staticB/home 必须配置项目 ID：upstreamParams.pid。
  • 所有齐云商品必须配置 upstreamParams.nodeId/nodeValue。
  • upstreamParams 必须是合法 JSON。

用户前台 member-web-v2

• 当前用户前台主开发目录为 member-web-v2。
• 控制台菜单栏已直接暴露四种购买入口：
  • 静态长效A (高带宽)
  • 静态长效B（特惠）
  • 住宅长效
  • 独享长效
• 购买产品菜单图标已改为自定义 SVG 风格，并统一图标尺寸、菜单文字间距和选中态。
• 从购买产品菜单进入购买页时，页面根据路由参数锁定产品类型，并隐藏商品选择组件。
• 购买页标题已从“购买静态代理”调整为“购买代理”。
• 商品下拉和购买时长下拉已替换为前台自定义 SearchSelect 风格组件：
  • 商品下拉支持搜索。
  • 购买时长下拉不启用搜索。
  • SearchSelect 已新增 searchable 开关，默认支持搜索。
• 项目选择已改为“项目分类 + 项目”的布局：
  • 项目分类支持全部、手游、端游、其他。
  • 项目分类默认停留在“全部分类”，不自动选中第一个分类，用户进入购买产品页时先看到全部项目。
  • 项目下拉支持搜索。
  • 省份筛选仅保留“全部地区”，已去除“全部省份”。
• 节点筛选已增加运营商选择，数据来自齐云节点字段 qiyunIsp。
• 购买页已增加代理账号设置：
  • 随机生成。
  • 指定账号。
  • 指定账号时展示账号和密码输入框。
• 端口设置暂时隐藏，当前前台固定提交随机端口模式。
• 节点选择已改为多节点购物车式交互：
  • 节点卡片数量选择器正常常显，居中展示，并加宽可操作区域。
  • 支持一次选择多个节点，并为每个节点设置购买数量。
  • 节点卡片和订单清单中的减少操作最低保留数量 1，不自动删除清单项。
  • 删除清单项需要点击订单清单中的移除按钮。
• 控制台资源入口与静态资产页已统一面向用户显示为“我的代理”，不再在菜单和页面标题中写“静态代理”。
• 控制台顶部搜索栏已从静态输入框改为可用搜索：
  • 支持搜索控制台功能入口并直接跳转。
  • 支持按关键词查询最近订单和我的代理，依赖会员订单列表和静态资产列表的 keywords 参数。
  • 从搜索结果进入“我的订单”或“我的代理”时，会把关键词带到页面并刷新列表。
• 右侧配置区域已改为“订单清单”购物车样式：
  • 展示已选节点、运营商、地区、单项数量。
  • 支持单项数量加减、移除、清空。
  • 汇总节点数量、购买总量和预估金额。
• 前台提交 POST /api/v1/member/package-center/static-orders 时，已通过 items[] 传递多节点下单明细，并继续按返回订单逐笔调用钱包余额支付。
• 购买页、动态资源、官网价格页、帮助页、开放 API 和通知公告等客户可见文案已收缩为面向客户的表达：
  • 无资源时统一使用“无可用资源”方向。
  • 去除“后台配置”“上游接口”“生产接口”“后台审核”等面向开发/运营内部的文案。
• 会员前台客户可见文案约束：
  • member-web-v2 中控制台和官网客户可见页面必须使用面向用户的商业化表达。
  • 避免直接出现“后台、接口、策略、配置、强制、驳回、生产、上游、开发、内部”等面向研发/运营的词。
  • 认证类页面建议使用“服务权限、认证进度、申请编号、处理说明、需补充”等用户可理解表达。
  • 状态失败或资料不通过时，优先表达为“需补充/请重新提交”，避免直接写“驳回”。
• 会员前台品牌与底部内容配置约束：
  • 后台“业务配置管理 -> 站点与资源配置 -> 会员前台站点配置”已有用户前台系统名称、浏览器图标、页面 Logo、客服信息和站点底部富文本。
  • member-web-v2 不应在外壳、标题、Logo、控制台底部等位置继续硬编码品牌信息。
  • 用户前台系统名称、页面 Logo、浏览器标签页 ico 和控制台底部富文本必须优先读取公开接口 GET /api/v1/member/site-config。
  • 接口不可用或字段为空时，前台才使用通用默认值兜底；默认值不能写死为“齐云 IP”。
  • 404 等异常页面的浏览器标签标题也必须走站点配置或通用默认值，不能回落到“齐云 IP”。
  • 菜单栏/侧边栏品牌位只展示配置的站点名称和 Logo，不再显示 Member Console、Proxy Cloud 等英文副标题小字。
• 会员前台站点配置已接入：
  • 新增 member-web-v2/src/stores/site.ts，统一加载 GET /api/v1/member/site-config。
  • 新增 MemberAPI.siteConfig() 和 MemberSiteConfig 类型。
  • 浏览器标题已按“页面名称 - 站点名称”生成，首页为站点名称。
  • 前台默认站点名称已从“齐云 IP”调整为通用默认值“代理云会员中心”，index.html 默认标题同步调整。
  • 浏览器标签页 ico 会使用 siteFaviconUrl 更新 <link rel="icon">。
  • 官网顶部 Logo、官网底部品牌、控制台侧边栏 Logo、移动端 Header Logo、登录/注册品牌位已优先使用 siteLogoUrl/siteName。
  • 控制台底部已优先渲染后台配置的 homeFooterContent 富文本；未配置时显示默认版权文案。
  • 已去除菜单栏、侧边栏和控制台底部默认文案中的 Member Console、Proxy Cloud；404 模板页版权也已改为站点名称。
  • 404 页面挂载后会重新读取站点配置并设置标题为“页面不存在 - 站点名称”。
• 用户控制台实名认证已完成对接：
  • member-web-v2/src/views/console/VerifyView.vue 已从占位 JSON 展示改为真实认证工作流。
  • 页面会读取 GET /api/v1/member/verify/current 返回的当前认证信息和策略字段。
  • 支持展示未提交、待审核、已认证、已驳回状态。
  • 支持按策略展示手机号、真实姓名、身份证号、身份证人像面、身份证国徽面、其他图片辅证。
  • 支持通过 POST /api/v1/files 上传认证图片，并把返回 url 写入认证表单。
  • 提交时调用 POST /api/v1/member/verify/submit，字段对齐后端 MemberVerifySubmitForm。
  • 待审核和已认证状态下页面只读，已驳回状态允许按审核备注重新提交。
  • 用户可见文案已商业化收口：
    • “提交并查看实名审核资料”调整为“完善实名信息，保障账户使用”。
    • “认证策略/强制认证场景/审核状态/认证单号/审核备注/已驳回”等表达已替换为“服务权限/认证进度/申请编号/处理说明/需补充”等用户表达。
• 用户控制台当前会员 ID 字段已按后端参数修正：
  • 后端 MemberCurrentUserVO 返回会员 ID 字段为 userId。
  • member-web-v2/src/api/member.ts 的 CurrentMember 已增加 userId，并保留 id 兼容旧数据。
  • 账户资料页和右上角用户菜单已优先展示 auth.user.userId，再兜底展示 auth.user.id。
• 用户控制台账户资料页认证状态已做前台转义：
  • verifyStatus=0 显示“未提交”。
  • verifyStatus=1 显示“待审核”。
  • verifyStatus=2 显示“已认证”。
  • verifyStatus=3 显示“需补充”。
  • 未知状态显示为 状态 {status}，避免直接裸露数字。

数据库脚本

• 已更新建表脚本：
  • java/sql/mysql/xxk_proxy_platform_v1.sql
  • java/sql/youlai_admin.sql
• 已新增齐云升级脚本：
  • java/sql/mysql/xxk_proxy_qiyun_adapter_upgrade.sql
• 该升级脚本已改为兼容老 MySQL 的 information_schema + PREPARE 判断写法，重复执行时不会因为字段已存在报错。
• 静态资产同步失败日志复用现有 xxk_upstream_request_log，本次不需要新增数据库表或字段。

数据库补丁规则

后续数据库补丁统一按 V01 累计更新。

规则：

• 不再分散新增多个临时补丁文件。
• 后续新增 SQL 变更统一追加到当前齐云适配升级补丁或后续明确命名的 V01 累计补丁中。
• 补丁必须尽量幂等，字段、索引、菜单、配置插入前要先判断是否存在。
• 已遇到的问题：当前 MySQL 版本不支持 ADD COLUMN IF NOT EXISTS，所以字段变更要使用 information_schema 判断后再动态执行。

未完成 / 后续建议

• 2026-06-10 排查补充：
  • 已定位“齐云开通成功，但本地订单仍显示开通中”的主要风险点在 ProxyOrderServiceImpl。
  • 原逻辑在上游返回成功后，如果本地资源落库、续费资产更新、佣金确认、回调等后续步骤抛异常，会进入 markOpenSyncException；但该方法原先只写 remark 和 OPEN_SYNC_FAIL 操作日志，不更新 order_status/open_status，因此订单会停留在支付阶段写入的 OPENING。
  • 现已调整：
    • 订单成功状态、资源落库和订单明细状态更新作为成功主流程提交。
    • 分销佣金确认、开放 API 回调等后置动作失败时只记录 warn，不再回滚订单开通成功状态。
    • 上游已成功但本地资源/资产同步失败时，订单会标记为 OPEN_FAIL，compensation_status=NONE，并写入 compensation_reason/remark 和 OPEN_SYNC_FAIL 日志，避免继续显示“开通中”。
    • 手动退款补偿会拦截 compensation_status=NONE 的同步异常订单，避免对“上游已开通成功”的订单误触发退款。
  • 当前已经卡住的历史订单不会被代码自动修复，建议先按订单号核对：
    • xxk_proxy_order 是否仍为 order_status=OPENING/open_status=OPENING。
    • xxk_order_operate_log 是否已有 OPEN_SYNC_FAIL。
    • xxk_static_proxy_asset 是否已生成该订单资产。
    • xxk_upstream_request_log 中 STATIC_OPEN_ORDER 的齐云响应是否为成功。
  • 若确认资产已生成且可用，可人工将该订单修正为成功；若资产未生成但齐云已开通，需要先按齐云订单号/代理 ID 同步或补录资产，再改订单状态。不要直接对这类订单执行退款补偿。
• 齐云“调换节点”已具备基础可用功能，并已接入项目/地区/节点联动选择器。
• 齐云节点同步已支持单资产手动同步、勾选批量同步、后端按订单同步、定时同步任务、后台失败日志查看、资产列表最近失败提示和失败行内重试。
• 购买闭环 MVP 已补到：会员选择静态套餐 -> 创建订单 -> 钱包余额支付 -> 调齐云开通 -> 生成资产 -> 用户控制台复制使用。
• 后续商业化增强建议：
  • 正式支付通道充值和支付回调验签。
  • 下单/支付按钮防重复提交的后端幂等键。
  • 同步失败告警、独立同步历史页。
  • 齐云余额/上游账户状态监控，如果齐云接口支持。
  • 请求日志定期归档/清理。
• 齐云项目列表、地区列表、节点列表已经接入后台商品配置联动选择器；保留 upstreamParams JSON 文本框用于查看和高级手动调整。
• 齐云白名单和远端自动续费文档未提供接口，当前按“不支持远端能力”处理。
• 动态代理相关旧功能结构仍在系统内，但齐云没有动态通道接口，后续如果接其它支持动态的平台，再新增对应 UpstreamDynamicProxyClient。
• 当前没有 git 管理，不要依赖 git diff / commit 交接；需要通过本文档和文件实际内容继续开发。

验证说明

• 用户已明确：新增代码不需要编译验证。
• 用户已明确：不要启动 member-web-v2 本地 dev 服务。
• 用户已明确：项目当前没有 git，不要依赖 git diff / status / commit 交接，也不要把 git 作为验证步骤。
• 后续交接说明按文件实际内容记录，不要求启动服务或编译。
• 本次后续不再做 Maven / 前端 build 编译验证。
• 之前尝试执行 Maven 时，当前 Windows 沙箱出现 CreateProcessWithLogonW failed: 1326，不是业务代码编译输出。
• 如果本地 npm run dev 页面仍显示 IPNux/IPNUX，当前源码已无该选项，请重启 ui 目录下的 Vite dev 服务并强刷浏览器缓存；旧 ui/dist 里仍有历史构建产物，但 dev 模式不应加载它。