qipai/README.md

# 自助棋牌室系统

本仓库是 `panda/qipai.git` 的单一 Monorepo 工作区。Windows 固定开发路径为 `D:\qipai`，当前权威开发总纲为 [`V5.4.md`](./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 后台管理端，必须适配桌面、平板和手机
- `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` 为准。

- 当前执行游标：`M04-C`
- 最近工程提交：`40c891f`，完成 M04-B 受控订单状态机、幂等迁移历史和审计联动。
- 下一工程目标：M04-C 续费、取消规则、换房和管理员调整。

## 版本递进

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

## Codex 入口

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