frontend_v2/README.md

Xisoa — 时尚档案（Fashion Archive）

记录走秀（runway looks）与街拍（street style）的时尚档案站。前端为 Astro 静态站， 数据来自独立的 Go + MySQL 后端（走秀/街拍列表、详情、收藏、历史等）。

技术栈

层	选型
前端框架	Astro 7（静态输出，详情页走 @astrojs/node 按需 SSR）
构建	Vite 8（Rolldown）
样式	Tailwind CSS v4
交互	Alpine.js（导航菜单、登录弹窗、收藏、灯箱等轻量交互）
轮播	Swiper
后端	Go + MySQL（独立仓库，不在本仓库内）
部署	Docker Compose + nginx（见 DEPLOY.md）

目录结构

src/
├── components/           # 通用组件（卡片、灯箱、弹窗、导航等）
│   └── views/            # 各页面主体（Home / RunwayLooks / StreetSnaps / Login / Account ...）
├── layouts/
│   └── Layout.astro      # 全站布局：TDK、导航、页脚、Alpine 全局组件注册
├── lib/
│   ├── api.ts            # 业务接口封装（走 request()）
│   ├── request.ts        # 唯一 HTTP 入口：签名 / locale / Bearer / 401 续期
│   ├── endpoints.ts      # 后端接口路径唯一来源（/api/v1、/api/internal/ssg）
│   ├── routes.ts         # 前端页面路由（带 locale 前缀）
│   ├── config/           # dev / prod 两份非密配置 + 必填校验
│   ├── i18n/             # 国际化：语言解析、t()、字典
│   ├── ssg.ts / ssr.ts    # 构建期 SSG / 运行期 SSR 取数
│   └── gallery.ts / favorites.ts / collection-page.ts / ...  # 业务逻辑
├── pages/                # Astro 路由（en / cn 两套 + 根重定向）
├── styles/               # global.css / look-grid.css
└── env.d.ts

环境与配置

• 非密配置：src/lib/config/env.dev.ts（dev）与 env.prod.ts（prod），按 import.meta.env.PROD 自动选择，缺项即抛异常。字段说明见 src/lib/config/types.ts：
  • baseApi：浏览器运行期 API 基址（生产为空串 = 同源 /api）。
  • baseApiSsr：运行期按需 SSR 取数基址（Node fetch 需绝对 URL）。
  • baseApiSsg：构建期 SSG 内部端口基址（仅回环，不对公网暴露）。
  • idleLogoutDays / siteName。
• 密钥：不进 config（会打包进客户端 bundle），仅走构建期 env，例如 SSG_TOKEN。

常用命令

命令	说明
npm install	安装依赖
npm run dev	本地开发，http://localhost:4321
npm run build	构建静态产物到 ./dist/
npm run preview	本地预览构建产物
npm run check	astro check：类型 / 模板检查
npm run astro ...	直接调用 Astro CLI（如 astro add）

本地运行需先启动后端：接口默认落在 localhost:8090，SSG 内部端口 localhost:8091（见 env.dev.ts）。

国际化

• 支持 en / cn，prefixDefaultLocale: true —— 两种语言都带前缀（/en/...、/cn/...）。
• 翻译字典在 src/lib/i18n/dictionary.ts，key 即英文原文，中文环境命中译文、缺失回退英文。
• 页面用 const { locale, t } = getI18n(Astro)；客户端脚本用 clientHref() 自行拼前缀。

部署

Docker Compose + Gitea Actions，前后端两个仓库联动上线。完整步骤见 DEPLOY.md。