AppClimb

AppClimb — App Store 关键词探索工具

AppClimb 是一款免费增值的 App Store 关键词工具，旨在回答一个问题： 我的应用实际上能在哪些关键词上获得排名？

搜索任意关键词，即可查看 Apple 官方广告热度 （searchPopularity1to100，1–100），以及 Apple 自有的每周历史数据、 展示依据的难度估算和判断（值得投放、长尾机会、竞争激烈、已被主导、需求较低）。关键词探索工具支持访客使用（每天可进行 8 次新查询）。免费账户每天可查询 30 次，还能解锁 1 个跟踪应用和 ASO 助手（每天 5 条消息）。可选的 Pro 方案（每月 $8，每年 $64）可提高 使用限额，增加 52 周 Apple 历史数据，并支持云同步。

热度是 Apple 的相对评分；对于在所属类别中排名低于 Apple 公布的前 500 位的词条，会显示为“≤N · 长尾”；只有在 Apple 无法访问时，才会显示带有明确标注的估算值。难度始终是估算值。这些数据都不是 搜索量，也不会编造历史数据。详见 ADR 0005。

产品功能

• 关键词探索工具（/）——搜索时可从 Apple 的真实 App Store 搜索词列表中 自动补全；查看“大家在搜什么”面板（飙升词、搜索量最高词、本月新词、按类别查看）； 关键词表格会显示热度（标注来源）、Apple 12 周趋势、难度和判断；详情 面板会显示判断原因、难度依据、Apple 每周 热度图表、Apple 相关搜索和排名前 10 的应用。
• 我的应用跟踪器（/，侧边栏）——通过名称、App Store URL 或 ID 添加 iOS 应用；获取基于元数据的关键词建议；跟踪评分、公开 iTunes 搜索结果中的 观测排名（前 200 位）、备注、机会评分、状态筛选、CSV 导出，以及每个应用和店面本地保存的真实排名历史。
• 店面——支持 16 个国家/地区。
• 本地历史记录——关键词探索工具：每个关键词每天保存一条真实快照，位于 appclimb:kw:v1:*（2026 年 10 月之前的记录包含虚构基线；加载时会删除这些数据点）。我的应用：真实排名/指标快照位于 appclimb:tracker:v1。
• 账户与 Pro（ADR 0004）——无密码登录（Google OAuth 或电子邮件魔法链接）、Paddle 账单、按方案管理配额、Pro 云同步，以及用户自助删除账户；每周清理任务会执行 /privacy 中的保留期限 （src/lib/retention.ts）。访客仍可使用搜索功能。跟踪器和助手需要免费账户。账户界面会在 NEXT_PUBLIC_PRO_ENABLED=1 或 GET /api/me 返回 configured: true 时显示。
• Agent 访问（ADR 0008）——位于 /mcp 的远程 MCP 服务，以及位于 /connect 的设置页面。已通过 server.json 列入官方 MCP Registry； Claude/ChatGPT 目录状态和提交文案见 docs/mcp-directory-submissions.md， 其中包括供目录审核人员使用的一次性密码登录 （src/lib/review-login.ts，除非设置了对应密钥，否则处于关闭状态）。
• 营销页面——/app-store-keywords、/guides/keyword-research、 /blog（+ 4 篇短文）、/about、/pricing、/privacy、/terms、/refunds。

架构

单个 Next.js 应用，通过 OpenNext 部署为 Cloudflare Worker。浏览器直接查询 itunes.apple.com（Apple 允许 CORS *，但会屏蔽 Cloudflare Worker IP）。官方热度数据来自 Worker 存储的 Apple 每周发布的搜索词（使用创始人的凭据调用 Apple Ads Platform API v1，并缓存到 D1；首次使用新的 storefront-week 时需要顺序调用 Apple 接口约 8 次，.github/workflows/warm-apple-terms.yml 会预先加载这些数据）。默认情况下，关键词历史记录保存在访问者的浏览器中。

变现功能运行在同一 Worker 上，并使用 D1 数据库（appclimb-db，暂存环境为 appclimb-db-staging）：

• src/app/api/auth/* — magic link + Google 登录、退出登录
• src/app/api/me — 个人资料、套餐、限制
• src/app/api/sync — Pro 云同步（tracker / explorer 数据块，LWW）
• src/app/api/billing/webhook — 已签名的 Paddle 事件 → D1 订阅
• src/app/api/billing/portal — Paddle 订阅管理 URL
• src/app/api/chat、src/app/api/popularity — 根据套餐设置配额
• src/app/api/terms/{suggest,related,trending} — Apple 发布的搜索词（由 D1 支持的存储位于 src/lib/search-terms-store.ts）
• migrations/ — D1 架构；src/lib — 套餐／身份验证／账单／同步／配额库
• worker/、deploy/、compose.yml — 早期架构遗留的冻结回滚产物；不是当前后端

本地开发

npm install
npm run dev

Keyword Explorer / My Apps 无需环境变量即可使用（回退到 iTunes 估算数据）。

官方 Apple Ads 热度数据需要仅供服务端使用的创始人凭据：

# local — see .env.example
APPLE_ADS_CLIENT_ID=...
APPLE_ADS_TEAM_ID=...
APPLE_ADS_KEY_ID=...
APPLE_ADS_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
APPLE_ADS_ACCOUNT_ID=...

# production Worker secrets (never commit)
npx wrangler secret put APPLE_ADS_CLIENT_ID
npx wrangler secret put APPLE_ADS_TEAM_ID
npx wrangler secret put APPLE_ADS_KEY_ID
npx wrangler secret put APPLE_ADS_PRIVATE_KEY
npx wrangler secret put APPLE_ADS_ACCOUNT_ID

可选的 ASO Assistant（DeepSeek V4 Flash）需要一个仅供服务端使用的密钥：

# local
echo 'DEEPSEEK_API_KEY=sk-...' >> .env.local

# production Worker secret (never commit the key)
npx wrangler secret put DEEPSEEK_API_KEY

此密钥仅用于 POST /api/chat，绝不会发送到浏览器。

变现功能设置（账户 · Paddle · 同步）

后端默认未启用：在创始人完成以下清单之前，各路由会返回 503，账户界面也会隐藏。请先在沙盒环境中完成，然后再为生产环境重复操作。

1. 数据库 — 已创建：appclimb-db（生产环境）和 appclimb-db-staging。本地开发：npx wrangler d1 migrations apply appclimb-db --local。
2. Paddle — 在 paddle.com 创建账户，然后在 Products 下创建 “AppClimb Pro”，并设置两个价格：Pro Monthly $8 和 Pro Yearly $64。记下对应的价格 ID。在 Sandbox → Developer tools → Authentication 中获取 API key、client-side token 和 notification/webhook secret。
3. Webhook — 在 Paddle 中订阅订阅事件（subscription.created/updated/paused/canceled），并将其指向 https://appclimb.app/api/billing/webhook。
4. Google OAuth — 在 Google Cloud Console → APIs & Services → Credentials → OAuth client (Web) 中，将 https://appclimb.app/api/auth/google/callback 添加为授权重定向 URI。
5. Resend — 前往 resend.com 获取 API key，并验证 appclimb.app 为发件域名（添加其显示的 DNS 记录）。
6. 服务端密钥（Worker，绝不提交到版本库）：

   npx wrangler secret put PADDLE_API_KEY
   npx wrangler secret put PADDLE_WEBHOOK_SECRET
   npx wrangler secret put RESEND_API_KEY
   npx wrangler secret put GOOGLE_CLIENT_ID
   npx wrangler secret put GOOGLE_CLIENT_SECRET
   npx wrangler secret put PRO_ENABLED   # value: 1  — enables plan quotas
   

7. 公开的构建时变量 — 前往 GitHub → 仓库 Settings → Secrets and variables → Actions → Variables： NEXT_PUBLIC_PRO_ENABLED=1、NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=<client token>、 NEXT_PUBLIC_PADDLE_ENV=sandbox（之后改为 production）、 NEXT_PUBLIC_PADDLE_PRICE_PRO_MONTHLY=<price id>、 NEXT_PUBLIC_PADDLE_PRICE_PRO_YEARLY=<price id>。
8. 暂存环境 — 使用 npm run deploy:cloudflare:web:staging 部署，并在切换到生产环境之前，为 staging 环境设置相同的密钥（npx wrangler secret put ... --env staging）。

验证

npm run lint
npm run typecheck
npm test
npm run build
npm run build:cloudflare
npm run test:e2e

npm run check 会运行 lint、类型检查、覆盖率检查以及两种构建。

生产环境配置

推送到 main 后会运行 .github/workflows/cloudflare-deploy.yml，构建项目、应用 D1 迁移、部署 Web Worker、验证规范主页、等待站点地图就绪，并通知 IndexNow。部署会立即生效——推送前请运行 npm run check 和 npm run test:e2e。

生产环境的规范主机是 https://appclimb.app；暂存 Worker 是 appclimb-web-staging。