# speak-api

**Repository Path**: liubb8280/speak-api

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-04
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Speak backend

Go API and local MySQL development environment for the Speak mini program.

## Local prerequisites

- Go 1.26 or newer
- MySQL 5.6 or newer
- `ffmpeg` for normalizing AAC/M4A and developer-tools WebM recordings

The local MySQL instance uses an isolated data directory under `backend\runtime\mysql` and listens on `127.0.0.1:3307`. It does not use or modify the installation's original data directory. Go build and module caches also stay under `backend\runtime`.

## Start locally

From the repository root:

```powershell
& .\backend\scripts\setup-db.ps1
& .\backend\scripts\run.ps1
```

WeChat login requires credentials supplied through environment variables:

```powershell
$env:WECHAT_APP_ID = 'your-mini-program-app-id'
$env:WECHAT_APP_SECRET = 'your-mini-program-app-secret'
```

The API deliberately has no development fake-login route and contains no built-in WeChat secret.

The API listens on all local interfaces at port `8080` by default. Use `http://127.0.0.1:8080` on the development machine or the machine's LAN IP from a phone on the same network.

```powershell
Invoke-RestMethod http://127.0.0.1:8080/health/live
Invoke-RestMethod http://127.0.0.1:8080/health/ready
Invoke-RestMethod http://127.0.0.1:8080/v1/scenario-packs
```

Business endpoints under `/v1` require `Authorization: Bearer <access-token>`. See `docs/AI接口清单与后续接入说明.md` for the provider modes and model-backed operations.

Stop the API with `Ctrl+C`. Stop the isolated database gracefully with:

```powershell
& .\backend\scripts\stop-mysql.ps1
```

On macOS or Linux, apply migrations to an existing local MySQL database with:

```bash
MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_DATABASE=speak \
MYSQL_USER=root MYSQL_PASSWORD=root ./scripts/migrate.sh
```

The foundational daily-training flow is documented in `docs/基础训练V3实现说明.md`. Dynamic exercise and personal-plan generation are documented in `docs/AI动态题目与个人计划设计.md`.

## Configuration

The service reads configuration from environment variables. See `.env.example` for the complete local defaults. `DB_DSN` is always required.

AI is disabled by default and returns a clear `ai_not_configured` error instead of fabricated analysis. For real analysis, set `AI_PROVIDER_MODE=volc`, configure SeedASR with `VOLC_ASR_API_KEY` (or both legacy keys), and configure Ark with `ARK_API_KEY` plus `ARK_EVALUATION_MODEL`. `AI_PROVIDER_MODE=mock` is only allowed outside production for explicit flow testing.

For local membership testing, set `PAYMENT_MODE=local`. Orders are completed without external payment and entitlements are issued in the same database transaction. This mode is rejected when `APP_ENV=production`; use `PAYMENT_MODE=disabled` until real WeChat Pay is connected.

The bundled MySQL 5.6 instance is suitable only for local development. Use a maintained MySQL 8 release for shared testing and production.