chore: init saasshop repo + sql migrations runner + gitee go

2026-03-10 11:31:02 +00:00
commit 50f15cdea8
210 changed files with 29534 additions and 0 deletions
--- a/docs/ADMIN_BASELINE.md
+++ b/docs/ADMIN_BASELINE.md
@@ -0,0 +1,84 @@
+# 总台管理基础能力（当前已完成）
+
+## 访问入口
+- 登录页：`/admin/login`
+- 总台仪表盘：`/admin`
+- 站点管理：`/admin/merchants`
+- 商品巡检：`/admin/products`
+- 订单监控：`/admin/orders`
+- 系统配置：`/admin/settings/system`
+- 渠道配置：`/admin/settings/channels`
+
+## 当前定位
+当前 `/admin` 已明确为 **总台管理（Platform Ops）**，面向平台运营方：
+- 管理站点
+- 查看总台视角的订单 / 商品 / 用户规模
+- 承接全局系统配置与渠道配置骨架
+- 为后续拆分站点后台、商家后台做边界准备
+
+## 当前能力
+- 总台管理登录（Session）
+- 登录态校验中间件 `admin.auth`
+- 总台统一布局模板与导航分组
+- 总台仪表盘与总台定位说明
+- 站点管理列表 + 新增站点
+- 商品巡检列表 + 新增 / 更新 / 删除
+- 订单监控列表 + 状态更新 + 详情页
+- 系统配置页面已接入数据库读取（`system_configs`）
+- 渠道配置页面已接入数据库读取（`channel_configs`）
+- 支付配置基线已落库并在渠道配置页展示（`payment_configs`）
+- Session 中已记录 `admin_role` / `admin_merchant_id` / `admin_merchant_id` / `admin_scope`，其中商家后台优先使用 `admin_merchant_id`，为后续总台 / 站点 / 商家三层后台边界做准备
+
+## 演示账号
+### 总台管理
+- 邮箱：`platform.admin@demo.local`
+- 密码：`Platform@123456`
+- 作用域：总台管理员（`merchant_id = null`）
+
+### 站点后台
+- 邮箱：`merchant.admin@demo.local`
+- 密码：`Merchant@123456`
+- 作用域：站点管理员（当前绑定 `merchant_id = 1`，第一阶段复用 Merchant 承接）
+
+### 商家后台
+- 邮箱：`merchant.admin@demo.local`
+- 密码：`Merchant@123456`
+- 作用域：商家管理员（当前绑定 `merchant_id = 1`）
+
+> 生产环境需要补独立权限体系、菜单权限控制、配置落库、操作审计，以及更细粒度的管理员角色权限。
+
+## 当前三层后台边界
+### 总台管理（`/admin`）
+- 管站点
+- 看总台视角订单 / 商品 / 用户规模
+- 管系统配置、渠道配置、支付配置
+- 仅允许 `merchant_id = null` 的总台管理员登录
+- 面向平台运营方
+
+### 站点后台（`/site-admin`）
+- 当前先展示绑定站点范围内的数据
+- 第一阶段继续复用 `Merchant / merchants / merchant_id` 作为站点承接层
+- 已具备站点商品、站点订单的最小筛选与导出入口
+- 仅允许绑定商家的管理员登录，并映射为站点作用域
+- 面向站点运营人员
+
+### 商家后台（`/merchant-admin`）
+- 只展示当前登录商家的数据
+- 当前商家后台会使用 `admin_merchant_id` 作为登录态中的商家作用域标识，并在数据查询时继续映射到底层 `merchant_id` 过滤：仪表盘、商品列表、订单列表、订单详情、订单状态更新、商品新增
+- 仅允许绑定商家的管理员登录
+- 面向商家运营人员
+
+## 当前代码层封装进展
+- `Admin` 模型已补充商家语义方法：`merchant()`、`merchantId()`、`isPlatformAdmin()`、`isMerchantAdmin()`
+- 商家后台已新增 `ResolvesMerchantContext` trait，用于统一解析 `merchantId()`、`merchant()`、`merchantAdmin()`
+- 站点后台已新增 `ResolvesSiteContext` trait，用于统一解析 `siteId()`、`site()`、`siteAdmin()`
+- 商家后台控制器已开始改用封装后的商家上下文，而不直接在每个控制器里重复读取 session
+- `Product` / `Order` / `User` 模型已新增 `forMerchant($merchantId)` scope，商家侧与站点侧查询开始用统一 scope 收口
+- 商家后台已补充商品编辑 / 删除，以及商家用户列表页 `/merchant-admin/users`
+
+## 下一步建议
+1. 继续把站点后台从最小筛选 / 导出推进到更贴近运营流程的汇总与异常提示
+2. 为总台站点管理到站点后台补更顺滑的链路设计（例如后续单独设计站点管理员体系或安全代入方案）
+3. 给商家后台继续补订单筛选、商品分类、用户详情等经营能力
+4. 给总台配置、渠道配置、支付配置补编辑能力与审计
+5. 继续补齐 merchant 语义收口后的配置编辑、审计与权限细化
--- a/docs/API_BASELINE.md
+++ b/docs/API_BASELINE.md
@@ -0,0 +1,60 @@
+# API 基础规范（当前版本）
+
+## 基础前缀
+- `/api/v1`
+
+## 当前接口
+### 系统
+- `GET /api/v1/ping`
+- `GET /api/v1/platforms`
+
+### 认证
+- `POST /api/v1/auth/login`
+- `POST /api/v1/auth/channel-login`
+
+### 商品
+- `GET /api/v1/products`
+- `GET /api/v1/products/{id}`
+
+### 订单
+- `GET /api/v1/orders`
+- `POST /api/v1/orders`
+
+## 统一返回结构
+```json
+{
+  "code": 0,
+  "message": "ok",
+  "data": {},
+  "server_time": "2026-03-08 13:00:00"
+}
+```
+
+## 多端预留字段
+### users
+- `register_source`
+- `last_login_source`
+- `wechat_openid`
+- `wechat_unionid`
+- `mini_openid`
+
+### orders
+- `platform`
+- `payment_channel`
+- `payment_status`
+- `device_type`
+
+### oauth_accounts
+- `platform`
+- `provider`
+- `openid`
+- `unionid`
+- `app_id`
+- `raw_payload`
+
+## 支持方向
+- PC
+- H5
+- 微信公众号
+- 微信小程序
+- APP（预留 API 层）
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,35 @@
+# SaaSShop 架构草图（当前阶段）
+
+## 已落地模块骨架
+- 首页 `/`
+- 健康检查 `/health`
+- 后台首页 `/admin`
+
+## 当前数据表
+- `merchants`：商家
+- `admins`：后台管理员
+- `users`：商城用户
+- `products`：商品
+- `orders`：订单
+
+## 当前设计方向
+### 1. 多商家平台
+- 每个商家对应一个店铺主体
+- 关键业务表挂 `merchant_id`
+- 后续可扩展为域名绑定、子域名、独立套餐与配置
+
+### 2. 管理后台
+- 入口：`/admin`
+- 后续增加：登录、权限、菜单、仪表盘、资源管理
+
+### 3. 商城业务
+- 商品：基础标题、SKU、价格、库存、状态
+- 订单：订单号、金额、买家信息、支付与履约时间
+- 用户：基础账户 + merchant 归属
+
+## 下一步建议
+1. 上管理员登录鉴权
+2. 增加后台布局模板
+3. 做商家 / 商品 / 订单 CRUD
+4. 补订单明细表 `order_items`
+5. 补商品分类、规格、多图与购物车
--- a/docs/DB_SQL_MIGRATIONS.md
+++ b/docs/DB_SQL_MIGRATIONS.md
@@ -0,0 +1,68 @@
+# SaaSShop 数据库结构迁移（SQL 版）
+
+> 目标：数据库**结构变更**以 SQL 脚本形式版本化，便于在新环境 / CI（Gitee Go）自动执行。
+> 
+> 约束：只推结构变更，不推业务数据。
+
+## 目录与命名
+
+- 脚本目录：`database/migrations/`
+- 命名规则：`V{数字}__{描述}.sql`
+  - 示例：`V2__add_platform_order_indexes.sql`
+  - 数字必须递增（V1、V2、V3...）
+
+## 执行方式
+
+### 1）Laravel 原生迁移
+
+首次初始化仍执行 Laravel migration（PHP 迁移），用于建立基础表：
+
+```bash
+php artisan migrate --force
+```
+
+### 2）SQL 脚本迁移
+
+执行 SQL 结构迁移：
+
+```bash
+composer run db:sql-migrate
+# 或
+php scripts/sql_migrate.php
+```
+
+该命令会：
+- 扫描 `database/migrations/V*__*.sql`
+- 按版本号升序执行
+- 执行成功后写入记录表 `schema_sql_migrations`
+
+## 记录表
+
+- 表名：`schema_sql_migrations`
+- 字段：
+  - `version`：如 `V1` / `V2`
+  - `description`：从文件名解析
+  - `applied_at`：执行时间
+
+## 编写脚本建议
+
+- **仅结构变更**：CREATE/ALTER/DROP/INDEX 等
+- 不写 INSERT/UPDATE 业务数据（除非是结构初始化必要数据，且要评估影响）
+- 每个脚本尽量“可重复执行”或在脚本内加存在性判断（视具体 DB 方言支持）
+
+## 新环境落地步骤（推荐）
+
+```bash
+git clone <repo>
+cd saasshop
+composer install
+cp .env.example .env
+php artisan key:generate
+php artisan migrate --force
+composer run db:sql-migrate
+php artisan test
+```
+
+## CI（Gitee Go）
+
+仓库内提供 `.gitee/go.yml` 模板，需在 Gitee Go 中配置数据库连接与环境变量后启用。
--- a/docs/FOUNDATION_PROGRESS_2026-03-08.md
+++ b/docs/FOUNDATION_PROGRESS_2026-03-08.md
@@ -0,0 +1,71 @@
+# 2026-03-08 基础能力推进记录
+
+## 本次完成
+
+### 1. 补齐基础数据结构
+- 新增 `product_categories` 表
+  - 字段：`merchant_id`、`name`、`slug`、`status`、`sort`、`description`
+- 给 `products` 表新增 `category_id`
+- 新增 `order_items` 表
+  - 字段：`merchant_id`、`order_id`、`product_id`、`product_title`、`product_sku`、`product_price`、`quantity`、`line_total_amount`、`snapshot`
+
+### 2. 新增模型与关系
+- `App\Models\ProductCategory`
+- `App\Models\OrderItem`
+- `Product` 增加：
+  - `category()`
+  - `orderItems()`
+- `Order` 增加：
+  - `items()`
+
+### 3. Seeder 扩展
+- 初始化两个演示分类：
+  - 默认分类
+  - 精选商品
+- 初始化第二个演示商品
+- 初始化订单明细 2 条，覆盖多商品场景
+- 初始化演示订单金额同步调整为 `397.00`
+
+### 4. 商家后台展示增强
+- 商品页已展示商品分类表
+- 商品创建 / 编辑支持选择分类
+- 订单详情页已展示订单明细
+
+### 5. Redis 缓存接入（第一阶段）
+- `.env` 已切换 `CACHE_STORE=redis`
+- 新增缓存 key 辅助类：`App\Support\CacheKeys`
+- 已缓存：
+  - 商家仪表盘统计
+  - 商家商品列表
+- 已实现基础缓存失效：
+  - 商品新增 / 更新 / 删除
+  - 订单状态更新
+
+## 影响范围
+- migration
+- model
+- seeder
+- merchant admin controllers
+- merchant admin views
+- docs
+
+## 风险提示
+- 由于新增 migration，需要执行迁移
+- 如果 Redis 服务异常，缓存层会受影响；但当前 `/health` 已可辅助确认 Redis 连通性
+- 当前商品分类仅做基础展示，尚未独立做商家后台分类 CRUD
+
+## 建议验证命令
+```bash
+cd /var/www/sites/app
+php artisan migrate
+php artisan db:seed --force
+php artisan optimize:clear
+php artisan route:list --path=merchant-admin
+```
+
+## 建议验证页面
+- `/health`
+- `/merchant-admin`
+- `/merchant-admin/products`
+- `/merchant-admin/orders`
+- `/merchant-admin/orders/{id}`
--- a/docs/MERCHANT_REFACTOR_PLAN.md
+++ b/docs/MERCHANT_REFACTOR_PLAN.md
@@ -0,0 +1,63 @@
+# 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. 后续视情况升级分页缓存失效策略
--- a/docs/MULTI_PLATFORM_PLAN.md
+++ b/docs/MULTI_PLATFORM_PLAN.md
@@ -0,0 +1,45 @@
+# 多端支持基础规划
+
+## 当前目标
+优先把 SaaS 电商系统的基础框架搭好，并确保可访问。
+
+## 现阶段支持策略
+### 已可直接访问
+- PC 端页面：`/pc`
+- H5 页面：`/h5`
+- 后台：`/admin`
+- API：`/api/v1/*`
+
+### 已预留接口
+- 微信公众号：`/wechat/mp`
+- 微信小程序：`/wechat/mini`
+- APP 端：统一走 `/api/v1/*`，后续由原生 App / Flutter / uni-app 对接
+
+## 建议的多端架构分层
+1. **管理后台层**
+   - PC Web 后台
+   - 负责商家、商品、订单、用户、配置管理
+
+2. **商城展示层**
+   - PC 模板
+   - H5 模板
+   - 小程序前端
+   - 微信公众号页面/菜单跳转 H5
+
+3. **统一业务接口层**
+   - `/api/v1`
+   - 提供登录、商品、购物车、订单、支付、用户信息等接口
+   - 后续 APP 端复用这一层
+
+4. **渠道适配层**
+   - 微信公众号 OAuth
+   - 微信小程序登录
+   - 微信支付/消息能力
+   - 后续 APP 登录/推送/支付适配
+
+## 下一步落地方向
+1. 后台登录鉴权
+2. API 统一返回结构
+3. 商品 / 订单 API
+4. 微信登录与支付预留字段
+5. 按端拆分前端模板与菜单配置
--- a/docs/NEXT_FOUNDATION_STEPS.md
+++ b/docs/NEXT_FOUNDATION_STEPS.md
@@ -0,0 +1,21 @@
+# 下一阶段基础建设建议
+
+## 已完成的基础能力
+- LNMP + Redis 环境
+- Laravel 多端骨架
+- 多端 API 基础层
+- 后台登录与基础管理页
+- 商家 / 商品 / 订单基础管理
+
+## 建议的下一步顺序
+1. 管理员权限与角色模型
+2. 商品分类 / 订单明细表
+3. 后台商家隔离基础（按 merchant_id 过滤）
+4. API token / Sanctum 或 JWT 方案
+5. 微信登录与支付配置表
+6. 系统配置中心（站点、支付、渠道参数）
+
+## 当前原则
+- 先补结构与底座
+- 再做功能细节
+- 最后做美化与体验
--- a/docs/ORDER_TENANT_PAGINATION_AND_ERRORS.md
+++ b/docs/ORDER_TENANT_PAGINATION_AND_ERRORS.md
@@ -0,0 +1,38 @@
+# 订单 / 站点分页与错误提示增强
+
+## 本轮完成
+
+### 分页接入
+已完成分页（每页 10 条）：
+- 商家订单列表
+- 总台订单列表
+- 总台站点列表
+
+### 缓存 key 扩展
+新增分页缓存 key：
+- `merchant:{merchantId}:orders:list:page:{page}`
+- `platform:orders:list:page:{page}`
+- `platform:merchants:list:page:{page}`
+
+### 失效策略
+- 商家订单状态更新：清理商家订单列表前 5 页缓存 + 商家仪表盘缓存
+- 总台订单状态更新：清理总台订单列表前 5 页缓存 + 总台仪表盘缓存
+- 新增站点：清理总台站点列表前 5 页缓存 + 总台仪表盘缓存
+
+### 页面错误提示
+已在两个后台 layout 中统一加入表单错误展示：
+- 总台管理 layout
+- 商家后台 layout
+
+现在后端 `validate()` 失败后，页面顶部会统一显示错误列表，不再只是跳回页面却看不清错在哪里。
+
+## 当前意义
+- 后台主要列表已逐步摆脱“一次性全量加载”的演示模式
+- 缓存与分页继续保持同步设计
+- 页面交互体验开始补齐基本可用性
+
+## 下一步建议
+1. 给商品 / 分类 / 站点创建表单补 old() 回填
+2. 给配置页面增加编辑保存能力
+3. 继续把总台订单和商家订单加入筛选条件（状态 / 平台 / 时间）
+4. 逐步把分页缓存失效从“前 5 页”升级为版本号式 key 方案
--- a/docs/PAGINATION_AND_VALIDATION_PROGRESS.md
+++ b/docs/PAGINATION_AND_VALIDATION_PROGRESS.md
@@ -0,0 +1,39 @@
+# 分页与分类唯一性校验推进
+
+## 本轮完成
+
+### 分类唯一性校验
+- 商家后台商品分类：按 `merchant_id + slug` 做唯一性校验
+- 总台管理商品分类：同样按商家维度校验 `slug` 唯一
+- 已补充更友好的中文报错文案
+- 分类编辑时也支持修改 slug，并保持唯一性约束
+
+### 分页接入
+已将以下列表切为分页（每页 10 条）：
+- 商家商品列表
+- 总台商品列表
+- 商家分类列表
+- 总台分类列表
+- 商家用户列表
+
+### 分页缓存 key 调整
+缓存 key 已按页码区分，例如：
+- `merchant:{merchantId}:products:list:page:{page}`
+- `platform:products:list:page:{page}`
+- `merchant:{merchantId}:categories:list:page:{page}`
+- `platform:categories:list:page:{page}`
+- `merchant:{merchantId}:users:list:page:{page}`
+
+### 缓存失效策略同步升级
+当商品 / 分类发生变更时，当前会尝试清理前 5 页的分页缓存，并同步清理相关统计缓存。
+
+## 当前意义
+- 列表页开始具备面向真实数据规模扩展的能力
+- 分类 slug 不再容易出现同商家冲突
+- Redis 缓存与分页结构已开始联动，而不是停留在单页列表阶段
+
+## 下一步建议
+1. 继续给订单列表和站点列表补分页
+2. 给分类 / 商品创建与更新操作增加表单错误提示展示
+3. 配置页开始做编辑能力与缓存刷新
+4. 后续将“清理前 5 页缓存”升级为更稳的版本号式 key 或集中失效策略
--- a/docs/PLATFORM_CONTEXT_AND_CATEGORY_PLAN.md
+++ b/docs/PLATFORM_CONTEXT_AND_CATEGORY_PLAN.md
@@ -0,0 +1,50 @@
+# 总台上下文封装与分类管理推进
+
+## 本轮完成
+
+### 总台上下文封装
+- 新增 `App\Http\Controllers\Concerns\ResolvesPlatformAdminContext`
+- 总台管理控制器开始统一通过该 trait 获取总台管理员上下文
+- `AdminAuth` 已改为从数据库校验 `admin_id` 对应管理员是否仍具备总台权限
+- `Admin` 模型新增 `platformLabel()`，统一总台 / 商家标识输出
+
+### 总台缓存第一阶段
+已接入缓存：
+- 总台仪表盘统计
+- 总台站点列表
+- 总台商品列表
+- 系统配置列表
+- 渠道 / 支付 / 站点概览聚合数据
+
+新增总台缓存 key：
+- `platform:dashboard:stats`
+- `platform:merchants:list`
+- `platform:products:list`
+- `platform:settings:system`
+- `platform:settings:channels`
+
+### 分类管理
+#### 商家后台
+- 新增 `/merchant-admin/product-categories`
+- 支持分类列表 / 新增 / 更新 / 删除
+- 分类变更后自动清理商家商品列表缓存和商家仪表盘缓存
+
+#### 总台管理
+- 新增 `/admin/product-categories`
+- 支持跨商家查看分类、创建分类、更新分类、删除分类
+- 总台商品页面已支持分类选择与商家校验
+
+### 总台订单展示增强
+- 总台订单列表已显示站点信息
+- 总台订单详情已显示订单明细
+
+## 当前意义
+- 总台管理已不再只是“能用”，开始形成更稳定的上下文解析层
+- 商家后台的分类结构已从“只读展示”升级为“可运营维护”
+- Redis 使用范围已从商家侧扩展到总台侧
+
+## 建议下一步
+1. 给分类增加唯一性校验与更友好的错误提示
+2. 给总台商品 / 订单列表增加分页
+3. 总台、站点、商家三层后台进一步补权限颗粒（owner / operator / viewer）
+4. 给配置页增加编辑能力并补审计日志
--- a/docs/REDIS_CACHE_PLAN.md
+++ b/docs/REDIS_CACHE_PLAN.md
@@ -0,0 +1,40 @@
+# Redis 缓存接入计划
+
+## 当前阶段
+- 默认缓存驱动已切换为 `redis`
+- 优先接入商家后台高频读场景
+  - 商家仪表盘统计
+  - 商家商品列表
+
+## 当前缓存 Key 设计
+- `merchant:{merchantId}:dashboard:stats`
+- `merchant:{merchantId}:products:list`
+
+配合 `.env` 中的：
+- `CACHE_STORE=redis`
+- `CACHE_PREFIX=saasshop-cache-`
+
+实际 Redis 中最终 key 会叠加 Laravel 前缀，避免与其他项目冲突。
+
+## TTL 策略
+- 商家仪表盘统计：10 分钟
+- 商家商品列表：10 分钟
+
+## 失效策略
+- 商品新增 / 更新 / 删除：
+  - 清理 `merchant:{merchantId}:products:list`
+  - 清理 `merchant:{merchantId}:dashboard:stats`
+- 订单状态更新：
+  - 清理 `merchant:{merchantId}:dashboard:stats`
+
+## 设计原则
+1. key 必须带 merchant 维度，避免跨商家串缓存
+2. 优先缓存读多写少页面，不先缓存复杂写流程
+3. 失效优先正确，再追求更细粒度
+4. 后续可扩展：分类列表缓存、总台管理统计缓存、配置缓存预热
+
+## 下一步建议
+1. 给商品分类列表增加单独缓存
+2. 给总台管理仪表盘增加缓存层
+3. 评估是否引入 tag（如果后续缓存驱动与场景需要）
+4. 后续把订单列表也纳入缓存，但要先设计分页和筛选条件 key 规范
--- a/docs/SITE_ADMIN_PLAN.md
+++ b/docs/SITE_ADMIN_PLAN.md
@@ -0,0 +1,230 @@
+# 站点后台最小落地方案（第一阶段）
+
+## 目标
+在当前已存在 **总台管理（/admin）** 与 **商家后台（/merchant-admin）** 的基础上，新增一层 **站点后台（/site-admin）**，让业务结构从“总台 + 商家”演进到更清晰的四级结构：
+
+- 总台管理
+- 站点后台
+- 商家后台
+- 买家侧前台 / 多端
+
+第一阶段目标不是一次性做完整第三套后台，而是先把 **信息架构、路由骨架、权限边界、最小可见页面** 搭起来，避免后续继续把“站点”只当成总台里的一个列表概念。
+
+---
+
+## 当前判断
+
+### 1. 现有 `Merchant` 可作为第一阶段“站点承接层”
+当前系统中的 `Merchant` 已经关联：
+- 管理员
+- 用户
+- 商品
+- 订单
+- 商品分类
+- 导入历史
+
+因此第一阶段无需立刻新增 `sites` 表或把所有 `merchant_id` 重构为 `site_id`。
+
+### 2. 第一阶段采用“显示层先站点化，底层暂借 Merchant 承接”
+建议策略：
+- **对外显示 / 页面文案 / 信息架构**：使用“站点”口径
+- **底层代码 / 数据库 / 外键字段**：暂时保留 `Merchant / merchant_id / merchants`
+
+这样可以在不打散现有稳定基线的前提下，先把“站点后台”独立成一层真实后台。
+
+---
+
+## 推荐落地方式
+
+### 新增独立后台前缀
+建议新增：
+- 登录页：`/site-admin/login`
+- 后台首页：`/site-admin`
+
+而不是继续把站点能力塞在 `/admin/merchants` 页面里硬扩。
+
+### 原因
+如果继续只放在 `/admin/merchants`：
+- 它更像总台中的一个管理页面
+- 难以形成独立后台边界
+- 后续站点仪表盘、站点商品、站点订单、站点商家治理容易继续堆在总台下，结构会越来越混
+
+新增 `/site-admin` 的收益：
+- 总台 / 站点 / 商家 三层后台职责更清晰
+- 权限边界更容易测试
+- 路由与布局更稳定，后续扩页面更自然
+- 可先做骨架，后续逐页填能力
+
+---
+
+## 第一阶段职责边界
+
+### 总台管理（/admin）
+面向平台运营方，负责：
+- 平台级配置
+- 多站点治理
+- 全站点级巡检与统计
+- 站点开通 / 状态维护
+- 渠道与系统能力
+
+### 站点后台（/site-admin）
+面向站点运营方，负责：
+- 当前站点仪表盘
+- 当前站点范围的商品巡检
+- 当前站点范围的订单监控
+- 当前站点范围的商家管理
+- 站点级运营入口与治理入口
+
+### 商家后台（/merchant-admin）
+面向商家经营方，负责：
+- 当前商家商品经营
+- 当前商家订单处理
+- 当前商家用户查看
+- 当前商家导入导出与日常运营
+
+---
+
+## 第一阶段建议页面
+
+### 必做骨架页
+1. `/site-admin/login` - 站点后台登录页
+2. `/site-admin` - 站点仪表盘
+3. `/site-admin/merchants` - 站点商家管理（占位 / 首版列表）
+4. `/site-admin/products` - 站点商品巡检（占位 / 首版列表）
+5. `/site-admin/orders` - 站点订单监控（占位 / 首版列表）
+
+### 可后置
+- `/site-admin/users`
+- `/site-admin/product-categories`
+- `/site-admin/settings/*`
+- `/site-admin/products/import-histories`
+
+第一阶段重点是把后台层级立起来，不要求所有运营能力一次补齐。
+
+---
+
+## 第一阶段技术实现建议
+
+### 1. 路由
+建议新增路由分组：
+- `Route::prefix('site-admin')`
+- 登录 / 退出登录
+- `Route::middleware('site.admin.auth')`
+
+### 2. 控制器命名空间
+建议新增：
+- `App\Http\Controllers\SiteAdmin\AuthController`
+- `App\Http\Controllers\SiteAdmin\DashboardController`
+- `App\Http\Controllers\SiteAdmin\MerchantController`
+- `App\Http\Controllers\SiteAdmin\ProductController`
+- `App\Http\Controllers\SiteAdmin\OrderController`
+
+第一阶段可复用总台控制器中的部分查询逻辑，但不要直接共用视图布局。
+
+### 3. 视图目录
+建议新增：
+- `resources/views/site_admin/layouts/app.blade.php`
+- `resources/views/site_admin/auth/login.blade.php`
+- `resources/views/site_admin/dashboard.blade.php`
+- `resources/views/site_admin/merchants/index.blade.php`
+- `resources/views/site_admin/products/index.blade.php`
+- `resources/views/site_admin/orders/index.blade.php`
+
+### 4. 中间件与上下文
+建议新增：
+- `App\Http\Middleware\SiteAdminAuth`
+- `App\Http\Controllers\Concerns\ResolvesSiteContext`
+
+第一阶段建议：
+- session 中新增 `admin_scope = site`
+- session 中预留 `admin_site_id`
+- 在底层尚未拆 `sites` 表之前，可暂时把 `admin_site_id` 映射到当前 `merchant_id` 或映射到“当前选中站点”上下文
+
+---
+
+## 第一阶段数据策略
+
+### 结论
+**不立刻改表，不立刻拆实体。**
+
+当前继续沿用：
+- `merchants`
+- `merchant_id`
+- `Merchant` 模型
+
+同时在设计上约定：
+- 第一阶段 `Merchant` = 站点承接层
+- 第二阶段如需独立“站点 -> 商家”两层实体关系，再单开数据结构重构方案
+
+这样做的优点：
+- 不打断现有商品 / 订单 / 分类 / 导入历史闭环
+- 不破坏当前测试基线
+- 可以先把三层后台信息架构跑起来
+
+---
+
+## 第一阶段账号与权限建议
+
+### 建议新增角色语义
+- 总台管理员：平台级
+- 站点管理员：站点级
+- 商家管理员：商家级
+
+### 第一阶段最小实现建议
+现阶段先不做完整 RBAC，先做边界：
+- 总台管理员不能登录站点后台（除非显式赋权）
+- 商家管理员不能登录站点后台
+- 站点管理员不能进入总台管理
+- 站点管理员进入站点后台后，所有查询都受当前站点作用域限制
+
+---
+
+## 第一阶段测试建议
+
+新增 Feature 测试：
+1. `SiteAdminAccessTest.php`
+   - 站点后台登录页可访问
+   - 站点管理员可登录 `/site-admin`
+2. `SiteAdminProtectedPagesTest.php`
+   - 未登录访问 `/site-admin/*` 跳转 `/site-admin/login`
+   - 错作用域账号访问返回 403
+3. `SiteAdminBusinessPagesTest.php`
+   - 仪表盘 / 站点商家 / 站点商品 / 站点订单页可访问
+   - 页面关键标题与入口存在
+
+---
+
+## 推荐实施顺序
+
+### 第 1 步
+先搭骨架：
+- route
+- controller
+- middleware
+- layout
+- login
+- dashboard
+
+### 第 2 步
+补最小站点业务页：
+- merchants
+- products
+- orders
+
+### 第 3 步
+补访问测试与权限边界测试
+
+### 第 4 步
+再决定是否把总台 `/admin/merchants` 页面逐步改造成“站点入口页 / 站点开通页”
+
+---
+
+## 当前推荐结论
+
+**站点后台应正式提上，且推荐以 `/site-admin` 作为独立后台层新增；第一阶段先复用 `Merchant` 作为站点承接层，不急着动数据库实体拆分。**
+
+这条路线最符合当前项目节奏：
+- 先打底
+- 先把层级立住
+- 先保证稳定
+- 再逐步把站点能力做实