update

README.md

@@ -1,46 +1,71 @@
-# Astro Starter Kit: Basics
+# Xisoa — 时尚档案（Fashion Archive）
 
-```sh
-npm create astro@latest -- --template basics
+记录走秀（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
 ```
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+## 环境与配置
 
-## 🚀 Project Structure
+- **非密配置**：`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`。
 
-Inside of your Astro project, you'll see the following folders and files:
+## 常用命令
 
-```text
-/
-├── public/
-│   └── favicon.svg
-├── src
-│   ├── assets
-│   │   └── astro.svg
-│   ├── components
-│   │   └── Welcome.astro
-│   ├── layouts
-│   │   └── Layout.astro
-│   └── pages
-│       └── index.astro
-└── package.json
-```
+| 命令 | 说明 |
+| --- | --- |
+| `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`） |
 
-To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
+> 本地运行需先启动后端：接口默认落在 `localhost:8090`，SSG 内部端口 `localhost:8091`（见 `env.dev.ts`）。
 
-## 🧞 Commands
+## 国际化
 
-All commands are run from the root of the project, from a terminal:
+- 支持 `en` / `cn`，`prefixDefaultLocale: true` —— **两种语言都带前缀**（`/en/...`、`/cn/...`）。
+- 翻译字典在 `src/lib/i18n/dictionary.ts`，**key 即英文原文**，中文环境命中译文、缺失回退英文。
+- 页面用 `const { locale, t } = getI18n(Astro)`；客户端脚本用 `clientHref()` 自行拼前缀。
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
+## 部署
 
-## 👀 Want to learn more?
-
-Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+Docker Compose + Gitea Actions，前后端两个仓库联动上线。完整步骤见 [`DEPLOY.md`](./DEPLOY.md)。