qipai/README.md

# 自助棋牌室系统

本仓库是 `panda/qipai.git` 的单一 Monorepo 工作区。Windows 固定开发路径为 `D:\qipai`，当前权威开发总纲为 [`V5.2.md`](./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、无微信云开发
- 部署入口：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` 为准。

- 最近工程提交：`98b66d2 feat(M01-A): 建立后端API基础骨架`。
- 下一工程目标：以 `docs/current-baseline.md` 的 `next_engineering_target` 为准，当前为 M01-A 后端 API 基础工程最小可运行骨架。
- 开发纪律：普通“继续开发”必须产生工程文件变化、测试、commit 和 push；只改 Markdown 不计入模块进度。

## 版本递进

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

## Codex 入口

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