# Sport-Era 体育咨询AI平台 - 实现流程文档

> 版本：v1.1（Demo版）
> 日期：2026-03-14
> 技术栈：ThinkPHP 8 + Vue 3 + UniApp + DeepSeek AI

---

## 一、技术架构总览

```
┌─────────────────────────────────────────────────┐
│                    客户端                         │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐        │
│  │ iOS  │  │Android│  │ 鸿蒙 │  │  H5  │        │
│  └──┬───┘  └──┬───┘  └──┬───┘  └──┬───┘        │
│     └─────────┴─────────┴─────────┘              │
│                UniApp (Vue 3)                     │
├─────────────────────────────────────────────────┤
│              管理后台: Vue 3 + Element Plus       │
├─────────────────────────────────────────────────┤
│              API层: ThinkPHP 8                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ adminapi │ │   api    │ │ AI Service│        │
│  └──────────┘ └──────────┘ └─────┬────┘        │
├──────────────────────────────────┼──────────────┤
│              数据层               │              │
│  ┌──────┐  ┌──────┐  ┌──────┐  │              │
│  │MySQL │  │Redis │  │ 队列  │  │              │
│  └──────┘  └──────┘  └──────┘  │              │
├────────────────────────────────┼──────────────┤
│            外部服务              │              │
│  ┌──────────┐  ┌──────────┐   │              │
│  │体育数据API│  │DeepSeek AI│◄──┘              │
│  └──────────┘  └──────────┘                    │
└─────────────────────────────────────────────────┘
```

---

## 二、开发阶段规划

### 阶段一：基础架构（预计 2-3 周）

#### 1.1 数据库建表 + 爬虫服务
- 创建所有业务表（约40张新表）
- 执行SQL迁移脚本
- 验证表结构和关联关系
- **开发爬虫服务(SportCrawlerService)**，爬取网络真实数据填充数据库
- 爬虫服务与正式上线API服务共用数据清洗/入库逻辑，切换时仅替换数据源适配器

#### 1.2 用户体系扩展
**后端（server/app/）**
```
app/common/model/user/
├── UserProfile.php          # 用户扩展资料模型
├── UserLevel.php            # 用户等级模型
├── UserVip.php              # VIP订阅模型
├── UserExpert.php           # 专家认证模型
└── UserCredit.php           # 信誉评分模型

app/api/controller/user/
├── UserProfileController.php
├── UserLevelController.php
└── UserVipController.php

app/api/logic/user/
├── UserProfileLogic.php
├── UserLevelLogic.php
└── UserVipLogic.php
```

**前端（uniapp/src/）**
```
pages/user/
├── profile/index.vue        # 个人资料页
├── level/index.vue          # 等级详情页
└── vip/index.vue            # VIP订阅页
```

**开发顺序**：
1. 创建用户扩展表 → Model → Logic → Controller → API路由
2. 前端个人资料页面
3. 等级经验值计算逻辑
4. VIP订阅流程

#### 1.3 头条资讯模块
**后端开发**
```
app/api/controller/article/
├── ArticleController.php     # 复用已有，扩展AI分析接口
└── ArticleCateController.php # 复用已有

app/api/logic/article/
└── ArticleAiLogic.php        # 新增 - AI导读分析逻辑

app/common/model/article/
└── ArticleAiAnalysis.php     # 新增 - AI分析结果模型

app/adminapi/controller/article/
└── ArticleController.php     # 复用已有 - 后台资讯管理
```

**前端开发**
```
uniapp/src/pages/
├── news/
│   ├── index.vue             # 资讯列表
│   ├── detail.vue            # 资讯详情
│   └── components/
│       ├── NewsCard.vue      # 资讯卡片组件
│       └── AiAnalysis.vue    # AI导读分析组件
```

**开发顺序**：
1. 扩展资讯分类（体育相关分类）
2. 资讯列表/详情前端页面
3. AI导读分析接口（阶段三实现AI逻辑，此处先预留接口）

#### 1.4 赛事基础模块
**后端开发**
```
app/common/model/sport/
├── SportType.php             # 运动类型
├── League.php                # 联赛
├── Team.php                  # 球队
├── Match.php                 # 赛事
├── MatchOdds.php             # 赔率
├── MatchStats.php            # 赛事统计
├── MatchHistory.php          # 历史交锋
├── Player.php                # 球员
└── PlayerInjury.php          # 伤停

app/api/controller/sport/
├── MatchController.php       # 赛事接口
├── LeagueController.php      # 联赛接口
└── TeamController.php        # 球队接口

app/api/logic/sport/
├── MatchLogic.php
├── LeagueLogic.php
└── TeamLogic.php

app/common/service/sport/
├── SportDataService.php      # 数据源统一接口（爬虫/API切换）
├── SportCrawlerService.php   # 爬虫服务（Demo阶段主要数据源）
└── DataCleanerService.php    # 数据清洗器（爬虫/API共用）
```

**前端开发**
```
uniapp/src/pages/
├── match/
│   ├── index.vue             # 赛事列表（按日期）
│   ├── detail.vue            # 赛事详情
│   └── components/
│       ├── MatchCard.vue     # 赛事卡片
│       ├── OddsPanel.vue     # 赔率面板
│       ├── ScoreBoard.vue    # 比分板
│       └── HistoryTable.vue  # 历史交锋表
├── league/
│   ├── index.vue             # 联赛列表
│   └── detail.vue            # 联赛详情（排名/赛程）
```

**开发顺序**：
1. 运动类型/联赛/球队基础数据表和模型
2. 赛事CRUD接口
3. 爬虫服务开发（SportCrawlerService）爬取网络真实赛事数据
4. 数据清洗器（DataCleanerService）统一入库格式
5. 前端赛事列表/详情页面
6. 赔率/盘口展示
7. SportDataService 统一接口（正式上线时切换数据源适配器）

---

### 阶段二：社区与互动（预计 2-3 周）

#### 2.1 社区发帖系统
**后端开发**
```
app/common/model/community/
├── CommunityPost.php         # 帖子
├── CommunityPostImage.php    # 帖子图片
├── CommunityComment.php      # 评论
├── CommunityLike.php         # 点赞
├── CommunityTag.php          # 标签
├── CommunityPostTag.php      # 帖子标签关联
└── CommunityFollow.php       # 关注

app/api/controller/community/
├── PostController.php        # 帖子接口
├── CommentController.php     # 评论接口
├── FollowController.php      # 关注接口
└── TagController.php         # 标签接口

app/api/logic/community/
├── PostLogic.php
├── CommentLogic.php
└── FollowLogic.php
```

**前端开发**
```
uniapp/src/pages/
├── community/
│   ├── index.vue             # 社区首页（帖子列表）
│   ├── post_detail.vue       # 帖子详情
│   ├── publish.vue           # 发帖页面
│   └── components/
│       ├── PostCard.vue      # 帖子卡片
│       ├── CommentList.vue   # 评论列表
│       ├── ImageUpload.vue   # 图片上传
│       └── TagSelector.vue   # 标签选择器
```

**开发顺序**：
1. 帖子CRUD → 评论 → 点赞 → 标签
2. 关注系统
3. 图片上传（战绩截图）
4. 推荐方案发布（关联赛事）

#### 2.2 跟单系统
**后端开发**
```
app/common/model/tipster/
├── TipsterPlan.php           # 推荐方案
├── TipsterFollow.php         # 跟单记录
├── TipsterStats.php          # 推手统计
└── TipsterProfitLog.php      # 盈亏日志

app/api/controller/tipster/
├── PlanController.php        # 方案接口
├── FollowController.php      # 跟单接口
└── StatsController.php       # 统计接口

app/api/logic/tipster/
├── PlanLogic.php
├── FollowLogic.php
└── StatsLogic.php
```

**前端开发**
```
uniapp/src/pages/
├── tipster/
│   ├── index.vue             # 推手列表/排行榜
│   ├── detail.vue            # 推手详情（历史方案/盈亏曲线）
│   ├── plan_detail.vue       # 方案详情
│   └── components/
│       ├── TipsterCard.vue   # 推手卡片
│       ├── PlanCard.vue      # 方案卡片
│       ├── ProfitChart.vue   # 盈亏曲线图
│       └── FollowButton.vue  # 跟单按钮
```

**开发顺序**：
1. 推荐方案发布/展示
2. 跟单功能
3. 盈利统计和排行榜
4. 盈亏曲线图表

#### 2.3 专家认证
**后端**：UserExpert 模型 + 认证申请/审核接口
**管理后台**：认证审核页面
**开发顺序**：认证申请接口 → 后台审核页面 → 前端申请页面

---

### 阶段三：AI智能模块（预计 3-4 周）

#### 3.1 AI基础服务层
**后端开发**
```
app/common/service/ai/
├── AiService.php             # AI服务基类
├── DeepSeekClient.php        # DeepSeek API客户端
├── AiCacheService.php        # AI结果缓存服务
└── AiQueueService.php        # AI异步队列服务

app/common/enum/
└── AiEnum.php                # AI相关枚举（分析类型/状态等）

config/
└── ai.php                    # AI配置文件（从 la_ai_config 表读取，后台可配置）
```

**核心类设计**：
```php
// DeepSeekClient.php - 核心调用类
class DeepSeekClient
{
    private string $apiKey;       // 从 la_ai_config 表读取，后台可配置
    private string $baseUrl;      // 从 la_ai_config 表读取
    private string $model;        // deepseek-chat / deepseek-reasoner，后台可切换

    public function chat(string $systemPrompt, string $userMessage): array
    public function chatStream(string $systemPrompt, string $userMessage): Generator
}

// AiService.php - 业务封装
class AiService
{
    public static function analyzeArticle(int $articleId): array    // 资讯AI分析
    public static function predictMatch(int $matchId): array        // 赛事预测
    public static function analyzeCredibility(int $userId): array   // 可信度分析
    public static function analyzeLottery(array $params): array     // 彩票概率分析
}
```

#### 3.2 AI资讯阅读助手
**Prompt设计**：
```
系统角色：你是一位专业的体育资讯分析师。

任务：对以下体育资讯文章进行深度分析，输出JSON格式结果：
{
    "summary": "3-5句话的摘要",
    "key_points": ["重点1", "重点2", ...],
    "risk_warnings": ["风险提示1", ...],
    "opposite_views": ["反向观点1", ...],
    "sentiment": {
        "label": "positive/neutral/negative",
        "confidence": 0.85
    }
}
```

**开发顺序**：
1. DeepSeekClient 封装（从 la_ai_config 读取配置）
2. 后台AI配置页面（API Key / 模型选择 / 参数调整 / 调用限制）
3. 资讯分析Prompt设计和调试
4. 结果缓存策略
5. 前端AI分析展示组件
6. 后台AI调用日志查看页面

#### 3.3 社区可信度分析模型
**数据采集**：
```
用户ID →
├── 历史推荐方案列表 → 命中率计算
├── 盈亏记录 → 波动率计算
├── 发帖时间序列 → 稳定性计算
├── 帖子编辑记录 → 事后编辑检测
└── 赛果对比 → 偏离程度计算
```

**Prompt设计**：
```
系统角色：你是体育社区内容审核AI。

输入数据：用户历史数据摘要（JSON格式）
任务：评估该用户的可信度，输出JSON：
{
    "credibility_score": 75,
    "risk_level": "medium",
    "is_suspicious": false,
    "analysis": "分析说明",
    "dimension_scores": {
        "hit_rate": 80,
        "volatility": 70,
        "stability": 85,
        "rationality": 65,
        "edit_integrity": 90,
        "deviation": 70
    }
}
```

**定时任务**：每日凌晨3点执行批量分析
**开发顺序**：
1. 数据采集逻辑
2. Prompt设计和调优
3. 定时任务配置
4. 前端可信度标识展示

#### 3.4 赛事预测模型
**数据输入组装**：
```php
// 组装赛事分析数据
$matchData = [
    'home_team' => [...],      // 主队近期数据
    'away_team' => [...],      // 客队近期数据
    'head_to_head' => [...],   // 历史交锋
    'odds' => [...],           // 当前赔率
    'injuries' => [...],       // 伤停信息
    'xg_data' => [...],        // xG数据
];
```

**开发顺序**：
1. 赛事数据组装逻辑
2. 预测Prompt设计
3. 预测结果存储和展示
4. 前端预测报告页面

#### 3.5 彩票概率模型
**实现方式**：统计算法为主 + DeepSeek辅助分析
```
历史开奖数据 →
├── PHP统计计算（频率/遗漏值/冷热号）
├── DeepSeek分析趋势和异常模式
└── 蒙特卡洛模拟生成推荐组合
```

#### 3.6 个性化推荐流
**推荐因子**：
- 用户浏览历史（赛事/资讯偏好）
- 关注的推手和球队
- AI分析结果质量评分
- 时效性（优先最新内容）

---

### 阶段四：变现与运营（预计 2-3 周）

#### 4.1 钱包管理
**后端开发**
```
app/common/model/wallet/
├── Wallet.php                # 钱包
├── WalletLog.php             # 钱包流水
├── WalletWithdraw.php        # 提现记录
└── WalletAddress.php         # 钱包地址

app/api/controller/wallet/
├── WalletController.php      # 钱包接口
└── WithdrawController.php    # 提现接口

app/api/logic/wallet/
├── WalletLogic.php
└── WithdrawLogic.php

app/adminapi/controller/wallet/
└── WithdrawController.php    # 后台提现审核
```

**前端开发**
```
uniapp/src/pages/
├── wallet/
│   ├── index.vue             # 钱包首页
│   ├── bill.vue              # 账单记录
│   ├── withdraw.vue          # 提现页面
│   └── address.vue           # 地址管理
```

**开发顺序**：
1. 钱包余额管理
2. 流水记录
3. 提现申请和审核流程
4. USTD地址管理

#### 4.2 分销管理
**后端开发**
```
app/common/model/distribution/
├── DistributionConfig.php    # 分销配置
├── DistributionInvite.php    # 邀请记录
├── DistributionTeam.php      # 团队关系
└── DistributionSettlement.php # 结算记录

app/api/controller/distribution/
├── InviteController.php      # 邀请接口
├── TeamController.php        # 团队接口
└── SettlementController.php  # 结算接口

app/api/logic/distribution/
├── InviteLogic.php           # 邀请码生成/绑定逻辑
├── TeamLogic.php             # 团队树形结构逻辑
└── SettlementLogic.php       # 佣金计算/结算逻辑
```

**前端开发**
```
uniapp/src/pages/
├── distribution/
│   ├── index.vue             # 分销中心
│   ├── invite.vue            # 邀请页面（含二维码）
│   ├── team.vue              # 团队列表
│   └── settlement.vue        # 结算报表
```

**开发顺序**：
1. 邀请码/链接生成
2. 注册绑定上级关系
3. 团队树形管理
4. 佣金计算逻辑
5. 月度自动结算定时任务

#### 4.3 平台首页聚合
**开发顺序**：
1. 今日赛事聚合接口
2. 热门推荐接口
3. 盈利排行榜接口
4. AI精选分析展示
5. 首页UI整合

---

## 三、后台管理扩展

### 需要新增的管理后台页面

```
admin/src/views/
├── sport/                    # 赛事管理
│   ├── type/index.vue        # 运动类型管理
│   ├── league/index.vue      # 联赛管理
│   ├── team/index.vue        # 球队管理
│   ├── match/index.vue       # 赛事管理
│   └── data_sync.vue         # 数据同步管理
├── community/                # 社区管理
│   ├── post/index.vue        # 帖子管理（审核/删除）
│   ├── comment/index.vue     # 评论管理
│   ├── tag/index.vue         # 标签管理
│   └── report.vue            # 举报处理
├── tipster/                  # 跟单管理
│   ├── plan/index.vue        # 方案管理
│   ├── expert/index.vue      # 专家认证审核
│   └── ranking.vue           # 排行榜管理
├── ai/                       # AI管理
│   ├── config.vue            # AI配置（API Key/参数）
│   ├── analysis_log.vue      # 分析日志
│   └── model_config.vue      # 模型参数配置
├── wallet/                   # 钱包管理
│   ├── withdraw/index.vue    # 提现审核
│   └── log.vue               # 流水查看
├── distribution/             # 分销管理
│   ├── config.vue            # 分销配置
│   ├── team.vue              # 团队查看
│   └── settlement.vue        # 结算管理
└── user_ext/                 # 用户扩展管理
    ├── level_config.vue      # 等级配置
    ├── vip_config.vue        # VIP配置
    └── credit.vue            # 信誉评分查看
```

---

## 四、API路由规划

### 前台API（app/api）

```
// 赛事模块
Route::group('sport', function () {
    Route::get('match/list', 'sport.Match/list');
    Route::get('match/detail', 'sport.Match/detail');
    Route::get('match/odds', 'sport.Match/odds');
    Route::get('match/history', 'sport.Match/history');
    Route::get('league/list', 'sport.League/list');
    Route::get('team/detail', 'sport.Team/detail');
});

// 社区模块
Route::group('community', function () {
    Route::get('post/list', 'community.Post/list');
    Route::get('post/detail', 'community.Post/detail');
    Route::post('post/publish', 'community.Post/publish');
    Route::post('post/like', 'community.Post/like');
    Route::post('comment/add', 'community.Comment/add');
    Route::post('follow/toggle', 'community.Follow/toggle');
});

// 跟单模块
Route::group('tipster', function () {
    Route::get('plan/list', 'tipster.Plan/list');
    Route::get('plan/detail', 'tipster.Plan/detail');
    Route::post('plan/publish', 'tipster.Plan/publish');
    Route::post('plan/follow', 'tipster.Follow/follow');
    Route::get('stats/ranking', 'tipster.Stats/ranking');
});

// AI模块
Route::group('ai', function () {
    Route::get('article/analysis', 'ai.Article/analysis');
    Route::get('match/prediction', 'ai.Match/prediction');
    Route::get('user/credibility', 'ai.User/credibility');
    Route::get('lottery/analysis', 'ai.Lottery/analysis');
});

// 钱包模块
Route::group('wallet', function () {
    Route::get('info', 'wallet.Wallet/info');
    Route::get('log/list', 'wallet.Wallet/logList');
    Route::post('withdraw/apply', 'wallet.Withdraw/apply');
    Route::get('withdraw/list', 'wallet.Withdraw/list');
    Route::post('address/save', 'wallet.Wallet/saveAddress');
});

// 分销模块
Route::group('distribution', function () {
    Route::get('invite/code', 'distribution.Invite/code');
    Route::get('invite/list', 'distribution.Invite/list');
    Route::get('team/list', 'distribution.Team/list');
    Route::get('settlement/list', 'distribution.Settlement/list');
});
```

---

## 五、定时任务清单

| 任务 | Cron表达式 | Demo阶段 | 说明 |
|------|-----------|----------|------|
| 赛事数据爬取 | */30 * * * * | ✅ 爬虫服务 | 每30分钟爬取赛事数据（Demo用爬虫，正式用API） |
| 赔率数据爬取 | 0 */2 * * * | ✅ 爬虫服务 | 每2小时爬取赔率变化 |
| 赛果更新 | 0 */1 * * * | ✅ 爬虫服务 | 每小时检查并更新赛果 |
| 资讯爬取 | 0 */4 * * * | ✅ 爬虫服务 | 每4小时爬取最新体育资讯 |
| 推荐方案结算 | 0 */1 * * * | ✅ 需要 | 每小时结算已结束赛事的方案 |
| AI可信度计算 | 0 3 * * * | ✅ 需要 | 每日凌晨3点批量计算信誉评分 |
| 用户等级计算 | 0 4 * * * | ✅ 需要 | 每日凌晨4点更新用户等级 |
| 分销佣金结算 | 0 2 1 * * | ✅ 需要 | 每月1日凌晨2点结算上月佣金 |
| AI分析报告生成 | 0 8 * * * | ✅ 需要 | 每日早8点生成当日赛事AI分析 |
| 盈利排行榜更新 | 0 */2 * * * | ✅ 需要 | 每2小时更新盈利排行 |

---

## 六、第三方服务集成

| 服务 | 用途 | Demo阶段 | 正式上线 |
|------|------|----------|----------|
| DeepSeek API | AI分析核心 | ✅ 真实接入（Key后台配置） | 同左 |
| 体育数据API | 赛事/赔率/比分 | ✅ 爬虫爬取真实数据 | 切换为付费API |
| 短信服务 | 注册/登录验证码 | ✅ 通用验证码0000 | 接入短信服务商 |
| 文件存储 | 图片/截图上传 | ✅ likeadmin已集成 | 同左(OSS) |
| 微信SDK | 小程序/公众号登录 | ✅ likeadmin已集成 | 同左 |
| 支付服务 | VIP订阅/方案购买 | ❌ 后台手动设置 | 接入支付渠道 |
| USTD提现 | 钱包提现 | ❌ 仅状态更新 | 接入链上转账 |

---

## 七、部署与同步流程

### 开发流程
```
本地开发(IDE) → Git Push(Gitee) → 服务器 Git Pull → 生效
```

### Git 部署（主要方式）
- 远程仓库：`https://gitee.com/phperbylyh/sport-era-service.git`
- 分支：`develop`
- 服务器更新命令（宝塔定时任务）：
```bash
cd /www/wwwroot/sportera.gs-z.cn && chattr -i public/.user.ini 2>/dev/null && git -c safe.directory=/www/wwwroot/sportera.gs-z.cn fetch --all && echo "----- 更新内容 -----" && git -c safe.directory=/www/wwwroot/sportera.gs-z.cn log HEAD..origin/develop --oneline 2>&1 && echo "----- 变更文件 -----" && git -c safe.directory=/www/wwwroot/sportera.gs-z.cn diff --stat HEAD origin/develop 2>&1 && git -c safe.directory=/www/wwwroot/sportera.gs-z.cn reset --hard origin/develop 2>&1 && chattr +i public/.user.ini 2>/dev/null && echo "===== 部署完成: $(date) ====="
```

### SFTP 配置（辅助方式）
- 配置文件：`.winsurf/sftp.json`
- 自动上传：保存即同步
- 忽略文件：.git, .env, runtime, vendor

### 前端构建部署
```bash
# Admin后台
cd admin && npm run build    # 输出到 server/public/admin/

# UniApp H5
cd uniapp && npm run build:h5  # 输出到 server/public/mobile/

# UniApp App
cd uniapp && npm run build:app  # 生成原生App包
```

---

## 八、里程碑节点

| 里程碑 | 阶段 | 预计完成 | 交付物 |
|--------|------|----------|--------|
| M1 | 基础架构 | 第3周 | 数据库+爬虫服务+用户体系+资讯+赛事基础数据 |
| M2 | 社区上线 | 第6周 | 社区发帖+跟单+专家认证 |
| M3 | AI上线 | 第10周 | AI分析全功能+后台AI配置管理 |
| M4 | 商业闭环 | 第13周 | 钱包+分销+VIP+首页聚合 |
| **Demo交付** | **全部** | **第13周** | **完整功能Demo + 虚拟数据** |
| M5 | 正式上线 | 第15周 | 接入真实数据API+支付+USTD |
| M6 | 优化迭代 | 持续 | 性能优化+数据积累+模型调优 |