README 与新人上手

简要摘要

本页提供完整的 README 模板、本地环境搭建步骤（从 git clone 到服务启动）、常见问题 FAQ 格式，以及贡献指南关键内容。目标是让新成员在 15 分钟内能跑起来，让 Agent 生成仓库首页时有可执行标准可依。

本技能约束仓库首页与 onboarding 文档的可执行性：版本钉扎、可复制命令、环境变量说明与 FAQ 同屏；安全上只给占位示例，真实密钥走内部渠道。阶梯上从「能 clone」到「能改一行并过 CI」，Agent 与人类共用同一检查清单。

完整 README 模板

以下为包含所有必要章节的 README 模板，可直接复制使用：

# project-name

> 一句话描述：这个项目解决什么问题，给谁用。

[![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)](...)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## 目录
- [要求](#要求)
- [快速开始](#快速开始)
- [环境变量](#环境变量)
- [开发指南](#开发指南)
- [常见问题](#常见问题)
- [贡献指南](#贡献指南)

## 要求
| 工具 | 版本 | 说明 |
|------|------|------|
| Node.js | >=20.0.0 | 使用 `.nvmrc` 中版本 |
| pnpm | >=9.0.0 | `corepack enable && corepack prepare pnpm@9` |
| Docker | >=24.0 | 本地依赖服务 |
| PostgreSQL | 15（via Docker） | 无需本地安装 |

## 快速开始
（见下方本地环境设置章节）

## 架构概览
[架构图链接](./docs/architecture.md) | [ADR 列表](./docs/adr/) | [API 文档](./docs/api.md)

本地与生产的主要差异：
- 数据库：本地用 Docker，生产用 RDS
- 邮件：本地用 Mailhog（localhost:8025），生产用 SES
- 支付：本地用 Stripe test mode，需配置测试密钥

本地环境设置（git clone 到服务启动）

完整步骤，每一步包含命令和验证方式：

# 步骤 1: 克隆仓库并进入目录
git clone https://github.com/org/project-name.git
cd project-name

# 步骤 2: 检查 Node.js 版本（与 .nvmrc 对齐）
node --version          # 应输出 v20.x.x
# 若版本不对:
nvm use                 # 自动读取 .nvmrc
# macOS/Linux: brew install nvm 或 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# Windows: 使用 nvm-windows: https://github.com/coreybutler/nvm-windows

# 步骤 3: 安装依赖
corepack enable
pnpm install
# 验证: 应看到 "node_modules/.pnpm" 目录，无 error

# 步骤 4: 复制并配置环境变量
cp .env.example .env
# 编辑 .env，填写必填字段（见环境变量说明）
# 必填: DATABASE_URL, JWT_SECRET（开发用任意字符串）
# 可留空: STRIPE_SECRET_KEY（跳过支付功能开发时）

# 步骤 5: 启动本地依赖服务（Docker）
docker compose up -d postgres redis mailhog
# 验证:
docker compose ps       # 应看到 postgres/redis/mailhog 状态为 Up

# 步骤 6: 运行数据库迁移
pnpm db:migrate
# 验证: 应输出 "All migrations completed successfully"
# 失败时: 检查 DATABASE_URL 是否指向本地 Docker（默认: postgresql://postgres:postgres@localhost:5432/app_dev）

# 步骤 7: 启动开发服务器
pnpm dev
# 验证: 打开 http://localhost:3000，应看到首页
# API 文档: http://localhost:3000/api-docs

# 步骤 8: 运行测试确认环境 OK
pnpm test               # 单元测试（约 30s）
pnpm test:integration   # 集成测试（需 Docker 服务运行，约 2min）

Agent 从仓库元数据到可交付 README / onboarding 页的推荐顺序。

[ 扫仓库：语言版本、脚本入口、CI 与目录角色 ]
                    │
                    ▼
         [ 写简介 / 要求 / 快速开始（可复制命令）]
                    │
                    ▼
      [ 环境变量表：名称 · 用途 · 示例占位（无真实密钥）]
                    │
                    ▼
    [ FAQ：常见失败 + 平台差异（Win / macOS / Linux）]
                    │
                    ▼
 [ 第一天任务 + 交叉引用 CHANGELOG、Runbook、架构图 ]

常见问题 FAQ 与贡献指南

## 常见问题

### Q: `pnpm install` 失败，提示 "EACCES: permission denied"
**症状**: macOS/Linux 上安装时权限报错
**原因**: npm 全局目录权限问题
**解决**:
```bash
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

### Q: 数据库连接失败 "ECONNREFUSED 127.0.0.1:5432"
**症状**: `pnpm dev` 启动报数据库连接错误
**原因**: Docker 服务未启动，或 DATABASE_URL 配置错误
**解决**:
```bash
# 检查 Docker 服务状态
docker compose ps
# 若未运行:
docker compose up -d postgres
# 检查 .env 中 DATABASE_URL
cat .env | grep DATABASE_URL
# 应为: postgresql://postgres:postgres@localhost:5432/app_dev
```

### Q: Windows 上 `pnpm dev` 报 "cross-env is not recognized"
**症状**: Windows PowerShell 运行脚本失败
**解决**:
```powershell
# 使用 Git Bash 而非 PowerShell
# 或安装 cross-env:
pnpm add -D cross-env
# .nvmrc 在 Windows 上需要 nvm-windows 支持
```

### Q: 测试失败 "Cannot find module '@/components/...'"
**症状**: 路径别名解析失败
**解决**: 确认 `tsconfig.json` 中 paths 与 `vitest.config.ts` 中 alias 一致

## 贡献指南

### Branch 命名规范
feat/short-description    # 新功能
fix/issue-number-desc     # Bug 修复（关联 issue 号）
docs/update-api-readme    # 文档更新
refactor/extract-service  # 重构
chore/upgrade-deps        # 依赖/构建相关

# 示例:
git checkout -b feat/user-avatar-upload
git checkout -b fix/1234-login-redirect-loop

### Commit 规范（Conventional Commits）
feat: add user avatar upload endpoint
fix(auth): resolve redirect loop on OAuth callback (#1234)
docs: update local setup for Windows
refactor(payment): extract charge logic to service class
chore: upgrade Node.js to v20.11.0

### PR 流程
1. 从 main 分支切出，保持分支短命（<1周）
2. PR 标题遵循 Conventional Commits 格式
3. 必须通过所有 CI 检查（lint + test + build）
4. 至少 1 名 reviewer approve（安全相关代码需 2 人）
5. 合并方式：Squash and merge（保持 main 历史整洁）
6. 合并后删除 feature branch

### 本地 CI 检查（提交前运行）
pnpm lint          # ESLint + Prettier 检查
pnpm type-check    # TypeScript 类型检查
pnpm test          # 单元测试
# 或一次性运行全部:
pnpm pre-commit    # 等同于上面三条命令

新人清单（可勾选）

勾选状态保存在本机浏览器，便于对照阶梯自测。

• 已核对运行时与包管理器版本与 CI / .tool-versions 或文档一致。
• 已按「快速开始」从零执行一遍，无省略步骤。
• 环境变量表已理解：必填项、可空项与获取密钥的内部链接已打开过。
• FAQ 或排错段落覆盖了自己平台（或已补充 issue）。
• 已认领或计划第一个小任务，并知悉评审与发布相关链接。