# Team Plan: 同步私有版剩余功能到 OSS

源目录：`/Users/Apple/vpn/ppanel-server`（私有版）
目标目录：`/Users/Apple/code_vpn/vpn/ppanel-server`（开源版）
方向：私有版功能 → 开源版（保留开源版改进）

---

## Layer 1（并行）

### Builder-1: 路由与服务上下文（高复杂度）

**文件范围：**
- `internal/handler/routes.go`
- `internal/svc/serviceContext.go`

**任务：routes.go**
1. 读取私有版 routes.go，识别以下需要添加的路由组：
   - Apple IAP 路由组：`/v1/public/iap/apple`（status, attach, restore）
   - Email login 路由：`POST /auth/login/email`
   - Error log report 路由：`POST /common/log/message/report`
   - Contact 路由：`POST /common/contact`
   - Bind email with verification：`POST /public/user/bind_email_verification`
   - Bind invite code：`POST /public/user/bind_invite_code`
   - Subscribe status：`GET /public/user/subscribe/status`
   - Agent stats/downloads/sales 路由
   - Delete account：`POST /public/user/delete_account`
   - Admin error log routes：`GET /admin/log/message/error/list`, `/detail`
2. 保留 OSS 已有路由（Redemption、WS、heartbeat、reset_token、reset_traffic、toggle_status、IP location、module config 等）
3. 不添加 App Version 路由（`/admin/application/version`、`/common/app/version`）
4. 不添加 Server migration 路由

**任务：serviceContext.go**
1. 添加 import：`logmessage`、`iapapple` model 包
2. 在 ServiceContext struct 中添加字段：
   - `LogMessageModel logmessage.Model`
   - `IAPAppleTransactionModel iapapple.Model`
3. 在 NewServiceContext 中初始化这些字段
4. 保留 OSS 已有字段（GeoIP、RedemptionCodeModel、RedemptionRecordModel、Redis 扩展配置）
5. 不添加 SessionLimit() 和 EnforceUserSessionLimit() 方法（设备绑定相关）

**验收标准：**
- `go build ./...` 编译通过
- 所有新路由正确注册
- 不包含设备绑定和 App 版本管理路由

---

### Builder-2: 认证与注册逻辑（中复杂度）

**文件范围：**
- `internal/logic/auth/userRegisterLogic.go`
- `internal/logic/common/sendEmailCodeLogic.go`
- `internal/middleware/deviceMiddleware.go`

**任务：userRegisterLogic.go**
1. 添加邮箱规范化：`req.Email = strings.ToLower(strings.TrimSpace(req.Email))`（在函数开头）
2. 保留 OSS 已有改进：IP 限流检查、已删除用户检查、activeTrial 返回 Subscribe 对象、事务外清缓存
3. 不添加 bypass code（`"202511"`）
4. 不添加 DeviceBindLimitExceeded 错误处理

**任务：sendEmailCodeLogic.go**
1. 添加邮箱规范化：`req.Email = strings.ToLower(strings.TrimSpace(req.Email))`
2. 添加动态验证码过期时间：从 `l.svcCtx.Config.VerifyCode.ExpireTime` 读取，默认 900 秒，转换为分钟
3. Redis TTL 使用配置的过期时间而非硬编码
4. 保留 OSS 已有的 Security type 手机绑定检查
5. 不添加 DeleteAccount 邮件类型

**任务：deviceMiddleware.go**
1. 统一常量名：`constant.LoginType` → `constant.CtxLoginType`
2. 移除多余 debug 日志

**验收标准：**
- 邮箱注册/验证码发送时自动 trim 和 lowercase
- 验证码过期时间可配置
- 编译通过

---

### Builder-3: 管理后台逻辑（中复杂度）

**文件范围：**
- `internal/logic/admin/user/getUserListLogic.go`
- `internal/logic/admin/user/updateUserBasicInfoLogic.go`
- `internal/logic/admin/payment/createPaymentMethodLogic.go`

**任务：getUserListLogic.go**
1. 读取私有版，添加批量获取活跃订阅逻辑（FindActiveSubscribesByUserIds）
2. 添加 MemberStatus 计算（基于订阅到期时间判断）
3. 添加 LastLoginTime 展示
4. 保留 OSS 的 Unscoped 和 ShortCode 查询参数
5. 不添加 DeviceId 过滤

**任务：updateUserBasicInfoLogic.go**
1. 读取私有版，添加 Remark 字段更新支持
2. 添加 MemberStatus 更新支持（如果有）
3. 保留 OSS 的错误处理模式（非 fmt.Sprintf 包装）
4. 考虑使用事务包裹所有修改（参考私有版 Transaction 用法）

**任务：createPaymentMethodLogic.go**
1. 对比两版差异，同步私有版中有用的改动

**验收标准：**
- 管理员用户列表显示 MemberStatus 和 LastLoginTime
- 编译通过

---

### Builder-4: 服务器、Handler 和模型修复（低-中复杂度）

**文件范围：**
- `internal/server.go`
- `internal/handler/notify.go`
- `internal/handler/subscribe.go`
- `internal/logic/server/constant.go`
- `internal/logic/subscribe/subscribeLogic.go`
- `initialize/config.go`
- `initialize/init.go`
- `cmd/run.go`
- `internal/model/subscribe/subscribe.go`
- `internal/model/order/model.go`
- `internal/model/announcement/model.go`
- `internal/model/log/log.go`
- `internal/model/user/model.go`
- `internal/types/subscribe.go`
- `pkg/constant/version.go`
- `internal/svc/devce.go`
- `internal/logic/server/serverPushUserTrafficLogic.go`
- `queue/logic/traffic/trafficStatisticsLogic.go`
- `internal/logic/public/subscribe/queryUserSubscribeNodeListLogic.go`
- `internal/logic/public/user/resetUserSubscribeTokenLogic.go`

**任务说明：**
以上大部分文件 OSS 版本已经是正确/更好的版本。Builder 需要：
1. 逐一 diff 对比，确认 OSS 版本是否完整
2. 对于已经正确的文件，跳过不做修改
3. 对于需要微调的文件（如 handler/notify.go 的路由路径斜杠修复），进行小修改
4. server.go：确认 OSS 有 gateway mode，保持不变
5. initialize/config.go、init.go：确认 OSS 有 gateway mode + Currency 调用，保持不变
6. cmd/run.go：确认 trace/init 已移至 server.go，保持不变
7. handler/notify.go：修复路由路径 `:platform/:token` → `/:platform/:token`（如果 OSS 已修复则跳过）
8. svc/devce.go：确认 `create_at` → `created_at` bug fix 已应用

**验收标准：**
- 所有文件状态正确
- 编译通过
- 不引入回退（不把 OSS 改进覆盖回去）

---

## 排除项（不同步）

- App 版本管理路由和逻辑
- 设备绑定相关：SessionLimit、EnforceUserSessionLimit、DeviceId context、DeviceBindLimitExceeded
- adapter/adapter.go、adapter/client.go（保留 OSS 的 Type/Params 改进）
- internal/model/user/default.go（保留 OSS 的软删除改进）
- pkg/payment/stripe/stripe.go（保留 OSS 的 ConstructEventWithOptions 改进）
- getDeviceListLogic.go、unbindDeviceLogic.go（设备绑定）
- authMethod.go（设备绑定 DeleteUserAuthMethodByIdentifier）
- device.go model（设备绑定增强）
- constant/types.go（DeleteAccount 枚举 - 设备绑定）
- device/device.go（GetOnlineDeviceLoginTime - 设备绑定）

---

## 依赖关系

Layer 1 所有 Builder 可并行执行，无互相依赖。