LOGILESS TECH BLOG vol.1 ~年間2000万件以上のEC出荷を支えるシステムをRDRA2.0のUC複合図にリバースエンジニアリングした話~
はじめに
はじめまして。
ロジレスでエンジニアをしている冨田(@seikoudoku2000) です。
週末に映画「ラストマイル」を観て、物流の恩恵を受ける一消費者としても、物流システムの一端に携わる者としても色々考えさせられると共に、LOGILESSというシステムの目指す所について思いを馳せる機会が増えた今日この頃です。
さて、会社のnoteに技術ブログ的なものも書いていってみようムーブが巻き起こり、その先陣を切らせていただくこととなりました。
今回は、直近の自分のタスクとして、(ほぼ何もドキュメントのない) LOGILESSのシステムをリバースエンジニアリングしながら、仕様を明確にするという課題に対して、RDRA2.0、その中でもUC(ユースケース)複合図を採用して仕様の書き起こしを行ったので、その事について、あれこれ書いてみたいと思います。
私自身、ここまで何もない状態から、しっかりと時間を取って一定量のドキュメントを整備した、というのが初めての経験で、色々と学びがありました。
動くシステムはあるけど何のドキュメントもなくて途方に暮れている方、システム仕様のドキュメントについてあれこれと試行錯誤している方 等々、システム構成のドキュメントについて思いを馳せている方々の、何らか参考になる情報となったら嬉しいです。
なお、この記事の中ではRDRA2.0自体についての説明は行いませんので、ネット上の各種情報を参照いただければと思います。
公式サイト
RDRA2.0の魅力を、簡潔に、でも最も上手に伝えてくれていると感じたスライド。めちゃくちゃ参考になりました。
tl;dr
数人のエンジニアで閉じて作っていたサービスがPMFして、これからアクセル踏んでこうっていうタイミングのスタートアップは、必ず、システム構成についてのドキュメントどうしよう問題に行き当たる (n=1の個人の数社での体験)
その最初の一歩として、RDRA2.0のUC複合図は候補の一つとしておすすめ
汎用性が高い
新入社員のオンボード等、知識０の人に対してのシステムの説明で使える
ある程度システム理解がある状態の人でも、ここの仕様どうなってたっけ？とか、初見の機能の概要の確認に丁度いい (細かい挙動はソースコードを辿る必要があるが、エントリーポイントや更新対象のエンティティがパッと分かる)
不具合調査やシステム改善検討等で、有識者同士で同じ図を見ながらディスカッションすることができる
作成した図を中心に社内のニーズに合わせてドキュメントを育てていける。
左側(抽象側)に図を伸ばすことで明文化されていなかったユースケースやシステム要求をまとめることができる
右側(詳細側)に図を伸ばすことでより詳細なシステム仕様をまとめることができる
タスク開始時点の状態
私が入社したのは2023/10で、当時４人目の正社員エンジニア、かつ、先輩エンジニア３人も直近半年以内での入社という状態でした。
一方で、LOGILESSのシステムを使っての年間出荷件数は2,000万件を超えており、ご利用いただいているお客様数と、エンジニアの数が釣り合っていない状態が長らく続いていました。
加えて、LOGILESSというシステムは、OMS・WMS一体型であることが特徴の一つであり、カバーしている業務範囲は広範囲で、管理しているデータも多岐に渡っている、という特徴もあります。
その状況下で、システムのドキュメントがどの程度整備されていたかについては、皆様のご想像の通りなので、詳細は割愛させていただきますw
ちなみに、この辺りの歴史的経緯については以下にまとまっていますので、是非こちらもご覧いただけたら嬉しいです！
1年前はLOGILESSというプロダクトを、私と業務委託のエンジニア2人と協力会社の方々にも手伝っていただき開発をしている状態でした。（実質正社員のエンジニアはゼロでした）当時はプロダクト開発の属人性があまりにも高くて、尚且つそれがドキュメント化もされていない状況だったので、プロダクトや業界に対する解像度があまりなくてもできる開発しか周りに任せることができずかなり限定的になってしまってました
なお、お客様数とエンジニア数のアンバランスは現在も継続中で、エンジニアを始め、各ポジション超絶絶賛ウルトラ大募集中なので、少しでも興味持たれた方はカジュアル面談を是非！（最下部にリンクを貼っています）
OKR設定
徐々にエンジニアの数も増えてきて、目の前のボールを打ち返す事以外の余力が出来てきた中で、最初にフォーカスしようとなったのが、LOGILESSのコアである在庫周りのデータ管理の仕様の明確化でした。
一定工数かけた取り組みとなるので、会社の目標設定で使われてるOKRのフォーマットに乗っける形で進めました。
部としてのOKR
部のOKRのObjectiveとしては、「LOGILESSのコア機能である在庫ドメインをハックして、チームで在庫の課題を改善できるようになっている」というものが掲げられました。
先述の通り、広範囲の業務を管理しているLOGILESSのシステムですが、その中でも、OMSとWMSを横断しての在庫管理は複雑で全容を掴むのが大変、かつ、不具合があった場合の影響度が深刻な部分で、数人しかいないチームなのに、既にCTOの田中さん以外にとってはアンタッチャブルな部分となりつつありました。
※ お客様向けのご案内のためのヘルプページは当時から一定充実していたのですが、社内エンジニアもこのヘルプページを読みつつ、ソースコードを解読しつつ、CTOの田中さんを隙間時間で捕まえて、疑問点を解読していく世界線…🌎
これから会社として組織をスケールさせていく、かつ、LOGILESSというシステムを安定的に進化させていくにあたって、この状況は早々に大きなボトルネックとなってしまう事は明白であったため、このObjectiveを掲げて、今回の取り組みが始まりました。
個人OKRに分解
上段のObjectiveとして、「LOGILESSのコア機能である在庫ドメインをハックして、チームで在庫の課題を改善できるようになっている」が設定されましたが、このままだとフワッとしすぎてて何をして良いか見えてこないので、
個人Objectiveとしてはもう一段分解して、以下の定義を行いました。
既存の在庫操作の仕様が明確に定義されており、全エンジニアが理解可能な状態になっている
上記で定義された仕様通りにシステムが100%動作している
そして、それぞれのObjectのKey Resultとして、以下を掲げました。
新しく入社したエンジニアが前知識無しで仕様を把握できるレベルのドキュメントを、在庫操作に関する代表的な18個のユースケースに対して作成する。フォーマットはRDRA2.0のUC複合図を想定。
JIRAに登録されているxx件の在操操作に関連するバグを全て解消する (登録されていた個数は秘密ですw)
ここでようやく、RDRA2.0という単語が出てきました。ちなみに、ユースケースも整備されたものはなかったので、ヘルプページの目次やそれまでの経験を元にエイやで仮置きし、途中で何度か追加されて、現時点ではこの数値になりました。
そもそも、システムのドキュメントが未整備の場合、自分達のシステムのユースケースのマスタも存在しない事が多いと考えられ、そこは既存の操作マニュアルやE2Eのシナリオテスト、プラス有識者へのヒヤリングを通して、何らか仮置きするという作業は必要になるかと思います。
※ 今回の記事では触れませんが、様々な要望に応える形で、スピード重視で様々な機能拡張を続けた事によるrace conditionに伴うバグが複数存在していたため、仕様を明確にした上で、それの通りに動く、という点もゴールに含めました。こっちの取り組みも様々な学びがあったので、機会があったら別記事で紹介したいと思います。
アウトプット例
前振りが長くなってしまいましたが、アウトプットとしては、以下のキャプチャのような図を選定したユースケース単位で、全１８個作成しました。
例えば、下の図は、
LOGILESSがカート・モールから未連携の新しい受注情報を取得してきて
受注に対して在庫引当が行われ
引当完了後の販売可能在庫数のサマリ更新が行われ
更新された販売可能在庫数をカート・モールに連携する
(複数カート・モールと連携している場合、他のカート・モールに在庫数連携する必要がある)
という、LOGILESSの１つの基本フローが、どのような流れで、どんな条件でどんなデータ更新しながら進んでいくかを図示したものになります。
※ システムの中身が詳らかになりすぎてしまうので、低解像度な画像キャプチャであることはご容赦ください🙏
アレンジを加えた所
フォーマットを選択した以上は、よほどの理由がない限り、その定義に従って何もカスタマイズせずに使っていくのがベターと考えますが、以下の２点、ちょっとしたアレンジを加えました。
”残管理”の概念の取り込み
この取り組みの前に読んでいた、「データモデリングでドメインを駆動する」という書籍で紹介されていた、”残管理”という概念は、今までボヤッと思っていたことを明確に言語化してくれた感じで目から鱗感があり、何らか処理を作ったり調査したりする時に意識するようになったのですが、
今回作成しているのはユースケース複合図ということで、各ユースケースが消化する、又はそのユースケースによって新たに発生する”残”に関する情報を記載すると良いのでは？という事で赤字で明記するようにしました。
※ ”残管理”について説明は割愛します、というか、書籍読む以外の説明方法が思いつかないので、ご興味持たれた方は是非、書籍を読んでみてください！
先のキャプチャから一部抜粋して、
カート・モールの受注を取り込むバッチでは、対象の”残”はロジレスに未取込のカート・モール上の受注である
バッチの実行結果として、在庫引当が必要な受注明細が新たな”残”として作成される
在庫引当workerが、在庫引当を行うことによって、上記のフローで作成された在庫引当が必要な受注明細という”残”を消化する
という流れを表現した図はこんな感じになっています。
エンティティではなく、実テーブル名を記載
上の図にある、sales_order, sales_order_line というのは実際のテーブル名です。
RDRAの定義では、ここには物理設計としての具体のテーブルではなく、論理設計としてのエンティティを書くことになっているのですが、ロジレスは、エンティティとテーブルが1:1になっている事がほとんどなのと、論理設計と物理設計が分かれている場合でも、仕様検討時の設計資料等もない中で抽象化してしまうと、逆に分かりづらくなるだけであろう、、という想定から、テーブル名を剥き出しで表出させることにしました。
今後、論理設計と物理設計が乖離してきた時には再考の余地があるかもしれませんが、現状の自分達にはこっちの方が合っていると感じるので、当面はこのままで進める想定です。
RDRA2.0の選定理由
この取り組みを始めるにあたって、最初に考えた事は、何らかの定義されたフォーマットに沿った形でドキュメントを残していきたいという事でした。
フォーマットの定められたドキュメント作成、型に縛られる感じで昔はあまり好きではなかったのですが、以前の職場でADRというフォーマットに出会って、それを一定期間チームで書いていて、書くのも読むのもめちゃくちゃ楽やん、、！ってなったのがきっかけで、フォーマット大好きマンになりました。
ソースコードは０から書く時間よりも、読んだりメンテする時間の方が圧倒的に多い、みたいな話はよくあるかと思いますが、ドキュメントも全く同じで、人の書いたドキュメントを読む時に、その人がどういう思考でどういう形式でまとめたのか？、文章の流れ良いな〜/悪いな〜みたいな、内容とは関係ない事を考えずに、次にどんな事が書かれているかを予想しながら内容だけに集中して読めるというのがめちゃくちゃ楽だし、レビューや議論する時も、ポイントが明確になりやすく、その魅力にハマったのでした。
※ ADRについてはこちらの記事にまとまっていますので、参考まで。今回の記事とは関係ないけど、ドキュメントフォーマットの文章で「思い」という単語が出てくるこの文章が結構好きで定期的に読み返してます & この文章きっかけで自分のドキュメントに対する熱量も少し変わった気がします。
と、謎のADR愛が溢れて、ちょっと横道に逸れてしまいましたが、今回のタスクである仕様の明確化においても、同じように何らかのフォーマットに沿った形でドキュメントをまとめていきたいと思いました。
本当は、他のフォーマットとの比較表みたいなのを作ることを考えたのですが、自分が前職でもRDRA2.0をベースにドキュメントを書いてた事があった、また、他に代替となりそうな明確なフォーマットを発見する事ができなかったので、まずはRDRA2.0、その中でも今回の目的を考えると、UC複合図の粒度が丁度良いであろう、という事で試験的に始めてみて、しっくりこなかったら別の形を考える、という形でスタートしました。
作成したドキュメントが１つ２つ形になったくらいの早いタイミングで、チーム内でレビューしてもらって、特に問題なかった、というか、とてもしっくり来てチーム内での評判も上々だったので、そのまま利用を進めた、という流れになります。
フォーマットを適用することのデメリットを１つ挙げるとすると、
フォーマットが定まっている文章を書く = 最初にどういうフォーマットであるかを理解するためのキャッチアップのための時間が必要である、、、という点があるかと思います。
この点に関して、読む側はフォーマットの存在を意識せずとも読むことはできますし、
書く側に関しては先述の通り、書いた時間以上の多くの人に読まれたり、更新したりする時間があるわけで、作成者の考えるオレ流最強フォーマットで書かれた文章を、他の多くの人が汲取力を使いながら読んだり、更新したりする負荷、更にそのフォーマットがいけてなくて誰も読まない/更新もされないドキュメントになってしまう(途中でレビューを挟んだとしても、文章フォーマット的な所は抽象度が高くて適切な指摘を入れづらい)等のリスクを鑑みると、
最初に多少コストが掛かろうとも、既存のフォーマットに乗っかる、というのは妥当な選択肢であると考えます。
効果
今の所、以下のような効果があると感じています。
オンボーディングの負荷の軽減
する側、される側共に
有識者の頭の中にしかない構成図だったので、伝える側も伝えられる側も負荷が高かったし、担当の理解度によって説明内容にバラツキが生まれやすい状態だったが、共通の図を見ながら会話できるようになったことで、諸々の問題が改善
有識者同士の議論の精度が高まる
それぞれの脳内にある構成図を元にした会話だと、言葉の空中戦になりやすかったが、同じ図を眺めて議論することが可能になった事で、会話の精度が向上
テクニカルサポートでのデータ不整合発生時の修正や、原因追及のバグ調査の時の問題発生箇所のあたりがつけやすくなる
複数人で一緒にトレースして行く時も、どういう思考で、どこを調査しているのかの認識を揃えやすい。
ドキュメントに対しての投資は、適切なものであればレバレッジはどんどん大きくなるはずなので、今後の更なる活用に期待！
RDRA2.0を採用してみての感想
先述の通り、一定の効果が出ていることは観測しているものの、今回作成したドキュメントを多くの人に読んでもらう、システムのアップデートに合わせて更新していく、、というようなフェーズはもうちょい先なので、ちゃんとした評価は難しいですが、
個人的にはとても良い選択だったと思いますし、時が戻って今回のタスクのスタート地点に戻ったり、もしくは今後、職場が変わって似たようなタスクを進める事があったら、同じ選択をすると思います。
また、UC複合図を作って終わりではなく、それをベースに、ニーズの高い所からドキュメントを育てていく流れができたのは、タスクの開始当初は想定できていなかったプラスポイントでした。
UC複合図を眺めながら、この機能の存在自体は知ってるけど、そもそも、どういうお客さんのどういう課題解決のためにあるんでしたっけ？という会話が発生したら、CTOの田中さんに当時の顧客課題についてヒヤリングしながら、一つ抽象度の高いユースケース図や業務フロー図をまとめたり、
在庫データのステータス遷移はかなり複雑なので、そこだけは別にまとめたいですねという会話が発生したら、一つ具象度の高い在庫データの状態遷移図を作成したりと、
UC複合図を元に、皆んなが共通認識持てていない部分が詳らかになると共に、優先度が高いと感じた点に関しては、クイックに違うレイヤのドキュメントを継ぎ足せるというのは、とても良い特徴だと感じています。
RDRA2.0の想定されている使い方としては、要件定義から始めて、段々と詳細な図を作成していく、、という流れかと思いますが、既に存在するシステムに対して、ニーズの高いレイヤからスモールスタートし、必要に応じて育てていく、という使い方も出来るのは、RDRA2.0がレイヤ間の定義を明確にしている事からこそできる芸当であると思います。
多くのスタートアップでは、既にシステムは動いているがドキュメントは何もない！という状況だと思うので、こんな感じで特定のレイヤに絞って小さく始めて、出来上がったものをベースに会話をしながら、必要な部分のドキュメントを育てていく事ができる柔軟性は、中々に魅力的なのでは？と考えます。
ロジレスのドキュメントも、半年後、一年後とかに、改めて評価したり、現時点からの変遷をまとめると、更なる学びがありそうだし、
このドキュメントを作っている中で、RDRA2.0のドキュメントをこういう形で作れたり、使えたりすると色んな事を良くできそうだな〜というアイデアも浮かんだりがあったので、時期をみて改めてまとめてみたいと思いました。
まとめ
私自身のキャリアとして、所謂スタートアップと呼ばれる会社に何社か在籍していましたが、全ての会社でドキュメントが足りない、何か作らないと、、、みたいな会話がなされていたけど、中々まとまった時間の確保は難しく、また、自分の中でも明確な打ち手を想定できていない状態でした。
ロジレスはその中でも深刻度が群を抜いていてw、今回、一定まとまった時間を使った取り組む機会があり、まだ道半ばではありますが、色々と学びがあったので、長々とあれこれ書いてみました。
この記事に辿り着いた皆様に少しでもお役に立てたら嬉しいです！
ロジレスでは、ドキュメントを揃えていきたいエンジニアも、ドキュメントなんて気にせずひたすら機能を作っていきたいエンジニアも、映画「ラストマイル」を観て物流に関係するシステムに興味を持ったエンジニアも、超絶絶賛ウルトラ大募集中です！
エンジニア採用関連のYouTube動画や記事です。
求人に関するお問い合わせはこちらから↓