From 8e3050ec80a20a9cc6b4c5beb088ad8f94d1d0fb Mon Sep 17 00:00:00 2001
From: AAsige <168331480+AAsige@users.noreply.github.com>
Date: Thu, 30 Jul 2026 23:25:28 +0800
Subject: [PATCH] Update README.md

---
 README.md | 157 ++++++++++++++++++++++++------------------------------
 1 file changed, 70 insertions(+), 87 deletions(-)

diff --git a/README.md b/README.md
index b0b51f8..6817a02 100644
--- a/README.md
+++ b/README.md
@@ -1,129 +1,112 @@
-# Brass Birmingham Linux Native Backend
+# Brass Birmingham Linux Native Backend v1 Usable
 
-这是基于现有客户端协议重写的 Linux 原生后端。
+这是一个基于现有客户端协议反推出来的 Linux 原生后端，用来替代原始 Windows 服务端。
 
-## 当前状态
+## 版本定位
 
-这份实现不是从源码直接移植，而是基于下面两部分反推出来的：
+`v1-usable` 是当前可用的基线版本，重点覆盖：
 
-- `BrassHost.exe` 中提取出的 Python 服务端字节码
-- `Assembly-CSharp.dll` 中提取出的客户端接口字符串
-
-它已经覆盖了客户端联机所需的核心接口：
-
-- 登录
-- 注册
-- 当前用户
-- 房间列表
-- 创建房间
-- 加入房间
-- 离开房间
-- 事件同步
+- 登录 / 注册
+- 当前用户信息
+- 房间列表 / 创建 / 加入 / 离开
+- 事件读写
 - `lastSeenRevision` 更新
 
-## 目录结构
+## 目录
 
 ```text
-linux-native-backend/
+linux-native-backend-v1-usable/
   app/
-    __init__.py
     server.py
   data/
-    games.json
     users.json
+    games.json
   run.sh
-  test_local.py
+  build-image.sh
+  docker-compose.yml
 ```
 
-## Docker 启动
+## 快速启动
 
-先构建 image：
+### Docker Compose
+
+```bash
+docker compose up -d --build
+```
+
+默认监听 `8765` 端口。
+
+### 本机运行
+
+```bash
+chmod +x run.sh
+./run.sh
+```
+
+也可以手动指定：
+
+```bash
+HOST=0.0.0.0 PORT=8765 ./run.sh
+```
+
+## Docker 镜像
 
 ```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：
+### 推送到 Docker Hub
+
+先登录：
 
 ```bash
-cd linux-native-backend
-docker compose up -d --build
+docker login -u sigema
 ```
 
-查看日志：
+给本地镜像打 tag：
 
 ```bash
-docker compose logs -f
+docker tag brass-birmingham-backend:latest docker.io/sigema/brass-birmingham-backend:latest
+docker tag brass-birmingham-backend:latest docker.io/sigema/brass-birmingham-backend:v1-usable
 ```
 
-停止服务：
+推送镜像：
 
 ```bash
-docker compose down
+docker push docker.io/sigema/brass-birmingham-backend:latest
+docker push docker.io/sigema/brass-birmingham-backend:v1-usable
 ```
 
-当前 `Dockerfile` 使用的是明确存在的基础镜像标签：
+如果仓库还不存在，先在 Docker Hub 创建：
 
-```text
-python:3.14.6-slim-bookworm
-```
+- 仓库名：`sigema/brass-birmingham-backend`
+- 地址：`https://hub.docker.com/`
 
-这样比浮动别名更稳，也更方便排查镜像拉取问题。
+## 数据持久化
 
-## 目录挂载
+用户和房间数据保存在 `data/`：
 
-`docker-compose.yml` 已经把本地数据目录挂载到容器里：
+- `data/users.json`
+- `data/games.json`
 
-```text
-./data -> /app/data
-```
+容器方式运行时，建议把该目录挂载出去，避免重建后数据丢失。
 
-所以容器重建后，用户和房间数据仍会保留。
+## 认证
 
-## 手动构建与运行
+支持以下方式：
 
-如果你不想用 Compose，也可以直接执行：
+- `Authorization: Bearer fake-token-<user_id>`
+- `access_token: fake-token-<user_id>`
+- `X-User-Id: <user_id>`
 
-```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 概览
+## API
 
 - `POST /login`
 - `POST /login/with/e-mail`
@@ -139,19 +122,19 @@ chmod +x run.sh
 - `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>/events-and-metadata`
 - `POST /1.0.0/games/<game_id>/metadata/lastSeenRevision`
 - `POST /1.0.0/devices`
 - `GET /debug/games`
 
-## 认证方式
+## 测试
 
-后端兼容原工具里暴露出来的伪 token 机制：
+```bash
+python test_local.py
+python test_turn_progression.py
+```
 
-- `Authorization: Bearer fake-token-<user_id>`
-- 或请求头 `X-User-Id: <user_id>`
+## 说明
 
-## 已知限制
-
-- 这份协议实现是逆向恢复版，不保证 100% 覆盖所有隐藏边缘逻辑
-- 目前没有实现 ngrok 辅助启动，因为这不属于后端核心协议
-- 如果后续抓到真实客户端请求样本，还可以继续把返回结构再对齐得更严
+- 这是逆向恢复版实现，不保证覆盖所有隐藏边缘逻辑。
+- 当前版本以“可用”为目标，后续可以继续对齐真实客户端返回结构。