# AGENTS.md — @app/web

## 职责

**薄 SSR** Astro 前端（Node standalone）：布局 / head / SEO / 中间件服务端渲染；页面主体为 React 客户端组件（`client:load`）。另含 tRPC HTTP 适配、SEO 文本端点、**i18n 路由**。

产品页面：首页、鉴权、仪表盘、媒体库 / 浏览 / 播放 / 挂载 / 弹幕设置与错误页。视觉遵循仓库根 `DESIGN.md` 与 `@app/design-tokens`。

## i18n

- 语言：`zh-CN`（`/zh-CN/...`）、`en`（`/en/...`）。**中文也带前缀**，不把中文留在裸 `/`。
- **单套路由**：`src/pages/[locale]/...` + `src/views/*`；禁止再复制 `pages/zh-CN`、`pages/en` 目录。
- 文案：`@app/i18n` 的 `t(locale, key)`；React island 传 `locale` prop，不引入 i18next。
- 裸 `/`：`src/middleware.ts` 按 cookie `app-lang` → `Accept-Language` 跳 `/zh-CN` 或 `/en`；响应 `Vary: Accept-Language`；非法/大小写 `zh-cn` 规范化。
- 手动切换：header 语言链接写 cookie 后跳转（布局内联脚本）。
- 设计说明：`docs/superpowers/specs/2026-09-24-i18n-design.md`。

## 结构

```
src/
  pages/
    [locale]/
      index.astro | dashboard.astro | library.astro | browse.astro
      watch.astro | mounts.astro | danmaku.astro（302→settings） | settings.astro
      auth/login.astro | auth/register.astro
      auth/forgot-password.astro | auth/reset-password.astro
    api/trpc/[...trpc].ts | api/stream.ts | api/users.ts
    sitemap.xml.ts | robots.txt.ts | llms.txt.ts | llms-full.txt.ts
    403.astro | 404.astro | 500.astro
  views/                    # SSR 壳 + seo/nav（每页一个）
    home.astro | dashboard.astro | library.astro | browse.astro
    watch.astro | mounts.astro | auth.astro | error.astro
  middleware.ts             # 裸 / 语言检测跳转 + locale 规范化
  layouts/AppLayout.astro
  components/
    pages/                  # 薄 SSR 主体（client:load）
      HomeBody.tsx | DashboardBody.tsx | LibraryBody.tsx | BrowseBody.tsx
      WatchBody.tsx | MountsBody.tsx | DanmakuSettingsBody.tsx（settings 页弹幕区块）
      AuthBody.tsx | ErrorBody.tsx
    UserList.tsx | UserMenu.tsx | ThemeSwitch.tsx | AuthForm.tsx | errors/*
  lib/
    trpc.ts | seo.ts（getSiteSeo(locale)）| nav.ts | theme.ts
    danmaku-render.ts | errors.ts | utils.ts（cn re-export）
  styles/globals.css
astro.config.ts
```

路径别名

- `~/*`、`@/*` → `src/*`
- `@app/i18n` / `@app/trpc` / `@app/types` / `@app/db` / `@app/seo-geo` → 各包 `dist`（astro.config.ts）
- `@app/ui` → `packages/ui/src`（源码直出）
- typecheck 时 tsconfig paths 指向各包 `src`——**改上游后先 build 再 dev/build web**

## 页面与 SEO（薄 SSR）

- **服务端**：`AppLayout.astro`（head、导航、脚注）、`seo` prop、middleware（locale / 鉴权跳转）、API / sitemap 等端点。
- **客户端**：`views/*` 只保留壳，主体为 `components/pages/*Body.tsx`，统一 `client:load`。
- 布局统一走 `AppLayout.astro`，必传 `locale`，通过 `seo` prop 传 `PageSeoInput`。
- 站点 SEO：`lib/seo.ts` 的 `getSiteSeo(locale)`；sitemap 双语 URL + hreflang `alternates`。
- 新公开页面：登记 `PUBLIC_PATHS` / views，并同步 `getSiteSeo` 的 `llms.pages` 与 sitemap；主体写成 `*Body.tsx`。
- 导航项集中在 `lib/nav.ts`，改菜单只动这一处。

## React islands

- 页面主体默认 `client:load`（薄 SSR）；局部岛仍可用 `client:visible`。
- 文案：`import { t } from "@app/i18n"` + `locale` prop；不要绑 i18next Provider。
- tRPC：组件内 `QueryClientProvider` + trpc Provider（参考 `UserList.tsx`）。
- UI：`@app/ui`（通用基础组件）+ `cn()`（`~/lib/utils` re-export）；颜色用 CSS 变量。
- 播放页弹幕渲染逻辑在 `lib/danmaku-render.ts`，与 `WatchBody` 解耦。

## 修改指南

- **加文案**：先改 `packages/i18n/src/messages/zh-CN.ts`，再补 `en.ts`。
- **加业务页面**：沿用 `views/*` + `components/pages/*Body` 薄 SSR 模式扩展。
- **调 API**：优先 tRPC（`trpc.media.*`）；`api/users.ts` 仅演示；`api/stream.ts` 为受保护的媒体流。
- **主题**：`localStorage` key `app-theme`；语言 cookie `app-lang`。
- Astro 保留字：组件 props 避免 `slot`。

## 命令

```bash
yarn workspace @app/web typecheck
yarn workspace @app/web lint
yarn workspace @app/web dev       # :4321
yarn workspace @app/web build
yarn dev:web
yarn test:e2e                     # Playwright（e2e/ 目录）
```