# Alien Snowflake 主键方案

适用于三台 MySQL 服务器（IP 尾段 251/252/253）的分布式雪花算法实现。

## 设计要点
- Snowflake 位分配：`41-bit 时间戳 | 5-bit 机房 | 5-bit 节点 | 12-bit 序列`。
- 时间基准：2024-01-01 00:00:00 UTC（`EPOCH_MS=1704067200000`）。
- 节点映射：默认将 IP 尾段 `251/252/253` 映射为 `worker_id=1/2/3`，可通过环境变量覆盖。
- 线程安全：内部使用锁，确保并发安全；发生时钟回拨时抛出异常。

## 使用方法
### 1) 直接取号
```python
from alien_snowflake import next_id

pk = next_id()
```

### 2) 在 SQLAlchemy 模型中用作主键默认值
```python
from sqlalchemy import BigInteger
from sqlalchemy.orm import mapped_column, Mapped
from alien_snowflake import next_id
from alien_database.base import Base

class Example(Base):
    __tablename__ = "example"
    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, default=next_id)
```

### 3) 自定义机房或映射
```python
from alien_snowflake import SnowflakeGenerator, resolve_worker_id

worker_id = resolve_worker_id()  # 自动根据本机 IP 或环境变量映射
gen = SnowflakeGenerator(datacenter_id=0, worker_id=worker_id)
pk = gen.next_id()
```

## IP 映射规则
- 环境变量优先：`SNOWFLAKE_WORKER_IP`（可填完整 IP 或尾段，如 `192.168.0.251` 或 `251`）。
- 默认映射表（`DEFAULT_IP_WORKER_MAP`）：
  - 251 → worker_id=1
  - 252 → worker_id=2
  - 253 → worker_id=3
- 若需要调整，请修改 `alien_snowflake/generator.py` 中的 `DEFAULT_IP_WORKER_MAP`，或在初始化时传入自定义 `ip_worker_map`。

## 部署建议
- 确认三台服务器的 IP 与映射一致，或在启动前设定 `SNOWFLAKE_WORKER_IP`。
- 保障服务器时间同步（NTP），避免时钟回拨；若检测到回拨将抛出异常终止发号。
- 若需更大规模，可扩展 `datacenter_id` / `worker_id` 映射，但需保持各节点唯一性。