# 项目长期记忆（Project MEMORY.md） > 维护约定：本文件只放**跨会话长期有效**的事实与铁律；当日细节写 `.workbuddy/memory/YYYY-MM-DD.md`。 > 历次合并去重：2026-09-14（修正 BASE_API 位置、ROUTES.article、ssgRequest、Raleway、View Transitions 等过时记述；补 gallery/灯箱与 Alpine 展开推断坑）。 ## 架构总览 - 前端 `d:/project/frontend_v2`：Astro（`adapter: node` standalone，SSR 运行时取数）+ Tailwind v4 + Alpine.js。构建 `npm run build`；类型检查 `npm run check`（= `astro check`）。SSG 取数走 `requestSsg`（src/lib/request.ts），失败 `null` 回落不影响构建。 - 后端 `d:/project/backend_v2`：Go + Gin + GORM(MySQL)。公开引擎 :8090（`/api/v1/public/*`、`/api/v1/auth/*`）；SSG 引擎 :8091（仅 127.0.0.1，nginx 不反代）。 - 接口 i18n：后端按 `?locale=cn|en` 选列；前端取数复用带 locale 原语（`request` / `requestSsg`），**绝不裸写 fetch**；语言以 URL 前缀为准。 - **base 地址全在 `src/lib/config/`（目录）**：`index.ts` 导出 `config`（`validate(isProd?prod:dev)`）、`types.ts`、`env.dev.ts`/`env.prod.ts`。三把址：`config.baseApi`（浏览器运行期）/ `config.baseApiSsr`（SSR 绝对 URL）/ `config.baseApiSsg`（构建期内部端口）。**全站无直接 `import.meta.env.BASE_API` 读取**（值硬编码在 env.*.ts，**不在 `.env`**）。密钥类（`SSG_TOKEN`）故意直读 env，不进客户端 bundle。 - **后端编译产物坑（Windows）**：`go build -o server-bin ./cmd/server` 实际产出无扩展名 `server-bin`，但运行的是 `server-bin.exe`。必须 `go build -o server-bin.exe` 显式覆盖，再 `Start-Process server-bin.exe`；杀进程 `(Get-NetTCPConnection -LocalPort 8090).OwningProcess`。本地后端长空闲报 `invalid connection` 先重启后端（连接池 `conn_max_idle_time` 须 < MySQL `wait_timeout`）。 - 前端 dev server **不热加载 `.env`**：改 base 后 `astro dev stop`+`astro dev --background`；浏览器旧 bundle 硬刷新、旧 token 失效重登录。 - **`504 (Outdated Optimize Dep)` 修法**：动过 `package.json` 依赖后 Vite 会重新预打包，哈希变了而浏览器仍攥着旧哈希 → 控制台报 `GET /node_modules/.vite/deps/xxx.js 504 (Outdated Optimize Dep)`。修：`astro dev stop` → 删 `node_modules/.vite` → `astro dev --background` → 浏览器**硬刷新**（Ctrl+Shift+R）。 - 报错里的 **`audit-*.js` 是 Astro 开发工具栏的 chunk**，只在 dev 存在，与站点代码无关，生产构建没有。 - 控制台里 `Images loaded lazily and replaced with placeholders. Load events are deferred.` 是 **Chrome DevTools 的提示**（开着 Network/Performance 面板时会把懒加载图临时换成占位图并推迟 load 事件），**不是错误**。 ## 关键约定 - 视觉：黑白极简编辑风（monospace 小标签 + 宽字距 + 细线 + 直角），**纯黑白，禁用暖米色/柔和阴影**；字体全走 Tailwind 体系。 - 品牌名前端只显英文（`display=nameEn`）；走秀标题/描述按 locale 选列。 - API 命名：一个功能一个接口，跨资源/独立功能独立路径（如 `brands/hot` 而非 `?featured=1`）。 - CSS：能 @apply 就 @apply；`