nshop/docs/asteria-migration.md

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

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

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

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）：

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 侧列已存在：

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（同步、无队列）。

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 则当场处理。

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

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

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。