- 代码缩进使用4个空格。
- 多个单词组成的变量名使用下划线分割，如
user_name。 - 文件名尽量也使用下划线命名法，如
article_blueprint.py。 - 代码段落直接应该用空行隔开。
- 用不到的引用(import)语句应该删除。
- 代码提交前需要先在本地运行一遍，确保没有报错。
- 每次提交都应使用
gitmoji，即一个表情加更新的内容概述。 - 表情的挑选需要依照gitmoji官网。选择最符合每次提交内容的表情，例如 “:rocket: 部署了课友群功能。”。注意表情与文字之间有一个空格，而且必须以句号结尾。建议多次小量的提交代码更改，尽量避免一次更新过多代码。
在克隆项目后，需要在项目根目录下创建classified.py文件。里面所需要建立的变量请看classified.py文件
部分内容。
需要安装requirements.txt中的所有依赖。
需要确保MySQL数据库已经安装并且已经启动。同时需要建立了名为ucsdcssa_website的数据库。
需要确保Redis数据库已经安装并且已经启动。
同时需要在assets文件夹中创建courses-qr-codes文件夹。并在文件夹中放入所有课程的二维码图片。
图片命名与格式要求请看courses-qr-codes文件夹部分内容。
需要确保所有图片都为.jpg(后缀必须是小写)。同时assets文件夹中需要有生成的courses_grouped.json和department.json文件。
有两种方式确保这些：
-
根据自己的系统，运行
utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。 并查看assets文件夹中是否有生成的courses_grouped.json和department.json文件。 -
手动查看并修改所有图片的后缀为
.jpg，然后手动运行utils文件夹中的get_courses_grouped_json.py文件来生成assets文件夹中关于课程分组的courses_grouped.json文件。 还需要运行同一文件夹下的get_department_json.py文件来生成assets文件夹中关于部门信息的department.json文件。
需要运行flask服务器后，在终端中cd到项目根目录并运行flask db init、flask db migrate、flask db upgrade命令来初始化数据库。
如果中间有报错，如过报错提示的是需要安装依赖则安装依赖。如果报错的是其他，可尝试删除migrations
文件夹与数据库中的alembic_version表。
然后再重新跑上方的三个命令。
图片格式要求为.jpg。三个字母必须全部小写，因此.JPG文件必须改为.jpg。.jpeg或其他格式也是不行的。
图片最好进行压缩以方便快速加载，可以使用这个网站进行压缩。
需要存在于项目根目录下。
这个文件没有加入版本控制是因为涉及到了一些敏感信息，如数据库密码、邮箱密码等。所以需要自己创建。
classified.py文件中需要有设置以下变量。可以复制下方代码并根据说明更换为相应的值：
DB_PASSWORD = "更换为你的MySQL数据库密码"
MAIL_USERNAME = "更换为你发送验证码的邮箱"
MAIL_PASSWORD = "更换为发送验证码邮箱的邮箱密码，有些邮箱网站可能需要手动生成应用专用密码，可以网上自行搜索一下步骤"
MAIL_DEFAULT_SENDER = '更换为你发送验证码的邮箱'
BACKEND_ADDRESS = "更换为后端地址，例如如果在本地跑，就写'http://127.0.0.1:{flask服务端口号}'。如果在服务器跑就写'https://api.ucsd.com'。"
"""
获取微信公众号文章
参考文章：https://www.mianshigee.com/note/detail/38130ncd/
COOKIE: 从浏览器里复制过来的cookie
TOKEN: 从浏览器里复制过来的token
"""
COOKIE = "跟着上方注释的教程走，这里更换为你网络请求的cookie"
TOKEN = "跟着上方注释的教程走，这里更换为你网络请求的token"需要存在于assets文件夹中。
这个文件夹没有加入版本控制是为了防止代写。
里面所有图片的命名格式为{专业简写} {课程号}.jpg。例如CSE 12.jpg。
文件名中间的空格是必须的，且其必须是英文空格，不能是中文空格。
需要存在于assets文件夹中。
里面所有图片的命名格式为{部门名}合照.jpg。例如主席团合照.jpg、开发部合照.jpg。
文件名中不能有空格。
需要存在于assets文件夹中。
里面所有图片的命名格式为{部门名}-{姓名}-{职位}.jpg。例如开发部-张三-部长.jpg、主席团-李四-主席.jpg。
文件名中不能有空格。
职位是用来排序的。排序顺序为主席、副主席、秘书、开发部部长、人事部部长、外联部部长、文体部部长、新媒体部部长、宣传部部长、
学术部部长、部长、成员。如果有其他职位例如设计组组长，则其会被排序在部长与部员之间。
部长的照片需要出现两次。以开发部部长为例，需要有主席团-张三-开发部部长.jpg和开发部-张三-部长.jpg两张图片。
下方为错误命名的例子：
开发部-张三-开发部部长.jpg，这里的开发部部长是错误的，应该是部长。因为前面开头的部门已经指向了开发部。外联部-李四-外联部部员.jpg，这里的外联部部员是错误的，应该是部员。因为前面开头的部门已经指向了外联部。主席团 - 王五 - 主席.jpg，这里的错误的原因是文件名有空格。主席团 赵六 主席.jpg，这里的错误的原因是需要用-而不是空格进行连接。文件名中是不能有空格的。
把courses-qr-codes文件夹中的图片全部删除，然后重新放入新的图片。
删除courses_grouped.json(其实不删也行，会自动覆盖。删除是为了确保真的生成了新的文件)。
然后像项目运行要求中的部分一样，有两种方法更新：
- 根据系统，运行
utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。ubuntu系统第一次需要先在utils目录下运行chmod +x format_courses_and_department.sh来给予执行权限。
- 手动查看并修改所有图片的后缀为
.jpg，然后手动运行utils文件夹中的get_courses_grouped_json.py文件来生成assets文件夹中关于课程分组的courses_grouped.json文件。
运行完后，需要查看在assets文件夹是否已经生成了courses_grouped.json文件。
把departments-group-photos
文件夹中不需要的旧照片全部删除，然后放入新的图片。确保照片名符合图片格式要求
和departments-group-photos文件夹
文档部分的命名规范。
把members-photos
文件夹中不需要的旧照片全部删除，然后放入新的图片。确保照片名符合图片格式要求
和members-photos文件夹文档部分的命名规范。
如果需要，修改assets文件夹中的departments_description.json文件。其中每个部门的recruit字段是HTML代码。
可以使用这个网站编辑文本，然后直接生成HTML代码并复制进来。
如果成立了新部门，需要在departments_description.json文件中添加新部门的信息。
确保上方都更新好之后，删除原有的department.json文件然后有两种方法生成新的department.json文件：
- 根据系统，运行
utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。ubuntu系统第一次需要先在utils目录下运行chmod +x format_courses_and_department.sh来给予执行权限。
- 手动查看并修改所有图片的后缀为
.jpg，然后手动运行utils文件夹中的get_department_json.py文件来生成assets文件夹中关于部门信息的department.json文件。
运行完后，需要查看在assets文件夹是否已经生成了department.json文件。
如果需要更新服务器的文章，则首先需要根据这个教程，
设置好classified.py的COOKIE和TOKEN字段。
然后用浏览器或软件Postman访问{flask地址}/crawl-articles/{要爬的文章数量}即可。例如:
- 如果需要在服务器上爬取100篇文章，则访问
https://api.ucsdcssa.com/crawl-articles/100 - 如果需要在本地爬取50篇文章，则访问
http://127.0.0.1:{你的端口号}/crawl-articles/50，例如http://127.0.0.1:667/crawl-articles/50
然后自己去MySQL数据库中查看是否已经爬取成功。
每条文章的所有字段除了headline_index和categories外，都是非空的。
headline_index决定了文章是否出现在头条的位置，如果为NULL则不会出现在头条的位置。如果不为NULL
，则会根据值的大小来决定文章在头条的位置。值越小，文章越靠前。
categories决定文章的类别。默认为NULL，所以文章只会出现在全部中。如果想增加类别，则需要在categories中添加类别名。类别名之间用空格分隔。
例如categories为CSSA原创，则文章会出现在CSSA原创和全部中。如果categories为CSSA原创 学术干货
，则文章会出现在CSSA原创、学术干货和全部中。
类别的可选值在前端代码中的src/staticVariables.js文件。
目前的可选值为：CSSA原创、活动推文、学术干货、新生必读、生活周边、政策要闻、独家赞助、其他。
- 这里要注意
全部不是一个可选值，而是在前端代码中用来布局的。
- 首先确保更改都已经发布到
GitHub上。 - 打开网站的宝塔面板，在左侧侧边栏中选中“网站”页面，并在上方选中“其他项目”。
- 找到项目
ucsdcssa_website_backend并点击服务状态列的运行中▶以停止项目，确保其状态变成||未启动。 - 在左侧侧边栏中找到“文件”页面并打开。然后打开网站目录：
/www/wwwroot/ucsdcssa-website-backend。 - 点击上方的终端，并在终端中运行
git pull按回车，然后根据提示输入相关用户名与密码或口令。 git抓取成功后，在左侧侧边栏中选中“网站”页面，并在上方选中“其他项目”。- 找到项目
ucsdcssa_website_backend并点击服务状态列的||未启动以启动项目，确保其状态变成运行中▶。
文档顺序是根据代码中的顺序来的。
-
GET /courses：获取所有按照首字母分组的课程信息。- 请求参数（需要在headers中）
- id：
string类型，用于验证身份，必填。 - token：
string类型，用于验证身份，必填。
- id：
- 返回值
JSON格式的课程信息。
- 请求参数（需要在headers中）
-
GET /courses/{course_name}/{id}/{token}：获取指定课程的二维码。- 请求参数（需要直接放在请求路径中）
- course_name：
string类型，课程名，必填。 - id：
string类型，用于验证身份，必填。 - token：
string类型，用于验证身份，必填。- 这里需要
token验证是为了防止代写通过直接访问接口从而获取到课程的二维码。
- 这里需要
- course_name：
- 返回值
- 指定课程的二维码图片。
- 示例
GET /courses/CSE 12/VdaMSEHtjc3dxUPBCcrnG3/FuOgozzNXUOXOhaOXBKoGET /courses/CSE%2012/VdaMSEHtjc3dxUPBCcrnG3/FuOgozzNXUOXOhaOXBKo- 这里的
%20是空格的URL编码，不过无论用URL编码还是直接用空格都是支持的。
- 这里的
- 请求参数（需要直接放在请求路径中）
-
GET /assistants/{id}: 获取指定小助手的二维码。- 请求参数（需要直接放在请求路径中）
- id：
int类型，小助手的id，必填。- 如需要访问小助手1的二维码，则id为1。如需要访问小助手2的二维码，则id为2。
- id：
- 示例
GET /assistants/1
- 返回值
- 指定小助手的二维码图片。
- 请求参数（需要直接放在请求路径中）
-
GET /crawl-articles/{num}：爬取指定数量的文章到数据库。- 请求参数（需要直接放在请求路径中）
- num：
int类型，要爬取的文章数量，必填。
- num：
- 返回值：成功后会返回"文章获取成功"。
- 请求参数（需要直接放在请求路径中）
-
GET /articles/{offset_num}/{category}：获取指定类别的文章。- 请求参数（需要直接放在请求路径中）
- offset_num：
int类型，偏移量，必填。- 例如：如果offset_num为0，则返回第1篇文章到第10篇文章。
- 如果offset_num为10，则返回第11篇文章到第20篇文章。
- 如果offset_num为20，则返回第21篇文章到第30篇文章。
- 以此类推。
- category：
string类型，文章类别，必填。- 可选值为
全部、CSSA原创、活动推文、学术干货、新生必读、生活周边、政策要闻、独家赞助、其他。 - 如果为
全部，则返回所有类别的文章。
- 可选值为
- offset_num：
- 返回值
JSON格式的文章信息。
- 请求参数（需要直接放在请求路径中）
-
GET /headlines：获取头条文章。- 返回值
JSON格式的头条文章信息。
- 返回值
-
GET /department/{department_name}: 获取指定部门的信息。- 请求参数（需要直接放在请求路径中）
- department_name：
string类型，部门名，必填。
- department_name：
- 返回值
JSON格式的部门信息。
- 请求参数（需要直接放在请求路径中）
-
GET /member/{department_name}/{member_name}: 获取指定部门的指定成员的照片。- 请求参数（需要直接放在请求路径中）
- department_name：
string类型，部门名，必填。 - member_name：
string类型，成员名，必填。
- department_name：
- 返回值
- 指定部员的照片。
- 请求参数（需要直接放在请求路径中）
-
GET /group-photo/{department_name}: 获取指定部门的部门合照。- 请求参数（需要直接放在请求路径中）
- department_name：
string类型，部门名，必填。
- department_name：
- 返回值
- 指定部门的部门合照。
- 请求参数（需要直接放在请求路径中）
-
POST /register: 注册用户。- 请求参数（需要在form中）
- email：
string类型，邮箱，必填。 - username：
string类型，用户名，必填。 - password：
string类型，密码，必填。 - captcha：
string类型，验证码，必填。
- email：
- 返回值
- id：
string类型，用户唯一标识。 - token：
string类型，此次登录的token。
- id：
- 请求参数（需要在form中）
-
POST /catpcha: 获取验证码。- 请求参数（需要在form中）
- email：
string类型，邮箱，必填。 - purpose：
string类型，验证码用途，必填。- 可选值为
注册、重置密码。
- 可选值为
- email：
- 返回值
- 如果成功则无返回值。
- 请求参数（需要在form中）
-
POST /login: 登录。- 请求参数（需要在form中）
- email：
string类型，邮箱，必填。 - password：
string类型，密码，必填。
- email：
- 返回值
- id：
string类型，用户唯一标识。 - token：
string类型，此次登录的token。
- id：
- 请求参数（需要在form中）
-
PUT /reset-password: 重置密码。- 请求参数（需要在form中）
- email：
string类型，邮箱，必填。 - password：
string类型，新密码，必填。 - captcha：
string类型，验证码，必填。
- email：
- 返回值
- 如果成功则无返回值。
- 请求参数（需要在form中）
-
GET /users/{id}: 获取指定用户的信息。- 请求参数（需要直接放在请求路径中）
- id：
string类型，用户唯一标识，必填。
- id：
- 请求参数（需要在headers中）
- token：
string类型，登录后产生的token，必填。
- token：
- 返回值
JSON格式的用户信息。
- 请求参数（需要直接放在请求路径中）
-
DELETE /users/{id}: 删除指定用户。- 请求参数（需要直接放在请求路径中）
- id：
string类型，用户唯一标识，必填。
- id：
- 请求参数（需要在headers中）
- token：
string类型，登录后产生的token，必填。
- token：
- 返回值
- 如果成功则无返回值。
- 请求参数（需要直接放在请求路径中）
-
PUT /users/{id}: 更新指定用户的信息除邮箱和密码外的信息。- 请求参数（需要直接放在请求路径中）
- id：
string类型，用户唯一标识，必填。
- id：
- 请求参数（需要在headers中）
- token：
string类型，登录后产生的token，必填。
- token：
- 请求参数（需要在form中）
- username：
string类型，用户名，选填。 - real_name：
string类型，真实姓名，选填。 - avatar：
string类型，头像，选填。- 为图片的base64编码。
- purchased:
bool类型，是否购买了CSSA卡，选填。 - card_number:
string类型，CSSA卡号，选填。
- username：
- 返回值
- 如果成功则无返回值。
- 请求参数（需要直接放在请求路径中）
-
GET /: 测试服务器是否正常运行。- 返回值
- 字符串
欢迎使用UCSD CSSA官网后端API。具体接口用法请参考GitHub仓库里的README.md。仓库地址：https://github.com/TallMessiWu/ucsdcssa-website-backend
- 字符串
- 返回值
-
GET /thumbnail: 获取缩略图。- 图片要求
- 返回的图片就是
assets文件夹中的thumbnail.jpg。这里后缀必须是小写的.jpg以满足项目规范的一致性。 - 图片需要小于300kb并且最小尺寸为300 x 200。
- 图片尺寸最佳为 1200 x 630。
- 可以用这个网站调整图片尺寸。
- 可以用这个网站测试网站缩略图等信息。测试网站地址填
https://www.ucsdcssa.com。
- 返回的图片就是
- 返回值
- 网站缩略图(即
index.html的<head>标签里<meta property="og:image">的content属性内容)。
- 网站缩略图(即
- 图片要求
| 姓名 | 个人邮箱 | UCSD邮箱 | 项目贡献 |
|---|---|---|---|
| 吴俊霖 | [email protected] | [email protected] | 项目搭建者，同时制定了项目规范。构建了项目以及确认了项目所使用的依赖包等。撰写了文章、课程、用户、部门相关功能接口与文档。同时编写了网站缩略图接口与文档。此外还设计了相关功能所涉及的数据库表格与表格结构。具体贡献可查询GitHub提交历史。 |