xxk-proxy/原系统说明书.md

# 开发交接-当前进度说明

## 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 / 菜单升级脚本，并按当前协作方式由用户本地完成编译验证