# bird-watcher

**Repository Path**: yoka24443/bird-watcher

## Basic Information

- **Project Name**: bird-watcher
- **Description**: 这个项目式万人鸟类科普挑战赛志愿者激励小程序 (爱鸟记录小助手)，为激励“鸟赛”的志愿者持续参与，通过游戏化、系统化的方式提升志愿者活跃度、活动体验质量及活动监督效率。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 爱鸟记录小助手 - 万人鸟类科普挑战赛志愿者激励小程序

## 项目简介

"爱鸟记录小助手"是一款面向观鸟志愿者和爱好者的微信小程序，通过游戏化激励体系（积分、称号、任务、兑换），激励志愿者持续参与科普活动，为观鸟爱好者提供记录和评价服务。

### 三大核心模块

| 模块 | 目标用户 | 核心功能 |
|------|----------|----------|
| **志愿者端** | 观鸟志愿者 | 任务中心、称号成就、积分商城、数据统计 |
| **爱好者端** | 观鸟爱好者 | 鸟类记录、服务评价、个人中心 |
| **管理后台** | 管理员 | 任务/奖品管理、用户管理、数据看板 |

---

## 技术栈

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 前端框架 | Taro | 4.1.9 | 跨端开发（微信小程序 + H5） |
| 语言 | TypeScript | 5.4.5 | - |
| 渲染 | React | 18.0.0 | - |
| UI 组件 | shadcn/ui (Taro 版) | - | `@/components/ui/*` |
| 图标 | lucide-react-taro | 1.4.x | Lucide 图标 Taro 适配 |
| 样式方案 | 原生 CSS 实用类 | - | `src/app.css` ~200+ 类名 |
| 状态管理 | React Hooks | - | useState + useEffect |
| 包管理 | pnpm | - | - |
| 后端框架 | NestJS | 10.x | - |
| 数据库 | PostgreSQL (Supabase) | - | 云数据库 |
| 认证 | JWT (微信登录) | - | 7 天有效期 |

---

## 项目结构

```
├── src/                          # 前端源码
│   ├── app.ts                    # 应用入口
│   ├── app.config.ts             # 应用配置（页面注册 + TabBar）
│   ├── app.css                   # 全局样式（~800 行实用类）
│   ├── network.ts                # 网络请求封装
│   ├── pages/
│   │   ├── index/                # 首页（角色选择 + 登录）
│   │   ├── volunteer/            # 志愿者端（5个页面）
│   │   │   ├── index.tsx         #   任务中心
│   │   │   ├── achievements.tsx   #   成就中心
│   │   │   ├── rewards.tsx       #   积分商城
│   │   │   ├── stats.tsx         #   数据统计
│   │   │   └── profile.tsx       #   个人中心
│   │   ├── enthusiast/           # 爱好者端（4个页面）
│   │   │   ├── index.tsx         #   首页
│   │   │   ├── birds.tsx         #   鸟类图鉴
│   │   │   ├── records.tsx       #   记录中心
│   │   │   └── profile.tsx       #   个人中心
│   │   └── admin/                # 管理后台（4个页面）
│   │       ├── index.tsx         #   看板
│   │       ├── tasks.tsx         #   任务管理
│   │       ├── rewards.tsx       #   奖品管理
│   │       └── users.tsx         #   用户管理
│   ├── components/ui/            # shadcn/ui 组件库
│   ├── utils/
│   │   └── auth.ts               # 认证工具（Token管理 + 微信登录）
│   └── presets/                  # 框架预置
├── server/                       # NestJS 后端服务
│   └── src/
│       ├── main.ts               # 服务入口（端口3000，全局 /api 前缀）
│       ├── app.module.ts         # 根模块
│       ├── modules/
│       │   ├── auth/             # 认证（微信登录 + JWT）
│       │   ├── tasks/            # 后台任务 CRUD
│       │   ├── task-progress/    # 用户任务进度
│       │   ├── titles/           # 称号管理
│       │   ├── rewards/          # 后台奖品 CRUD
│       │   ├── rewards/public-*  # 公开积分商城 API
│       │   ├── points/           # 积分记录
│       │   ├── evaluations/      # 评价体系
│       │   ├── users/            # 用户管理
│       │   └── dashboard/        # 看板数据
│       └── storage/database/     # Supabase 客户端
├── config/                       # Taro 构建配置
├── types/                        # 类型定义
├── assets/tabbar/                # TabBar 图标（本地 PNG）
├── project.config.json           # 微信小程序配置
└── package.json                  # 脚本详见下方
```

---

## 可用脚本

```bash
# 开发
pnpm dev              # 启动 H5（端口5000）+ 后端（端口3000）热更新
pnpm dev:web          # 仅 H5 前端热更新
pnpm dev:server       # 仅后端热更新
pnpm dev:weapp        # 微信小程序构建（监听模式）

# 构建与验证
pnpm validate         # ESLint + TypeScript 检查（交付前必跑）
pnpm build:weapp      # 构建微信小程序（自动拷贝 app.json 到根目录）
pnpm build:web        # 构建 H5 版本
pnpm build:server     # 构建后端
pnpm build            # 全量构建

# 其他
pnpm lint             # ESLint 检查
pnpm lint:fix         # ESLint 自动修复
pnpm tsc              # TypeScript 类型检查
```

---

## 快速开始

### 1. 环境准备

```bash
node >= 18
pnpm >= 8
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 配置环境变量

创建 `.env.local`：

```env
# Supabase 数据库
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# JWT 密钥（可选，有默认值）
JWT_SECRET=your_jwt_secret

# H5 模式标识（可选）
IS_H5_ENV=true
```

### 4. 启动开发

```bash
pnpm dev
```

- H5 预览：`http://localhost:5000`
- 后端 API：`http://localhost:3000`
- H5 前端通过 Vite proxy 将 `/api/*` 代理到后端 3000 端口

---

## 跨端注意事项

- **样式单位**：Taro 默认 750 设计宽度，通过 `pxtransform` 将 CSS px 转为小程序 `rpx` / H5 `rem`
- **Input/Textarea**：H5 端为 inline 元素，须用 `View` 包裹 + `width: 100%` 修复样式
- **Fixed + Flex**：H5 Tailwind 失效，必须使用 `style={{ position: 'fixed', display: 'flex' }}`
- **CSS 变量**：微信小程序 WXSS **不支持** CSS 自定义属性（`var(--xxx)`），所有值须硬编码
- **图标**：`lucide-react-taro` 在小程序端用 `<Image>` 渲染 SVG data URI，`className` 不改变颜色/尺寸，须用 `color`/`size` props
- **图片资源**：除 TabBar 图标（本地 PNG）外，其余一律走 TOS 对象存储