# 服务配置说明

支付、PocketBase、MinIO 存储已组件化、配置化，可通过环境变量和主题配置覆盖。

## 配置入口

- **`config/services.config.ts`** - 服务配置
- **`config/site.config.ts`** - 主题可覆盖 `services` 字段

## PocketBase

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `NEXT_PUBLIC_POCKETBASE_URL` | 客户端可见的 PB 地址 | https://pocketbase.hackrobot.cn |
| `POCKETBASE_URL` | 服务端 PB 地址 | 同上 |
| `POCKETBASE_JOIN_COLLECTION` | 申请表单集合名 | solan |
| `POCKETBASE_EMAIL` | 管理员邮箱（创建记录用） | - |
| `POCKETBASE_PASSWORD` | 管理员密码 | - |

### 主题覆盖

在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：

```ts
services: {
  pocketbaseJoinCollection: "solan",  // 申请/加入表单集合
},
```

### 使用方式

```ts
import { pbLogin, pbRegister, pbSaveAuth, pbLogout, getStoredUserEmail } from "@/app/lib/pocketbase";

// 登录
const result = await pbLogin(email, password);
pbSaveAuth(result.token, result.record);

// 注册
const result = await pbRegister(email, password, passwordConfirm);
pbSaveAuth(result.token, result.record);

// 登出
pbLogout();

// 获取当前用户邮箱
const email = getStoredUserEmail();
```

## 支付

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `PAYMENT_API_URL` | payjsapi 地址 | 开发: 127.0.0.1:8700 / 生产: api.hackrobot.cn |
| `PAYMENT_PROVIDER` | 支付提供商 | zpay |
| `PAYMENT_DEFAULT_AMOUNT` | 默认金额（分） | 80 |
| `PAYMENT_DEFAULT_TYPE` | 默认订单类型 | meetup |
| `ZPAY_SUBMIT_URL` | ZPAY 提交地址 | https://zpayz.cn/submit.php |

### 主题覆盖

在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：

```ts
services: {
  join: {
    amount: 80,    // 加入费用（分）
    type: "meetup", // 订单类型
  },
},
```

### 使用方式

```ts
import {
  getPayEnv,
  getRecommendedChannel,
  mustUseWxPay,
  redirectToPay,
  getDeviceFromEnv,
} from "@/app/lib/payment";

// 检测支付环境
const env = getPayEnv();  // "pc" | "h5" | "wechat"
const channel = getRecommendedChannel(env);
const device = getDeviceFromEnv(env);

// 发起支付跳转（加入场景，使用主题配置）
redirectToPay({
  user_id: userId,
  return_url: returnUrl,
  channel,
  device,
  useJoinConfig: true,  // 使用主题的 amount/type
});
```

## MinIO 存储

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MINIO_ENDPOINT` | 服务端点 | minioweb.hackrobot.cn |
| `MINIO_PORT` | 端口 | 9035 |
| `MINIO_USE_SSL` | 是否使用 SSL | false |
| `MINIO_BUCKET` | 存储桶 | hackrobot |
| `MINIO_ACCESS_KEY` | Access Key | - |
| `MINIO_SECRET_KEY` | Secret Key | - |
| `MINIO_REGION` | 区域 | china |
| `MINIO_PUBLIC_URL` | 公开访问 URL | https://{endpoint}/{bucket} |
| `MINIO_UPLOAD_PREFIX` | 上传路径前缀 | joins |

### 主题覆盖

在 `config/site.config.ts` 的 `THEME_CONFIGS[theme].services` 中：

```ts
services: {
  minio: {
    bucket: "my-bucket",      // 存储桶
    uploadPrefix: "joins",    // 上传路径前缀
  },
},
```

### 使用方式

```ts
import {
  getMinioClient,
  uploadBuffer,
  generateObjectKey,
} from "@/app/lib/minio";

// 上传文件
const objectKey = generateObjectKey("jpg");
const { url } = await uploadBuffer(buffer, objectKey, "image/jpeg");

// 获取客户端（高级用法）
const client = getMinioClient();
```

## API 路由

- **`/api/join`** - 使用 `getPocketBaseConfig()` 和主题的 `pocketbaseJoinCollection`
- **`/api/pay`** - 使用 `getPaymentConfig()` 和 `getJoinPaymentConfig()`
- **`/api/pay/status`** - 使用 `getPaymentConfig()`
- **`/api/upload-media`** - 使用 `getMinioConfig()` 和主题的 `minio` 配置

## 目录结构

```
config/
  services.config.ts    # 服务配置
  site.config.ts        # 主题配置（含 services 覆盖）

app/lib/
  pocketbase/
    auth.ts             # 认证：login/register/logout
    constants.ts        # 存储 key
    config.ts           # 配置导出
    index.ts
  payment/
    client.ts           # redirectToPay
    config.ts           # 配置导出
    types.ts            # PayChannel, PayEnv
    index.ts            # 聚合 payEnv
  minio/
    config.ts           # 配置导出
    client.ts           # getMinioClient, uploadBuffer, generateObjectKey
    index.ts
```

## 缓存与部署更新

项目已配置 `Cache-Control: no-store, no-cache`，部署后用户应能立即看到更新。若使用 **Cloudflare**，还需在控制台调整：

### Cloudflare 控制台设置

1. **Caching → Configuration**
   - **Caching Level**：选 `Standard` 或 `Bypass`（开发/频繁更新时）
   - **Browser Cache TTL**：选 `Respect Existing Headers`，以遵循源站 `Cache-Control`

2. **Caching → Cache Rules**（可选）
   - 为 `/*` 添加规则：`Cache eligibility` = Bypass，或 `Edge TTL` = 0

3. **DNS**
   - 记录 **TTL**：设为 `1`（Auto）或 `60` 秒，加快 DNS 变更生效