advertising-system/readme.md

# 自媒体维基广告投放页面

## 项目简介
这是一个基于访问量动态定价的广告投放系统，专为自媒体维基网站设计。系统能够根据网站实时访问量自动调整广告位价格，为广告主提供透明、公平的广告投放服务。

## 技术架构
### 前端技术栈
- HTML5：页面结构
- CSS3：样式设计
- JavaScript：交互逻辑
- WebP：图片格式（优化加载速度）

### 核心功能模块
1. **动态定价系统**
   - 基于访问量的价格计算
   - 自动价格更新机制
   - 多种支付方式支持

2. **广告位管理**
   - 多类型广告位支持
   - 预订状态管理
   - 图片预览功能

3. **数据统计**
   - 实时访问量统计
   - 价格系数计算
   - 预订状态追踪

## 文件结构
```
project/
├── index.html          # 主页面
├── styles.css          # 样式文件
├── script.js           # 核心逻辑
├── info.php           # 访问量数据接口（通过开源项目umami的API获取数据）
├── update_token.php   # Token手动更新工具
├── umami_cache.json   # 访问量数据缓存文件（自动生成）
├── umami_token.json   # Token缓存文件（自动生成）
└── images/            # 图片资源目录
```
## 文件说明

`info.php` 文件来源开源仓库: https://github.com/zhheo/HeoPVBridge
本项目部分灵感来源: https://immmmm.com/hi-umami-api/
```

## 核心配置说明

### 1. Umami API配置 (info.php)
```php
// 基础配置
$apiBaseUrl = 'https://um.com';        // Umami服务器地址
$username = 'your-username';           // Umami登录用户名
$password = 'your-password';           // Umami登录密码
$websiteId = '你的网站id';             // 网站ID
```

**Token自动更新功能**：
- 系统会自动检测token有效性
- Token失效时自动获取新token
- Token缓存7天，减少API调用
- 支持手动更新：运行 `php update_token.php`

### 2. 广告位配置 (script.js)
```javascript
const AD_POSITIONS = {
    'ad-id': {
        id: 'ad-id',           // 广告位唯一标识
        title: '广告位标题',    // 显示标题
        image: '图片URL',      // 预览图片
        dimensions: '尺寸',     // 广告位尺寸
        prices: {
            monthly: 价格,     // 月付价格
            yearly: 价格       // 年付价格
        }
    }
};
```

### 2. 访问量价格系数 (script.js)
```javascript
const VISIT_COEFFICIENTS = {
    'low': { min: 0, max: 30000, coefficient: 0.8 },     // 低访问量，价格打8折
    'medium': { min: 30001, max: 60000, coefficient: 1 }, // 中等访问量，原价
    'high': { min: 60001, max: 100000, coefficient: 1.2 }, // 高访问量，价格上浮20%
    'veryHigh': { min: 100001, max: Infinity, coefficient: 1.5 } // 极高访问量，价格上浮50%
};
```

### 3. 预订状态管理 (script.js)
```javascript
const BOOKED_STATUS = {
    'ad-id': {
        isBooked: true/false,  // 是否已预订
        endDate: '到期时间'    // ISO格式的到期时间
    }
};
```

## 维护指南

### 1. 添加新广告位
1. 在 `AD_POSITIONS` 中添加新配置
2. 在 `BOOKED_STATUS` 中添加状态管理
3. 确保图片资源已上传

### 2. 修改价格系数
1. 编辑 `VISIT_COEFFICIENTS` 对象
2. 调整各访问量区间的系数
3. 系统会自动应用新的价格计算规则

### 3. 更新预订状态
1. 修改 `BOOKED_STATUS` 中的状态
2. 设置 `isBooked` 为 true/false
3. 更新 `endDate` 为新的到期时间

### 4. 图片资源管理
1. 使用 WebP 格式优化加载速度
2. 图片尺寸建议：
   - Banner广告：1200×200px
   - 侧边栏广告：300×600px
   - 分类页广告：800×150px
   - 文末广告：600×300px
   - 网址推荐：800×100px

## 数据接口说明

### 访问量数据接口 (info.php)
```php
// 返回格式
{
    "today_uv": 今日UV,
    "today_pv": 今日PV,
    "yesterday_uv": 昨日UV,
    "yesterday_pv": 昨日PV,
    "last_month_pv": 上月PV,
    "last_year_pv": 去年PV
}
```

## 价格计算规则
1. 基础价格 × 访问量系数 = 实际价格
2. 访问量系数根据月PV自动调整
3. 价格每5分钟自动更新一次

## 预订流程
1. 用户选择广告位
2. 系统计算实际价格
3. 用户确认预订
4. 更新预订状态
5. 显示预订成功信息

## 注意事项
1. 确保 info.php 接口正确返回访问量数据
2. 定期检查图片资源是否可用
3. 及时更新预订状态
4. 保持价格系数的合理性

## 更新日志
### 2025-01-27
- 🚀 **页面加载性能优化**：
  - 改用 `DOMContentLoaded` 事件替代 `window.onload`，提前初始化页面
  - 实现渐进式价格显示：立即显示基础价格 → 加载状态 → 实时价格
  - 新增 `fetchVisitData()` 超时处理（15秒）和重试机制（3次）
  - 新增价格状态视觉区分：基础价格（灰色斜体）、加载中（蓝色动画）、实时价格（绿色加粗）
  - 优化用户体验：从首次加载需2分钟等待优化为立即显示基础价格，后台异步更新实时价格
- 🔧 **新增Token自动更新功能**：
  - 添加了Umami token自动获取和更新机制
  - 新增 `getNewUmamiToken()` 函数用于获取新token
  - 新增 `getValidToken()` 函数实现token自动管理
  - 新增 `isTokenValid()` 函数检测token有效性
  - 创建独立的 `update_token.php` 工具用于手动更新token
  - Token缓存7天，自动处理Umami重启后的token失效问题
- 🚀 **优化缓存策略**：将info.php中的缓存时间从10分钟（600秒）延长至7天（604800秒）
- ⚡ **提升系统性能**：减少API调用频率，增强系统稳定性

### 2024-02-29
- 初始版本发布
- 实现动态定价系统
- 添加广告位预览功能
- 优化移动端显示效果

## 维护说明

### Token管理
- ✅ **自动化处理**：系统已集成token自动更新功能，无需手动干预
- 🔄 **自动检测**：每次API调用前自动检测token有效性
- 📱 **手动更新**：如需手动更新token，运行：`php update_token.php`
- 📁 **缓存机制**：Token缓存7天，减少不必要的API调用
- ⚠️ **注意事项**：Umami升级后可能导致token失效，系统会自动处理

### 日常维护
- 定期检查 `umami_cache.json` 和 `umami_token.json` 文件权限
- 确保PHP有写入权限以创建和更新缓存文件
- 监控系统日志，关注token获取失败的错误信息
token获取：POST /api/auth/login
```
{
  "username": "your-username",
  "password": "your-password"
}
```
如果成功，你应该得到以下类似的响应：
```
{
    "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A",
    "user": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "username": "admin",
        "role": "admin",
        "createdAt": "2000-00-00T00:00:00.000Z",
        "isAdmin": true
    }
}
```
- 定期更新访问量数据接口
- 监控系统运行状态
- 及时处理异常情况

## 未来计划

- 可在线支付的自助广告系统，绑定对应广告位的动态码，实现全程自助下单并完成广告投放。
- 提供广告投放的API，方便第三方开发者接入。
- 提供广告投放的后台管理系统，方便广告主管理广告位、预订状态等信息。
- 提供广告投放的统计分析系统，方便广告主了解广告投放效果。

## 版权信息
© 2025 自媒体维基. All rights reserved.