hero920103
57d9866dab
后端: 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
421 lines
16 KiB
Markdown
421 lines
16 KiB
Markdown
# 毕业照墙（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 + 小程序） | 暂缓 |
|
||
|
||
---
|
||
|
||
## 九、约束与注意事项
|
||
|
||
1. **不得偏离本文档定义的核心需求**，开发前须先阅读本文档。
|
||
2. 所有数据库表必须使用 `yz_pw_` 前缀。
|
||
3. 班级创建必须校验用户有学习履历。
|
||
4. 同学名单少于 8 人必须打回，不得通过。
|
||
5. 加入班级的搜索方式必须验证 8 人姓名全部正确。
|
||
6. 超过审核截止时间（30天）未通过的班级必须自动删除。
|
||
7. 个人照片每人每班级严格限制 10 张。
|
||
8. 联系方式各类型数量上限必须在后端校验。
|
||
9. 前端页面必须适配 H5 移动端，不得仅适配 PC。
|
||
10. UniApp 版本暂缓，仅在文档中记录规划。
|