From 54ce74860b82a96b30a717d2d61e84c5459cfb48 Mon Sep 17 00:00:00 2001
From: AAsige <168331480+AAsige@users.noreply.github.com>
Date: Thu, 30 Jul 2026 21:04:54 +0800
Subject: [PATCH] Create README.md for project documentation

Add README for Brass Birmingham Linux Native Backend
---
 README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b0b51f8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,157 @@
+# Brass Birmingham Linux Native Backend
+
+这是基于现有客户端协议重写的 Linux 原生后端。
+
+## 当前状态
+
+这份实现不是从源码直接移植，而是基于下面两部分反推出来的：
+
+- `BrassHost.exe` 中提取出的 Python 服务端字节码
+- `Assembly-CSharp.dll` 中提取出的客户端接口字符串
+
+它已经覆盖了客户端联机所需的核心接口：
+
+- 登录
+- 注册
+- 当前用户
+- 房间列表
+- 创建房间
+- 加入房间
+- 离开房间
+- 事件同步
+- `lastSeenRevision` 更新
+
+## 目录结构
+
+```text
+linux-native-backend/
+  app/
+    __init__.py
+    server.py
+  data/
+    games.json
+    users.json
+  run.sh
+  test_local.py
+```
+
+## Docker 启动
+
+先构建 image：
+
+```bash
+cd linux-native-backend
+chmod +x build-image.sh
+./build-image.sh
+```
+
+默认会生成：
+
+```text
+brass-birmingham-backend:latest
+```
+
+如果你想自定义名字或 tag：
+
+```bash
+IMAGE_NAME=myrepo/brass-backend IMAGE_TAG=v1 ./build-image.sh
+```
+
+推荐直接用 Docker Compose：
+
+```bash
+cd linux-native-backend
+docker compose up -d --build
+```
+
+查看日志：
+
+```bash
+docker compose logs -f
+```
+
+停止服务：
+
+```bash
+docker compose down
+```
+
+当前 `Dockerfile` 使用的是明确存在的基础镜像标签：
+
+```text
+python:3.14.6-slim-bookworm
+```
+
+这样比浮动别名更稳，也更方便排查镜像拉取问题。
+
+## 目录挂载
+
+`docker-compose.yml` 已经把本地数据目录挂载到容器里：
+
+```text
+./data -> /app/data
+```
+
+所以容器重建后，用户和房间数据仍会保留。
+
+## 手动构建与运行
+
+如果你不想用 Compose，也可以直接执行：
+
+```bash
+cd linux-native-backend
+docker build -t brass-birmingham-backend .
+docker run -d \
+  --name brass-birmingham-backend \
+  -p 8765:8765 \
+  -v "$(pwd)/data:/app/data" \
+  --restart unless-stopped \
+  brass-birmingham-backend
+```
+
+## 直接本机启动
+
+```bash
+cd linux-native-backend
+chmod +x run.sh
+./run.sh
+```
+
+默认监听：
+
+```text
+0.0.0.0:8765
+```
+
+## API 概览
+
+- `POST /login`
+- `POST /login/with/e-mail`
+- `POST /register`
+- `GET /me`
+- `POST /logout`
+- `POST /password/email`
+- `GET /1.0.0/games`
+- `POST /1.0.0/games`
+- `PUT /1.0.0/games/<game_id>/players`
+- `DELETE /1.0.0/games/<game_id>/players`
+- `GET /1.0.0/games/<game_id>/events`
+- `POST /1.0.0/games/<game_id>/events`
+- `DELETE /1.0.0/games/<game_id>/events`
+- `GET /1.0.0/games/<game_id>/events-and-metadata`
+- `POST /1.0.0/games/<game_id>/metadata/lastSeenRevision`
+- `POST /1.0.0/devices`
+- `GET /debug/games`
+
+## 认证方式
+
+后端兼容原工具里暴露出来的伪 token 机制：
+
+- `Authorization: Bearer fake-token-<user_id>`
+- 或请求头 `X-User-Id: <user_id>`
+
+## 已知限制
+
+- 这份协议实现是逆向恢复版，不保证 100% 覆盖所有隐藏边缘逻辑
+- 目前没有实现 ngrok 辅助启动，因为这不属于后端核心协议
+- 如果后续抓到真实客户端请求样本，还可以继续把返回结构再对齐得更严