photowall/README.md

PhotoWall 毕业照存储系统

全球学校毕业照存储与同学联络平台。支持国家→省/州→县/区三级组织架构，班级唯一毕业照，每人每班级10张个人照片，8人姓名验证加入，平台审核机制。

技术栈

• 后端: Go (Gin + GORM + MySQL + Redis)
• 前端: Vue3 + Vite + Element Plus + Less + ECharts + FontAwesome
• 数据库: MySQL 5.7+ (utf8mb4, 表前缀 yz_pw_)
• 认证: JWT (3小时有效期) + 盐+MD5密码 + 图形验证码

快速启动

1. 环境要求

• Go 1.21+
• Node.js 16+
• MySQL 5.7+ (需提前创建数据库 photowall)
• Redis (可选，未安装时自动降级为内存模式)

2. 数据库配置

编辑 go/internal/config/config.go 或设置环境变量：

# 默认配置
DB_HOST=10.31.100.3
DB_PORT=3306
DB_USER=photowall
DB_PASSWORD=Dfn47yeKpyJfwz8n
DB_NAME=photowall

提前在 MySQL 中创建数据库：

CREATE DATABASE photowall DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 启动后端

cd go
go run ./cmd/server
# 或编译后运行
go build -o photowall.exe ./cmd/server
./photowall.exe

后端启动后自动：

• 连接 MySQL 并创建所有数据表（表前缀 yz_pw_）
• 创建超级管理员账号 hero920103 / 密码 920103
• 初始化16项系统配置、20个默认菜单、示例地区数据（中/美/英/日）
• 启动定时任务（每小时检查过期班级，30天未补齐自动删除）

后端端口：8010

4. 启动前端

cd vue
npm install
npm run dev

前端端口：8011，自动代理 /api 和 /uploads 到后端 8010。

5. 登录

• 管理员账号：hero920103 / 920103
• 开发万能验证码：888888（任意 captcha_id 均可通过）

功能清单

用户系统

• 注册/登录（图形验证码）
• 忘记密码（邮箱重置码，开发模式直接返回）
• 短信验证码登录（预留，需配置短信服务商）
• 微信扫码登录（预留，需配置微信开放平台）
• JWT 3小时有效期，超时强制跳转登录
• 盐+MD5密码加密
• 个人资料管理（昵称、邮箱、简介）
• 学习履历管理（必须有履历才能创建班级）
• 联系方式管理（邮箱2/QQ5/微信2/手机5/住址1/工作单位1）

组织架构

• 三级地区：国家 → 省/州 → 县/区（最低级是县）
• 学校管理（大学/职业学校/高中/初中/小学/幼儿园/其他）
• 学院管理（仅大学/职业学校有学院层级）
• 示例地区种子数据（中国含江苏连云港海州区）

班级系统

• 班级创建（4步向导：选地区→选学校→填信息→上传毕业照+同学名单）
• 班级唯一性约束（学校+学院+年级+班号+毕业年份）
• 毕业照唯一（每个班级一张）
• 同学名单（创建时必须录入，至少8人）
• 老师名单
• 每人每班级最多10张个人照片
• 加入班级两种方式：
  • 管理员邀请码
  • 搜索+正确说出至少8位同学姓名
• 管理员转移（只能转给同班同学）
• 成员管理（移除成员）

审核机制

• 班级创建后进入待审核状态
• 少于8人直接打回
• 平台管理员巡查发现照片与名单不符可打回
• 打回后30天内未补齐自动删除班级
• 审核日志记录

平台管理

• 数据统计仪表盘（用户/学校/班级/照片核心指标 + 增长趋势 + 分布图表 + 地区TOP10）
• 系统配置管理（16项配置，5个分类：基础/极验/短信/微信/存储）
• 菜单管理（动态路由数据源，树形结构，增删改查）
• 用户管理（封禁/解封账号，封禁原因记录）
• 敏感词全局屏蔽（DFA算法，增删改查，启用/禁用）
• 审核管理（审核队列、通过、打回、手动删除、审核日志）

技术特性

• 动态路由（菜单存储在数据库，登录后按角色动态加载）
• 文件上传MD5去重（重复文件直接返回已有路径，ref_count引用计数）
• 数据隔离（班级照片和联系方式只有班级成员或管理员可见）
• Redis集成（验证码/缓存，连接失败自动降级内存模式）
• 敏感词检测（班级创建时自动检测名称）
• 账号封禁（被封禁用户无法登录）
• H5响应式适配
• CORS跨域支持

目录结构

photowall/
├── go/                          # 后端
│   ├── cmd/server/main.go      # 入口
│   ├── internal/
│   │   ├── config/              # 配置
│   │   ├── database/            # 数据库连接+迁移+种子
│   │   ├── model/               # 数据模型（16+张表）
│   │   ├── service/             # 业务逻辑
│   │   ├── handler/             # HTTP处理器
│   │   ├── middleware/          # 中间件（JWT认证）
│   │   ├── router/              # 路由注册
│   │   └── scheduler/           # 定时任务
│   ├── pkg/                     # 工具包
│   │   ├── jwt/                 # JWT
│   │   ├── hash/                # 盐+MD5
│   │   ├── response/            # 统一响应
│   │   ├── captcha/             # 图形验证码
│   │   ├── redis/               # Redis+内存降级
│   │   └── sensitive/           # DFA敏感词检测
│   ├── uploads/                 # 上传文件目录
│   └── photowall.exe            # 编译产物
├── vue/                         # 前端
│   ├── src/
│   │   ├── api/                 # API封装
│   │   ├── assets/              # 全局样式（Less蓝白配色）
│   │   ├── composables/         # useAuth等
│   │   ├── router/              # 动态路由
│   │   ├── views/               # 页面
│   │   │   ├── auth/            # 登录/注册/忘记密码
│   │   │   ├── home/            # 首页
│   │   │   ├── class/           # 班级（list/edit/detail/join）
│   │   │   ├── normalsettings/  # 个人中心等
│   │   │   └── admin/           # 管理（审核/配置/菜单/统计/用户/敏感词）
│   │   ├── App.vue              # 布局（侧边栏+顶部栏）
│   │   └── main.js              # 入口
│   └── dist/                    # 构建产物
└── doc/                         # 文档
    └── 立项说明.md              # 开发基准文档

第三方服务配置

在「系统管理 → 系统配置」中配置以下参数（留空则处于开发模式）：

分类	配置项	获取地址
极验	geetest_id / geetest_key	https://www.geetest.com
短信	sms_access_key / sms_secret_key / sms_sign_name / sms_template_code	阿里云/腾讯云短信控制台
微信	wechat_app_id / wechat_app_secret / wechat_redirect_uri	https://open.weixin.qq.com

开发说明

• 开发万能验证码：888888
• 忘记密码重置码：开发模式直接在接口返回（生产需配置SMTP邮件服务）
• 短信验证码：开发模式直接返回（需配置短信服务商后真实发送）
• Redis：未安装时自动降级为内存模式，不影响功能
• 表前缀：所有业务表均以 yz_pw_ 开头

UniApp 版本

规划中，用于生成 APK 和小程序端源码。详见 doc/立项说明.md。