★ FEATURED ARTICLE 上周末我们俱乐部办了场十二支队伍参与的队式桥牌赛四轮瑞士移位我在计分台边看裁判用纸质成绩单和 Excel 来回倒腾七八个标签页还是容易把 IMP 和 VP 算岔。回来的路上我就在琢磨这种比赛计分能不能做成一个微信小程序后端用 Flask 自动算分、实时刷新排名说干就干于是就有了这套 Python 微信小程序 Flask 的桥牌游戏比赛计分系统。这套系统解决的是最实际的三个问题分数录入效率低、IMP/VP 转换容易出错、排名发布不及时。裁判在手机上录入每桌每副牌的分数后端自动完成复式桥牌的横向比较、IMP 转换和 VP 累计所有队伍成绩实时可见。适合想快速搭建赛事管理工具的开发者、俱乐部赛事组织者也适合正在学 Flask 或小程序开发、想找一个完整项目练手的同学。1. 项目整体设计与选型思路1.1 桥牌比分系统到底在解决什么问题很多人以为桥牌计分就是记个定约和结果其实远没那么简单。复式桥牌比赛里同一副牌会在不同桌上被多次打出计分员需要记录的是每桌、每副牌的最终净得分比如南北 420、东西 -420。然后系统要把同一副牌在不同桌上的结果进行横向比较计算出每桌之间的 IMP 差再按轮次累加成净 IMP最后转换成 VP形成队伍排名。这中间最烦人的就是转换表。IMP 表有二十多档阈值VP 表又跟着轮次副数变手算很容易出错。更麻烦的是一场比赛几十副牌每副都要重复这套逻辑工作量全耗在机械计算上了。所以系统的第一目标就是把“记录”和“计算”彻底分开录入只管录入算分全部交给后端。1.2 为什么选了 Flask 而不是 Django后端选型时我其实纠结过 Django。Django 自带 Admin 后台和 ORM做这种管理系统确实省事但考虑到比赛系统接口不多、逻辑集中在计分计算这一个核心点上Django 的框架重量反而成了负担。Flask 轻量、灵活路由和蓝图组织起来很清晰一个 app 文件加几个模块就能跑起来部署也简单一个 gunicorn 进程就能抗住小型比赛的并发量。再一个原因是团队或自己后续改起来快。Flask 的请求生命周期和视图函数逻辑一目了然新增一个“删掉某条错误成绩”的接口十行代码搞定。微信小程序端只关心 HTTP 接口不关心后端用什么框架所以后端怎么轻怎么来。1.3 功能模块划分整个系统我拆成了四个模块比赛管理创建比赛、配置轮次和每轮副数。成绩录入按轮次和桌号录入南北/东西队的分数。自动计算同一副牌的跨桌比较、IMP 转换、VP 累计。排名展示按 VP 排序附带净 IMP 作为并列排名参考。这样的划分让前后端接口非常干净。小程序端每个页面只对应用户的一个操作场景后端每个接口只处理一类数据调试时定位问题特别快。2. 核心计分逻辑拆解2.1 复式赛制的计分流程复式桥牌的规则要点是同组牌在不同桌上使用相同牌型这样才能排除牌运因素纯粹比较打牌水平。计分系统要做的就是基于这个前提做对比。具体流程是这样的录入手表每桌打完一副牌裁判录入南北队的定约和结果系统换算成净得分比如 420、-50。工程里我让裁判直接录净得分不做定约解析因为定约到得分的映射规则虽然固定但写一套解析器并不划算直接录分反而减少输入步骤。同牌比较找到另一桌打同一副牌的队伍比较南北方向或东西方向的净得分差。计算 IMP把上一步的分数差代入 IMP 转换表得到该副牌的 IMP 净差。累计净 IMP把一轮内的所有副牌 IMP 加起来得到每两支队伍交锋的本轮 IMP 净差。转换 VP将本轮净 IMP 按 VP 表转为本次交锋的 VP 得分。汇总排名所有轮次的 VP 相加得到总排名。这套流程里最需要小心的是第 2 步。不同桌上坐南北方向的队伍可能不同东西方向的队伍也可能不同所以“两队交锋”必须通过桌号和轮次来具体定位不能想当然地按南北队为一方、东西队为另一方来算。我在设计数据表时专门给每条成绩记录加了 round_no 和 board_no 两个字段确保能精确匹配到对应的比较对象。2.2 IMP 与 VP 的转换实现IMP 转换是这套系统计算功能的核心实现不复杂但阈值表必须背准。我用一个列表按从小到大排列阈值这样写既直观又不会漏档# score_engine.py IMP_TABLE [ (0, 0), (20, 1), (50, 2), (90, 3), (130, 4), (170, 5), (220, 6), (270, 7), (320, 8), (370, 9), (420, 10), (500, 11), (600, 12), (750, 13), (900, 14), (1100, 15), (1300, 16), (1500, 17), (1750, 18), (2000, 19), (2250, 20), (2500, 21), (3000, 22), (3500, 23), (4000, 24) ] def score_diff_to_imp(diff: int) - int: diff abs(diff) for limit, imp in IMP_TABLE: if diff limit: return imp return 24 def compute_imp(ns_score_a: int, ns_score_b: int) - int: diff ns_score_a - ns_score_b imp score_diff_to_imp(diff) return imp if diff 0 else -imp这里有个容易踩的坑IMP 表不是“分数差越大档位越高”的均匀递增而是分段取整。比如分数差 190 和 210 都算 5 IMP但 220 就算 6 IMP 了。所以写代码时不要用除法或比例去近似必须老老实实查表。VP 转换我采用的是常见的 20 副牌连续 VP 表净 IMP 为 0 时双方各得 15 VP每多 1 IMP 胜方加 1 VP负方减 1 VP上限是 25-5 封顶def imp_to_vp(net_imp: int) - tuple[int, int]: if net_imp 10: return (25, 5) if net_imp -10: return (5, 25) winner_vp 15 abs(net_imp) loser_vp 15 - abs(net_imp) if net_imp 0: return (winner_vp, loser_vp) return (loser_vp, winner_vp)不同比赛规则可能用不同的 VP 表比如 8 副、16 副、20 副各有对应版本。所以我在系统里把 VP 表做成了后台配置项不同比赛可以加载不同的表避免为了某一场比赛去改代码。2.3 必须处理的边界情况实际比赛中边界情况比想象中多。这里列几个我测试时反复出问题的场景空成绩某轮某桌因为特殊原因没有打完数据库里可能没有这条记录。计算排名时比较逻辑需要跳过缺失的牌副否则会报 KeyError 或把缺失当成 0 分导致结果完全错误。调整分仲裁委员会调整过的分数没有对应的另一桌成绩。这种分数在录入时要打上标记不参与副牌横向比较但计入总 VP。负分差南北队打成 -420 的情况很常见compute_imp 里的正负号处理是核心返回负 IMP 表示这方净负。并列名次多支队伍 VP 相同排名要用净 IMP 做次关键字排序再不行比胜负关系。这个在小程序展示页和数据库查询里都要提前设计好。3. Flask 后端与数据库设计3.1 数据模型与表结构我用了很直观的四张表比赛表、队伍表、交锋表、成绩明细表。重点说下成绩明细表它是所有计算的数据源头# models.py from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() class Match(db.Model): __tablename__ matches id db.Column(db.Integer, primary_keyTrue) name db.Column(db.String(64), nullableFalse) rounds db.Column(db.Integer, default4) boards_per_round db.Column(db.Integer, default8) vp_table_id db.Column(db.Integer, default1) created_at db.Column(db.DateTime, defaultdb.func.now()) class Team(db.Model): __tablename__ teams id db.Column(db.Integer, primary_keyTrue) name db.Column(db.String(64), nullableFalse) match_id db.Column(db.Integer, db.ForeignKey(matches.id)) class RoundMatch(db.Model): __tablename__ round_matches id db.Column(db.Integer, primary_keyTrue) match_id db.Column(db.Integer, db.ForeignKey(matches.id)) round_no db.Column(db.Integer) home_team_id db.Column(db.Integer, db.ForeignKey(teams.id)) away_team_id db.Column(db.Integer, db.ForeignKey(teams.id)) net_imp db.Column(db.Integer, default0) home_vp db.Column(db.Float, default15) away_vp db.Column(db.Float, default15) class ScoreRecord(db.Model): __tablename__ score_records id db.Column(db.Integer, primary_keyTrue) match_id db.Column(db.Integer, db.ForeignKey(matches.id)) round_no db.Column(db.Integer) table_no db.Column(db.Integer) board_no db.Column(db.Integer) ns_team_id db.Column(db.Integer, db.ForeignKey(teams.id)) ew_team_id db.Column(db.Integer, db.ForeignKey(teams.id)) ns_score db.Column(db.Integer) # 南北净得分可正可负 ew_score db.Column(db.Integer) # 东西净得分一般等于 -ns_score is_adjusted db.Column(db.Boolean, defaultFalse)这里有个设计细节RoundMatch 表里直接存放了 net_imp 和双方 VPScoreRecord 表只负责记录原始分数。这样排名查询就很轻量不用每秒钟跑一遍全部计算。代价是每次录入一条分数后要触发一次当前交锋的重算这个可以通过在 Flask 的录入接口内部调用更新函数来解决。3.2 计分核心函数与计算时机我写了一个重算函数专门处理某一场比赛、某一轮次下的所有 ScoreRecord更新 RoundMatch 表。这个函数在新增成绩、修改成绩、删除成绩三个动作后都会被调用。# services/score_service.py from score_engine import compute_imp, imp_to_vp def recalculate_round(match_id: int, round_no: int): # 先清理旧的交锋记录重新聚合 RoundMatch.query.filter_by(match_idmatch_id, round_noround_no).delete() # 对每个队伍两两交锋遍历这一轮里同桌同副的分数 scores ScoreRecord.query.filter_by( match_idmatch_id, round_noround_no ).all() grouped {} for rec in scores: key (rec.table_no, rec.board_no) grouped.setdefault(key, []).append(rec) # key 对应的两条记录就是同一副牌同两队在不同方向的结果 for (table_no, board_no), recs in grouped.items(): if len(recs) 2: continue # 缺一条记录就跳过该副牌 rec_a, rec_b recs[0], recs[1] net_imp compute_imp(rec_a.ns_score, rec_b.ns_score) # 归集到对应的 RoundMatch # 这里简化为查找或创建交锋记录后累加 # 全部牌副处理后按净 IMP 转 VP 并落库这段伪代码的关键在于 recs[0] 和 recs[1] 代表了同一副牌两桌的比赛结果。实际开发中还要处理一桌只录了一条成绩的情况所以 len(recs) 2 直接跳过是最安全的写法。计算时机上我踩过一个坑一开始想在查询排名时实时算结果比赛进行中数据一多接口响应直接从 30ms 变成 2 秒。后来改成写操作后异步重算查询接口只读库响应时间立刻降回去了。小型比赛根本不需要消息队列直接在录入接口里同步调用重算就行一台跑 Flask 的轻量服务器完全扛得住。3.3 对外 API 设计接口我保持尽量精简前后端只靠 JSON 通信GET /api/matches 比赛列表 POST /api/matches 创建比赛 GET /api/matches/id/teams 队伍列表 POST /api/score_records 新增一条成绩 PUT /api/score_records/id 修改成绩 DELETE /api/score_records/id 删除成绩 GET /api/matches/id/standings 获取排名 GET /api/matches/id/rounds/round 获取某轮明细这里有个设计原则录入接口接收的是原始分数不接收 IMP 或 VP。前端不需要懂桥牌规则只需要把数字填对至于这些数字换算成什么完全由后端统一处理。这样做还有一个好处如果桥牌规则更新了转换表只需要改后端小程序不需要发版。Flask 的视图函数我放在了蓝图里按 match、score、standing 三个蓝图组织。返回统一格式{code: 0, data: ...}错误时{code: 40001, msg: ...}小程序端判断 code 字段就可以了。4. 微信小程序端实现4.1 页面组成与交互流程小程序端我规划了四个页面对应不同角色在使用时的核心场景比赛列表页展示所有已创建的比赛用户点进去就是比赛详情。成绩录入页选择轮次、桌号、南北队、东西队输入南北净得分提交送后端。排名页展示当前比赛的队伍排名按 VP 排序实时刷新。成绩明细页按轮次查看每副牌的录入情况和 IMP 结果方便裁判校对。录入页是整个系统里最重要的一页交互设计上我把“提交”按钮放在页面底部并且做了输入校验分数必须是数字且不能为空南北队和东西队不能选同一个队。微信小程序的表单校验如果纯粹靠 WXML 内置规则不够灵活我是直接在事件处理函数里判断的// pages/score/score.js submitScore() { const { matchId, roundNo, tableNo, boardNo, nsTeamId, ewTeamId, nsScore } this.data if (!matchId || !roundNo || !tableNo || !boardNo) { wx.showToast({ title: 请选全比赛信息, icon: none }) return } if (!nsTeamId || !ewTeamId || nsTeamId ewTeamId) { wx.showToast({ title: 南北和东西不能同一队, icon: none }) return } if (nsScore ) { wx.showToast({ title: 请输入南北净得分, icon: none }) return } // 提交 }4.2 请求封装与登录态小程序里所有接口调用我统一封装在 utils/request.js 里避免每个页面都重复写 wx.request。封装时要注意两点超时时间要设置默认值 60 秒太长了接口一般在数据量大时也就几百毫秒超时设 10 秒足够另外要对非 2xx 状态码统一做错误提示避免页面里到处 try catch。登录态这块桥牌比赛计分系统属于内部工具型小程序我没有做完整的多用户权限系统只保留了最基础的 openid 识别。用户首次进入时调用 wx.login 拿到 code后端通过 code 向微信服务器换取 openid之后用它匹配“裁判”身份。如果只是俱乐部内部用甚至可以不做登录直接通过比赛口令进入省掉一套账号体系。// utils/request.js const BASE_URL https://bridge.example.com/api function request(path, method GET, data {}) { return new Promise((resolve, reject) { wx.request({ url: BASE_URL path, method, data, timeout: 10000, header: { Content-Type: application/json }, success: (res) { if (res.statusCode 200 res.statusCode 300) { resolve(res.data) } else { wx.showToast({ title: 请求失败 res.statusCode, icon: none }) reject(res) } }, fail: (err) { wx.showToast({ title: 网络异常, icon: none }) reject(err) } }) }) } module.exports { request, BASE_URL }4.3 成绩录入和排名展示的实现要点成绩录入页用了三个 picker 分别选择轮次、南北队和东西队。南北队和东西队的列表来自同一份队伍数据但选择时会校验不能重复。净得分输入框我用的 typenumber同时允许输入负号这在微信小程序里需要额外注意因为数字键盘默认没有负号键。我最终选择了 typetext 配合正则校验保证负数也能正常输入。排名页的核心就是一个带 tab 的 scroll-view纵向展示所有队伍每行显示名次、队伍名、VP、净 IMP。为了让数据刷新不那么生硬我在 onShow 里重新拉取排名接口这样裁判每次录完分切回排名页看到的就是最新结果体验上很流畅。如果比赛数据量大还可以加一个简单的下拉刷新。!-- pages/rank/rank.wxml -- view classrank-header text名次/text text队伍/text textVP/text text净IMP/text /view scroll-view scroll-y classrank-list view classrank-row wx:for{{rankList}} wx:keyteam_id text{{index 1}}/text text{{item.team_name}}/text text{{item.vp}}/text text{{item.net_imp}}/text /view /scroll-view这个页面的数据绑定完全依赖后端返回的排序结果。我后端排序时先按 VP 降序再按净 IMP 降序所以小程序端拿到什么就渲染什么不需要做二次处理。5. Flask 部署与实战排错5.1 生产环境部署要点Flask 自带的开发服务器只能用于调试生产环境我用的 gunicorn nginx 组合。部署在腾讯云轻量服务器上2C4G 配置跑这种小型比赛计分系统绰绰有余。关键步骤安装依赖建议用 venv 隔离环境避免污染系统 Python。启动 gunicorn绑 127.0.0.1:8000后端接口不直接对公网开放。nginx 反向代理监听 443 端口做 HTTPS 终止把 /api 路径转发到 gunicorn。配置域名微信小程序要求所有请求域名必须备案且在公众平台配置好 request 合法域名。# 启动命令4 个 worker 足够 gunicorn -w 4 -b 127.0.0.1:8000 run:appserver { listen 443 ssl; server_name bridge.example.com; ssl_certificate /etc/nginx/ssl/bridge.pem; ssl_certificate_key /etc/nginx/ssl/bridge.key; location /api { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }数据库我用的是 SQLite 开发调试生产环境切到了 MySQL。Flask 的 SQLAlchemy 在这两种数据库之间的兼容性很好只要注意不要用数据库特有的函数迁移基本零成本。考虑到比赛数据量很小其实 SQLite 配 WAL 模式也能支撑几百人的比赛但 MySQL 至少让我在并发写入时更安心。5.2 常见问题与排查速查表开发过程中我整理了一张排查表很多问题都是真实碰到的现象可能原因解决办法真机请求报 request:fail域名未配置或未启用 HTTPS在微信公众平台配置合法域名注意必须 HTTPS开发工具正常、真机失败开发者工具勾选了“不校验合法域名”真机上没有这个选项检查自己的域名备案和证书录入成绩后排名没更新重算逻辑没有被调用检查新增/删除接口里是否都调用了 recalculate_round某副牌分数差异大但 IMP 没变IMP 表档位判断错误打印分数差和转换后的 IMP和官方表对照队伍 VP 出现小数VP 表里用了非整数配置确认数据表字段类型不要用 Integer 存 VPpicker 选择队伍时报错队伍列表没绑定 matchId进入录入页时先请求当前比赛的队伍列表我自己卡得最久的一个问题是 MySQL 下 ScoreRecord 表忘了加索引导致比赛录到第二轮后重算函数查成绩记录越来越慢。后来加了(match_id, round_no, board_no)复合索引重算从 1 秒降到 20ms 左右体感提升非常明显。5.3 一些避坑心得开发这套系统的过程中最大的体会是“计算逻辑要集中不要散落到各个接口里”。我第一版代码把 IMP 转换直接写进了 POST 接口后来加一个批量导入功能时发现没法复用又重构了一遍费了不少力气。第二版把计分函数抽到 score_engine.py所有接口统一调后面加什么都不慌。另一个心得是前端不要做任何计分逻辑连 IMP 转换里“分数差 20 到 40 算 1 IMP”这种常识都不要写进小程序代码。因为如果前后端各写一套规则规则一旦更新就是一场灾难。我的做法是后端算好直接返回展示字段小程序只负责把数字渲染出来。最后说一个已经验证过的扩展方向这套系统的核心并不是桥牌专用的“IMP/VP”公式而是“录入原始成绩 → 横向比较 → 转换积分 → 排名展示”这个流程。把它抽成通用的比赛积分引擎后同样的代码可以支撑围棋、象棋这类复式赛制的积分编排。桥牌比赛计分只是第一个落地场景底层流程改一改就能变成通用赛事工具。个人建议不要把代码写死在桥牌业务上哪怕只是把转换表和计算引擎拆成独立模块后续扩展都会轻松很多。
阅读完成 · 觉得有帮助？
