前端 2023-2024 计划

[FranGuam]

这里是网站组前端小队今年的计划，会根据进度及时调整，请队员们查收~

[FranGuam]

目前的饼

1. UI优化

   • 整体的审美意义下的美化
   • 对手机、平板等各端的适配
   • 信息展现形式的优化（特别是天梯，与第3点有关）
   • 支持暗色模式、导览等高级功能（与第2点有关）

2. 解决依赖问题

   • 重点是antd从v4升级到v5（已影响开发）
   • 其他还有node、less和react整体升级
   • 清理多余的依赖、制定依赖引入的指导性原则
   • 开启并优化自动依赖升级和lint等CI功能

3. 数据库整理

   • 用户组和权限融合调整
   • 减少未用的键的查询，目标是一个页面配一个graphql
   • 整理表结构，允许比赛常态化（与第5点有关）
   • 改用GraphQL Code Generator生成接口

4. 项目结构整理

   • 文件夹整理和重命名（目的是减少冗余、让人一看就懂）
   • 将单页中的数据获取、Hooks和返回的页面元素分离
   • 将可复用的api归并到一起，以便后续与后端统筹安排

5. 深度融合队式比赛

   • 继续支持WebGL观看回放功能
     • 主要是催促界面组（新功能：进度条）
   • 比赛直播功能（可能需要我们自己做简易界面）
   • 比赛试玩功能（与比赛直播功能类似）
   • 提升参赛者从报名前到比赛后的全流程指引效果
     • 指引窗、链接、优化信息展示
   • 比赛管理员的全流程优化
   • 尝试PWA、Electron或React Native构建本地应用
     • 主要优势：无需联网、断点续传（可直接访问本地文件）、界面美观提升体验

6. 课程评测和资源分享

   • 确定UI和数据库结构
   • 课程反馈功能、课程资源分享功能
   • 其他经验分享功能

7. Docs和Overleaf维护

   • Docs尝试接入分享平台
   • Overleaf重新启用

8. 用户注册流程拓展

   • 关联Github账户（为资源分享做准备）
   • 关联微信账户（为微信推送和未来的小程序做准备）

9. 与后端对接的部分

   • 用户注册流程（从mongo迁移到hasura）
   • 静态资源的获取（cos存储策略和api访问方法）

工作计划

【学习】第一阶段 9.18 - 10.15

• 目标
  • 配置环境
  • 对前端使用的整体技术栈和框架有基本的了解
• 任务和分工
  • 能在本地运行前端代码
  • 查阅资料，每人画一张前端开发/生产的项目框架图

【学习】第二阶段 10.15 - 12.3

• 目标
  • 掌握TypeSript语言使用和Debug方法
  • 提第一个PR，熟悉Git协作方式
  • 理解纵向开发->测试->生产->部署的流程和项目管理方法（依赖、命令）
• 任务和分工
  • 将antd从v4升到v5
  • 清理其他依赖，需要的一并升级

【学习】第三阶段 12.3 - 1.7

• 目标
  • 掌握GraphQL的代码写作和调用方法
  • 尝试改变UI，理解React组件的含义（与页面的对应关系）
  • 理解横向页面->虚拟DOM->数据库/后端的流程和项目文件结构（调用关系）
• 任务和分工（第一次分工）
  • 代码整理（具体要求见下一条评论）
    • @youyc22 : ContestSite
    • @lqs22yeah : InfoSite & HomeSite
    • @ljxuann : ShareSite & UserSite

【开发】第一阶段 3.3 - 3.31

• 目标
  • 整理和稳定版本（2024版）
• 任务和分工（延续第一次分工）
  • Debug
  • UI优化

【开发】第二阶段 4.1 - 5.12

• 目标
  • 聚焦比赛站大改版
• 任务和分工（第二次分工）
  • @youyc22 : 天梯排名页、数据分析页、管理员页面、角色选择功能
  • @lqs22yeah : 代码提交页
  • @ljxuann : 赛事信息页
  • @zou-y-t : 组队报名页、代码提交页

【开发】第三阶段 5.13 - 6.30

• 目标
  • 开启新方向
• 任务和分工（第三次分工）
  • @ljxuann : 主页UI升级
  • @zou-y-t : 新生导师Bug fix
  • @lqs22yeah : 推送通知功能
  • @VanellopeAsher : Weekly自动更新功能
  • @youyc22 & @zzdhybthu : 课程共享平台

【尾声】2024.7 - 2024.9

• 目标
  • 整理文档与交接
• 任务
  • 完善接口文档
  • 维护仓库设置（依赖包升级）
  • 制定2024-2025计划

[FranGuam]

代码整理的具体要求

流程与方法

1. 替换原有获取数据的函数，改用GraphQL CodeGen生成的接口

   • 从/generated/graphql.tsx引入useXXXSuspenseQuery/ useXXXSuspenseMutation，XXX与之前的函数同名
   • 使用方法可以到/generated/graphql.tsx中函数就近的注释中查询，变量名均不变
   • loading全部删去，改用<Suspense>（Suspense – React 中文文档）

2. 调整代码顺序，理解每部分大致功能（用分割线分隔各部分）

   • 把所有不需要每次渲染时更新（不依赖于hooks和props）的定义移到组件外面
   • 把states和props的定义移到组件最前面
   • 把获取数据用的hook放在第二位、useEffect放在第三位
   • 把其他函数分门别类放在后面

3. 尝试改变UI，体会代码与页面之间的关系

   • 可以先尝试修改return部分，例如将某个组件添加或删除
   • 记得在修改之前commit所有更改，方便之后回退
   • Feel free to explore!

4. 修复antd升级和暗色模式导致的API和样式不兼容

   • 观察代码，如有删除线的API意味着已弃用，搜索antd官方文档改用相应新API
   • F12打开开发者工具中的控制台/console，点开每个页面，解决控制台中报的warning
   • 点开每一个页面，若有明显样式错误的地方（可与当前官网比较）尝试修复
   • 切换到暗色模式，重复上一步，善用PageProps中的mode（可学习src/index.tsx的写法）

5. 构建页面数据模型，整理GraphQL语句

   • 整理出该页面最终用来显示或处理逻辑的最少数据，用伪代码写出其Object表示
   • 在hasura console中观察表结构，明确从页面变量到所需数据的查询路径/修改路径
   • 在src/graphql中为每个页面新建一个同名.graphql文件（例如PlaybackPage.tsx -> playback.graphql）
   • 在hasura console中实现的查询路径/修改路径并复制代码到.graphql文件中，注意改用变量为查询值
   • yarn generate后调用生成的接口，测试是否满足功能要求
   • 尽量使用主键和唯一索引（即xxx_by_pk，xxx_one）进行查询，若查询表总和用xxx_aggregate

6. 进一步规整代码，可参考的要求有

   • 明确所有变量的类型，避免使用any
   • 最后的return要简洁，长的组件和带有业务逻辑的函数拿到前面定义
   • 几个页面都使用了的业务逻辑函数可以在src/api新建ts文件提高复用
   • 几个页面都使用了的组件可以在src/app/Components新建tsx文件提高复用
   • 思考每个组件和功能更简单的实现方法

参考的文件结构

import X from XXX;
/* ---------------- 接口和类型定义 ---------------- */
interface XXXProps {
    mode: String;
}
/* ---------------- 不随渲染刷新的常量和组件 ---------------- */
const Container = ({mode}) => styled.div`
    color: ${mode}
`;
/* ---------------- 主页面 ---------------- */
const XXXPage: React.FC<XXXProps> = ({mode}) => {
    /* ---------------- States 和引入的 Hooks ---------------- */
    const [mode, setMode] = useState("black");
    const url = useUrl();
    /* ---------------- 从数据库获取数据的 Hooks ---------------- */
    const {data, error} = useXXXSuspenseQuery({
        variables: {
            key: value;
        }
    });
    /* ---------------- useEffect ---------------- */
    useEffect(() => console.log(error), [error]);
    /* ---------------- 业务逻辑函数 ---------------- */
    const handleUpload = (file: XXX) => {
        return uploadFile(file);
    };
    /* ---------------- 随渲染刷新的组件 ---------------- */
    const Content = () => {
        if (mode === "black") return <Button onClick={handleUpload} />;
        else return "This is empty.";
    };
    /* ---------------- 页面组件 ---------------- */
    return (
        <Container mode={mode}>
            <Content />
        </Container>
    );
}

export default XXXPage;