自助棋牌室系统

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

固定约束

• 当前权威总纲：V5.4.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、无微信云开发
• 部署入口：Ubuntu 执行 sudo bash /opt/apps/setup.sh
• 开发流程：Windows 本地开发与测试 → 按 M00→M10 固定队列持续编码 → 每个子阶段测试、commit、SSH push、远端校验 → 自动进入下一子阶段

目录

• backend/：Fastify + TypeScript 后端 API；若实际后端位于仓库根目录，以 docs/repository-map.md 为准
• admin/：Vue3 后台管理端，已接入 M08-B 保洁运营工作台、运营待处理入口、运营待处理导出、待验收任务批量验收/驳回、免清洁标记、批量免清洁与统计展示、协作者管理、任务成员导出、任务详情照片预览、任务操作流水、任务流水导出、任务详情协作分账、任务列表导出、任务详情导出、结算详情、结算详情导出、待结算候选预览与导出、结算列表导出、结算批量同步微信状态、结算转账状态筛选、微信确认参数展示与导出、微信转账预检资料展示与导出、真实转账前自动预检拦截、统计明细、每日趋势、保洁员绩效排行、统计导出、保洁员资料管理、保洁员列表导出、保洁员待补资料导出、微信绑定状态、保洁员选择器、任务/结算/统计筛选、联调检查项搜索、联调筛选结果导出与筛选清除、联调负责人筛选、联调负责人看板、联调执行阶段看板、联调期限记录、联调逾期清单、联调风险清单导出和联调归档包导出，必须适配桌面、平板和手机
• 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.4.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
WSL MySQL 本地配置	D:\qipai\config\dev\mysql.local.env
WSL MQTT 本地配置	D:\qipai\config\dev\mqtt.local.env
后台开发配置	D:\qipai\admin\.env.development
后台生产配置	D:\qipai\admin\.env.production
小程序环境配置	D:\qipai\miniapp\config\env.js
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
MySQL	127.0.0.1:3306
MySQL 开发/测试账号	root
MySQL 开发/测试密码	root123

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
MySQL 客户端凭据	/etc/qipai/mysql-client.cnf（600）
部署 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 客户端认证仍待验证
WSL 本地	MySQL	127.0.0.1:3306	root	root123	开发、测试和迁移预演
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	root	Da@Shuai!6y8c..XT	已确认；写入 /etc/qipai/qipai.secrets 与 /etc/qipai/mysql-client.cnf

数据库密码包含特殊字符时，脚本不得直接拼接到 shell 命令或未编码 URI。生产环境检查、迁移和备份统一通过权限为 600 的 /etc/qipai/mysql-client.cnf 或等效 --defaults-extra-file 连接，日志不得打印密码。

持续开发规则

• 唯一模块顺序：M00 → M01 → M02 → … → M10，模块内按 A → B → C → …。
• docs/module-status.md 顶部的 execution_cursor 是唯一续接游标；Codex 不重新规划、不从 M00 重来。
• 一个 commit 只完成一个子阶段；同一次 Codex 会话可连续完成多个相邻子阶段。
• 每个子阶段必须完成工程编码、真实测试、增量文档、commit、push，并验证 HEAD == origin/main。
• 完成一个子阶段后，在会话资源允许时自动继续下一子阶段，不询问“是否继续”。
• 纯 Markdown 变更不计业务进度；V5.4 文档提交后的下一次普通开发必须产生工程增量。
• 当前游标、最近工程提交和下一工程目标以 docs/module-status.md、docs/current-baseline.md 为准，不在 README 中猜测。

当前进度

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

• 当前执行游标：M08-B（PARTIAL）
• 最近工程提交：96c5fa4 / M08-B联调筛选清除增量，本轮补齐现场联调分类、状态、负责人和关键字筛选的一键清除，不会重置已填写的联调草稿。
• 下一工程目标：继续 M08-B，补更完整保洁运营管理界面和真实商户现场执行记录。

版本递进

• V5.1：同步 README，明确全部配置位置、明文凭据登记和 README 随总纲递进规则。
• V5.2：增加工程编码优先、反文档循环、增量审计和工程完成证据。
• V5.3：增加固定模块队列、执行游标、会话内自动推进、可中断恢复和跨模块回归检查点。
• V5.4：固化 WSL/生产 MySQL 账号密码、配置位置、真实登录检测和特殊字符处理规则。

Codex 入口

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