xxk/xxk-proxy

Fork 0

Files

T

xxk cfef094568 第一次上传

2026-06-11 10:31:24 +08:00

17 KiB

Raw Permalink Blame History

开发交接-当前进度说明

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. 下次继续开发建议顺序

下次继续开发，建议按下面顺序推进：

先做 IPNux 真实联调修正
再补更细的补偿告警通知
再做上游日志失败筛选、统计看板与脱敏细化
再补分销佣金结算逻辑
最后再做会员前台认证提交页面和会员端独立前端

如果要直接接着当前进度往下做，建议优先从“IPNux 真实联调修正”开始。

7. 继续开发时的提醒

当前很多接口骨架已经有了，不要重复新建第二套目录或第二套业务域
后续扩展尽量沿用 proxy 业务域
商品上游参数不要再拆散，统一由 xxk_product 承载
静态与动态的交易层可以统一，但资源层不要强行合并
继续开发前优先同步最新 SQL / 菜单升级脚本，并按当前协作方式由用户本地完成编译验证

17 KiB Raw Permalink Blame History Unescape Escape

开发交接-当前进度说明

1. 当前阶段结论

2. 已完成内容

2.1 需求与设计文档

2.2 数据库设计与 SQL

2.3 后端业务域已建立

2.4 已完成的核心实体

2.5 已完成的基础后台管理 API

2.6 已完成的订单主流程

2.7 已完成的 IPNux 对接能力

静态 IP

动态 IP

2.8 已完成的资源管理接口

静态代理管理

动态通道管理

2.9 已完成的会员认证配置与审核闭环

2.10 已完成的订单异常补偿第一阶段闭环

2.11 已完成的会员管理认证状态接入

2.12 已完成的上游请求日志与失败排查基础能力

2.13 已完成的补偿记录联动排查能力

2.14 已完成的会员前台独立站首版骨架

3. 当前代码状态

3.1 已经具备的能力

3.2 当前仍属于“开发中”的部分

3.3 当前环境限制

4. 待完成内容

4.1 高优先级

A. 菜单权限与初始化数据

B. 订单异常补偿后续增强

C. 真实联调校验

4.2 中优先级

A. 分销佣金逻辑补全

B. 静态代理更多管理能力

C. 动态代理更多管理能力

4.3 后续阶段

A. 前端后台对接

B. 定时任务

C. 上游日志后续增强

5. 关键代码位置索引

5.1 数据库与文档

5.2 订单主流程

5.3 IPNux 对接

5.4 静态代理管理

5.5 动态通道管理

5.6 商品和价格管理

5.7 钱包管理

5.8 会员前台独立站

6. 下次继续开发建议顺序

7. 继续开发时的提醒

17 KiB

Raw Permalink Blame History