使用 Slack 应用开始的工作日志（第1回）- 基本操作 -

日本語|English|中国语
| 6 min read
Author: masao-sato masao-satoの画像
#businessDiary #仕様駆動
Information

为了覆盖更广泛的受众，这篇文章已从日语翻译而来。
您可以在这里找到原始版本。

1. 前言

#

前几天，我写了一篇关于工作日志的文章，链接如下。

/blogs/2026/01/06/businessdiary/

不过，

  • 这是一个技术博客，仅仅发表文章似乎不够。
  • 既然我是技术人员，就想趁此机会做点什么。

因此，我以工作日志为题材制作了一个应用程序。
（不过这只是一个学习用的示例应用）

另外，最近在公司内部培训中学习了需求定义、设计、文档撰写等内容，所以也顺便把这些练习一番。

因此，本文以工作日志应用为例，主要介绍如何整理需求定义到设计的过程。希望能面向与我一样制作应用的工程师们，共享制作过程，而非设计的优劣。至于应用的具体实现部分，本文将略去，另在后续文章中发布。

2. 开发应用

#
  • 首先，这次的目标是仅开发出创建工作日志应用所需的最基本功能。
  • 考虑到我在上一篇博客中提到过使用 Slack 创建工作日志，这次就尝试制作一个 Slack 应用（技术要素稍后整理）。
  • 开发按以下步骤进行：
    1. 需求定义
    2. 设计
    3. 制造与测试（在博客中略去具体细节）

2-1. 需求定义

#
  • 本文的重点内容，篇幅稍长，还请耐心阅读😓
  • 在需求定义阶段，将按照“期望→需求→要件→规范”的顺序进行编写。

2-1-1. 列出期望

#

首先，“期望”是指“希望系统（本例中为应用）实现的功能”。这里先将关于工作日志应用可能实现的内容随想随记地写出来。

Information
  • 希望自动创建工作日志。
    手写比较麻烦，希望由应用自动生成。
  • 希望自动报告工作日志。
    希望实现自动化报告，例如发布到 Slack 频道等。
  • 希望在规定时间创建和报告工作日志。
    希望根据定时等调度创建、报告工作日志。
  • 希望调整工作日志的格式。
    想创建工作日志模板，以便统一日志格式。
  • 希望随时注册任务。
    希望在工作过程中随时将要记录到日志的任务注册进来。
    （在创建日志时再想要记录的内容并不高效，所以想提前注册。）
  • 希望管理任务的状态。
    想能够了解任务的进展情况。
  • 希望保留已注册的任务。
    即使在应用停止、重启后，也能查阅之前注册的任务。
  • 希望保留已创建的工作日志。
    即使在应用停止、重启后，也能查阅之前创建的工作日志。
  • 希望能够对工作日志进行汇总。
    将已创建的多日工作日志汇总，作为周报、月报，或评估面谈资料。
  • 希望获得反馈。
    希望对所创建的工作日志内容获得反馈。
    （可能让 AI 等进行评审）

2-1-2. 列出需求

#

接下来，“需求”是指“在期望中被采纳实现的部分”。这次作为工作日志应用，仅选取必要的最基本期望作为需求。因此，需求如下。

Information
  1. 希望注册任务。
    使得能够注册在工作中进行的任务。
  2. 希望确认已注册的任务。
    能够查看已注册的任务。
  3. 希望设置任务状态。
    使得能够为已注册的任务设置状态。
    任务状态如下：
    • 未开始
    • 进行中
    • 完成
  4. 希望创建工作日志。
    从已注册的任务中创建工作日志。
    工作日志中包含“当天执行的任务列表”和“次日预定执行的任务列表”。
  5. 希望保存已注册的任务。
    确保已注册的任务不会丢失。
  6. 希望保存已创建的工作日志。
    确保已创建的工作日志不会丢失。

对于1-4项我觉得没问题。至于5、6项虽然有点不同，但暂且先这么定。注册和持久化大多数情况下是成对出现的，所以我觉得应该在某处合并为一项更好。

2-1-3. 期望中不包含在需求内的内容

#

在期望中列出的内容里，不作为需求采纳的部分也要一并明确说明。

Information
  • 工作日志的自动生成
    将工作日志生成作为应用功能，但生成流程的触发需手动进行。
  • 工作日志的自动报告
    报告需手动进行。
  • 工作日志的定时生成
    不是必需功能，故不在范围内。
  • 工作日志的模板
    本次将工作日志模板固定。
  • 工作日志的汇总
    不是必需功能，故不在范围内。
  • 工作日志的反馈
    不是必需功能，故不在范围内。

2-1-4. 编写要件

#

接着，基于上述需求来定义要件。要件是指“定义系统完成后要实现的内容”。

Information
  1. 用户必须能够通过应用界面注册任务。
  2. 用户必须能够在应用界面查看已注册任务列表。
  3. 用户必须能够通过应用界面，为已注册任务设置预定义的任务状态。
  4. 用户必须能够指示应用创建工作日志。
    应用必须基于已注册的任务生成工作日志，并将其内容展示给用户。
  5. 即使用户停止并重新启动应用，也必须能够查看停止前注册的任务。
  6. 即使用户停止并重新启动应用，也必须能够查看停止前创建的工作日志。

2-1-5. 编写规范

#

最后，尝试定义规范。规范是指“全面描述要件的文档”。

Information
  1. 任务的注册
  • 用户在界面上输入任务内容。
  • 应用将用户输入的任务内容与以下内容一并注册：
    • 任务ID
    • 注册日期
    • 任务状态
  • 任务ID应为能唯一标识任务的标识符。
  • 注册日期使用注册时的当前日期，格式为 yyyy/MM/dd。
  • 注册日期应基于用户执行任务注册时的日本标准时间（JST）。
  • 同时，将任务状态设置为“未开始”。
  • 任务内容为必填项，去除前后空白字符后若为空字符串则视为无效。
  • 如果任务内容未输入，应用应显示注册失败的消息并结束流程。
  • 任务内容允许的最大输入字符数为100字符，此时不区分全/半角，均按1字符计算。
  1. 任务列表的确认
  • 用户指示应用显示已注册任务的列表。
  • 应用在界面上显示已注册任务的列表。
  • 列表按注册顺序（任务ID）的升序排列。
  • 列表中显示任务内容、注册日期、任务状态。
  1. 任务状态的变更
  • 用户可指定目标任务并更改其任务状态。
  • 任务状态包括“未开始”、“进行中”、“完成”三种。
  • 如果用户尝试更新不存在的任务（任务ID），应用应显示设置失败的消息并结束流程。
  • 如果用户尝试设置为预定义状态外的值，应用应显示设置失败的消息并结束流程。
  • 应用使用用户输入的任务ID和任务状态更新指定任务的状态。
  • 状态之间不设转换限制，必须按用户指定状态进行设置。
  1. 工作日志的生成
  • 用户在界面上指示应用生成工作日志。
  • 应用接收指令后，从已注册任务中创建工作日志。
  • 工作日志由以下项目构成：
    • 生成日期
    • 当日执行任务列表
    • 次日预定执行任务列表
  • 生成日期显示为生成时的当前日期。
  • 生成日期格式为 yyyy年MM月dd日（WeekDay）
    ※WeekDay 表示星期，如月、火、水…等。
  • 生成日期基于日志创建时点的日本标准时间（JST）。
  • 当日执行任务列表包含满足以下所有条件的任务：
    • 当日内更新了任务状态。
    • 任务状态为“进行中”或“完成”。
  • 次日预定执行任务列表包含满足以下所有条件的任务：
    • 任务状态为“未开始”或“进行中”。
  1. 任务的保存
  • 用户注册任务时，应用应将任务持久化。
  • 用户查看任务列表时，应用应从持久化任务中生成列表。
  • 用户设置任务状态时，应用应更新持久化任务的状态。
  1. 工作日志的保存
  • 应用在生成工作日志时，应将其持久化。

2-2. 设计

#

2-2-1. 方式设计

描述应用整体的设计方针。由于是设计阶段，也会写明具体的技术要素。

Information
  • 应用将作为 Slack 应用来实现。
    • 应用需要 UI，但觉得制作桌面应用有些过于繁琐。
    • 在工作中使用 Slack，如果能在 Slack 中创建工作日志，
      创建→报告可在同一处完成，比较理想。
    • 使用 Bolt for JavaScript 框架。
  • 为了持久化数据，将使用数据库，选用 SQLite。
    • 由于本次是本地运行的示例，
      轻量的内存数据库已足够。
  • 在持久化层采用 O/R 映射工具 Drizzle ORM。
    • https://orm.drizzle.team/
    • 这是个人喜好。
  • 开发语言使用 TypeScript（JavaScript）。
    • 前述 Bolt 框架可使用 Python 和 JavaScript，
      但不擅长 Python，所以使用擅长的 JavaScript。
    • 不使用 Deno。
      Bolt for JavaScript 支持 Deno，个人也不排斥 Deno，
      但不确定 Deno 的普及度，因此本次先不采用。

2-2-2. 功能设计

将规范中的5和6（已注册任务与工作日志的保存/持久化）分别合并到1和4中。因此功能共计4项，以下分别说明。

Information
  1. 注册任务
    1. 输入任务内容
      1. 在应用私信（DM）中作为消息输入任务内容。
    2. 验证任务内容
      1. 如果任务内容未输入，则显示错误消息。错误消息以应用回复的形式展示。
      2. 如果任务内容超过100字符，则显示错误消息。错误消息以应用回复的形式展示。
    3. 注册任务内容
      1. 通过执行 Slack 应用命令启动任务内容的注册。
      2. 将任务内容保存到数据库。保存内容包括输入的任务内容、注册日期和初始任务状态（未开始）。
  2. 查看任务
    1. 显示任务列表
      1. 通过执行命令显示任务列表。任务列表的各项目包含任务内容、状态、设置按钮共4项。
      2. 如果没有已注册任务，则显示错误消息。错误消息以应用回复的形式展示。
  3. 设置任务状态
    1. 更新任务状态
      1. 在任务列表中点击设置按钮，将任务状态设置为所选值。
  4. 生成工作日志
    1. 生成工作日志
      工作日志为文本形式。应包含当日执行任务列表和次日执行任务列表。当日执行任务列表为任务状态为“进行中”或“完成”的任务。次日执行任务列表为任务状态为“未开始”或“进行中”的任务。如果不存在符合条件的任务，则在工作日志中包含文本“没有可用任务”，而不是列表。通过执行命令生成工作日志。生成的工作日志以应用回复的形式展示。
    2. 保存工作日志
      将生成的工作日志保存到数据库。保存内容包括工作日志ID、注册日期和工作日志内容三项。

2-3. 图

#

兼作设计练习，同时进行绘图。

2-3-1. 用例图

用例图

2-3-2. 领域模型

领域模型

2-3-4. 鲁棒性图

鲁棒性图
鲁棒性图
鲁棒性图
鲁棒性图

3. 关于已创建的应用

#

应用已完成，这里仅记录运行结果。
※至于应用本身，会在其他文章中进行说明。

3-1. 功能运行确认

#

3-1-1. 注册任务

首先，注册任务。
通过 /task_add 命令，将任务内容作为参数设置后发送。
任务注册执行
注册成功后会收到回复消息。
任务注册结果

3-1-2. 查看任务

接着，通过 /task_list 命令显示已注册任务。
列表显示命令无需参数。
任务列表显示执行

列表按注册顺序显示。
另外，为了能更新状态，将状态显示为下拉框，并配置了用于执行更新操作的按钮。
任务列表显示结果
另外，为了测试运行，已注册了3个任务。

3-1-3. 设置任务状态

接着尝试修改状态。
在3个任务中，将一个改为进行中，另一个改为完成。
任务更新结果
在应用上修改状态后点击更新按钮，状态即被更新，并收到回复消息。

3-1-4. 创建工作日志

最后尝试生成工作日志。
执行 /businessDiary_create 命令。
工作日志创建执行

命令受理后，先返回响应，然后显示生成的工作日志。
在当天任务列表中显示“进行中”或“完成”的任务。
在次日任务预定列表中显示“未开始”或“进行中”的任务。
工作日志创建结果

4. 总结

#

在本文中，以工作日志为题材，进行了应用程序的需求定义、设计与实现。整理的内容属于个人学习的一部分，希望能对同样在设计中苦恼并制作应用的朋友有所帮助。

实际上实践后的感想如下：

  • 由于属于业余项目，某些地方有省略之处，但撇开这些不谈，仍有很多不足之处，希望通过此类练习提高能力。
  • 此外，即使是这样一个示例级别的应用，真正进行需求定义与设计时，也感觉工作量相当可观。
  • 不过应用开发本身（就感受而言）似乎进展顺利，因此我认为这类需求定义、设计流程并非多余。
  • 以前使用过低代码工具进行开发，受制于“工具生成的产物（代码）= 设计文档”的思路，常常省略设计而直接实现。但像这次这样先设计再实现的流程感觉更高效，即使不是低代码，通过事先将设计文档化也更有助于理解规范，而不是在实现中反复试错。

关于工作日志应用，今后也计划兼顾技术学习进行功能扩展。另外，所采用的技术要素也计划在后续以文章形式发布。

豆蔵では共に高め合う仲間を募集しています！

recruit

具体的な採用情報はこちらからご覧いただけます。