Hai-world 是一个以 Boss 战斗为核心的实时点击小游戏项目，当前实现基于 Vue 3 + Vite + Go(Hertz) + Redis + MongoDB，并已扩展出房间分线、装备与强化、天赋战斗态、任务系统、消息墙、商店外观、后台管理和 OSS 图片上传链路。
- 前端位于
frontend/，不引入路由库，通过window.location.pathname切页。 - 后端位于
backend/，模块路径为long。 - 实时链路以前端
WebSocket /api/ws为主，承载 protobuf 二进制消息；链路异常时自动回退到SSE /api/events。 - Redis 负责热数据；MongoDB 已固定启用，用于冷数据、任务、日志、归档等持久化内容。
- 运行时配置通过 Consul KV 拉取 YAML；配置变更后进程会主动退出，由外部拉起新进程。
- 前端构建产物先输出到
backend/public/，再通过go:embed编译进后端二进制。
下面这份目录树基于当前仓库结构整理，保留主要工作目录，省略了 node_modules、.git、构建缓存和大体积产物细节。
. # 仓库根目录
├── .github/ # GitHub 平台配置
│ └── workflows/ # GitHub Actions 工作流目录
│ └── build.yml # 构建与发布流程
├── AGENTS.md # 协作规则
├── CLAUDE.md # 协作规则镜像文件
├── Dockerfile # 容器镜像构建入口
├── Makefile # 常用开发命令入口
├── README.md # 项目主入口文档
├── backend/ # Go 后端主目录
│ ├── cmd/ # 后端可执行程序入口
│ │ ├── backfillbosskills/ # Boss 击杀回填工具
│ │ ├── checkbosskills/ # Boss 击杀核对工具
│ │ ├── internal/ # 命令行工具共享内部代码
│ │ ├── local_click_latency/# 本地点击时延测试工具
│ │ ├── migratecolddata/ # 冷数据迁移工具
│ │ ├── migrateroommodel/ # 房间模型迁移工具
│ │ ├── migratetaskmodel/ # 任务模型迁移工具
│ │ ├── printcfg/ # 配置打印工具
│ │ ├── report/ # 报表工具
│ │ └── server/ # 正式服务启动入口
│ ├── config.example.yaml # 配置示例
│ ├── config.test.yaml # 测试配置
│ ├── config.yaml # 本地默认配置
│ ├── embed_public.go # 嵌入前端静态资源
│ ├── go.mod # Go 模块声明
│ ├── go.sum # Go 依赖锁定
│ ├── internal/ # 后端内部业务代码
│ │ ├── admin/ # 后台鉴权与管理能力
│ │ ├── archive/ # 冷数据归档能力
│ │ ├── config/ # 配置加载与校验
│ │ ├── core/ # 核心玩法与状态逻辑
│ │ ├── events/ # 实时事件广播
│ │ ├── httpapi/ # HTTP 与 WebSocket 接口
│ │ ├── mongostore/ # MongoDB 存储实现
│ │ ├── nickname/ # 昵称规则处理
│ │ ├── oss/ # OSS 上传与签名
│ │ ├── playerauth/ # 玩家登录鉴权
│ │ ├── ratelimit/ # 点击限流
│ │ ├── realtimepb/ # protobuf 生成代码
│ │ ├── report/ # 报表查询逻辑
│ │ └── xlog/ # 日志封装
│ ├── public/ # 前端构建产物目录
│ │ ├── effects/ # 特效静态资源
│ │ ├── favicon.svg # 站点图标
│ │ ├── icons.svg # SVG 图标集
│ │ ├── images/ # 页面图片资源
│ │ └── index.html # 前端入口 HTML
│ └── reports/ # 后端侧报表产物
├── docs/ # 一次性文档总目录
│ ├── README.md # docs 索引
│ ├── announcements/ # 版本公告
│ ├── architecture/ # 架构方案
│ ├── archive/ # 历史归档
│ ├── demos/ # 静态 demo
│ ├── designs/ # 设计与策划案
│ ├── developer-reference/ # 开发参考
│ ├── effects/ # 特效说明
│ ├── implementation/ # 实施记录
│ ├── reports/ # 阶段总结
│ ├── specs/ # 当前规范
│ └── superpowers/ # 历史 spec/plan 产物
├── frontend/ # Vue 前端主目录
│ ├── README.md # 前端局部说明
│ ├── bun.lock # Bun 依赖锁定
│ ├── index.html # 前端入口 HTML
│ ├── package.json # 前端依赖声明
│ ├── public/ # 原始静态资源
│ │ ├── effects/ # 特效资源
│ │ ├── favicon.svg # 前端图标
│ │ ├── icons.svg # 前端图标集
│ │ └── images/ # 前端图片资源
│ ├── src/ # 前端源码
│ │ ├── App.vue # 根组件
│ │ ├── assets/ # 源码内静态资源
│ │ ├── components/ # 可复用组件
│ │ ├── main.js # 前端启动入口
│ │ ├── pages/ # 页面级组件
│ │ ├── proto/ # 前端 protobuf 生成代码
│ │ ├── style.css # 全局样式
│ │ ├── utils/ # 工具逻辑
│ │ └── viteProxy.test.js # Vite 代理相关测试
│ └── vite.config.js # Vite 配置
├── lefthook.yml # Git hook 配置
├── package.json # 根目录 Node 脚本声明
├── pixel-assets/ # 像素素材工程目录
│ ├── README.md # 像素素材说明
│ ├── oss-manifest.json # OSS 资源清单
│ ├── oss-url-map.json # OSS URL 映射
│ ├── output/ # 像素输出产物
│ ├── scripts/ # 像素处理脚本
│ ├── specs/ # 像素规格定义
│ └── thicken-report.json # 像素加粗报告
├── scripts/ # 仓库辅助脚本
│ ├── boss_defeated_count.py # Boss 击杀统计脚本
│ ├── generate_equip_prompts.py # 装备提示词生成脚本
│ └── move_players_room.sh # 玩家切房脚本
├── wclick.conf # Web 服务相关配置
└── 大海世界.pptx # 展示用课件
AGENTS.md/CLAUDE.md- 长期协作规则，两份文件正文保持一致。
README.md- 当前有效的项目入口文档。
Makefile- 本地开发、测试、构建、hook 安装入口。
Dockerfile- 发布镜像入口，当前基于
cgr.dev/chainguard/static:latest。
- 发布镜像入口，当前基于
.github/workflows/build.yml- 当前 GitHub Actions 构建与部署流程。
docs/- 一次性方案、实施记录、开发参考、阶段总结、归档。
scripts/- 本地运维与数据辅助脚本。
pixel-assets/- 像素资源与视觉素材。
cmd/server/main.go- 服务启动入口。
cmd/printcfg/main.go- 配置打印工具。
cmd/backfillbosskills/main.go- Boss 击杀统计回填工具。
cmd/checkbosskills/main.go- Boss 击杀统计检查工具。
cmd/local_click_latency/main.go- 本地点击时延测试工具。
internal/httpapi/- HTTP 路由、WebSocket、静态资源与接口入口。
internal/events/- SSE 订阅中心与事件广播。
internal/core/- 主要玩法、状态与存储逻辑。
internal/config/- Consul 配置加载。
internal/mongostore/- MongoDB 冷数据与日志存储。
internal/oss/- OSS 上传与签名能力。
public/- 前端构建产物目录，由 Vite 输出并嵌入二进制。
src/main.js- 前端入口。
src/App.vue- 根组件。
src/pages/- 主要页面：战斗、资料页、任务、消息、商店、后台、天赋等。
src/components/admin/- 后台管理组件。
src/utils/- 实时传输、状态合并、格式化等工具。
src/proto/- 前端实时协议生成代码。
- Go
1.26.2 - Bun
1.3.13或兼容版本 - 可访问的 Redis、MongoDB、Consul
运行时配置由 Consul 提供，常见本地环境变量：
export CONSUL_ADDR=http://127.0.0.1:8500
export CONSUL_CONFIG_KEY=vote-wall/dev配置字段参考：
backend/config.example.yamlbackend/cmd/printcfg/main.go
make deps
make dev
make backend-run
make frontend-dev
make build
make test
make check
bun --cwd=frontend run test
make hooks-install补充命令：
make backend-backfill-boss-kills
make backend-check-boss-kills
go -C backend run ./cmd/printcfg- Go 命令必须在
backend/目录执行，或使用go -C backend ...。 - 前端命令默认在仓库根目录通过
bun --cwd=frontend ...执行。 make dev会同时启动 Go 后端和 Vite 前端。make build只构建前端产物到backend/public/。make test只运行后端测试。make check是本地手动全量校验入口，包含：- 后端测试
go vet- 前端测试
- 前端构建
仓库使用 lefthook 管理本地 pre-commit。
安装：
make hooks-install当前 pre-commit 会执行：
bun --cwd=frontend installgo -C backend mod tidygo -C backend fix ./...go -C backend test ./...go -C backend vet ./...bun --cwd=frontend run test
Vite 当前输出目录是 frontend/vite.config.js 中的 ../backend/public，后端通过 backend/embed_public.go 将其嵌入编译产物，因此发布镜像只需要后端二进制即可承载静态资源。
当前发布命令：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go -C backend build -trimpath -buildvcs=false -ldflags "-w -s -buildid=" -o long ./cmd/server当前 workflow 位于 .github/workflows/build.yml，在 main 分支 push 后执行：
- 安装前端依赖
- 运行后端测试与
vet - 构建前端产物
- 构建 Linux
amd64后端二进制 - 通过 SSH 清理服务器上的旧容器和旧镜像
- 同步
Dockerfile、docker-compose.yml、后端二进制和前端静态产物到服务器 - 通过 SSH 到
x1sv在服务器端执行docker compose up -d --build
- 发布镜像当前在服务器端基于仓库内
docker-compose.yml触发构建。 - 服务器端部署目录为
/home/docker-images/long/deploy-artifacts。 - workflow 当前在服务器端执行：
cd /home/docker-images/long/deploy-artifacts
docker network inspect docker-compose_app-net >/dev/null 2>&1 || \
docker network create docker-compose_app-net
CONSUL_ADDR=... CONSUL_CONFIG_KEY=... docker compose up -d --build- 后端测试使用
miniredis，不依赖真实 Redis。 - 前端测试主要使用
vitest做源码模式校验和工具逻辑校验，不依赖完整浏览器渲染环境。
当前有效的一次性设计、方案与实施记录统一放在 docs/，总索引见 docs/README.md。
推荐入口：
- Mongo / 任务系统主线：
- 实时链路与降载优化：
- 房间分线与战斗表现：