# hero_set — 英雄配置编辑器

英雄数值/技能/触发/光环的可视化配置工具。数据存储在 **MongoDB**，编辑器产出可写回游戏工程的 `heroSet.ts` 与 `英雄设计表.csv`。

## 双版本架构

| | 项目开发版（local） | 线上设计版（remote） |
|---|---|---|
| 使用人 | 开发者 | 数值设计人员 |
| 数据 | 同一个线上 MongoDB | 同一个线上 MongoDB |
| meta 底座（技能/Buff） | 从游戏工程 TS 实时编译 | `server/data/meta.json` 快照（需随部署发布） |
| 英雄/预设 增删改 | ✅ | ✅（库结构版本更高时只读） |
| 写 heroSet.ts / 导出 CSV | ✅ | ❌（接口返回 403，按钮隐藏） |

**版本闸门**：库中 `meta` 集合存 `schemaVersion`（只升不降）。线上版启动版本低于库版本时，保存接口返回 409、前端禁用保存——防止旧结构覆盖新数据。结构有破坏性变更时：本地 `SCHEMA_VERSION` +1 → `npm run push-meta` → 重新部署线上版。

## 目录

```
put/
├── server/          # Express API（单服务托管 API + 前端静态页）
│   ├── index.js     # 接口与模式/版本闸门
│   ├── db.js        # MongoDB 存储层
│   ├── data/        # meta.json 快照（remote 模式必需）
│   ├── scripts/
│   │   ├── migrate-to-mongo.js  # 一次性：JSON 文件 → Mongo
│   │   └── push-meta.js         # 开发版：生成 meta 快照 + 抬升库版本
│   └── .env.example
└── web/             # Vue3 + Element Plus 前端
    └── dist/        # 构建产物（remote 模式由 server 托管，需提交）
```

## 部署线上设计版（给 AI 部署智能体）

前置：Node.js ≥ 18；可访问的 MongoDB 连接串。

```bash
# 1. 拉代码
git clone git@git.eoxnet.com:pan/hero_set.git && cd hero_set

# 2. 配置环境变量
cp server/.env.example server/.env
# 编辑 server/.env：
#   MODE=remote
#   MONGO_URL=mongodb://user:pass@host:27017
#   MONGO_DB=heroconfig
#   PORT=3001

# 3. 构建前端
cd web && npm ci && npm run build && cd ..
# 注意：web/dist 与 server/data/meta.json 必须存在（均已随仓库提交，若仓库有更新请重新构建）

# 4. 启动（server 自动托管 web/dist，单服务即可）
cd server && npm ci && npm start
# 访问 http://<host>:3001
```

进程守护（可选）：`pm2 start index.js --name hero-set --cwd server`

## 开发版工作流（本地）

```bash
# server/.env：MODE=local + 同一个 MONGO_URL
cd server && npm ci && npm run dev     # API :3001
cd web && npm ci && npm run dev        # 前端 :4004（已代理 /api → :3001）
```

- **保存到数据库** → 全量覆盖 MongoDB（按 uuid upsert + 删除多余）
- **写入 heroSet.ts** → 渲染进 `assets/script/game/common/config/heroSet.ts` 的 `@hero-setup:heroes-begin/end` 标记区域
- **技能/底座结构变更后**：`SCHEMA_VERSION` +1 → `npm run push-meta`（需 dev 服务已启动）→ 提交并重新部署线上版

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `MODE` | `local` | `local` 开发版 / `remote` 线上设计版 |
| `MONGO_URL` | — | 必填，MongoDB 连接串 |
| `MONGO_DB` | `heroconfig` | 库名 |
| `PORT` | `3001` | 服务端口 |
| `HOST` | `0.0.0.0` | 监听地址；容器部署必须保持 0.0.0.0 并映射端口（如 `docker run -p 3001:3001`） |
| `SCHEMA_VERSION` | `1` | 数据结构版本，破坏性变更时 +1 |

前端单独部署（不经 server 托管）时，`web/.env` 配 `VITE_API_BASE=http://<host>:3001`。

## 数据库结构（MongoDB · heroconfig）

- `heroes`：每个英雄一条文档，`uuid` 唯一索引
- `templates`：`_id='presets'` 单文档（triggerPresets / fieldPresets）
- `meta`：`_id='version'` 单文档（schemaVersion）