/ucsdcssa-website-backend

UCSD CSSA官网后端

Primary LanguagePython

UCSD CSSA官网后端

官网入口

API入口

前端GitHub仓库

后端GitHub仓库

目录

代码样式

  1. 代码缩进使用4个空格。
  2. 多个单词组成的变量名使用下划线分割，如user_name。
  3. 文件名尽量也使用下划线命名法，如article_blueprint.py。
  4. 代码段落直接应该用空行隔开。
  5. 用不到的引用(import)语句应该删除。

代码提交要求

  1. 代码提交前需要先在本地运行一遍，确保没有报错。
  2. 每次提交都应使用gitmoji，即一个表情加更新的内容概述。
  3. 表情的挑选需要依照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文件。 有两种方式确保这些：

  1. 根据自己的系统，运行utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。 并查看assets文件夹中是否有生成的courses_grouped.json和department.json文件。

  2. 手动查看并修改所有图片的后缀为.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文件

需要存在于项目根目录下。

这个文件没有加入版本控制是因为涉及到了一些敏感信息，如数据库密码、邮箱密码等。所以需要自己创建。

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"

courses-qr-codes文件夹

需要存在于assets文件夹中。

这个文件夹没有加入版本控制是为了防止代写。

里面所有图片的命名格式为{专业简写} {课程号}.jpg。例如CSE 12.jpg。

文件名中间的空格是必须的，且其必须是英文空格，不能是中文空格。

departments-group-photos文件夹

需要存在于assets文件夹中。

里面所有图片的命名格式为{部门名}合照.jpg。例如主席团合照.jpg、开发部合照.jpg。

文件名中不能有空格。

members-photos文件夹

需要存在于assets文件夹中。

里面所有图片的命名格式为{部门名}-{姓名}-{职位}.jpg。例如开发部-张三-部长.jpg、主席团-李四-主席.jpg。

文件名中不能有空格。

职位是用来排序的。排序顺序为主席、副主席、秘书、开发部部长、人事部部长、外联部部长、文体部部长、新媒体部部长、宣传部部长、 学术部部长、部长、成员。如果有其他职位例如设计组组长，则其会被排序在部长与部员之间。

部长的照片需要出现两次。以开发部部长为例，需要有主席团-张三-开发部部长.jpg和开发部-张三-部长.jpg两张图片。

下方为错误命名的例子：

  1. 开发部-张三-开发部部长.jpg，这里的开发部部长是错误的，应该是部长。因为前面开头的部门已经指向了开发部。
  2. 外联部-李四-外联部部员.jpg，这里的外联部部员是错误的，应该是部员。因为前面开头的部门已经指向了外联部。
  3. 主席团 - 王五 - 主席.jpg，这里的错误的原因是文件名有空格。
  4. 主席团 赵六 主席.jpg，这里的错误的原因是需要用-而不是空格进行连接。文件名中是不能有空格的。

更新信息

更新课友群

把courses-qr-codes文件夹中的图片全部删除，然后重新放入新的图片。 删除courses_grouped.json(其实不删也行，会自动覆盖。删除是为了确保真的生成了新的文件)。

然后像项目运行要求中的部分一样，有两种方法更新：

  1. 根据系统，运行utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。
  2. 手动查看并修改所有图片的后缀为.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文件：

  1. 根据系统，运行utils文件夹中的format_courses_and_department.bat或format_courses_and_department.sh文件。
  2. 手动查看并修改所有图片的后缀为.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原创、活动推文、学术干货、新生必读、生活周边、政策要闻、独家赞助、其他。

  • 这里要注意全部不是一个可选值，而是在前端代码中用来布局的。

网站更新指南

  1. 首先确保更改都已经发布到GitHub上。
  2. 打开网站的宝塔面板，在左侧侧边栏中选中“网站”页面，并在上方选中“其他项目”。
  3. 找到项目ucsdcssa_website_backend并点击服务状态列的运行中▶以停止项目，确保其状态变成||未启动。
  4. 在左侧侧边栏中找到“文件”页面并打开。然后打开网站目录：/www/wwwroot/ucsdcssa-website-backend。
  5. 点击上方的终端，并在终端中运行git pull按回车，然后根据提示输入相关用户名与密码或口令。
  6. git抓取成功后，在左侧侧边栏中选中“网站”页面，并在上方选中“其他项目”。
  7. 找到项目ucsdcssa_website_backend并点击服务状态列的||未启动以启动项目，确保其状态变成运行中▶。

API接口

文档顺序是根据代码中的顺序来的。

课友群相关接口

  • GET /courses：获取所有按照首字母分组的课程信息。

    • 请求参数（需要在headers中）
      • id：string类型，用于验证身份，必填。
      • token：string类型，用于验证身份，必填。
    • 返回值
      • JSON格式的课程信息。

  • GET /courses/{course_name}/{id}/{token}：获取指定课程的二维码。

    • 请求参数（需要直接放在请求路径中）
      • course_name：string类型，课程名，必填。
      • id：string类型，用于验证身份，必填。
      • token：string类型，用于验证身份，必填。
        • 这里需要token验证是为了防止代写通过直接访问接口从而获取到课程的二维码。
    • 返回值
      • 指定课程的二维码图片。
    • 示例
      • GET /courses/CSE 12/VdaMSEHtjc3dxUPBCcrnG3/FuOgozzNXUOXOhaOXBKo
      • GET /courses/CSE%2012/VdaMSEHtjc3dxUPBCcrnG3/FuOgozzNXUOXOhaOXBKo
        • 这里的%20是空格的URL编码，不过无论用URL编码还是直接用空格都是支持的。

  • GET /assistants/{id}: 获取指定小助手的二维码。

    • 请求参数（需要直接放在请求路径中）
      • id：int类型，小助手的id，必填。
        • 如需要访问小助手1的二维码，则id为1。如需要访问小助手2的二维码，则id为2。
    • 示例
      • GET /assistants/1
    • 返回值
      • 指定小助手的二维码图片。

文章相关接口

  • GET /crawl-articles/{num}：爬取指定数量的文章到数据库。

    • 请求参数（需要直接放在请求路径中）
      • num：int类型，要爬取的文章数量，必填。
    • 返回值：成功后会返回"文章获取成功"。

  • 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原创、活动推文、学术干货、新生必读、生活周边、政策要闻、独家赞助、其他。
        • 如果为全部，则返回所有类别的文章。
    • 返回值
      • JSON格式的文章信息。

  • GET /headlines：获取头条文章。

    • 返回值
      • JSON格式的头条文章信息。

部门信息相关接口

  • GET /department/{department_name}: 获取指定部门的信息。

    • 请求参数（需要直接放在请求路径中）
      • department_name：string类型，部门名，必填。
    • 返回值
      • JSON格式的部门信息。

  • GET /member/{department_name}/{member_name}: 获取指定部门的指定成员的照片。

    • 请求参数（需要直接放在请求路径中）
      • department_name：string类型，部门名，必填。
      • member_name：string类型，成员名，必填。
    • 返回值
      • 指定部员的照片。

  • GET /group-photo/{department_name}: 获取指定部门的部门合照。

    • 请求参数（需要直接放在请求路径中）
      • department_name：string类型，部门名，必填。
    • 返回值
      • 指定部门的部门合照。

用户相关接口

  • POST /register: 注册用户。

    • 请求参数（需要在form中）
      • email：string类型，邮箱，必填。
      • username：string类型，用户名，必填。
      • password：string类型，密码，必填。
      • captcha：string类型，验证码，必填。
    • 返回值
      • id：string类型，用户唯一标识。
      • token：string类型，此次登录的token。

  • POST /catpcha: 获取验证码。

    • 请求参数（需要在form中）
      • email：string类型，邮箱，必填。
      • purpose：string类型，验证码用途，必填。
        • 可选值为注册、重置密码。
    • 返回值
      • 如果成功则无返回值。

  • POST /login: 登录。

    • 请求参数（需要在form中）
      • email：string类型，邮箱，必填。
      • password：string类型，密码，必填。
    • 返回值
      • id：string类型，用户唯一标识。
      • token：string类型，此次登录的token。

  • PUT /reset-password: 重置密码。

    • 请求参数（需要在form中）
      • email：string类型，邮箱，必填。
      • password：string类型，新密码，必填。
      • captcha：string类型，验证码，必填。
    • 返回值
      • 如果成功则无返回值。

  • GET /users/{id}: 获取指定用户的信息。

    • 请求参数（需要直接放在请求路径中）
      • id：string类型，用户唯一标识，必填。
    • 请求参数（需要在headers中）
      • token：string类型，登录后产生的token，必填。
    • 返回值
      • JSON格式的用户信息。

  • DELETE /users/{id}: 删除指定用户。

    • 请求参数（需要直接放在请求路径中）
      • id：string类型，用户唯一标识，必填。
    • 请求参数（需要在headers中）
      • token：string类型，登录后产生的token，必填。
    • 返回值
      • 如果成功则无返回值。

  • PUT /users/{id}: 更新指定用户的信息除邮箱和密码外的信息。

    • 请求参数（需要直接放在请求路径中）
      • id：string类型，用户唯一标识，必填。
    • 请求参数（需要在headers中）
      • token：string类型，登录后产生的token，必填。
    • 请求参数（需要在form中）
      • username：string类型，用户名，选填。
      • real_name：string类型，真实姓名，选填。
      • avatar：string类型，头像，选填。
        • 为图片的base64编码。
      • purchased: bool类型，是否购买了CSSA卡，选填。
      • card_number: string类型，CSSA卡号，选填。
    • 返回值
      • 如果成功则无返回值。

其他接口

项目贡献名单

姓名 个人邮箱 UCSD邮箱 项目贡献
吴俊霖 junlin-wu@foxmail.com juw029@ucsd.edu 项目搭建者，同时制定了项目规范。构建了项目以及确认了项目所使用的依赖包等。撰写了文章、课程、用户、部门相关功能接口与文档。同时编写了网站缩略图接口与文档。此外还设计了相关功能所涉及的数据库表格与表格结构。具体贡献可查询GitHub提交历史。