# 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. 后续视情况升级分页缓存失效策略