# 本地部署说明（当前环境）

## 访问地址
- 应用首页：`http://192.168.10.199:9001/`
- 总台管理：`http://192.168.10.199:9001/admin/login`
- 站点后台：`http://192.168.10.199:9001/site-admin/login`
- 商家后台：`http://192.168.10.199:9001/merchant-admin/login`
- phpMyAdmin：`http://192.168.10.199:888/`

## 应用目录
- Laravel 项目：`/var/www/sites/app`

## 技术栈
- Nginx 1.22
- PHP 8.2 FPM
- MariaDB 10.11
- Redis 7
- Laravel 12

## 已配置内容
- Laravel 已接入 MySQL 数据库 `appdb`
- Laravel 已接入 Redis（缓存 / 队列）
- `9001` 已指向 Laravel `public/`
- `888` 已指向 phpMyAdmin
- 当前项目已完成总台管理、站点后台、商家后台三层后台基础骨架
- 当前数据库与代码基线已统一使用 `merchant / merchants / merchant_id` 语义

## 已实现功能概览（持续更新）

## 最近版本更新（Changelog）

### 2026-03-15
- 客服中心（工单）骨架落地（总台管理）
  - 新增：工单模型 `SupportTicket` + 表 `support_tickets`
  - 新增：`/admin/support-tickets` 工单列表占位页（后续接入列表/筛选/创建/指派）
  - 新增：总台 TopNav 菜单「客服中心」→「工单」
  - 新增 Feature 护栏：
    - `AdminSupportTicketIndexPageShouldRenderTest`
    - `AdminTopNavShouldContainSupportCenterLinkTest`

### 2026-03-15（治理链路风险点处置）
- 回滚未完成的“平台订单 attach-subscription”半成品预埋（避免脏改混入）

## 下一步开发清单（Top 5）
1) 客服中心：工单最小 CRUD（列表真实数据 + 创建）+ 基础筛选（status/priority/scope 预留）
2) 治理命中 → 一键生成工单（优先：`renewal_missing_subscription`）
3) 工单编号生成策略（ticket_no）与索引/唯一性策略落地
4) 权限与隔离：按 scope（platform/site/merchant）约束查询与操作（先平台 scope 起步）
5) 后台样式体系继续收敛（admin-components.css 组件化）

---

## 已实现功能概览（截至 2026-03-11）

### 1) 三层后台（总台/站点/商家）基础骨架
- 总台管理（`/admin`）
  - 登录 + 登录态校验中间件
  - 仪表盘与运营定位说明
  - 站点管理：列表 + 新增（基础骨架）
  - 商品巡检：列表 + 新增/更新/删除（基础骨架）
  - 订单监控：列表 + 状态更新 + 详情页（基础骨架）
  - 系统配置/渠道配置页面：已接入数据库读取（骨架）
  - 支付配置基线：已落库并在渠道配置页展示（骨架）
- 站点后台（`/site-admin`）
  - 登录
  - 站点范围内的商品/订单最小查询能力（骨架，逐步推进中）
- 商家后台（`/merchant-admin`）
  - 仪表盘统计（已接入 Redis 缓存与失效）
  - 商品：列表 + 新增/编辑/删除（含分类展示/选择）
  - 订单：列表 + 详情 + 状态更新（含订单明细）
  - 用户：列表

### 2) 商品分类 + 订单明细数据结构
- `product_categories`：商品分类表（站点维度）
- `products.category_id`：商品关联分类
- `order_items`：订单明细（多商品场景）
- Seeder：已补演示分类/商品/订单明细数据

### 3) Redis 缓存（第一阶段）
- `.env` 已切换 `CACHE_STORE=redis`
- 缓存 key 辅助类：`App\Support\CacheKeys`
- 已缓存：商家仪表盘统计、商家商品列表
- 已实现基础缓存失效：商品新增/更新/删除、订单状态更新

### 4) 商品导入失败明细留痕 + 定时清理
- 导入失败 CSV 文件保存到本地磁盘（`storage/app/private/...`）
- 总台/商家后台提供下载入口
- 已补定时清理脚本：每天东八区 `04:30` 清理 30 天前失败文件

### 5) 收费闭环（骨架已落地，持续完善中）
围绕 `plans + site_subscriptions + platform_orders` 建立“可运营可治理”的最小闭环。

- 核心表/模型/迁移
  - `plans`（套餐）
  - `site_subscriptions`（站点订阅）
  - `platform_orders`（平台订单）
- 订阅激活服务（最小闭环）
  - `SubscriptionActivationService::activateOrder()`
  - 支持：新购创建订阅；续费延长订阅到期（未过期基于 ends_at，已过期从 now 起算）
  - 幂等保护：同一订单重复同步不会重复续期（基于 meta.subscription_activation）
- 平台订单（总台治理核心页）
  - 列表：筛选/摘要卡/异常定位（回执、退款、对账差额、同步状态、失败原因 Top 等）
  - 详情：支付/退款回执留痕、退款汇总口径统一、订阅关联、同步动作、审计记录
  - 工具：导出 CSV、批量同步订阅、批量仅标记生效、清除同步失败标记（均支持筛选条件透传）
- 订阅详情（总台治理页）
  - 订阅维度治理摘要：回执/退款汇总 + 对账差额 + 同步状态聚合
  - 与平台订单列表一键联动跳转（保持筛选上下文）
  - 支持从订单/订单列表进入并回跳（back）

### 6) 测试覆盖（Feature Tests 为主）
- 平台订单：列表/详情/筛选/导出/批量工具/回执退款口径/失败原因联动
- 订阅详情：治理摘要与联动链接
- 订阅激活：续期延长口径与幂等保护

> 更详细的边界与页面清单可参考：`docs/ADMIN_BASELINE.md`、`docs/FOUNDATION_PROGRESS_2026-03-08.md`。

## 数据库连接
- DB_HOST=`127.0.0.1`
- DB_PORT=`3306`
- DB_DATABASE=`appdb`
- DB_USERNAME=`appuser`
- 密码存放于：`/app/working.secret/appdb.env`

## phpMyAdmin
- 使用 MySQL 账号登录（推荐直接用 `appuser`）
- 地址：`http://192.168.10.199:888/`

## 商品导入失败明细文件
- 商品批量导入失败明细 CSV 通过 Laravel `local` 磁盘保存
- 当前 `local` 磁盘根目录为：`/var/www/sites/app/storage/app/private`
- 总台管理失败文件目录：`/var/www/sites/app/storage/app/private/imports/product-failures/platform/`
- 商家后台失败文件目录：`/var/www/sites/app/storage/app/private/imports/product-failures/merchant_<merchant_id>/`
- 页面下载入口：
  - 总台：`/admin/products/import-failures/{file}`
  - 商家：`/merchant-admin/products/import-failures/{file}`
- 文件内容包含：`row_number + 原始导入字段 + error`
- 已补定时清理脚本：`/usr/local/bin/saasshop_import_failures_cleanup.sh`
- 当前保留策略：默认保留 30 天，每天东八区 `04:30` 自动清理一次过期 failure CSV

## 注意
- 敏感凭证不要写进公开文档或长期记忆
- 当前项目已进入 SaaS 电商基础框架阶段，后续优先继续补经营能力、配置能力与筛选能力