75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# 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
|
||
```
|