GeekApk basic design document 📑🚀

GeekApkSpec.tex

% GeekApk basic design document
% License: CC-BY
% Author: duangsuse
% Toolchain: XeLaTeX

\documentclass[a4paper, 11pt]{article}

% XeTex is utf8 based
%\usepackage[utf8]{inputenc}

\usepackage[T1]{fontenc}
\usepackage{lmodern}

% Hyperlinks
\usepackage[colorlinks]{hyperref}

% Highlight
\usepackage{xcolor}
\usepackage{listings}

% Tightlists
\newcommand{\tightlist}{
	\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
	
% Pandoc highlight
\usepackage{fancyvrb}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}

% Shaded
\newenvironment{Shaded}{}{}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{\textbf{{#1}}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.56,0.13,0.00}{{#1}}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{{#1}}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{{#1}}}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.25,0.63,0.44}{{#1}}}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{{#1}}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.25,0.44,0.63}{{#1}}}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.38,0.63,0.69}{\textit{{#1}}}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.00,0.44,0.13}{{#1}}}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{{#1}}}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.02,0.16,0.49}{{#1}}}
\newcommand{\RegionMarkerTok}[1]{{#1}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{1.00,0.00,0.00}{\textbf{{#1}}}}
\newcommand{\NormalTok}[1]{{#1}}

% CJK Support
\usepackage{fontspec, xunicode, xltxtra}

% CJK style
\usepackage[top = 1in, bottom = 1in, left = 1.25in, right = 1.25in]{geometry}

\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt minus 0.1pt

\renewcommand{\baselinestretch}{1.25}

\parindent 2em

% Set main font
\setmainfont{Source Han Serif CN}

% Article format

\title{GeekApk 标准参考文档}
\author{duangsuse}

% Main document

\begin{document}

\maketitle

\section{GeekApk 文档引子}

\subsection{文档简介}
GeekApk 是一个曾经酷友（酷安用户） 们自发组织创立的\textbf{开源 Android 应用社区}，它崇尚自由、设计时融合了\textbf{酷安、GooglePlay、GitHub、ApkPure、ApkMirror、F-Droid} 的优秀设计于一体，目标是成为一个能\textbf{替代酷安的应用市场兼社区}

\subsection{GeekApk 特性}
\begin{itemize}
	\item \textbf{熟悉的模型：} 用户、分类、应用、更新、评论，通知、星标、跟随、时间线
	\item \textbf{开放：} 完全以 AGPL-3.0 开放源代码，API 不需要验证客户端口令、开放数据库
	\item \textbf{可扩展：} 开放的 API，简易 JavaScript 插件系统，为插件支持优化的前后端设计
	\item \textbf{自由：} 不需要电话验证、发布软件不需要「开发者验证」证明你是开发者！一切和 GitHub 一样简单
	\item \textbf{Geek：} 简单的 Web 后端实现和 API，多样的客户端、自动脚本，时间线模式、软件包不限于 Apks
\end{itemize}

\subsection{许可证}
本文档使用 \textbf{CC-BY} 作为许可证，访问 \textbf{https://creativecommons.org/licenses/by/4.0/deed.zh}\\
GeekApk 应使用 \textbf{GNU Affero 通用公共许可证}（GNU AGPL） 3.0 或以上版本许可

\subsection{文档内容列表}
\begin{itemize}
	\item 项目风格模板
	\item 模型列表、JSON 对象举例说明
	\item 基本规则、API 操作枚举
	\item GitApk 对标准的实现
\end{itemize}

\pagebreak % Table of contents page

\tableofcontents

\pagebreak % 项目风格模板

\section{GeekApk 项目风格模板}

\begin{quote}
适用于 GitApk，也可以在微小改动后适配于 GeekApk 项目\\
GitApk 不同于很多其他的 Web 应用程序，它不是单独的后端服务，也不是由服务器渲染的网站，也没法变成纯静态网站 \\
GitApk 渲染器可以使用 HuGo、Hexo、Jekyll 等静态网站框架完成，也可以使用手写模板生成器完成
\end{quote}

\bigskip

\subsection{相对于项目根目录的文件}
\begin{itemize}
	\item \textbf{.editorconfig} 每个项目都有对应的编辑器风格配置文件
	\item \textbf{.gitignore} 使用 Git 进行源代码管理的项目都要添加 gitignore
	\item \textbf{.travis.yml} GeekApk 项目一般使用也只使用一个 CI 服务
	\item \textbf{CODE\_OF\_CONDUCT.md} 参与者公约，要包含中文版的链接
	\item \textbf{参与者公约.md} 参与者公约，中文版本
	\item \textbf{.github/CONTRIBUTING.md} GitHub 贡献指南
	\item \textbf{.github/ISSUE\_TEMPLATE.md} GitHub Issue 模板
	\item \textbf{.github/PULL\_REQUEST\_TEMPLATE.md} GitHub PR 模板
	\item \textbf{LICENSE} 项目许可证
	\item \textbf{README.md} 项目 README
	\item \textbf{\_config.yml} GitHub Pages 配置
\end{itemize}

\bigskip

\subsection{文件夹}
\begin{itemize}
	\item \textbf{bitmaps} GeekApk 徽标目录
	\item \textbf{documents} GeekApk 文档目录
	\item \textbf{easter} 欢乐打卡墙目录
	\item \textbf{gitapk} GitApk 渲染器工程
	\item \textbf{gitapk/templates} GitApk cHTML 模板
	\item \textbf{gitapk/js} GitApk ES6 脚本
	\item \textbf{gitapk/src} GitApk 源代码
\end{itemize}

\pagebreak % 数据库模型

\section{GeekApk 数据库模型}

\subsection{用户（可以星标应用、可以跟随用户，以被跟随数或创建时间排序）}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
uid & Integer & Int32 & 用户 ID \\
\hline
username & VarChar & String & 用户简单名 \\
\hline
nickname & VarChar & String & 用户名 \\
\hline
avatar & VarChar & String & 头像地址 \\
\hline
bio & Text & String & 自我介绍 \\
\hline
blocked & Boolean & Bool & 是否被屏蔽 \\
\hline
shash & VarChar & String & 分发密码 \\
\hline
hash & VarChar & String & 密码 \\
\hline
created & TimeStamp & Date & 创建时间 \\
\hline
\end{tabular}

\subsection{分类}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
tid & SmallInt & Int16 & 分类 ID \\
\hline
name & Text & String & 分类名 \\
\hline
\end{tabular}

\subsection{应用（可以按照星标数、评论数、更新时间、创建时间排序）}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
aid & Integer & Int32 & 应用 ID \\
\hline
package & VarChar & String & 应用包名，唯一性 \\
\hline
author & Reference(uid) & Int32 & 应用创建者 \\
\hline
category & Reference(tid) & Int16 & 应用分类 \\
\hline
name & Text & String & 应用名 \\
\hline
icon & VarChar & String & 应用图标链接 \\
\hline
readme & Text & String & Markdown 自述文本 \\
\hline
screenshots & VarChar & String & 截图 \\
\hline
created & TimeStamp & Date & 创建时间 \\
\hline
updated & TimeStamp & Date & 更新时间 \\
\hline
latest & SmallInt & Int16 & 最新版本号 \\
\hline
\end{tabular}

\subsection{更新（附加于应用）}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
for & Reference(aid) & Int32 & 所属应用 \\
\hline
reversion & SmallInt & Int16 & 修订号 \\
\hline
version & VarChar & String & 版本号 \\
\hline
updates & Text & String & 更新内容 \\
\hline
minsdk & SmallInt & Int16 & 最低 SDK 版本 \\
\hline
install & VarChar & String & 安装 Uri \\
\hline
created & TimeStamp & Date & 创建时间 \\
\hline
\end{tabular}

\subsection{评论（按照创建时间排序，属于用户，附加于应用）}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
cid & Integer & Int32 & 评论 ID \\
\hline
author & Reference(uid) & Int32 & 评论作者 \\
\hline
app & Reference(aid) & Int32 & 评论目标应用 \\
\hline
reply & Reference(cid)? & Int32 & 回复评论 \\
\hline
content & Text & String & 内容 \\
\hline
created & TimeStamp & Date & 创建时间 \\
\hline
updated & TimeStamp & Date & 更新时间 \\
\hline
replies & Integer & Int32 & 回复数 \\
\hline
\end{tabular}

\subsection{时间线}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
owner & Integer & Int32 & 时间线所属人 \\
\hline
type & SmallInt & Int16 & 时间线类型 \\
\hline
data & Integer & Int32 & 时间线数据 \\
\hline
created & TimeStamp & Date & 时间线发布（创建）时间 \\
\hline
\end{tabular}

\subsection{通知}
\begin{tabular}{|c|c|c|c|}
\hline
全局名称 & 类型 & 格式 & 解释 \\
\hline
owner & Integer & Int32 & 通知所属人 \\
\hline
type & SmallInt & Int16 & 通知类型 \\
\hline
data & Integer & Int32 & 通知数据 \\
\hline
created & TimeStamp & Date & 通知创建时间 \\
\hline
read & Boolean & Bool & 已读标记 \\
\hline
\end{tabular}

\pagebreak % JSON 文档

\section{GeekApk JSON 对象}

%% Generated by pandoc 2.0.6
%% Fixed by duangsuse

\hypertarget{ux7528ux6237}{%
\subsection{用户}\label{ux7528ux6237}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"uid"}\FunctionTok{:} \DecValTok{1}\FunctionTok{,}
    \DataTypeTok{"username"}\FunctionTok{:} \StringTok{"duangsuse"}\FunctionTok{,}
    \DataTypeTok{"nickname"}\FunctionTok{:} \StringTok{"duangsuse"}\FunctionTok{,}
    \DataTypeTok{"avatar"}\FunctionTok{:} \StringTok{"https://i.jpg.dog/img/9bb1c31af0f51e5b8d2e1ebb9318da3d.jpg"}\FunctionTok{,}
    \DataTypeTok{"bio"}\FunctionTok{:} \StringTok{"Salted fish, salty life...."}\FunctionTok{,}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1532180922}\FunctionTok{,}
    \DataTypeTok{"banned"}\FunctionTok{:} \KeywordTok{false}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{ux5206ux7c7b}{%
\subsection{分类}\label{ux5206ux7c7b}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"tid"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"name"}\FunctionTok{:} \StringTok{"系统工具/优化清理"}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{ux5e94ux7528}{%
\subsection{应用}\label{ux5e94ux7528}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"aid"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"package"}\FunctionTok{:} \StringTok{"kh.android.dir"}\FunctionTok{,}
    \DataTypeTok{"author"}\FunctionTok{:} \DecValTok{3}\FunctionTok{,}
    \DataTypeTok{"category"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"name"}\FunctionTok{:} \StringTok{"Dir"}\FunctionTok{,}
    \DataTypeTok{"icon"}\FunctionTok{:} \StringTok{"https://i.loli.net/2018/01/11/5a572dc8d8967.png"}\FunctionTok{,}
    \DataTypeTok{"readme"}\FunctionTok{:} \StringTok{"## Dir - 简单美观的 Android 垃圾清理工具}\CharTok{\textbackslash{}n\textbackslash{}n}\StringTok{- 阻止创建垃圾文件夹}\CharTok{\textbackslash{}n}\StringTok{> Dir 支持使用文件替换文件夹来尽可能地阻止垃圾文件夹复活}\CharTok{\textbackslash{}n}\StringTok{- 支持更多软件}\CharTok{\textbackslash{}n}\StringTok{> Dir 依靠来自社区的力量获得更多垃圾文件规则，包括那些小众应用}\CharTok{\textbackslash{}n}\StringTok{- Material Design}\CharTok{\textbackslash{}n}\StringTok{Dir 遵循 Material Design 设计，小巧美观}\CharTok{\textbackslash{}n}\StringTok{- 良心整洁 绿色应用}\CharTok{\textbackslash{}n}\StringTok{> Dir 无任何后台和推送，已通过绿色应用公约认证}\CharTok{\textbackslash{}n}\StringTok{## 权限清单}\CharTok{\textbackslash{}n}\StringTok{"}\FunctionTok{,}
    \DataTypeTok{"previews"}\FunctionTok{:} \StringTok{"http://image.coolapk.com/apk_image/2018/0111/6706e5403da311bd-128297-o_1c3iqijt71lmp19f3igf10l91nd310-uid-543424@1440x2560.png.t.jpg;http://image.coolapk.com/apk_image/2017/0710/screener_1499669411395-for-128297-o_1bklkjfa71bed1qgv5bg4fv62cq-uid-543424.png.t.jpg"}\FunctionTok{,}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1522181505}\FunctionTok{,}
    \DataTypeTok{"updated"}\FunctionTok{:} \DecValTok{1532081641}\FunctionTok{,}
    \DataTypeTok{"latest"}\FunctionTok{:} \DecValTok{23}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{ux8bc4ux8bba}{%
\subsection{评论}\label{ux8bc4ux8bba}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"cid"}\FunctionTok{:} \DecValTok{1}\FunctionTok{,}
    \DataTypeTok{"author"}\FunctionTok{:} \DecValTok{1}\FunctionTok{,}
    \DataTypeTok{"app"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"reply"}\FunctionTok{:} \KeywordTok{null}\FunctionTok{,}
    \DataTypeTok{"content"}\FunctionTok{:} \StringTok{"&em@doge/smile!&"}\FunctionTok{,}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1532082181}\FunctionTok{,}
    \DataTypeTok{"updated"}\FunctionTok{:} \KeywordTok{null}\FunctionTok{,}
    \DataTypeTok{"replies"}\FunctionTok{:} \DecValTok{1}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{ux66f4ux65b0}{%
\subsection{更新}\label{ux66f4ux65b0}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"for"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"version"}\FunctionTok{:} \StringTok{"1.62b"}\FunctionTok{,}
    \DataTypeTok{"reversion"}\FunctionTok{:} \DecValTok{36}\FunctionTok{,}
    \DataTypeTok{"install"}\FunctionTok{:} \StringTok{"https_dl://api.trumeet.top/dir/v1/beta?stable"}\FunctionTok{,}
    \DataTypeTok{"updates"}\FunctionTok{:} \StringTok{"fooooooo"}\FunctionTok{,}
    \DataTypeTok{"minsdk"}\FunctionTok{:} \DecValTok{21}\FunctionTok{,}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1532082513}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{timeline}{%
\subsection{时间线}\label{timeline}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"owner"}\FunctionTok{:} \DecValTok{1}\FunctionTok{,}
    \DataTypeTok{"type"}\FunctionTok{:} \DecValTok{1}\FunctionTok{,}
    \DataTypeTok{"data"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1532182596}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{ux901aux77e5}{%
\subsection{通知}\label{ux901aux77e5}}

\begin{Shaded}
\begin{Highlighting}[]
\FunctionTok{\{}
    \DataTypeTok{"created"}\FunctionTok{:} \DecValTok{1532182596}\FunctionTok{,}
    \DataTypeTok{"type"}\FunctionTok{:} \DecValTok{2}\FunctionTok{,}
    \DataTypeTok{"data"}\FunctionTok{:} \DecValTok{0}\FunctionTok{,}
    \DataTypeTok{"read"}\FunctionTok{:} \KeywordTok{false}
\FunctionTok{\}}
\end{Highlighting}
\end{Shaded}

\hypertarget{star-ux67d0ux5e94ux7528ux7684ux4ebaux67d0ux4eba-star-ux7684ux5e94ux7528ux8fd4ux56de}{%
\subsection{Star 某应用的人/某人 Star
的应用 / Follow 某人的/被某人 Follow
的返回列表返回}\label{star-ux67d0ux5e94ux7528ux7684ux4ebaux67d0ux4eba-star-ux7684ux5e94ux7528ux8fd4ux56de}}

按 Star 时间排行的 \textbf{空格分割 AID/UID 列表}

\begin{verbatim}
12 32 23 4 2
\end{verbatim}

%% End - Generated by pandoc 2.0.6

\pagebreak % 基本规划

\section{GeekApk 基本规则}

%% Generated by pandoc 2.0.6
%% Fixed by duangsuse

\hypertarget{ux5173ux4e8eux6a21ux578b}{%
\subsection{关于模型}\label{ux5173ux4e8eux6a21ux578b}}

GeekApk 里有这些模型：

\textbf{实体}：用户、分类、应用、更新、评论

\textbf{辅助}：时间线、通知

GeekApk 还支持 \textbf{用户 Star 应用}、\textbf{用户 Follow 用户}

\textbf{评论和更新} 附加在 \textbf{应用} 上

\textbf{评论} 可以被添加为 \textbf{评论} 的 \textbf{子评论}

\hypertarget{ux8be6ux7ec6ux4fe1ux606f}{%
\subsubsection{详细信息}\label{ux8be6ux7ec6ux4fe1ux606f}}

\begin{itemize}
\tightlist
\item
  用户有简易名称（唯一标识）、用户名和
  UID、头像链接、自我介绍、创建时间、管理员修改的小黑屋状态
\item
  分类有自己不可修改的 TID 和管理员修改的名称，一般以 \texttt{/}
  切分分类路径
\item
  应用有
  AID（内部使用的唯一标识）、包名（也是唯一标识）、管理员修改的创建用户引用、管理员修改的所属分类引用、名称、图标链接、应用描述、预览图像、创建时间、更新时间
\item
  更新有不可修改的所属应用引用、版本名、reversion、安装链接、更新内容、最低适配
  SDK 版本、创建时间
\item
  评论有
  CID、不可修改的创建用户引用、不可修改的所属应用引用、不可修改可空的被回复评论引用、内容、更新时间、被回复数、创建时间
\item
  时间线有所属用户引用、创建时间、类型、数据引用
\item
  通知有所属用户、创建时间、类型、数据引用、已读状态
\end{itemize}

\hypertarget{ux5173ux4e8eux6743ux9650}{%
\subsection{关于权限}\label{ux5173ux4e8eux6743ux9650}}

\begin{quote}
GeekApk 使用 \textbf{基于角色} 的权限制度
\end{quote}

GeekApk 中有三种角色：\textbf{访客、用户、权限狗（Doge）}

\textbf{任何人}，包括 \textbf{用户} 和 \textbf{权限狗}，同时也都是访客

所有人都 \textbf{无权修改} 创建时间和实体 ID，系统生成的 \textbf{时间线}
和 \textbf{通知}（除了 \textbf{已读} 字段）\textbf{不能修改和删除}

\textbf{权限狗是 GeekApk 的管理员}，管理员可以

\begin{itemize}
\tightlist
\item
  管理用户，如创建/删除用户、修改用户分发密码、ban/unban 用户
\item
  管理分类，如创建修改删除分类
\item
  删除实体，如删除应用、删除更新、删除评论
\item
  修改信息，如转移应用、移动应用到新分类
\end{itemize}

\textbf{用户是 GeekApk 的普通用户}，用户可以

\begin{itemize}
\tightlist
\item
  管理自我介绍
\item
  创建/删除和修改自己的应用，但不能移动应用到新分类
\item
  修改自己是协作者的应用，但不能移动应用到新分类
\item
  创建/删除和修改自己的/自己是协作者的应用的更新
\item
  创建评论、删除/修改自己的评论
\item
  读取和标记已读自己的通知
\item
  (Un)Follow 用户/(Un)Star 应用
\end{itemize}

\textbf{作为 GeekApk 访客}，我可以

\begin{itemize}
\tightlist
\item
  获得除了 \textbf{密码、通知} 外所有的 \textbf{只读权限} \textbf{“Read
  Access”}
\end{itemize}

\hypertarget{ux6743ux9650ux9a8cux8bc1ux5b9eux73b0}{%
\subsubsection{权限验证实现}\label{ux6743ux9650ux9a8cux8bc1ux5b9eux73b0}}

GeekApk \textbf{HTTP API} 使用 \textbf{Cookie} 来验证操作权限

\begin{itemize}
\tightlist
\item
  权限狗使用 \texttt{doge} cookie，服务器只有一个命名为
  \texttt{DOGE\_TOK} 的令牌，测试相等性
\item
  用户使用 \texttt{uid} 和 \texttt{hash} 两个
  cookie，服务器不会从执行的操作推测你的用户
  ID，如果没有权限或验证失败，返回 \textbf{HTTP 代码} Forbidden 和
  Unauthorized
\item
  用户可以使用 \texttt{shash}（分发密码）URL 参数来重置用户
  \texttt{hash}，只有一个 API 能这么做
\item
  计算密码的 Hash 值过程由客户端执行，服务器只把密码作为字符串看待
\item
  GeekApk 允许应用主添加其他用户作为 Collaborator
\end{itemize}

\hypertarget{why-not-jwtjson-web-tokens-otp}{%
\paragraph{\texorpdfstring{Why not \href{https://jwt.io/}{JWT}(JSON Web
Tokens) /
OTP}{Why not JWT(JSON Web Tokens) / OTP}}\label{why-not-jwtjson-web-tokens-otp}}

JWT
是很多网络应用使用的（临时）密码算法，由服务器生成的密码可以设置过期时间、自定义荷载等，基于复杂的密码学算法且非常安全，客户端在需要时可以使用用户密码生成新令牌使用，而生成的令牌中也可以包含客户端不可篡改的自定义数据以记录访问权限等信息，而
GeekApk 则使用 \texttt{hash} cookie 直接比对来验证用户身份

GeekApk
不想过多的添加依赖关系和增加处理逻辑复杂度（虽然使用中间件等不会使代码看启来更难看），希望验证系统在满足基本安全需求的情况下更加简单，所以，GeekApk
没有使用 JWT，而是直接采用了 \texttt{hash} 对比验证用户身份

OTP
是一次性密码生成算法，一般用于根据密钥生成临时密码，一般用于二次验证，GeekApk
不会将它作为主要验证方式，也不会提供 2fa（出于和 JWT 同样的考虑）

\hypertarget{ux5173ux4e8eux6570ux636eux683cux5f0f}{%
\subsection{关于数据格式}\label{ux5173ux4e8eux6570ux636eux683cux5f0f}}

\hypertarget{ux662f-markdown-ux6587ux672c}{%
\subsubsection{是 Markdown 文本}\label{ux662f-markdown-ux6587ux672c}}

\begin{itemize}
\tightlist
\item
  用户自我介绍
\item
  应用描述
\item
  更新内容
\item
  评论内容
\end{itemize}

\hypertarget{tzsjxnbdy}{%
\subsection{通知和时间线的内部定义}\label{tzsjxnbdy}}

括号内的是 \textbf{类型 ID}，可以在 \textbf{JSON} 和 \textbf{API} 参数里使用

\hypertarget{notifications}{%
\subsubsection{通知}\label{notifications}}

\begin{itemize}
\tightlist
\item
  用户的评论被回复（\texttt{1}）
\item
  用户被 \textbf{@} 提到（\texttt{2}）
\item
  用户被用户跟随（\texttt{3}）
\item
  用户被 Ban（\texttt{4}）
\item
  用户被 Unban（\texttt{5}）
\item
  用户删除了应用（\texttt{6}）
\item
  用户被添加为 Collaborator（\texttt{7}）
\end{itemize}

\hypertarget{tline}{%
\subsubsection{时间线}\label{tline}}

\begin{itemize}
\tightlist
\item
  用户 \textbf{跟随} 了某个用户（\texttt{1}）
\item
  用户 \textbf{创建} 了某个评论（\texttt{2}）
\item
  用户 \textbf{发布} 了某个应用（\texttt{3}）
\item
  用户 \textbf{更新} 了某个应用（\texttt{4}）
\item
  用户 \textbf{删除} 了某个应用（\texttt{5}）
\item
  用户 \textbf{星标} 了某个应用（\texttt{6}）
\item
  用户 \textbf{被添加} 为 Collaborator（\texttt{7}）
\end{itemize}

\hypertarget{ux5173ux4e8eux5206ux9875ux548cux6392ux5e8f}{%
\subsection{关于分页和排序}\label{ux5173ux4e8eux5206ux9875ux548cux6392ux5e8f}}

\hypertarget{ux5982ux4f55ux6392ux5e8f}{%
\subsubsection{如何排序}\label{ux5982ux4f55ux6392ux5e8f}}

\begin{itemize}
\tightlist
\item
  \textbf{用户} 执行 \textbf{全站排列或搜索时} 可以按照
  \textbf{跟随者数目、创建时间} 排序
\item
  \textbf{应用} 执行 \textbf{排列或搜索时} 可以按照
  \textbf{星标数、评论数、更新时间、创建时间} 排序
\item
  \textbf{评论} 使用创建时间排序
\end{itemize}

应用 \textbf{默认使用更新时间排序}，其他列出的默认使用
\textbf{创建时间}，没有列出的查询时的不会添加排序参数

\hypertarget{ux5982ux4f55ux5206ux9875}{%
\subsubsection{如何分页}\label{ux5982ux4f55ux5206ux9875}}

所有 \textbf{需要分页} 的请求都可以使用 \textbf{URL 参数} \texttt{start}
和 \texttt{limit}，意味着 \textbf{索引范围} 起止（\textbf{始于
\texttt{0}、包含最小值，不包含最大值}）

\texttt{limit} 将是 \textbf{SQL LIMIT 语句}
后的参数，它对使用分页的请求是 \textbf{必须} 的，\texttt{start}
参数不是必须的，它默认为 \texttt{0}

需要分页的 API 请求返回 \textbf{JSON 列表} 都在 \texttt{list}
字段里，表本身包含 \texttt{start}、\texttt{limit} 和 \texttt{total} 指示
\textbf{请求参数} 和服务端实际上的结果列表 \textbf{总长度}

如果 \texttt{start} 大于实际上 SQL
查询返回数据的长度，直接返回空列表，不然，返回裁剪过的列表

\hypertarget{ux5220ux9664ux65f6}{%
\subsection{删除时}\label{ux5220ux9664ux65f6}}

\textbf{用户、分类、应用、更新、评论、通知}
这些都可以删除，删除后将不会再出现使用 \textbf{同一 ID} 的新实体

\textbf{用户} 只能由 \textbf{管理员删除}，删除时所有他名下的
\textbf{应用} 都会 \textbf{自动删除}，管理员不能拒绝用户删除帐号

\begin{quote}
如果用户不想让应用随帐号被删除，可以提前将所有权移动到其他用户手上，所有权转交行为是由管理员执行的
\end{quote}

被删除用户的 Star 保留、评论全部删除，Following
全部删除，时间线和通知全部删除

\textbf{应用} 删除时自动删除其所有 \textbf{更新和评论}

\textbf{评论} 删除时自动删除其所有 \textbf{子评论}

\hypertarget{geekapk-ux8f6fux4ef6ux5de5ux7a0b}{%
\subsection{GeekApk ::
软件工程}\label{geekapk-ux8f6fux4ef6ux5de5ux7a0b}}

GeekApk
由少数的几个人开发维护，实现不是特别困难且工程量相对不小，也没有特别健壮、易维护、性能的要求，GeekApk
将使用
\href{https://zh.wikipedia.org/wiki/\%E7\%80\%91\%E5\%B8\%83\%E6\%A8\%A1\%E5\%9E\%8B}{瀑布模型}
开发

瀑布模型是十分简单：

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  需求定义（Requirements）
\item
  设计（Design）
\item
  实现（Implementation）
\item
  集成与测试（Verification）
\item
  移交与维护（Maintenance）
\end{enumerate}

GeekApk 在设计上更倾向于“\textbf{一次做好}”而不是“\textbf{渐进模式}”，这是出于
它漫长的设计期考虑

GeekApk
将编写完整的文档，包括代码内联注释文档和外部文档（\textbf{例如，HTTP
API、部署文档}）

GeekApk
会在内部留存一些调试代码，需要时应该能打开调试开关进行使用（他们是动态判断的，但在非调试编译中不应该引入降低性能）

开发者们会为 GeekApk
编写完整的单元测试、集成测试和验收测试，甚至对重要的部分进行性能测试（\textbf{即使我们不会主动考虑性能优化}），安全测试由于人员技能的原因暂时无法进行，欢迎外部贡献者在非生产环境中进行合理的安全测试并上报结果

GeekApk 主服务应该可以部署在任何拥有 Postgresql 服务的 64 位 Linux 4.x
服务器上

%% End - Generated by pandoc 2.0.6

\pagebreak % API 枚举

%% Generated by pandoc 2.0.6

\section{HTTPS API 枚举}

\begin{quote}
由 \textbf{duangsuse} 创建于 \textbf{2018.7.28}，版本 \textbf{0.1.0}
\end{quote}

\hypertarget{misc-apis}{%
\subsection{Misc APIs}\label{misc-apis}}

\begin{itemize}
\tightlist
\item
  获得服务程序版本() -\textgreater{} 文本
\item
  获得服务程序描述() -\textgreater{} 文本
\item
  获得主页() -\textgreater{} 静态 HTML
\end{itemize}

\hypertarget{admin-apisux53eaux6709-doge-ux53efux4ee5ux4f7fux7528}{%
\subsection{Admin APIs（只有 doge
可以使用）}\label{admin-apisux53eaux6709-doge-ux53efux4ee5ux4f7fux7528}}

\begin{itemize}
\tightlist
\item
  创建用户(body = inital\_simple\_name) -\textgreater{}
  \texttt{uid:rhash}
\item
  重置分发密码(uid, body = new\_rhash) -\textgreater{}
  \texttt{old\ rhash}
\item
  删除用户(uid) -\textgreater{} \texttt{uid}
\item
  改变用户屏蔽状态(uid, new\_state) -\textgreater{} \texttt{old\ state}
\item
  创建分类(body = name) -\textgreater{} \texttt{tid}
\item
  修改分类名(tid, body = new\_name) -\textgreater{}
  \texttt{tid:old\ name}
\item
  删除分类(tid) -\textgreater{} \texttt{tid}
\item
  删除应用(aid) -\textgreater{} \texttt{aid}
\item
  修改应用分类(aid, new\_category) -\textgreater{}
  \texttt{aid:old\ category}
\item
  转移应用所有权(aid, new\_owner) -\textgreater{}
  \texttt{aid:old\ owner}
\item
  删除应用更新(aid, reversion) -\textgreater{} \texttt{aid:reversion}
\item
  删除评论(cid) -\textgreater{} \texttt{cid:num\ deleted\ subcomments}
\end{itemize}

\hypertarget{category-apis}{%
\subsection{Category APIs}\label{category-apis}}

\begin{itemize}
\tightlist
\item
  获取所有分类() -\textgreater{} \texttt{categories\ json\ array}
\item
  获得分类名(tid) -\textgreater{} \texttt{name}
\end{itemize}

\hypertarget{user-apis}{%
\subsection{User APIs}\label{user-apis}}

\begin{itemize}
\tightlist
\item
  获取用户(uid) -\textgreater{} \texttt{user\ json} \textgreater{}
  可更新属性：\textbf{simple\_name、name、avatar、bio}
\item
  更新用户属性(uid, attr, body = new\_value) -\textgreater{}
  \texttt{attr:old\_value}
\item
  更新用户密码(uid, shash, new\_hash) -\textgreater{} \texttt{new\_hash}
\item
  检查密码() \textgreater{}
  搜索类型：\textbf{name/simple\_name/bio}、排行：\textbf{created/followers}
\item
  查找用户(type, sort, body = content) -\textgreater{}
  \texttt{paged\ user\ array}
\item
  获取用户列表(sort) -\textgreater{} \texttt{paged\ user\ array}
\end{itemize}

\hypertarget{timeline-apis}{%
\subsection{Timeline APIs}\label{timeline-apis}}

\begin{itemize}
\tightlist
\item
  获得用户的时间线(uid, only\_type, only\_ref) -\textgreater{}
  \texttt{paged\ timeline\ array}
\item
  获得所有人的时间线(only\_type, only\_ref) -\textgreater{}
  \texttt{paged\ timeline\ array}
\item
  获得一打用户的时间线(uids, only\_type, only\_ref) -\textgreater{}
  \texttt{paged\ timeline\ array}
\end{itemize}

\hypertarget{notification-apis}{%
\subsection{Notification APIs}\label{notification-apis}}

\begin{itemize}
\tightlist
\item
  获得我的活动通知() -\textgreater{} \texttt{notification\ array}
\item
  获得我的所有通知() -\textgreater{} \texttt{paged\ notification\ array}
\item
  将时间段内通知标为已读(start, end, stat) -\textgreater{}
  \texttt{number\ marked\ notifications}
\end{itemize}

\hypertarget{app-apis}{%
\subsection{App APIs}\label{app-apis}}

\begin{itemize}
\item
  获取应用(aid) -\textgreater{} \texttt{app} \textgreater{}
  可更新属性：\textbf{package、name、icon、previews、readme}
\item
  更新应用属性(aid, attr, body = new\_value) -\textgreater{}
  \texttt{attr:old\_value}
\item
  创建应用(package, category) -\textgreater{} \texttt{aid}
  \textgreater{}
  类型：\textbf{name/package/icon/readme}，排序：\textbf{updated/created/comments/stars}
\item
  查找应用(in\_category, body = content, type, sort) -\textgreater{}
  \texttt{paged\ app\ array}
\item
  根据包名查找应用(package) -\textgreater{} \texttt{aid}
\item
  获取应用列表(in\_category, sort) -\textgreater{}
  \texttt{paged\ app\ array}
\item
  删除应用(aid) -\textgreater{} \texttt{aid}
\item
  添加协作者(aid, uid) -\textgreater{} \texttt{aid:collaborators\ num}
\item
  移除协作者(aid, uid) -\textgreater{} \texttt{aid:collaborators\ num}
\item
  获取应用协作者(aid) -\textgreater{} \texttt{collab\ uid\ list}
\item
  获取用户协作的应用(uid) -\textgreater{} \texttt{collab\ aid\ list}
\end{itemize}

\hypertarget{update-apis}{%
\subsection{Update APIs}\label{update-apis}}

\begin{itemize}
\tightlist
\item
  获得应用的所有更新(aid) -\textgreater{} \texttt{update\ list}
\item
  获得一打应用的最新修订号(aids) -\textgreater{}
  \texttt{reversion\ list}
\item
  获取更新(aid, reversion) -\textgreater{} \texttt{update}
\item
  创建更新(aid, reversion) -\textgreater{} \texttt{aid:reversion}
  \textgreater{} 属性：\textbf{version/install/updates/minsdk}
\item
  修改更新属性(aid, reversion, attr, body = new\_value) -\textgreater{}
  \texttt{attr:old\_value}
\item
  删除更新(aid, reversion) -\textgreater{} \texttt{aid:reversion}
\end{itemize}

\hypertarget{comment-apis}{%
\subsection{Comment APIs}\label{comment-apis}}

\begin{itemize}
\tightlist
\item
  搜索评论(in\_app, user, replies\_to, content) -\textgreater{}
  \texttt{paged\ comment\ array}
\item
  列出评论(aid) -\textgreater{} \texttt{paged\ comment\ array}
\item
  列出子评论(cid) -\textgreater{} \texttt{paged\ comment\ array}
\item
  列出全站评论(in\_app, user, replies\_to) -\textgreater{}
  \texttt{paged\ comment\ array}
\item
  创建评论(aid) -\textgreater{} \texttt{aid:uid}
\item
  修改评论内容(cid, body = new\_content) -\textgreater{}
  \texttt{cid:aid:old\_content}
\item
  删除评论(cid) -\textgreater{} \texttt{cid}
\end{itemize}

\hypertarget{follow-apisux90fdux8fd4ux56deux65b0ux72b6ux6001ux6216-id-ux5217ux8868}{%
\subsection{Follow APIs（都返回新状态或 ID
列表）}\label{follow-apisux90fdux8fd4ux56deux65b0ux72b6ux6001ux6216-id-ux5217ux8868}}

\begin{itemize}
\tightlist
\item
  跟随用户(uid)
\item
  取消跟随用户(uid)
\item
  查询用户跟随者(uid)
\item
  查询用户跟随的用户列表(uid)
\end{itemize}

\hypertarget{star-apisux90fdux8fd4ux56deux65b0ux72b6ux6001ux6216-id-ux5217ux8868}{%
\subsection{Star APIs（都返回新状态或 ID
列表）}\label{star-apisux90fdux8fd4ux56deux65b0ux72b6ux6001ux6216-id-ux5217ux8868}}

\begin{itemize}
\tightlist
\item
  标记应用(aid)
\item
  取消标记应用(aid)
\item
  查询用户标记的应用(uid)
\item
  查询标记应用的用户(aid)
\end{itemize}

%% End - Generated by pandoc 2.0.6

\pagebreak % GitApk

%\section{GitApk - 在 Gitea 上运行的 GeekApk}

\pagebreak % 完结撒花

\end{document}