跳到主要内容

PRD-050 帮会竞拍分红

文档编号：PRD-050
版本：v1.0
状态：已通过
适用端：服务端 / 客户端
脚本挂载：lua/guild/guild_auction.lua

1. 背景与目标​

帮会活动产出的稀有物品通过内部竞拍分配，收益按贡献分红。竞拍规则、分红比例、流拍处理适合用 Lua 编排。

目标

  • 帮会 BOSS/活动掉落的稀有物品进入帮会竞拍。
  • 成员用帮会贡献/金币竞价，价高者得。
  • 成交金额按贡献比例分给参与成员，流拍进入帮会仓库。

2. 核心规则​

  • 竞拍由帮主/副帮主开启，持续 30 分钟。
  • 竞拍物品来自帮会活动掉落，绑定物品不可竞拍。
  • 起拍价、加价幅度由物品品质决定。
  • 竞价冻结货币，被超价解冻。
  • 成交后物品邮件发给买家，金额按“参与度 + 贡献”分红。
  • 流拍物品进入帮会仓库，下次活动重新上架。

3. 服务端设计​

3.1 Lua 脚本设计​

-- lua/guild/guild_auction.lua
GuildAuction = {
    duration = 1800,
    min_increment = 100,
    dividend_rate = 0.9, -- 90% 分红，10% 帮会资金
}

function OnAuctionStart(ctx, guild, item)
    local order = ctx:CreateGuildAuction(guild, item)
    ctx:BroadcastGuild(guild, "帮会竞拍开始：" .. item.name)
    ctx:SetTimer("auction_end_" .. order.id, GuildAuction.duration, function()
        OnAuctionEnd(ctx, order.id)
    end)
end

function OnBid(ctx, role, order_id, price)
    local order = ctx:GetAuction(order_id)
    if price < order.current + GuildAuction.min_increment then
        return ctx:Fail(role, "加价不足")
    end
    if not ctx:FreezeMoney(role, price) then
        return ctx:Fail(role, "货币不足")
    end
    ctx:RefundMoney(order.last_bidder, order.current)
    ctx:UpdateAuction(order, role, price)
end

function OnAuctionEnd(ctx, order_id)
    local order = ctx:GetAuction(order_id)
    if not order.bidder then
        ctx:MoveToGuildWarehouse(order.item)
    else
        ctx:DeliverToBidder(order)
        ctx:DistributeDividend(order, GuildAuction.dividend_rate)
    end
    ctx:CloseAuction(order)
end
  • 竞拍状态、冻结货币、分红明细持久化。
  • 分红按成员贡献度/参与次数权重，脚本计算。
  • 流拍物品进入帮会仓库，脚本记录来源。

3.2 协议​

方向协议说明
S→CSC_GuildAuctionInfo物品/当前价/倒计时
C→SCS_GuildAuctionBid出价
S→CSC_GuildAuctionResult成交/流拍/分红

3.3 权限与风控​

  • 仅帮主/副帮主可开启/提前结束。
  • 帮主可设置是否允许自己竞价（默认允许）。
  • 同一买家/卖家频繁交易触发风控。
  • 竞价冻结/退款/分红全部事务化。

4. 客户端设计​

  • 帮会竞拍页：物品、当前价、加价按钮、倒计时。
  • 出价弹窗显示冻结金额与余额。
  • 分红明细：总金额、帮会资金、个人分红。
  • 流拍提示与仓库入口。
  • 竞拍历史。

5. 配置与 Lua 接口​

配置说明
duration竞拍时长
min_increment最小加价
dividend_rate分红比例
start_price起拍价规则
warehouse流拍去向

Lua 接口：CreateGuildAuction、FreezeMoney、RefundMoney、UpdateAuction、DistributeDividend、MoveToGuildWarehouse。

6. 边界与异常​

场景处理
竞拍中帮会解散取消竞拍，退还冻结货币
买家退会仍可成交，物品邮件发放
分红时成员离线邮件发放
重复结算幂等
服务器重启从 DB 恢复竞拍
脚本异常取消竞拍，全额退款

7. 验收标准​

  • 开启/出价/冻结/退款/成交/流拍/分红正确。
  • 分红比例与明细可追溯。
  • 权限、退会、解散处理正确。
  • 事务一致，无重复扣款/发奖。
  • 脚本可调整时长/加价/分红。