# api

**Repository Path**: legand/api

## Basic Information

- **Project Name**: api
- **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-07-30
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Teacher Tools API

位于 `teacher_tools/api/` 的 Python 3.12 + FastAPI 后端。当前提供课后轻写所需的微信匿名会话、反馈生成、反馈规范提取、限流、幂等、模型适配和质量回归。

## 本地准备

```bash
uv sync
cp .env.example .env
```

`.env` 至少配置：

```dotenv
AUTH_MODE=wechat
WECHAT_APP_ID=小程序AppID
WECHAT_APP_SECRET=只保存在服务端
SESSION_SIGNING_SECRET=至少32字节的随机值
```

启动：

```bash
uv run uvicorn app.main:app --host 127.0.0.1 --port 3100 --workers 1
```

打开：

- `http://127.0.0.1:3100/health`
- `http://127.0.0.1:3100/docs`
- `http://127.0.0.1:3100/openapi.json`

## 检查

```bash
uv run pytest
uv run ruff check .
uv run mypy app quality scripts
uv run python scripts/check_requirements.py
```

服务启动后：

```bash
API_BASE_URL=http://127.0.0.1:3100 uv run python scripts/smoke_test.py
```

## 依赖管理

只修改 `pyproject.toml`，然后执行：

```bash
uv lock
uv export --frozen --no-dev --no-hashes --no-header --output-file requirements.txt
```

提交 `uv.lock` 和 `requirements.txt`，不提交 `.venv/`。

## 模型配置

默认 `GENERATION_PROVIDER=mock`。接入 OpenAI-compatible 服务时配置：

```dotenv
GENERATION_PROVIDER=openai_compatible
MODEL_BASE_URL=https://MODEL_HOST
MODEL_API_PATH=/v1/chat/completions
MODEL_NAME=SERVER_MODEL
MODEL_API_KEY=只保存在服务器
MODEL_RESPONSE_FORMAT=json_schema
MODEL_TIMEOUT_MS=45000
MODEL_TEMPERATURE=0.3
```

## 质量回归

质量数据只使用合成案例：

```bash
API_ACCESS_TOKEN=TOKEN uv run python scripts/run_quality_regression.py
API_ACCESS_TOKEN=TOKEN uv run python scripts/run_profile_extraction_regression.py
```

报告写入被忽略的 `quality/reports/`。

## 部署

目标服务器和域名的默认配置位于
[`deploy/deploy.env.example`](deploy/deploy.env.example)。首次部署：

```bash
cp deploy/deploy.env.example deploy/deploy.env
./deploy/deploy.sh --bootstrap
```

默认使用 `$HOME/.ssh/id_rsa_legand`；私钥有 passphrase 时，发布前先用
`ssh-add --apple-use-keychain ~/.ssh/id_rsa_legand` 解锁到 SSH Agent。

服务器必须已经安装 Nginx、`/usr/local/bin/uv`，并为
`app.legand.cloud` 准备好 Let's Encrypt 证书。当前服务器复用证书名
`legand.cloud`；初始化脚本会检查这些条件，不会静默替换证书。

日常发布：

```bash
./deploy/deploy.sh
```

显式更新服务器共享环境文件：

```bash
./deploy/deploy.sh --update-env
```

部署脚本先完成本地测试和静态检查，再把运行时白名单上传到服务器。版本
保存在 `/opt/teacher_tools/releases/`，`current` 软链接指向当前版本，
`shared/.env` 跨版本共享。发布失败会切回上一版本，成功后保留最近五个
版本。

查看服务日志：

```bash
ssh -p 22 ubuntu@1.14.46.12 \
  'sudo journalctl -u teacher-tools-api.service -n 100 --no-pager'
```

服务器使用 `uv sync --frozen --no-dev` 建立项目自己的 `.venv`。第一阶段固定 `--workers 1`，避免内存限流和幂等状态在多个进程间不一致。