第一次上传

2026-06-11 10:31:24 +08:00
commit cfef094568
1523 changed files with 210650 additions and 0 deletions
@@ -0,0 +1,610 @@
+# 开发交接-当前进度说明
+
+## 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 / 菜单升级脚本，并按当前协作方式由用户本地完成编译验证