# koudai-refactor

**Repository Path**: TangChengZao/koudai-refactor

## Basic Information

- **Project Name**: koudai-refactor
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-09-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Koudai Refactor

这是《口袋》长期运营新版的重构仓库。目标不是逐行翻译旧 PHP，而是保留玩家可感知玩法，同时重新设计后端模型、数据结构、运营后台和玩家助手能力。

## 技术方向

- 主后端：Java 21 + Spring Boot 3
- 后端持久化：MyBatis，复杂业务 SQL 显式建模
- 登录会话：Sa-Token + Redis
- 前端：Vue 3 + TypeScript + Vite
- 数据库：MySQL 8
- 缓存：Redis
- 数据工具：Python，用于旧数据清洗、爬取、对照验证
- 玩家助手：Tauri/Electron 方向，优先通过服务端授权 API 执行挂机策略

## 仓库结构

```text
apps/
  api/          Java Spring Boot 游戏后端
  web/          Vue 3 游戏端 / 管理端前端
  assistant/    Tauri 桌面助手的 Vue 工作台与开发入口
docs/
  architecture/ 架构设计
  gameplay/     玩法规则拆解
  migration/    旧系统迁移记录
tools/
  data/         Python 数据清洗与采集工具
```

## 当前状态

项目已从“建立重构地基”进入“核心玩法闭环后的长尾收口”阶段：

- 登录、欢迎页、个人中心、两页中心城镇和主要建筑入口已接通。
- 宠物成长、牧场、宠物神殿、背包、仓库、商店、任务、普通战斗、经典副本、组队和主要特殊地图已形成可验证链路。
- 神秘商店、魔法屋、公告牌、扫雷、皇宫、情人岛、家族战场和神圣战场均已完成当前接口闭环；历史周期默认关闭。
- 活动容器、窗口、排行快照、消费归属、结构化奖励和领奖幂等已具备，真实历史消费仍等待旧库数据。
- API 最小披露以及历史活动未映射消费处理、GM 配置审计已收口；当前重点转为活动来源奖励/入口/广播、战斗与宠物明确长尾和玩家页面验收，不重新扫描已关闭审计的模块。

准确状态以迁移审计台账为准；近期执行顺序和缺失数据边界分别见下一步还原队列与剩余还原路线图。

## 重构计划

- [重构总计划](docs/plan/refactor-master-plan.md)
- [迁移审计台账](docs/plan/audit-ledger.md)
- [模块迁移总账](docs/plan/module-progress.md)
- [下一步还原队列](docs/plan/next-rebuild-backlog.md)
- [剩余还原路线图](docs/plan/remaining-restoration-roadmap.md)
- [玩法拆解目录](docs/gameplay/README.md)
- [账号入口切片](docs/plan/vertical-slice-account-entry.md)
- [第一垂直切片：宠物成长](docs/plan/vertical-slice-pet-growth.md)
- [模块边界](docs/architecture/module-boundaries.md)
- [数据库重设计原则](docs/architecture/database-principles.md)
- [旧前端布局梳理](docs/architecture/legacy-frontend-layout.md)
- [新前端层级设计](docs/architecture/frontend-layering.md)
- [账号入口玩法说明](docs/gameplay/account-entry.md)
- [宠物升级与五行成长](docs/gameplay/pet-growth.md)

## Java 构建加速

API 镜像使用 Docker BuildKit 缓存 Gradle 依赖，并通过 Spring Boot layertools 拆分运行镜像层。冷构建仍需要下载和编译依赖；依赖不变时，重复 `docker compose build api` 可复用缓存，源码小改后的本地构建通常只需要重新编译应用层。

当前优先保留 Dockerfile 方案，方便 `docker compose` 本地调试。Jib 后续适合接入 CI 或镜像仓库发布，用于直接构建分层镜像并减少 Dockerfile 维护成本；在本地开发链路稳定前先不引入额外插件。
## 本地开发

当前本机不要求安装 Java。后端可以通过 Docker 构建运行：

```powershell
Copy-Item .env.example .env
# 修改 .env 中的三个密码占位值；本地 HTTP 调试保持 APP_SESSION_COOKIE_SECURE=false。
docker compose up -d mysql redis
docker compose up --build api
```

MySQL 和 Redis 仅发布到 `127.0.0.1`。Compose 不再提供数据库或 Redis 弱默认密码，缺少 `.env` 时会拒绝启动。已有数据卷从旧配置升级时，应先使用旧凭据执行 `ALTER USER` 修改 `root` 和应用用户密码，再按新 `.env` 重建容器；不要删除数据卷。

生产环境必须设置 `APP_SESSION_COOKIE_SECURE=true` 并只通过 HTTPS 暴露游戏入口。本地直接运行 Spring Boot 时还需显式提供 `SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD` 和 `SPRING_DATA_REDIS_PASSWORD`。

新服生产环境必须使用全新 MySQL 数据卷执行 Flyway，只保留玩法静态配置，不导入旧玩家、`yblog` 消费、领奖资格、战场参战记录或开发测试账号。不要把本地开发数据卷复制到生产；完整空库验收见 [初始化验证记录](docs/migration/initial-validation.md)。

前端需要 Node.js：

```powershell
cd apps/web
npm install
npm run dev
```

前端开发地址固定为 `http://127.0.0.1:5180`，避免和其他 Vite 项目的默认 `5173` 端口冲突；访问 `http://localhost:5180` 会自动跳转到 IPv4 地址，避免本机连续 XHR 请求偶发 300ms 等待。

Windows 中文工作区下，Gradle 测试输出会自动写入系统临时目录的 `koudai-refactor-build/api`，规避 Test Worker 无法加载中文路径测试类的问题；Docker/Linux 构建目录保持默认值。