外观
商城与福利点券 · 技术实现
「玩家设定 →」
1. 代码位置
| 层 | 类 | 职责 |
|---|---|---|
| Controller | controller/ShopController（/api/shop） | overview / material-choice-box/buy / rainbow-stone/exchange / world-horn/exchange / naming-exclusive/buy / gold-exchange / mythic-stone/buy |
| Service | service/ShopService | 商城总览、神石兑换、材料自选箱、周限购、神话石直购 |
| Service | service/ShopMaterialChoiceService | 材料自选箱结算 |
| domain | domain/ShopBalanceRules | 福利点券/神石/卡片常量与额度公式 |
| domain | domain/MaterialChoiceBoxType、domain/MaterialChoiceType | 材料自选箱类型 |
| domain | domain/GoldExchangeRules | 打金兑换商品（灵金/黄金/元宝 → 神石）与神话石直购单价 |
2. 数据表
| 表 | 关键列 | 说明 |
|---|---|---|
player_weekly_shop_purchase | player_id、week、product_id、quantity | 商城周限购（V31） |
inventory_item | player_id、item_id、quantity | 福利点券/神石持有（V1） |
player_privilege | player_id、vip_level、total_recharge | 额度公式输入（V8） |
3. 配置与常量
- 商城常量：
名称 数值 说明 welfareTicketIdWELFARE_TICKET_ID 4001L — rainbowStoneIdRAINBOW_STONE_ID 4002L — monthlyCardIdMONTHLY_CARD_ID 4003L — namingCardIdNAMING_CARD_ID 4004L — lifetimeCardIdLIFETIME_CARD_ID 4005L — welfareTicketNameWELFARE_TICKET_NAME "福利点券" — dailySignInRewardTicketsDAILY_SIGN_IN_REWARD_TICKETS 1_000 — rainbowStoneNameRAINBOW_STONE_NAME "五彩神石" — monthlyCardNameMONTHLY_CARD_NAME "月卡" — namingCardNameNAMING_CARD_NAME "冠名卡" — lifetimeCardNameLIFETIME_CARD_NAME "终身卡" — namingNameNAMING_NAME "冠名" — dailyWelfareChallengeLimitDAILY_WELFARE_CHALLENGE_LIMIT 100 — rainbowStonePriceRAINBOW_STONE_PRICE 100 — baseDailyStoneLimitBASE_DAILY_STONE_LIMIT 50 — monthlyCardExtraStoneLimitMONTHLY_CARD_EXTRA_STONE_LIMIT 50 — namingExtraStoneLimitNAMING_EXTRA_STONE_LIMIT 400 — lifetimeCardSweepQuotaBonusLIFETIME_CARD_SWEEP_QUOTA_BONUS 10 — serverDailyStoneLimitSERVER_DAILY_STONE_LIMIT 600 — worldHornLimitIdWORLD_HORN_LIMIT_ID 9501L 世界喇叭福利点券兑换（对齐 docs/33 §4.2） worldHornLimitNameWORLD_HORN_LIMIT_NAME "世界喇叭日限购" — worldHornPriceWORLD_HORN_PRICE 100 — dailyWorldHornLimitDAILY_WORLD_HORN_LIMIT 10 — rainbowStoneResonanceRatePerStoneRAINBOW_STONE_RESONANCE_RATE_PER_STONE 0.0004D VIP7 最终 ×1.5、VIP8 基础 +1 / 最终 ×1.5；VIP9/10 数值权益并入 VIP8。 vip5GrowthThresholdVIP5_GROWTH_THRESHOLD 5 — vip6GrowthThresholdVIP6_GROWTH_THRESHOLD 6 — vip7GrowthThresholdVIP7_GROWTH_THRESHOLD 7 — vip8GrowthThresholdVIP8_GROWTH_THRESHOLD 8 — monthlyCardGrowthBaseContributionMONTHLY_CARD_GROWTH_BASE_CONTRIBUTION 1 — vip5GrowthBaseContributionVIP5_GROWTH_BASE_CONTRIBUTION 1 — vip6GrowthBaseContributionVIP6_GROWTH_BASE_CONTRIBUTION 1 — vip8GrowthBaseContributionVIP8_GROWTH_BASE_CONTRIBUTION 1 — namingGrowthBaseContributionNAMING_GROWTH_BASE_CONTRIBUTION 1 — lifetimeCardGrowthBaseContributionLIFETIME_CARD_GROWTH_BASE_CONTRIBUTION 1 — monthlyCardFinalMultiplierMONTHLY_CARD_FINAL_MULTIPLIER 1.2D — lifetimeCardFinalMultiplierLIFETIME_CARD_FINAL_MULTIPLIER 1.2D — vip5FinalMultiplierVIP5_FINAL_MULTIPLIER 1.2D — vip7FinalMultiplierVIP7_FINAL_MULTIPLIER 1.5D — vip8FinalMultiplierVIP8_FINAL_MULTIPLIER 1.5D — namingFinalMultiplierNAMING_FINAL_MULTIPLIER 2.0D — baseGrowthRateBASE_GROWTH_RATE 5.0D — monthlyCardAttackSpeedBonusMONTHLY_CARD_ATTACK_SPEED_BONUS 2.0D — lifetimeCardAttackSpeedBonusLIFETIME_CARD_ATTACK_SPEED_BONUS 2.0D — namingAttackSpeedBonusNAMING_ATTACK_SPEED_BONUS 3.0D — namingExtraTicketsNAMING_EXTRA_TICKETS 500 — mountDropRateMOUNT_DROP_RATE 0.001D 坐骑掉率，对齐进阶石 mountMaterialQtyEasyMOUNT_MATERIAL_QTY_EASY 50 坐骑/翅膀副本升级材料按怪物分级掉落（百次模型，NORMAL 100 颗/次） mountMaterialQtyNormalMOUNT_MATERIAL_QTY_NORMAL 100 — mountMaterialQtyHardMOUNT_MATERIAL_QTY_HARD 150 — mountMaterialQtyEliteMOUNT_MATERIAL_QTY_ELITE 200 — mountMaterialQtyBossMOUNT_MATERIAL_QTY_BOSS 250 — entryDungeonMaterialMultiplierENTRY_DUNGEON_MATERIAL_MULTIPLIER 0.40D — wingDropRateWING_DROP_RATE 0.001D 翅膀副本掉落与升级消耗（对齐 docs/翅膀玩法设计文档.md §5），数值镜像坐骑。 petDropRatePET_DROP_RATE 0.001D — materialDungeonVipBonusPerRunMATERIAL_DUNGEON_VIP_BONUS_PER_RUN 0.5D VIP5+ 每场 +50% materialDungeonMonthlyBonusPerRunMATERIAL_DUNGEON_MONTHLY_BONUS_PER_RUN 0.5D 月卡 每场 +50% materialDungeonNamingBonusPerRunMATERIAL_DUNGEON_NAMING_BONUS_PER_RUN 1.0D 冠名 每场 +100% materialDungeonMaxRewardMultiplierMATERIAL_DUNGEON_MAX_REWARD_MULTIPLIER 3.0D — materialDungeonTierEasyFactorMATERIAL_DUNGEON_TIER_EASY_FACTOR 0.25D 更高难度（BOSS）有真实溢价，更低难度（EASY/NORMAL/HARD）产出下降，纠正"所有难度一样"的体验。 materialDungeonTierNormalFactorMATERIAL_DUNGEON_TIER_NORMAL_FACTOR 0.5D — materialDungeonTierHardFactorMATERIAL_DUNGEON_TIER_HARD_FACTOR 0.75D — materialDungeonTierEliteFactorMATERIAL_DUNGEON_TIER_ELITE_FACTOR 1.0D — materialDungeonTierBossFactorMATERIAL_DUNGEON_TIER_BOSS_FACTOR 1.25D — welfareBaseTicketsWELFARE_BASE_TICKETS 10 福利怪掉落规则（加法模型，可叠加） monthlyCardExtraTicketsMONTHLY_CARD_EXTRA_TICKETS 100 — maxVipLevelMAX_VIP_LEVEL 10 — maxVipBenefitLevelMAX_VIP_BENEFIT_LEVEL 8 承载数值权益的最高 VIP 等级（docs/64 §1.3）：VIP1-8 承载全部成长、战斗、材料、 额度、次数与便利加成，VIP9/10 是荣誉等级、不再提供任何数值权益。 所有依赖 VIP 等级的数值权益一律用 {@link #effectiveVipLevel(int)} 取等级。 vipThresholdsVIP_THRESHOLDS { 0, 600, 3_000, 6_800, 12_800, 25_800, 64_800, 150_000, 300_000, 500_000, 1_000_000 } VIP0 vipWelfareTicketBonusVIP_WELFARE_TICKET_BONUS {0, 10, 10, 35, 35, 75, 110, 150, 200} VIP1-8 固定档位加成（docs/64 §1.3）：索引即 VIP 等级，VIP2/VIP4 不重复加成， 累计值 = 本级数组值（VIP8 封顶 +200）。 vipStoneLimitBonusVIP_STONE_LIMIT_BONUS {0, 10, 10, 35, 35, 75, 110, 150, 200} — vipAttackSpeedBonusVIP_ATTACK_SPEED_BONUS {0.0D, 0.10D, 0.10D, 0.35D, 0.35D, 0.75D, 1.10D, 1.50D, 2.00D} — 来源：emberfall-server/src/main/java/com/emberfall/domain/ShopBalanceRules.java· commit22d062aff99fabdc373f3b1c82b2a6eff4a034d3- 货币：
WELFARE_TICKET_ID=4001（福利点券）、RAINBOW_STONE_ID=4002（五彩神石）、RAINBOW_STONE_PRICE=100 - 福利怪掉落：基础 10 + VIP 每级 20 + 月卡 100 + 冠名 500（
ticketsPerChallenge），每日挑战上限 100（DAILY_WELFARE_CHALLENGE_LIMIT） - 每日神石额度：基础 50 + 月卡 50 + VIP 每级 20 + 冠名 300，封顶 600
- 神石共鸣：
RAINBOW_STONE_RESONANCE_RATE_PER_STONE=0.0004（每颗 +0.04% 成长速率）
- 货币：
- 兑换（
GoldExchangeRules）：神话石福利点券直购 200（MYTHIC_STONE_WELFARE_TICKET_PRICE，不限购，ShopService.buyMythicStoneWithWelfareTicket不做额度校验）、灵金 20 万、黄金/元宝各 2 万；五彩神石 2 万灵金（限购 7×10）；材料包日限 10/30 - 神话石效果（
MythStoneRules）：MAX_PCT=10.0、K=25_000，面板加成pct(S)=MAX_PCT×S/(S+K)（渐近 +1000%）；展示字段currentPercent / nextStonePercent / maxPercent / todayGained由ShopService.buildMythicStoneInfo填充（今日产出 = 试炼 9301 日池 + 打金 9203 兑换池已产出） - yml 键：无（注意
trial.v2.cycle.welfare-ticket-item-id: 4001共享福利点券）
4. 数据流简述
GET /api/shop/overview 按 PlayerPrivilege 计算各商品价格与每日/每周额度。POST /api/shop/rainbow-stone/exchange 以福利点券 4001 按 100 单价兑换五彩神石，扣减福利点券、校验 dailyStoneLimit（额度公式封顶 600）后发放。POST /api/shop/gold-exchange/buy 按 GoldExchangeRules 用灵金/黄金/元宝兑换神石与材料包，周限购写 player_weekly_shop_purchase。持有神石数量进入 GrowthPolicyService 共鸣计算（每颗 +0.04%）。
POST /api/shop/mythic-stone/buy（ShopService.buyMythicStoneWithWelfareTicket）：以 consumeItem(playerId, WELFARE_TICKET_ID, 200 × 数量) 原子条件扣减福利点券，失败抛 BusinessException(7023, "福利点券不足") 并整体回滚；成功后 addItem(MYTHIC_STONE_ID) 发放并 invalidatePlayerInfoCache(playerId)（神话石持有即生效，面板需即时刷新）。无每日限购池校验。
5. 已知差异
（神话石直购 500 → 200/颗、取消每日限购；效果由「每颗 +1% 无上限」改为双曲渐近曲线，渐近上限 +1000%）（神话石直购货币由点券改为福利点券：buyMythicStoneWithPoints → buyMythicStoneWithWelfareTicket，MYTHIC_STONE_POINT_PRICE → MYTHIC_STONE_WELFARE_TICKET_PRICE，扣减由 deductCreditIfEnough 改为 consumeItem(4001, ...)；GameRepository.deductCreditIfEnough 已删除；DTO 字段 creditBalance → welfareTicketBalance、pointMythicStoneInfo → mythicStoneInfo；URL /api/shop/mythic-stone/buy 不变。点券为充值货币且本项目无充值通道，全库角色点券恒为 0，原出口不可能成交。）6. 相关代码
- VIP（
ShopBalanceRules：额度公式） - 打金（
GoldExchangeRules：兑换商品） - 交易行（
TradeRules.CURRENCY_ITEM_ID=4001：福利点券作货币） - 每日签到（
DAILY_SIGN_IN_REWARD_TICKETS=1000）