当前产品与工程约束

更新时间：2026-06-05

项目定位

Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台。当前平台不是单一 RPG demo，而是把 AI 创作、作品草稿、公开分发、运行态、用户账号、钱包任务、后台管理和小程序外壳收在同一套工程中。

当前主要内容形态：

RPG / 自定义世界创作与运行时。
拼图玩法创作、草稿、发布、运行态和排行榜。
抓大鹅 Match3D 创作、2D 多视角素材生成、发布和运行态。
大鱼吃小鱼、方洞挑战、视觉小说、汪汪声浪和儿童向寓教于乐玩法。
用户账号、短信/密码/微信登录、个人资料、任务、钱包、邀请码、充值、反馈、法律信息和后台管理。

产品命名

产品展示名：陶泥儿。
消费单位：泥点。
公开账号标识：陶泥号。
创作侧称谓：陶泥儿主。

不要把旧“百梦”等历史命名重新写入新 UI 或新文档。

当前入口

主站默认地址：http://127.0.0.1:3000。
后台入口：http://127.0.0.1:3000/admin/ 或 http://127.0.0.1:3102。
后台前端工程：apps/admin-web。
小程序 WebView 外壳：miniprogram/。
法律文本仍保存在 media/files/user_agreement.md、media/files/privacy_policy.md、media/files/disclaimer.md，由前端法律弹窗读取。

移动端平台一级 Tab 当前为：

推荐 / 发现 / 创作 / 草稿 / 我的

内部状态值可继续复用历史 home/category/create/saves/profile，但用户可见文案按上面的新口径展示。

账户与登录

主站登录弹窗必须稳定展示 短信登录 与 密码登录 两个核心入口；GET /api/auth/login-options 只能补充微信等环境相关入口，不能决定是否隐藏短信或密码登录。
login-options 为空、失败、只返回 phone 或只返回 password 时，前端仍要同时展示验证码登录页签和密码登录页签；短信能力真实可用性由发送验证码接口返回结果表达。
登录弹窗继续复用现有独立 modal 和页签结构，不在页面中新增功能说明类文案，也不把邀请码输入放回登录面板。
微信小程序 web-view 外壳默认不预登录，首次进入直接打开 H5，并保持与 Web 端一致的未登录状态；只有 H5 触发 openLoginModal / requireAuth 等受保护入口时，才跳转小程序原生授权态。
小程序内需要登录时不展示 H5 登录弹窗，也不走手输手机号 / 短信验证码流程；统一先通过 wx.login 获取微信登录 code 并调用 /api/auth/wechat/miniprogram-login 完成快捷登录。若该接口返回 created=true，或返回用户昵称仍是手机号、公开陶泥号、“微信旅人”等默认展示值，才展示原生 input type="nickname" 补充微信昵称并再次调用 /api/auth/wechat/miniprogram-login 写入 displayName。若后端返回 pending_bind_phone，再通过原生 button open-type="getPhoneNumber" 获取微信手机号授权并调用 /api/auth/wechat/bind-phone 换取系统登录态。
小程序外壳注入到 H5 URL 的 clientType、clientRuntime、miniProgramEnv 是宿主上下文，H5 内部 pushState / 阶段导航必须跨页面保留，避免登录和充值误判为普通浏览器；首点时微信 JS bridge 可能尚未就绪，前端还需用 MicroMessenger + miniProgram User-Agent 作为小程序识别兜底。
小程序 web-view 页必须启用好友分享与朋友圈分享，分享目标固定回到 pages/web-view/index，不把 H5 当前 URL 作为不受控启动参数传回小程序页。
小程序 web-view 外壳运行时通过 wx.getAccountInfoSync().miniProgram.envVersion 自动识别版本：线上版 release 使用 www.genarrative.world，体验版 trial 与开发版 develop 使用 dev.genarrative.world；传给后端的 x-mini-program-env 分别为 release、trial、dev。
账号信息面板只展示 账号信息 标题；绑定手机号和绑定微信以紧凑模块展示当前绑定状态，已绑定手机号展示完整手机号，已绑定微信优先展示微信平台实际返回并由后端保存的 wechatDisplayName。小程序 jscode2session 不能直接返回微信昵称或个人微信号，只能稳定拿到当前小程序维度的 openid，并在满足微信开放平台条件时拿到 unionid；小程序昵称来自快捷登录后按需展示的原生 input type="nickname" 提交的 displayName。后端下发 wechatAccount 作为绑定账号标识，前端在没有真实昵称时展示微信账号尾号，不展示裸“已绑定”。换绑入口放在对应模块右上角，退出登录和退出全部设备固定放在面板内容最底部。

账户与充值

“我的”页账户充值弹窗包含 泥点充值 与 会员卡充值 两个页签，入口必须打开独立弹窗，不在当前面板下方展开。
泥点默认档位为 60 / 180 / 300 / 680 / 1280 / 3280，会员默认档位为月卡、季卡、年卡；实际展示、下单校验和支付确认都以后端返回的充值商品配置为准。
首充双倍按泥点商品档位独立计算。用户买过 points_60 后，只影响 points_60 的首充展示和结算，其它未购买档位仍保留各自首充权益。
前端不得用 hasPointsRecharged 统一隐藏所有泥点档位首充权益；该字段只表示账号是否发生过任一泥点充值。
充值支付渠道只允许由设备平台隔离层解析为 wechat_mp、wechat_h5 或 wechat_native；生产真实支付不得默认落到 mock，缺失或未知 paymentChannel 必须拒绝。
小程序 WebView 充值使用 wechat_mp 渠道时，H5 只跳转 native 支付页并在返回后请求服务端查单确认；手机微信内网页使用 wechat_h5 跳转微信 H5 支付；桌面微信内网页使用 wechat_native 二维码。只有微信通知或查单确认 SUCCESS 后才刷新余额或会员状态。
后端必须按 access JWT 中的最小设备快照拦截真实微信充值路径，不能只依赖前端隐藏入口或请求体传入的 paymentChannel。
后台“充值商品”页维护泥点和会员商品配置，保存后影响新的充值中心快照、下单和支付确认；历史订单保留下单时快照。

唯一后端路线

当前后端唯一有效路线：

server-rs + Axum + SpacetimeDB

职责边界：

api-server：HTTP / SSE / BFF 门面和外部副作用编排。
spacetime-module：SpacetimeDB 表、reducer、procedure、事务 adapter 和 row mapper。
spacetime-client：后端访问 SpacetimeDB 的 typed facade。
module-*：纯领域模型、命令、应用规则、领域事件和领域错误。
platform-*：OSS、LLM、认证、语音等外部平台能力。
shared-contracts / packages/shared：前后端 DTO 和公开契约。
前端：表现、交互、临时 UI 状态和后端结果渲染。

明确废弃：

旧 server-node、Express、PostgreSQL 正式后端路线。
Go 服务端试验路线。
maincloud / Maincloud / MAINCLOUD 脚本、环境变量、测试和文档口径。
除 CI/CD 脚本内部受控用法外，人工命令中的 spacetime --root-dir。
前端绕过后端投影或后端 API 自行承接正式业务真相。

UI 与交互约束

移动端优先，同时保证桌面端可用。
UI 面板不要默认写功能说明、规则解释、操作教程类文案。
点击按钮弹出独立面板时，必须弹出 dialog / drawer / modal，不要在当前面板下方展开内容。
优先复用现有系统、页面、组件和弹层，不因一次需求新建平行系统。
游戏式页面要防止文字、按钮、HUD、底部 dock、输入法和画布互相遮挡。
平台根壳已处理移动端输入法聚焦：输入法弹出时保持画布稳定高度，用偏移聚焦输入框，业务组件不要重复注册全局键盘适配。
主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
图像输入通用 UI 统一走 src/components/common/CreativeImageInputPanel.tsx。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
发现页 分类 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、通用设置入口和法律信息；media/profile/ 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位。页面不再提供独立存档按钮入口，也不在底部保留旧的填邀请码次级入口；主题设置、账号与安全只作为通用设置弹窗下一级入口，不在“我的”页外层单独占行。填邀请码只由邀请链接 query 或其它明确引导打开独立弹窗，不作为“我的”页常驻按钮。
“我的”页每日任务卡必须展示后端 /api/profile/tasks 返回的当前任务摘要，包括奖励泥点数和进度；外层任务卡不展示“去完成”等左右侧行动按钮，领取 / 去完成 / 已完成状态只在任务中心弹窗内表达。任务领取成功后，卡片摘要必须跟随返回的任务中心数据同步刷新，不能继续硬编码 0 / 1 或只更新弹窗内任务列表。用户停留在“我的”页跨过北京时间 0 点时，前端必须非阻断刷新登录态以补齐 daily_login 埋点，再重拉任务中心，避免继续展示上一自然日已领取状态。
“我的”页泥点余额、累计游玩、已玩游戏三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 10px 到 14px 的普通 UI 字号区间，避免展示级字号挤压内容。
移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 src/index.css 的 --platform-* 主题变量和 apps/admin-web/src/styles/admin.css 的同系色值，不再引入粉红、蓝绿等独立主色方案。

文案与编码

代码需要有必要的中文注释，注释解释业务意图或复杂边界，不写空泛重复注释。
不要擅自把中文文案、剧情、注释或文档改成英文。
看到中文乱码时，先确认真实编码，不要沿用乱码文本，也不要用英文替换。
PowerShell 5.1 读取或写入文本时必须显式使用 UTF-8。
非必要不要整文件重写，尤其是包含中文的文件；优先局部补丁。
修改中文文件后优先执行 npm run check:encoding。

Agent 与协作规则

Issue tracker 是自托管 Gitea。可用 Gitea UI/API 或 tea CLI；不要用 GitHub gh 或 GitLab glab。
默认 triage labels：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。
根 CONTEXT.md 是当前领域语言入口；架构决策以本文档和 .hermes/shared-memory/decision-log.md 的最新稳定摘要为准。
.hermes/ 只保存可进入 Git 的团队共享记忆、计划和可公开 skill，不提交个人 Hermes 配置、会话、密钥、Token 或本地私密路径。
每次工程修改都应同步更新本目录当前文档；如果产生长期有效知识，再同步 .hermes/shared-memory/。

当前文档策略

本目录只保留少量当前文档。旧审计、阶段计划、修复流水账和历史 PRD 中仍有效的编码级口径已融合；没有融合的内容视为历史参考，不再作为实现依据。

13 KiB Raw Blame History Unescape Escape