Web Launch

Overview

End-to-end guide for taking a website or web app from an empty folder to a live URL on WorkBuddy.
Covers two deploy shapes (static site vs single-port Node app) and two product flavors:

• Static brand / marketing site — 品牌官网、落地页、招商页、门店/农场/工厂介绍站. Zero runtime,
  zero dependencies, trust-first sections, WeChat-QR conversion. Playbook in
  references/static-brand-site.md.
• Node app — login, forum, prompt library, any runtime API or persistence, optional WeChat
  mini-program sync.

Plus: the "发布为应用" (Publish as App) deploy mechanism, a near-monochrome clean editorial visual
system, multi-channel login (WeChat QR / SMS code / password) gated by environment variables,
zero-dependency WeChat/SMS integration, media craft (image cropping, scannable QR design, original
synthesized background music), and the deploy-cache + browser-testing traps that silently break
"it works locally but not online".

When to use

• "帮我建个网站 / 上线一个站点 / 做个品牌官网 / 落地页" / "发布为应用" / "把静态站改成 Node 应用"
• Building a brand/marketing page from supplied materials (including a scanned brand book PDF)
• The site needs login, a forum, a prompt library, or any runtime API
• WeChat QR login, SMS verification code, or site↔mini-program sync is required
• Needing site imagery, a scannable WeChat QR, or original royalty-free background music
• A "local works, online shows the old version" cache problem appears

Workflow

Step 0 — Pick the flavor, then the shape

• Brand / marketing site (no login/API) → static (language: static). Follow
  references/static-brand-site.md end to end. This is the common case for 品牌官网/落地页.
• Content / community / tool site with login or API → single-port Node app (language: node);
  continue Steps 1–9 below.

Step 1 — Choose the deploy shape

Decide between static site and single-port Node app before writing code. Full checklist in references/deploy-decisions.md. Short version:
- Pure content/marketing page, no server logic → static (language: static).
- Needs login, API, forum, or any runtime state → single-port Node app (language: node). The whole site (HTML/CSS/JS + server/) is served by one Node HTTP process; the frontend calls a same-origin /api, so no CORS is needed.

Step 2 — Scaffold the project

For a Node app, create at the project root:
- package.json with "scripts": { "start": "node server/server.js" }
- server/ with server.js (ESM: add "type":"module" in server/package.json) and store.js
Copy the runnable skeleton from assets/min-node-app/ and adapt.

Step 3 — Build pages + visual system

Apply a consistent, near-monochrome "clean editorial" look. Start from assets/style-v6.css (1240px container, 120px section rhythm, large left-aligned h1, a three-state card pattern). Keep all shared class names stable across archived pages so old pages keep rendering after a redesign.
For a brand site, use the trust-first section order in references/static-brand-site.md §4 and
keep the build zero-dependency / no external CDN (§0) for China speed.

Step 4 — Add backend / API

In server.js, serve static files from the project root and route /api/* to JSON handlers (auth, posts, likes). Persist with a file-based JSON store (store.js) for MVP; note it may reset on container restart (mitigate with an idempotent seed script). Always server.listen(PORT, '0.0.0.0', ...) so the sandbox can reach it, and read PORT from env.

Step 5 — Implement auth (multi-channel, env-gated)

Build one login modal with three channels, each gated by env vars so the site runs with zero credentials:
- WeChat QR — enabled when WX_APPID+WX_SECRET are set
- SMS code — enabled when an SMS provider is configured
- Password — always available as fallback
Route the default pane by availability (WeChat → SMS → password) so an unconfigured channel never shows a dead end. See references/auth-channels.md.

Step 6 — WeChat / SMS zero-dependency integration

WeChat QR: generate the open.weixin.qq.com/connect/qrconnect URL; the callback exchanges code for openid and auto-creates the user. For the WeChat domain-ownership check, add a /MP_verify_*.txt route that returns the verification file content (no static file needed). SMS: sign requests with node:crypto (Aliyun HMAC-SHA1 / Tencent TC3-HMAC-SHA256) — no SDK install. Details in references/auth-channels.md.

Step 7 — Media craft (images, QR, background music)

Any brand site needs this step; see references/media-and-assets.md:
- Images: crop from scans, web sizes, loading="lazy"; handle non-ASCII paths with imdecode.
- WeChat QR: never redraw the code; tight crop → ×3 upscale → mild sharpen → ≥4-module quiet
zone → JPEG subsampling=0; verify with two decoders (OpenCV + zxing-cpp) and re-verify on the
rendered page.
- Original BGM: synthesize (per-instrument modelling, true crossfade loop, −1.5dBFS), encode with
-write_xing 1, and handle the browser autoplay policy with a first-gesture takeover.

Step 8 — Mini program sync (optional)

If a WeChat mini program mirrors the site, generate its data/content.js from the live site via a gen_data.py that pulls /api/questions?sort=hot and /api/prompts. Keep site and mini program on the same source; re-publish the mini program from its panel after each site content change.

Step 9 — Deploy via 发布为应用

Use the "发布为应用" (Publish as App) capability. Reuse the same app id to keep the public URL unchanged. Pass startCmd with required env vars (e.g. ADMIN_TOKEN=xxx node server/server.js). Setting env vars and reusing the app id are deploy actions that require explicit user confirmation (deploy red-light). See references/deploy-decisions.md.

Step 10 — Verify online + dodge cache pitfalls

After deploy, verify with a real browser (CDP), not just curl — curl with ?cb= bypasses the CDN cache and lies. Stamp every static asset URL with a version query (assets/style.css?v=6.7) and bump it on each redesign; rename media files (not just the URL) on replacement. Watch for the headless-test traps in references/pitfalls.md (empty seekable looks like a broken loop; --mute-audio hides sound; lazy images look broken). Full list in references/pitfalls.md.

Resources

• references/static-brand-site.md — static high-end brand-site playbook: file layout, scanned-PDF
  sourcing, food/claims compliance, trust-first section order, WeChat-QR conversion, SEO/JSON-LD,
  placeholder discipline, real-browser verification
• references/media-and-assets.md — image cropping (non-ASCII path trap), scannable pretty QR design
• dual-decoder verification, original royalty-free BGM synthesis (instrument modelling, seamless
  loop, Xing header, autoplay policy)
• references/deploy-decisions.md — static-vs-Node checklist, deploy command / env-var notes, ESM + persistence
• references/pitfalls.md — cache traps, JSON-reset mitigation, WeChat domain-verify route, headless-test traps
• references/auth-channels.md — WeChat QR + SMS zero-dep integration, multi-channel gating
• assets/min-node-app/ — runnable zero-dep Node skeleton (server.js, store.js, package.json)
• assets/style-v6.css — clean editorial visual starter