saasshop/docs/MERCHANT_REFACTOR_PLAN.md

merchant 语义重构收口记录

背景

项目在基础阶段曾短暂使用 tenant 语义，但当前产品定位已经明确为“总台管理 + 站点后台 + 商家后台”的 SaaS 电商结构，因此数据库层、代码层、页面层统一收口到 merchant / 商家 更符合后续长期演进方向。

本轮结论

tenant -> merchant 主链路重构已基本完成，当前项目基线统一采用：

• 表：merchants
• 外键：merchant_id
• 领域模型：Merchant
• 页面文案：商家
• 总台站点管理入口：/admin/merchants
• 商家后台入口：/merchant-admin

已完成项

数据库基线

• 基线表已统一为 merchants
• 相关业务表统一使用 merchant_id
• 相关外键已指向 merchants
• 已通过 php artisan migrate:fresh --seed 验证

代码层

• 模型关系已统一使用 merchant()
• 总台管理控制器已切到 MerchantController
• 商家后台上下文统一使用 admin_merchant_id
• 总台管理与商家后台鉴权边界均已验证通过
• API 入参 / 返回中的商家归属字段已统一为 merchant_id

页面与文案

• 总台管理 dashboard / 商品 / 分类 / 订单 / 渠道配置页已改为商家语义
• 总台站点管理页统一为 admin/merchants
• 首页与后台入口文案均已完成阶段性收口

缓存与配置

• 总台站点列表缓存 key 已统一为 platform:merchants:list:page:{page}
• 总台基础配置项已从 tenant_mode 调整为 merchant_mode

验证结果

已完成以下验证：

• php artisan migrate:fresh --seed
• php artisan optimize:clear
• php artisan route:list --path=admin
• php artisan route:list --path=merchant-admin
• php artisan route:list --path=api/v1
• 总台账号登录总台管理成功
• 商家账号登录商家后台成功
• 商家账号访问总台管理返回 403
• 总台账号访问商家后台返回 403
• 总台 / 商家关键页面与基础 API 返回正常

收尾原则

为了保持开发环境基线干净：

1. 不再继续引入新的 tenant 语义
2. 不再新增兼容性双命名
3. 文档、配置、缓存 key、页面文案统一使用 merchant
4. 后续新功能在此基线上继续推进

当前剩余事项

1. 继续补表单 old() 回填
2. 给总台 / 商家订单列表增加筛选条件
3. 补总台配置编辑能力
4. 后续视情况升级分页缓存失效策略