入门引导

本页即 /guide，与仓库根目录 README.md 同步维护：环境变量、路由表、部署要点以 README 为准；此处便于在运行中的站点内直接阅读。

1. 项目是什么

  • SSR：Node 端用 EJS 拼 HTML 再返回，首屏不依赖浏览器再打一轮接口。
  • BFF：/bff/* 返回 JSON，演示「给前端用的聚合接口」；当前与 SSR 共用 src/services/，便于对照。
  • EJS：模板在 views/；express-ejs-layouts 把页面正文注入布局 <%- body %>；片段用 include。
  • 数据源：商品与横幅在仓库 data/*.json；SSR 与 BFF 经 catalog / promotions 读同一文件。
  • 模板工作室 / 数据源页（开发默认开管理端）：/admin/templates 改 EJS；/admin/datasource 改 JSON 并预览 SSR（详见下文）。

2. 本机命令

需先 pnpm install。常用：

  • pnpm start → node src/server.js
  • pnpm run dev → node --watch src/server.js
  • pnpm run check → 模板编译 + 内存 HTTP 自检

默认端口 3000；生产/云平台用环境变量 PORT。

3. 环境变量（与 README 一致）

  • PORT：HTTP 端口。
  • NODE_ENV=production：视图缓存、错误页脱敏。
  • TEMPLATE_STUDIO=1：在生产也挂载工作室（/admin/*、/api/templates/*）。
  • ALLOW_TEMPLATE_PUBLISH=1：允许工作室写回 views/（慎用）。
  • ALLOW_DATA_STORE_WRITE=1：生产环境允许通过 API 写回 data/*.json；开发模式默认可写。

4. 建议浏览顺序

  1. 你已在本页；可选再看 关于（默认带管理端浏览器内开启参数）。
  2. 首页：横幅、精选商品、链到 BFF。
  3. 商品列表 → 进入某一 详情。
  4. 新标签打开 GET /bff/products，对比列表数据形态。
  5. 表单演示：?q= 与 POST，观察 SSR 回显。
  6. （工作室开启时）/admin/templates 模板工作室；/admin/datasource 编辑 data/*.json（有写权限时约 0.5s 停手自动保存，可手动保存），右侧预览会拉最新 HTML 并优先只更新各 iframe 内 #main。
  7. 任意 SSR 页顶栏在管理端开启时会出现 模板工作室、数据源 入口（与 app.locals.templateStudioEnabled 一致）。

5. 路由速查

SSR：/guide、/、/products、/products/:id、/about、/demo/form。

BFF：GET /bff/home、/bff/products、/bff/products/:id。

数据源（始终）：GET /api/data/store/meta、/api/data/store/products、/api/data/store/banners；写回对应 PUT 在生产需 ALLOW_DATA_STORE_WRITE=1。磁盘文件：data/products.json、data/banners.json。

工作室（开启时）：GET /admin/templates、GET /admin/datasource；API /api/templates/registry、…/source、POST …/preview、POST …/:id/publish（发布需 ALLOW_TEMPLATE_PUBLISH=1）。

6. 入口文件

  • src/app.js — createApp()，不含 listen；并设置 app.locals.templateStudioEnabled 供顶栏是否显示管理端链接。
  • src/server.js — createApp() + listen(PORT)。

7. 模板与数据源

  • 模板工作室：public/admin/studio.html + js/studio-app.js 等；路由 src/routes/admin/template.route.js；API src/routes/api/template-studio.router.js。预览在服务端执行 EJS，结果写入 iframe.srcdoc（整份预览文档替换；模板结构各异，未做固定 DOM 差量更新）。
  • 数据源页：public/admin/datasource.html + js/datasource-app.js；路由 src/routes/admin/datasource.route.js；HTTP src/routes/api/data-store.router.js；读写 src/data-store/json-files.js、校验 validate.js。防抖间隔见脚本内 AUTO_SAVE_DEBOUNCE_MS（默认约 500ms）。
  • 业务层 catalog / promotions 只读 JSON，实现模板与展示数据分离；勿对公网暴露未鉴权的管理端。
  • 顶栏导航片段：views/partials/header.ejs。

8. 部署

根目录 Dockerfile（Node 22 + pnpm），CMD node src/server.js。Railway 等平台注入 PORT 即可。完整说明见 README。

9. 代码地图

  • src/routes/README.md — 路由命名与挂载约定。
  • src/routes/pages/*.route.js — 各 SSR 页。
  • src/routes/bff.router.js — BFF JSON。
  • src/data-store/ — 数据源 JSON 与校验。
  • src/ejs-helpers.js — currency、truncateWords 等 app.locals。