144 lines
7.5 KiB
Markdown
144 lines
7.5 KiB
Markdown
# Genarrative 项目共享概览
|
||
|
||
> 用途：给团队成员本地 Hermes 快速建立项目背景。内容应保持高层、稳定、可验证；细节以代码、`README.md`、`AGENTS.md` 和 `docs/` 最新文档为准。
|
||
|
||
## 一句话定位
|
||
|
||
Genarrative / AI Native Visual RPG 是一个以 **AI 叙事 + 本地规则 + 像素演出** 为核心的视觉 RPG 与 AI 原生游戏创作平台原型。
|
||
|
||
项目当前不只是单一 RPG demo，而是在同一平台内同时承载：
|
||
|
||
- RPG / 自定义世界创作与运行时
|
||
- 拼图玩法创作与运行时
|
||
- 大鱼吃小鱼玩法链路
|
||
- 抓大鹅 Match3D 玩法链路
|
||
- 用户账号、存档、钱包、任务、埋点、后台管理与生产部署链路
|
||
|
||
## 已具备的主要能力
|
||
|
||
来自根目录 `README.md` 的当前主能力：
|
||
|
||
- 世界与角色选择
|
||
- AI 剧情推进与流式对话
|
||
- 战斗演出、NPC 战斗、切磋
|
||
- NPC 交易、送礼、求助、招募
|
||
- 宝藏交互
|
||
- 同伴跟随与战斗
|
||
- 游戏主流程内嵌的角色资产工坊、自定义世界实体编辑与角色形象编辑
|
||
- 自动存档与继续游戏
|
||
|
||
## 当前前端与平台入口
|
||
|
||
- 主站默认地址：`http://127.0.0.1:3000`
|
||
- 后台可从 `http://127.0.0.1:3000/admin/` 进入，也可直连 `http://127.0.0.1:3102`
|
||
- 主站、后台和 Rust 后端联调默认走 `npm run dev`
|
||
- 只启动前端页面可用 `npm run dev:web`，默认代理到本地 Rust `api-server`
|
||
- 后台管理独立前端工程为 `apps/admin-web`，管理端只做表现，数据和写操作走 `server-rs` 的 `/admin/api/*`
|
||
|
||
## 当前后端唯一落地口径
|
||
|
||
后端主线已经切到：
|
||
|
||
```text
|
||
server-rs + Axum + SpacetimeDB
|
||
```
|
||
|
||
当前唯一有效后端方向：
|
||
|
||
- HTTP 门面：Rust `api-server` / Axum
|
||
- 实时状态与业务真相：`server-rs/crates/spacetime-module` / SpacetimeDB
|
||
- 共享领域与契约：`server-rs` 多 crate 分层维护
|
||
- 前端职责：表现、输入采集、临时 UI 状态、服务端结果渲染
|
||
|
||
明确不再作为正式兼容目标：
|
||
|
||
- `server-node` / Express / PostgreSQL 正式后端路线
|
||
- Go 服务端试验路线
|
||
- 浏览器侧承担正式运行时逻辑、正式生成编排或正式数据真相的路线
|
||
|
||
## server-rs DDD 分层边界
|
||
|
||
DDD 分层边界以 `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`、`SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md` 和 `AGENTS.md` 为准：
|
||
|
||
- `module-*`：领域模型、命令、应用编排结果、领域事件、领域错误
|
||
- `spacetime-module`：SpacetimeDB 表、reducer、procedure、事务 adapter、mapper
|
||
- `spacetime-client`：后端访问 SpacetimeDB 的 typed facade
|
||
- `api-server`：HTTP / SSE / BFF adapter 与外部平台服务编排
|
||
- `platform-*`：LLM、OSS、SMS、微信等外部副作用
|
||
- `shared-contracts`：前后端 DTO 与公开协议
|
||
- `shared-kernel`：跨纯领域 crate 复用的基础字符串、ID、时间和归一化能力
|
||
- `tests-support`：`server-rs` workspace 共享测试支撑
|
||
|
||
## 当前 Rust workspace 主要 crate
|
||
|
||
以 `server-rs/Cargo.toml` 为准，当前主要成员包括：
|
||
|
||
- 业务领域：`module-ai`、`module-assets`、`module-auth`、`module-big-fish`、`module-combat`、`module-inventory`、`module-custom-world`、`module-match3d`、`module-npc`、`module-puzzle`、`module-progression`、`module-quest`、`module-runtime`、`module-runtime-story`、`module-runtime-item`、`module-story`
|
||
- 平台副作用：`platform-oss`、`platform-auth`、`platform-llm`
|
||
- 共享层：`shared-contracts`、`shared-kernel`、`shared-logging`
|
||
- SpacetimeDB 接入：`spacetime-client`、`spacetime-module`
|
||
- HTTP 服务与测试：`api-server`、`tests-support`
|
||
|
||
注意：`server-rs` 的默认 `cargo build` 只构建 `crates/api-server`，本地 SpacetimeDB 模块发布继续走 `spacetime publish --module-path ... --build-options="--debug"`。
|
||
|
||
Cargo 依赖口径：第三方依赖版本和 workspace 内部 crate path 统一维护在 `server-rs/Cargo.toml` 的 `[workspace.dependencies]`，成员 crate 默认继承 workspace 依赖，只保留自身 `features`、`optional` 或 target-specific 差异。
|
||
|
||
Rust 加密摘要依赖口径：新代码不再引入 `sha1`；OSS V4 签名、阿里云 OpenAPI V3 签名和 refresh session token 摘要统一使用 `sha2::Sha256`。
|
||
|
||
## SpacetimeDB 表域总览
|
||
|
||
以 `docs/technical/SPACETIMEDB_TABLE_CATALOG.md` 为持续维护入口。当前表域包括：
|
||
|
||
- 运维迁移：`database_migration_operator`、`database_migration_import_chunk`
|
||
- 认证：`auth_store_snapshot`、`user_account`、`auth_identity`、`refresh_session`
|
||
- 运行时档案：`runtime_setting`、`runtime_snapshot`、`user_browse_history`、`profile_dashboard_state`、`profile_wallet_ledger`、`analytics_date_dimension`、`tracking_event`、`tracking_daily_stat`、`profile_task_config`、`profile_task_progress`、`profile_task_reward_claim`
|
||
- RPG 运行时：`story_session`、`story_event`、`npc_state`、`inventory_slot`、`battle_state`、`treasure_record`、`quest_record`、`quest_log`、`player_progression`、`chapter_progression`
|
||
- 世界创作：`custom_world_profile`、`custom_world_session`、`custom_world_agent_session`、`custom_world_agent_message`、`custom_world_agent_operation`、`custom_world_draft_card`、`custom_world_gallery_entry`
|
||
- 拼图：`puzzle_agent_session`、`puzzle_agent_message`、`puzzle_work_profile`、`puzzle_event`、`puzzle_runtime_run`、`puzzle_leaderboard_entry`
|
||
- 抓大鹅 Match3D：`match3d_agent_session`、`match3d_agent_message`、`match3d_work_profile`、`match3d_runtime_run`
|
||
- 大鱼吃小鱼：`big_fish_creation_session`、`big_fish_agent_message`、`big_fish_asset_slot`、`big_fish_event`、`big_fish_runtime_run`
|
||
- 资产：`asset_object`、`asset_entity_binding`、`asset_event`
|
||
- AI 任务：`ai_task`、`ai_task_stage`、`ai_text_chunk`、`ai_result_reference`、`ai_task_event`
|
||
|
||
## 产品命名与运营口径
|
||
|
||
以 `docs/technical/PRODUCT_NAMING_BAIMENG_RENAME_2026-05-01.md` 为准：
|
||
|
||
- 产品展示名：百梦
|
||
- 消费单位：光点
|
||
- 公开账号标识：百梦号
|
||
- 创作侧称谓：百梦主
|
||
|
||
个人任务与埋点系统首版边界：
|
||
|
||
- 埋点原始事实写入 `tracking_event`
|
||
- 聚合投影写入 `tracking_daily_stat`
|
||
- 任务配置写入 `profile_task_config`
|
||
- 任务进度写入 `profile_task_progress`
|
||
- 领奖记录写入 `profile_task_reward_claim`
|
||
- 钱包流水写入 `profile_wallet_ledger`
|
||
- “星光”奖励复用现有“光点”钱包，不新增第二种货币
|
||
- 个人任务 scope 首版仅支持 `user`
|
||
|
||
## 关键文档入口
|
||
|
||
- 根项目说明：`README.md`
|
||
- 项目总约束：`AGENTS.md`
|
||
- 文档总入口：`docs/README.md`
|
||
- 经验沉淀：`docs/experience/README.md`
|
||
- 审计与复盘：`docs/audits/README.md`
|
||
- 系统设计：`docs/design/README.md`
|
||
- 技术方案：`docs/technical/README.md`
|
||
- 规划与优先级：`docs/planning/README.md`
|
||
- 参考目录：`docs/reference/README.md`
|
||
- 埋点查询：`docs/tracking/README.md`
|
||
- 运营查询：`docs/operations/README.md`
|
||
- 后端当前基线：`docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
|
||
- 后端 DDD 总纲：`docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
|
||
- 后端并行任务清单：`docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
|
||
- 契约与路由矩阵：`docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
|
||
- SpacetimeDB 表结构变更约束：`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
|
||
- SpacetimeDB 表目录：`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
|
||
- Rust workspace 依赖集中配置：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`
|
||
- 生产部署计划：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`
|