Skip to main content

工单系统设计实现

· 11 min read

工单/Issues 系统都不会陌生,Github、Gitlab、Gitea 中每天都在接触的系统。想要学习如何设计实现最简单的是直接从别人的系统逻辑参考理解。

我理解的工单系统

  • 元数据丰富
  • 分类标签体系
  • 基于时间线呈现活动
  • 可扩展性强
  • 能封装出上层管理体系
    • 看板
    • 里程碑
    • 日历

Gitea

  • Issues 特性
    • 上下文切换 - 组织、当前用户
    • 模板
    • 里程碑
    • 标签
    • 指派
    • 时间跟踪
    • 回应 - 表情
    • 过滤
      • Open
      • Closed
      • 你的仓库
      • 被指派工单
      • 你创建的工单
      • 仓库
    • 排序: 最老的、最近更新、评论数量
    • 搜索、评论、附件
  • 数据模型位于 models
    • 13 个关于用户的模型文件
    • 23 个关于仓库的模型文件
    • 28 个关于工单的模型文件 - 是系统中最多的模块
  • 评论作为活动/指令,Issues 基于时间关联评论修改操作

核心 Issue 模型

// Issue represents an issue or pull request of repository.
type Issue struct {
ID int64 `xorm:"pk autoincr"`
RepoID int64 `xorm:"INDEX UNIQUE(repo_index)"`
Repo *Repository `xorm:"-"`
Index int64 `xorm:"UNIQUE(repo_index)"` // Index in one repository.
PosterID int64 `xorm:"INDEX"`
Poster *User `xorm:"-"`
OriginalAuthor string
OriginalAuthorID int64 `xorm:"index"`
Title string `xorm:"name"`
Content string `xorm:"TEXT"`
RenderedContent string `xorm:"-"`
Labels []*Label `xorm:"-"`
MilestoneID int64 `xorm:"INDEX"`
Milestone *Milestone `xorm:"-"`
Project *Project `xorm:"-"`
Priority int
AssigneeID int64 `xorm:"-"`
Assignee *User `xorm:"-"`
IsClosed bool `xorm:"INDEX"`
IsRead bool `xorm:"-"`
IsPull bool `xorm:"INDEX"` // Indicates whether is a pull request or not.
PullRequest *PullRequest `xorm:"-"`
NumComments int
Ref string

DeadlineUnix timeutil.TimeStamp `xorm:"INDEX"`

CreatedUnix timeutil.TimeStamp `xorm:"INDEX created"`
UpdatedUnix timeutil.TimeStamp `xorm:"INDEX updated"`
ClosedUnix timeutil.TimeStamp `xorm:"INDEX"`

Attachments []*Attachment `xorm:"-"`
Comments []*Comment `xorm:"-"`
Reactions ReactionList `xorm:"-"`
TotalTrackedTime int64 `xorm:"-"`
Assignees []*User `xorm:"-"`

// IsLocked limits commenting abilities to users on an issue
// with write access
IsLocked bool `xorm:"NOT NULL DEFAULT false"`

// For view issue page.
ShowTag CommentTag `xorm:"-"`
}

关联内容

  • 上下文关联: Repo, Project
  • 元信息关联: Poster, OriginalAuthor, PullRequest
  • 分类关联: Labels, Milestone
  • 指派关联: Assignee, Assignees
  • 内容关联: Attachments, Comments, Reactions

评论核心模型

// Comment represents a comment in commit and issue page.
type Comment struct {
ID int64 `xorm:"pk autoincr"`
Type CommentType `xorm:"INDEX"`
PosterID int64 `xorm:"INDEX"`
Poster *User `xorm:"-"`
OriginalAuthor string
OriginalAuthorID int64
IssueID int64 `xorm:"INDEX"`
Issue *Issue `xorm:"-"`
LabelID int64
Label *Label `xorm:"-"`
AddedLabels []*Label `xorm:"-"`
RemovedLabels []*Label `xorm:"-"`
OldProjectID int64
ProjectID int64
OldProject *Project `xorm:"-"`
Project *Project `xorm:"-"`
OldMilestoneID int64
MilestoneID int64
OldMilestone *Milestone `xorm:"-"`
Milestone *Milestone `xorm:"-"`
AssigneeID int64
RemovedAssignee bool
Assignee *User `xorm:"-"`
AssigneeTeamID int64 `xorm:"NOT NULL DEFAULT 0"`
AssigneeTeam *Team `xorm:"-"`
ResolveDoerID int64
ResolveDoer *User `xorm:"-"`
OldTitle string
NewTitle string
OldRef string
NewRef string
DependentIssueID int64
DependentIssue *Issue `xorm:"-"`

CommitID int64
Line int64 // - previous line / + proposed line
TreePath string
Content string `xorm:"TEXT"`
RenderedContent string `xorm:"-"`

// Path represents the 4 lines of code cemented by this comment
Patch string `xorm:"-"`
PatchQuoted string `xorm:"TEXT patch"`

CreatedUnix timeutil.TimeStamp `xorm:"INDEX created"`
UpdatedUnix timeutil.TimeStamp `xorm:"INDEX updated"`

// Reference issue in commit message
CommitSHA string `xorm:"VARCHAR(40)"`

Attachments []*Attachment `xorm:"-"`
Reactions ReactionList `xorm:"-"`

// For view issue page.
ShowTag CommentTag `xorm:"-"`

Review *Review `xorm:"-"`
ReviewID int64 `xorm:"index"`
Invalidated bool

// Reference an issue or pull from another comment, issue or PR
// All information is about the origin of the reference
RefRepoID int64 `xorm:"index"` // Repo where the referencing
RefIssueID int64 `xorm:"index"`
RefCommentID int64 `xorm:"index"` // 0 if origin is Issue title or content (or PR's)
RefAction references.XRefAction `xorm:"SMALLINT"` // What hapens if RefIssueID resolves
RefIsPull bool

RefRepo *Repository `xorm:"-"`
RefIssue *Issue `xorm:"-"`
RefComment *Comment `xorm:"-"`

Commits *list.List `xorm:"-"`
OldCommit string `xorm:"-"`
NewCommit string `xorm:"-"`
CommitsNum int64 `xorm:"-"`
IsForcePush bool `xorm:"-"`
}

因为评论同时表示了 Issue 的评论和 Commit 评论,因此包含了很多提交相关的信息。评论有相当多的类型

const (
// 普通评论 - 可关联到提交和行
CommentTypeComment CommentType = iota
CommentTypeReopen
CommentTypeClose

CommentTypeIssueRef // 工单引用
CommentTypeCommitRef // 提交引用
CommentTypeCommentRef // 评论引用
CommentTypePullRef // PR 引用
CommentTypeLabel // 标签修改
CommentTypeMilestone // 里程碑修改
CommentTypeAssignees // 指派人修改
CommentTypeChangeTitle // 标题修改
CommentTypeDeleteBranch // 删除分支
CommentTypeStartTracking // 开始时间跟踪
CommentTypeStopTracking // 结束时间跟踪
CommentTypeAddTimeManual // 手动添加时间跟踪信息
CommentTypeCancelTracking // 取消时间跟踪
CommentTypeAddedDeadline // 添加截止日期
CommentTypeModifiedDeadline // 修改截止日期
CommentTypeRemovedDeadline // 删除截止日期
CommentTypeAddDependency // 添加依赖
CommentTypeRemoveDependency // 删除依赖
CommentTypeCode // 评论代码行
CommentTypeReview // PR 评论反馈
CommentTypeLock // 锁定工单为协作者
CommentTypeUnlock // 解锁工单
CommentTypeChangeTargetBranch // 修改 PR 目标分支
CommentTypeDeleteTimeManual // 删除时间跟踪
CommentTypeReviewRequest // 添加或删除审核请求
CommentTypeMergePull // 合并 PR
CommentTypePullPush // 推送到 PR head 分支
CommentTypeProject // 修改项目
CommentTypeProjectBoard // 修改项目面板
)

评论类型非常详细,因为 Issues 是基于时间线的事件,评论等同于注释,每个注释都是一个命令,使用命令的方式才能实现时间线变化。

Gitlab

Gitlab 相比 Gitea 的 Issues 功能更加强大

Issues 功能特性

  • 内容: 标题, 描述, 任务
  • 人员: 作者, 指派人
  • 状态: 打开/关闭, 健康状态, 可信度, 任务完成度
  • 计划和跟踪: 里程碑, 截止日期,权重,时间跟踪,标签,投票,表情,工单关联,Epic 关联,唯一的编号和地址
  • 其他相关功能
    • 看板
    • Epic
    • 服务台/Service Deck
    • 外部集成
    • 带范围支持层级的 Label
    • 用户 Todo List
    • 燃尽图
    • 分组管理 - 组级别可统计和管理组内项目
    • 迭代
    • 设计管理
    • 价值流
    • 洞察

Issues 对于 Gitlab 来说不只是工单管理,在最基础的功能上实现了更多管理和分析相关的功能,作为有一定规模的团队,这些附加的功能都是很有必要的。

核心 issues  表

CREATE TABLE issues (
id integer NOT NULL,
title character varying,
author_id integer,
project_id integer, -- 项目管理
created_at timestamp without time zone,
updated_at timestamp without time zone,
description text,
milestone_id integer, -- 里程碑
iid integer, -- 项目内 ID
updated_by_id integer,
weight integer,
confidential boolean DEFAULT false NOT NULL, -- 隐秘
due_date date, -- 截止日期
moved_to_id integer, -- 迁移
lock_version integer DEFAULT 0,
title_html text,
description_html text,
time_estimate integer, -- 时间预估
relative_position integer,
service_desk_reply_to character varying,
cached_markdown_version integer,
last_edited_at timestamp without time zone,
last_edited_by_id integer,
discussion_locked boolean,
closed_at timestamp with time zone,
closed_by_id integer,
state_id smallint DEFAULT 1 NOT NULL, -- 状态
duplicated_to_id integer, -- 重复标志
promoted_to_epic_id integer, -- epic
health_status smallint, -- 健康状态
external_key character varying(255), -- 外部关联
sprint_id bigint, -- sprint 关联
issue_type smallint DEFAULT 0 NOT NULL, -- 类型
blocking_issues_count integer DEFAULT 0 NOT NULL,
CONSTRAINT check_fba63f706d CHECK ((lock_version IS NOT NULL))
);


-- 提及的用户
CREATE TABLE issue_user_mentions (
id bigint NOT NULL,
issue_id integer NOT NULL,
note_id integer,
mentioned_users_ids integer[],
mentioned_projects_ids integer[],
mentioned_groups_ids integer[]
);
-- 指派关系
CREATE TABLE issue_assignees (
user_id integer NOT NULL,
issue_id integer NOT NULL
);
-- 邮件 - service desk
CREATE TABLE issue_email_participants (
id bigint NOT NULL,
issue_id bigint NOT NULL,
created_at timestamp with time zone NOT NULL,
updated_at timestamp with time zone NOT NULL,
email text NOT NULL
);
-- slas
CREATE TABLE issuable_slas (
id bigint NOT NULL,
issue_id bigint NOT NULL,
due_at timestamp with time zone NOT NULL
);
-- 严重程度
CREATE TABLE issuable_severities (
id bigint NOT NULL,
issue_id bigint NOT NULL,
severity smallint DEFAULT 0 NOT NULL
);
-- epic
CREATE TABLE epic_issues (
id integer NOT NULL,
epic_id integer NOT NULL,
issue_id integer NOT NULL,
relative_position integer
);

Gitlab 不是通过注释来关联活动,而是通过 events 进行关联。例如

-- 迭代事件
CREATE TABLE resource_iteration_events (
id bigint NOT NULL,
user_id bigint NOT NULL,
issue_id bigint,
merge_request_id bigint,
iteration_id bigint,
created_at timestamp with time zone NOT NULL,
action smallint NOT NULL
);
-- 标签事件
CREATE TABLE resource_label_events (
id bigint NOT NULL,
action integer NOT NULL,
issue_id integer,
merge_request_id integer,
epic_id integer,
label_id integer,
user_id integer,
created_at timestamp with time zone NOT NULL,
cached_markdown_version integer,
reference text,
reference_html text
);
-- 里程碑事件
CREATE TABLE resource_milestone_events (
id bigint NOT NULL,
user_id bigint,
issue_id bigint,
merge_request_id bigint,
milestone_id bigint,
action smallint NOT NULL,
state smallint NOT NULL,
created_at timestamp with time zone NOT NULL
);
-- 状态事件
CREATE TABLE resource_state_events (
id bigint NOT NULL,
user_id bigint,
issue_id bigint,
merge_request_id bigint,
created_at timestamp with time zone NOT NULL,
state smallint NOT NULL,
epic_id integer,
source_commit text,
close_after_error_tracking_resolve boolean DEFAULT false NOT NULL,
close_auto_resolve_prometheus_alert boolean DEFAULT false NOT NULL,
source_merge_request_id bigint,
CONSTRAINT check_f0bcfaa3a2 CHECK ((char_length(source_commit) <= 40)),
CONSTRAINT state_events_must_belong_to_issue_or_merge_request_or_epic CHECK ((((issue_id <> NULL::bigint) AND (merge_request_id IS NULL) AND (epic_id IS NULL)) OR ((issue_id IS NULL) AND (merge_request_id <> NULL::bigint) AND (epic_id IS NULL)) OR ((issue_id IS NULL) AND (merge_request_id IS NULL) AND (epic_id <> NULL::integer))))
);
-- 权重事件
CREATE TABLE resource_weight_events (
id bigint NOT NULL,
user_id bigint,
issue_id bigint NOT NULL,
weight integer,
created_at timestamp with time zone NOT NULL
);

使用事件的模式则都是反向关联,扩展性相对通过 Type+条件字段 更好,模块之间影响也会更小。但需要查询所有的事件则会麻烦一点。

Gitlab 的 Issues 页面是在服务端生成的,且生成的内容会缓存,Markdown 生成的 HTML 会直接写入表中,某种程度上减少了需要客户端拉取所有事件的复杂度。

总结

虽然只看了 Gitea 和 Gitlab 的实现,但也足够有参考意义,如果要实现简单的工单系统,可能会选择第一种,但要实现复杂的逻辑则考虑选择第二种方式。