SCUTMarket

华南理工大学校内二手交易平台。

当前实现为前后端分离开发、后端可托管前端构建产物的结构：

• 前端：React 19 + TypeScript + Vite + TanStack Router + TanStack Query
• 后端：Go + SQLite

更完整的产品设计和业务背景见 SCUTmarket.md。

功能概览

• 校内邮箱注册 / 登录
• 商品发布、编辑、上下架、删除
• 公告管理
• 商品举报
• 审核队列与管理员审核
• 图片上传
• SQLite 本地存储

目录结构

SCUTmarket/
├── backend/              # Go 后端
│   ├── cmd/server/       # 服务启动入口
│   └── config/           # 后端配置
├── frontend/             # React 前端
│   ├── src/              # 前端源码
│   └── dist/             # 前端构建产物
├── data/                 # SQLite 数据库文件
├── uploads/              # 上传图片目录
└── SCUTmarket.md         # 设计文档

环境要求

• Go 1.22 或更高版本
• Node.js 20 或更高版本
• npm

配置

后端配置

默认读取 backend/config/server.json。

可以参考 backend/config/server.example.json 新建或修改实际配置。示例文件里已经带了 _comment_* 字段说明每个配置项的用途。

后端支持通过环境变量切换配置文件：

SCUTMARKET_CONFIG=/path/to/server.json go run ./cmd/server

关键配置说明：

• server：监听地址、数据库路径、静态文件目录、上传目录、Session 密钥
• auth：密码长度、验证码有效期、发送冷却、登录态有效期
• smtp：验证码邮件发送配置
• admin：管理员邮箱和初始密码
• audit.enable_rule：是否启用规则审核
• audit.enable_ai：是否启用 AI 审核

注意：

• enable_rule 和 enable_ai 可以任意组合，可以都开，也可以都关。
• 服务启动时会自动确保 admin.email 对应的管理员账号存在；如果该邮箱已存在，也会同步提升为管理员并更新密码。
• server.json 不应提交真实密钥、SMTP 密码或真实管理员密码。

前端本地配置

前端本地配置文件是 frontend/src/config/app.json。

可参考 frontend/src/config/app.example.json。目前这里只放纯前端展示相关配置，例如商品卡片宽度。

安装依赖

前端：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm install

后端：

cd /home/xbohodx02/work/SCUTmarket/backend
go mod download

启动方式

1. 开发模式

适合日常开发。前端和后端分开运行。

启动后端：

cd /home/xbohodx02/work/SCUTmarket/backend
go run ./cmd/server

启动前端：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm run dev

通常访问地址：

• 前端开发服务器：http://localhost:5173
• 后端接口：http://localhost:8080

2. 集成预览 / 生产式启动

适合验证实际部署形态。前端先构建，再由后端统一托管静态文件。

构建前端：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm run build

启动后端：

cd /home/xbohodx02/work/SCUTmarket/backend
go run ./cmd/server

然后访问：

http://localhost:8080

常用命令

前端开发：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm run dev

前端构建：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm run build

前端预览构建产物：

cd /home/xbohodx02/work/SCUTmarket/frontend
npm run preview

后端运行：

cd /home/xbohodx02/work/SCUTmarket/backend
go run ./cmd/server

后端测试：

cd /home/xbohodx02/work/SCUTmarket/backend
go test ./...

数据与文件

• SQLite 数据库默认在 data/scutmarket.db
• 上传图片默认保存在 uploads
• 前端构建产物默认输出到 frontend/dist

如果想重置本地数据，通常需要清理数据库文件和上传目录中的测试数据；执行前先确认不需要保留现有数据。

审核说明

审核链路由后端配置决定：

• 只开 enable_rule
• 只开 enable_ai
• 两者同时开启
• 两者都关闭

当启用 AI 审核时，还需要在 audit.ai 中补齐可用的接口配置；如果 enable_ai=true 但 AI 配置不完整，系统会提示 AI 审核当前不会实际执行。

说明

• frontend/dist/assets 里的文件是 Vite 构建产物，文件名带 hash 是正常现象，用于缓存失效。
• server.example.json 和 app.example.json 中的注释以 _comment_* 字段形式存在，这是为了保持文件仍然是合法 JSON。