# AGENTS.md — @app/web

## 职责

Astro SSR 前端（Node standalone）：页面、布局、React islands、tRPC HTTP 适配、SEO 文本端点、**i18n 路由**。

脚手架基线页面：首页、鉴权、仪表盘（user 列表示例）、设置。视觉遵循仓库根 `DESIGN.md` 与 `@app/design-tokens`。

## i18n

- 语言：`zh-CN`（`/zh-CN/...`）、`en`（`/en/...`）。**中文也带前缀**，不把中文留在裸 `/`。
- **单套路由**：`src/pages/[locale]/index.astro`、`[locale]/dashboard.astro` + `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 | auth/* | settings.astro
    api/trpc/[...trpc].ts | api/users.ts
    sitemap.xml.ts | robots.txt.ts | llms.txt.ts | llms-full.txt.ts
  views/
    home.astro | dashboard.astro | auth.astro | error.astro
  middleware.ts       # 裸 / 语言检测跳转 + locale 规范化
  layouts/AppLayout.astro
  components/
    UserList.tsx | UserMenu.tsx | ThemeSwitch.tsx | AuthForm.tsx | errors/*
  lib/
    trpc.ts | seo.ts（getSiteSeo(locale)）| theme.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

- 布局统一走 `AppLayout.astro`，必传 `locale`，通过 `seo` prop 传 `PageSeoInput`。
- 站点 SEO：`lib/seo.ts` 的 `getSiteSeo(locale)`；sitemap 双语 URL + hreflang `alternates`。
- 新公开页面：登记 `PUBLIC_PATHS` / views，并同步 `getSiteSeo` 的 `llms.pages` 与 sitemap。

## React islands

- 需要交互才加 `client:load` / `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 变量。

## 修改指南

- **加文案**：先改 `packages/i18n/src/messages/zh-CN.ts`，再补 `en.ts`。
- **加业务页面**：在下游仓库扩展，勿把产品业务写回模板。
- **调 API**：优先 tRPC；`api/users.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
```