qipai/README.md

自助棋牌室系统

本仓库是 panda/qipai.git 的单一 Monorepo 工作区。Windows 固定开发路径为 D:\qipai，当前权威开发总纲为 V5.2.md。详细功能、模块顺序、验收标准和 Codex 纪律以总纲及 docs/ 为准。

固定约束

• 当前权威总纲：V5.2.md
• 固定远端：ssh://git@git.txyundm.cn:2222/panda/qipai.git
• 默认分支：main
• 生产 API：https://api.txyundm.cn
• 小程序 API：https://api.txyundm.cn/app-api
• 后台 API：https://api.txyundm.cn/admin-api
• 后台 Web：https://api.txyundm.cn/admin/
• 正式 MQTT Broker：101.42.38.246:1883
• 生产系统：Ubuntu Server 24.04 x86-64/amd64，无桌面、无 Docker、无微信云开发
• 后端运行时：Node.js 20+、npm 10+
• 部署入口：Ubuntu 执行 sudo bash /opt/apps/setup.sh
• 开发流程：Windows 本地开发与测试 → 完成一个模块 → 更新文档 → commit → SSH push origin/main

目录

• backend/：Fastify + TypeScript 后端 API；若实际后端位于仓库根目录，以 docs/repository-map.md 为准
• admin/：Vue3 后台管理端，必须适配桌面、平板和手机
• miniapp/：微信原生小程序
• database/：迁移、种子和兼容 SQL
• deploy/：Nginx、PM2、EMQX 模板与部署版本
• scripts/：Windows、WSL 和 Ubuntu 辅助脚本
• docs/：模块状态、开发日志、配置、API/DB/部署变更和验收文档
• 参考/：只读参考代码、SQL、运行包和硬件协议
• setup.sh：Ubuntu 24.04 中文菜单式部署与环境监测入口

配置文件位置

Windows / Git 仓库

用途	位置
项目入口	D:\qipai\README.md
当前总纲	D:\qipai\V5.2.md
完整配置索引	D:\qipai\docs\configuration.md
仓库目录映射	D:\qipai\docs\repository-map.md
后端开发配置	D:\qipai\backend\.env.development
后端测试配置	D:\qipai\backend\.env.test
后端配置模板	D:\qipai\backend\.env.example
后台开发配置	D:\qipai\admin\.env.development
后台生产配置	D:\qipai\admin\.env.production
小程序环境配置	D:\qipai\miniapp\config\env.js
WSL MQTT 本地配置	D:\qipai\config\dev\mqtt.local.env
WSL MQTT 模板	D:\qipai\config\dev\mqtt.env.example
PM2 模板	D:\qipai\deploy\pm2\ecosystem.config.cjs
Nginx 模板	D:\qipai\deploy\nginx\api.txyundm.cn.conf
EMQX 模板	D:\qipai\deploy\emqx\
部署组件版本	D:\qipai\deploy\VERSION
部署入口	D:\qipai\setup.sh

当前仓库若尚未建立上述某个文件，Codex 应在对应模块中创建；若实际目录名不同，必须同步更新本 README 和 docs/repository-map.md，不得保留错误路径。

WSL 本地调试

用途	位置/地址
Windows 工作区映射	/mnt/d/qipai
EMQX 配置目录	/etc/emqx/
EMQX 数据	/var/lib/emqx/
EMQX 日志	/var/log/emqx/
MQTTX CLI	/usr/local/bin/mqttx
EMQX Dashboard	http://127.0.0.1:18083
MQTT TCP	127.0.0.1:1883 或 WSL 当前 IP :1883

WSL 已验证：EMQX 5.8.9、MQTTX CLI 1.13.0、EMQX 服务 active (running) 且已开机启动；监听 1883/8883/8083/8084/18083。

Ubuntu 正式服务器

用途	位置
菜单部署入口	/opt/apps/setup.sh
生产 Git 工作区	/opt/apps/qipai-backend/
后台静态发布	/opt/apps/qipai-admin/current/
小程序源码镜像	/opt/apps/qipai-miniapp/source/
非敏感配置	/etc/qipai/qipai.conf
敏感配置	/etc/qipai/qipai.secrets
部署 SSH 私钥	/etc/qipai/ssh/id_ed25519
Nginx 站点	/etc/nginx/sites-available/api.txyundm.cn.conf
PM2 配置	/opt/apps/qipai-backend/deploy/pm2/ecosystem.config.cjs
Gitea 配置	/opt/apps/gitea/custom/conf/app.ini
MySQL 配置	/etc/mysql/mysql.conf.d/mysqld.cnf
EMQX 配置	/etc/emqx/
TLS 证书	/etc/letsencrypt/live/api.txyundm.cn/
上传目录	/opt/apps/qipai-backend/shared/uploads/
统一备份	/opt/apps/backups/

明文账号与密码

本项目按用户决定在私有 Gitea 仓库中明文记录账号密码。SSH/TLS/微信支付私钥或证书正文仍不得提交，只记录路径和指纹。

环境	服务	地址	账号	密码	说明
WSL 本地	EMQX Dashboard	http://127.0.0.1:18083	admin	admin123	已知 Dashboard 登录凭据；是否可用于 MQTT 客户端认证仍待验证
Windows	Gitea SSH	ssh://git@git.txyundm.cn:2222/panda/qipai.git	SSH Key	免密	Windows 已配置
Ubuntu 生产	MQTT	101.42.38.246:1883	待配置	待配置	禁止复用 WSL 凭据
Ubuntu 生产	MySQL	127.0.0.1:3306	待配置	待配置	配置后写入 /etc/qipai/qipai.secrets 并同步更新本表

Codex 工程优先纪律

• 默认流程：读取必要文档 → 选择一个未完成子阶段 → 先修改工程文件 → 测试 → 增量更新既有文档 → commit → push。
• 除用户明确要求只更新文档外，普通开发提交必须包含后端、后台、小程序、迁移、测试、脚本或部署配置中的实质工程变化。
• 只修改 Markdown 不得把模块标记为 DONE，不得增加功能完成数。
• 禁止连续两个纯文档提交；同一模块子阶段只保留一份开发日志，补丁追加到原日志。
• docs/current-baseline.md 使用 audited_commit 做增量核验，禁止每次重新生成全量审计。
• 详细门禁见 V5.2.md 的 0.0 工程编码优先与反文档循环硬门禁。

当前进度

项目已开发部分模块；具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 docs/current-baseline.md、docs/module-status.md、docs/feature-status.md 为准。

• 最近工程提交：b8b384e feat(M01-B): 严格转换旧库订单金额。
• 下一工程目标：以 docs/current-baseline.md 的 next_engineering_target 为准，当前为 M01-B 一次性 MySQL 8 往返迁移验证。
• 开发纪律：普通“继续开发”必须产生工程文件变化、测试、commit 和 push；只改 Markdown 不计入模块进度。

版本递进

• V5.0：固化 WSL EMQX 5.8.9、MQTTX CLI 1.13.0 和已有代码续接规则。
• V5.1：同步 README，明确全部配置位置、明文凭据登记和 README 随总纲递进规则。
• V5.2：增加工程编码优先、禁止文档循环、基线增量核验和工程证据门禁。

Codex 入口

请阅读 V5.2.md，按当前进度继续开发。