skill/fullstack-task/references/api-design.md

@@ -0,0 +1,55 @@
+# API 设计规范
+
+## 风格
+
+- 默认 REST
+- 复杂查询可用 RPC 风格
+- 内部服务可用 tRPC
+
+## 路径
+
+- 资源用复数：`/api/posts`
+- 嵌套不超过两层：`/api/posts/:id/comments`
+- 动作用子资源或 POST：`/api/posts/:id/publish`
+
+## 方法
+
+- GET 查询
+- POST 创建
+- PATCH 局部更新
+- PUT 全量替换
+- DELETE 删除
+
+## 请求
+
+- Body 用 JSON
+- 分页：`?page=1&pageSize=20` 或 cursor
+- 排序：`?sort=-createdAt`
+- 过滤：`?status=published&tag=nextjs`
+
+## 响应
+
+成功：
+
+```json
+{ "data": { ... }, "meta": { ... } }
+```
+
+## 状态码
+
+- 200 -> 成功
+- 201 -> 创建成功
+- 204 -> 删除成功
+- 400 -> 参数错误
+- 401 -> 未登录
+- 403 -> 无权限
+- 404 -> 不存在
+- 409 -> 冲突
+- 422 -> 业务校验失败
+- 500 -> 服务器错误
+
+## 校验
+
+- 所有输入用 Zod 校验
+
+- 错误信息可读，不暴露内部细节

skill/fullstack-task/references/database.md

@@ -0,0 +1,46 @@
+---
+
+## references/database.md
+
+```markdown
+# 数据库设计规范
+
+## 通用字段
+
+- `id`：主键，cuid / uuid / 自增
+- `createdAt`：创建时间
+- `updatedAt`：更新时间
+- `deletedAt`：软删除（可选）
+
+## 建模
+
+- 先画实体关系，再写 schema
+- 一对多用外键
+- 多对多用关联表
+- 避免过宽表，必要时拆表
+
+## 索引
+
+- 外键加索引
+- 高频查询字段加索引
+- 复合索引注意顺序
+- 唯一约束用 unique
+
+## 迁移
+
+- 每次 schema 变更生成迁移文件
+- 迁移必须可回滚
+- 生产环境先备份
+
+## 事务
+
+- 多表写入用事务
+- 保持事务短小
+- 避免在事务里做网络请求
+
+## 查询
+
+- 避免 N+1
+- 列表接口必须分页
+- 大字段按需 select
+```

skill/fullstack-task/references/frontend.md

@@ -0,0 +1,43 @@
+# 前端规范
+
+## 组件
+
+- 一个组件一个职责
+- 展示组件与容器组件分离
+- props 用 TypeScript 定义
+- 避免超过 200 行，超出则拆
+
+## 状态
+
+- 局部状态用 useState
+- 跨组件用 Context 或状态库
+- 服务端状态用 TanStack Query
+- 避免把服务端数据放进全局 store
+
+## 数据获取
+
+- Next.js 优先 Server Components
+- 客户端请求要有 loading / error / empty
+- 请求失败要有重试或提示
+
+## 表单
+
+- React Hook Form + Zod
+- 前端校验 + 后端校验
+- 提交中禁用按钮
+- 错误定位到字段
+
+## 可访问性
+
+- 语义化标签
+- 图片有 alt
+- 表单有 label
+- 键盘可操作
+- 颜色对比度达标
+
+## 性能
+
+- 图片用 next/image
+- 路由级代码分割
+- 长列表虚拟化
+- 避免不必要的 re-render

skill/fullstack-task/references/stack-defaults.md

@@ -0,0 +1,39 @@
+# 默认技术栈
+
+除非用户指定，按以下默认值执行。
+
+## 前端
+
+- 框架：Next.js（App Router）或 React + Vite
+- 语言：TypeScript
+- 样式：Tailwind CSS
+- 状态：React 内置 + TanStack Query
+- 表单：React Hook Form + Zod
+
+## 后端
+
+- 运行时：Node.js
+- 框架：Next.js Route Handlers / Hono / Express
+- 校验：Zod
+- 鉴权：Session + HttpOnly Cookie，或 JWT
+- 日志：pino
+
+## 数据库
+
+- 默认：PostgreSQL
+- ORM：Prisma 或 Drizzle
+- 轻量场景：SQLite
+- 缓存：Redis（可选）
+
+## 部署
+
+- 前端 / 全栈：Vercel
+- 容器：Docker + Fly.io / Railway
+- 静态：Cloudflare Pages
+
+## 工具
+
+- 包管理：pnpm
+- Lint：ESLint + Prettier
+- 测试：Vitest + Playwright
+- CI：GitHub Actions

skill/fullstack-task/references/testing.md

@@ -0,0 +1,37 @@
+# 测试规范
+
+## 分层
+
+- 单元测试：纯函数、工具、校验
+- 集成测试：API、DB、服务
+- 端到端：主链路
+
+## 工具
+
+- Vitest：单元 + 集成
+- Playwright：端到端
+- MSW：mock 网络
+
+## 用例设计
+
+每个功能至少覆盖：
+
+- happy path
+- 空值 / 缺字段
+- 非法输入
+- 权限不足
+- 资源不存在
+- 并发或重复提交
+
+## 命名
+
+- describe("createPost", () => {
+- it("creates a post with valid input", ...)
+- it("rejects empty title", ...)
+- })
+
+## CI
+
+- push 触发 lint + typecheck + test
+- 主分支保护
+- 失败阻断合并