# 开发交接-当前进度说明 ## 1. 当前阶段结论 本项目已完成“代理平台后端一期主骨架”的第一阶段建设，当前进度已经从纯需求设计推进到： - 数据库设计已落文档和 SQL - `proxy` 业务域已建立 - 商品、钱包、订单、静态资产、动态通道、分销等核心实体已建立 - 后台基础管理 API 已补齐第一批 - 订单创建、余额支付、按商品类型分流开通的主链路已搭建 - `IPNux` 已接入第一批真实接口 - 静态代理管理、动态通道管理的后台接口已搭建 - 代理平台后台前端已接入一批正式化页面 当前代码已经具备继续联调和继续扩展的基础，但还不算“可直接上线”状态。 补充说明： - 已完成会员认证策略中心、认证审核闭环、强制认证场景校验 - 已完成订单异常补偿第一阶段闭环： - 支付、上游开通、退款改为分阶段提交 - 上游开通失败后自动进入补偿 - 支持补偿状态跟踪、补偿记录落表、人工重试补偿 - 已完成补偿记录排查视角增强： - 补偿记录详情已联动订单操作日志 - 补偿记录详情已联动钱包流水并高亮当前退款流水 - 订单、静态资产、动态通道已可联动跳转到上游请求日志页 - 已启动会员前台独立站首版骨架： - 新建 `member-web` 独立 Vue3 目录 - 已拆出官网营销布局与会员控制台布局 - 已接入会员登录态、钱包、订单、静态代理、动态通道、实名认证基础页面 ## 2. 已完成内容 ### 2.1 需求与设计文档 已完成以下设计文档： - `需求设计-静态住宅IP代理分销平台-v1.md` - `需求设计-静态+动态住宅IP代理分销平台-v2.md` - `数据库详细设计-代理平台-v1.md` 主要结论： - 一期同时支持静态住宅 IP 和动态住宅 IP - 一期先做后端 - 静态 IP 按国家定价 - 静态/动态都按时长倍率销售，天数为 30 的整数倍 - 动态 IP 按固定流量套餐售卖 - 一期支付只做余额支付 - 一期充值只做后台加款 - 分销佣金按“开通成功金额”计算 - 一期只接 `IPNux`，但架构保留多上游扩展 ### 2.2 数据库设计与 SQL 已完成 SQL 文件： - `java/sql/mysql/xxk_proxy_platform_v1.sql` 当前已设计的核心表包括： - `xxk_upstream_provider` - `xxk_product` - `xxk_product_static_country_price` - `xxk_product_duration_multiplier` - `xxk_product_dynamic_plan` - `xxk_user_profile` - `xxk_wallet_account` - `xxk_wallet_flow` - `xxk_proxy_order` - `xxk_proxy_order_item` - `xxk_static_proxy_asset` - `xxk_static_proxy_whitelist` - `xxk_dynamic_channel` - `xxk_dynamic_channel_traffic_log` - `xxk_dynamic_proxy_generate_log` - `xxk_distribution_relation` - `xxk_distribution_config` - `xxk_distribution_commission` - `xxk_upstream_request_log` - `xxk_order_operate_log` 说明： - 后续对静态/动态管理做更深扩展时，可能还需要补充字段或索引 - 当前 `xxk_product` 已补充 `IPNux` 上游所需关键参数： - `proxies_type` - `proxies_format` - `purpose_web` - `protocols_type` - `udp_status` ### 2.3 后端业务域已建立 已新增业务域： - `java/src/main/java/com/youlai/boot/proxy` 当前已包含： - `controller` - `converter` - `enums` - `integration` - `mapper` - `model/entity` - `model/form` - `model/query` - `model/vo` - `service` - `service/impl` ### 2.4 已完成的核心实体 已完成主要实体类： - `Product` - `ProductStaticCountryPrice` - `ProductDurationMultiplier` - `ProductDynamicPlan` - `UpstreamProvider` - `UserProfile` - `WalletAccount` - `WalletFlow` - `ProxyOrder` - `ProxyOrderItem` - `StaticProxyAsset` - `StaticProxyWhitelist` - `DynamicChannel` - `DynamicChannelTrafficLog` - `DynamicProxyGenerateLog` - `DistributionRelation` - `DistributionConfig` - `DistributionCommission` ### 2.5 已完成的基础后台管理 API 目前已经完成第一批后台管理接口骨架： - 上游供应商管理 - 商品管理 - 静态国家定价管理 - 动态流量套餐管理 - 时长倍率管理 - 钱包账户列表 - 钱包后台加款 对应控制器： - `UpstreamProviderController` - `ProductController` - `ProductStaticCountryPriceController` - `ProductDynamicPlanController` - `ProductDurationMultiplierController` - `WalletAccountController` ### 2.6 已完成的订单主流程 当前订单主链已接通基础业务编排： - 创建订单 - 按商品类型计算销售价 - 余额支付 - 扣减钱包余额 - 写入钱包流水 - 支付成功后调用上游开通 - 根据商品类型分流： - 静态 IP 开通 - 动态通道开通 - 开通成功后回写本地资源表 - 更新订单状态 对应核心类： - `ProxyOrderController` - `ProxyOrderService` - `ProxyOrderServiceImpl` ### 2.7 已完成的 IPNux 对接能力 已接入 IPNux 公共请求支持： - `IPNuxApiSupport` 已实现的 IPNux 能力： #### 静态 IP - 开通下单 `OpenApiPurchaseNewOrder` - 列表查询 `OpenApiNodeList` - 续费 `OpenApiNoneRenew` - 自动续费 `SetAutoRenew` - 节点改密 `OpenApiEditNodeUserAndPass` - 新增白名单 `OpenApiAddWhite` - 删除白名单 `OpenApiDelWhite` #### 动态 IP - 创建通道 `OpenApiCreateChannel` - 通道列表 `OpenApiSubUsers` - 更新通道 `OpenApiEditChannel` - 查询流量 `OpenApiGetUseTraffic` - 生成代理出口 `OpenApiGenerateCustomEndpoints` ### 2.8 已完成的资源管理接口 #### 静态代理管理 已完成： - 静态代理分页列表 - 静态代理续费 - 静态代理改密 - 静态代理自动续费开关 - 静态代理白名单新增 - 静态代理白名单删除 对应控制器： - `StaticProxyAssetController` 对应服务： - `StaticProxyAssetService` - `StaticProxyAssetServiceImpl` #### 动态通道管理 已完成： - 动态通道分页列表 - 按供应商同步通道 - 更新通道 - 查询通道流量 - 生成动态代理出口 对应控制器： - `DynamicChannelManageController` 对应服务： - `DynamicChannelService` - `DynamicChannelServiceImpl` ### 2.9 已完成的会员认证配置与审核闭环 已完成： - 会员认证策略统一收口到 `member.verify.policy` - 后台业务配置中心可配置： - 是否开启认证 - 是否开启强制认证 - 强制认证场景 - 认证字段启用/必填/图片数量限制 - 会员认证提交与后台审核接口 - 会员认证记录快照落库 - 认证通过/驳回结果回写会员资料表 - 已接入强制认证场景校验： - 会员下单 - 静态白名单新增 - 动态代理出口生成 对应 SQL： - `java/sql/mysql/xxk_member_verify_upgrade.sql` - `java/sql/mysql/xxk_member_verify_menu_init.sql` ### 2.10 已完成的订单异常补偿第一阶段闭环 已完成： - 订单支付、上游开通、退款补偿拆分为分阶段事务提交 - 上游开通失败后自动进入退款补偿流程 - 订单主表增加补偿状态、补偿说明、重试次数、最近补偿时间 - 新增订单补偿记录表，保留每次补偿尝试结果 - 退款增加幂等判断，已存在退款流水时自动补齐订单状态 - 新增后台“重试订单补偿”接口 - 新增订单补偿失败自动重试定时任务 - 补偿定时任务支持基础配置： - 是否启用 - Cron 表达式 - 单次批量处理数 - 最大尝试次数 - 最小重试间隔分钟数 - 后台订单页已接入： - 补偿状态筛选 - 补偿状态/补偿说明/重试次数展示 - 手动重试补偿入口 - 已新增订单补偿记录分页接口 - 已新增后台“订单补偿记录”页面 - 已支持从订单页直接跳转到对应订单的补偿记录页 对应 SQL： - `java/sql/mysql/xxk_proxy_order_compensation_upgrade.sql` - `java/sql/mysql/xxk_proxy_order_compensation_record_menu_upgrade.sql` ### 2.11 已完成的会员管理认证状态接入 已完成： - 会员列表支持按认证状态筛选 - 会员列表增加认证状态、实名信息、最近提交/通过时间展示 - 会员编辑页增加认证概况区域 - 可从会员管理页直接跳转到认证审核页 - 认证审核页支持按 `memberUserId` 过滤，承接会员页跳转 - 后台手工新增会员时同步初始化 `MemberProfile` ### 2.12 已完成的上游请求日志与失败排查基础能力 已完成： - `IPNuxApiSupport` 统一记录所有 IPNux 请求日志 - 记录内容包括： - 请求地址 - 请求头 - 请求体 - 响应体 - HTTP 状态码 - 业务码 - 成功标记 - 耗时 - 错误信息 - 后台新增上游请求日志分页查询接口 - 后台新增上游请求日志详情接口 - 后台新增“上游请求日志”排查页面 - 日志按业务类型区分静态开通、白名单、动态通道、流量查询、动态出口生成等请求 - 上游日志关键字查询已扩展到请求体、响应体、请求头 - 已支持从以下页面联动跳转到上游日志页： - 订单管理 - 静态代理管理 - 动态通道管理 - 上游日志页已支持承接路由查询参数自动筛选 对应 SQL： - `java/sql/mysql/xxk_proxy_upstream_request_log_menu_upgrade.sql` ### 2.13 已完成的补偿记录联动排查能力 已完成： - 补偿记录详情抽屉已支持联动查询订单操作日志 - 补偿记录详情抽屉已支持联动查询钱包流水 - 补偿记录详情可高亮当前补偿关联退款流水 - 联动接口复用补偿记录页权限，无需新增额外菜单 - 当前作为最小可用排查中枢，暂未单独拆订单操作日志页和钱包流水页 ### 2.14 已完成的会员前台独立站首版骨架 已完成： - 新建独立目录 `member-web` - 基于 Vue3 + Vite + TypeScript 搭建会员前台骨架 - 已拆分两套前端布局： - 官网营销布局 - 会员控制台布局 - 已接入会员登录态基础能力： - 账号密码登录 - 短信验证码登录 - 当前会员信息获取 - 令牌自动续期基础逻辑 - 已完成首批前台页面骨架： - 首页 - 套餐购买页 - 帮助中心 - 登录页 - 控制台首页 - 我的订单 - 静态代理 - 动态通道 - 我的钱包 - 实名认证 - 已直接对接现有会员接口： - 登录 - 钱包概况 - 订单分页 - 静态代理分页 - 动态通道分页 - 认证策略 / 当前认证信息 / 认证提交 当前说明： - 套餐购买页当前为前台正式化展示骨架，尚未接真实商品价格接口 - 下一步需要补会员侧商品、国家价格、时长倍率、动态套餐接口，才能形成完整购买闭环 ## 3. 当前代码状态 ### 3.1 已经具备的能力 当前代码已经具备： - 商品配置 - 静态国家价格配置 - 动态流量套餐配置 - 时长倍率配置 - 钱包加款 - 创建订单 - 余额支付 - 调用 IPNux 开通 - 开通后本地落资产/通道 - 静态代理基础管理 - 动态通道基础管理 - 订单补偿记录排查与补偿执行追踪 - 上游请求日志联动排查 ### 3.2 当前仍属于“开发中”的部分 虽然主骨架已经有了，但仍有以下现实情况： - AI 侧本轮未执行真实编译校验 - 未做完整联调验证 - 菜单 SQL 已有基础版本，但后续新增功能仍需继续补升级脚本 - 后台前端已接入一批页面，但分销等页面仍未补齐 - 未做补偿定时任务、同步任务、统计/看板类日志任务 - 未做完整分销佣金结算逻辑 ### 3.3 当前环境限制 当前开发环境里： - 用户本地已经可以正常执行 SQL 与编译 - AI 侧默认不主动执行编译，若后续需要可按需再做编译排错 所以下次继续开发时，建议继续沿用“本地编译 + 我负责改代码与排错”的协作方式。 ## 4. 待完成内容 以下内容按优先级分组。 ### 4.1 高优先级 #### A. 菜单权限与初始化数据 当前代理平台基础菜单 SQL 已存在，会员认证菜单和上游请求日志菜单升级 SQL 也已补齐。 后续仍需要随着新功能继续补菜单/按钮升级 SQL，例如： - 订单补偿记录页及按钮权限 - 上游日志和订单/资产/通道联动入口权限 - 分销管理相关菜单及按钮权限 - 后续会员前台独立系统的后台配置菜单 建议新增： - 按功能增量维护菜单升级 SQL - 需要时补一份演示角色授权 SQL #### B. 订单异常补偿后续增强 当前已经完成自动退款、补偿状态、补偿记录、人工重试和定时自动重试。 后续还建议继续补： - 更细的告警通知（如补偿失败短信/站内消息/日志告警） #### C. 真实联调校验 当前虽然已经接入 `IPNux` 接口，但还需要做真实联调： - 静态下单时 `buyData` 是否接受 `country_code` - `purpose_web` 字段真实类型 - 成功码集合是否稳定 - `SetAutoRenew` 请求字段是否完全一致 - 动态通道创建后的返回字段结构 - 通道流量字段 `UseTrafficGb` / `TotalTrafficGb` 真实格式 ### 4.2 中优先级 #### A. 分销佣金逻辑补全 当前只做了表结构和订单中的邀请人字段预留，还没有真正写佣金计算与确认。 需要补： - 下单时读取分销配置 - 开通成功后生成一级佣金 - 开通成功后生成二级佣金 - 退款或失败时佣金失效 - 佣金流水查询接口 #### B. 静态代理更多管理能力 当前已做基础管理，但还可继续补： - 静态代理详情页接口 - 批量续费 - 批量自动续费开关 - 批量改密 - 静态资产同步任务 - 静态代理详情接口 `OpenApiNodeDetail` #### C. 动态代理更多管理能力 当前已做基础管理，但还可继续补： - 动态通道详情接口 - 动态通道周期性同步任务 - 动态流量时间序列展示接口 - 代理生成结果结构化解析 - 动态端点生成日志查询接口 ### 4.3 后续阶段 #### A. 前端后台对接 当前 `ui` 目录已经接入了代理平台一批后台页面，并且已经做过一轮去示例化和正式化处理。 建议后续新增： - 订单管理页面 - 分销管理页面 - 会员前台独立站点（后续阶段再拆） #### B. 定时任务 后续建议补充： - 静态资产同步任务 - 动态通道同步任务 - 到期提醒任务 - 自动续费任务 - 失败补偿任务 #### C. 上游日志后续增强 当前已经补了统一请求日志记录与基础排查页面。 后续建议继续补： - 失败日志快捷筛选与看板统计 - 脱敏规则细化（不同字段不同脱敏级别） - 长响应体压缩或分片策略 ## 5. 关键代码位置索引 ### 5.1 数据库与文档 - `数据库详细设计-代理平台-v1.md` - `java/sql/mysql/xxk_proxy_platform_v1.sql` ### 5.2 订单主流程 - `java/src/main/java/com/youlai/boot/proxy/controller/ProxyOrderController.java` - `java/src/main/java/com/youlai/boot/proxy/service/ProxyOrderService.java` - `java/src/main/java/com/youlai/boot/proxy/service/impl/ProxyOrderServiceImpl.java` ### 5.3 IPNux 对接 - `java/src/main/java/com/youlai/boot/proxy/integration/ipnux/IPNuxApiSupport.java` - `java/src/main/java/com/youlai/boot/proxy/integration/ipnux/IPNuxStaticProxyClient.java` - `java/src/main/java/com/youlai/boot/proxy/integration/ipnux/IPNuxDynamicProxyClient.java` - `java/src/main/java/com/youlai/boot/proxy/integration/core/impl/UpstreamProviderFacadeImpl.java` ### 5.4 静态代理管理 - `java/src/main/java/com/youlai/boot/proxy/controller/StaticProxyAssetController.java` - `java/src/main/java/com/youlai/boot/proxy/service/impl/StaticProxyAssetServiceImpl.java` ### 5.5 动态通道管理 - `java/src/main/java/com/youlai/boot/proxy/controller/DynamicChannelManageController.java` - `java/src/main/java/com/youlai/boot/proxy/service/impl/DynamicChannelServiceImpl.java` ### 5.6 商品和价格管理 - `java/src/main/java/com/youlai/boot/proxy/controller/ProductController.java` - `java/src/main/java/com/youlai/boot/proxy/controller/ProductStaticCountryPriceController.java` - `java/src/main/java/com/youlai/boot/proxy/controller/ProductDynamicPlanController.java` - `java/src/main/java/com/youlai/boot/proxy/controller/ProductDurationMultiplierController.java` ### 5.7 钱包管理 - `java/src/main/java/com/youlai/boot/proxy/controller/WalletAccountController.java` - `java/src/main/java/com/youlai/boot/proxy/service/impl/WalletAccountServiceImpl.java` ### 5.8 会员前台独立站 - `member-web/package.json` - `member-web/src/router/index.ts` - `member-web/src/layouts/MarketingLayout.vue` - `member-web/src/layouts/ConsoleLayout.vue` - `member-web/src/views/marketing/HomeView.vue` - `member-web/src/views/marketing/PricingView.vue` - `member-web/src/views/account/LoginView.vue` - `member-web/src/views/console/DashboardView.vue` - `member-web/src/views/console/VerifyView.vue` ## 6. 下次继续开发建议顺序 下次继续开发，建议按下面顺序推进： 1. 先做 IPNux 真实联调修正 2. 再补更细的补偿告警通知 3. 再做上游日志失败筛选、统计看板与脱敏细化 4. 再补分销佣金结算逻辑 5. 最后再做会员前台认证提交页面和会员端独立前端 如果要直接接着当前进度往下做，建议优先从“IPNux 真实联调修正”开始。 ## 7. 继续开发时的提醒 - 当前很多接口骨架已经有了，不要重复新建第二套目录或第二套业务域 - 后续扩展尽量沿用 `proxy` 业务域 - 商品上游参数不要再拆散，统一由 `xxk_product` 承载 - 静态与动态的交易层可以统一，但资源层不要强行合并 - 继续开发前优先同步最新 SQL / 菜单升级脚本，并按当前协作方式由用户本地完成编译验证