# Asteria（Magento 1）→ Bagisto 数据迁移说明

从旧站 Asteria（Magento 1.x）只读导入用户、评论、订单到本店。源库以 **`as`** 为准（不要用 `longyishop`）。三条命令共用 Laravel 连接名 `asteria`，可分批、可断点续跑、可 `--dry-run`，重复执行不会重复插入。

**推荐顺序：** 先同步商品，再迁用户，再迁订单 / 评论。

```bash
php artisan migrate
php artisan catalog:sync                    # 商品 SKU 需与 Magento 一致
php artisan customers:migrate-asteria
php artisan orders:migrate-asteria
php artisan reviews:migrate-asteria --sync  # 或走队列，见下文
```

---

## 1. 前置：Asteria 数据库连接

`.env` 中配置只读 Magento 库（应用层只跑 SELECT）：

```env
ASTERIA_DB_HOST=127.0.0.1
ASTERIA_DB_PORT=3306
ASTERIA_DB_DATABASE=as
ASTERIA_DB_USERNAME=root
ASTERIA_DB_PASSWORD=
ASTERIA_DB_PREFIX=          # Magento 有表前缀时填写，例如 mag_
ASTERIA_DB_CHARSET=utf8
```

连接名默认 `asteria`，定义在 `config/database.php`。所有命令都支持 `--connection=` 覆盖。

跑迁移前确认 Bagisto 侧列已存在：

```bash
php artisan migrate
```

| 表 | 幂等列 | 迁移文件 |
|---|---|---|
| `customers` | `migrated_from_asteria_id`（unique），另有 `legacy_password` | `database/migrations/2026_08_20_163200_add_asteria_migration_columns_to_customers_table.php` |
| `orders` | `migrated_from_asteria_id`（unique） | `database/migrations/2026_08_25_143200_add_asteria_migration_column_to_orders_table.php` |
| `product_reviews` | `migrated_from_asteria_id`（unique） | 评论命令在缺列时会提示，也可交互自动 `ALTER TABLE` |

---

## 2. 用户 `customers:migrate-asteria`

同步写入 Bagisto `customers` + `addresses`（同步、无队列）。

```bash
php artisan customers:migrate-asteria
php artisan customers:migrate-asteria --batch-size=200
php artisan customers:migrate-asteria --dry-run
php artisan customers:migrate-asteria --reset-progress
```

源表：`customer_entity`、`customer_address_entity` 及对应 EAV。

行为要点：

- 无效邮箱：跳过。
- 已有相同 `migrated_from_asteria_id` 或相同邮箱（不区分大小写）：**关联**，不覆盖姓名/密码，只补未导入的地址。
- 新用户：写入 `general` 分组、默认 Channel；`password` 为随机 bcrypt，Magento 哈希放在 `legacy_password`。用户用旧密码登录成功后会自动升级为 bcrypt。
- 手机号与现有用户冲突：新用户 `phone` 置空。
- 地址按 `addresses.additional.asteria_address_id` 去重；街道换行压成 `, `。

进度缓存：`migrate_asteria_customers_last_id`（30 天）。

---

## 3. 评论 `reviews:migrate-asteria`

写入 `product_reviews`。默认按队列 `review-migration` 分批投递；`--sync` 则当场处理。

```bash
php artisan queue:work --queue=review-migration   # 非 --sync 时需要
php artisan reviews:migrate-asteria
php artisan reviews:migrate-asteria --batch-size=200
php artisan reviews:migrate-asteria --status=1     # 仅 Magento 已审核
php artisan reviews:migrate-asteria --sync
php artisan reviews:migrate-asteria --dry-run
php artisan reviews:migrate-asteria --reset-progress
```

`--status`：Magento `status_id`，`1=approved`，`2=pending`，`3=not-approved`。不传则全部导入，状态映射为 Bagisto 的 `approved` / `pending` / `disapproved`。

关联方式：

- 商品：Magento `catalog_product_entity.sku` ↔ Bagisto `products.sku`。对不上的评论会跳过并打日志。
- 用户：按邮箱挂 `customer_id`；没有则游客名（`name`）。
- 图片：写入 Magento `review_media_image` 的 URL，后续再批量上 S3（不在本命令内下载文件）。

进度缓存：`migrate_asteria_reviews_last_id`（30 天）。

---

## 4. 订单 `orders:migrate-asteria`

同步写入订单头、商品行、账单/收货地址、支付方式。

```bash
php artisan orders:migrate-asteria
php artisan orders:migrate-asteria --batch-size=100
php artisan orders:migrate-asteria --dry-run
php artisan orders:migrate-asteria --reset-progress
```

源表：`sales_flat_order`、`sales_flat_order_item`、`sales_flat_order_address`、`sales_flat_order_payment`。

**会做：**

- 保留 Magento `increment_id` 和 `created_at`，方便用户认历史单号。
- 客户：先按 `customers.migrated_from_asteria_id`，再按邮箱；都没有则游客单（快照姓名/邮箱仍写入）。
- 商品行：按订单行 SKU 对 Bagisto；对不上仍导入快照，`product_id` 为空。
- 状态：`complete` → `completed`；`canceled` → `canceled`；`pending_payment` / `payment_review` / `pending_paypal` → `pending_payment`；`holded` → `pending`；其余常见状态原样对应，未知为 `pending`。
- 支付：`paypal_express` / `paypal_standard` / `paypaluk_*` → `paypal_standard`；`checkmo` → `moneytransfer`；`klarna*` → `klarna`；`afterpay*` / `clearpay*` → `afterpay`。原文写在 `order_payment.additional.magento_method`。

**不做：** 发票、发货、退款；不扣库存；不触发下单邮件 / 礼品卡等 `checkout.order.save.after` 事件。

跳过规则：

- 已有 `migrated_from_asteria_id`（幂等）。
- Magento `increment_id` 已被 Bagisto **现网订单**占用（避免覆盖新单）。
- `increment_id` 为空。

进度缓存：`migrate_asteria_orders_last_id`（30 天）。

---

## 5. 共同约定

| 选项 | 含义 |
|---|---|
| `--batch-size` | 每批条数，默认 100 |
| `--dry-run` | 只统计，不写库，也不更新进度 |
| `--reset-progress` | 从 ID=0 重新扫（仍幂等，已迁记录会 skip） |
| `--connection` | 源库连接名，默认 `asteria` |

中断后再次执行会从缓存的 last id 继续。换环境或确认要重扫时加 `--reset-progress`。

---

## 6. 明确不迁的数据

后台管理员、收藏、积分、购物车 Quote、发票、发货单、退款单都不在这三条命令范围内。

---

## 7. 常见问题

**连不上 Asteria：** 检查 `.env` 的 `ASTERIA_DB_*`，以及 Magento 表前缀 `ASTERIA_DB_PREFIX`。源库必须是 `as`，不要配成 `longyishop`。

**MySQL 5.6 `Unknown column 'generation_expression'`：** Laravel 自带的 `Schema::hasColumn()` 会查 5.7 才有的 `information_schema.columns.generation_expression`。迁移脚本已改用 `SHOW COLUMNS`，可在 5.6 上跑。若 TablePlus 等客户端仍报这个错，是客户端自己在看表结构，与迁移无关。

**提示缺列：** 先 `php artisan migrate`。评论列也可在命令交互里自动加。

**评论一条都没有 / 大量 skip：** 先确认 `catalog:sync` 后 SKU 与 Magento 一致。

**订单是游客单：** 先跑用户迁移，并确认 Magento `customer_id` / 邮箱能对上 `migrated_from_asteria_id` 或 Bagisto 邮箱。

**旧密码登不上：** 新迁用户密码在 `legacy_password`。Web 登录与 API 登录都会走 Magento 1 MD5（可带 salt）校验，成功后改成 bcrypt。已存在的 Bagisto 账号被「关联」时**不会**写入 `legacy_password`，仍用原 Bagisto 密码。

**重复跑会不会翻倍：** 不会。用户按 Asteria ID / 邮箱，地址按 `asteria_address_id`，订单/评论按 `migrated_from_asteria_id`。