# AGENTS.md — 帆幕（Fanmu）总览

面向 AI 编码代理的仓库导览。修改任何代码前，先读本文件与目标子包的 `AGENTS.md`。

## 项目是什么

**帆幕（Fanmu）**：私有影音库 · 弹幕观影 · 网盘挂载。本仓库为**产品仓**，业务代码进入既有分层。视觉基线见 `DESIGN.md`。

技术栈：Astro 7（SSR）+ React 19 islands · tRPC v11 · Drizzle ORM + Turso/libSQL · Tailwind CSS 4 · TypeScript 7 · Biome · Yarn 4 workspaces + Turbo。

## 模块地图

| 包 | 职责 | 依赖 |
|----|------|------|
| `@app/types` | Zod 入参 schema + 共享输出类型 | zod |
| `@app/danmaku` | 弹幕开放协议纯函数（签名/hash/XML/匹配/过滤；`./browser` 无 node:crypto） | — |
| `@app/models` | Drizzle 表定义（唯一 schema 源） | drizzle-orm |
| `@app/db` | libSQL/Turso 客户端单例 + drizzle-kit | models |
| `@app/dao` | 数据访问层（`userDao` / `mountDao` / `mediaItemDao` 等） | db, models |
| `@app/trpc` | tRPC 路由 + service 业务逻辑（调用 DAO） | types, dao, danmaku |
| `@app/web` | Astro 前端 + React islands + 本地 tRPC HTTP 适配 | trpc, types, danmaku（`./browser`）, design-tokens, seo-geo, i18n, ui |
| `@app/ui` | shadcn 风格基础 UI 组件（源码直出 + Storybook） | design-tokens, react (peer) |
| `@app/design-tokens` | 共享 CSS 设计令牌（`tokens.css`） | — |
| `@app/seo-geo` | SEO/GEO 纯函数（meta、sitemap、JSON-D、llms.txt） | zod, schema-dts, escape-html, fast-xml-builder, serialize-javascript, mdast-util-to-markdown |
| `@app/i18n` | 文案与 locale 纯函数（zh-CN / en、t()、Accept-Language） | — |
| `@app/adsense` | AdSense 脚本加载 + `AdSlot` React 组件 | react (peer) |
| `@app/docs` | 产品文档站（VitePress，中文根路径 + 英文 `/en`） | —（仅 vitepress） |

依赖方向（只允许向下）：

```
web ──► trpc ──► dao ──► db ──► models
 │        │  │              │
 │        │  └──► danmaku   │
 │        └─────────────────┴──► types
 ├──► danmaku（浏览器侧走 ./browser）
 ├──► design-tokens
 ├──► seo-geo
 ├──► i18n
 ├──► adsense
 └──► ui

docs（独立，不依赖上述业务包）
```

禁止循环依赖。跨包只通过 `package.json` 的 `exports` 入口引用，不要 deep import。

## 目录约定

- 源码在各包 `src/`；构建产物在 `dist/`（git 忽略，勿手改）。
- 环境变量模板见 `.env.example`：`TURSO_DATABASE_URL`、`TURSO_AUTH_TOKEN`、`PUBLIC_SITE_URL`。
- 根 `.env` 由 `packages/db/drizzle.config.ts` 与 `packages/db/scripts/seed.ts` 手动加载（monorepo 下工具不会自动读根 env）。
- **分层不跳层**：业务实体按 types → models → dao → trpc → web 落地；领域逻辑进 service，SQL 进 dao。
- `e2e/`：Playwright 端到端测试（配置在根 `playwright.config.ts`），不是 workspace 包。
- `app/docs/`：VitePress 文档站源码（`.vitepress/` 配置 + `guide/` 中文 + `en/guide/` 英文）。

## 常用命令

```bash
yarn install
yarn test               # 各包 vitest（turbo run test）
yarn typecheck          # 全仓 typecheck
yarn lint               # Biome
yarn build              # 全仓 build（依赖拓扑）
yarn build:web          # 仅 @app/web + 上游依赖闭包（日常/CI 更快）
yarn dev:web            # Astro :4321
yarn dev:api            # 独立 tRPC :4000（web 内嵌 /api/trpc 时通常不需要）
yarn docs:dev           # VitePress 文档站
yarn docs:build
yarn test:e2e           # Playwright（自动起 webServer）
yarn db:generate        # Drizzle 迁移生成
yarn db:push            # 推 schema
yarn db:seed            # 初始化默认管理员（幂等）
yarn db:studio
yarn storybook          # @app/ui Storybook :6006
```

改某个包时可先 `yarn workspace @app/<name> typecheck`。

## 全局约定（必须遵守）

1. **TypeScript 很严**：`strict` + `noUncheckedIndexedAccess` + `exactOptionalPropertyTypes` + `noPropertyAccessFromIndexSignature`。可选属性传 `undefined` 时类型要写 `?: T | undefined`。
2. **ESM only**（`"type": "module"`）。源码内相对 import 带 `.js` 后缀（TS bundler 解析）。
3. **格式化/静态检查**：Biome（2 空格、行宽 100）。不要引入 ESLint/Prettier。
4. **校验**：对外输入用 Zod 4，定义放在 `@app/types`，router/service 共用。
5. **数据库模型**只放 `@app/models`；**查询/SQL** 只放 `@app/dao`；`@app/db` 只建连接单例，不建表、不含业务规则。
6. **UI**：设计令牌从 `@app/design-tokens` 引入；组件优先用 `@app/ui`（shadcn 风格，源码在 `packages/ui`）+ `cn()`。视觉遵循 `DESIGN.md`。
7. **构建顺序**：改 `types`/`models` 后需先 build 上游，再让下游 typecheck（Turbo `dependsOn: ["^build"]` 已配置）。
8. **注释**：只写非显而易见的 WHY；默认不写注释。
9. **新增业务实体**：按 types → models → dao → trpc → web 分层落地，不要跳层。

## 各包入口

细节见各包 `AGENTS.md`：

- [packages/types/AGENTS.md](packages/types/AGENTS.md)
- [packages/models/AGENTS.md](packages/models/AGENTS.md)
- [packages/db/AGENTS.md](packages/db/AGENTS.md)
- [packages/dao/AGENTS.md](packages/dao/AGENTS.md)
- [packages/trpc/AGENTS.md](packages/trpc/AGENTS.md)
- [app/web/AGENTS.md](app/web/AGENTS.md)
- [packages/design-tokens/AGENTS.md](packages/design-tokens/AGENTS.md)
- [packages/seo-geo/AGENTS.md](packages/seo-geo/AGENTS.md)
- [packages/i18n/AGENTS.md](packages/i18n/AGENTS.md)
- [packages/adsense/AGENTS.md](packages/adsense/AGENTS.md)
- [packages/ui/AGENTS.md](packages/ui/AGENTS.md)
- [app/docs/AGENTS.md](app/docs/AGENTS.md)