# StarJar

**Repository Path**: Kuaima-tech/star-jar

## Basic Information

- **Project Name**: StarJar
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 星星罐

当前仓库包含两个版本：

- Web 版：根目录 `Next.js + MySQL 8 + Prisma`，继续作为业务逻辑参考和 Web 原型。
- 微信小程序版：[apps/miniprogram](D:/workspace/codex/StarJar/apps/miniprogram)，新增的 `uni-app Vue3 + Pinia + uniCloud` 工程，用于发布微信小程序。

## Setup

1. Install dependencies:

```bash
npm install
```

2. Create `.env.local` from `.env.example` and set a MySQL 8 database URL:

```bash
DATABASE_URL="mysql://user:password@localhost:3306/star_jar"
NEXT_PUBLIC_API_BASE_URL="/api"
SESSION_SECRET="replace-with-a-long-random-secret"
AUTH_CODE_DEV_MODE="true"
AUTH_CODE_EXPIRES_MINUTES="5"
```

3. Create tables and seed demo data:

```bash
npm run db:migrate
npm run db:seed
```

4. Start the app:

```bash
npm run dev
```

Open `http://localhost:3000`.

## Scripts

- `npm run dev` - Start Next.js dev server.
- `npm run build` - Build production app.
- `npm run start` - Start production server.
- `npm run lint` - Run ESLint.
- `npm run db:generate` - Generate Prisma client.
- `npm run db:migrate` - Run Prisma migrations against MySQL.
- `npm run db:seed` - Seed demo family, children, habits, rewards, reminders, badges, and energy data.

## API

The app uses phone verification-code login with a server session cookie. In development mode, `POST /api/auth/request-code` returns `devCode` so the login flow can be tested without an SMS provider.

- `POST /api/auth/request-code`
- `POST /api/auth/verify-code`
- `POST /api/auth/logout`
- `GET /api/me`
- `POST /api/me/current-child`
- `POST /api/families`
- `POST /api/families/switch`
- `GET /api/bootstrap`
- `GET/POST/PATCH /api/children`
- `GET/POST/PATCH /api/habits`
- `POST /api/checkins`
- `GET /api/energy/overview`
- `GET /api/energy/ledger`
- `GET/POST/PATCH /api/rewards`
- `GET/POST /api/redemptions`
- `POST /api/redemptions/:id/approve`
- `POST /api/redemptions/:id/reject`
- `GET /api/growth?view=week|month|year&offset=0`
- `GET/PATCH /api/reminders`
- `GET/PATCH /api/settings`

Business API routes require a valid session and isolate data by the current family and child from the session. Business rules for check-ins, energy balance, reward redemption, ledger updates, stats, and badges run on the server.

## 微信小程序 / uniCloud

小程序工程位于 `apps/miniprogram`，不会直接依赖根目录的 Next.js API、Prisma 或 MySQL。

```bash
cd apps/miniprogram
npm install
npm run dev:mp-weixin
```

生成后用微信开发者工具导入：

```text
apps/miniprogram/dist/dev/mp-weixin
```

云端目录：

- `apps/miniprogram/uniCloud-tcb/cloudobjects` - `starjar-*` 业务云对象。
- `apps/miniprogram/uniCloud-tcb/common/starjar-common` - 权限、上下文、审计、打卡、兑换、统计等公共服务逻辑。
- `apps/miniprogram/uniCloud-tcb/database` - uniCloud DB schema 与索引。

迁移说明见 [docs/unicloud-miniprogram-migration-plan.md](D:/workspace/codex/StarJar/docs/unicloud-miniprogram-migration-plan.md)。

小程序首版默认：

- 使用 `uni-id-co.loginByWeixin` 登录。
- 首次登录后创建家庭或输入邀请码加入家庭。
- 5 个 Tab：习惯、能量、兑换、成长、设置。
- 兑换输入兑换密码后直接扣星星并生成 `completed` 记录，不走审批或冻结。
- 数据写操作全部通过云对象，不开放客户端直写核心业务集合。

本地仅打开页面调试时，`apps/miniprogram/src/manifest.json` 默认使用 `touristappid` 并关闭 URL 校验，避免微信开发者工具因占位 AppID 报安全信息错误。接入真实微信登录和 uniCloud 服务空间前，需要把它替换为正式微信小程序 AppID。

小程序默认构建连接本地 Next.js API，即根目录的 MySQL 数据链路。请先启动 MySQL，再在根目录运行 `npm run dev`，小程序默认请求 `http://127.0.0.1:3000/api`。如需改端口，在 `apps/miniprogram` 下设置 `VITE_API_BASE_URL` 后重新构建。连接真实 uniCloud 可设置 `VITE_DATA_SOURCE=unicloud`，并使用 HBuilderX 关联服务空间或完成对应 CLI 服务空间配置。