# 码箱游戏后端 **Repository Path**: bitcarton/game ## Basic Information - **Project Name**: 码箱游戏后端 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-31 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # bridge-server · 守了个桥 后端 微信小游戏《守了个桥》的登录与存档服务。做三件事:换 openid 发 token、存/取一份 JSON 存档,以及把后台要用的**结构化快照**(神将属性、玩家资产)单独落库。不做支付、不做服务端权威账本,那些等有需要再加。 ## 技术栈 | 项 | 选型 | |---|---| | 框架 | Spring Boot 3.2.5 | | JDK | 17+ | | 数据库 | MySQL 8.0(`payload` 用 `MEDIUMTEXT`) | | 鉴权 | JWT(HS256,30 天) | | ORM | `mybatis-jet-spring-boot3-starter` 1.0.0(`BaseMapper` + `QueryWrapper`) | ## 快速开始 ### 1. 建库建表 ```bash mysql -uroot -p -e "CREATE DATABASE bridge DEFAULT CHARSET utf8mb4;" mysql -uroot -p bridge < src/main/resources/db/schema.sql ``` 持久化层不做自动建表(没有 `ddl-auto` 这类开关),表结构只由 `schema.sql` 决定。这是刻意的:自动建表在改字段时会静默丢数据。`schema.sql` 会顺带幂等初始化公共神将表 `t_hero` 的 18 行定义(初始攻击/暴击/射速、显示顺序、启用状态,`image_url` 留空待后台配置)。重复执行初始化只刷新名字与初始数值,**不会覆盖后台配好的图片、排序和启停**。 **存量库升级**:`CREATE TABLE IF NOT EXISTS` 不会给已建好的表加列或加外键,按自己库的状态选一条: ```bash # A. 旧库还没有 t_hero(没跑过上一版迁移):一次到位,已含 sort_no / enabled mysql --default-character-set=utf8mb4 -uroot -p bridge < src/main/resources/db/migration_hero_catalog.sql # B. t_hero 已有 18 行、但还没有 sort_no / enabled:只补这两列 mysql --default-character-set=utf8mb4 -uroot -p bridge < src/main/resources/db/migration_hero_display.sql # C. 库里出现了 tangtang / tiangang 这两个写错的 hero_id:改名修正 mysql --default-character-set=utf8mb4 -uroot -p bridge < src/main/resources/db/migration_fix_hero_ids.sql # D. t_hero_stat 还是 (uid, hero_id) 复合主键:改成单主键 id(换 mybatis-jet 必须做) mysql --default-character-set=utf8mb4 -uroot -p bridge < src/main/resources/db/migration_hero_stat_single_pk.sql # E. 商城「每日免费领取」上线:给 t_player_asset 补当天已领次数三列(存量行默认 0) mysql --default-character-set=utf8mb4 -uroot -p bridge < src/main/resources/db/migration_free_claim_20261115.sql ``` A 脚本建 `t_hero` 并灌入 18 行、自检孤儿 `hero_id`、去掉玩家表里冗余的 `hero_name`、给 `t_hero_stat.hero_id` 加外键 `fk_hero_stat_hero`;B 脚本只补显示配置列并回填顺序;C 脚本把手工灌错的 `tangtang` → `tang`、`tiangang` → `tianwang` 改回来(见下方 ID 对照表);D 脚本给 `t_hero_stat` 加 `id` 单主键、回填存量行、把 `(uid, hero_id)` 降级为唯一索引;E 脚本给 `t_player_asset` 加 `free_claim_day / free_claim_coin_count / free_claim_gem_count`,记录客户端上报的「商城每日免费领取」当天进度(金币、钻石各自独立计数,跨天由客户端归零)。**都不删任何玩家数据行**。旧的 `migration_add_hero_name.sql` 已被 A 取代,不必再跑。 ### 2. 配置 全部走环境变量,不写进配置文件: ```bash export WX_APPID=wx1234567890abcdef export WX_SECRET=你的appsecret # 绝对不能提交到 git export JWT_SECRET=$(openssl rand -base64 48) # 至少 32 字节,否则启动直接报错 export DB_URL="jdbc:mysql://127.0.0.1:3306/bridge?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true" export DB_USER=root export DB_PASSWORD=你的密码 ``` ### 3. 本地跑(没有 appid 也能跑) ```bash WX_MOCK=true JWT_SECRET=local-dev-secret-key-at-least-32-bytes java -jar target/bridge-server-1.0.0.jar ``` `WX_MOCK=true` 时,客户端传的 `code` 会被直接当成身份(加 `mock_` 前缀)。**生产环境绝不能开**,启动日志会打 WARN。 ### 4. 打包 ```bash mvn clean package -DskipTests mvn test # 13 个集成测试,走 H2 内存库,不依赖真实 MySQL ``` ## 接口 所有接口返回 JSON,业务错误统一 `{ "code": 400, "message": "..." }`。 ### `POST /api/auth/login` 免鉴权。 ```jsonc // 请求 { "code": "wx.login 拿到的 code" } // 响应 200 { "token": "eyJhbGciOi...", "uid": 1, "isNew": true } ``` `code` 5 分钟有效、只能用一次。同一个微信用户重复登录永远拿到同一个 `uid`。 错误码: | HTTP | 含义 | |---|---| | 400 | code 为空 | | 401 | code 已失效或被用过(微信返回 40029 / 40163) | | 502 | 微信接口不可用,或服务端没配 appid/secret | ### `GET /api/save` 需要 `Authorization: Bearer `。 ```jsonc // 新用户(云端还没有存档) { "payload": null, "revision": 0, "updatedAt": null } // 已有存档 { "payload": { "unlocked": 23, "coin": 8888 }, "revision": 3, "updatedAt": "2026-11-12T16:51:13" } ``` ### `PUT /api/save` 需要鉴权。**必须带 `revision`**,这是乐观锁: ```jsonc // 请求 { "payload": { "unlocked": 24, "coin": 9000 }, "revision": 3 } // 响应 200 { "payload": {...}, "revision": 4, "updatedAt": "2026-11-12T16:51:14" } ``` | 情况 | 返回 | |---|---| | 成功 | 200,`revision` 递增 1 | | 传的 `revision` 不是服务端当前值 | **409**,客户端应先 `GET` 拉最新 | | 首次上传却传了 `revision != 0` | 409 | | payload 超过 256KB | 400 | ### `POST /api/hero-stats` 需要鉴权。**批量上报神将当前四项属性**(等级 / 攻击力 / 暴击率 / 射速),一次 1~18 条,按 `(uid, hero_id)` upsert。`hero_id` 必须是公共表 `t_hero` 里已收录的神将,否则 400。 ```jsonc // 请求 { "heroes": [ { "heroId": "staff", "heroLevel": 1, "attack": 16, "crit": 2.00, "rate": 1.23 }, { "heroId": "fozu", "heroLevel": 10, "attack": 312, "crit": 26.00, "rate": 0.25 } ] } // 响应 200(heroName 由公共表带出,不是回显上报值) { "count": 2, "updatedAt": "2026-11-12T16:52:24", "heroes": [ /* 本次落库的数据 */ ] } ``` | 字段 | 类型 | 说明 | |---|---|---| | heroId | string | 神将 id,外键引用 `t_hero.hero_id`,最长 32 | | heroName | string | **只读出参**:响应里由公共表 `t_hero` 带出;为兼容旧客户端仍允许上报,但**不落库** | | heroLevel | int | 等级 1~10 | | attack | int | 当前等级攻击力(前端 `displayAtk`) | | crit | decimal | 当前等级暴击率百分数,`2.00` = 2.0% | | rate | decimal | 当前等级射速,每秒施放次数 | 数值由客户端按卡片显示的同一套公式算好,后端只校验范围并落库,**不重复实现数值公式**。中文名、初始值、说明图统一放在公共表 `t_hero`,玩家表只存 `hero_id` 引用(见 `GET /api/heroes`)。客户端在登录成功、采用云端存档、神将升级成功后静默上报;失败或离线一律降级,不影响游戏。 ### `GET /api/heroes` 需要鉴权,返回公共神将定义表 `t_hero` 里 **`enabled = 1`** 的全部条目,按 `sort_no` 升序、同值按 `heroId` 兜底排序,全服共享、只读。 **客户端上阵页的显示以本接口为准**:显示哪些神将、按什么顺序、叫什么名字、1 级初始值多少、说明图是哪张,全部读这里;后台改库即可生效,不用发版。接口失败或离线时客户端退回内置的 18 位神将,游戏照常能玩。 ```jsonc { "heroId": "staff", "heroName": "悟空", "initAtk": 16, "initCrit": 2.00, "initRate": 1.23, "imageUrl": "", "sortNo": 10 } ``` | 字段 | 含义 | |---|---| | initAtk / initCrit / initRate | 1 级初始值,与前端卡片 `displayAtk / displayCrit / displayRate(id, 1)` 同源 | | imageUrl | 神将说明图链接(图鉴 / 详情页解释用),由后台 UPDATE 配置,初始为空串 | | sortNo | 上阵页显示顺序,小的在前 | 表内容由 `schema.sql` / 迁移脚本维护,接口不提供写入。别和 `GET /api/hero-stats` 混:这里存的是**基准初始值**,那里存的是玩家**当前等级的实际值**。 #### hero_id 对照表(改库前先看这里) `hero_id` 是**客户端存档里的技术主键**,不是中文名的拼音翻译。它同时被三处绑定:前端 `Weapons.ts` 的 `WEAPON_IDS`、玩家存档 `loadout` / `owned` 的 key、`t_hero_stat.hero_id` 外键。**不能按字面意思改名**:改成客户端不认识的 id,那一行会被 `HeroCatalog` 当未知神将丢掉,客户端上报还会直接 400「未知神将 id」。 早期上过一版宗教人名的 id,后来中文名为了审核合规统一改成意象化的虚构名,但 id 保留没动(改 id 会清空老玩家存档),所以有几组看着「对不上」,实际是前端就这么定义的: | hero_id | 中文名 | 备注 | |---|---|---| | `staff` | 悟空 | | | `drink` | 寿将·仙桃 | | | `rake` | 八戒·天蓬砸 | | | `dragon` | 云从·行雨 | | | `axe` | 广寒·月轮 | | | `water` | 水将·碧涛 | | | `fire` | 火将·真火 | | | `tianwang` | 镇元·地仙 | 早期「天王」,现为地仙法印;**不是 `tiangang`** | | `nezha` | 哪吒·火尖枪 | | | `pagoda` | 镇岳·宝塔 | | | `guanyin` | 甘露·净瓶 | 早期「观音」,现为净瓶 | | `laojun` | 紫金·八卦炉 | 早期「老君」,现为八卦炉 | | `yudi` | 雷震 | 早期「玉帝」,现为落雷(`kind: 'bolt'`),**不是「金阙·天帝」** | | `fozu` | 金阙·天帝 | 早期「佛祖」,现为全屏神掌(`kind: 'palm'`),**不是「雷震」** | | `erlang` | 二郎·哮天 | | | `tang` | 唐僧·禅杖 | **不是 `tangtang`** | | `zhunti` | 金身·圣杵 | | | `puti` | 方寸·仙师 | | 库里如果出现表外 id(例如 `tangtang` / `tiangang`),先跑上面的 C 脚本修正;`schema.sql` 和迁移脚本里的 18 个 id 已经和前端逐条对齐,新库不会有这个问题。 ```sql -- 配说明图 / 改名 UPDATE t_hero SET hero_name = '齐天大圣·悟空', image_url = 'https://你的CDN/heroes/staff.png' WHERE hero_id = 'staff'; -- 临时下线(已上阵的玩家存档不会被删,只是不再出现在候选库里) UPDATE t_hero SET enabled = 0 WHERE hero_id = 'pagoda'; -- 排到最前 UPDATE t_hero SET sort_no = 5 WHERE hero_id = 'nezha'; ``` 注意:客户端只在**登录成功后**拉一次配置,改完库要让客户端重进上阵页或冷启动才刷新。 ### `GET /api/hero-stats` 需要鉴权,返回该玩家全部神将属性(按 heroId 排序),中文名由 `t_hero` 提供。新用户返回 `count: 0`。 | HTTP | 含义 | |---|---| | 400 | 条数超过 18 / 为空 / 字段越界 | | 401 | 凭证缺失或过期 | ### `POST /api/player-assets` 需要鉴权。**全量上报玩家资产快照**(金币 / 钻石 / 体力 / 关卡 / VIP / 战车改装 …),一玩家一行,按 `uid` upsert。 ```jsonc // 请求(字段与前端 SaveData 对应,后端列用 snake_case,JSON 用 camelCase) { "coin": 9000, "gem": 350, "stamina": 25, "unlocked": 23, "totalStars": 8, "chest": 320, "sweepTickets": 7, "signCount": 3, "signLast": "Sat Nov 08 2026", "playCount": 88, "vipExp": 120, "vipLevel": 3, "vipClaimDate": "Sat Nov 08 2026", "chariotDmgLv": 4, "chariotCritLv": 2, "chariotRateLv": 5, "chariotPower": 129, "loadout": "staff,rake,dragon,fozu", "firstTs": 1793325000000, "stTs": 1794107000000, "ownedJson": "{\"staff\":5,\"rake\":3}", "shardsJson": "{\"staff\":12}", "starsJson": "{\"0\":3,\"1\":2,\"2\":3}" } // 响应 200 { "count": 1, "updatedAt": "2026-11-12T16:52:24", "asset": { /* 本次落库的数据 */ } } ``` | 字段组 | 字段 | 说明 | |---|---|---| | 货币 | coin / gem | 金币 / 钻石,BIGINT | | 资源 | stamina / chest / sweepTickets | 体力 / 高额宝箱进度 / 扫荡券 | | 进度 | unlocked / totalStars / playCount | 已解锁关卡数 / 关卡总星数 / 累计游戏次数 | | 签到 | signCount / signLast | 连续签到天数 / 最后签到日期 | | VIP | vipExp / vipLevel / vipClaimDate | 经验 / 等级 / 每日奖励领取日期 | | 战车 | chariotDmgLv / chariotCritLv / chariotRateLv / chariotPower | 三部位改装等级 / 战力 | | 阵容 | loadout | 上阵神将 id,逗号分隔 | | 时间 | firstTs / stTs | 首次进入 / 体力回复计时起点;**接口按毫秒上报**(客户端体力回复要拿它做减法),落库前转为 `DATETIME` | | 明细 | ownedJson / shardsJson / starsJson | 神将等级 / 碎片 / 关卡星级的 JSON 原文,TEXT 存 | **上报的是整份资产、不是增量**:客户端传 9000 就是 9000,重复上报只覆盖同一行,不会把金币累加成 18000。`totalStars` / `vipLevel` / `chariotPower` 是派生值,由客户端按游戏内同一套公式算好,后端只校验范围并落库。字段值不能为负、三个 JSON 明细各不超过 8192 字符,越界返回 400。 客户端在**登录成功、资产变动(加/扣金币钻石、升级、签到、领奖、改装等)**后静默上报,带 3 秒防抖;失败或离线一律降级,不影响游戏。 > ⚠️ **这不是服务端权威账本**:资产数值由客户端上报,服务端不校验其真伪,改包即可伪造。它用于后台查询、排序、报表、看板,**不能作为发奖、扣费、防作弊的依据**。若将来要做充值 / 发放 / 交易,必须另建服务端权威的货币流水与幂等扣减,不能基于本表。 ### `GET /api/player-assets` 需要鉴权,返回该玩家资产快照。新用户返回 `count: 0`、`asset: null`。 | HTTP | 含义 | |---|---| | 400 | 字段缺失 / 为负 / 超长 | | 401 | 凭证缺失或过期 | ### `GET /api/health` 免鉴权,给负载均衡探活用。 ## 持久化层(mybatis-jet) 依赖 `com.bitcarton:mybatis-jet-spring-boot3-starter:1.0.0`,**没有 Spring Data JPA**。启动类上 `@MapperScan` 注册 `repository` 与 `mapper` 两个包,所有 Mapper 继承 `com.bitcarton.mybatisjet.core.base.BaseMapper`,纯注解生成 SQL,不需要任何 XML mapper 文件。 **每张表有且仅有一个主键**,这是框架的硬约束:启动期 `TableMetaHelper.initAllTableMeta()` 校验「`@TableId` 数量必须为 1」,复合主键(原来的 `@IdClass`)会直接抛 `multiple primary keys are not currently supported`。所以 `t_hero_stat` 不再用 `(uid, hero_id)` 双主键: | 表 | 单主键 | 策略 | |---|---|---| | `t_user` | `id` | `IdType.SNOW`,insert 时框架生成雪花 ID 并回填实体 | | `t_hero_stat` | `id` | `IdType.SNOW`;`(uid, hero_id)` 改由唯一索引 `uk_uid_hero` 保证一人一将一行 | | `t_save` / `t_player_asset` | `uid` | `IdType.NONE`,调用方赋值 | | `t_hero` | `hero_id` | `IdType.NONE`,主数据由 SQL 初始化 | 不用 `IdType.AUTO`:`InsertProviderImpl` 的 `@Options` 没开 `useGeneratedKeys`,数据库自增的 id 不会回填到实体,注册新用户就拿不到 uid。`SNOW` 零外部依赖,不需要 `leaf_alloc` 表、不需要开 `enable-segment`。 **没有 upsert**。`BaseMapper` 只有 `insert / getById / updateById / list / update / delete / saveBatch`,没有 `insertOrUpdate`。原来 JPA 的 `save()` 天然「有主键就更新、没有就插入」,现在在 Service 里显式写:先按业务键 `list(QueryWrapper...)` 查出已有行的主键,查到 `updateById`、查不到 `insert`。`SaveService` 的乐观锁是例外:要在库里做 `revision = revision + 1` 的 CAS,`update(bean, wrapper)` 只能写固定值,所以 `SaveRepository` 里用一条 `@Update` 显式 SQL。 `@Transactional` 不用改包名:starter 传递依赖了 `spring-boot-starter-jdbc`,事务管理器由 Boot 自动装配,Service 上的 Spring `@Transactional` 原样生效。 配置只有一项必须开:`mybatis.configuration.map-underscore-to-camel-case: true`,否则 `hero_id` / `updated_at` 这类列映射不到实体驼峰字段。不要配 `fixed-dialect-name`(让框架按连接自动探测)、不要配 `enable-segment` / `sql-audit-enable`。 **测试**:H2 内存库(`MODE=MySQL`),不再靠 Hibernate `create-drop` 建表,改由 `spring.sql.init.schema-locations` 执行 `src/test/resources/schema-h2.sql`,再由 `data.sql` 灌入 18 行公共神将数据。`mvn clean test` 即可,不需要本地 MySQL。 ## 数据表 ```sql t_user (id, openid UNIQUE, unionid, created_at, last_login_at) t_save (uid PK, payload TEXT, revision, updated_at) t_hero (hero_id PK, hero_name, init_atk, init_crit, init_rate, image_url, sort_no, enabled, updated_at) t_hero_stat (id PK 雪花, uid + hero_id UNIQUE, hero_id → t_hero FK, hero_level, attack, crit, rate, updated_at) t_player_asset (uid PK, coin, gem, stamina, unlocked, total_stars, chest, sweep_tickets, sign_count, sign_last, play_count, vip_exp, vip_level, vip_claim_date, chariot_dmg_lv, chariot_crit_lv, chariot_rate_lv, chariot_power, loadout, first_ts, st_ts, owned_json, shards_json, stars_json, free_claim_day, free_claim_coin_count, free_claim_gem_count, updated_at) ``` `payload` 存客户端存档的原始 JSON,**后端不解析任何字段**。这是有意的:存档结构随版本迭代会变,后端一旦开始解析,每次加字段都要改表、改 DTO、重新发版。现在无论客户端加多少字段,后端都不用动。 `t_hero` 是**公共主数据表**(全服一份):神将中文名、1 级初始值、说明图链接、上阵页顺序与启用状态都在这里,`t_hero_stat.hero_id` 通过外键引用它,后台要名字/图片 JOIN 这张表即可,玩家表不重复存。客户端 `GET /api/heroes` 只取 `enabled=1` 的行并按 `sort_no` 排序,所以后台改这两列就能控制上阵页显示哪些神将、按什么顺序,无需发版。`t_hero_stat` / `t_player_asset` 是后台要用的**结构化快照**,与 `t_save` 相互独立:存档仍是一整份 JSON 且不解析,只是把查询、排序、报表要用的字段单独拆出来落库。两者都由客户端主动上报(前者按 `id` 查后 update/insert、后者按 `uid` 查后 update/insert,见「持久化层」),数值由客户端按游戏内公式算好,后端只校验范围、不实现公式。建表语句在 `src/main/resources/db/schema.sql`。**这两张表不是权威账本**,不能作为发奖/扣费/防作弊依据,见 `POST /api/player-assets` 下的安全提示。 **时间列统一用 `DATETIME`**(`t_user.created_at` / `last_login_at`、各表 `updated_at`、`t_player_asset.first_ts` / `st_ts`),实体用 `LocalDateTime`,在库里直接能看出日期;接口响应里的 `updatedAt` 是 ISO-8601 字符串,客户端 `/api/player-assets` 入参仍按毫秒上报,由 `PlayerAssetServiceImpl` 转换。存量库从 BIGINT 毫秒升级请执行 `src/main/resources/db/migration_datetime_20261112.sql`(会先建备份表,不删数据行)。JWT 的 `iat` / `exp` 按协议必须是数字时间戳,不属于落库时间列。 ## 安全要点 1. **`appsecret` 只在服务端**。一旦进了小游戏包,等于把服务器交出去。 2. **`openid` 不下发客户端**。JWT 里只放 `uid`,openid 属于微信侧隐私标识。 3. **JWT_SECRET 至少 32 字节**,启动时校验,不够直接拒绝启动。 4. **`WX_MOCK` 生产必须关**。 5. **`t_hero_stat` / `t_player_asset` 是客户端上报的快照,不是权威账本**。数值可被改包伪造,只能用于查询/报表,不能用于发奖、扣费、防作弊。要做充值或运营发放,必须另建服务端权威流水。 6. 生产环境请在前面挂 Nginx 做 HTTPS 终止,微信小游戏 `wx.request` 只允许 https。 ## 部署 ```bash # 打包后丢到服务器,用 systemd 托管 java -jar bridge-server-1.0.0.jar --server.port=8080 ``` Nginx 反向代理示例: ```nginx location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } ``` 小游戏后台需要把这个域名加入 **request 合法域名**。 ## 客户端接入 客户端代码在 `mx-shoot-game` 仓库的 `assets/scripts/net/NetService.ts`,改一处即可: ```ts static BASE = 'https://api.example.com'; // 换成你的域名 ``` 存档同步逻辑在 `assets/scripts/core/Save.ts` 的 `bootstrap()`,具备: - 本地优先,断网照玩 - 3 秒防抖上推 - 409 冲突时整份取优(不做字段级 merge,避免金币重复累加) - 切后台(`wx.onHide` / `visibilitychange`)时强制 flush ## 已知限制 - 单档位。要支持多档需给 `t_save` 加 `slot` 字段并改主键。 - 没有做接口限流。上线前建议在 Nginx 层对 `/api/auth/login` 加 `limit_req`,防止被刷。 - 后台可通过 `GET /api/player-assets`、`GET /api/hero-stats` 查询玩家资产与神将属性,但**不能靠直接改这两张表来发钻/发币**:客户端下次全量上报会把改动整份覆盖。运营发放需另做服务端权威流水与下发队列。