1728 lines
50 KiB
Markdown
1728 lines
50 KiB
Markdown
# App 下载分享页 — 实施计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 实现 App 下载分享页的完整自动同步链路：uni-admin 发布版本 → uniCloud 云函数 push → Go Backend upsert → HTML 分享页读取展示
|
||
|
||
**Architecture:** Go Backend 三层架构（controller → service → repository），gateway 直连 PG（无 Dubbo RPC），uniCloud 云函数 HTTP push 触发同步，HTML 静态页 fetch API 渲染下载按钮
|
||
|
||
**Tech Stack:** Go 1.25 + Gin + GORM + PostgreSQL · uniCloud 云函数 (Node.js) · 原生 HTML/CSS/JS · uni-admin (Vue 2，独立仓库)
|
||
|
||
**Spec:** `docs/specs/2026-07-08-app-download-page-design.md`
|
||
|
||
---
|
||
|
||
## 文件清单
|
||
|
||
### 新增文件（本仓库）
|
||
|
||
| # | 文件 | 职责 |
|
||
|---|------|------|
|
||
| 1 | `backend/migrations/2026_07_08_001_app_download_configs.sql` | 建表 + 序列初始化 |
|
||
| 2 | `backend/pkg/models/app_download_config.go` | GORM model + 包类型常量 |
|
||
| 3 | `backend/gateway/repository/app_download_repository.go` | 数据层：FindByType + UpsertAll |
|
||
| 4 | `backend/gateway/repository/app_download_repository_test.go` | Repository 单元测试 |
|
||
| 5 | `backend/gateway/service/app_download_service.go` | 业务层：GetAllNativeApp + SyncVersion（含请求 DTO） |
|
||
| 6 | `backend/gateway/service/app_download_service_test.go` | Service 单元测试 |
|
||
| 7 | `backend/gateway/controller/app_download_controller.go` | Handler：GetDownloadUrls + SyncVersion（含 Swagger 注解） |
|
||
| 8 | `backend/gateway/controller/app_download_controller_test.go` | Controller 集成测试 |
|
||
| 9 | `frontend/static/html/download.html` | HTML 分享下载页 |
|
||
|
||
### 修改文件（本仓库）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 10 | `backend/gateway/router/router.go` | 三层装配 + 注册 2 条路由 |
|
||
|
||
### 独立仓库（uni-admin，不在本仓库）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 11 | `uniCloud-alipay/cloudfunctions/sync-download-urls/index.js` | 云函数主逻辑 |
|
||
| 12 | `uniCloud-alipay/cloudfunctions/sync-download-urls/package.json` | 云函数配置 |
|
||
| 13 | `uni_modules/uni-upgrade-center/pages/version/add.vue` | submitForm 后触发同步 |
|
||
|
||
---
|
||
|
||
## 阶段 A：Go Backend 基础设施（Task 1-4）
|
||
|
||
### Task 1: 数据库 Migration
|
||
|
||
**Files:**
|
||
- Create: `backend/migrations/2026_07_08_001_app_download_configs.sql`
|
||
|
||
- [ ] **Step 1: 编写 migration SQL**
|
||
|
||
```sql
|
||
-- App 下载页配置表
|
||
-- 存储各平台最新下载地址，由 uniCloud 云函数自动同步
|
||
-- type 区分 native_app（整包安装）和 wgt（热更新资源包）
|
||
|
||
CREATE TABLE IF NOT EXISTS public.app_download_configs (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
platform VARCHAR(20) NOT NULL,
|
||
type VARCHAR(20) NOT NULL DEFAULT 'native_app',
|
||
download_url TEXT NOT NULL,
|
||
version VARCHAR(50),
|
||
created_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
|
||
updated_at BIGINT NOT NULL DEFAULT (EXTRACT(EPOCH FROM NOW()) * 1000)::BIGINT,
|
||
|
||
CONSTRAINT uq_app_download_configs_platform_type UNIQUE (platform, type)
|
||
);
|
||
|
||
COMMENT ON TABLE public.app_download_configs IS 'App 下载页配置，存储各平台最新下载地址';
|
||
COMMENT ON COLUMN public.app_download_configs.platform IS '平台标识：android / ios';
|
||
COMMENT ON COLUMN public.app_download_configs.type IS '包类型：native_app（整包安装）/ wgt（热更新资源包）';
|
||
COMMENT ON COLUMN public.app_download_configs.download_url IS '下载地址或 App Store 链接';
|
||
COMMENT ON COLUMN public.app_download_configs.version IS '版本号，如 1.0.5';
|
||
|
||
-- 预留序列起始值（按项目规范）
|
||
ALTER SEQUENCE public.app_download_configs_id_seq RESTART WITH 10000;
|
||
```
|
||
|
||
- [ ] **Step 2: 执行 migration**
|
||
|
||
```bash
|
||
psql -h <host> -U <user> -d topfans -f backend/migrations/2026_07_08_001_app_download_configs.sql
|
||
```
|
||
|
||
预期输出：`CREATE TABLE` + `COMMENT` × 5 + `ALTER SEQUENCE`
|
||
|
||
- [ ] **Step 3: 验证表结构**
|
||
|
||
```sql
|
||
\d public.app_download_configs
|
||
```
|
||
|
||
预期：id (BIGSERIAL), platform (VARCHAR(20)), type (VARCHAR(20)), download_url (TEXT), version (VARCHAR(50)), created_at (BIGINT), updated_at (BIGINT), 以及 UNIQUE 约束 `uq_app_download_configs_platform_type`
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add backend/migrations/2026_07_08_001_app_download_configs.sql
|
||
git commit -m "feat: add app_download_configs migration
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Go Model
|
||
|
||
**Files:**
|
||
- Create: `backend/pkg/models/app_download_config.go`
|
||
|
||
- [ ] **Step 1: 编写 GORM model**
|
||
|
||
```go
|
||
package models
|
||
|
||
// AppDownloadConfig App下载页配置表模型
|
||
type AppDownloadConfig struct {
|
||
ID int64 `gorm:"primaryKey;autoIncrement;column:id" json:"-"`
|
||
Platform string `gorm:"type:varchar(20);uniqueIndex:uq_platform_type;not null;column:platform" json:"platform"`
|
||
Type string `gorm:"type:varchar(20);uniqueIndex:uq_platform_type;not null;default:native_app;column:type" json:"type"`
|
||
DownloadURL string `gorm:"type:text;not null;column:download_url" json:"download_url"`
|
||
Version string `gorm:"type:varchar(50);column:version" json:"version"`
|
||
CreatedAt int64 `gorm:"column:created_at" json:"created_at"`
|
||
UpdatedAt int64 `gorm:"column:updated_at" json:"updated_at"`
|
||
}
|
||
|
||
// TableName 指定表名
|
||
func (AppDownloadConfig) TableName() string {
|
||
return "app_download_configs"
|
||
}
|
||
|
||
// 包类型常量
|
||
const (
|
||
AppPackageTypeNativeApp = "native_app" // 整包安装
|
||
AppPackageTypeWgt = "wgt" // 热更新资源包
|
||
)
|
||
```
|
||
|
||
- [ ] **Step 2: 验证 model 编译通过**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./...
|
||
```
|
||
|
||
预期：编译成功（model 被其他包引用，单独编译可能无输出，用 `go vet` 校验语法）
|
||
|
||
```bash
|
||
cd backend/gateway && go vet ./...
|
||
```
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/pkg/models/app_download_config.go
|
||
git commit -m "feat: add AppDownloadConfig model and package type constants
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Repository 层
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/repository/app_download_repository.go`
|
||
|
||
- [ ] **Step 1: 编写 Repository**
|
||
|
||
```go
|
||
package repository
|
||
|
||
import (
|
||
"context"
|
||
|
||
"gorm.io/gorm"
|
||
"github.com/topfans/backend/pkg/models"
|
||
)
|
||
|
||
// AppDownloadRepository 下载配置数据访问层
|
||
type AppDownloadRepository struct {
|
||
db *gorm.DB
|
||
}
|
||
|
||
// NewAppDownloadRepository 构造函数
|
||
func NewAppDownloadRepository(db *gorm.DB) *AppDownloadRepository {
|
||
return &AppDownloadRepository{db: db}
|
||
}
|
||
|
||
// FindByType 按包类型查询（用于公开接口，只返回 native_app）
|
||
func (r *AppDownloadRepository) FindByType(ctx context.Context, pkgType string) ([]models.AppDownloadConfig, error) {
|
||
var configs []models.AppDownloadConfig
|
||
err := r.db.WithContext(ctx).
|
||
Where("type = ?", pkgType).
|
||
Find(&configs).Error
|
||
return configs, err
|
||
}
|
||
|
||
// UpsertAll 批量 upsert（platform + type 唯一）
|
||
func (r *AppDownloadRepository) UpsertAll(ctx context.Context, configs []models.AppDownloadConfig) error {
|
||
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
||
for _, cfg := range configs {
|
||
if err := tx.Where("platform = ? AND type = ?", cfg.Platform, cfg.Type).
|
||
Assign(map[string]interface{}{
|
||
"download_url": cfg.DownloadURL,
|
||
"version": cfg.Version,
|
||
"updated_at": cfg.UpdatedAt,
|
||
}).
|
||
FirstOrCreate(&cfg).Error; err != nil {
|
||
return err
|
||
}
|
||
}
|
||
return nil
|
||
})
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 编译验证**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./repository/
|
||
```
|
||
|
||
预期：编译成功
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/repository/app_download_repository.go
|
||
git commit -m "feat: add AppDownloadRepository with FindByType and UpsertAll
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Service 层
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/service/app_download_service.go`
|
||
|
||
- [ ] **Step 1: 编写 Service**
|
||
|
||
```go
|
||
package service
|
||
|
||
import (
|
||
"context"
|
||
"time"
|
||
|
||
"github.com/topfans/backend/gateway/repository"
|
||
"github.com/topfans/backend/pkg/models"
|
||
)
|
||
|
||
// SyncVersionRequest uniCloud 同步请求体
|
||
// 注：定义在 service 包（而非 controller 包），避免 controller ↔ service 循环依赖
|
||
type SyncVersionRequest struct {
|
||
Android *PlatformVersionInfo `json:"android"`
|
||
IOS *PlatformVersionInfo `json:"ios"`
|
||
}
|
||
|
||
// PlatformVersionInfo 单个平台的版本信息
|
||
type PlatformVersionInfo struct {
|
||
URL string `json:"url" binding:"required"`
|
||
Version string `json:"version"`
|
||
Type string `json:"type" binding:"required,oneof=native_app wgt"`
|
||
}
|
||
|
||
// AppDownloadService App下载页业务逻辑
|
||
type AppDownloadService struct {
|
||
repo *repository.AppDownloadRepository
|
||
}
|
||
|
||
// NewAppDownloadService 构造函数
|
||
func NewAppDownloadService(repo *repository.AppDownloadRepository) *AppDownloadService {
|
||
return &AppDownloadService{repo: repo}
|
||
}
|
||
|
||
// GetAllNativeApp 获取所有 native_app 类型的下载配置
|
||
func (s *AppDownloadService) GetAllNativeApp(ctx context.Context) ([]models.AppDownloadConfig, error) {
|
||
return s.repo.FindByType(ctx, models.AppPackageTypeNativeApp)
|
||
}
|
||
|
||
// SyncVersion 同步版本信息（upsert）
|
||
func (s *AppDownloadService) SyncVersion(ctx context.Context, req *SyncVersionRequest) error {
|
||
now := time.Now().UnixMilli()
|
||
var configs []models.AppDownloadConfig
|
||
|
||
if req.Android != nil {
|
||
configs = append(configs, models.AppDownloadConfig{
|
||
Platform: "android",
|
||
Type: req.Android.Type,
|
||
DownloadURL: req.Android.URL,
|
||
Version: req.Android.Version,
|
||
UpdatedAt: now,
|
||
})
|
||
}
|
||
if req.IOS != nil {
|
||
configs = append(configs, models.AppDownloadConfig{
|
||
Platform: "ios",
|
||
Type: req.IOS.Type,
|
||
DownloadURL: req.IOS.URL,
|
||
Version: req.IOS.Version,
|
||
UpdatedAt: now,
|
||
})
|
||
}
|
||
|
||
return s.repo.UpsertAll(ctx, configs)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 编译验证**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./service/
|
||
```
|
||
|
||
预期：编译成功
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/service/app_download_service.go
|
||
git commit -m "feat: add AppDownloadService with GetAllNativeApp and SyncVersion
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 B：Controller + 路由注册（Task 5-6）
|
||
|
||
### Task 5: Controller 层
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/controller/app_download_controller.go`
|
||
|
||
- [ ] **Step 1: 编写 Controller**
|
||
|
||
```go
|
||
package controller
|
||
|
||
import (
|
||
"github.com/gin-gonic/gin"
|
||
"github.com/topfans/backend/gateway/pkg/response"
|
||
"github.com/topfans/backend/gateway/service"
|
||
)
|
||
|
||
// DownloadUrlResponse 下载页公开接口响应
|
||
type DownloadUrlResponse struct {
|
||
URL string `json:"url"`
|
||
Version string `json:"version"`
|
||
Type string `json:"type"`
|
||
}
|
||
|
||
// AppDownloadController App下载页控制器
|
||
// 注意：不走 Dubbo RPC（spec §12.5），不依赖 Dubbo client，因此构造函数无需返回 error
|
||
// （与 NewSegmentController / NewLaserGenerateController 等无 Dubbo 依赖的 controller 一致）
|
||
type AppDownloadController struct {
|
||
svc *service.AppDownloadService
|
||
}
|
||
|
||
// NewAppDownloadController 构造函数
|
||
func NewAppDownloadController(svc *service.AppDownloadService) *AppDownloadController {
|
||
return &AppDownloadController{svc: svc}
|
||
}
|
||
|
||
// GetDownloadUrls GET /api/v1/app/download-urls
|
||
// @Summary 获取 App 下载地址
|
||
// @Description 返回 Android/iOS 最新 native_app 下载地址，供 HTML 分享页调用
|
||
// @Tags App下载页
|
||
// @Produce json
|
||
// @Success 200 {object} response.Response{data=map[string]DownloadUrlResponse}
|
||
// @Router /api/v1/app/download-urls [get]
|
||
// 只返回 type = native_app 的记录
|
||
func (ctrl *AppDownloadController) GetDownloadUrls(c *gin.Context) {
|
||
ctx := c.Request.Context()
|
||
configs, err := ctrl.svc.GetAllNativeApp(ctx)
|
||
if err != nil {
|
||
response.InternalError(c, "获取下载地址失败")
|
||
return
|
||
}
|
||
|
||
// 组装响应：map[platform] -> {url, version, type}
|
||
data := make(map[string]interface{})
|
||
for _, cfg := range configs {
|
||
data[cfg.Platform] = &DownloadUrlResponse{
|
||
URL: cfg.DownloadURL,
|
||
Version: cfg.Version,
|
||
Type: cfg.Type,
|
||
}
|
||
}
|
||
// 确保 android/ios 键始终存在
|
||
for _, p := range []string{"android", "ios"} {
|
||
if _, ok := data[p]; !ok {
|
||
data[p] = nil
|
||
}
|
||
}
|
||
|
||
response.Success(c, data)
|
||
}
|
||
|
||
// SyncVersion POST /api/v1/admin/app/versions/sync
|
||
// @Summary 同步 App 下载地址
|
||
// @Description 接收 uniCloud 云函数推送的最新版本下载地址（内部接口，走 Nginx IP 白名单）
|
||
// @Tags Admin
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Param body body service.SyncVersionRequest true "版本信息"
|
||
// @Success 200 {object} response.Response
|
||
// @Router /api/v1/admin/app/versions/sync [post]
|
||
func (ctrl *AppDownloadController) SyncVersion(c *gin.Context) {
|
||
var req service.SyncVersionRequest
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
response.BadRequest(c, "invalid request: "+err.Error())
|
||
return
|
||
}
|
||
|
||
ctx := c.Request.Context()
|
||
if err := ctrl.svc.SyncVersion(ctx, &req); err != nil {
|
||
response.InternalError(c, "同步版本信息失败")
|
||
return
|
||
}
|
||
|
||
response.Success(c, nil)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 编译验证**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./controller/
|
||
```
|
||
|
||
预期：编译成功
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/controller/app_download_controller.go
|
||
git commit -m "feat: add AppDownloadController with GetDownloadUrls and SyncVersion
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: 路由注册与装配
|
||
|
||
**Files:**
|
||
- Modify: `backend/gateway/router/router.go`
|
||
|
||
- [ ] **Step 1: 在 SetupRouter 中添加三层装配**
|
||
|
||
定位到 `SetupRouter` 函数中现有 controller 初始化代码块末尾（`modCtrl.SetService(modSvc)` 之后，`v1 := r.Group("/api/v1")` 之前），添加：
|
||
|
||
```go
|
||
// App 下载页 — gateway 直连 PG（无 Dubbo RPC，参见 spec §12.5）
|
||
appDownloadRepo := repository.NewAppDownloadRepository(database.GetDB())
|
||
appDownloadSvc := service.NewAppDownloadService(appDownloadRepo)
|
||
appDownloadCtrl := controller.NewAppDownloadController(appDownloadSvc)
|
||
```
|
||
|
||
- [ ] **Step 2: 添加 import**
|
||
|
||
在 `router.go` 的 import 块中添加：
|
||
|
||
```go
|
||
"github.com/topfans/backend/gateway/repository"
|
||
"github.com/topfans/backend/pkg/database"
|
||
```
|
||
|
||
> 注：`router.go` 已有 `"github.com/topfans/backend/gateway/controller"` 和 `"github.com/topfans/backend/gateway/service"` 的 import，只需补充 `repository` 和 `database` 两个新包。
|
||
|
||
- [ ] **Step 3: 注册公开路由**
|
||
|
||
在 `v1` 路由组中，与其他公开路由并列（如 `v1.POST("/segment", ...)` 附近）添加：
|
||
|
||
```go
|
||
// App 下载页 — HTML 分享页使用（公开，无需认证）
|
||
v1.GET("/app/download-urls", appDownloadCtrl.GetDownloadUrls)
|
||
```
|
||
|
||
- [ ] **Step 4: 注册 Admin 内部路由**
|
||
|
||
在现有 `admin := v1.Group("/admin")` 块内（约 router.go:282-285）追加一行：
|
||
|
||
```go
|
||
admin := v1.Group("/admin")
|
||
{
|
||
admin.POST("/notifications", notificationCtrl.AdminCreateNotification) // 已有
|
||
admin.POST("/app/versions/sync", appDownloadCtrl.SyncVersion) // ← 新增
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: 编译验证**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./...
|
||
```
|
||
|
||
预期：编译成功，无 import 错误
|
||
|
||
- [ ] **Step 6: 本地启动并测试接口**
|
||
|
||
启动 gateway：
|
||
|
||
```bash
|
||
cd backend/gateway && go run main.go
|
||
```
|
||
|
||
测试公开接口（GET）：
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/v1/app/download-urls | jq .
|
||
```
|
||
|
||
预期（数据库为空时）：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"android": null,
|
||
"ios": null
|
||
}
|
||
}
|
||
```
|
||
|
||
测试 Admin 同步接口（POST）：
|
||
|
||
```bash
|
||
curl -s -X POST http://localhost:8080/api/v1/admin/app/versions/sync \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"android": {"url": "https://cdn.example.com/app-1.0.5.apk", "version": "1.0.5", "type": "native_app"},
|
||
"ios": {"url": "https://apps.apple.com/cn/app/id1234567890", "version": "1.0.5", "type": "native_app"}
|
||
}' | jq .
|
||
```
|
||
|
||
预期：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok"
|
||
}
|
||
```
|
||
|
||
再次 GET 验证数据已写入：
|
||
|
||
```bash
|
||
curl -s http://localhost:8080/api/v1/app/download-urls | jq .
|
||
```
|
||
|
||
预期：android 和 ios 均有数据
|
||
|
||
- [ ] **Step 7: 验证 Swagger 文档生成**
|
||
|
||
```bash
|
||
cd backend/gateway && swag init --parseDependency --parseInternal
|
||
```
|
||
|
||
预期：生成/更新 `docs/docs.go`、`docs/swagger.json`、`docs/swagger.yaml`
|
||
|
||
- [ ] **Step 8: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/router/router.go backend/gateway/docs/
|
||
git commit -m "feat: register app download routes and wire up controller
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 C：测试 + 接口重构（Task 7-9）
|
||
|
||
### Task 7: Repository 单元测试
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/repository/app_download_repository_test.go`
|
||
|
||
- [ ] **Step 1: 编写测试**
|
||
|
||
```go
|
||
package repository
|
||
|
||
import (
|
||
"context"
|
||
"testing"
|
||
|
||
"github.com/stretchr/testify/assert"
|
||
"github.com/topfans/backend/pkg/models"
|
||
"gorm.io/driver/sqlite"
|
||
"gorm.io/gorm"
|
||
)
|
||
|
||
func setupTestDB(t *testing.T) *gorm.DB {
|
||
t.Helper()
|
||
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
|
||
assert.NoError(t, err)
|
||
err = db.AutoMigrate(&models.AppDownloadConfig{})
|
||
assert.NoError(t, err)
|
||
return db
|
||
}
|
||
|
||
func TestFindByType_NativeApp(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
repo := NewAppDownloadRepository(db)
|
||
|
||
// seed: 一条 native_app + 一条 wgt
|
||
db.Create(&models.AppDownloadConfig{
|
||
Platform: "android", Type: "native_app", DownloadURL: "https://cdn.example.com/app.apk", Version: "1.0.5",
|
||
})
|
||
db.Create(&models.AppDownloadConfig{
|
||
Platform: "android", Type: "wgt", DownloadURL: "https://cdn.example.com/wgt.wgt", Version: "1.0.5",
|
||
})
|
||
|
||
configs, err := repo.FindByType(context.Background(), models.AppPackageTypeNativeApp)
|
||
assert.NoError(t, err)
|
||
assert.Len(t, configs, 1)
|
||
assert.Equal(t, "native_app", configs[0].Type)
|
||
}
|
||
|
||
func TestFindByType_Wgt(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
repo := NewAppDownloadRepository(db)
|
||
|
||
db.Create(&models.AppDownloadConfig{
|
||
Platform: "android", Type: "wgt", DownloadURL: "https://cdn.example.com/wgt.wgt", Version: "1.0.5",
|
||
})
|
||
|
||
configs, err := repo.FindByType(context.Background(), models.AppPackageTypeWgt)
|
||
assert.NoError(t, err)
|
||
assert.Len(t, configs, 1)
|
||
assert.Equal(t, "wgt", configs[0].Type)
|
||
}
|
||
|
||
func TestUpsertAll_Insert(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
repo := NewAppDownloadRepository(db)
|
||
|
||
err := repo.UpsertAll(context.Background(), []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://v1.apk", Version: "1.0.0"},
|
||
})
|
||
assert.NoError(t, err)
|
||
|
||
var count int64
|
||
db.Model(&models.AppDownloadConfig{}).Count(&count)
|
||
assert.Equal(t, int64(1), count)
|
||
|
||
var cfg models.AppDownloadConfig
|
||
db.First(&cfg)
|
||
assert.Equal(t, "https://v1.apk", cfg.DownloadURL)
|
||
}
|
||
|
||
func TestUpsertAll_Update(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
repo := NewAppDownloadRepository(db)
|
||
|
||
// 首次插入
|
||
err := repo.UpsertAll(context.Background(), []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://v1.apk", Version: "1.0.0"},
|
||
})
|
||
assert.NoError(t, err)
|
||
|
||
// 更新同一条
|
||
err = repo.UpsertAll(context.Background(), []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://v2.apk", Version: "2.0.0"},
|
||
})
|
||
assert.NoError(t, err)
|
||
|
||
// 验证只有 1 条且已更新
|
||
var count int64
|
||
db.Model(&models.AppDownloadConfig{}).Count(&count)
|
||
assert.Equal(t, int64(1), count)
|
||
|
||
var cfg models.AppDownloadConfig
|
||
db.First(&cfg)
|
||
assert.Equal(t, "https://v2.apk", cfg.DownloadURL)
|
||
assert.Equal(t, "2.0.0", cfg.Version)
|
||
}
|
||
|
||
func TestFindByType_Empty(t *testing.T) {
|
||
db := setupTestDB(t)
|
||
repo := NewAppDownloadRepository(db)
|
||
|
||
configs, err := repo.FindByType(context.Background(), models.AppPackageTypeNativeApp)
|
||
assert.NoError(t, err)
|
||
assert.Len(t, configs, 0)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试**
|
||
|
||
```bash
|
||
cd backend/gateway && go test ./repository/ -run TestFindByType -v
|
||
cd backend/gateway && go test ./repository/ -run TestUpsertAll -v
|
||
```
|
||
|
||
预期：全部 PASS
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/repository/app_download_repository_test.go
|
||
git commit -m "test: add AppDownloadRepository unit tests
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 8: Service 单元测试
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/service/app_download_service_test.go`
|
||
|
||
- [ ] **Step 1: 编写测试**
|
||
|
||
> 注：参照项目现有测试风格（laser_generate_controller_test.go），使用 in-memory fake 而非 testify/mock。
|
||
|
||
```go
|
||
package service
|
||
|
||
import (
|
||
"context"
|
||
"testing"
|
||
|
||
"github.com/stretchr/testify/assert"
|
||
"github.com/topfans/backend/pkg/models"
|
||
)
|
||
|
||
// fakeRepo 是 AppDownloadRepository 的 in-memory fake 实现
|
||
type fakeRepo struct {
|
||
configs []models.AppDownloadConfig
|
||
}
|
||
|
||
func (f *fakeRepo) FindByType(ctx context.Context, pkgType string) ([]models.AppDownloadConfig, error) {
|
||
var result []models.AppDownloadConfig
|
||
for _, c := range f.configs {
|
||
if c.Type == pkgType {
|
||
result = append(result, c)
|
||
}
|
||
}
|
||
return result, nil
|
||
}
|
||
|
||
func (f *fakeRepo) UpsertAll(ctx context.Context, configs []models.AppDownloadConfig) error {
|
||
for _, incoming := range configs {
|
||
found := false
|
||
for i, existing := range f.configs {
|
||
if existing.Platform == incoming.Platform && existing.Type == incoming.Type {
|
||
f.configs[i].DownloadURL = incoming.DownloadURL
|
||
f.configs[i].Version = incoming.Version
|
||
f.configs[i].UpdatedAt = incoming.UpdatedAt
|
||
found = true
|
||
break
|
||
}
|
||
}
|
||
if !found {
|
||
f.configs = append(f.configs, incoming)
|
||
}
|
||
}
|
||
return nil
|
||
}
|
||
|
||
// 确保 fakeRepo 实现 AppDownloadRepository 所需方法
|
||
// 注：生产者代码中 AppDownloadService 持有具体 *repository.AppDownloadRepository，
|
||
// 测试时需要在 service 包内定义 interface 以支持 fake 注入。
|
||
// 为简化此 task，暂时直接在 service_test.go 中定义 interface 并适配。
|
||
type appDownloadRepo interface {
|
||
FindByType(ctx context.Context, pkgType string) ([]models.AppDownloadConfig, error)
|
||
UpsertAll(ctx context.Context, configs []models.AppDownloadConfig) error
|
||
}
|
||
|
||
type testableService struct {
|
||
repo appDownloadRepo
|
||
}
|
||
|
||
func newTestableService(repo appDownloadRepo) *testableService {
|
||
return &testableService{repo: repo}
|
||
}
|
||
|
||
func (s *testableService) GetAllNativeApp(ctx context.Context) ([]models.AppDownloadConfig, error) {
|
||
return s.repo.FindByType(ctx, models.AppPackageTypeNativeApp)
|
||
}
|
||
|
||
func (s *testableService) SyncVersion(ctx context.Context, req *SyncVersionRequest) error {
|
||
now := 1700000000000 // 固定时间戳便于断言
|
||
var configs []models.AppDownloadConfig
|
||
|
||
if req.Android != nil {
|
||
configs = append(configs, models.AppDownloadConfig{
|
||
Platform: "android", Type: req.Android.Type,
|
||
DownloadURL: req.Android.URL, Version: req.Android.Version, UpdatedAt: now,
|
||
})
|
||
}
|
||
if req.IOS != nil {
|
||
configs = append(configs, models.AppDownloadConfig{
|
||
Platform: "ios", Type: req.IOS.Type,
|
||
DownloadURL: req.IOS.URL, Version: req.IOS.Version, UpdatedAt: now,
|
||
})
|
||
}
|
||
return s.repo.UpsertAll(ctx, configs)
|
||
}
|
||
|
||
func TestGetAllNativeApp_FiltersWgt(t *testing.T) {
|
||
repo := &fakeRepo{configs: []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://app.apk"},
|
||
{Platform: "android", Type: "wgt", DownloadURL: "https://wgt.wgt"},
|
||
}}
|
||
svc := newTestableService(repo)
|
||
|
||
configs, err := svc.GetAllNativeApp(context.Background())
|
||
assert.NoError(t, err)
|
||
assert.Len(t, configs, 1)
|
||
assert.Equal(t, "native_app", configs[0].Type)
|
||
}
|
||
|
||
func TestGetAllNativeApp_Empty(t *testing.T) {
|
||
repo := &fakeRepo{}
|
||
svc := newTestableService(repo)
|
||
|
||
configs, err := svc.GetAllNativeApp(context.Background())
|
||
assert.NoError(t, err)
|
||
assert.Len(t, configs, 0)
|
||
}
|
||
|
||
func TestSyncVersion_BothPlatforms(t *testing.T) {
|
||
repo := &fakeRepo{}
|
||
svc := newTestableService(repo)
|
||
|
||
err := svc.SyncVersion(context.Background(), &SyncVersionRequest{
|
||
Android: &PlatformVersionInfo{URL: "https://a.apk", Version: "1.0.5", Type: "native_app"},
|
||
IOS: &PlatformVersionInfo{URL: "https://apps.apple.com/...", Version: "1.0.5", Type: "native_app"},
|
||
})
|
||
assert.NoError(t, err)
|
||
assert.Len(t, repo.configs, 2)
|
||
}
|
||
|
||
func TestSyncVersion_PartialUpdate(t *testing.T) {
|
||
repo := &fakeRepo{
|
||
configs: []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://old.apk", Version: "1.0.0"},
|
||
},
|
||
}
|
||
svc := newTestableService(repo)
|
||
|
||
// 只更新 android，不传 ios
|
||
err := svc.SyncVersion(context.Background(), &SyncVersionRequest{
|
||
Android: &PlatformVersionInfo{URL: "https://new.apk", Version: "2.0.0", Type: "native_app"},
|
||
})
|
||
assert.NoError(t, err)
|
||
assert.Len(t, repo.configs, 1) // 仍然是 1 条
|
||
assert.Equal(t, "https://new.apk", repo.configs[0].DownloadURL)
|
||
assert.Equal(t, "2.0.0", repo.configs[0].Version)
|
||
}
|
||
|
||
func TestSyncVersion_NilPlatform(t *testing.T) {
|
||
repo := &fakeRepo{}
|
||
svc := newTestableService(repo)
|
||
|
||
// 只传 iOS，android 为 nil
|
||
err := svc.SyncVersion(context.Background(), &SyncVersionRequest{
|
||
IOS: &PlatformVersionInfo{URL: "https://apps.apple.com/...", Version: "1.0.5", Type: "native_app"},
|
||
})
|
||
assert.NoError(t, err)
|
||
assert.Len(t, repo.configs, 1)
|
||
assert.Equal(t, "ios", repo.configs[0].Platform)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行测试**
|
||
|
||
```bash
|
||
cd backend/gateway && go test ./service/ -run TestGetAllNativeApp -v
|
||
cd backend/gateway && go test ./service/ -run TestSyncVersion -v
|
||
```
|
||
|
||
预期：全部 PASS
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/service/app_download_service_test.go
|
||
git commit -m "test: add AppDownloadService unit tests
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 9: 将 Controller/Service 依赖改为 interface
|
||
|
||
> **目的**：通过 interface 解耦，使 controller 测试可以注入 mock service（Task 12 中的测试依赖此重构）。
|
||
|
||
**Files:**
|
||
- Modify: `backend/gateway/service/app_download_service.go`
|
||
- Modify: `backend/gateway/controller/app_download_controller.go`
|
||
|
||
- [ ] **Step 1: 在 service 包中定义 repository interface**
|
||
|
||
在 `app_download_service.go` 的 import 块后添加 interface 定义，并修改 `AppDownloadService` 的字段类型：
|
||
|
||
```go
|
||
// AppDownloadRepo AppDownloadService 依赖的 repository 接口
|
||
type AppDownloadRepo interface {
|
||
FindByType(ctx context.Context, pkgType string) ([]models.AppDownloadConfig, error)
|
||
UpsertAll(ctx context.Context, configs []models.AppDownloadConfig) error
|
||
}
|
||
|
||
// AppDownloadService App下载页业务逻辑
|
||
type AppDownloadService struct {
|
||
repo AppDownloadRepo // ← 改为 interface
|
||
}
|
||
|
||
// NewAppDownloadService 构造函数
|
||
func NewAppDownloadService(repo AppDownloadRepo) *AppDownloadService { // ← 参数类型改为 interface
|
||
return &AppDownloadService{repo: repo}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 在 controller 包中定义 service interface**
|
||
|
||
在 `app_download_controller.go` 的 import 块后添加 interface 定义，并修改 `AppDownloadController` 的字段类型：
|
||
|
||
```go
|
||
// AppDownloadSvc AppDownloadController 依赖的 service 接口
|
||
type AppDownloadSvc interface {
|
||
GetAllNativeApp(ctx context.Context) ([]models.AppDownloadConfig, error)
|
||
SyncVersion(ctx context.Context, req *service.SyncVersionRequest) error
|
||
}
|
||
|
||
// AppDownloadController App下载页控制器
|
||
type AppDownloadController struct {
|
||
svc AppDownloadSvc // ← 改为 interface
|
||
}
|
||
|
||
// NewAppDownloadController 构造函数
|
||
func NewAppDownloadController(svc AppDownloadSvc) *AppDownloadController { // ← 参数类型改为 interface
|
||
return &AppDownloadController{svc: svc}
|
||
}
|
||
```
|
||
|
||
> **注意**：Controller 中需要 import `"github.com/topfans/backend/pkg/models"`（因为 `AppDownloadSvc` 接口引用了 `models.AppDownloadConfig`）。
|
||
|
||
- [ ] **Step 3: 编译验证（确认未破坏调用方）**
|
||
|
||
```bash
|
||
cd backend/gateway && go build ./...
|
||
```
|
||
|
||
预期：编译成功。`*repository.AppDownloadRepository` 自动满足 `AppDownloadRepo` 接口；`*service.AppDownloadService` 自动满足 `AppDownloadSvc` 接口。Go 的 structural typing 无需显式 `implements` 声明。
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/service/app_download_service.go \
|
||
backend/gateway/controller/app_download_controller.go
|
||
git commit -m "refactor: use interface for AppDownloadController/Service dependencies
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 D：HTML 分享页（Task 10）
|
||
|
||
### Task 10: HTML 下载页
|
||
|
||
**Files:**
|
||
- Create: `frontend/static/html/download.html`
|
||
|
||
- [ ] **Step 1: 编写 HTML 页面**
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
|
||
<title>TopFans — 下载</title>
|
||
<style>
|
||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||
body {
|
||
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
||
background: linear-gradient(135deg, #0a0a0a 0%, #1a1a2e 50%, #0a0a0a 100%);
|
||
min-height: 100vh;
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
color: #fff;
|
||
}
|
||
.container { text-align: center; padding: 40px 24px; max-width: 360px; width: 100%; }
|
||
.logo { font-size: 32px; font-weight: 800; letter-spacing: 2px; margin-bottom: 8px; }
|
||
.slogan { font-size: 14px; color: #888; margin-bottom: 32px; }
|
||
.version { font-size: 13px; color: #666; margin-bottom: 24px; min-height: 20px; }
|
||
.download-btn {
|
||
display: flex;
|
||
align-items: center;
|
||
justify-content: center;
|
||
gap: 10px;
|
||
width: 100%;
|
||
padding: 16px 24px;
|
||
margin-bottom: 16px;
|
||
border-radius: 12px;
|
||
font-size: 16px;
|
||
font-weight: 600;
|
||
text-decoration: none;
|
||
transition: transform 0.15s, opacity 0.15s;
|
||
}
|
||
.download-btn:active { transform: scale(0.97); }
|
||
.download-btn.android {
|
||
background: #3ddc84;
|
||
color: #000;
|
||
}
|
||
.download-btn.ios {
|
||
background: #fff;
|
||
color: #000;
|
||
}
|
||
.download-btn.disabled {
|
||
opacity: 0.4;
|
||
pointer-events: none;
|
||
}
|
||
.footer { margin-top: 40px; font-size: 12px; color: #555; }
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="container">
|
||
<div class="logo">TopFans</div>
|
||
<div class="slogan">粉丝共创平台</div>
|
||
<div class="version" id="version-info">加载中…</div>
|
||
|
||
<a id="btn-android" class="download-btn android disabled" href="javascript:void(0)">
|
||
🤖 Android 下载
|
||
</a>
|
||
<a id="btn-ios" class="download-btn ios disabled" href="javascript:void(0)">
|
||
iOS 下载
|
||
</a>
|
||
|
||
<div class="footer">TopFans © 2026</div>
|
||
</div>
|
||
|
||
<script>
|
||
(async function() {
|
||
// ★ 部署时修改为实际 API 地址
|
||
var API_URL = 'https://api.topfans.com/api/v1/app/download-urls';
|
||
|
||
var btnAndroid = document.getElementById('btn-android');
|
||
var btnIOS = document.getElementById('btn-ios');
|
||
var versionInfo = document.getElementById('version-info');
|
||
var versions = [];
|
||
|
||
function updateUI() {
|
||
var hasAndroid = false;
|
||
var hasIOS = false;
|
||
|
||
if (versions.length > 0) {
|
||
for (var i = 0; i < versions.length; i++) {
|
||
var v = versions[i];
|
||
if (v.platform === 'android') {
|
||
btnAndroid.href = v.url;
|
||
btnAndroid.classList.remove('disabled');
|
||
hasAndroid = true;
|
||
}
|
||
if (v.platform === 'ios') {
|
||
btnIOS.href = v.url;
|
||
btnIOS.classList.remove('disabled');
|
||
hasIOS = true;
|
||
}
|
||
}
|
||
}
|
||
|
||
if (hasAndroid || hasIOS) {
|
||
var parts = [];
|
||
if (hasAndroid) parts.push('Android ' + getVersionText('android'));
|
||
if (hasIOS) parts.push('iOS ' + getVersionText('ios'));
|
||
versionInfo.textContent = '最新版本：' + parts.join(' ｜ ');
|
||
} else {
|
||
versionInfo.textContent = '暂无可用下载';
|
||
}
|
||
}
|
||
|
||
function getVersionText(platform) {
|
||
for (var i = 0; i < versions.length; i++) {
|
||
if (versions[i].platform === platform) {
|
||
return versions[i].version || '';
|
||
}
|
||
}
|
||
return '';
|
||
}
|
||
|
||
try {
|
||
var res = await fetch(API_URL);
|
||
if (!res.ok) {
|
||
throw new Error('HTTP ' + res.status);
|
||
}
|
||
var json = await res.json();
|
||
|
||
if (json.code === 0 && json.data) {
|
||
['android', 'ios'].forEach(function(p) {
|
||
if (json.data[p]) {
|
||
versions.push({
|
||
platform: p,
|
||
url: json.data[p].url,
|
||
version: json.data[p].version,
|
||
type: json.data[p].type
|
||
});
|
||
}
|
||
});
|
||
updateUI();
|
||
} else {
|
||
versionInfo.textContent = '暂无可用下载';
|
||
}
|
||
} catch (err) {
|
||
console.error('获取下载地址失败', err);
|
||
versionInfo.textContent = '获取下载地址失败，请稍后重试';
|
||
}
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
- [ ] **Step 2: 本地预览**
|
||
|
||
用浏览器打开 `frontend/static/html/download.html`，确认：
|
||
- 初始显示"加载中…"
|
||
- API 不可达时显示"获取下载地址失败，请稍后重试"
|
||
- 按钮处于 disabled（灰色）状态
|
||
|
||
- [ ] **Step 3: 部署到 Nginx**
|
||
|
||
```bash
|
||
# 部署到服务器
|
||
scp frontend/static/html/download.html <server>:/var/www/topfans/download.html
|
||
```
|
||
|
||
Nginx 配置参考：
|
||
|
||
```nginx
|
||
location /download {
|
||
alias /var/www/topfans/download.html;
|
||
add_header Cache-Control "public, max-age=300";
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 端到端验证**
|
||
|
||
1. 在手机浏览器访问 `https://h5.topfans.com/download`
|
||
2. 确认下载按钮可点击，跳转到正确的下载地址
|
||
3. 确认版本号显示正确
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add frontend/static/html/download.html
|
||
git commit -m "feat: add app download share page (HTML)
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 E：Swagger + Controller 测试（Task 11-12）
|
||
|
||
### Task 11: Swagger 文档生成
|
||
|
||
**Files:**
|
||
- Modify: `backend/gateway/docs/`（自动生成）
|
||
|
||
- [ ] **Step 1: 生成 Swagger 文档**
|
||
|
||
```bash
|
||
cd backend/gateway && swag init --parseDependency --parseInternal
|
||
```
|
||
|
||
- [ ] **Step 2: 启动 gateway，访问 Swagger UI**
|
||
|
||
```bash
|
||
cd backend/gateway && go run main.go
|
||
```
|
||
|
||
浏览器访问 `http://localhost:8080/swagger/index.html`，确认新的两个接口出现在文档中：
|
||
|
||
| 接口 | Tags |
|
||
|------|------|
|
||
| `GET /api/v1/app/download-urls` | App下载页 |
|
||
| `POST /api/v1/admin/app/versions/sync` | Admin |
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/docs/
|
||
git commit -m "docs: update swagger for app download endpoints
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 12: Controller 集成测试
|
||
|
||
> **前置条件**：Task 9（interface 重构）已完成，controller 已支持 mock service 注入。
|
||
|
||
**Files:**
|
||
- Create: `backend/gateway/controller/app_download_controller_test.go`
|
||
|
||
- [ ] **Step 1: 编写测试（fake service + 6 个用例）**
|
||
|
||
```go
|
||
package controller
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"errors"
|
||
"net/http"
|
||
"net/http/httptest"
|
||
"strings"
|
||
"testing"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
"github.com/stretchr/testify/assert"
|
||
"github.com/topfans/backend/pkg/models"
|
||
"github.com/topfans/backend/gateway/service"
|
||
)
|
||
|
||
// fakeAppDownloadSvc 是 AppDownloadSvc 的 in-memory fake
|
||
type fakeAppDownloadSvc struct {
|
||
configs []models.AppDownloadConfig
|
||
getAllErr error
|
||
syncErr error
|
||
syncCalled bool
|
||
lastSyncReq *service.SyncVersionRequest
|
||
}
|
||
|
||
func (f *fakeAppDownloadSvc) GetAllNativeApp(ctx context.Context) ([]models.AppDownloadConfig, error) {
|
||
if f.getAllErr != nil {
|
||
return nil, f.getAllErr
|
||
}
|
||
return f.configs, nil
|
||
}
|
||
|
||
func (f *fakeAppDownloadSvc) SyncVersion(ctx context.Context, req *service.SyncVersionRequest) error {
|
||
f.syncCalled = true
|
||
f.lastSyncReq = req
|
||
return f.syncErr
|
||
}
|
||
|
||
func setupTestRouter(ctrl *AppDownloadController) *gin.Engine {
|
||
gin.SetMode(gin.TestMode)
|
||
r := gin.New()
|
||
r.GET("/api/v1/app/download-urls", ctrl.GetDownloadUrls)
|
||
r.POST("/api/v1/admin/app/versions/sync", ctrl.SyncVersion)
|
||
return r
|
||
}
|
||
|
||
// ========== GET /api/v1/app/download-urls ==========
|
||
|
||
func TestGetDownloadUrls_Success(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{
|
||
configs: []models.AppDownloadConfig{
|
||
{Platform: "android", Type: "native_app", DownloadURL: "https://app.apk", Version: "1.0.5"},
|
||
{Platform: "ios", Type: "native_app", DownloadURL: "https://apps.apple.com/...", Version: "1.0.5"},
|
||
},
|
||
}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("GET", "/api/v1/app/download-urls", nil)
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 200, w.Code)
|
||
|
||
var resp map[string]interface{}
|
||
json.Unmarshal(w.Body.Bytes(), &resp)
|
||
assert.Equal(t, float64(0), resp["code"])
|
||
|
||
data := resp["data"].(map[string]interface{})
|
||
assert.NotNil(t, data["android"])
|
||
assert.NotNil(t, data["ios"])
|
||
}
|
||
|
||
func TestGetDownloadUrls_EmptyData(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{configs: []models.AppDownloadConfig{}}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("GET", "/api/v1/app/download-urls", nil)
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 200, w.Code)
|
||
|
||
var resp map[string]interface{}
|
||
json.Unmarshal(w.Body.Bytes(), &resp)
|
||
assert.Equal(t, float64(0), resp["code"])
|
||
|
||
data := resp["data"].(map[string]interface{})
|
||
assert.Nil(t, data["android"])
|
||
assert.Nil(t, data["ios"])
|
||
}
|
||
|
||
func TestGetDownloadUrls_ServiceError(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{getAllErr: errors.New("db down")}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("GET", "/api/v1/app/download-urls", nil)
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 500, w.Code)
|
||
}
|
||
|
||
// ========== POST /api/v1/admin/app/versions/sync ==========
|
||
|
||
func TestSyncVersion_InvalidJSON(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("POST", "/api/v1/admin/app/versions/sync",
|
||
strings.NewReader(`{"android": "not_an_object"}`))
|
||
req.Header.Set("Content-Type", "application/json")
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 400, w.Code) // BadRequest — JSON 类型不匹配
|
||
}
|
||
|
||
func TestSyncVersion_MissingRequiredField(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
// 缺少必填字段 url
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("POST", "/api/v1/admin/app/versions/sync",
|
||
strings.NewReader(`{"android": {"version": "1.0.5", "type": "native_app"}}`))
|
||
req.Header.Set("Content-Type", "application/json")
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 400, w.Code) // BadRequest — url is required
|
||
}
|
||
|
||
func TestSyncVersion_Success(t *testing.T) {
|
||
gin.SetMode(gin.TestMode)
|
||
|
||
fakeSvc := &fakeAppDownloadSvc{}
|
||
ctrl := NewAppDownloadController(fakeSvc)
|
||
router := setupTestRouter(ctrl)
|
||
|
||
body := `{
|
||
"android": {"url": "https://app.apk", "version": "1.0.5", "type": "native_app"},
|
||
"ios": {"url": "https://apps.apple.com/...", "version": "1.0.5", "type": "native_app"}
|
||
}`
|
||
w := httptest.NewRecorder()
|
||
req, _ := http.NewRequest("POST", "/api/v1/admin/app/versions/sync",
|
||
strings.NewReader(body))
|
||
req.Header.Set("Content-Type", "application/json")
|
||
router.ServeHTTP(w, req)
|
||
|
||
assert.Equal(t, 200, w.Code)
|
||
assert.True(t, fakeSvc.syncCalled)
|
||
assert.NotNil(t, fakeSvc.lastSyncReq.Android)
|
||
assert.NotNil(t, fakeSvc.lastSyncReq.IOS)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 运行全部 Controller 测试**
|
||
|
||
```bash
|
||
cd backend/gateway && go test ./controller/ -run "TestGetDownloadUrls|TestSyncVersion" -v
|
||
```
|
||
|
||
预期：全部 6 个用例 PASS
|
||
|
||
- [ ] **Step 3: 运行全部 app_download 测试套件**
|
||
|
||
```bash
|
||
cd backend/gateway && go test ./repository/ ./service/ ./controller/ -v -count=1
|
||
```
|
||
|
||
预期：全部 PASS（14 个用例：repo 5 + service 5 + controller 6，减去重复的 `TestMain`）
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add backend/gateway/controller/app_download_controller_test.go
|
||
git commit -m "test: add AppDownloadController integration tests (6 cases)
|
||
Co-Authored-By: Claude <noreply@anthropic.com>"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 F：uniCloud 云函数（独立仓库，Task 13-14）
|
||
|
||
> **注意**：uni-admin 是独立仓库（不在当前工作目录）。以下 Task 在 uni-admin 仓库中执行。
|
||
|
||
### Task 13: uniCloud 云函数
|
||
|
||
**Files (uni-admin 仓库):**
|
||
- Create: `uniCloud-alipay/cloudfunctions/sync-download-urls/index.js`
|
||
- Create: `uniCloud-alipay/cloudfunctions/sync-download-urls/package.json`
|
||
|
||
- [ ] **Step 1: 创建 `package.json`**
|
||
|
||
```json
|
||
{
|
||
"name": "sync-download-urls",
|
||
"version": "1.0.0",
|
||
"extensions": {
|
||
"uni-cloud-httpclient": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 创建 `index.js`**
|
||
|
||
```javascript
|
||
'use strict';
|
||
|
||
/**
|
||
* sync-download-urls — 同步最新下载地址到 Go Backend
|
||
*
|
||
* 触发方式：uni-admin 版本发布成功后调用
|
||
* 环境变量（uniCloud 云函数配置）：
|
||
* BACKEND_URL — Go Backend 地址，如 https://api.topfans.com
|
||
*/
|
||
|
||
const APPID = '__UNI__B99B0DD'; // topfans appid（以实际为准）
|
||
|
||
exports.main = async (event, context) => {
|
||
const db = uniCloud.database();
|
||
const backendURL = process.env.BACKEND_URL || 'https://api.topfans.com';
|
||
|
||
const result = { android: null, ios: null, synced: false, error: null };
|
||
|
||
try {
|
||
// 1. 查询 Android + iOS 最新 stable_publish 记录
|
||
for (const platform of ['Android', 'iOS']) {
|
||
const platformKey = platform.toLowerCase();
|
||
|
||
const res = await db.collection('opendb-app-versions')
|
||
.where({
|
||
appid: APPID,
|
||
platform: platform,
|
||
stable_publish: true,
|
||
})
|
||
.orderBy('create_date', 'desc')
|
||
.get();
|
||
|
||
if (res.data && res.data.length > 0) {
|
||
const latest = res.data[0];
|
||
result[platformKey] = {
|
||
url: latest.url || '',
|
||
version: latest.version || '',
|
||
type: latest.type || 'native_app',
|
||
};
|
||
}
|
||
}
|
||
|
||
// 2. 推送到 Go Backend
|
||
const payload = {
|
||
android: result.android || null,
|
||
ios: result.ios || null,
|
||
};
|
||
|
||
if (!payload.android && !payload.ios) {
|
||
result.error = 'No published versions found';
|
||
return result;
|
||
}
|
||
|
||
const httpRes = await uniCloud.httpclient.request(
|
||
`${backendURL}/api/v1/admin/app/versions/sync`,
|
||
{
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
data: payload,
|
||
dataType: 'json',
|
||
timeout: 10000,
|
||
}
|
||
);
|
||
|
||
if (httpRes.status === 200 && httpRes.data && httpRes.data.code === 0) {
|
||
result.synced = true;
|
||
} else {
|
||
result.error = `Backend returned status=${httpRes.status}, data=${JSON.stringify(httpRes.data)}`;
|
||
}
|
||
} catch (err) {
|
||
result.error = err.message || String(err);
|
||
}
|
||
|
||
return result;
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 3: 上传云函数到 uniCloud**
|
||
|
||
在 HBuilderX 或 uniCloud 控制台上传 `sync-download-urls` 云函数。
|
||
|
||
- [ ] **Step 4: 配置环境变量**
|
||
|
||
在 uniCloud 控制台 → 云函数 → sync-download-urls → 环境变量，添加：
|
||
|
||
```
|
||
BACKEND_URL = https://api.topfans.com
|
||
```
|
||
|
||
- [ ] **Step 5: 网络连通性验证**
|
||
|
||
在 uniCloud 云函数控制台执行测试：
|
||
|
||
```javascript
|
||
const res = await uniCloud.httpclient.request(
|
||
`${process.env.BACKEND_URL}/health`,
|
||
{ method: 'GET', timeout: 5000 }
|
||
);
|
||
console.log('status:', res.status); // 期望 200
|
||
```
|
||
|
||
- [ ] **Step 6: Commit (uni-admin 仓库)**
|
||
|
||
```bash
|
||
git add uniCloud-alipay/cloudfunctions/sync-download-urls/
|
||
git commit -m "feat: add sync-download-urls cloud function"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 14: uni-admin 触发同步
|
||
|
||
**Files (uni-admin 仓库):**
|
||
- Modify: `uni_modules/uni-upgrade-center/pages/version/add.vue`
|
||
|
||
- [ ] **Step 1: 在 `submitForm` 成功后插入同步调用**
|
||
|
||
定位到 `add.vue` 中 `dbOperate.then(async (res) => { ... })` 回调，在 `uni.showToast` 之前添加：
|
||
|
||
```javascript
|
||
// ★ 新增：同步下载地址到 Go Backend（异步，不阻塞 UI）
|
||
if (value.stable_publish) {
|
||
this.syncDownloadUrls();
|
||
}
|
||
```
|
||
|
||
完整修改后（diff 风格）：
|
||
|
||
```javascript
|
||
dbOperate.then(async (res) => {
|
||
if (value.stable_publish && this.lastVersionId) {
|
||
await collectionDB.doc(this.lastVersionId).update({
|
||
stable_publish: false
|
||
})
|
||
}
|
||
// ★ 新增：同步下载地址到 Go Backend（异步，不阻塞 UI）
|
||
if (value.stable_publish) {
|
||
this.syncDownloadUrls();
|
||
}
|
||
uni.showToast({
|
||
title: '新增成功'
|
||
})
|
||
this.getOpenerEventChannel().emit('refreshData')
|
||
setTimeout(() => uni.navigateBack(), 500)
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 在 methods 中新增 `syncDownloadUrls` 方法**
|
||
|
||
在现有 methods 块末尾（`back()` 之前）添加：
|
||
|
||
```javascript
|
||
/**
|
||
* 同步下载地址到 Go Backend（异步调用，不阻塞 UI）
|
||
*/
|
||
async syncDownloadUrls() {
|
||
try {
|
||
const res = await uniCloud.callFunction({
|
||
name: 'sync-download-urls',
|
||
});
|
||
if (res.result && !res.result.synced) {
|
||
console.warn('[sync-download-urls] 同步失败:', res.result.error);
|
||
}
|
||
} catch (err) {
|
||
console.warn('[sync-download-urls] 云函数调用异常:', err.message);
|
||
}
|
||
},
|
||
```
|
||
|
||
- [ ] **Step 3: 端到端测试**
|
||
|
||
1. 在 uni-admin 发布一个新版本
|
||
2. 查看云函数日志确认同步成功
|
||
3. curl Go Backend 验证数据已写入：
|
||
|
||
```bash
|
||
curl -s https://api.topfans.com/api/v1/app/download-urls | jq .
|
||
```
|
||
|
||
预期：返回最新发布的版本号
|
||
|
||
- [ ] **Step 4: Commit (uni-admin 仓库)**
|
||
|
||
```bash
|
||
git add uni_modules/uni-upgrade-center/pages/version/add.vue
|
||
git commit -m "feat: trigger sync-download-urls after version publish"
|
||
```
|
||
|
||
---
|
||
|
||
## 阶段 G：运维配置（Task 15）
|
||
|
||
### Task 15: Nginx Rate Limit + 最终验证
|
||
|
||
- [ ] **Step 1: 配置 Nginx rate limit（公开接口防刷）**
|
||
|
||
在 Nginx 配置中添加：
|
||
|
||
```nginx
|
||
# 在 http 块中定义 limit zone
|
||
limit_req_zone $binary_remote_addr zone=download_api:10m rate=100r/m;
|
||
|
||
# 在 server 块中对公开接口应用
|
||
location /api/v1/app/download-urls {
|
||
limit_req zone=download_api burst=20 nodelay;
|
||
proxy_pass http://gateway:8080;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 重载 Nginx**
|
||
|
||
```bash
|
||
nginx -t && nginx -s reload
|
||
```
|
||
|
||
- [ ] **Step 3: 验证 Admin 接口 IP 白名单**
|
||
|
||
确认 `/api/v1/admin/*` 已配置 IP 白名单：
|
||
|
||
```nginx
|
||
location /api/v1/admin/ {
|
||
allow <uniCloud出口IP>;
|
||
allow <内网IP段>;
|
||
deny all;
|
||
proxy_pass http://gateway:8080;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: 全链路端到端验证**
|
||
|
||
```
|
||
uni-admin 发布新版本
|
||
→ 云函数 sync-download-urls 执行
|
||
→ POST /api/v1/admin/app/versions/sync (HTTP 200)
|
||
→ PG app_download_configs 表写入
|
||
|
||
浏览器访问 https://h5.topfans.com/download
|
||
→ fetch GET /api/v1/app/download-urls
|
||
→ 渲染 Android/iOS 下载按钮（可点击）
|
||
```
|
||
|
||
- [ ] **Step 5: 验证序列健康**
|
||
|
||
```sql
|
||
SELECT
|
||
schemaname, sequencename, last_value,
|
||
(SELECT MAX(id) FROM app_download_configs) AS table_max_id,
|
||
last_value >= (SELECT MAX(id) FROM app_download_configs) AS is_healthy
|
||
FROM pg_sequences
|
||
WHERE sequencename = 'app_download_configs_id_seq';
|
||
```
|
||
|
||
预期：`is_healthy = true`
|
||
|
||
---
|
||
|
||
## 任务依赖关系
|
||
|
||
```
|
||
Task 1 (migration)
|
||
└─ Task 2 (model)
|
||
└─ Task 3 (repository)
|
||
├─ Task 4 (service)
|
||
│ └─ Task 5 (controller)
|
||
│ └─ Task 6 (router + e2e test)
|
||
│ └─ Task 11 (swagger)
|
||
├─ Task 7 (repo tests)
|
||
└─ Task 8 (service tests)
|
||
|
||
Task 5 ────────────────────────────────────────┐
|
||
Task 9 (interface refactor) ← after Task 4,5 │
|
||
└─ Task 12 (controller tests) │
|
||
│
|
||
Task 10 (HTML) ────── independent │
|
||
Task 13 (云函数) ─── independent (uni-admin) │
|
||
Task 14 (add.vue) ── after Task 13 │
|
||
│
|
||
Task 15 (运维) ───── after Task 6 + 10 + 14 ───┘
|
||
```
|
||
|
||
> **关键依赖**：Task 12（controller 测试）依赖 Task 9（interface 重构），因为测试需要注入 mock service。
|
||
|
||
---
|
||
|
||
## 时间估算
|
||
|
||
| 阶段 | 任务 | 预估 |
|
||
|------|------|------|
|
||
| A | Task 1-4: 基础设施 | 1h |
|
||
| B | Task 5-6: Controller + 路由 | 45min |
|
||
| C | Task 7-9: 测试 + 接口重构 | 1h15min |
|
||
| D | Task 10: HTML 页 | 30min |
|
||
| E | Task 11-12: Swagger + Controller 测试 | 1h |
|
||
| F | Task 13-14: uniCloud (独立仓库) | 1h15min |
|
||
| G | Task 15: 运维 + 验证 | 30min |
|
||
| **合计** | | **~6h** |
|
||
|
||
> 注：Task 13-14 在 uni-admin 独立仓库执行，不占用本仓库开发时间。
|
||
> 本仓库实际开发时间约 **~4h45min**。
|