# Xisoa — 时尚档案（Fashion Archive）

记录走秀（runway looks）与街拍（street style）的时尚档案站。前端为 **Astro**（列表静态生成，详情页走按需 SSR），
数据来自独立的 **Go 后端 + PostgreSQL（pgvector）**，两者各自独立仓库、通过 Docker Compose 一起上线。

## 技术栈

| 层 | 选型 |
| --- | --- |
| 前端框架 | Astro 7（`@astrojs/node` standalone，详情页按需 SSR） |
| 构建 | Vite 8（Rolldown） |
| 样式 | Tailwind CSS v4 |
| 交互 | Alpine.js（导航菜单、登录弹窗、收藏、灯箱等轻量交互） |
| 轮播 | Swiper |
| 后端 | Go + Gin + GORM + PostgreSQL 16 + pgvector（独立仓库 `../backend`） |
| 图片存储 | 缤纷云 S4（对象存储，不落服务器磁盘） |
| 部署 | Docker Compose，蓝绿双槽 + 常驻 nginx，零停机发布（**部署入口在后端仓**） |

## 目录结构

```
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
```

本仓库只负责前端构建产物（`Dockerfile` 只跑 Astro node server）。代理、数据库、发布脚本都在后端仓。

## 环境与配置

- **非密配置**：`src/lib/config/env.dev.ts`（dev）与 `env.prod.ts`（prod），按 `import.meta.env.PROD` 自动选择。
  - `baseApi`：浏览器运行期 API 基址（生产为空串 = 同源 `/api`）。
  - `baseApiSsr`：运行期 SSR 取数基址，可用环境变量 `BASE_API_SSR` 覆盖（容器内必须是 `http://proxy:18090`）。
  - `baseApiSsg`：构建期 SSG 内部端口基址，可用 `BASE_API_SSG` 覆盖（Docker 构建时走 `127.0.0.1:18091`）。
  - `idleLogoutDays` / `siteName`。
- **密钥**：不进 `config`（会打包进客户端 bundle），仅走构建期 env，例如 `SSG_TOKEN`。

## 本地开发

```bash
npm install
npm run dev      # http://localhost:4321
```

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

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 本地开发 |
| `npm run build` | 构建到 `./dist/` |
| `npm run preview` | 预览构建产物 |
| `npm run check` | 类型 / 模板检查 |

## 国际化

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

## 部署

部署入口在**后端仓**，完整说明见 `../backend/DEPLOY.md`：

```bash
cd /opt/fashion/backend
./deploy.sh all      # 会自动把前端仓一起拉到位并构建
```