93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
# AGENTS.md — app-template 总览
|
||
|
||
面向 AI 编码代理的仓库导览。修改任何代码前，先读本文件与目标子包的 `AGENTS.md`。
|
||
|
||
## 项目是什么
|
||
|
||
**可复用全栈脚手架 / 开发模板**（不绑定产品业务）。只保留鉴权 + `user` 垂直示例，演示完整分层接线。视觉基线见 `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/models` | Drizzle 表定义（唯一 schema 源） | drizzle-orm |
|
||
| `@app/db` | libSQL/Turso 客户端单例 + drizzle-kit | models |
|
||
| `@app/dao` | 数据访问层（`userDao` 等） | db, models |
|
||
| `@app/trpc` | tRPC 路由 + service 业务逻辑（调用 DAO） | types, dao |
|
||
| `@app/web` | Astro 前端 + React islands + 本地 tRPC HTTP 适配 | trpc, types, 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) |
|
||
|
||
依赖方向（只允许向下）：
|
||
|
||
```
|
||
web ──► trpc ──► dao ──► db ──► models
|
||
│ │ │
|
||
│ └─────────────────┴──► types
|
||
├──► design-tokens
|
||
├──► seo-geo
|
||
├──► i18n
|
||
├──► adsense
|
||
└──► ui
|
||
```
|
||
|
||
禁止循环依赖。跨包只通过 `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` 手动加载（drizzle-kit 在 monorepo 中不会自动读根 env）。
|
||
- **模板不掺杂业务逻辑**：禁止把产品领域实体/页面写进本仓库；下游业务仓库再扩展。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
yarn install
|
||
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 db:generate # Drizzle 迁移生成
|
||
yarn db:push # 推 schema
|
||
yarn db:studio
|
||
```
|
||
|
||
改某个包时可先 `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. **新增业务实体**：复制 `user` 垂直切片（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)
|