本文档根据当前 Web 启动器（web/） 与 WinUI 登录页（微信扫码） 中的界面与假数据归纳，供后端建表参考。实际表名、字段类型可按所用数据库（PostgreSQL / MySQL / SQL Server 等）调整。
一、当前程序功能概览
| 模块 | 功能要点 |
|---|---|
| 账号 | 桌面端微信扫码登录（需绑定平台用户） |
| 个人资料 | 昵称、展示 ID、等级、VIP、钱包（传奇币/礼包/背包类计数） |
| 游戏目录 | 996 / Gee 频道、分类与特色筛选、推荐标记、排序（人气/下载量） |
| 游戏详情 | 标题、标语、海报、人气、下载量、点赞数（可冗余）、品类、特色标签、可选：体积、上架/推荐时间、作者 |
| 激活 / 购买 | 未购游戏走激活页；会员 / 激活码等模式（演示） |
| 已购 / 收藏 | 用户维度的游戏列表 |
| 互动 | 收藏、点赞（可按游戏聚合统计） |
| 下载 | 由客户端根据 games.package_download_url 拉取；进度与队列仅存本机，不落库 |
| 本地资源 | 是否已下载、安装路径等由客户端本地维护，后端不建表 |
| 首页 | 新游时间轴、主推 Banner、热门横滑、右侧促销卡片、公告列表 |
| 游戏管理（演示） | 启停服、工具入口、存档与 GM 等均为界面演示，后端不建表 |
二、建议数据表与字段
1. users（用户主表）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT / UUID PK | 用户主键 |
| wechat_openid | VARCHAR(64) UNIQUE NULL | 微信 OpenID（若仅扫码可再扩展 unionid） |
| wechat_unionid | VARCHAR(64) UNIQUE NULL | 可选 |
| phone | VARCHAR(20) NULL | 可选绑定 |
| status | TINYINT | 正常/冻结等 |
| created_at / updated_at | DATETIME |
2. user_profiles（展示与成长，可与 users 合并为单表以减少联表）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| user_id | PK，FK → users.id | 与账号 一对一；删除用户时建议 ON DELETE CASCADE 或业务层一并删除 |
| nickname | VARCHAR(64) | 展示名 |
| avatar_url | VARCHAR(512) NULL | 头像 |
| subtitle | VARCHAR(128) NULL | 个性签名/副标题 |
| display_uid | VARCHAR(32) UNIQUE | 对外唯一展示 ID（如 1132309） |
| level | INT | 等级 |
| vip_level | INT | VIP 等级 |
| coin | BIGINT | 传奇币等 |
| gift_count | INT | 礼包类计数 |
| bag_count | INT | 背包类计数 |
| created_at | DATETIME | |
| updated_at | DATETIME |
3. game_categories（类别字典 / 后台可维护）
与前端 categoryOptions（如：全部、单职业、三职业、多职业）对应；游戏表用 category_id 关联本表。类别为全站共用字典；频道（996 / Gee）仅在 games.source_channel，列表筛选典型写法：WHERE source_channel = ? AND category_id = ?（及特色等多对多条件）。
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | INT PK | 类别 ID，接口筛选传此 ID |
| code | VARCHAR(32) UNIQUE NULL | 稳定业务键，如 single_class（可选，利于多语言或迁移） |
| name | VARCHAR(32) | 展示名称，如 单职业 |
| sort_order | INT DEFAULT 0 | 列表/筛选项排序 |
| status | TINYINT | 启用/停用；停用后不在筛选器展示 |
| created_at / updated_at | DATETIME |
用 ID 关联相对直接存 category 字符串的好处：索引更小、等值查询稳定；改名只改字典表一行；后台增删类别不需批量改 games；与「特色标签」同样采用字典 + 关联，模型一致。
4. games（游戏主数据 / 上架目录）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| slug | VARCHAR(64) UNIQUE NULL | URL、分享、后台检索用稳定键（如 zhong-shen-zhi-zhan） |
| title | VARCHAR(128) | 名称 |
| tagline | VARCHAR(256) NULL | 短描述 |
| source_channel | VARCHAR(16) | 996 / gee，库内统一小写，与接口常量一致；与 category_id 组合筛列表 |
| category_id | INT FK → game_categories.id NULL | 职业/玩法类别；常与 source_channel 联查 |
| poster_url | VARCHAR(512) NULL | 海报图 URL（前端现用渐变可改为 URL） |
| popularity | BIGINT DEFAULT 0 | 人气（建议异步汇总写入，见 §四） |
| download_count | BIGINT DEFAULT 0 | 下载量（展示/统计，建议异步汇总） |
| like_count | BIGINT DEFAULT 0 | 点赞总数，与 user_game_likes 双写：写入点赞明细时同步 +1/-1 或定时校准 |
| is_new | BOOL | 是否新游；可与 listed_at 规则并用 |
| listed_at | DATETIME NULL | 上架时间；可做「新游 N 天内」自动规则 |
| is_recommended | BOOL DEFAULT false | 是否推荐（强推、精选等） |
| recommend_until | DATETIME NULL | 推荐截止时间；到期后任务或查询层与 is_recommended 一并处理 |
| file_size_bytes | BIGINT NULL | 客户端大小 |
| package_download_url | VARCHAR(2048) NULL | 游戏包下载地址（HTTPS 直链、对象存储预签名 URL 或下载网关路径；客户端据此拉取） |
| updated_at | DATETIME NULL | 版本更新时间 |
| author | VARCHAR(64) NULL | 作者/发行方 |
| status | TINYINT | 上架/下架（勿物理删除有订单/激活关联的游戏，优先配合 deleted_at） |
| created_at | DATETIME | |
| deleted_at | DATETIME NULL | 软删除；非空表示下线且保留历史关联 |
若同一游戏需 多包（分卷、Windows/Mac、增量补丁等），可另建子表 game_packages（game_id、平台、序号、download_url、file_size_bytes、checksum 等），主表 package_download_url 可表示默认包或留空仅走子表。
游戏特色标签（多对多）
5. game_features（标签字典，可选）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | INT PK | |
| code | VARCHAR(32) UNIQUE | 稳定英文/拼音键，如 has_bot、micro_change（勿用中文作 code） |
| label | VARCHAR(32) | 中文展示名，如「有假人」「微变」 |
| sort_order | INT DEFAULT 0 | 筛选项/后台列表排序 |
| status | TINYINT | 启用/停用 |
| created_at / updated_at | DATETIME |
6. game_feature_rel（游戏 ↔ 标签）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| game_id | FK | 删除游戏前需处理关联或禁止物理删除（见 §四） |
| feature_id | FK | 建议单列索引 feature_id，便于按标签反查游戏 |
| created_at | DATETIME | 打标时间，便于审计 |
| PK | (game_id, feature_id) |
7. user_game_purchases（已购 / 授权）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| user_id | FK | |
| game_id | FK | |
| acquired_at | DATETIME | 获得时间 |
| source | VARCHAR(32) NULL | purchase / gift / activation_code 等 |
| order_id | BIGINT NULL | 关联订单 |
| UNIQUE | (user_id, game_id) | 同一游戏一条授权 |
8. user_game_favorites（收藏）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| user_id | FK | |
| game_id | FK | |
| created_at | DATETIME | |
| PK | (user_id, game_id) |
9. user_game_likes（点赞，若需防重复）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| user_id | FK | |
| game_id | FK | |
| created_at | DATETIME | |
| PK | (user_id, game_id) |
点赞列表以
user_game_likes为准；列表页展示用games.like_count（双写或定时对齐）。
10. activation_codes（激活码，可选）
生产环境不明文存完整码：仅存哈希 + 盐；核销时对用户输入做相同哈希比对。max_uses / used_count 更新需事务或行锁防并发超卖。
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| batch_no | VARCHAR(64) NULL | 运营批次/备注，便于后台筛选 |
| code_hash | CHAR(64) NOT NULL | 激活码 SHA-256（或同等）十六进制，与 salt 共同校验 |
| salt | VARCHAR(32) NOT NULL | 每码独立盐；校验：hash(规范化输入 + salt) 与 code_hash 比对 |
| game_id | FK NULL | 绑定单游戏或 NULL 表示通用 |
| max_uses | INT | 总可核销次数 |
| used_count | INT | 已核销次数 |
| expires_at | DATETIME NULL | |
| status | TINYINT | |
| created_at | DATETIME |
核销流程：用户提交明文码 → 规范化 → 对候选或全表匹配 code_hash（若业务允许可先按 batch_no 缩小范围）；匹配成功后递增 used_count 并写 activation_redemptions。
11. activation_redemptions（激活记录）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| user_id | FK | |
| code_id | FK | |
| game_id | FK | |
| redeemed_at | DATETIME | |
| UNIQUE | (code_id, user_id) | 防同一用户重复核销同一码（按需；若一码多用户可去掉） |
12. orders（订单，若存在付费购买）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| order_no | VARCHAR(64) UNIQUE | 商户侧订单号，对外展示与对账 |
| user_id | FK | |
| amount | DECIMAL(12,2) | |
| currency | VARCHAR(8) | |
| status | VARCHAR(16) | |
| payment_channel | VARCHAR(32) NULL | 如 wechat_pay、alipay |
| third_party_trade_no | VARCHAR(64) NULL | 微信/支付宝交易号等，建议索引 |
| notify_payload | TEXT NULL | 支付回调原文，便于对账与排错 |
| game_id | FK NULL | 单笔单游戏时可填；多商品以 order_items 为准，此字段可空 |
| created_at / paid_at | DATETIME |
13. order_items（订单明细，多商品时必填）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| order_id | FK → orders.id | |
| game_id | FK | |
| quantity | INT DEFAULT 1 | |
| unit_price | DECIMAL(12,2) | 行单价 |
| created_at | DATETIME |
单笔单游戏可仅填 orders.game_id 或只写一行 order_items，由产品约定。
14. announcements（公告）
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| title | VARCHAR(256) | 或纯文本一行 |
| content | TEXT NULL | |
| link_url | VARCHAR(512) NULL | 点击跳转 |
| link_target | VARCHAR(16) NULL | _blank / _self 等 |
| source_channel | VARCHAR(16) NULL | 996 / gee；NULL 表示全站 |
| published_at | DATE / DATETIME | |
| sort_order | INT | |
| status | TINYINT |
15. home_banners / home_recommend_slots（首页 Banner / 新游推荐，可拆分）
与 games.is_recommended / home_banners.game_id 并存时，运营需约定：强推以 Banner 配置为准还是以游戏字段为准，避免重复位冲突。
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| slot_type | VARCHAR(32) | hero / timeline / popular_row |
| game_id | FK NULL | 关联游戏或纯图 |
| image_url | VARCHAR(512) NULL | |
| title / subtitle / tag | VARCHAR | 展示文案 |
| gradient_css | VARCHAR(256) NULL | 过渡期可存前端样式 |
| source_channel | VARCHAR(16) NULL | NULL=全站；否则仅该频道展示 |
| start_at / end_at | DATETIME NULL | 投放时间 |
| sort_order | INT | |
| status | TINYINT | 启用/停用 |
16. promo_cards（右侧促销位，可选）
与 home_banners 职责接近；长期可演进为统一「运营位」表，当前保持分表并 字段对齐（状态、有效期、频道）。
| 字段 | 类型建议 | 说明 |
|---|---|---|
| id | BIGINT PK | |
| title | VARCHAR(64) | |
| description | VARCHAR(128) | |
| tone | VARCHAR(16) | 前端配色 key |
| link_url | VARCHAR(512) NULL | |
| source_channel | VARCHAR(16) NULL | NULL=全站 |
| start_at / end_at | DATETIME NULL | 与 Banner 一致 |
| sort_order | INT | |
| status | TINYINT | 启用/停用 |
三、与前端假数据对应关系（便于联调）
launcherData.js→user_profiles（含display_uidUNIQUE）+ 部分静态导航可配置表（未单独列出）。gameCatalogData.js→game_categories+games（含slug、source_channel小写、like_count、listed_at/ 推荐字段等）+game_features（code英文 /label中文）+game_feature_rel；已购集合 →user_game_purchases。- 前端
downloadTasks/useDownloadQueue、管理页「游戏已下载」、GM 名单 / 存档列表等均为客户端本地或纯演示，不对应后端表。 announcements/heroBanner/popularGames/promoCards→announcements、home_banners、promo_cards（均支持source_channel、有效期等）或统一 CMS。
四、说明（索引、删除策略、同步与运维）
- 字符集：库表建议使用 utf8mb4（MySQL）或等价，避免中文与 emoji 截断。
- 索引（常用）：
(source_channel, status)、(source_channel, category_id)、(source_channel, is_recommended)、(user_id, game_id)、game_feature_rel(feature_id)、orders(third_party_trade_no)、activation_codes核销链路按实现加code_hash或批次索引。 - 删除策略：对
games优先 软删（deleted_at），外键对子表宜 RESTRICT 或业务校验，避免物理删除连带订单/激活记录异常；删除用户时user_profiles建议 CASCADE 或随账号一并清理。 - 计数与冷热数据：
popularity、download_count宜异步汇总写games，与下单链路解耦；点赞采用user_game_likes+games.like_count双写，写入明细时同步增减或短周期校准任务。 - 激活码：
used_count与核销插入activation_redemptions同学务事务；大批量发码时明文仅导出一次，库中只留code_hash。 - 本文档为 草案，落地前请结合支付、风控、审计与合规再评审。
五、残留与演进（未强制改表结构）
以下仍为产品/工程选型，未再拆新表：
| 项目 | 说明 |
|---|---|
users 与 user_profiles | 可合并为单表；当前保留拆分并已补 created_at、一对一 PK、display_uid UNIQUE。 |
home_banners 与 promo_cards | 仍分两表，字段已对齐；后续可合并为统一「运营位」表 + position。 |
| 支付审计 | 已用 orders.notify_payload 存回调原文；若量大可再拆 payment_notify_logs。 |
文档版本：与仓库 web/ + Pages/LoginPage 功能同步归纳，随产品迭代更新。
六、管理端（MineAdmin / cq_server）说明
- 业务表使用迁移
databases/migrations/2026_04_23_100000_create_cq_box_tables.php（表名带DB_PREFIX，如cq_app_user、cq_game等），对应后台与 权限 / 日志 并列的三个一级菜单：box:userMgmt用户管理（C 端用户、收藏、已购）、box:gameBiz游戏业务（分类、目录、特色）、box:ops运营管理（公告、首页位、促销卡等）。无单独的「玛法盒子」总节点（name=box已不再使用）。 - 全新/重装菜单数据：
databases/seeders/menu_seeder_20240926.php已包含上述 cqBox 三项一级菜单 整树；执行全量db:seed会按项目配置依次跑多个 Seeder，其中user_seeder会truncate用户表，生产环境慎跑。 - 已有库只补菜单：
php bin/hyperf.php db:seed --path=databases/seeders/cq_box_menu_20260423.php --realpath（若已存在parent_id=0的box:userMgmt则跳过）。 - 已有库去掉旧根「box」、与种子对齐：
php bin/hyperf.php db:seed --path=databases/seeders/cq_box_menu_reorg_nested_20260423.php --realpath（若仍存在name=box：必要时先在box下建三个分组并归组子菜单，再把box:userMgmt/box:gameBiz/box:ops提到一级并删除box）。 - 运营类表：
announcement、home_banner、promo_card由迁移2026_04_24_100000_create_cq_box_cms_tables.php创建；后台在 运营管理 下提供「公告管理 / 首页运营位 / 促销卡片」页面。若需同步权限，请在 系统管理 → 菜单 中处理，或为超级管理员重新勾选新菜单。