corp-transfer/docs/OPERATION_GUIDE.md

# 企业微信 ID 转换与数据迁移操作指南

本文档介绍如何编译打包、运行企业微信数据迁移任务（`transfer.js` 等脚本），以及执行完毕后的数据验证方式。

## 1. 整体流程
迁移主要包含三个步骤：
1. **构建打包（可选但推荐）**：打包脚本，将配置信息直接注入到单产物中，方便分发到不同机器（如接收端机器），不依赖外部 `node_modules`。
2. **测试评估（Dry-run）**：获取 API 数据，扫描相关表进行日志打印统计，但不做实际写入。 
3. **真实修改（Apply）**：将转换后的用户 ID 写回原有的 MongoDB 集合中。


## 2. 构建与打包准备 (Build)

如果需要在生产机上直接运行而不需要安装库依赖，可使用已配置好的 `esbuild` 进行单文件打包。

1. 进入项目目录并安装依赖（如尚未安装）：
   ```bash
   cd c:\code\yk\gykq\transfer
   npm install
   ```
2. 准备环境变量文件（如 `.env.gk`）。打包脚本会自动将其读取并注入到构建结果中。
3. 执行打包命令：
   ```bash
   npm run build
   ```
   *产物将生成在 `dist/` 目录下（如 `dist/transfer.js`、`dist/corpid.js`），你可以把这个单文件发给对方，对端机器只需安装了 Node.js 就能直接跑。*


## 3. 运行指南 (Run)

以迁移企业微信 `open_userid` 及 `external_userid` 为例，核心使用 `transfer.js`。

如果已经使用内置 env（例如 `.env.gk`，或打包后的 `dist/transfer.js`），通常不需要再手动传 `--mongoUri`、`--dbName`、`--targetCorpId`、`--sourceAgentId` 这类基础参数；脚本会直接读取内置配置。只有临时覆盖某个值时，才需要显式加参数。

### 3.1 步骤一：预演空跑（Dry-Run）
强烈建议在实际写入生产数据前，执行一次空测试。该模式仅读取数据和调用查询 API，不会修写数据库。

**内置 env 直接执行：**
```bash
node transfer.js --skipApi
```
**或者执行打包后的产物：**
```bash
node dist/transfer.js --skipApi
```
*注：可通过日志查看预计会有多少条数据被改变、读取的数据形态是否符合预期。*

### 3.2 步骤二：实际执行转换并写入（Apply）
在确认空跑日志报错和逻辑都没有问题后，带上 `--apply --yes` 标志位做真实写入。

```bash
# 需保证服务器外网出口 IP 已经在企业微信开发平台的白名单中
node dist/transfer.js --apply --yes
```

如果只是想临时覆盖某个默认值，可以继续追加参数，例如：

```bash
node dist/transfer.js --apply --yes --collections wechat-friends
```

> **提示**：脚本设计为使用 MongoDB 的 `upsert` 或根据 `_id` 覆盖写入。如果在中途网络断开或因接口限制（如并发 / token 过期）导致报错退出，直接原样重启脚本即可，不会造成脏数据重复写入。


## 4. 如何验证 (Verify)

转换脚本执行完毕后，可通过以下三种方式进行验证：

### 4.1 日志验证
检查终端输出的最终 Summary 日志。

### 4.2 数据库数据验证
使用 MongoDB 客户端（如 MongoDB Compass、Navicat 或 mosh）连接数据库：
1. 打开被修改的数据表（例如 `wechat-friends` 或具体对应业务的 collection）。
2. 核对被转换的字段（如 `open_userid` 是否已变更为了 `userid`，服务商的 `external_userid` 是否变更为企业的 `external_userid`）。
3. 检查原数据文档的其他字段是否存在丢失。得益于 `_id` 覆盖更新机制，确保只变更多出的或改写的字段。

### 4.3 业务功能验证
登录实际业务系统或者企业微信应用端：
1. **身份鉴权测试**：尝试调用依赖当前企微系统的登录模块或回调模块，验证基于新 `userid` 是否能正常查到员工权限和身份。
2. **外部联系人服务测试**：给发生转换的用户发送测试企微消息或打标签，确认企业微信后台或第三方系统能由转换后的 `external_userid` 成功匹配到对应客户，不报“不是企业客户”之类的错误。

---

## 5. 单独替换 corpId

### 5.1 默认运行方式

`corpid.js` 已经会默认走 `.env.gk`，所以如果环境变量已准备好，直接跑就行：

```powershell
node corpid.js
```

实际写入：

```powershell
node corpid.js --apply --yes
```

### 5.2 常见定向运行

只处理某个数据库：

```powershell
node corpid.js --dbName corp
```

只处理指定 collection：

```powershell
node corpid.js --dbName corp --collections corp-member,wechat-friends
```

显式指定旧 corpId 和新 corpId：

```powershell
node corpid.js --sourceCorpId <旧corpId> --newCorpId <新corpId>
```

补充说明：

- 默认旧 corpId 从 `TARGET_CORP_ID` 取
- 默认新 corpId 从 `TOKEN_CORP_ID` 取
- `corp` collection 里会额外维护 `internal_agentid`

### 5.3 重复字段和重复执行

这个脚本的“重复”有两层含义：

- 同一文档里 `corpId`、`corpid`、`corp_id` 可能同时出现，脚本会全部替换
- 你重复执行同一命令，dry-run 不会落库；apply 模式按原 `_id` 回写，重复跑不会造重复文档

---

## 6. 数据库迁移

### 6.1 运行顺序

迁移必须先起 receiver，再跑 sender。

1. 在目标环境启动 receiver
2. 在源环境启动 sender，把数据推过去

### 6.2 启动 receiver

receiver 默认监听 8081，默认参数已经写在脚本里。内网/目标机一般直接运行即可：

```powershell
node migrate-corpid-receiver.js
```

如果你要改端口或目标 MongoDB，可以覆盖参数：

```powershell
node migrate-corpid-receiver.js --port 8081 --targetMongoUri "mongodb://<user>:<pass>@<host>:27017/admin" --token "<token>"
```

### 6.3 启动 sender

sender 默认也带有内置配置，常规情况下直接运行即可：

```powershell
node migrate-corpid-sender.js
```

如果要覆盖源库、receiver 地址或 token：

```powershell
node migrate-corpid-sender.js --sourceMongoUri "mongodb://<user>:<pass>@<host>:27017/admin" --receiverUrl "http://127.0.0.1:8081" --token "<token>" --corpId "<corpId>"
```

### 6.4 迁移范围和重复执行

sender 会扫描源库的业务数据库和 collection，默认过滤 `admin`、`config`、`local` 以外的范围。它会：

- 先把 collection 的索引发给 receiver
- 再按批发送文档
- receiver 用 `_id` 做 upsert 写入

迁移脚本适合重跑：

- 索引有去重缓存
- 文档按 `_id` 覆盖写入
- 中途失败后可以重新执行 sender

---

## 7. 怎么验证

### 7.1 先看日志

每个脚本结束时都应该看最后的 summary：

- `transfer.js`：看扫描数、命中文档数、写入数、invalid 数
- `corpid.js`：看扫描的数据库数、collection 数、corpId 替换次数、`internal_agentid` 更新次数
- `migrate-corpid-sender.js`：看迁移完成 summary，确认 migratedDocs 数量正常

### 7.2 mongosh 验证命令

下面给的是可以直接复制的 `mongosh` 命令。把 `<MONGO_URI>`、`<DB_NAME>`、`<COLLECTION>`、`<OLD_CORP_ID>`、`<NEW_CORP_ID>` 替换成你的真实值即可。

#### 验证 corpId 替换

先看旧 corpId 还剩多少：

```bash
mongosh "<MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const col = dbx.getCollection("<COLLECTION>");
const oldCorpId = "<OLD_CORP_ID>";
print("old corpId count:", col.countDocuments({ $or: [ { corpId: oldCorpId }, { corpid: oldCorpId }, { corp_id: oldCorpId } ] }));
'
```

再看新 corpId 命中多少：

```bash
mongosh "<MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const col = dbx.getCollection("<COLLECTION>");
const newCorpId = "<NEW_CORP_ID>";
print("new corpId count:", col.countDocuments({ $or: [ { corpId: newCorpId }, { corpid: newCorpId }, { corp_id: newCorpId } ] }));
printjson(col.findOne({ $or: [ { corpId: newCorpId }, { corpid: newCorpId }, { corp_id: newCorpId } ] }, { projection: { corpId: 1, corpid: 1, corp_id: 1, internal_agentid: 1 } }));
'
```

如果你想检查整个数据库里是否还有旧 corpId，可以在 mongosh 里循环所有 collection：

```bash
mongosh "<MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const oldCorpId = "<OLD_CORP_ID>";
for (const name of dbx.getCollectionNames()) {
   const col = dbx.getCollection(name);
   const count = col.countDocuments({ $or: [ { corpId: oldCorpId }, { corpid: oldCorpId }, { corp_id: oldCorpId } ] });
   if (count) print(name + ": " + count);
}
'
```

#### 验证企微 ID 转换

如果你知道要查的 collection，可以先抽样看一条文档：

```bash
mongosh "<MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const col = dbx.getCollection("<COLLECTION>");
printjson(col.findOne({}, { projection: { open_userid: 1, userid: 1, external_userid: 1, corpId: 1, corpid: 1, corp_id: 1 } }));
'
```

如果你想确认旧格式值是否还残留，可以针对你已知字段做计数。比如常见的 open_userid / external_userid 形式：

```bash
mongosh "<MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const col = dbx.getCollection("<COLLECTION>");
print("open_userid-like count:", col.countDocuments({ open_userid: /^wo/ }));
print("external_userid-like count:", col.countDocuments({ external_userid: /^wm/ }));
'
```

如果你的数据字段不是顶层字段，而是嵌套在对象里，那么更实用的办法是：

1. 先从日志里拿到处理过的 collection 名
2. 用 `findOne` 抽样看字段
3. 再针对具体字段写 `countDocuments` 或 `find` 验证

#### 验证迁移前后数据量

迁移时最直接的验证方式，是在源库和目标库分别看同一个 collection 的数量是否一致。

源库：

```bash
mongosh "<SOURCE_MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
print("source count:", dbx.getCollection("<COLLECTION>").estimatedDocumentCount());
'
```

目标库：

```bash
mongosh "<TARGET_MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
print("target count:", dbx.getCollection("<COLLECTION>").estimatedDocumentCount());
'
```

如果要更严谨一点，可以再比对同一批 `_id` 是否能查到：

```bash
mongosh "<TARGET_MONGO_URI>" --quiet --eval '
const dbx = db.getSiblingDB("<DB_NAME>");
const col = dbx.getCollection("<COLLECTION>");
printjson(col.find({}, { projection: { _id: 1 } }).limit(5).toArray());
'
```

### 7.3 验证 receiver 是否在工作

这个不是 mongosh 命令，但很适合一起检查：

```powershell
Invoke-RestMethod http://127.0.0.1:8081/health
```

如果返回 `success: true`，说明 receiver 已经在监听。

---

## 8. 推荐执行顺序

最稳妥的顺序是：

1. 先跑 `transfer.js --skipApi` 做 dry-run
2. 用 `mongosh` 抽样看数据形态
3. 再跑 `transfer.js --apply --yes`
4. 跑 `corpid.js` 做 corpId 替换
5. 最后做 sender / receiver 迁移

如果只是要迁移其中一类数据，就只跑对应脚本，不必全跑。