Files
spark-store/下载量统计接口规范.md
T
shenmo7192 e22f71d255 refactor(download-count): 下载量改为读取 app.json/applist.json 的 DownloadTimes
下载量不再逐个应用请求 download-times.txt(数千个应用 = 数千次额外请求),
改为直接读取服务器注入到目录/详情 JSON 的 DownloadTimes 字段。

- AppJson 新增 DownloadTimes,normalizeAppJson 映射为 app.downloadCount
- useRanking 移除逐应用请求、并发批处理与 localStorage 缓存,
  直接按已加载 apps 的 downloadCount 排序发布(零额外请求)
- 详情页优先用目录数据的 downloadCount;缺失时(如已安装页兜底 App)
  回退读取 app.json 的 DownloadTimes,并加请求序号防止旧响应覆盖
- modules/ranking 新增 parseDownloadTimes,统一处理数字/字符串/非法值
- 新增回归测试 ranking-download-count.test.ts
- 更新《下载量统计接口规范》与 ranking 计划文档

验证:vue-tsc 0 error;新增 6 项测试通过;全套单测失败项与改动前
完全一致(35 项均为既有失败,无新增);eslint 改动文件无新增问题。

Signed-off-by: shenmo <jifengshenmo@outlook.com>
2026-11-11 20:03:34 +08:00

142 lines
3.4 KiB
Markdown

# 下载量统计接口规范
## 0. 客户端读取方式(现行)
客户端**不再**逐个应用请求 `download-times.txt`(数千个应用意味着数千次请求),
改为直接读取目录/详情 JSON 中服务器注入的 `DownloadTimes` 字段:
- 列表与下载排行:`{SOURCE_URL}/{ARCH}/{CATEGORY}/applist.json` 每项的 `DownloadTimes`
- 详情页兜底:`{SOURCE_URL}/{ARCH}/{CATEGORY}/{Package Name}/app.json` 的 `DownloadTimes`
`DownloadTimes` 为正整数(下载次数),字段缺失时客户端视为「未知」,不展示下载量。
下文 `download-times.txt` 接口仍然保留可用,但客户端已不再使用。
---
## 1. 获取下载次数(旧接口,客户端已不再请求)
获取指定应用的下载次数
**URL**: `{SOURCE_URL}/{ARCH}/{CATOGARY}/{Package Name}/download-times.txt`
**请求方式**: GET
**示例**:
```
https://cdn.d.store.deepinos.org.cn/store/tools/spark-store/download-times.txt
https://cdn.d.store.deepinos.org.cn/amd64-store/office/wps/download-times.txt
https://cdn.d.store.deepinos.org.cn/aarch64-store/tools/spark-store/download-times.txt
```
**响应**: 纯文本,返回下载次数数字,如 `12345`
---
## 2. 上报下载次数 (apm-app-store)
apm-app-store 项目使用 HTTP POST 上报下载统计
**URL**: `{STATS_BASE_URL}/handle_post`
**请求方式**: POST
**请求头**:
```
Content-Type: application/json
```
**请求参数**:
```json
{
"path": "{ARCH}/{CATOGARY}/{Package Name}"
}
```
**示例**:
请求:
```
POST https://feedback.spark-app.store/handle_post
Content-Type: application/json
{
"path": "amd64-apm/office/wps"
}
```
---
## 3. 上报下载次数 (spark-store)
# Spark Store 评分反馈接口文档
## 接口概述
| 项目 | 内容 |
|------|------|
| 接口名称 | 应用评分反馈 |
| 接口地址 | `https://feedback.spark-app.store/handle_post` |
| 请求方式 | POST |
| 协议 | HTTPS |
---
## 请求头
| Header | 值 | 说明 |
|--------|-----|------|
| Content-Type | application/json | 请求数据类型 |
| User-Agent | Spark-Store/4.x | 客户端标识 |
---
## 请求参数
### 请求体 (JSON)
```json
{
"path": "应用安装路径"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| path | string | 是 | 应用在系统中的安装路径 |
---
## 响应结果
### 成功响应
```json
Finished
```
### 失败响应
```
Permission denied
```
---
## 调用示例
### cURL
```bash
curl -X POST "https://feedback.spark-app.store/handle_post" \
-H "Content-Type: application/json" \
-H "User-Agent: Spark-Store/4.x" \
-d '{"path":"/opt/spark-store/apps/com.example.app"}'
```
### Python
```python
import requests
url = "https://feedback.spark-app.store/handle_post"
headers = {
"Content-Type": "application/json",
"User-Agent": "Spark-Store/4.x"
}
data = {"path": "/opt/spark-store/apps/com.example.app"}
response = requests.post(url, json=data, headers=headers)
print(response.text)
```
---
## 错误码
| 错误信息 | 说明 |
|----------|------|
| Finished | 请求成功 |
| Permission denied | 权限不足或请求失败 |
说明:当应用下载成功后,客户端会自动发送下载统计数据到服务器。此接口主要用于内部统计,不建议外部直接调用。
请求体:JSON格式,包含应用元数据URL和统计标识符
注意:此接口由客户端自动调用,无需手动触发。