# 中学成绩档案（初中 / 高中）

Secondary School Grade Archive — 多用户 Web 系统：成绩录入、占比趋势分析、错题 OCR + 本地 AI 解法。

**版权所有 © 马建军** · 微信 **dekun03** · 手机 **18364911125**

> [COPYRIGHT.md](./COPYRIGHT.md) · [LICENSE](./LICENSE)

**仓库：** [https://git.bz121.com/dekun/secondary-school-grade-archive.git](https://git.bz121.com/dekun/secondary-school-grade-archive.git)

---

## 文档

| 文档 | 说明 |
|------|------|
| [docs/DEPLOY.md](./docs/DEPLOY.md) | **Ubuntu 零 Node 部署**（systemd + FastAPI 单进程） |
| [docs/USAGE.md](./docs/USAGE.md) | 用户使用说明 |

---

## 修改代码后如何发布（必读）

**生产服务器不安装 Node.js，也不在服务器上执行 `npm build`。**  
凡涉及前端或全栈改动的发布，均按以下流程在**开发机**完成构建后再推送：

```
开发机改代码 → 本地构建 frontend/dist → git push 远端仓库 → 服务器 git pull + update.sh
```

### 仅改后端（`backend/`）

```bash
git add backend/
git commit -m "你的说明"
git push
```

服务器（需代理时先 `export http_proxy=http://192.168.8.246:10810` 等，见 [DEPLOY.md §3](./docs/DEPLOY.md#3-一键部署新服务器)）：

```bash
bash /opt/secondary-school-grade-archive/deploy/update.sh
```

### 改前端或同时改前后端（`frontend/`）

**必须先本地构建，再把 `frontend/dist` 一并提交推送：**

```powershell
# Windows
.\deploy\build-frontend.ps1
```

```bash
# Linux / macOS
bash deploy/build-frontend.sh
```

```bash
git add frontend/ frontend/dist
git commit -m "你的说明"
git push
```

服务器（需代理时先 `export http_proxy=http://192.168.8.246:10810` 等，见 [DEPLOY.md §3](./docs/DEPLOY.md#3-一键部署新服务器)）：

```bash
bash /opt/secondary-school-grade-archive/deploy/update.sh
```

> 若只推送源码而未推送 `frontend/dist`，服务器更新后页面不会变化。详见 [docs/DEPLOY.md §2](./docs/DEPLOY.md#2-代码修改与发布流程重要)。

---

## Ubuntu 一键部署（零 Node）

若服务器访问外网需走代理，**先设置代理再执行安装**：

```bash
export http_proxy=http://192.168.8.246:10810
export https_proxy=http://192.168.8.246:10810
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
```

```bash
git clone https://git.bz121.com/dekun/secondary-school-grade-archive.git /opt/secondary-school-grade-archive
cd /opt/secondary-school-grade-archive
chmod +x deploy/*.sh
bash deploy/install.sh
```

> `install.sh` 会自动将代理用于 `apt`、`git`、`pip`、`curl`。无需代理时可省略 `export` 步骤。

- 安装目录：`/opt/secondary-school-grade-archive`
- 访问地址：`http://<服务器IP>:23566`
- 进程管理：`systemctl status grade-archive` / `journalctl -u grade-archive -f`
- 默认超级管理员：**admin / admin123**（登录后请在「系统设置」中修改）

**前提：** 仓库中已包含 `frontend/dist/`（由开发机构建后推送）。详见 [docs/DEPLOY.md](./docs/DEPLOY.md)。**反向代理不包含在本项目中。**

---

## 本地开发

### 方式一：前后端分离（推荐日常开发）

```bash
# PostgreSQL 本地安装后
cp .env.example .env

cd backend
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 23566

cd frontend
npm install && npm run dev
```

- 前端开发：http://localhost:5173（Vite 代理 `/api` → 23566）
- 后端 API：http://localhost:23566/api/health

### 方式二：模拟生产（单进程 + 静态 dist）

```bash
cd frontend && npm run build
cd ../backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 23566
```

访问 http://localhost:23566

---

## 运维

```bash
bash deploy/update.sh    # 拉代码 + 更新依赖 + 重启服务
bash deploy/backup.sh    # 备份
bash deploy/uninstall.sh # 停止并卸载
```

### 停止 / 启动（不卸载）

```bash
sudo systemctl stop grade-archive
sudo systemctl start grade-archive
sudo systemctl restart grade-archive
```

### 卸载

```bash
# 仅停服务，保留代码与数据
sudo bash /opt/secondary-school-grade-archive/deploy/uninstall.sh

# 删除安装目录
sudo bash /opt/secondary-school-grade-archive/deploy/uninstall.sh --purge

# 删除数据库
sudo bash /opt/secondary-school-grade-archive/deploy/uninstall.sh --purge-db

# 完全清除
sudo bash /opt/secondary-school-grade-archive/deploy/uninstall.sh --purge --purge-db
```

详见 [docs/DEPLOY.md §5.1 / §5.2](./docs/DEPLOY.md#51-停止与启动服务)。

---

## 技术支持

微信 **dekun03** · 手机 **18364911125**
