add docs for event size

2025-12-24 10:51:23 +00:00 · 2025-05-10 11:09:18 +08:00 · 2025-05-10 11:09:18 +08:00 · 30c2f6f61b
commit 30c2f6f61b
parent c0a93b8adc
2 changed files with 102 additions and 3 deletions
--- a/repair/assets/issue-label.png
+++ b/repair/assets/issue-label.png
--- a/repair/weekend.md
+++ b/repair/weekend.md
@ -102,17 +102,17 @@ sequenceDiagram

 ```

-目前，新的维修事件会同步到 [Github Issue](https://github.com/nbtca/repair-tickets/issues) 中。成员可以在Github Issue中处理维修事件
+目前，新的维修事件会同步到 [Github Issue](https://github.com/nbtca/repair-tickets/issues) 中。成员可以在Github Issue中处理维修事件。

 ### 前提条件

-在开始之前，你需要先关联你的Github账户。你可以前往 [MyId](https://myid.app.nbtca.space/account/connections) 关联你的Github账户
+在开始之前，你需要先关联你的Github账户。你可以前往 [MyId](https://myid.app.nbtca.space/account/connections) 关联你的Github账户。

 ![link-github](./assets/link-github.png)

 ### 处理事件

-在Github Issue中，你可以通过在回复中包含以下命令来处理事件：
+在Github Issue中，可以通过在回复中包含以下命令来处理事件：

 - `@nbtca-bot accept` will accept this ticket
 - `@nbtca-bot drop` will drop your previous accept
@ -121,3 +121,102 @@ sequenceDiagram
 - `@nbtca-bot close` will close this ticket as completed

 ![issue-reply](./assets/issue-reply-example.png)
+
+### 记录事件工作量
+
+通过在Github Issue中添加标签来记录工时。
+![issue-label](./assets/issue-label.png)
+
+| 标签名    | 对应时长 | 示例维修任务（仅供参考）                        | 场景说明                                         |
+| --------- | -------- | ----------------------------------------------- | ------------------------------------------------ |
+| `size:xs` | 0.5 小时 | 重启系统、插拔键鼠、调整BIOS启动项              | 无需工具，仅简单排查或软件层级操作               |
+| `size:s`  | 1 小时   | 更换键盘、电源适配器、内存条                    | 简单拆装部件，操作快，风险低                     |
+| `size:m`  | 2 小时   | 拆机清灰、重新安装操作系统、驱动修复            | 需基本工具、一定技术判断，时间较长               |
+| `size:l`  | 4 小时   | 主板故障检测与更换、电源模块更换                | 较复杂的拆装和测试流程，需熟练技能、多人协作可能 |
+| `size:xl` | 8 小时   | 批量电脑检修（5 台以上）、全室网卡/主板统一更换 | 工作量极大，涉及多个设备，需团队作业和详细记录   |
+
+
+
+### 志愿者时长统计
+
+```typescript
+type Record = {
+  studentId: string;
+  eventId: string;
+  tag: string; // e.g., "size:s"
+};
+
+const BASE_TIME = 2; // hours
+const MAX_TIME = 8;  // hours
+
+// Mapping from tag to time in hours
+const tagTimeMap: Record<string, number> = {
+  'size:s': 1,
+  'size:m': 2,
+  'size:l': 4,
+  'size:xl': 8,
+};
+
+// Compute total time for a given student and event
+function calculateTime(records: Record[], studentId: string): number {
+  const relevantRecords = records.filter(
+    (r) => r.studentId === studentId
+  );
+
+  let totalTime = BASE_TIME;
+
+  for (const record of relevantRecords) {
+    const time = tagTimeMap[record.tag] || 0;
+    totalTime += time;
+  }
+
+  return Math.min(MAX_TIME, totalTime);
+}
+
+
+const records: Record[] = [
+  { studentId: '2333333333', eventId: '123456', tag: 'size:s' },
+  { studentId: '2333333333', eventId: '123456', tag: 'size:m' },
+];
+const time = calculateTime(records, '2333333333');
+console.log('Calculated time:', time); // Output: 5
+
+```
+
+| Key            | Value     | Description              |
+| -------------- | --------- | ------------------------ |
+| 基础时长       | 2         | 每个志愿者的基础时长     |
+| 最高时长       | 8         | 每个志愿者的最高申报时长 |
+| 上一次统计日期 | 2025.4.21 | 上一次统计时长的日期     |
+
+统计时长时，获取自从上一次统计日期以来的维修记录，统计完成后将上一次统计日期更新为当前日期。
+时长计算参考以上代码中的 `calculateTime` 函数。
+
+#### 例子
+
+| 学号       | 事件ID | size   |
+| ---------- | ------ | ------ |
+| 2333333333 | 123456 | size:s |
+| 2333333333 | 123456 | size:m |
+
+计算后时长为 min(8， 2 + 1 + 2) = 5。
+
+#### 使用Saturday API导出时长为excel
+
+| 字段名       | 描述                 |
+| ------------ | -------------------- |
+| start_time   | 开始时间             |
+| end_time     | 结束时间             |
+| bearer_token | token，需要admin权限 |
+
+```http
+GET https://repair.nbtca.space/api/events/xlsx?start_time={{start_time}}&end_time={{end_time}}
+Authorization: {{bearer_token}}
+```
+
+##### 示例
+```bash
+curl -X GET "http://repair.nbtca.space/api/events/xlsx?start_time=2025-01-01&end_time=2025-05-31" \
+  -H "Authorization:  {{bearer_token}}" \
+  -OJ
+```