# Overview

本篇文章介绍了 Management Portal UI 这个项目基本的 code base 和目前（截止更新日期：11/18/2020）已经实现的一些可复用组件/逻辑/工具等，来帮助新加入的 contributors 快速的熟悉项目和上手开发，同时可以避免一些重复的开发工作。

## Project Skeleton

项目的整体目录结构如下图所示：

![project skeleton](./images/project-skeleton.png)

### Common Components

已经实现的一些通用组件, 可复用的 UI 功能组件等：

![components skeleton](./images/components-skeleton.png)

- Layout
  - App Layout Wrapper
  - Header
  - Sidebar
  - Breadcrumb
- UI Components
  - AccountMenu（顶部导航栏上的用户 Account/Profile 菜单）
  - CollapseCell（Table 中需要折叠面板显示的 Cell）
  - Loader（目前只封装了 page 级别的 Loader）
  - MessageBar（消息提醒 Bar，目前多用于 Form 表单提交后的 Error Message 显示）
- Composite Components
  - ModalForm (Form wrapped with a Modal)
  - Table
    - useTable hook（封装了 Table 中更新 dataSource, pagination 等 state 相关的逻辑）
    - ListToolBar（一些对于列表整体的操作）
    - ActionCell（一些针对某一行数据的操作）

### API Client

项目中使用 [openpai-generator](https://github.com/OpenAPITools/openapi-generator) 来自动生成基于 typescript-axios 的 apiClient, 需要后端定义好的 swagger.json 支持。如何使用请参考 README.md 中的 [Contributing and Developing](../README.md#contributing-and-developing) 部分。

通过运行 `yarn run gen:api` 脚本后，自动生成的 OpenAPIs 相关文件都放在 `./src/apiClient/openapi` 目录中（目前使用 generated `apis` 和 `models` separately 的模式，且只用到了 models 定义部分），`./src/apiClient/openapi` 目录结构如下图：

![api client skeleton](./images/api-client-skeleton.png)

其中，除了自动生成的 `api` 目录之外，剩下的一些文件是一些与业务相关的 auth0, axios 和 endpoint 的相关配置。

### Utils

已实现的一些工具 hooks 或者方法（比如，money/time 等特殊数据的格式化方法，number/string 等数据类型的一些常用操作等）：

![utils skeleton](./images/utils-skeleton.png)

### Styling and Theming

在介绍了 js/jsx 方面的结构之后，下面简单介绍关于 Styling code 的组织结构：

整体来说，目前我们使用 ant-design 提供的默认 design guide, 一些关于 default 样式的 less 变量定义在 `~antd/lib/style/themes/default.less` 文件中，开发中只是针对个别样式进行了微调。

全局样式代码定义在 `global.less` 中，包含一些常用的工具类（flex, align, center, container 等）, 而 `App.less` 则作为整个项目基础样式定义的 imports 入口，如图：

![app.less](./images/app-less.png)

其余针对不同 Components 的 Styling code，都会定义在当前 Component 的目录下，如：

![component.less](./images/component-less.png)

## Others

其次，`@types` 目录中是一些类型定义文件 `.d.ts`, `pages` 目录中是项目所有 routes 对应的页面实现（全局的 routes 定义在 `./src/routes.tsx` 中），`images` 目录中是项目中用到的所有图片资源。

除此之外还有一些项目配置相关的文件，本篇文章就不过多展开介绍，以后根据不同的专题会有具体的文章详细介绍。