读码笔记 card-system：发卡回调的锁行与双重幂等-星海夜航

card-system 是一款开源的 PHP 卡密商城系统（发卡平台，MIT 协议，3000+ star，当前版本 3.21）：卖家导入卡密、给商品定价，买家下单付款后系统自动占卡、邮件/短信通知发货。Laravel 写的，支付渠道独立成子模块仓库，CI、更新文档、发布包脚本齐全，同类项目里算做得最完整的之一。

是什么

功能面覆盖商城前台（Shop）、超级后台（Admin）、商户后台（Merchant），代码里就是三个控制器目录，权限分层直接体现在目录结构上。发货分三种：库存卡密自动发、手动发货、API 接口生卡。支付支持支付宝各形态、微信支付、QQ 钱包、易支付、PayPal、CoinPayments 等，更多渠道在配套的 card-gateway 仓库里，主仓库只负责调用。购买侧带优惠券（成交后券状态翻成已使用）和单品 buy_min/buy_max 限购。没做到的：实物物流、面向终端买家的 App；商户端资金对账的具体口径 README 没写，得自己读代码。

技术栈与部署

README 写明的环境：PHP 8.2+、Composer 2、MySQL 5.7+、Node.js 22+、npm、Git。源码安装，在项目根目录执行：

git submodule update --init --recursive
composer install
npm ci
npm run build

cp .env.example .env   # 填写数据库配置
php artisan key:generate
php artisan jwt:secret
php artisan migrate --seed

网站入口设为 public 目录。默认后台账号 admin@qq.com、密码 123456，README 要求立即改。开发时要开三个终端：php artisan serve（后端 8000）、npm run dev:admin（8081）、npm run dev:shop（8080），前端 API 代理地址由各自 .env.local 的 DEV_API_TARGET 控制。发布包用 composer build，产出 card-system-3.21.tar.gz。

值得抄的三点

一、锁行占卡防超卖。shipOrder 回调在事务里先对商品 lockForUpdate，再用 Card::whereRaw(‘count_sold < count_all’)->take($order->count)->lockForUpdate()->get() 取出够数的卡，成交后统一翻成已售、count_sold 用 DB::raw 做数据库侧自增。卡密是行级数据，去重靠表结构和状态字段，不靠字符串比对。订单号由 unique_no() 用「时间戳+随机串」生成，撞号就循环重生成；订单和卡的关系走中间表 attach，卡支持软删除，历史订单用 withTrashed 查询，卡被删了单还能还原发货内容。

二、双检幂等。事务外先判断订单是否 STATUS_UNPAY，进事务拿到行锁后再查一次状态，第二次支付回调进来直接什么都不做。金额校验只做单向：实收小于订单金额就拒绝，多收放行——代码注释写明部分渠道实际到账会略大于订单金额。

三、缺货保单不保发货。卡不够时不自动退款、不报错，订单标成 STATUS_PAID（已支付未发货），发货提示里写明缺几件、引导联系客服，商户后台手动补发。邮件/短信通知走队列异步发出，另用 send_status 字段记录每次通知成败，通知挂了不影响订单本身。

别踩的坑

一、支付网关和网关注册文件都在 git 子模块里，clone 后不执行 submodule init 就会付款环节报错。README 还强调更新流程：先备份数据库和 .env，更新后不要重跑初始化种子，不然演示数据会被塞回生产库。

二、改 .env 或后台站点设置后不生效，要依次跑 cache:clear、config:clear、route:clear 三个清理命令；开了后台登录验证码把自己锁在门外，得手动把 systems 表里 vcode_login_admin 的值改成 0 再清缓存。验证码接口出 500，多半是 PHP 的 gd、fileinfo 扩展没开。忘了后台密码不用动数据库，README 给了命令 php artisan reset:password 账号 ‘新密码’ 直接重置。

三、锁粒度在高并发下的表现，README 没给数字，得自己压测。