# HY Voice Room

HY Voice Room 是一个语音房后端 monorepo。当前重点不是做通用 IM 平台，而是把语音房的实时业务闭环跑起来：HTTP 命令入口、房间 Room Cell、WebSocket 消息投递、MySQL 状态恢复、Redis 房间路由。

## Architecture

核心边界：

- `gateway-service` 是客户端 HTTP JSON 入口，负责鉴权、协议转换和调用 `room-service`。它不持有房间状态，也不终止 WebSocket。
- `room-service` 是房间业务状态 owner，负责 Room Cell、麦位、房间 presence、本地礼物榜、送礼落房间、snapshot、command log、outbox、Redis lease 路由。
- `im-service` 是连接和消息 owner，负责 WebSocket、房间频道订阅、公屏、房间系统消息、单聊、ACK、最近房间历史。
- `wallet-service` 当前提供送礼扣费 stub，`room-service` 的 `SendGift` 同步调用它。
- `user-service` 和 `activity-service` 当前是独立进程骨架，后续分别承接用户主数据和活动消费。

外部协议和内部协议：

- 客户端命令面：`gateway-service` 暴露 HTTP JSON。
- 客户端实时面：`im-service` 暴露 WebSocket JSON。
- 服务内部调用：gRPC + protobuf，契约在 `api/proto`。
- 房间外事件：protobuf outbox，当前先落 MySQL。

## Ports

本地和 Docker 编排统一使用 `13xxx` 端口：

| Component | Port | Purpose |
| --- | ---: | --- |
| `gateway-service` | `13000` | HTTP JSON |
| `room-service` | `13001` | gRPC |
| `im-service` | `13002` | HTTP/WebSocket |
| `im-service` | `13003` | gRPC |
| `wallet-service` | `13004` | gRPC |
| `user-service` | `13005` | gRPC |
| `activity-service` | `13006` | gRPC |
| MySQL | `13306 -> 3306` | local Docker only |
| Redis | `13379 -> 6379` | local Docker only |

## Run Locally

Use Docker for local and test environments:

```bash
make up
```

`make up` starts the stack in detached mode and prints host-local, host-LAN, and Docker-network addresses for every service port.

Follow logs:

```bash
make logs
```

Print addresses again without restarting services:

```bash
make addr
```

Operate one service:

```bash
make up rs
make rebuild rs
make restart rs
make stop rs
make logs rs
make ps rs
```

Service aliases: `gs/gateway`, `rs/room`, `is/im`, `ws/wallet`, `us/user`, `as/activity`, `mysql`, `redis`.

Stop services:

```bash
make down
```

The compose stack starts MySQL and Redis. MySQL schema is initialized from:

```text
services/room-service/deploy/mysql/initdb/001_room_service.sql
```

For direct host execution, each service reads its own `services/<service>/configs/config.yaml`.

## Development Commands

```bash
make proto
make test
make build
make up
make addr
make logs
make ps
make up rs
make rebuild rs
make restart rs
make stop rs
make logs rs
make ps rs
make down
```

`make proto` requires `protoc`, `protoc-gen-go`, and `protoc-gen-go-grpc`.

## Storage Model

`room-service` uses MySQL as the durable source:

- `rooms`: room metadata.
- `room_snapshots`: latest room state snapshot.
- `room_command_log`: replayable command log for recovery.
- `room_outbox`: async event records.

`room-service` uses Redis for current room ownership:

```text
room:route:{room_id}
```

The Redis value stores `room_id`, `node_id`, `lease_token`, and `expires_at_ms`. Lease acquisition is atomic through Lua in `internal/router/redis_directory.go`.

## Room Recovery

A room is not permanently bound to one process. A node is only the current executor while its Redis lease is valid.

Recovery path:

1. A request reaches a node that can own the room.
2. The node acquires or renews `room:route:{room_id}`.
3. If the local Room Cell does not exist, it loads the latest MySQL snapshot.
4. It replays command log records after the snapshot version.
5. It installs a local Room Cell and continues processing.

This is single-active recovery, not hot standby. Short retry/reconnect windows are expected during node failure.

## Cloud Deployment

Local Docker uses:

```text
services/room-service/configs/config.docker.yaml
```

Tencent Cloud deployment should follow:

```text
services/room-service/configs/config.tencent.example.yaml
```

Set the real Tencent Cloud MySQL DSN, Redis address, Redis password, and internal service DNS names. Keep `mysql_auto_migrate: false` online; schema changes should run through a controlled migration process.

Deployment lifecycle requirements are documented in:

```text
docs/health-checks.md
docs/graceful-shutdown.md
```

## API Entry Points

Gateway HTTP routes:

- `POST /api/v1/rooms/create`
- `POST /api/v1/rooms/join`
- `POST /api/v1/rooms/leave`
- `POST /api/v1/rooms/mic/up`
- `POST /api/v1/rooms/mic/down`
- `POST /api/v1/rooms/mic/change`
- `POST /api/v1/rooms/user/mute`
- `POST /api/v1/rooms/user/kick`
- `POST /api/v1/rooms/gift/send`

Gateway business responses use one envelope:

```json
{
  "code": "OK",
  "message": "ok",
  "request_id": "req_xxx",
  "data": {}
}
```

`request_id` is generated by gateway unless the client sends `X-Request-ID`. The same value is propagated to internal gRPC `RequestMeta.request_id`.

IM WebSocket path:

```text
ws://127.0.0.1:13002/ws
```

The first WS frame must be `auth`; later frames include `subscribe_room`, `unsubscribe_room`, `room_chat_send`, `peer_send`, `ack`, and `pull_history`.

## Project Layout

```text
api/proto/                 protobuf contracts
pkg/                       small shared packages
services/gateway-service/  HTTP entry service
services/room-service/     Room Cell and durable room state
services/im-service/       WebSocket and message delivery
services/wallet-service/   wallet stub
services/user-service/     user stub
services/activity-service/ activity stub
```

## Current Limits

- `wallet-service`, `user-service`, and `activity-service` are still stubs.
- `room-service` outbox is durable, but external activity consumption is not implemented yet.
- `im-service` keeps message/session state in memory; scaling it across nodes still needs shared online routing or a delivery bus.
- JWT secrets in local config are development values only.