@hupu-tech/shaper 0.2.12 → 0.2.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +6 -0
- package/dist/cli.js +2 -2
- package/dist/cloud/client.d.ts +0 -1
- package/dist/cloud/service-build.d.ts +2 -4
- package/dist/index.js +1 -1
- package/dist/project/create.d.ts +9 -3
- package/dist/project/delivery.d.ts +5 -5
- package/dist/runtime.d.ts +2 -1
- package/dist/runtime.js +1 -1
- package/dist/shared-2WDEQ3AQ.js +19 -0
- package/package.json +1 -1
- package/skills/business/SKILL.md +158 -0
- package/skills/business/activity/README.md +14 -0
- package/skills/business/activity/hupu-leaderboard-template/SKILL.md +52 -0
- package/skills/business/activity/hupu-leaderboard-template/example/README.md +20 -0
- package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/.cloudignore +3 -0
- package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/index.js +218 -0
- package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/package.json +15 -0
- package/skills/business/activity/hupu-leaderboard-template/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
- package/skills/business/activity/hupu-leaderboard-template/example/index.html +291 -0
- package/skills/business/activity/hupu-leaderboard-template/example/migrations/20260828210000_create_leaderboard.sql +54 -0
- package/skills/business/activity/hupu-lottery-draw/SKILL.md +50 -0
- package/skills/business/activity/hupu-lottery-draw/example/README.md +21 -0
- package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/.cloudignore +3 -0
- package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/index.js +142 -0
- package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/package.json +9 -0
- package/skills/business/activity/hupu-lottery-draw/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
- package/skills/business/activity/hupu-lottery-draw/example/index.html +178 -0
- package/skills/business/activity/hupu-lottery-draw/example/migrations/20260828220000_create_draw.sql +193 -0
- package/skills/business/activity/hupu-pk-voting/SKILL.md +54 -0
- package/skills/business/activity/hupu-pk-voting/example/README.md +44 -0
- package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/.cloudignore +3 -0
- package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/index.js +370 -0
- package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/package.json +15 -0
- package/skills/business/activity/hupu-pk-voting/example/cloudfunctions/activity_api/scf_bootstrap +2 -0
- package/skills/business/activity/hupu-pk-voting/example/index.html +729 -0
- package/skills/business/activity/hupu-pk-voting/example/migrations/20260828220000_create_pk_vote.sql +168 -0
- package/skills/business/activity/hupu-request-activity-execute-vote-task/SKILL.md +77 -0
- package/skills/business/activity/hupu-request-activity-get-vote-detail/SKILL.md +84 -0
- package/skills/business/activity/hupu-request-activity-get-vote-task-list/SKILL.md +86 -0
- package/skills/business/activity/hupu-request-activity-list-by-biz-keys/SKILL.md +153 -0
- package/skills/business/activity/hupu-request-activity-report-vote-task/SKILL.md +58 -0
- package/skills/business/activity/hupu-request-activity-submit-vote/SKILL.md +58 -0
- package/skills/business/activity/hupu-vote-task/SKILL.md +47 -0
- package/skills/business/community/README.md +13 -0
- package/skills/business/community/hupu-request-bbs-detail/SKILL.md +197 -0
- package/skills/business/community/hupu-request-bbs-get-tag-thread-list/SKILL.md +257 -0
- package/skills/business/community/hupu-request-bbs-get-topic-threads/SKILL.md +159 -0
- package/skills/business/community/hupu-request-bbs-gets-thread-post-list/SKILL.md +124 -0
- package/skills/business/community/hupu-request-bbs-open-post-editor/SKILL.md +75 -0
- package/skills/business/community/hupu-request-bbs-reply-post/SKILL.md +59 -0
- package/skills/business/community/hupu-score-add-score/SKILL.md +57 -0
- package/skills/business/community/hupu-score-get-item-detail/SKILL.md +173 -0
- package/skills/business/community/hupu-score-get-score/SKILL.md +263 -0
- package/skills/business/quality/README.md +7 -0
- package/skills/business/quality/hupu-security-check-audit/SKILL.md +39 -0
- package/skills/business/quality/hupu-wasm-compression/SKILL.md +69 -0
- package/skills/business/quality/hupu-wasm-compression/agents/openai.yaml +4 -0
- package/skills/business/quality/hupu-wasm-compression/tool/checks.mjs +90 -0
- package/skills/business/quality/hupu-wasm-compression/tool/compress-worker.mjs +40 -0
- package/skills/business/quality/hupu-wasm-compression/tool/public/app.js +84 -0
- package/skills/business/quality/hupu-wasm-compression/tool/public/index.html +80 -0
- package/skills/business/quality/hupu-wasm-compression/tool/public/style.css +3 -0
- package/skills/business/quality/hupu-wasm-compression/tool/server.mjs +126 -0
- package/skills/business/quality/hupu-web-security-audit/SKILL.md +45 -0
- package/skills/business/quality/hupu-web-security-audit/agents/openai.yaml +4 -0
- package/skills/business/rewards/README.md +13 -0
- package/skills/business/rewards/hupu-vacoin/SKILL.md +70 -0
- package/skills/business/rewards/hupu-vacoin-consume-coins/SKILL.md +47 -0
- package/skills/business/rewards/hupu-vacoin-get-coin-overview/SKILL.md +52 -0
- package/skills/business/rewards/hupu-vacoin-get-session-coins/SKILL.md +44 -0
- package/skills/business/rewards/hupu-vacoin-reset-session-id/SKILL.md +39 -0
- package/skills/business/rewards/hupu-vatask/SKILL.md +63 -0
- package/skills/business/rewards/hupu-vatask-complete-reward-video/SKILL.md +43 -0
- package/skills/business/rewards/hupu-vatask-consume-activity-chance/SKILL.md +48 -0
- package/skills/business/rewards/hupu-vatask-get-activity-task-state/SKILL.md +49 -0
- package/skills/business/runtime/README.md +13 -0
- package/skills/business/runtime/hupu-add-to-desktop/SKILL.md +51 -0
- package/skills/business/runtime/hupu-close-webview/SKILL.md +48 -0
- package/skills/business/runtime/hupu-cloud-auth/SKILL.md +43 -0
- package/skills/business/runtime/hupu-cloud-request/SKILL.md +56 -0
- package/skills/business/runtime/hupu-fullscreen-safe-top/SKILL.md +33 -0
- package/skills/business/runtime/hupu-navigate-to/SKILL.md +45 -0
- package/skills/business/runtime/hupu-request/SKILL.md +67 -0
- package/skills/business/runtime/hupu-seer-chat/SKILL.md +183 -0
- package/skills/business/runtime/hupu-track-report/SKILL.md +71 -0
- package/skills/business/sharing/README.md +7 -0
- package/skills/business/sharing/hupu-oss-upload-file/SKILL.md +40 -0
- package/skills/business/sharing/hupu-result-poster-posting/SKILL.md +37 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/README.md +14 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/.cloudignore +3 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/index.js +187 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/package.json +15 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/cloudfunctions/activity_api/scf_bootstrap +3 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/index.html +256 -0
- package/skills/business/sharing/hupu-result-poster-posting/example/migrations/20260828213000_create_result_poster_results.sql +60 -0
- package/skills/business/sharing/hupu-result-poster-posting/references/api-contract.md +46 -0
- package/skills/business/sharing/hupu-social-share/SKILL.md +27 -0
- package/skills/business/sports/README.md +27 -0
- package/skills/business/sports/hupu-request-basketball-player-info/SKILL.md +131 -0
- package/skills/business/sports/hupu-request-basketball-single-match/SKILL.md +158 -0
- package/skills/business/sports/hupu-request-basketball-team-info/SKILL.md +96 -0
- package/skills/business/sports/hupu-request-basketball-team-player-list/SKILL.md +108 -0
- package/skills/business/sports/hupu-request-basketball-team-salary-info/SKILL.md +85 -0
- package/skills/business/sports/hupu-request-football-coach-info/SKILL.md +76 -0
- package/skills/business/sports/hupu-request-football-live-room-news-list/SKILL.md +85 -0
- package/skills/business/sports/hupu-request-football-match-info/SKILL.md +126 -0
- package/skills/business/sports/hupu-request-football-player-info/SKILL.md +82 -0
- package/skills/business/sports/hupu-request-football-team-info/SKILL.md +83 -0
- package/skills/business/sports/hupu-request-football-team-player-season-stats/SKILL.md +73 -0
- package/skills/business/sports/hupu-request-football-team-season-year/SKILL.md +68 -0
- package/skills/business/sports/hupu-request-kog-playbyplay/SKILL.md +77 -0
- package/skills/business/sports/hupu-request-live-tab-info-list/SKILL.md +85 -0
- package/skills/business/sports/hupu-request-live-tab-list/SKILL.md +66 -0
- package/skills/business/sports/hupu-request-lol-playbyplay/SKILL.md +77 -0
- package/skills/business/sports/hupu-request-match-get-tab-detail-schedule-list/SKILL.md +113 -0
- package/skills/business/sports/hupu-request-match-query-all-diagram-info-by-id/SKILL.md +79 -0
- package/skills/business/sports/hupu-request-match-query-match-stats-by-match-info/SKILL.md +85 -0
- package/skills/business/sports/hupu-request-news-news-common-list/SKILL.md +90 -0
- package/skills/business/sports/hupu-request-news-player-news-list/SKILL.md +79 -0
- package/skills/business/sports/hupu-request-news-subject-news/SKILL.md +89 -0
- package/skills/business/sports/hupu-request-news-team-news-list/SKILL.md +76 -0
- package/skills/business/storage/README.md +9 -0
- package/skills/business/storage/hupu-cloud-save/SKILL.md +129 -0
- package/skills/business/storage/hupu-cloud-save/references/legacy-migration.md +111 -0
- package/skills/business/storage/hupu-cloud-save-load/SKILL.md +41 -0
- package/skills/business/storage/hupu-cloud-save-save/SKILL.md +45 -0
- package/skills/business/storage/hupu-storage-get-value/SKILL.md +26 -0
- package/skills/business/storage/hupu-storage-set-value/SKILL.md +42 -0
- package/skills/business/user/README.md +6 -0
- package/skills/business/user/hupu-auth-get-user-info/SKILL.md +47 -0
- package/skills/business/user/hupu-game-auth/SKILL.md +46 -0
- package/skills/core/hupu-business/SKILL.md +1 -1
- package/skills/core/hupu-business/references/runtime.md +17 -11
- package/skills/core/shaper-backend/SKILL.md +1 -1
- package/skills/core/shaper-backend/references/database.md +2 -2
- package/skills/core/shaper-backend/references/legacy.md +1 -1
- package/skills/core/shaper-backend/references/node-server.md +29 -20
- package/skills/core/shaper-development/SKILL.md +5 -1
- package/skills/core/shaper-development/references/project-setup.md +1 -1
- package/skills/core/shaper-game-development/SKILL.md +1 -1
- package/skills/core/shaper-release/SKILL.md +1 -1
- package/templates/cloud-service/README.md +4 -30
- package/templates/cloud-service/cloud.json +5 -8
- package/templates/cloud-service/package-lock.json +922 -15
- package/templates/cloud-service/release.json +4 -4
- package/templates/cloud-service/server.cjs +37 -0
- package/templates/leaderboard/README.md +3 -0
- package/templates/leaderboard/cloud/database/migrations/202611130001_leaderboard.sql +6 -0
- package/templates/leaderboard/cloud/functions/api/cloud.json +10 -0
- package/templates/leaderboard/cloud/functions/api/leaderboard.cjs +49 -0
- package/templates/leaderboard/cloud/functions/api/package-lock.json +1093 -0
- package/templates/leaderboard/cloud/functions/api/package.json +19 -0
- package/templates/leaderboard/cloud/functions/api/server.cjs +25 -0
- package/templates/leaderboard/cloud/gateway/routes.json +15 -0
- package/templates/leaderboard/docs/design.md +1 -0
- package/templates/leaderboard/docs/integration.md +12 -0
- package/templates/leaderboard/docs/product.md +1 -0
- package/templates/leaderboard/docs/validation.md +1 -0
- package/templates/leaderboard/index.html +12 -0
- package/templates/leaderboard/package-lock.json +828 -0
- package/templates/leaderboard/package.json +17 -0
- package/templates/leaderboard/public/.gitkeep +1 -0
- package/templates/leaderboard/shaper.config.json +7 -0
- package/templates/leaderboard/src/main.js +67 -0
- package/templates/leaderboard/src/style.css +69 -0
- package/templates/leaderboard/test/leaderboard.test.cjs +93 -0
- package/templates/offline-game/README.md +3 -0
- package/templates/offline-game/docs/design.md +1 -0
- package/templates/offline-game/docs/integration.md +10 -0
- package/templates/offline-game/docs/product.md +1 -0
- package/templates/offline-game/docs/validation.md +1 -0
- package/templates/offline-game/index.html +1 -0
- package/templates/offline-game/package-lock.json +828 -0
- package/templates/offline-game/package.json +16 -0
- package/templates/offline-game/public/.gitkeep +1 -0
- package/templates/offline-game/shaper.config.json +7 -0
- package/templates/offline-game/src/game.js +11 -0
- package/templates/offline-game/src/main.js +12 -0
- package/templates/offline-game/src/style.css +1 -0
- package/templates/offline-game/test/game.test.js +7 -0
- package/dist/shared-APGA5MU5.js +0 -19
- package/templates/cloud-service/handlers.cjs +0 -46
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hupu-capabilities
|
|
3
|
+
description: Shaper 前端能力总览。说明 window.ShaperAI 是什么、如何按子目录 Skill 调用,并给出常用 example。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Shaper Skill 是什么
|
|
7
|
+
|
|
8
|
+
本目录是 **Shaper** 注入到活动 H5 的前端能力包。
|
|
9
|
+
|
|
10
|
+
- 运行时全局对象:`window.ShaperAI`
|
|
11
|
+
- 第一层目录按场景分类,分类下每个技能目录是一个独立 Skill(含 `SKILL.md`)
|
|
12
|
+
- 前端能力按子 Skill 的 **JS Path** 调用,不要发明未文档化的 API
|
|
13
|
+
- 开发工具类 Skill 按自己的文档使用附带脚本,不一定提供 `window.ShaperAI` API
|
|
14
|
+
|
|
15
|
+
页面默认已由 Shaper 平台注入 SDK,业务代码**不要**再自行引入另一份 ShaperAI。
|
|
16
|
+
|
|
17
|
+
# 怎样使用
|
|
18
|
+
|
|
19
|
+
1. 打开需要的子目录,例如 `runtime/hupu-cloud-request/SKILL.md`
|
|
20
|
+
2. 按文档中的 `window.ShaperAI.<namespace>.<method>(params)` 调用
|
|
21
|
+
3. 绝大多数能力返回 `Promise`,先判断 `code === 200`(或文档约定字段),失败时用 `message` 提示用户
|
|
22
|
+
4. 参数、约束、返回值以**该子目录 SKILL.md 为准**;本文件只给总览与示例
|
|
23
|
+
|
|
24
|
+
# 场景导航
|
|
25
|
+
|
|
26
|
+
分类只用于源码组织,不新增技能标准。以下目录中的技能保留现有名称与使用方式。
|
|
27
|
+
|
|
28
|
+
| 场景 | 内容 | 技能数 |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| [用户登录](user/README.md) | 识别玩家、获取用户资料 | 2 |
|
|
31
|
+
| [社区互动](community/README.md) | 帖子浏览、发帖回帖、评分 | 9 |
|
|
32
|
+
| [赛事与资讯](sports/README.md) | 篮球、足球、电竞、赛程与新闻 | 23 |
|
|
33
|
+
| [活动玩法](activity/README.md) | 投票任务、PK、抽卡、排行榜 | 10 |
|
|
34
|
+
| [激励与金币](rewards/README.md) | 激励视频、机会与金币结算 | 9 |
|
|
35
|
+
| [分享与素材](sharing/README.md) | 分享、结果海报发帖、文件上传 | 3 |
|
|
36
|
+
| [存档与恢复](storage/README.md) | 云存档、本地数据保存和恢复 | 5 |
|
|
37
|
+
| [页面能力接入](runtime/README.md) | 业务请求、云请求、跳转、安全区、埋点与 AI 对话 | 9 |
|
|
38
|
+
| [检查与优化](quality/README.md) | 安全检查、WASM 压缩 | 3 |
|
|
39
|
+
|
|
40
|
+
# Examples
|
|
41
|
+
|
|
42
|
+
### 1) 通用虎扑业务请求
|
|
43
|
+
|
|
44
|
+
```javascript
|
|
45
|
+
window.ShaperAI.request({
|
|
46
|
+
url: 'https://activity.hupu.com/api/info',
|
|
47
|
+
method: 'GET'
|
|
48
|
+
}).then((res) => {
|
|
49
|
+
console.log(res.statusCode, res.data);
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### 2) 获取当前用户
|
|
54
|
+
|
|
55
|
+
```javascript
|
|
56
|
+
window.ShaperAI.auth.getUserInfo().then((res) => {
|
|
57
|
+
if (res.code !== 200) {
|
|
58
|
+
// Toast(res.message)
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
console.log(res.data?.puid, res.data?.nickname);
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 3) CloudBase:调活动网关
|
|
66
|
+
|
|
67
|
+
```javascript
|
|
68
|
+
// 活动 EnvId 由页面/配置注入,示例:
|
|
69
|
+
const envId = window.ACTIVITY_ENV_ID;
|
|
70
|
+
const apiBase = window.ACTIVITY_API_BASE; // 如 https://{envId}.service.tcloudbase.com/api
|
|
71
|
+
|
|
72
|
+
window.ShaperAI.cloud.request({
|
|
73
|
+
url: apiBase + '/vote',
|
|
74
|
+
method: 'POST',
|
|
75
|
+
envId,
|
|
76
|
+
auth: true,
|
|
77
|
+
data: { candidateId: '...' }
|
|
78
|
+
}).then((res) => {
|
|
79
|
+
if (res.code !== 200) {
|
|
80
|
+
// Toast(res.message)
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
console.log(res.data);
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
公开读接口可不登录:
|
|
88
|
+
|
|
89
|
+
```javascript
|
|
90
|
+
window.ShaperAI.cloud.request({
|
|
91
|
+
url: apiBase + '/candidates',
|
|
92
|
+
method: 'GET'
|
|
93
|
+
}).then((res) => console.log(res.data));
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### 4) 跳转
|
|
97
|
+
|
|
98
|
+
```javascript
|
|
99
|
+
window.ShaperAI.navigate.to({
|
|
100
|
+
url: 'https://m.hupu.com/',
|
|
101
|
+
target: '_blank'
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 5) 本地存储
|
|
106
|
+
|
|
107
|
+
```javascript
|
|
108
|
+
await window.ShaperAI.storage.setValue({ data: { draft: 'hello' } });
|
|
109
|
+
const saved = await window.ShaperAI.storage.getValue({ key: 'draft' });
|
|
110
|
+
console.log(saved);
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### 6) 埋点
|
|
114
|
+
|
|
115
|
+
点击与曝光必须双向成对:同一模块埋了点击就必须同时埋对应曝光,埋了曝光就必须同时埋对应点击,不能只实现单边;在模块实际可见、用户实际点击时分别上报。同一模块必须复用完全一致的中文 `ext.label` 字符串(包括空格和标点),不得分别添加“点击”“曝光”等前后缀,仅通过 `act` 区分事件。`ext.label` 统一使用 `业务场景-模块或入口` 结构,以半角连字符 `-` 分隔,保持简洁,控制在 10 个中文字以内(含 10 个字),如“活动首页-报名入口”“任务中心-奖励领取”“排行榜-选手详情”。完整规范见 [runtime/hupu-track-report/SKILL.md](runtime/hupu-track-report/SKILL.md)。
|
|
116
|
+
|
|
117
|
+
```javascript
|
|
118
|
+
// 页面需已有 id="activity-join-btn" 的参与按钮;在按钮渲染后绑定一次。
|
|
119
|
+
const joinButton = document.getElementById("activity-join-btn");
|
|
120
|
+
if (joinButton) {
|
|
121
|
+
const point = {
|
|
122
|
+
blk: "BMC001",
|
|
123
|
+
pos: "T1",
|
|
124
|
+
ext: {
|
|
125
|
+
label: "活动首页-报名入口",
|
|
126
|
+
custom: { activityId: 101, entryId: "mainVenue" }
|
|
127
|
+
}
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
joinButton.addEventListener("click", () => {
|
|
131
|
+
window.ShaperAI.track({ ...point, act: "click" });
|
|
132
|
+
// 在埋点之后执行实际参与操作或跳转。
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
let exposed = false;
|
|
136
|
+
const observer = new IntersectionObserver((entries) => {
|
|
137
|
+
entries.forEach((entry) => {
|
|
138
|
+
if (!exposed && entry.isIntersecting && entry.intersectionRatio >= 0.5) {
|
|
139
|
+
exposed = true;
|
|
140
|
+
window.ShaperAI.track({ ...point, act: "exposure" });
|
|
141
|
+
observer.unobserve(entry.target);
|
|
142
|
+
}
|
|
143
|
+
});
|
|
144
|
+
}, { threshold: 0.5 });
|
|
145
|
+
observer.observe(joinButton);
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
# 约束(总原则)
|
|
150
|
+
|
|
151
|
+
- 虎扑业务接口用 `window.ShaperAI.request`,不要直接 `fetch` / `XHR`(易跨域、丢登录头)
|
|
152
|
+
- CloudBase 活动接口用 `window.ShaperAI.cloud.*`,禁止手写 `Authorization` / 直连 `signin/custom`
|
|
153
|
+
- 跳转用 `window.ShaperAI.navigate.to`,不要用 `location.href` / `window.open`
|
|
154
|
+
- 云存档优先调用 `cloudSave.save({ slot, value })` / `cloudSave.load({ slot })`。slot 只接受 number 类型的整数 1–5,建议每个应用最多使用三个存档位;同编号完整覆盖,value 为字符串,每个存档最多 2MiB UTF-8 bytes。
|
|
155
|
+
- 云存档按白名单只存恢复必需且无法可靠重建的内容,已有数据优先存稳定 ID 及必要关系、顺序。按需读取,有变化才保存;结合实际功能选择手动或业务节点保存,仅有持续保护中途内容需求的功能启用持续自动保存,并合并变化、处理恢复时序,不默认给所有应用或功能添加自动保存。失败保留用户编辑,不能当成无记录写回默认值。保存时机、接口约定、数据取舍、读写示例与失败处理见 [storage/hupu-cloud-save/SKILL.md](storage/hupu-cloud-save/SKILL.md)。
|
|
156
|
+
- body / query **禁止**客户端自报 `puid` 等身份字段
|
|
157
|
+
- 云存档 `getValue/setValue` 的使用方法继续保留,供已有应用维护,作为非首选接口见 [旧接口用法与迁移方案](storage/hupu-cloud-save/references/legacy-migration.md)。无需强制迁移;决定切换到 `save/load` 时再按方案处理原数据,升级 SDK 不会自动迁移旧 key。
|
|
158
|
+
- 具体参数与错误码以各子 Skill 文档为准
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# 活动玩法
|
|
2
|
+
|
|
3
|
+
投票任务、PK、抽卡、排行榜。本目录仅分类,技能内容暂不重构。
|
|
4
|
+
|
|
5
|
+
- [hupu-leaderboard-template](hupu-leaderboard-template/SKILL.md)
|
|
6
|
+
- [hupu-lottery-draw](hupu-lottery-draw/SKILL.md)
|
|
7
|
+
- [hupu-pk-voting](hupu-pk-voting/SKILL.md)
|
|
8
|
+
- [hupu-request-activity-execute-vote-task](hupu-request-activity-execute-vote-task/SKILL.md)
|
|
9
|
+
- [hupu-request-activity-get-vote-detail](hupu-request-activity-get-vote-detail/SKILL.md)
|
|
10
|
+
- [hupu-request-activity-get-vote-task-list](hupu-request-activity-get-vote-task-list/SKILL.md)
|
|
11
|
+
- [hupu-request-activity-list-by-biz-keys](hupu-request-activity-list-by-biz-keys/SKILL.md)
|
|
12
|
+
- [hupu-request-activity-report-vote-task](hupu-request-activity-report-vote-task/SKILL.md)
|
|
13
|
+
- [hupu-request-activity-submit-vote](hupu-request-activity-submit-vote/SKILL.md)
|
|
14
|
+
- [hupu-vote-task](hupu-vote-task/SKILL.md)
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hupu-leaderboard-template
|
|
3
|
+
description: 使用活动数据存储创建可运行的移动端排行榜 H5 页面;适用于“实现一个排行榜功能”“做积分榜/排名榜”等请求,不用于仅展示静态榜单图片或后台报表。
|
|
4
|
+
metadata:
|
|
5
|
+
required-skills:
|
|
6
|
+
- act-cloudbase
|
|
7
|
+
- hupu-cloud-request
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# 排行榜功能模版
|
|
11
|
+
|
|
12
|
+
当用户提出“实现一个排行榜功能”或同义需求时,使用本技能生成一个真实可运行的活动 H5,而不是只给出 UI 草图。页面必须同时组合:
|
|
13
|
+
|
|
14
|
+
- `act-cloudbase`(活动数据存储):负责 PostgreSQL 数据表、云函数和网关接口。
|
|
15
|
+
- `hupu-cloud-request`:负责安全访问榜单接口。
|
|
16
|
+
|
|
17
|
+
## 实施顺序
|
|
18
|
+
|
|
19
|
+
1. 先阅读 `example/migrations/20260828210000_create_leaderboard.sql` 和 `example/README.md`,在 `act-cloudbase` 预置的 `activity_api` / `demo_items` 基线上改造,保留环境、权限、CORS 和迁移留档约定。不要另建第二套云函数。
|
|
20
|
+
2. 复制 `example/index.html` 到活动的 `h5/index.html`,按活动名称、接口前缀和业务字段调整。页面必须是原生 HTML/CSS/JS,可双击打开;不要引入 Vue、React、Vite 或运行时打包器。
|
|
21
|
+
3. 页面初始化时使用 `window.ShaperAI.cloud.request` 读取公开榜单;`code !== 200` 时用返回的 `message` 提示。禁止手写 Bearer、直接调用 `fetch` 或把虎扑 Token 写入页面。
|
|
22
|
+
4. 所有 CloudBase 请求必须使用 `window.ShaperAI.cloud.request`,并由服务端校验请求上下文和业务参数。页面不得提交用户身份字段或自行拼接鉴权信息。
|
|
23
|
+
5. 页面至少提供:榜单前 3 名突出展示、可扫描的排名列表、加载中/空榜/失败状态。若活动页面产生新成绩,提交接口只接受服务端可验证的业务事件;提交成功后重新读取榜单。
|
|
24
|
+
6. 所有服务端返回值都要检查 HTTP 状态和业务 `code`(兼容 `0` 与 `200`);错误优先展示服务端 `message`,不要吞掉错误或伪造成功提示。渲染昵称、活动名称等外部数据前进行 HTML 转义。
|
|
25
|
+
7. 交付前按 `act-cloudbase` 的流程完成迁移、函数、网关和接口冒烟;静态预览阶段可以使用模板中的本地演示数据,但上线前必须切换到真实接口并移除会掩盖服务端错误的生产降级。
|
|
26
|
+
|
|
27
|
+
## 示例目录
|
|
28
|
+
|
|
29
|
+
`example/` 是可直接参考的最小完整实现,不是第二套独立能力:
|
|
30
|
+
|
|
31
|
+
- `example/index.html`:原生移动端排行榜页面,包含榜单读取、加载/空榜/失败状态,以及 CloudBase 请求调用。
|
|
32
|
+
- `example/cloudfunctions/activity_api/`:`activity_api` HTTP 云函数示例,提供 `/health`、`/leaderboard`、`/leaderboard/me` 和 `/leaderboard/submit`,由网关上下文完成请求校验。
|
|
33
|
+
- `example/migrations/20260828210000_create_leaderboard.sql`:复用 `demo_items` 为 `leaderboard_entries` 的 PostgreSQL 迁移,包含最高分幂等写入函数、索引、权限和 RLS 处理。
|
|
34
|
+
|
|
35
|
+
复制示例时,先替换页面中的活动环境配置,再根据实际成绩来源决定是否保留 `/leaderboard/submit`;不要把示例中的演示成绩或环境占位符作为生产回退。
|
|
36
|
+
|
|
37
|
+
## 排名规则
|
|
38
|
+
|
|
39
|
+
- 默认按 `score DESC, updated_at ASC, id ASC` 排序;同分时先达到分数的用户优先,规则应在页面中明确说明。
|
|
40
|
+
- 榜单接口必须限制 `limit`(默认 50,最大 100),不得返回全表。
|
|
41
|
+
- “我的名次”使用索引友好的 `COUNT(*) + 1` 统计比分高的行,禁止 `RANK() OVER` 全表窗口排序。
|
|
42
|
+
- 写接口只接收业务分数或服务端可验证的事件结果,并在云函数中完成范围校验和限频。
|
|
43
|
+
- 高频积分不可通过对同一榜单行无限更新实现;优先使用明细事件表或带唯一约束的幂等 upsert,并在云函数中做范围校验和限频。
|
|
44
|
+
|
|
45
|
+
## 可复用资源
|
|
46
|
+
|
|
47
|
+
- [example/README.md](example/README.md):示例目录说明、接口契约和部署前检查项;需要调整活动后端时阅读。
|
|
48
|
+
- [example/migrations/20260828210000_create_leaderboard.sql](example/migrations/20260828210000_create_leaderboard.sql):可参考的 PostgreSQL 榜单迁移。
|
|
49
|
+
- [example/cloudfunctions/activity_api/index.js](example/cloudfunctions/activity_api/index.js):可参考的 `activity_api` 云函数实现。
|
|
50
|
+
- [example/index.html](example/index.html):可运行的原生 H5 模板;生成页面时复制并替换配置与文案。
|
|
51
|
+
|
|
52
|
+
完成后应留下 `h5/index.html`、迁移 SQL、云函数改造记录和活动 manifest,并说明真实榜单接口、同分规则及异常降级行为。`example/` 中的文件用于参考,不应直接作为活动线上资源发布。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Leaderboard Example
|
|
2
|
+
|
|
3
|
+
This directory is a reference implementation for the `hupu-leaderboard-template` skill.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- `index.html`: mobile-first H5 page using `window.ShaperAI.cloud.auth` and `window.ShaperAI.cloud.request`.
|
|
8
|
+
- `cloudfunctions/activity_api/`: Node.js HTTP function for the leaderboard API.
|
|
9
|
+
- `migrations/20260828210000_create_leaderboard.sql`: PostgreSQL migration that reuses the platform `demo_items` baseline as `leaderboard_entries`.
|
|
10
|
+
|
|
11
|
+
## API contract
|
|
12
|
+
|
|
13
|
+
- `GET /api/leaderboard`: authenticated top 50 entries, sorted by score descending, then `updated_at` ascending.
|
|
14
|
+
- `GET /api/leaderboard/me`: authenticated current-user score and rank.
|
|
15
|
+
- `POST /api/leaderboard/submit`: authenticated body `{ "score": 123, "displayName": "..." }`; the user ID comes from the gateway context, never from the body.
|
|
16
|
+
- `GET /api/health`: public health check.
|
|
17
|
+
|
|
18
|
+
The migration stores one highest score per user with a unique `puid` index and uses a PostgreSQL function for an atomic higher-score upsert. The function example includes grants and disables RLS on the activity table; review the environment's security policy before applying it.
|
|
19
|
+
|
|
20
|
+
Before deploying an adapted example, replace the page's `ACTIVITY_API_BASE` and `ACTIVITY_ENV_ID` with values from the actual activity environment, configure gateway auth/CORS, and run authenticated read/write smoke tests.
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
const http = require("http");
|
|
2
|
+
const zlib = require("zlib");
|
|
3
|
+
const tcb = require("@cloudbase/node-sdk");
|
|
4
|
+
|
|
5
|
+
const app = tcb.init({
|
|
6
|
+
env: process.env.CLOUDBASE_ENV_ID || process.env.TCB_ENV,
|
|
7
|
+
accessKey: process.env.COLORBOX__ACCESS_KEY
|
|
8
|
+
});
|
|
9
|
+
const rdb = app.rdb({ database: "public" });
|
|
10
|
+
const LEADERBOARD_TABLE = "leaderboard_entries";
|
|
11
|
+
|
|
12
|
+
function apiPath(req) {
|
|
13
|
+
const pathname = new URL(req.url, "http://localhost").pathname || "/";
|
|
14
|
+
return pathname.replace(/^\/api(?=\/|$)/, "") || "/";
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function readPuid(req) {
|
|
18
|
+
const raw = req.headers["x-cloudbase-context"];
|
|
19
|
+
if (!raw) {
|
|
20
|
+
const err = new Error("请先登录");
|
|
21
|
+
err.statusCode = 401;
|
|
22
|
+
throw err;
|
|
23
|
+
}
|
|
24
|
+
let buf = Buffer.from(String(raw).trim(), "base64");
|
|
25
|
+
if (buf.length >= 2 && buf[0] === 0x1f && buf[1] === 0x8b) {
|
|
26
|
+
buf = zlib.gunzipSync(buf);
|
|
27
|
+
}
|
|
28
|
+
const context = JSON.parse(buf.toString("utf8"));
|
|
29
|
+
const puid = context.customUserId || context.userId || context.uid;
|
|
30
|
+
if (!puid) {
|
|
31
|
+
const err = new Error("请先登录");
|
|
32
|
+
err.statusCode = 401;
|
|
33
|
+
throw err;
|
|
34
|
+
}
|
|
35
|
+
return String(puid);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function queryRows(result) {
|
|
39
|
+
if (!result) return [];
|
|
40
|
+
if (Array.isArray(result)) return result;
|
|
41
|
+
if (Array.isArray(result.data)) return result.data;
|
|
42
|
+
if (Array.isArray(result.rows)) return result.rows;
|
|
43
|
+
return [];
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function createMemoryCache(ttlMs) {
|
|
47
|
+
let value = null;
|
|
48
|
+
let expiresAt = 0;
|
|
49
|
+
const cached = async (fetcher) => {
|
|
50
|
+
if (value && Date.now() < expiresAt) return value;
|
|
51
|
+
value = await fetcher();
|
|
52
|
+
expiresAt = Date.now() + ttlMs;
|
|
53
|
+
return value;
|
|
54
|
+
};
|
|
55
|
+
cached.clear = () => {
|
|
56
|
+
value = null;
|
|
57
|
+
expiresAt = 0;
|
|
58
|
+
};
|
|
59
|
+
return cached;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const readLeaderboard = createMemoryCache(5000);
|
|
63
|
+
|
|
64
|
+
async function loadLeaderboard() {
|
|
65
|
+
return readLeaderboard(async () => {
|
|
66
|
+
const result = await rdb
|
|
67
|
+
.from(LEADERBOARD_TABLE)
|
|
68
|
+
.select("id, display_name, score, updated_at")
|
|
69
|
+
.order("score", { ascending: false })
|
|
70
|
+
.order("updated_at", { ascending: true })
|
|
71
|
+
.order("id", { ascending: true })
|
|
72
|
+
.limit(50);
|
|
73
|
+
return queryRows(result);
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function getJsonBody(req) {
|
|
78
|
+
return new Promise((resolve, reject) => {
|
|
79
|
+
let body = "";
|
|
80
|
+
req.on("data", chunk => {
|
|
81
|
+
body += chunk;
|
|
82
|
+
if (body.length > 65536) reject(new Error("请求内容过大"));
|
|
83
|
+
});
|
|
84
|
+
req.on("end", () => {
|
|
85
|
+
if (!body) return resolve({});
|
|
86
|
+
try { resolve(JSON.parse(body)); } catch { reject(new Error("请求格式不正确")); }
|
|
87
|
+
});
|
|
88
|
+
req.on("error", reject);
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
async function getRdbServiceToken() {
|
|
93
|
+
const credential = await app.auth().getClientCredential();
|
|
94
|
+
if (typeof credential === "string" && credential.trim()) return credential.trim();
|
|
95
|
+
if (credential && typeof credential.access_token === "string" && credential.access_token.trim()) {
|
|
96
|
+
return credential.access_token.trim();
|
|
97
|
+
}
|
|
98
|
+
const accessKey = process.env.COLORBOX__ACCESS_KEY;
|
|
99
|
+
if (accessKey && accessKey.trim()) return accessKey.trim();
|
|
100
|
+
throw new Error("数据库服务凭据不可用");
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
async function submitScore(puid, displayName, score) {
|
|
104
|
+
const token = await getRdbServiceToken();
|
|
105
|
+
const envId = process.env.CLOUDBASE_ENV_ID || process.env.TCB_ENV;
|
|
106
|
+
const response = await fetch(
|
|
107
|
+
`https://${envId}.api.tcloudbasegateway.com/v1/rdb/rest/rpc/submit_leaderboard_score`,
|
|
108
|
+
{
|
|
109
|
+
method: "POST",
|
|
110
|
+
headers: {
|
|
111
|
+
"Authorization": `Bearer ${token}`,
|
|
112
|
+
"X-Db-Instance": "default",
|
|
113
|
+
"Accept-Profile": "public",
|
|
114
|
+
"Content-Profile": "public",
|
|
115
|
+
"Content-Type": "application/json"
|
|
116
|
+
},
|
|
117
|
+
body: JSON.stringify({ p_puid: puid, p_display_name: displayName, p_score: score })
|
|
118
|
+
}
|
|
119
|
+
);
|
|
120
|
+
const raw = await response.text();
|
|
121
|
+
let data = raw;
|
|
122
|
+
try { data = raw ? JSON.parse(raw) : null; } catch { /* preserve text for logs */ }
|
|
123
|
+
if (!response.ok) {
|
|
124
|
+
console.error("[Leaderboard RPC Error]", response.status, data);
|
|
125
|
+
const err = new Error("成绩暂时无法保存");
|
|
126
|
+
err.statusCode = 500;
|
|
127
|
+
throw err;
|
|
128
|
+
}
|
|
129
|
+
return Array.isArray(data) ? data[0] : data;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
async function handle(req, res) {
|
|
133
|
+
const headers = {
|
|
134
|
+
"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
|
|
135
|
+
"Access-Control-Allow-Headers": "Content-Type, Authorization, X-Request-Id, X-CloudBase-Context",
|
|
136
|
+
"Content-Type": "application/json; charset=utf-8"
|
|
137
|
+
};
|
|
138
|
+
if (req.method === "OPTIONS") {
|
|
139
|
+
res.writeHead(204, headers);
|
|
140
|
+
return res.end();
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
const path = apiPath(req);
|
|
144
|
+
try {
|
|
145
|
+
if (req.method === "GET" && path === "/health") {
|
|
146
|
+
res.writeHead(200, headers);
|
|
147
|
+
return res.end(JSON.stringify({ code: 0, message: "ok" }));
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
if (req.method === "GET" && path === "/leaderboard") {
|
|
151
|
+
const puid = readPuid(req);
|
|
152
|
+
const rows = await loadLeaderboard();
|
|
153
|
+
const data = rows.map((row, index) => ({
|
|
154
|
+
rank: index + 1,
|
|
155
|
+
displayName: row.display_name,
|
|
156
|
+
score: Number(row.score),
|
|
157
|
+
updatedAt: row.updated_at,
|
|
158
|
+
isCurrent: false
|
|
159
|
+
}));
|
|
160
|
+
const mine = await rdb.from(LEADERBOARD_TABLE).select("score").eq("puid", puid).limit(1);
|
|
161
|
+
const myRows = queryRows(mine);
|
|
162
|
+
const myScore = myRows.length ? Number(myRows[0].score) : null;
|
|
163
|
+
if (myScore !== null) {
|
|
164
|
+
const higher = await rdb.from(LEADERBOARD_TABLE).select("score", { count: "exact" }).gt("score", myScore);
|
|
165
|
+
const rank = (typeof higher.count === "number" ? higher.count : queryRows(higher).length) + 1;
|
|
166
|
+
for (const entry of data) {
|
|
167
|
+
if (entry.score === myScore && entry.rank === rank) entry.isCurrent = true;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
res.writeHead(200, headers);
|
|
171
|
+
return res.end(JSON.stringify({ code: 0, message: "success", data }));
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
if (req.method === "GET" && path === "/leaderboard/me") {
|
|
175
|
+
const puid = readPuid(req);
|
|
176
|
+
const result = await rdb.from(LEADERBOARD_TABLE).select("score, display_name, updated_at").eq("puid", puid).limit(1);
|
|
177
|
+
const rows = queryRows(result);
|
|
178
|
+
if (!rows.length) {
|
|
179
|
+
res.writeHead(200, headers);
|
|
180
|
+
return res.end(JSON.stringify({ code: 0, message: "success", data: null }));
|
|
181
|
+
}
|
|
182
|
+
const score = Number(rows[0].score);
|
|
183
|
+
const higher = await rdb.from(LEADERBOARD_TABLE).select("score", { count: "exact" }).gt("score", score);
|
|
184
|
+
const rank = (typeof higher.count === "number" ? higher.count : queryRows(higher).length) + 1;
|
|
185
|
+
res.writeHead(200, headers);
|
|
186
|
+
return res.end(JSON.stringify({ code: 0, message: "success", data: { rank, score, displayName: rows[0].display_name } }));
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
if (req.method === "POST" && path === "/leaderboard/submit") {
|
|
190
|
+
const puid = readPuid(req);
|
|
191
|
+
const body = await getJsonBody(req);
|
|
192
|
+
const score = Number(body.score);
|
|
193
|
+
if (!Number.isSafeInteger(score) || score < 0 || score > 2147483647) {
|
|
194
|
+
const err = new Error("成绩格式不正确");
|
|
195
|
+
err.statusCode = 400;
|
|
196
|
+
throw err;
|
|
197
|
+
}
|
|
198
|
+
const displayName = typeof body.displayName === "string" && body.displayName.trim()
|
|
199
|
+
? body.displayName.trim().slice(0, 40)
|
|
200
|
+
: "Hupu User";
|
|
201
|
+
const data = await submitScore(puid, displayName, score);
|
|
202
|
+
readLeaderboard.clear();
|
|
203
|
+
res.writeHead(200, headers);
|
|
204
|
+
return res.end(JSON.stringify({ code: 0, message: "success", data: { score: Number(data.score), displayName: data.display_name } }));
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
res.writeHead(404, headers);
|
|
208
|
+
return res.end(JSON.stringify({ code: 404, message: "not found" }));
|
|
209
|
+
} catch (err) {
|
|
210
|
+
console.error("[Activity API Error]", err);
|
|
211
|
+
const statusCode = err.statusCode || 500;
|
|
212
|
+
const message = statusCode < 500 ? (err.message || "请求失败") : "服务暂时不可用";
|
|
213
|
+
res.writeHead(statusCode, headers);
|
|
214
|
+
return res.end(JSON.stringify({ code: statusCode, message }));
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
http.createServer(handle).listen(process.env.PORT || 9000);
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "activity_api",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "CloudBase leaderboard activity API",
|
|
5
|
+
"main": "index.js",
|
|
6
|
+
"scripts": {
|
|
7
|
+
"start": "node index.js"
|
|
8
|
+
},
|
|
9
|
+
"engines": {
|
|
10
|
+
"node": ">=18.15"
|
|
11
|
+
},
|
|
12
|
+
"dependencies": {
|
|
13
|
+
"@cloudbase/node-sdk": "^3.16.0"
|
|
14
|
+
}
|
|
15
|
+
}
|