WeChat Weekly Leaderboard

Overview

Implement WeChat mini game weekly friend leaderboards through the open data domain. Keep the main domain responsible for game state, score submission, panel layout, and sharedCanvas compositing; keep the open data domain responsible only for relationship-chain data reads and leaderboard drawing.

Read references/wechat-open-data-weekly.md before editing leaderboard code. It contains the implementation contract, message schema, async rendering guardrails, and validation checklist.

Workflow

1. Read the project rules first, especially AGENTS.md and any existing directory conventions.
2. Locate existing entry points: game.js, game.json, score/state logic, renderer/panel logic, storage helpers, and any open-data/ directory.
3. If the project lacks leaderboard structure, add or document these roles before coding:
   - Main domain bridge, usually js/leaderboard.js.
   - Open data domain entry, usually open-data/index.js and open-data/game.js.
   - game.json openDataContext configuration.
   - README or project notes for backend configuration of the leaderboard key.
4. Implement main-domain score submission:
   - Keep a local weekly best record keyed by week id.
   - Submit only the best weekly score through wx.setUserCloudStorage.
   - Store the value as JSON with wxgame.score, wxgame.update_time, weekId, and optional metadata such as bestLevel.
5. Implement main-domain panel drawing:
   - Send showWeeklyLeaderboard messages with content size, pixel ratio, key, week id, local/self score, and current run metadata.
   - Resize and draw sharedCanvas inside the existing panel rectangle.
   - Provide a short loading fallback when open data is unavailable.
6. Implement open-data rendering:
   - Read friends with wx.getFriendCloudStorage({ keyList: [key] }).
   - Read self with wx.getUserCloudStorage when available.
   - Normalize both WeChat ranking JSON and plain numeric values.
   - Filter out scores from other weeks.
   - Merge local self fallback only when cloud self data is missing or stale.
   - Sort descending, dedupe self, and render rows to sharedCanvas.
7. Protect async rendering:
   - Use monotonically increasing request ids to ignore stale callbacks.
   - Cache the latest valid friend-inclusive rows for the current key + weekId.
   - Do not let a later retry or failed request overwrite a displayed friend list with a self-only fallback.
8. Validate with syntax checks and a mocked open-data scenario where possible.

Implementation Rules

• Do not put main game logic in open-data/.
• Do not use a backend, cloud database, or third-party game engine unless the project explicitly already uses one.
• Do not report every score change if a local weekly best has already been uploaded.
• Do not display stale cross-week scores.
• Do not use hard-coded panel coordinates if the renderer already exposes a content rectangle.
• Do not rely on ctx.roundRect; use a manual path helper for WeChat Canvas compatibility unless the project already wraps it safely.

Validation

Run the project's declared validation commands. For simple native JavaScript projects, also run:

node --check game.js
Get-ChildItem js -Filter *.js | ForEach-Object { node --check $_.FullName }
node --check open-data\index.js
node --check open-data\game.js

When fixing flicker or fallback bugs, add or run a lightweight mocked test that simulates:

1. First showWeeklyLeaderboard request returns friend rows.
2. Later duplicate showWeeklyLeaderboard request fails or returns only self.
3. Final rendered rows still include the previously displayed friends.