# APP全局产品架构草案
> 文档版本：v1.0
> 最后更新：2026-04-02 18:10:04

本文档用于整理当前 APP 级产品逻辑的整体设想，作为后续页面架构、后端对象模型、联调边界和默认流程设计的上层基线。

---

## 1. 总体判断

当前产品不应再简单理解为“地图游戏程序”，更准确的定位应当是：

**以地图为资源底座、以活动为对外核心、以对局为过程、以用户资产为沉淀的运动游戏系统。**

这意味着：

- 地图是场地资产和体验载体
- 活动是运营层、展示层、商业层和用户入口
- Session 是一次真实对局过程
- 历史、成就、奖励、资料等属于用户长期资产

---

## 2. 一级模块建议

建议 APP 长期按 5 个一级模块组织。

### 2.1 首页 / 发现

负责：

- 地区浏览
- 地图列表
- 推荐活动
- 默认体验入口
- 宣传入口

适用对象：

- 游客
- 初次进入的新用户
- 以地图体验为目标的训练型用户

### 2.2 活动 / 赛事

这是系统核心模块。

负责：

- 活动卡片列表
- 活动详情
- 报名
- 签到
- 开局
- 公告
- 排行榜
- 社交或分享入口
- 多地图活动聚合

说明：

- 活动页本质上是系统的对外展示壳和运营壳
- 不同客户的活动页、排行榜、宣传页都可能是定制化的
- 这里适合长期采用“原生模板 + 原生 DSL + H5 增强”的分层方案

### 2.3 地图体验

负责：

- 地图默认体验活动
- 地图自由体验
- 训练入口
- 正式进入地图游戏过程
- 游戏过程中的内容、规则、结算

说明：

- 地图体验层是运行层，不是对外运营主入口
- 游客主要通过这一层进入体验

### 2.4 我的

负责：

- 历史记录
- 成绩详情
- 报名信息
- 全局头像与昵称
- 成就
- 奖励展示
- 收藏与长期资产

说明：

- 历史、成就、奖励不应分散在不同页面里，建议统一收口在用户资产中心

### 2.5 系统

负责：

- 设置
- 帮助
- 使用说明
- 反馈
- 关于
- 调试入口

---

## 3. 核心对象模型

建议长期围绕 4 个核心对象组织前后端模型。

### 3.1 Map

含义：

- 地图资源
- 场地资产
- 瓦片与底图
- 点位、图层、默认体验挂载位置

### 3.2 Event

含义：

- 活动
- 赛事
- 运营包装壳
- 报名、签到、排行榜、宣传、社交等活动级能力

说明：

- 一个 Event 可以挂一个地图，也可以挂多个地图
- 一个地图也可以承载多个 Event

### 3.3 Session

含义：

- 一次具体开局记录
- 一次真实游戏过程
- 与规则、成绩、恢复、结果页直接相关

### 3.4 User Asset

含义：

- 历史记录
- 成就
- 奖励
- 头像昵称
- 报名资料快照
- 收藏与长期沉淀

---

## 4. 用户主流程建议

### 4.1 游客主流程

1. 打开程序
2. 浏览地区和地图
3. 进入地图默认体验活动
4. 进行单局游戏
5. 结果和历史先本地保存
6. 登录后再触发同步或迁移

设计结论：

- 游客以地图体验链为主
- 游客不应直接进入正式活动能力

### 4.2 注册用户主流程

1. 打开程序
2. 浏览活动 / 赛事
3. 进入活动详情
4. 报名 / 签到 / 开局
5. 进入正式对局
6. 成绩回写历史、排行榜、奖励、成就

设计结论：

- 注册用户以活动运营链为主
- 活动是主要用户入口

---

## 5. 当前设想的逐项落点

### 5.1 地图列表

保留，但定位建议明确为：

- 自由体验入口
- 游客入口
- 训练入口

### 5.2 活动卡片列表

必须升格为核心模块。

活动系统长期需要支持：

- 标准模板活动
- 默认体验活动
- 客户定制活动

### 5.3 历史记录

建议归入“我的”模块统一管理，至少分成：

- 最近活动
- 全部记录
- 成绩详情

### 5.4 游客模式

建议正式规则为：

- 游客只可进入地图默认体验活动
- 游客数据先本地存储
- 登录后触发数据迁移或合并

### 5.5 全局资料与活动内资料

建议分两层模型：

- 全局用户资料
- 活动报名资料快照

因为活动内昵称、头像、队伍信息可能与全局资料不同。

### 5.6 帮助页面

建议未来拆成：

- 新手引导
- 使用帮助
- 常见问题

### 5.7 反馈功能

建议反馈最少自动带上：

- 当前活动
- 当前地图
- 当前 session
- 设备信息
- 程序版本

### 5.8 成就展示

当前可以先不做奖励系统，但架构上建议预留：

- 成就
- 奖章
- 奖励
- 收藏品

---

## 6. 产品主线建议

当前最适合正式确定的一条主线是：

### 游客态

- 以地图和默认体验为主

### 登录态

- 以活动和赛事为主

这个分流非常重要，因为它会影响：

- 首页结构
- 登录前后导航
- 活动和地图的权重关系
- 默认入口设计

---

## 7. 与当前工程结构的关系

对照当前代码与文档体系，可以理解为：

- `MapEngine`、渲染层、传感器层：地图资源与运行骨架
- 规则层、Telemetry、Feedback：Session 过程层
- 活动页、准备页、结果页、首页聚合：Event 与 User Asset 的上层壳
- 配置系统与文档体系：把 Map / Event / Session 的差异转为可配置运行态

因此，后续开发不应再只围绕“地图页”扩功能，而应正式开始：

- 活动系统设计
- 结果与历史沉淀设计
- 游客链与登录链分流

---

## 8. 当前阶段建议

当前建议优先做这三件事：

1. 正式梳理活动系统页面骨架  
2. 打磨顺序赛 / 积分赛的默认规则、默认样式、默认流程  
3. 明确游客模式与登录模式的数据迁移规则  

不建议当前阶段做的事：

- 过早铺开复杂社交体系
- 在奖励系统未定前做大而全的成就结构
- 让地图页承担过多对外展示职责

---

## 9. 一句话结论

当前 APP 最合理的全局方案是：

**地图是资源底座，活动是对外核心，Session 是游戏过程，历史与成就是用户资产。**

后续页面、后端模型、联调策略和配置体系，都应围绕这四个对象继续收口。
