6.2 KiB
6.2 KiB
酷冰甲（原圣巧依）降温服官网 — 全过程总结与维护手册
整理日期：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：稳定性与路由修复（地基）
- 灾难性 0 字节丢失：
Model::write()遇非法 UTF-8 →json_encode=false→ 整文件被清空。修复：加sanitizeUtf8()+JSON_INVALID_UTF8_SUBSTITUTE+ 编码失败保留旧文件。 - 详情页 404：
App.php路由表缺product/news详情段。补ProductController::show/NewsController::show路由。 - 环境验证：本地 PHP 7.4 起服务，前后台 CRUD 全部 200，UTF-8/❄ 正常落盘。
阶段 B：部署与权限（上线）
- 部署辅助：
deploy.sh（设权限 + 跑安装）、Apache.htaccess、Nginx 伪静态（关键：try_files，禁rewrite last）。 - 宝塔踩坑：ACME HTTP-01 在 root=/public 时 404 → 建议 DNS-01。
- www 写权限：上传后目录归 root、PHP-FPM 跑 www → 后台保存"假成功"。
deploy.sh补chown -R www:www storage public/assets/css。 - 三级权限系统：
admin_users.role，Helper::admin_role_map()矩阵，dispatchAdmin统一拦截；密码管理 + 超管重置他人。
阶段 C：业务扩展
- 支付/订单/查询：
Order/Payment模型 +Core/Payment/网关层（Alipay/Wechat + demo 回退）；前台下单→支付→查询；后台订单/支付管理；后台「数据升级」按钮（Installer::upgrade非破坏刷新）。 - 客户案例模块：
CustomerCase（避 PHP 保留字Case）、CaseController、4 视图、路由/权限/导航/首页全接入，同构新闻。 - 产品单页 + 吸底购买栏：修
/products/{slug}复数详情路由缺失；product/show.php加吸底.buy-bar。 - 订单查询：先「仅手机号」，后升级为「客户名+手机号」双重校验。
阶段 D：可视化自由画布（核心重构）
- 页面可视化编辑器：
MediaController+page_builder.php+page-builder.js+ 前台page/show.php，720px 画布拖拽排版。 - 推广到四大模块：重写构建器支持 6 类元素（text/image/button/buy/price/specs）；新增可复用
admin/parts/builder.php（后台三栏）与parts/canvas.php（前台统一渲染）；四模块表单/控制器接入layout；表加layout列 +InstallerALTER 兜底；前台详情接 canvas 并保留导航/购买 chrome。
阶段 E：打磨与 Bug 收口
- 暗色主题自适应：
canvas.php改用 CSS 变量，历史#0f172a归一var(--c-text)；page/show.php复用共享 canvas 去掉重复内联。 - 全站品牌更名：
圣巧依→酷冰甲、service@sqy58.com→service@st-joyapparel.com，19 文件替换 + grep 0 命中（保留 SQY 型号代号/英文 eyebrow/目录名/参考外链）。 - 案例/新闻编辑 404：表单缺 slug 框 → update 按中文标题重建 slug。补 slug 框 + 隐藏 content 框。
- 升级清数据根因：
Installer::upgrade()曾DELETE清空客户数据。改为非破坏（按 id/skey 补齐）；update slug 空则保留；前台 show 加数字 id 兜底。 - slug 顺序生成：store 先插取 id → slug=id（自定义则 slugify），URL 短而稳定。
- 编辑器三栏重构：左图标栏 / 中编辑 / 右「预览·属性·素材」标签页；素材 × 删除；图片/文字 左/中/右 + 竖（文字竖排、图片垂直居中）；实时预览克隆 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」四步，照此模式即可。