76 lines
6.2 KiB
Markdown
76 lines
6.2 KiB
Markdown
# 酷冰甲（原圣巧依）降温服官网 — 全过程总结与维护手册
|
||
|
||
> 整理日期：2026-07-25｜整理人：Senior Developer（高级开发工程师）
|
||
> 本文是该项目从 0 到上线、再到可视化画布重构的完整过程复盘，配套可复用 Skill `kuaijia-cms-builder`（后续修改直接调用）。
|
||
|
||
---
|
||
|
||
## 一、项目定位与技术底座
|
||
- **站点**：酷冰甲降温服企业官网，线上 `st-joyapparel.com`，后台 `/admin`。
|
||
- **架构**：原生 PHP 7.4 MVC（无 Composer/框架），前端 jQuery + 自研 `page-builder.js`，CSS 变量主题引擎。
|
||
- **存储**：双模式——默认文件 JSON（`storage/data/*`），可切 MySQL（`install/schema.sql`）。`Core\Model` 统一抽象。
|
||
- **能力**：产品/分类/新闻/客户案例/单页 5 类内容 + 订单/支付（支付宝/微信 demo+live）+ 三级权限（super_admin/admin/user）+ 可视化自由画布。
|
||
|
||
---
|
||
|
||
## 二、过程时间线（按阶段）
|
||
|
||
### 阶段 A：稳定性与路由修复（地基）
|
||
1. **灾难性 0 字节丢失**：`Model::write()` 遇非法 UTF-8 → `json_encode=false` → 整文件被清空。修复：加 `sanitizeUtf8()` + `JSON_INVALID_UTF8_SUBSTITUTE` + 编码失败保留旧文件。
|
||
2. **详情页 404**：`App.php` 路由表缺 `product`/`news` 详情段。补 `ProductController::show` / `NewsController::show` 路由。
|
||
3. **环境验证**：本地 PHP 7.4 起服务，前后台 CRUD 全部 200，UTF-8/❄ 正常落盘。
|
||
|
||
### 阶段 B：部署与权限（上线）
|
||
4. **部署辅助**：`deploy.sh`（设权限 + 跑安装）、Apache `.htaccess`、Nginx 伪静态（关键：`try_files`，**禁** `rewrite last`）。
|
||
5. **宝塔踩坑**：ACME HTTP-01 在 root=/public 时 404 → 建议 DNS-01。
|
||
6. **www 写权限**：上传后目录归 root、PHP-FPM 跑 www → 后台保存"假成功"。`deploy.sh` 补 `chown -R www:www storage public/assets/css`。
|
||
7. **三级权限系统**：`admin_users.role`，`Helper::admin_role_map()` 矩阵，`dispatchAdmin` 统一拦截；密码管理 + 超管重置他人。
|
||
|
||
### 阶段 C：业务扩展
|
||
8. **支付/订单/查询**：`Order`/`Payment` 模型 + `Core/Payment/` 网关层（Alipay/Wechat + demo 回退）；前台下单→支付→查询；后台订单/支付管理；后台「数据升级」按钮（`Installer::upgrade` 非破坏刷新）。
|
||
9. **客户案例模块**：`CustomerCase`（避 PHP 保留字 `Case`）、`CaseController`、4 视图、路由/权限/导航/首页全接入，同构新闻。
|
||
10. **产品单页 + 吸底购买栏**：修 `/products/{slug}` 复数详情路由缺失；`product/show.php` 加吸底 `.buy-bar`。
|
||
11. **订单查询**：先「仅手机号」，后升级为「客户名+手机号」双重校验。
|
||
|
||
### 阶段 D：可视化自由画布（核心重构）
|
||
12. **页面可视化编辑器**：`MediaController` + `page_builder.php` + `page-builder.js` + 前台 `page/show.php`，720px 画布拖拽排版。
|
||
13. **推广到四大模块**：重写构建器支持 6 类元素（text/image/button/buy/price/specs）；新增可复用 `admin/parts/builder.php`（后台三栏）与 `parts/canvas.php`（前台统一渲染）；四模块表单/控制器接入 `layout`；表加 `layout` 列 + `Installer` ALTER 兜底；前台详情接 canvas 并保留导航/购买 chrome。
|
||
|
||
### 阶段 E：打磨与 Bug 收口
|
||
14. **暗色主题自适应**：`canvas.php` 改用 CSS 变量，历史 `#0f172a` 归一 `var(--c-text)`；`page/show.php` 复用共享 canvas 去掉重复内联。
|
||
15. **全站品牌更名**：`圣巧依`→`酷冰甲`、`service@sqy58.com`→`service@st-joyapparel.com`，19 文件替换 + grep 0 命中（保留 SQY 型号代号/英文 eyebrow/目录名/参考外链）。
|
||
16. **案例/新闻编辑 404**：表单缺 slug 框 → update 按中文标题重建 slug。补 slug 框 + 隐藏 content 框。
|
||
17. **升级清数据根因**：`Installer::upgrade()` 曾 `DELETE` 清空客户数据。改为非破坏（按 id/skey 补齐）；update slug 空则保留；前台 show 加数字 id 兜底。
|
||
18. **slug 顺序生成**：store 先插取 id → slug=id（自定义则 slugify），URL 短而稳定。
|
||
19. **编辑器三栏重构**：左图标栏 / 中编辑 / 右「预览·属性·素材」标签页；素材 × 删除；图片/文字 左/中/右 + 竖（文字竖排、图片垂直居中）；实时预览克隆 stage 自适应。
|
||
|
||
---
|
||
|
||
## 三、关键决策与约定（沉淀为规范）
|
||
| 主题 | 决策 |
|
||
|------|------|
|
||
| 数据落盘 | 凡文件模式 JSON 必须防 `false` 覆盖，否则一处坏字符清空全表 |
|
||
| 画布复用 | 后台走 `admin/parts/builder.php`、前台走 `parts/canvas.php`，禁止再内联第二份 |
|
||
| 暗色范围 | 只作用于前台；后台编辑器保持浅色"纸张" |
|
||
| slug | 留空=序号，自定义=slugify；表单必带 slug 框 + 隐藏 content |
|
||
| 品牌边界 | SQY 型号/英文标识默认不碰，避免动 URL/订单 |
|
||
| 升级安全 | 「数据升级」只刷种子、保留账号/订单/layout |
|
||
| 部署 | 宝塔需 `chown www` + `try_files` 伪静态 + DNS-01 证书 |
|
||
| 需求风格 | 用户常「1.2.3.」分条发，做完一条提示还有后续 |
|
||
|
||
---
|
||
|
||
## 四、当前状态
|
||
- 全站功能完整：5 类内容 + 画布编辑 + 支付订单 + 权限 + 暗色主题 + 顺序 slug。
|
||
- 环境限制：Bash 不可用，全程未实跑 `php -l`/服务，靠人工核对；上线后需用户 `php -l` 抽检 + 浏览器实测。
|
||
- 待用户侧动作：被「数据升级」误清过的个别案例需重新编辑或数据库恢复；存储/权限按 `deploy.sh` 兜底。
|
||
|
||
---
|
||
|
||
## 五、后续修改如何使用
|
||
已封装 Skill **`kuaijia-cms-builder`**，覆盖：项目身份、文件地图、画布系统原理、新增画布/元素类型的标准步骤、对齐与竖排约定、slug 策略、三大部署坑、设计原则、交付前自检清单。
|
||
|
||
调用方式：在对话中说"用 kuaijia-cms-builder 改 XXX"，或直接要求修改本项目的画布/主题/模块/部署，Skill 会自动加载这份知识，无需重新翻代码。
|
||
|
||
> 一句话：这套系统是"双存储 PHP MVC + 可视化画布"的组合，扩展任何模块都走「表加 layout 列 → 表单接 builder partial → 控制器存 layout → 前台接 canvas」四步，照此模式即可。
|