8.3 KiB
8.3 KiB
后台管理独立前端工程 PRD
日期：2026-04-30
1. 目标
本 PRD 定义当前项目的后台管理独立前端工程 v1。目标不是重做一套后端，也不是把玩家端前端改造成后台，而是在 monorepo 内新增一个独立管理端应用，正式承接已经从 api-server 内嵌页面移出的后台 UI。
首版目标：
- 后台 UI 独立落在
apps/admin-web，不再写入 Rust 源码字符串。 - 管理数据、业务规则、权限校验和写操作继续统一走
server-rs/crates/api-server。 - v1 只接管已有管理能力：管理员登录、当前管理员信息、服务/数据库概览、受控 API 调试、兑换码管理、注册邀请码管理。
- 保持管理端清爽、可扫读、移动端可用，不在界面堆大段规则说明。
2. 用户与使用场景
2.1 目标用户
- 项目开发者：用于本地或测试环境快速查看
api-server与 SpacetimeDB 连接状态。 - 运维/运营人员：用于创建、更新、停用兑换码，预置注册邀请码，以及确认后台接口是否可用。
- 后续后台功能开发者：以本工程作为后续用户、作品、资产、审核等管理模块的承载壳。
2.2 首版高频场景
- 管理员打开后台登录页，输入环境变量配置的管理员用户名和密码。
- 登录后进入总览页，确认当前服务监听、JWT issuer、SpacetimeDB server/database、schema 表数量和关键表统计。
- 在 API 调试页对当前
api-server的同源相对路径发起受控请求，排查接口状态。 - 在兑换码管理页创建或更新公共码、唯一码、私有码，并在需要时停用兑换码。
- 在邀请码管理页创建或更新注册链路使用的邀请码与 metadata。
3. 功能范围
3.1 包含
- 独立前端工程骨架：
apps/admin-web。 - 登录页：
- 调用
POST /admin/api/login。 - 登录成功后保存管理员 Bearer token。
- 登录失败直接展示后端返回的错误消息。
- 调用
- 管理端 Shell：
- 顶部显示当前管理员、登录状态和退出按钮。
- 侧边或底部导航包含“总览”“API 调试”“兑换码”“邀请码”。
- 移动端导航改为底部或顶部紧凑标签。
- 总览页：
- 调用
GET /admin/api/me恢复管理员会话。 - 调用
GET /admin/api/overview展示服务和数据库概览。 - 表统计允许部分失败，并直接展示失败项。
- 调用
- API 调试页：
- 调用
POST /admin/api/debug/http。 - 只允许填写同源相对路径，不提供绝对 URL 输入暗示。
- 调试结果在独立结果面板展示状态码、响应头、响应文本和 JSON 预览。
- 调用
- 兑换码管理页：
- 调用
POST /admin/api/profile/redeem-codes创建/更新兑换码。 - 调用
POST /admin/api/profile/redeem-codes/disable停用兑换码。 - 支持
public、unique、private三种模式。 - 私有码支持输入内部
userId和公开陶泥号，提交给后端统一解析。
- 调用
- 邀请码管理页：
- 调用
POST /admin/api/profile/invite-codes创建/更新注册邀请码。 - 支持输入 JSON 对象 metadata，提交前做基础 JSON 对象校验，最终校验以服务端为准。
- 调用
3.2 不包含
- 不新建后台专用后端服务、BFF、Express 服务或 PostgreSQL 数据面。
- 不让管理端直接连接 SpacetimeDB TypeScript SDK。
- 不新增 SpacetimeDB 表结构。
- 不实现完整用户管理、作品审核、资产审核、充值订单后台。
- 不实现多角色权限体系、管理员 refresh session、多端会话管理。
- 不保留
GET /admin同源内嵌页面作为正式后台入口。
4. 页面与交互要求
4.1 登录页
登录页只保留必要输入和状态反馈：
- 用户名输入框。
- 密码输入框。
- 登录按钮。
- 登录失败状态。
- 后台未启用状态。
后台未启用时，前端根据 POST /admin/api/login 的 503 响应展示不可登录状态，不额外引导用户在页面配置环境变量。
4.2 总览页
总览页必须能快速扫读：
- 服务状态：监听地址、端口、JWT issuer。
- SpacetimeDB 配置：server URL、database。
- 数据库元信息：database identity、owner identity、host type。
- 表清单与表统计：展示成功计数和失败原因。
总览页不展示任意 SQL 输入框。
4.3 API 调试页
API 调试页是受控接口调试台，不是通用代理工具：
- method 使用选择控件。
- path 只接受
/xxx形式。 - headers 使用结构化键值编辑。
- body 使用文本框。
- 结果展示在固定结果面板，不在按钮下方临时插入内容。
4.4 兑换码管理页
兑换码管理页首版采用一个创建/更新表单和一个停用表单：
- code：提交前可在前端 trim，但最终标准化以服务端为准。
- mode：
public、unique、private。 - rewardPoints：必须为正整数，最终校验以服务端为准。
- maxUses：必须为正整数，最终校验以服务端为准。
- enabled：创建/更新时可切换。
- allowedUserIds：私有码允许的内部用户 ID 列表。
- allowedPublicUserCodes：私有码允许的公开陶泥号列表。
提交成功后展示后端返回的兑换码记录；失败时展示后端错误消息。
4.5 邀请码管理页
邀请码管理页首版采用一个创建/更新表单和一个结果面板：
- inviteCode：提交前可在前端 trim，最终标准化以服务端为准。
- metadata：必须是 JSON 对象；空值按
{}提交。 - 提交成功后展示后端返回的 userId、inviteCode、createdAt、updatedAt 和 metadata。
- 失败时展示后端错误消息。
5. 数据与权限边界
- 管理端所有请求必须经过
/admin/api/*。 - 管理端持有的管理员 token 只用于后台接口，不复用玩家登录 token。
- 普通玩家 token 访问管理接口应被后端拒绝。
- 管理端不持久化密码。
- token 首版可保存在 localStorage；退出登录时立即清除。
- SpacetimeDB 表、reducer、procedure、迁移和权限判断均不由管理端直接处理。
6. 验收标准
apps/admin-web可以独立启动和构建。- 登录页可完成管理员登录，错误和未启用状态展示清楚。
- 登录后刷新页面可通过
GET /admin/api/me恢复会话。 - 总览页可展示
GET /admin/api/overview的服务与数据库数据。 - API 调试页可通过后端调试接口访问
/healthz。 - 兑换码管理页可创建/更新、停用兑换码，并展示返回记录。
- 邀请码管理页可创建/更新注册邀请码，并展示返回记录。
GET /admin保持 404，不恢复旧内嵌页面。npm run check:encoding通过。
7. 首版任务拆解
首版编码按以下模块收口，避免独立后台工程继续扩散成未定义功能：
- 工程骨架：创建
apps/admin-web，补齐 Vite、TypeScript、React 入口和独立构建脚本。 - API client：只封装
/admin/api/*，统一处理 Bearer token、统一 envelope 和后端错误消息。 - 登录与会话：实现登录、启动恢复、
401清理、退出登录四个状态流。 - 页面 Shell：实现桌面侧栏/顶部栏与移动端紧凑导航，不在未登录状态渲染后台导航。
- 总览页：展示
service、database、tableStats、fetchErrors，部分失败不阻断整页。 - API 调试页：实现 method、path、headers、body 输入和独立结果面板。
- 兑换码页：实现创建/更新、停用、三种 mode 切换和私有码用户列表输入。
- 邀请码页：实现注册邀请码创建/更新、metadata JSON 对象输入和最近记录展示。
- 验证：完成后台工程 typecheck/build、根工程编码检查，以及
/admin仍为 404 的后端验证。
8. 交互修正记录
8.1 兑换码记录页签保持
兑换码管理页的“记录”面板展示最近一次创建、更新或停用接口返回的兑换码记录。该记录在管理端会话内切换“总览”“API 调试”“兑换码”页签时必须保留，避免运营人员切页核对信息后丢失刚返回的结果。退出登录、登录新会话或刷新浏览器页面时可以清空该前端会话态；持久化查询能力后续由新的后端查询接口承接，不在首版用前端伪造历史列表。