# 开发交接 - 当前进度说明 更新时间：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` 用于保存齐云差异参数，例如： ```json { "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` 更新 ``。 - 官网顶部 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 模式不应加载它。