4.7 KiB

Raw Blame History

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）。
模板不掺杂业务逻辑：禁止把产品领域实体/页面写进本仓库；下游业务仓库再扩展。

常用命令

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。

全局约定（必须遵守）

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

各包入口

细节见各包 AGENTS.md：

4.7 KiB Raw Blame History Unescape Escape