Files

T

hero920103 57d9866dab feat: PhotoWall 毕业照存储系统初始版本

后端: Go(Gin+GORM+MySQL+Redis)
- 17张业务表(yz_pw_前缀), 自动迁移
- JWT认证(3小时) + 盐+MD5密码 + 图形验证码
- 班级CRUD/加入(8人姓名验证/邀请码)/审核/30天自动清理
- 系统配置(16项)/菜单管理(动态路由)/数据统计
- 文件MD5去重/数据隔离/账号封禁/敏感词DFA检测

前端: Vue3+Vite+Element Plus+Less+ECharts+FontAwesome
- 动态路由(数据库菜单驱动)
- 蓝白配色, H5响应式
- 登录/注册/忘记密码/个人中心
- 班级创建向导/详情/加入/列表
- 管理后台: 审核/配置/菜单/统计/用户/敏感词

数据库: MySQL 10.31.100.3:3306/photowall
管理员: hero920103 / 920103

2026-09-03 05:55:23 +08:00

16 KiB

Raw Permalink Blame History

毕业照墙（PhotoWall）立项说明

本文档为项目开发基准，所有功能开发须遵循本文档定义，不得偏离设计核心。

一、项目概述

1.1 项目定位

一个面向全球用户的毕业照存储与同学联络平台。用户可以按国家→省/州→县/区→学校→学院→班级的层级组织毕业照，每个班级留存唯一一张毕业照，每位成员可在班级下留存最多 10 张个人当期照片，同时通过学习履历、联系方式等功能促进同学间的长期联络。

1.2 项目目标

建立覆盖全球的行政区划与学校组织架构
为每个班级提供唯一毕业照存档与个人照片墙
通过严格的身份验证机制（8 人姓名验证 / 邀请码）确保班级成员真实性
通过平台审核机制确保毕业照与名单一致性
提供同学间联系方式共享，促进长期联络

二、核心功能需求

2.1 组织架构（地区 → 学校 → 学院 → 班级）

层级	说明	是否必填
国家	覆盖全球所有国家	是
省/州	国家下的省级行政区（含直辖市、州、府等）	是
县/区	最低层级，学校必须挂载在区/县级下	是
学校	区/县下的学校，含类型区分	是
学院	仅大学/职业学校有学院层级	大学必填，其他无
班级	学校（+学院）下的具体班级	是

学校类型：大学（university）、职业学校/中专（vocational）、高中（senior_high）、初中（junior_high）、小学（primary）、幼儿园（kindergarten）、其他（other）。

班级唯一性：同一学校 + 学院 + 年级 + 班级序号 + 毕业年份唯一。

2.2 毕业照与个人照片

班级毕业照：每个班级唯一一张，由班级管理员上传。
个人当期照片：每位班级成员可在该班级下留存最多 10 张个人照片，附在班级照片墙下。
照片存储在本地文件系统，生产环境建议替换为对象存储（OSS）。

2.3 班级创建与审核流程

用户创建班级（需有学习履历）
    ↓
上传毕业照 + 录入全班同学姓名 + 老师姓名
    ↓
┌─ 同学姓名 < 8 人 ──→ 直接打回（rejected），需补齐
│
└─ 同学姓名 ≥ 8 人 ──→ 待审核（pending）
                            ↓
                    平台管理员巡查审核
                            ↓
              ┌─ 照片与名单一致 ──→ 通过（active）
              │
              └─ 不一致/有问题 ──→ 打回（rejected），需补齐
                                        ↓
                                30 天内未补齐完成
                                        ↓
                                系统自动删除班级（取消创建）

关键规则：

创建班级的人自动成为班级管理员。
管理员可将管理员身份转移给同班其他成员。
审核截止时间为创建时间 + 30 天，逾期未通过自动删除。
被打回后管理员可补齐资料重新提交审核。

2.4 加入班级的两种方式

方式一：管理员邀请（邀请码）

管理员生成邀请码（可设置最大使用次数、有效期）。
成员输入邀请码直接加入，无需验证姓名。
邀请码可被管理员禁用。

方式二：搜索加入（8 人姓名验证）

用户搜索到目标班级（仅 active 状态可被搜索）。
用户需正确说出该班级至少 8 位同学的姓名（须与毕业照名单完全一致）。
全部验证通过后方可加入。

设计意图：确保加入者确实是该班级成员，防止陌生人混入。

2.5 用户学习履历

每位用户可维护自己的学习履历（学校、学院、专业、学历、起止年份、备注）。
没有学习履历的用户不允许创建班级。
学习履历是创建班级的前置门槛。

2.6 用户联系方式

同班成员可互相查看联系方式。各类型数量上限：

联系方式类型	上限	说明
邮箱（email）	2
QQ	5
微信（wechat）	2
手机号（phone）	5
家庭住址（address）	1
工作单位（workunit）	1

可设置某条为"主要联系方式"。

2.7 平台管理员

平台管理员负责班级审核巡查、打回、通过、删除。
可查看数据概览（用户数、班级数、各状态班级数、学校数、照片数）。
可手动触发过期班级清理。
默认账号：admin / admin123456（首次启动自动创建）。

三、技术架构

3.1 技术栈

层级	技术选型	说明
后端语言	Go 1.22+
Web 框架	Gin
ORM	GORM
数据库	MySQL 8.0	utf8mb4 字符集
表前缀	`yz_pw_`	所有业务表统一前缀
认证	JWT
密码加密	bcrypt
前端框架	Vue 3 + Vite
路由	Vue Router 4
HTTP 客户端	Axios
移动端	UniApp（规划中，暂不开发）	生成 APK + 小程序

3.2 数据库配置

配置项	值
地址	10.31.100.3:3306
用户名	photowall
密码	Dfn47yeKpyJfwz8n
数据库名	photowall
字符集	utf8mb4
表前缀	yz_pw_

支持通过环境变量覆盖：DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME、DB_CHARSET。

3.3 项目目录结构

photowall/
├── go/                          # Go 后端
│   ├── cmd/server/main.go       # 入口
│   ├── internal/
│   │   ├── config/              # 配置
│   │   ├── database/            # 数据库初始化 + 种子数据
│   │   ├── model/               # 数据模型
│   │   ├── handler/             # HTTP Handler
│   │   ├── service/             # 业务逻辑
│   │   ├── middleware/          # 中间件（JWT、权限）
│   │   ├── router/              # 路由注册
│   │   └── scheduler/           # 定时任务（30天清理）
│   ├── pkg/                     # 工具包（jwt、hash、response）
│   ├── uploads/                 # 上传文件存储
│   └── go.mod
│
├── vue/                         # Vue3 前端（H5/PC 自适应）
│   ├── src/
│   │   ├── api/                 # API 封装
│   │   ├── assets/              # 静态资源
│   │   ├── components/          # 全局公共组件
│   │   ├── composables/         # 组合式函数
│   │   ├── router/              # 路由
│   │   └── views/               # 页面（按功能模块分层）
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
│
└── doc/                         # 项目文档
    └── 立项说明.md               # 本文档

四、前端页面目录规范

所有页面按功能模块 → 基层操作分层，每个基层文件夹包含 index.vue + components/（该页面专用组件）。

views/
├── auth/                     # 认证模块
│   └── login/
│       ├── index.vue
│       └── components/
├── home/                     # 首页/工作台
│   ├── index.vue
│   └── components/
├── class/                    # 班级模块
│   ├── list/                 # 班级列表/搜索
│   │   ├── index.vue
│   │   └── components/
│   ├── edit/                 # 创建/编辑班级
│   │   ├── index.vue
│   │   └── components/
│   ├── detail/               # 班级详情（毕业照、照片墙、成员）
│   │   ├── index.vue
│   │   └── components/
│   └── join/                 # 加入班级
│       ├── index.vue
│       └── components/
├── normalsettings/           # 基本设置模块
│   ├── usersettings/         # 用户设置
│   │   ├── list/             # 个人中心首页
│   │   ├── edit/             # 编辑资料
│   │   └── detail/           # 用户详情
│   ├── rolesettings/         # 角色设置
│   │   ├── list/
│   │   ├── edit/
│   │   └── detail/
│   └── logmanagement/        # 日志管理
│       ├── list/
│       └── detail/
└── admin/                    # 管理后台
    └── audit/                # 审核管理
        ├── list/             # 审核队列
        │   ├── index.vue
        │   └── components/
        └── detail/           # 审核详情/日志
            ├── index.vue
            └── components/

五、H5 / 响应式适配要求

5.1 适配原则

前端页面必须同时适配 PC 端和移动端 H5。
使用响应式布局，以移动端优先（Mobile First）为基础，逐步增强 PC 端展示。
核心操作在手机端必须可完成（创建班级、上传照片、加入班级、审核等）。

5.2 断点规范

断点	设备类型	宽度范围
xs	手机竖屏	< 576px
sm	手机横屏/小平板	≥ 576px
md	平板	≥ 768px
lg	笔记本/桌面	≥ 992px
xl	大屏桌面	≥ 1200px

5.3 适配要点

容器宽度：PC 端最大宽度 1200px 居中，移动端全屏铺满。
表单：PC 端多列并排（form-row），移动端单列堆叠。
表格：PC 端正常表格，移动端可考虑卡片式布局或横向滚动。
照片网格：使用 CSS Grid auto-fill + minmax 自适应列数。
弹窗：PC 端居中固定宽度，移动端接近全屏（底部弹出或全屏）。
字体：使用 rem 或 vw 单位适配，基准字号 14px。
触摸友好：按钮最小点击区域 44×44px，间距适中。
图片上传：支持移动端相机拍照和相册选择。

六、UniApp 版本规划（暂不开发）

6.1 目标

基于 UniApp 开发跨端版本，编译生成：

Android APK（安卓应用）
微信小程序源码
（可选）iOS、H5、其他小程序平台

6.2 与 Vue 版的关系

Vue 版（vue/ 目录）为 H5/PC Web 端，优先开发。
UniApp 版后续独立创建目录（建议 uniapp/），复用后端 API。
两端共享同一套后端接口，数据完全互通。

6.3 UniApp 开发要点（预留）

使用 Vue 3 + UniApp（Vue3 语法模式）。
页面结构与 Vue 版保持一致的功能模块划分。
图片上传需适配 UniApp 的 uni.uploadFile。
APK 打包需配置证书、权限（相机、存储、网络）。
小程序端需适配微信小程序的域名白名单、上传限制等。
登录态存储使用 uni.setStorageSync。

6.4 开发优先级

UniApp 版本暂缓开发，待 Vue Web 端核心功能稳定后启动。当前阶段仅在本文档中记录规划，不创建代码。

七、数据模型概要

核心表（表前缀 yz_pw_）：

表名	说明
users	用户
user_contacts	用户联系方式
education_histories	用户学习履历
regions	地区（国家/省/县三级自关联）
schools	学校
colleges	学院（仅大学）
classes	班级（含毕业照、同学/老师名单、审核状态）
class_members	班级成员
class_photos	班级个人照片（每人每班级≤10张）
invitations	班级邀请码
audit_logs	班级审核日志
sms_codes	短信验证码
password_resets	密码重置码
system_configs	系统配置（16项，5分类）
menus	动态路由菜单（20个默认菜单）
upload_files	文件上传记录（MD5去重）
sensitive_words	敏感词库（DFA全局屏蔽）

八、平台管理功能（补充）

8.1 数据统计仪表盘

核心指标：总用户数、学校总数、班级总数、照片总数、待审核/已通过/被打回班级数、封禁用户数
增长趋势：近7天用户增长、近7天班级增长（折线图）
分布统计：班级状态分布（饼图）、学校类型分布（柱状图）、毕业年份分布（柱状图）
地区排名：班级数量TOP10地区

8.2 系统配置管理

16项配置，分5类：基础配置、极验配置、短信配置、微信配置、存储配置
每项配置含：显示名称、说明、输入框示例、官方文档/获取地址链接
后台可视化编辑，保存后即时生效（部分需重启）

8.3 菜单管理（动态路由）

菜单数据存储在数据库，登录后按角色动态加载路由
树形结构，支持增删改查、排序、显示/隐藏、权限控制
20个默认菜单初始化

8.4 用户管理（封禁/解封）

管理员可封禁违规账号，填写封禁原因
被封禁用户无法登录，提示封禁原因
支持解封操作
不能封禁管理员账号

8.5 敏感词全局屏蔽

DFA算法高效检测
支持分类管理（政治/色情/暴力/广告/辱骂/其他）
支持启用/禁用单个敏感词
班级创建时自动检测名称，包含敏感词则拦截
内容发布时可扩展检测（简介、描述等）

九、技术特性（补充）

9.1 认证与安全

JWT Token，有效期3小时，超时前端强制跳转登录
密码使用盐+MD5加密（随机盐，每用户不同）
图形验证码（PNG图片，4位字符，5分钟过期，一次性）
开发万能验证码：888888
注册/登录均需验证码
忘记密码：邮箱重置码（30分钟有效，开发模式直接返回）

9.2 文件上传

支持班级毕业照、个人照片、头像三类
单文件最大10MB
MD5去重：相同文件只存一份，ref_count引用计数
重复上传直接返回已有文件路径

9.3 数据隔离

班级照片和联系方式只有班级成员或超级管理员可见
非成员访问班级详情时，照片和联系方式返回空
删除照片只有本人/班级管理员/超级管理员可操作

9.4 Redis集成

go-redis/v9，默认localhost:6379无密码
连接失败自动降级为内存模式（保证开箱即用）
用于验证码存储、缓存等

9.5 前端技术栈

Vue3 + Vite + Vue Router4 + Axios
Element Plus 组件库（中文语言包）
Less 样式预处理器
蓝白配色（主白和灰，主色#1890ff）
FontAwesome 图标（不用Element图标）
ECharts 数据可视化
WangEditor 富文本编辑器（预留）
H5响应式适配

9.6 第三方服务预留

极验行为验证（geetest_id/key，留空则用自建图形验证码）
短信验证码（阿里云/腾讯云，留空则开发模式直接返回）
微信扫码登录（微信开放平台，留空则功能隐藏）
所有参数在系统配置页面可视化填写

十、开发计划与里程碑

阶段	内容	状态
M1	后端骨架 + 数据库 + 认证 + 地区/学校/班级核心接口	已完成
M2	前端 Vue 核心页面（登录、首页、创建班级、班级详情、加入班级、个人中心）	已完成
M3	平台管理员审核后台 + 30天自动清理	已完成
M4	前端 H5 响应式适配完善	已完成
M5	前端目录结构规范化（list/edit/detail + components）	已完成
M6	Element Plus + Less + FontAwesome 前端重构 + 动态路由	已完成
M7	系统配置 + 菜单管理 + 数据统计仪表盘	已完成
M8	用户封禁 + 敏感词全局屏蔽 + 文件MD5去重 + 数据隔离	已完成
M9	注册/忘记密码/短信/微信登录预留	已完成
M10	UniApp 版本（APK + 小程序）	暂缓

九、约束与注意事项

不得偏离本文档定义的核心需求，开发前须先阅读本文档。
所有数据库表必须使用 yz_pw_ 前缀。
班级创建必须校验用户有学习履历。
同学名单少于 8 人必须打回，不得通过。
加入班级的搜索方式必须验证 8 人姓名全部正确。
超过审核截止时间（30天）未通过的班级必须自动删除。
个人照片每人每班级严格限制 10 张。
联系方式各类型数量上限必须在后端校验。
前端页面必须适配 H5 移动端，不得仅适配 PC。
UniApp 版本暂缓，仅在文档中记录规划。

16 KiB Raw Permalink Blame History Unescape Escape