Trac 经验谈之（4）报表篇

Trac 经验谈之（1）杂谈篇
Trac 经验谈之（2）杂谈篇补遗
Trac 经验谈之（3）工作流篇
Trac 经验谈之（4）报表篇
Trac 经验谈之（5）插件篇
Trac 经验谈之（6 完）插件篇补遗
=================

Trac 经验谈之（4）报表篇

赖勇浩（http://laiyonghao.com）

最近又花时间折腾了一下 Trac 的用户体验，hack 了一个插件来实现属主（owner）的选择，重点是能够显示用户填入的中文昵称，这样大家找起人来方便。不过今天我们不谈这个，花开两朵，各表一枝，继续谈计划好的报表篇。
Trac 的报表功能是很强大、很灵活的，除了本身提供的各种报表，还可以由用户自由定制。我不知道别人怎么定义 Trac 的报表这个术语，不过我是把 Trac 的路线图（RoadMap）和查看任务单（Report，这个翻译有点操蛋）都看作报表的，下面我们分别来谈一谈。

路线图（RoadMap）

路线图中的重要概念就是里程碑（MileStone），里程碑可以指定一个逾期日，和一个完成日，分别表示预期完成时间和实际完成时间，通过这两个时间，可以看出是否存在延期或提前。每一个任务单（ticket）都有一个里程碑字段可供设定它所属的里程碑，乐观地说，如果能够把项目的需求、缺陷和改进都分析、细化到多个 ticket 中去，并设定好里程碑，那么整个项目的计划书就跃然纸上了。
在项目的推进中，不停地解决一些任务单，也不断地有新的任务单增加进来，也不停地有一些任务单被转移到其它里程碑中去，所以事实上里程碑里的任务单是不停地变化的。那如何才能快速、直观地了解里程碑的进度和健康程度呢？路线图报表就是用来解决这个问题的。

如上图，可以看到有 3 个里程碑，以及属于这些里程碑的任务单的状态。通过页面右上角的设置，还可以查看到已经完成的里程碑和做一些增进体验的设置，如隐藏没有截止日期的里程碑。这些里程碑的任务单状态分组是已经定制过的，所以可以看到已关闭、测试中和开发中三个状态的任务单数量，通过点击状态分组，可以进入此分组的任务单报表。定制状态分组通过编辑 trac.ini 来完成，首先确保 trac.ini 中有如下一节：

[milestone]
stats_provider = DefaultTicketGroupStatsProvider

然后加入一个名为 milestone-groups 的节，我所用的定义如下：

[milestone-groups]
closed = closed
closed.order = 1
closed.query_args = group=resolution
closed.overall_completion = true
closed.label = 已关闭
                            
resolved = resolved
resolved.order = 2
resolved.css_class = new
resolved.label = 测试中

active = *
active.order = 3
active.css_class = open
active.label = 开发中

其中 closed、resolved 和 active 都可以随意定义，它们表示分组名（groupname）。每一个分组名的值是一个以逗号（,）分格的列表，每一个元素都是一个状态名；也可以使用一次星号（*），它匹配了所有尚未指定的状态。每一个分组都有 order、query_args、overall_completion、label 和 css_class 五个属性供你设定，它们的意义如下：

1. order：决定了进度条中的显示次序，越小的数值越排在前面；
2. label：显示的名字；
3. css_class：css样式类名，可以通过增加 table.progress td.<class>这种形式的 selector 来定义；
4. query_args：前文说过点击进度条色块或 label 会打开一个任务单查询报表，这个参数的结果会附到那个报表的 url 之后，用来定制报表的，比如重载分组方式，可以使用 closed.query_args = group=resolution；
5. overall_completion：一个布尔值参数，标识在计算完成度时此组是否作为已完成状态的组。

查看任务单（Report）

内建报表

Trac 内建了 8 个基础报表，基本满足了一般项目的需要。不过商业项目毕竟不比开源项目，老板或项目经理往往想要更方便地方式来了解项目或里程碑的进展情况，这时候就需要定制报表。不过在此之前，我们先来了解一下内建的 8 个报表的功能先：

1. 活跃的任务单（active tickets）：非 closed 状态的任务单
2. 活跃的任务单按版本划分（active tickets by version）：分组方式为版本
3. 活跃的任务单按里程碑划分（active tickets by milestone）：分组方式为里程碑
4. 已接受的活跃任务单按属主划分（accepted, active tickets by owner）：accepted 状态的任务单，分组方式为属主
5. 全描述的已接受的活跃任务单按属主划分（accepted, active tickets by owner(full description)）：accepted 状态的任务单，分组方式为属主，显式完整的描述字段
6. 所有任务单（含已关闭的）按里程碑划分（all tickets by milestone (including closed)）：分组方式为里程碑的所有任务单（包括已关闭的）
7. 我的任务单（my tickets）：属主为我的任务单
8. 活跃的任务单，我的优先（active tickets, mine first）：所有任务单，但属主为我的排在前面。

为了方便查看我们的业务进展情况，我在此外还定制了 5 个报表，如下：

1. 最近变更的活跃任务单：获得最近的项目动向
2. 活跃用户单（按属主划分）：获得对组员工作压力得信息
3. 我发起的任务单：获得我发起的任务单现在的情况
4. 已解决的任务单：了解进入 resolved 状态但还没有通过 QA 人员检测的任务单
5. 已关闭任务单：获得已关闭任务单的情况，如了解它们的解决方案

新建的报表默认排在基础报表之后，为获得更好体验，你可以改变这些报表在数据库里的 ID 来重新排序，比如：

update report set id=5 where id=3;

执行以后就可以把原来排得较后的报表排到前面（不过 ID 是 PRIMARY KEY，所以需要注意它的唯一性）。

定制查询

Trac 的报表定制性很强，而且提供了图形界面的定制查询和基于 SQL Query 语句的新建报表，在这里我们先来谈一下较基础的定制查询，然后再深入到 SQL Query 语句及其注意事项。
点击报表（report）页面上部左右侧的定制查询连接就可以进入定制查询页面，一般地，已经在过滤器中加了属主和状态两个字段，并且下方也显示了当前的过滤结果，如下图：

过滤器字样下方的减号（-）按钮可以用来删除这个过滤器，每一个过滤字段都可以通过选择或填写来方便地设定过滤条件。在过滤器下面的“和”及“或”两个下拉框可以用来添加新的过滤字段，如类型、报告人等。
列字样的多选框用来选择需要在报表中显示的列，还有比较关键的是“结果分组”参数，可以按不同的 ticket 字段来分组，一般选择属主或状态。
选好参数以后，可以点击“更新结果”按钮查看效果，如果觉得满意，那么可以点击页面下方的“保存查询”把这个报表添加到报表页面了。

新建报表

定制查询虽然方便，但失去了一些灵活性，Trac Reports 能够让用户使用标准 SQL SELECT 语句进行报表定制。点击报表页面下方的“新建报表”按钮，可以进入 SQL 或 TracQuery 的编辑页面，定义好标题和它的描述，然后把 SQL 语句填入查询框，再保存报表即可。如“按优先级和时间排序的所有活跃任务单”报表的查询如下：

SELECT id AS ticket, status, severity, priority, owner,
       time AS created, summary FROM ticket
  WHERE status IN ('new', 'assigned', 'reopened')
  ORDER BY priority, time

使用这种复杂的方式，是为了获得更丰富的能力，比如在查询中使用变量。这个规则解决，以$开头的单词将被看作变量，如：

SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY

这个 $PRIORITY 就是变量，它的值由报表页面的 URL 传进来：

http://trac.edgewall.org/reports/14?PRIORITY=high

除了定量，还有一些默认的特殊变量（或称为常量），现在只有一个，$USER，使用这些特殊变量时需要改变 URL，Trac 自动地传递它的值，如查询属主为自己的任务单：

SELECT id AS ticket,summary FROM ticket WHERE owner=$USER

除此之外，Trac 还有自己的黑魔法——对一些字段自动格式化，主要有：

• ticket：修饰为带 ticket url 超链接
• created, modified, date, time：把字段格式化为日期和（或）时间
• description：使用 wiki 引擎处理

还有 ID 和 realm 字段，不过这两个字段得不多，就不介绍了。除了字段自动格式化，还可以定制列格式、改变报表行的布局等。

wiki中的报表

有时候我们需要在 wiki 页面中引用一些报表，这时候可以使用 TracQuery（它也可以替代 SQL 用在新建报表中）。它是 Trac 用来显示符合特定需要的任务单的。比如你可以在 wiki 中写入如下语句：

[query:status=new|assigned|reopened&version=1.0 对应1.0版的活跃任务单]

那么 wiki 引擎将把它渲染为一个指向 http://www.example.com/trac/query?status=new&status=assigned&status=reopened&version=1.0&order=priority 的超链接（锚文本是对应1.0版的活跃任务单），可以看到这个 URL 的参数正是 Query 语句的值。
Trac 强大的 wiki 引擎还可以使用 [[TicketQuery]] 宏把整个报表嵌入到 wiki 中，如：

[[TicketQuery(max=3,status=closed,order=id,desc=1,format=table,col=resolution|summary|owner|reporter,rows=description)]]

以上宏表示显示按 ID 倒序排前 3 的已关闭的任务单，每条任务单显示处理结果（resolution）、概述（summary）、属主（owner）和报告人（report），然后再另起一行显示任务单的描述（description）。

to be continued...