iOS · SwiftUI · MVP · App Store 审核中

VPCT – VPIP Controller

一款实时扑克行为分析应用：在 live session 中追踪 VPIP（Voluntarily Put $ In Pot），并通过事件驱动的行为分析检测 tilt（情绪失控）模式；在行为未自我纠正时升级到冷静模式（Cooldown）。同时提供 session 与生涯统计，帮助理解自己的打法风格。

本文为 MVP 的架构与实现方案整理；tilt 子系统细则以仓库内 TILT_DETECTION.md 为准。

页面与导航（4 Tab）

├── VT (Home)       — 首页：VPIP 概览 + 最近 session
├── Live (Session)  — 牌局中：实时记录 + tilt 检测
├── Stats           — 统计分析（仅登录用户）
└── Me (Settings)   — 设置、账户、语言、外观

技术栈

层级	技术
UI	SwiftUI
架构	`@Observable` + DataService（集中式数据服务）
本地存储	SwiftData
认证	Sign in with Apple（计划中）
状态	`@Observable`
本地化	应用内 L10n 枚举（非系统 .strings）

账户体系

Guest 模式（当前默认）

无需登录即可使用全部 session 相关功能。
Guest 数据不持久化：app 重启后清除已结束 session。
Guest 下不累积 lifetime 统计。
在 session 结束、首页 banner 等关键时刻提示登录。

Logged-in 模式（计划中）

Sign in with Apple。
数据持久化，lifetime 统计累积。
Stats Tab 完整开放。

数据模型

PlayerData

字段	类型	说明
id	UUID	唯一标识
createdAt	Date	账户创建时间
lifetimeHands	Int	总手数
lifetimeVPIPHands	Int	总 VPIP 手数

SessionData

字段	类型	说明
id	UUID	唯一标识
startTime	Date	开始时间
endTime	Date?	结束时间（nil = 进行中）
totalHands	Int	本 session 手数
vpipHands	Int	本 session VPIP 手数
totalBBResult	Double?	BB 盈亏（可选）
handRecords	[HandRecordData]	级联删除

HandRecordData

字段	类型	说明
id	UUID	唯一标识
timestamp	Date	手牌时间
didVPIP	Bool	是否入池（VPIP）
card1Rank / card2Rank	String?	牌面点数 A–2
isSuited	Bool?	同花 / 非同花
resultRaw	String?	WIN / NOT_WIN
bbResult	Double?	BB 结果（可选）
positionRaw / actionTypeRaw	String?	预留 Pro
session	SessionData?	父 session

手牌录入流程

VPIP 手牌（≤ 4 次点击目标）

点选第一张牌（rank A–2）
点选第二张牌（同点数 = 口袋对）
（可选）切换同花 / 非同花（口袋对时自动禁用）
（可选）输入 BB 数量
点 WIN 或 LOSS → 自动收起

Fold

单次点击 FOLD：中等强度触觉 + 统计条视觉闪烁；totalHands += 1，无需进一步输入。

数据管理

Session 内手牌：支持长按删除（context menu）。
首页与全部 session 列表：支持长按删除整个 session。
删除 session 时：反向扣减 lifetime 统计并重新计算相关聚合。

Session 屏实时统计展示

状态	界面
Warm-up（< 10 手）	进度环倒计时 + 手数
Normal	Session VPIP（hero）+ 30min / lifetime / hands 条带
Warning	30min VPIP（hero，琥珀色）+ session / lifetime 条带
Danger	30min VPIP（hero，红色）+ 抖动动画
Observing	琥珀进度环（X/5 手）+ 观察行为
Cooldown	红色倒计时环（剩余/总）+ 收紧范围

玩家类型（VPIP 区间）

VPIP	类型	描述
< 15%	Nit	仅极窄范围
15–19%	Tight	选择性入池
20–24%	Standard	平衡
25–29%	Loose	偏宽
≥ 30%	Very Loose	入池过多

Tilt 检测系统（核心）

5 个独立检测器，分三层按优先级排列。

三层架构

Layer 1 情绪驱动（最高）
  Loss Chase danger → Style Drift danger

Layer 2 事件 + 情绪
  Big Pot danger → Loss Chase warning → Win Tilt → Big Pot warning

Layer 3 行为偏移（最低）
  Style Drift warning → VPIP Drift danger → VPIP Drift warning

设计原则

danger 保守：门槛高，不易触发，触发即严重。
warning 敏感：早期提醒，不进入冷静期。
仅 danger 进入冷静期；warning 只展示消息。
VPIP Drift：数量偏移（入池率整体变高）。
Style Drift：质量偏移（牌型质量变差）。

五个检测器

#	检测器	层级	触发条件（摘要）	级别
1	Loss Chase（追损）	情绪	输率 ≥ 60% 且 VPIP 飙升 ≥ 8%	warning / danger
2	Style Drift（风格失真）	行为	近期 ≥ 2/4 手异常牌型	warning / danger
3	Big Pot（大底池）	事件	单手 BB 绝对值 ≥ 100，按强弱牌与输赢分 4 场景	warning / danger
4	Win Tilt（顺风膨胀）	情绪	胜率 ≥ 60% 且 VPIP 扩大 ≥ 8%	warning only
5	VPIP Drift（入池漂移）	行为	30min VPIP 比生涯高 ≥ 10% / 18%（分档）	warning / danger

状态等级

Normal：无警报
Warning：教练消息卡片（flat border）
Danger：教练卡片 + 抖动动画

冷静期升级（Cooldown）

核心规则：仅 danger 触发冷静期；warning 不升级。

状态机

normal
  → danger 触发 → observing（5 手）
       → 未改善 → cooldown（10 手）→ normal
       → 改善   → normal

冷静期触发类型映射

检测器	级别	冷静期类型
Loss Chase	danger	lossBased（+5 手延长）
Style Drift	danger	driftBased（+5 手延长）
Big Pot（弱牌输）	danger	lossBased（+5 手延长）
VPIP Drift	danger	driftBased（+5 手延长）
Win Tilt	warning	不触发
Big Pot（其他）	warning	不触发

Deviation Check（isStillDeviating）

Signal A：最近 5 手 VPIP 率仍 ≥ baseline + 10%
Signal B：最近 5 手内 ≥ 2 手弱牌 / GTO 偏离
Signal C：（仅 lossBased / driftBased）≥ 2 次亏损且 ≥ 3 次 VPIP 入池

任一信号成立 = 仍在偏离 → 延长冷静期（最多 25 手）。

UI 文案要点

Observing：琥珀环 X/5，「观察中」
Cooldown：红色倒计时环，「冷静模式」+「收紧范围」徽章

设置与功能开关

通知 / Tilt 总控

开关	Key	默认	作用
Tilt Alert	`vt_tilt_enabled`	ON	总开关，关则所有检测器停用
Cooldown Mode	`vt_cooldown_enabled`	ON	冷静期升级系统
GTO Advice	`vt_gto_advice_enabled`	ON	选牌时翻前策略建议

单检测器（仅 Tilt Alert 开启时显示）

开关	Key	默认
Big Pot	`vt_bigpot_enabled`	ON
Loss Chase	`vt_losschase_enabled`	ON
Win Tilt	`vt_wintilt_enabled`	ON
Style Drift	`vt_styledrift_enabled`	ON
VPIP Drift	`vt_vpipdrift_enabled`	ON

其他

外观：System / Light / Dark
语言：English（默认）/ 中文
关于：版本、隐私政策、使用条款

本地化

应用内 L10n 枚举，非 iOS .strings 文件。
LanguageManager（@Observable）将语言偏好存 UserDefaults。
全视图使用 L10n.s(.key, lang) 模式；80+ key（文档称 90+）。
应用名 「VPCT」/「VPIP CONTROLLER」不翻译。

语言	Code	标签
English	`.english`	English
中文	`.chinese`	中文

Stats 页面

访问控制

用户状态	Stats
Guest	锁定，显示登录引导
已登录，< 10 手	空状态：「多打一些手牌」
已登录，≥ 10 手	完整统计

已登录用户内容（摘要）

头部：玩家类型徽章、lifetime VPIP、总手数
BB：总 BB、BB/100
GTO 合规：范围内比例、常见偏离、建议
Tilt：tilt session 次数、比例、平均时长

实现进度

已完成

SwiftData 模型（Player / Session / HandRecord）
Session 系统（开始、结束、进行中追踪）
手牌记录（Fold + VPIP 选牌）
VPIP 计算（session、30 分钟滚动、lifetime）
玩家类型分类
五检测器 tilt 系统（三层）+ danger-only 冷静期与触发类型
Big Pot（单手 ≥ 100BB，四场景）
设置中单检测器开关
应用内中英本地化（90+ keys）
Guest 架构、欢迎 / onboarding、Sign in with Apple UI
自定义扁平 TabBar（4 Tab）、iOS 18 扁平视觉
外观、语言、功能开关；session/手牌删除与统计重算
触觉反馈系统

待办

Sign in with Apple 后端认证
云端数据同步
隐私政策与使用条款（上架文案）
App Store 提审（当前：审核中）
TestFlight 公测

强弱牌参考（Tilt / Big Pot）

弱牌（Style Drift 追踪）

类别	示例
Weak Broadway	KTo, QTo, JTo
Weak Suited	K9s, Q9s, J8s
Gap Hands	K7s, Q8s, J7s
Marginal	A9o, K8o, Q7o
Connectors	T9o, 98o, 87o

若某弱牌历史盈利（≥ 2 次记录且总 BB > 0），则不算弱牌。

强牌（Big Pot Alert）

类别	示例
Premium Pairs	AA–99
Premium Suited	AKs, AQs, AJs, ATs, KQs, KJs
Premium Offsuit	AKo, AQo

文档版本

站内整理自 MVP 方案 v3.0 · 原稿更新 2026-03-22