# 毕业照墙（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 版本暂缓，仅在文档中记录规划。