Genarrative/docs/【项目基线】当前产品与工程约束-2026-05-15.md

当前产品与工程约束

更新时间：2026-05-15

项目定位

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，但用户可见文案按上面的新口径展示。

账户与登录

1. 主站登录弹窗必须稳定展示 短信登录 与 密码登录 两个核心入口；GET /api/auth/login-options 只能补充微信等环境相关入口，不能决定是否隐藏短信或密码登录。
2. login-options 为空、失败、只返回 phone 或只返回 password 时，前端仍要同时展示验证码登录页签和密码登录页签；短信能力真实可用性由发送验证码接口返回结果表达。
3. 登录弹窗继续复用现有独立 modal 和页签结构，不在页面中新增功能说明类文案，也不把邀请码输入放回登录面板。
4. 微信小程序 web-view 外壳默认不预登录，首次进入直接打开 H5，并保持与 Web 端一致的未登录状态；只有 H5 触发 openLoginModal / requireAuth 等受保护入口时，才跳转小程序原生授权态。
5. 小程序内需要登录时不展示 H5 登录弹窗，也不走手输手机号 / 短信验证码流程；统一通过原生 button open-type="getPhoneNumber" 获取微信手机号授权，再调用 /api/auth/wechat/miniprogram-login 与 /api/auth/wechat/bind-phone 换取系统登录态。

账户与充值

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

唯一后端路线

当前后端唯一有效路线：

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 与交互约束

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

文案与编码

1. 代码需要有必要的中文注释，注释解释业务意图或复杂边界，不写空泛重复注释。
2. 不要擅自把中文文案、剧情、注释或文档改成英文。
3. 看到中文乱码时，先确认真实编码，不要沿用乱码文本，也不要用英文替换。
4. PowerShell 5.1 读取或写入文本时必须显式使用 UTF-8。
5. 非必要不要整文件重写，尤其是包含中文的文件；优先局部补丁。
6. 修改中文文件后优先执行 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 中仍有效的编码级口径已融合；没有融合的内容视为历史参考，不再作为实现依据。