全尺寸卡游辅助器产品整体设计方案

详细专题方案见设计文档索引。明确确认、建议冻结和暂缓事项以决策与状态记录为准。

1. 文档目的

本文档用于统一产品、硬件、固件、资源管理和测试工作的设计基线。Rev.A 的目标是验证产品核心体验，不追求一次完成最终消费级产品。

当实现细节与本文档冲突时，应先更新决策记录，再修改实现，避免硬件、固件和内容工具分别形成不兼容的约定。

2. 已确认决策

3. 产品定义

3.1 一句话定义

一张可切换武将、管理体力与状态的全尺寸电子武将牌；玩家搭配一副实体手牌，即可开展三国杀线下面杀。

3.2 目标用户

• 经常参与三国杀线下面杀的玩家。
• 拥有大量武将牌、扩展包，携带和整理成本较高的玩家。
• 希望快速选将、补充缺失武将并简化体力管理的桌游组织者。
• 喜欢个性化桌搭、卡牌展示和收藏设备的用户。

3.3 核心问题

• 武将种类多，实体武将牌携带和整理不便。
• 不同模式下体力、护盾和状态规则容易记错。
• 选将、补抽和寻找指定武将影响开局效率。
• 体力牌、标记物容易移动、丢失或产生歧义。

3.4 核心价值

1. 用一台设备承载大量武将牌。
2. 保留接近实体卡牌的尺寸、持握和展示体验。
3. 自动处理体力上限、身份修正、护盾和通用计数。
4. 通过反射式显示实现无背光、长时间静态展示和低功耗。
5. 固件和资源格式为后续其他卡游预留扩展能力，但不扩大 Rev.A 范围。

3.5 产品边界

本产品是线下面杀辅助设备，不是线上游戏客户端，不实现线上匹配、远程对局、自动裁决或替代实体手牌。

4. Rev.A 范围

4.1 必须实现

• 从 MicroSD 读取卡牌包和武将资源。
• 卡池列表、武将列表和最近使用。
• 全屏展示武将牌。
• 选择普通、主公、地主等身份修正。
• 显示并增减体力。
• 显示并增减护盾。
• 一个可命名的通用 Token 计数器。
• 游戏状态锁定、防误操作和单步撤销。
• 休眠、唤醒和未结束对局恢复。
• RTC 时间和对局持续时间。
• 电量显示和低电量处理。
• USB 固件升级与调试。
• 屏幕、MicroSD、按键、RTC、电池的诊断页面。

4.2 可在 Rev.A 后半段加入

• 随机选将。
• 收藏武将。
• 通过 USB 向设备传输卡牌包。
• Wi-Fi 配网和资源传输。
• BLE 近距离设备发现。
• 简单对局摘要。

4.3 暂缓

• 触摸交互。
• NFC 加好友或碰一碰。
• 多设备组局和群主流程。
• 完整好友系统、账号系统和云同步。
• 游戏统计和社交分享。
• 卡牌市场、付费内容和插件市场。
• 阅读器、相册的专门产品功能。
• 扬声器、RGB 灯、振动马达和磁吸扩展配件。
• 设备端 OCR、图片裁切或复杂素材处理。
• 除三国杀之外的游戏插件。

5. 典型使用流程

5.1 首次使用

1. 用户在电脑上准备 MicroSD 和卡牌包。
2. 插卡开机，设备检查文件系统和资源索引。
3. 首次使用显示五键操作说明。
4. 用户选择卡池、武将和身份。
5. 设备计算体力上限并进入游戏界面。

5.2 日常开始游戏

1. 唤醒设备。
2. 选择“继续上次游戏”或“选择武将”。
3. 选择卡池和武将。
4. 选择身份，设备应用身份修正。
5. 进入卡面，默认可操作；休眠恢复或异常恢复后保持锁定。

5.3 游戏中

1. 长按确定解锁操作。
2. 上键增加体力，下键减少体力。
3. 确定键打开护盾和 Token 状态菜单。
4. 返回键撤销最近一次状态变化。
5. 根据可选设置决定是否自动锁定，默认关闭。

5.4 结束游戏

1. 长按返回，出现结束确认。
2. 确认后保存最小对局摘要或直接结束。
3. 返回武将选择或进入休眠。

6. Rev.A 硬件方案

6.1 总体结构

USB-C
  ├─ 充电与电池保护
  ├─ ESP32-S3 原生 USB
  └─ USB 插入检测

800 mAh 锂电池
  └─ 低静态功耗 3.3 V 电源
      ├─ ESP32-S3 N16R8
      ├─ ST7305 RLCD
      ├─ MicroSD 卡座
      └─ PCF85063 RTC

ESP32-S3
  ├─ SPI → ST7305
  ├─ SPI → MicroSD
  ├─ I2C → PCF85063
  ├─ GPIO → 五键
  ├─ ADC → 电池电量检测
  ├─ USB → 升级、调试、后续资源传输
  └─ 预留 GPIO → 后续扩展接口

6.2 主控与存储职责

卡牌资源不依赖 16 MB 内部 Flash。设备拔出 MicroSD 后，当前对局状态仍应保留在内部存储中。

6.3 屏幕

• 当前：4.2 英寸 RLCD。
• 方向：300 × 400 竖屏为默认设计基准。
• 灰阶：逻辑上按 2 灰阶、1-bit 资源设计。
• 驱动：ST7305。
• 接口：SPI。
• 逻辑全帧大小约为 15 KB；实际显存打包、扫描方向和刷新命令以模组资料为准。
• 卡牌比例与屏幕比例不同，完整卡面适配时可渲染为约 286 × 400，并保留窄边距；最终参数以实际有效显示区域为准。

Rev.A 重点验证尺寸、可读性、刷新、交互和功耗，不以黑白画面评价最终六色显示品质。UI长期保留RLCD与六色屏两套配置，共享信息架构、五键和组件语义，分别维护视觉资源与刷新策略。

6.4 屏幕信号预算

应至少预留以下信号，具体 GPIO 在原理图阶段确定：

• LCD_SCLK
• LCD_MOSI
• LCD_CS
• LCD_DC
• LCD_RST
• LCD_BUSY 或屏幕中断（模组支持时）
• LCD_PWR_EN

即使当前模组未使用全部信号，也应为后续六色墨水屏预留 BUSY、复位和独立电源控制能力。

6.5 MicroSD

• Rev.A 使用 MicroSD 卡座，建议支持 8～32 GB 卡进行主要验证。
• 默认文件系统为 FAT32。
• 使用 SPI 模式并配置独立片选。
• 卡座建议提供插卡检测信号。
• 屏幕和 MicroSD 可以共享 SPI 时钟与数据线，也可在 GPIO 和布板允许时使用不同 SPI 控制器。
• 游戏模式以只读资源为主，导入、删除等写操作集中在专门管理模式。

建议预留：

• SD_SCLK
• SD_MOSI
• SD_MISO
• SD_CS
• SD_DETECT
• 可选 SD_PWR_EN

6.6 RTC

PCF85063 通过 I2C 连接，用于：

• 当前时间。
• 对局开始时间和持续时长。
• 时间戳。
• 可选定时唤醒。

应预留 I2C_SDA、I2C_SCL 和可选 RTC_INT。是否配置后备电源取决于“主电池完全失电后是否必须保持时间”的产品要求。

6.7 五键

规则：

• 游戏界面的上、下键不启用连续连发。
• 所有按键包含消抖、短按、长按和超长按识别。
• 长按阈值应通过样机测试确定，初始建议约 1 秒。
• 硬件复位使用隐藏针孔，不作为第五个日常按键。

6.8 电源

• 电池目标容量为 800 mAh。
• 3.3 V 电源需承受 ESP32-S3 开启无线功能时的瞬时负载，设计应留足余量。
• 稳压器、充电芯片和电池保护器件需优先关注静态功耗。
• 屏幕和 MicroSD 应尽可能支持独立断电或低功耗控制。
• 电池电压采样分压应可关断，避免持续漏电。
• 支持 USB 插入检测和边充边用，具体电源路径方案在原理图阶段确认。

功耗不能只依据器件标称值推算，必须在 Rev.A 实机测量。

6.9 后续扩展接口

Rev.A 可预留四针焊盘或触点，但不作为首轮验收项。候选定义为：

最终定义需同时处理短路、静电、插拔、反接和外设供电保护，未完成电气评审前不得视为对外接口承诺。

7. 显示与资源方案

7.1 显示抽象

游戏逻辑不得直接调用 ST7305 驱动。固件分为：

业务界面与游戏状态
        ↓
统一显示接口
        ↓
ST7305 驱动 / 后续六色墨水屏驱动

统一显示接口至少提供：

• 初始化、休眠和唤醒。
• 获取屏幕宽高、颜色能力和刷新能力。
• 全屏刷新。
• 矩形区域刷新。
• 绘制位图、文字、线条和状态图标。
• 刷新完成或忙状态查询。
• 屏幕错误恢复。

建议使用屏幕能力描述，而不是在业务代码中判断具体驱动名称，例如：

width
height
color_mode
supports_partial_refresh
partial_refresh_alignment
full_refresh_cost

7.2 RLCD 内容处理

原始彩色卡图不直接在设备端转换。电脑端工具负责：

• 缩放和裁切。
• 对比度调整。
• 灰度到 1-bit 转换。
• 适当抖动。
• 加强人物、名称和关键文字轮廓。
• 输出设备可直接读取的显示资源。

设备只负责读取、合成状态层和刷新屏幕，避免在 ESP32-S3 上执行 OCR 或复杂图像处理。

7.3 卡面模式

Rev.A 同时保留两种界面进行用户测试：

1. 全卡面模式：默认显示完整武将牌，操作时临时叠加体力和状态层。
2. 固定状态区模式：压缩卡面，在底部永久显示体力、护盾和 Token。

默认推荐全卡面模式，因为更符合“电子武将牌”的产品定义。最终选择由真实对局测试决定。

7.4 六色屏迁移

卡牌资源应允许同时携带 RLCD 和彩色变体：

characters/caocao/
├─ card.json
├─ rlcd.bin
└─ color.png

更换六色屏时，预期修改范围为：

• 新屏幕底层驱动。
• 新的颜色转换和资源打包工具。
• 屏幕能力描述。
• 必要的布局适配。
• 电源、时序和刷新策略。

武将规则、卡池、按键、状态管理和对局流程不得因换屏重写。

8. 固件架构

应用层
├─ 首页
├─ 卡池与武将库
├─ 快速游戏
├─ 体力、护盾和 Token
├─ 对局恢复
├─ 设置
└─ 诊断

领域层
├─ 卡牌与卡池模型
├─ 游戏规则适配
├─ 身份修正规则
├─ 对局状态机
├─ 撤销记录
└─ 资源索引

设备服务层
├─ 显示服务
├─ 输入服务
├─ 存储服务
├─ RTC 服务
├─ 电源服务
├─ USB 服务
├─ Wi-Fi 服务
└─ BLE 服务

驱动层
├─ ST7305
├─ SPI / MicroSD
├─ PCF85063
├─ GPIO 按键
├─ ADC 电量检测
└─ USB

8.1 设计原则

• 业务逻辑与具体屏幕驱动解耦。
• 三国杀规则位于游戏适配层，不散落在界面代码中。
• 资源读取失败不能导致设备无法进入设置或诊断页面。
• 当前对局不依赖 MicroSD 持续可写。
• 无线连接失败不能阻止本地游戏。
• 所有可能长时间运行的存储、刷新和通信操作均应避免阻塞按键处理。

9. 数据与存储设计

9.1 MicroSD 目录

/cardhelper/
├─ manifest.json
├─ games/
│  └─ sanguosha/
│     ├─ game.json
│     ├─ pools/
│     │  ├─ standard.json
│     │  └─ expansion.json
│     └─ characters/
│        └─ caocao/
│           ├─ card.json
│           ├─ rlcd.bin
│           └─ color.png
└─ updates/

9.2 卡牌属性示例

{
  "schemaVersion": 1,
  "id": "sgs_caocao_001",
  "name": "曹操",
  "game": "sanguosha",
  "pools": ["standard"],
  "maxHp": 4,
  "maxShield": 0,
  "orientation": "portrait",
  "assets": {
    "rlcd": "rlcd.bin",
    "color": "color.png"
  }
}

身份规则不改写卡牌的基础体力。开始游戏时计算：

实际体力上限 = 武将基础体力 + 模式修正 + 身份修正

9.3 内部状态

以下信息保存在内部 NVS 或等价的带磨损均衡存储中：

• 最近使用的武将和卡池。
• 用户设置。
• 当前武将 ID。
• 当前体力和体力上限。
• 当前护盾。
• Token 名称和数值。
• 模式和身份。
• 对局开始时间。
• 锁定状态。
• 最近一次可撤销操作。

状态变化后延迟合并写入，例如停止操作约 2 秒后保存；进入休眠或关机前强制保存，避免每次按键都写 Flash。

9.4 文件安全

• 正常游戏期间对 MicroSD 以只读为主。
• 设备写资源时使用临时文件、校验完成后再原子替换索引。
• USB 资源传输进入专用模式，避免电脑和设备同时修改同一文件系统。
• 检测到损坏或缺失资源时跳过单项并记录错误，不阻塞整个系统启动。
• 无卡启动时显示插卡说明、设置和硬件诊断，同时保留内置测试图。

10. 交互与状态机

10.1 游戏锁定

进入游戏（默认可操作）
   ├─ 上：体力 +1
   ├─ 下：体力 -1
   ├─ 返回：限时撤销
   ├─ 确定：状态菜单
   └─ 长按确定：锁定/解锁

自动锁定允许在设置中选择关闭、30秒、60秒或120秒，默认关闭；最终值由真实对局测试决定。

10.2 状态变化反馈

• 只刷新发生变化的区域，屏幕不支持可靠局刷时再退化为全刷。
• 显示“体力 3 → 2”等短暂反馈。
• 达到上限或下限时不修改数值，并给出明确提示。
• 返回键仅撤销最近一次体力、护盾或 Token 操作。
• 切换武将、结束游戏等高影响操作需要确认。

10.3 异常状态

11. USB、Wi-Fi 与 BLE

11.1 USB

实施顺序：

1. Rev.A 早期：固件烧录、日志和调试。
2. 可玩原型：固件升级。
3. MVP：专用资源传输模式。

Rev.A 早期资源可通过电脑直接写入 MicroSD。设备端 USB 传输未完成前，不将设备伪装成可被电脑和固件同时写入的大容量磁盘。

11.2 Wi-Fi

硬件保留 2.4 GHz Wi-Fi，首轮用途候选为：

• 网络校时。
• 局域网资源传输。
• 固件更新。

无线不可用时，所有本地游戏功能仍应正常工作。

11.3 BLE 5

首轮仅完成基础硬件和协议验证。设备发现、近距离传输、多设备互动属于后续阶段，不进入最小可玩原型验收。

12. 原型界面信息架构

启动
├─ 继续上次游戏
├─ 选择武将
│  ├─ 最近使用
│  ├─ 收藏
│  ├─ 卡池
│  └─ 随机选将（后半段）
├─ 设置
│  ├─ 自动锁定
│  ├─ 屏幕方向
│  ├─ 时间
│  ├─ 无线
│  ├─ 设备信息
│  └─ 存储管理
└─ 诊断
   ├─ 屏幕
   ├─ 按键
   ├─ MicroSD
   ├─ RTC
   ├─ 电池
   └─ 无线

300 × 400 黑白屏上的武将浏览采用文字列表，不使用大量低辨识度缩略图。中文输入和设备端全文搜索不作为 Rev.A 的必要功能。

13. 功耗状态

Rev.A 必测项目：

• 关机电流。
• 深睡眠电流。
• 保持静态卡面时的平均电流。
• 单次全屏和局部刷新能耗。
• MicroSD 读取时的峰值电流。
• Wi-Fi 传输时的平均与峰值电流。
• 连续两小时真实对局的电量消耗。
• USB 充电时间和边充边用温升。

14. 法律与内容合规

• 产品官方在未获得授权时不预装、销售或公开分发第三方受保护的卡图、Logo、角色素材和规则数据库。
• “允许用户自行导入”或“第三方插件”不能自动消除版权和商标风险。
• 对外宣传优先描述通用图片展示、用户自有资源管理和状态计数能力。
• 官方合作内容应具备明确授权范围、分发方式、期限和更新机制。
• 商业发布前应对设备预装内容、演示素材、资源导入方式和品牌表达进行专项知识产权审查。
• 官方资源工具不内置未经授权素材源，也不提供针对受保护网站的一键抓取能力。

15. 开发阶段与退出条件

阶段 A：硬件点亮

• ST7305 稳定显示测试图。
• 完成全刷和可用的局刷验证。
• 五键短按、长按和消抖可靠。
• MicroSD 能稳定挂载并读取资源。
• RTC 和电量检测工作正常。

阶段 B：最小可玩原型

• 能读取至少 100 张武将牌。
• 能浏览卡池并选择武将。
• 能选择身份并正确计算体力上限。
• 能增减体力、护盾和 Token。
• 能锁定、解锁并撤销一次操作。
• 休眠和意外复位后能够恢复未结束对局。

阶段 C：真实对局验证

• 完成至少 5 场真实线下面杀测试。
• 每场至少连续运行 2 小时。
• 记录误触、刷新等待、可读性和续航问题。
• 比较全卡面模式与固定状态区模式。
• 明确用户可接受的整机尺寸、刷新速度和价格区间。

阶段 D：六色屏迁移准备

• 确认候选六色屏尺寸、分辨率、刷新、功耗、接口、价格和供货周期。
• 证明新驱动可接入统一显示接口。
• 建立六色资源转换流水线。
• 评估主板电源、GPIO 和外壳是否需要改版。

16. Rev.A 验收标准

• 冷启动可以可靠读取资源索引。
• 无 MicroSD 也能进入系统设置和诊断。
• 至少 100 张武将牌连续切换不死机、不损坏文件。
• 身份修正和体力边界计算正确。
• 游戏状态修改、防误触、撤销和自动锁定工作正确。
• 休眠、唤醒和异常重启后状态可恢复。
• 屏幕刷新失败、卡损坏和 RTC 无效均有可恢复路径。
• 连续完成两小时对局，无非预期重启。
• 能输出屏幕刷新、存储、无线和整局功耗测量结果。
• 替换显示驱动不需要修改三国杀游戏规则和对局状态逻辑。

17. 待决策事项

以下事项尚未冻结：

• ST7305 模组的具体供应商、有效显示尺寸、引脚、电压和刷新限制。
• ESP32-S3 模组具体料号与板载/外接天线选择。
• 充电、保护、电源路径和 3.3 V 稳压器件。
• RTC 是否配置独立后备电源。
• MicroSD 与屏幕共享 SPI 还是分别使用 SPI 控制器。
• 电量估算采用简单 ADC 还是电量计芯片。
• 四针扩展接口是否进入 Rev.A PCB，以及最终电气定义。
• 外壳尺寸、厚度、重量、挂环、磁吸结构和定制面板方式。
• 全卡面模式与固定状态区模式的最终选择。
• USB 资源传输协议和电脑端工具形态。
• 六色墨水屏的具体型号和量产供货方案。
• BOM 目标、零售价格和首批数量。

18. 决策记录