NextStop 使用指南 / User Guide

中英双语。面向三类使用者:普通用户、社区与基地方、管理员。 Bilingual. Three audiences: Visitors, Communities & Spaces, Admins.

线上站点 / Live site: https://nextstop.pages.dev

---

1. 普通用户 / For Visitors

中文

• 浏览目录:在首页可以浏览数字游民城市、基地(社区)与活动。
• 加入候补 / 留资:在首页填写邮箱并提交,即进入审核队列;提交成功会看到「已提交,等待审核」提示。
• 入住登记:在「入住登记」页填写姓名、手机号、入住日期等,提交后进入审核队列。
• 联系方式要求:任意一种即可(邮箱 / 手机号 / 微信),但至少要留一个,否则会被拒绝。
• 审核后可见:所有提交都会先经管理员审核,通过后才会出现在公开目录里。

English

• Browse the directory of nomad cities, spaces (communities), and events on the home page.
• Join the waitlist: enter your email on the home page and submit — it enters the moderation queue and you'll see a "submitted, pending review" toast.
• Stay registration: fill the "入住登记" form (name, phone, check-in date) to register interest.
• Contact requirement: at least one of email / phone / WeChat is required, or the submission is rejected.
• Visible after review: every submission is moderated by an admin before it appears publicly.

---

2. 社区与基地方 / For Communities & Spaces

中文

• 社区 / 基地入驻:在「社区入驻」页填写基地名称、城市、地址、月均参考价、简介与联系人信息,提交后进入审核。
• 提交活动:在「提交社区活动」页填写活动标题、日期、地点、人数上限、报名费等,提交后进入审核。
• 通过后自动上架:管理员批准后,记录状态变为 published,即出现在公开目录与开放 API 中。
• 开发者 / 数据接入:目录数据可通过只读 API 获取(见下表),方便二次开发或聚合。

English

• List a community/space: use the "社区入驻" form (name, city, address, monthly price, description, contact) — it enters moderation.
• Submit an event: use the "提交社区活动" form (title, date, venue, capacity, fee) — it enters moderation.
• Auto-published on approval: once an admin approves, the record becomes published and shows up in the public directory and the open API.
• Developers / data access: the directory is available through read-only APIs (table below).

开放只读 API / Public read-only API

提交类接口 / Submission endpoints:POST /api/submissions/{join|stay|community|event},请求体为 JSON。 返回统一为 { "ok": true, "data": … } 或 { "ok": false, "error": { "code", "message" } }。

---

3. 管理员 / For Admins

中文

• 审核后台地址:https://nextstop.pages.dev/admin.html
• 登录方式:在页面顶部输入框粘贴 ADMIN_API_TOKEN,点 Load。令牌会保存在浏览器 localStorage,并以 Authorization: Bearer <token> 发送。
• 审核操作:选择状态(pending / approved / rejected)与类型过滤 → Load 列表 → 对每条点 Approve / Reject。每次操作都会写入审计日志(操作者记为 api-admin)。
• 令牌存放在哪:ADMIN_API_TOKEN 是 Cloudflare Pages 加密 secret,不在 Git 里,也无法读回。 这是刻意设计——面板里只能看到名字,看不到值。
• 设置 / 轮换令牌: ``bash # 生成强随机串 openssl rand -hex 32 # 写入生产 secret(交互式粘贴,或用管道) printf '%s' "<新令牌>" | wrangler pages secret put ADMIN_API_TOKEN --project-name=nextstop # 重新部署以让运行中的生产部署绑定新 secret(关键!否则新值不生效) npm run deploy ``
• 一键轮换脚本:仓库内置 scripts/rotate-admin-token.sh(或 npm run token:rotate),自动完成 「生成 → 写 secret → 重新部署 → 验证」全过程;加 -y 跳过确认,--no-deploy 只写 secret 不部署。
• 丢了怎么办:无法找回,按上面步骤重新生成一个即可,旧令牌随即失效。

English

• Admin console: https://nextstop.pages.dev/admin.html
• Sign in: paste ADMIN_API_TOKEN into the top input and click Load. It's kept in the browser's localStorage and sent as Authorization: Bearer <token>.
• Moderate: pick a status (pending / approved / rejected) and optional type filter → Load → click Approve / Reject per row. Every action writes an audit-log entry (actor recorded as api-admin).
• Where the token lives: ADMIN_API_TOKEN is an encrypted Cloudflare Pages secret — not in Git and not readable back by design; the dashboard shows only its name, never its value.
• Set / rotate the token: ``bash openssl rand -hex 32 # generate a strong value printf '%s' "<new-token>" | wrangler pages secret put ADMIN_API_TOKEN --project-name=nextstop npm run deploy # REQUIRED: redeploy to bind the new secret ``
• One-command rotation: the repo ships scripts/rotate-admin-token.sh (or npm run token:rotate) that runs generate → set secret → redeploy → verify; pass -y to skip the prompt, --no-deploy to set the secret only.
• Lost it? It can't be recovered — generate a new one with the steps above; the old one stops working.

说明 / Note:后台目前用单一令牌鉴权(pre-auth 阶段的过渡方案),尚无每用户登录 / 角色权限; 真正的邮箱/OAuth 登录与会话角色是后续计划项(见 docs/backend-plan.md P3)。 The console currently uses single-token auth (a pre-auth stopgap); per-user login and role checks are planned (see docs/backend-plan.md P3).