需求分析規(guī)范-附加說明1：用例描述文檔編寫規(guī)范

長春一汽啟明信息技術有限公司版本歷史日期版本描述作者2006-07-01<1.0>初稿整理呂春秋

用例描述文檔編寫規(guī)范（精要）前言目的本用例描述文檔編寫精要對新一代ERP項目組幾年來用例設計經(jīng)驗進行總結，廣泛吸收各方長處，分析編寫過程中出現(xiàn)的弊端，整理出了這些編寫用例文檔需要掌握的要點，為指導今后需求設計、需求更改過程中文檔編寫起到規(guī)范的作用，不足，發(fā)現(xiàn)優(yōu)點。還要不斷地充實和完善。提高用例編寫水平，范圍本“用例描述文檔編寫精要”作為一個規(guī)范性的文件，適用于新一代ERP項目組需求分析與設計過程中的用例描述文檔的設計工作。本文檔說明采用說明與案例相結合的方式進行描述，便于理解。本文檔描述的內(nèi)容相對比較多，每次應用時都通篇閱讀比較費時。為了重點突出，文檔描述中帶“雙下浪線”的文字都是當前章節(jié)的要點內(nèi)容，便于概覽閱讀。為了問題說明重點突出，所有例子都是化簡之后的實例，不能認為例子與原用例的不一致就是用例錯誤或例子錯誤。新一代ERP項目的需求規(guī)范是在開發(fā)過程中不斷總結和完善的，因此，本“用例描述文檔編寫精要”同樣需要逐步完善的過程，如果發(fā)現(xiàn)文檔存在問題，發(fā)現(xiàn)需求設計工作存在問題，或者有好的建議，或者有不同見解，請及時與需求主管聯(lián)系，誠謝。

系統(tǒng)的效率基本要求對于用例描述文檔的書寫（需求設計），不同部分會有不同的要求，但是從整體上來講應該遵循以下幾項原則：要從開發(fā)者的角度完善文檔的可讀性及處理性能；要站在客戶的角度考慮程序的可操作性用例所用的表結構要和ROSE中的業(yè)務類圖保持一致，用例中使用的類屬性描述；需求設計基本上還是邏輯功能設計，應該是面向任何開發(fā)工具和開發(fā)平臺的。因此，在需求文檔中應該只描述出功能即可，而不應該絕對具體，以免限制設計人員針對具體開發(fā)工具的物理實現(xiàn)設計和程序人員的發(fā)揮；在用例描述文檔中對事件流、業(yè)務規(guī)則、公共業(yè)務規(guī)則、例外、擴充點、注釋等內(nèi)容的引用，要進行鏈接，便于閱讀。用例事件流的描述用例文檔中有三種事件流：基本事件流、子事件流、備選事件流，事件流編寫的基本要求如下：事件流描寫“執(zhí)行者”和“系統(tǒng)”的交互過程，一般不應該夾雜著業(yè)務規(guī)則和條件判斷；子事件流和備選事件流的確定：有的事件流在一個用例文檔中既作為子事件流出現(xiàn)，又作為備選事件流出現(xiàn)，此時沒有必要把這一個事件流分別作為子事件流和備選事件流寫成兩個，而是以流程的執(zhí)行或書寫的順序，在第一次使用這個事件流時它是子事件流，就將它放在子事件流章節(jié)中作為子事件流來書寫；在第一次使用這個事件流時它是備選事件流，就將它放在備選事件流章節(jié)中作為備選事件流來書寫；界面流轉在事件流中一定要說清楚；例如：系統(tǒng)顯示“選擇查詢戰(zhàn)略”界面（CCA120-09）。執(zhí)行者選擇“按信息結構查詢”。系統(tǒng)根據(jù)條件{“應用環(huán)境”=當前應用環(huán)境.并且.“物流應用程序標志”＝真}在“物流信息系統(tǒng)”類中查找符合條件的信息，顯示在界面內(nèi)（CCA120-10“應用程序選擇”界面）。正確的描述方法應該是：系統(tǒng)顯示“選擇查詢戰(zhàn)略”界面（CCA120-09）。執(zhí)行者選擇“按信息結構查詢”。系統(tǒng)進入“應用程序選擇”（CCA120-10）界面，并根據(jù)條件{“應用環(huán)境”=當前應用環(huán)境.并且.“物流應用程序標志”＝真}在“物流信息系統(tǒng)”類中查找符合條件的信息，顯示在界面內(nèi)。流程中描寫的操作應該是一個抽象的操作功能，而不應該寫成“按XX按鈕”或“雙擊XX項”等具體的操作方法。例如，操作者要選擇“執(zhí)行”操作，可以寫成：執(zhí)行者選擇“執(zhí)行”。系統(tǒng)按照XX業(yè)務規(guī)則處理發(fā)貨。而不寫成：執(zhí)行者按“執(zhí)行”按鈕，或執(zhí)行者雙擊“執(zhí)行”按鈕；基本事件流的要求任何用例都必須有基本事件流，基本事件流是一個用例的入口點，是一個用例的主要流程。編寫基本事件流應該注意以下要點：基本事件流描寫的是一個用例的主要流程，從這個主要流程能夠看出用例執(zhí)行的全貌；而非主要流程或細節(jié)流程，可以放在子事件流或備選事件流中進行描寫基本事件流是流程中正確處理的流程，例外流程應該作為備選事件流來描述；基本事件流一定要清晰、完整，要有始有終，具有一個出口結束點；基本事件流描寫的步驟不宜太多（過程比較復雜的用例的基本事件流一般也要控制在20個步驟之內(nèi)）；子事件流的要求子事件流是另一個前序事件流中一個處理步驟的細節(jié)交互處理過程。編寫子事件流應該注意以下要點：子事件流要放在用例文檔的“子事件流”章節(jié)中，子事件流的編號為“S-nn”（nn是從01開始的連續(xù)的兩位數(shù)字編號）；子事件流的定義除了要有子事件流編號之外，還應該給子事件流一個中文名稱，便于閱讀。例如：5.2子事件流S-01：創(chuàng)建一個成本要素（1）系統(tǒng)按照業(yè)務規(guī)則“HYPERLINKBR-002：初始化基本數(shù)據(jù)界面規(guī)則”顯示“創(chuàng)建成本要素-基本數(shù)據(jù)”界面（HYPERLINKN-1）（2）執(zhí)行者輸入或選擇編輯項……子事件流要完整（有始有終），子事件流結束后，正常應該返回到引用子事件流之處，但是也允許將控制轉移到其它事件流；引用子事件流之處可以用“按照‘子事件流編號’進行XXX操作”等描述將控制轉入子事件流。例如：……（4）執(zhí)行者選擇“確定”。（5）系統(tǒng)進入“創(chuàng)建次級成本要素-基本數(shù)據(jù)”界面（HYPERLINKS-1：創(chuàng)建一個次級成本要素），創(chuàng)建一個次級成本要素。……備選事件流的要求備選事件流是前序事件流中某個備選操作項的詳細過程描述，是前序事件流的一個處理分支。編寫子事件流應該注意以下要點：備選事件流要放在用例文檔的“備選事件流”章節(jié)中，編號為“A-nn”（nn是從01開始的連續(xù)的兩位數(shù)字編號）；備選事件流結束正常應該返回到引用備選事件流之處，但是也允許將控制轉移到其它事件流；引用備選事件流之處應該用“或某操作‘備選事件流編號’”的方式將控制引入備選事件流；在引用備選事件流之處允許有多個備選操作項，例如：……（3）執(zhí)行者選擇“確定”（或“顯示”HYPERLINKA-01、或“創(chuàng)建”A-02、或“退出”）?！瓕τ凇皬椭啤薄ⅰ皠h除”、“取消”、“退出”等備選操作，在“ERP-REQ-一般說明.doc”文檔中有標準的操作結果描述，如果當前用例對這些操作的記過與“ERP-REQ-一般說明.doc”文檔標準操作相一致，則在備選操作引用之處指出操作種類，而不同再重復描寫備選操作流程；例如，上例的“或‘退出’”備選項；有條件的備選流可以借助于其它方式進行描述，例如可以在界面原型中說明。事件流中的序號標號事件流中，對描述執(zhí)行者和系統(tǒng)之間操作過程的步驟序號統(tǒng)一規(guī)范，使用“（1）”、“（2）”標號形式。事件流中“確認”與“執(zhí)行”操作描述的建議在事件流描述中，經(jīng)常會遇到“確認”與“執(zhí)行”之間備選操作的時候。在新一代ERP項目早期的用例描述中習慣于以下的方式：系統(tǒng)顯示“創(chuàng)建分配因子主數(shù)據(jù)界面”（CCA120-02）；執(zhí)行者維護“名稱”、“……”屬性值并確認；系統(tǒng)根據(jù)業(yè)務規(guī)則（HYPERLINKBR-002）檢查執(zhí)行者錄入；執(zhí)行者執(zhí)行“保存”操作；系統(tǒng)根據(jù)業(yè)務規(guī)則（HYPERLINKBR-002）再次檢查并更新“分配因子”類；這樣描述之后，程序開發(fā)人員在閱讀之后提出異議：在“確認”操作的時候都按照業(yè)務規(guī)則檢查，“保存”時為什么還重復檢查？其實用例描述的本意是允許執(zhí)行者在執(zhí)行“保存”之前可以先使用“確認”功能進行一次檢查。為了意思表達清楚，規(guī)定：在遇到“確認”與“執(zhí)行”之間備選操作的時候使用備選流的方式進行描述，并且將“確認”功能作為備選流描述：系統(tǒng)顯示“創(chuàng)建分配因子主數(shù)據(jù)界面”（CCA120-02）；執(zhí)行者維護“名稱”、“……”屬性值并執(zhí)行“保存”（或“確認”A-02）；系統(tǒng)根據(jù)業(yè)務規(guī)則（HYPERLINKBR-002）檢查之后，并更新“分配因子”類；……A-02：創(chuàng)建界面確認系統(tǒng)按照業(yè)務規(guī)則（HYPERLINKBR-002）檢查檢查界面數(shù)據(jù)項；事件流結束，返回調用點。業(yè)務規(guī)則的描述業(yè)務規(guī)則是需求文檔中對業(yè)務處理要求及處理邏輯的描述，因此，除了在事件流當中描寫的處理過程之外，其它需求都應該放在業(yè)務規(guī)則中描寫。業(yè)務規(guī)則的種類在新一代ERP系統(tǒng)開發(fā)規(guī)范中，按照業(yè)務規(guī)則的應用范圍（即所在文檔）的不同，將其分為業(yè)務規(guī)則和公共業(yè)務規(guī)則兩類，它們在描述上沒有什么區(qū)別，只是作用范圍不同。對于它們共同的規(guī)定有以下幾方面：在用例描述文檔中，對于重復使用的處理邏輯及處理規(guī)則，無論業(yè)務規(guī)則還是公共業(yè)務規(guī)則，除了給出正確的編號之外，還要給出其相應的中文名稱。中文名稱的要求是：能夠高度概括業(yè)務規(guī)則的主要功能；為了便于閱讀，無論業(yè)務規(guī)則還是公共業(yè)務規(guī)則，在其起始處都要給出簡要的注釋說明；業(yè)務規(guī)則的抽取及編號這里所說的“業(yè)務規(guī)則”是用例文檔中放在業(yè)務規(guī)則章節(jié)中描述的業(yè)務處理要求及處理邏輯，其有效作用范圍是所在用例。業(yè)務規(guī)則的編號為：BR-nnn，（nnn為用例中業(yè)務規(guī)則連續(xù)編號的序號）；業(yè)務規(guī)則處理公共業(yè)務規(guī)則的抽取及編號公共業(yè)務規(guī)則和用例文檔中的業(yè)務規(guī)則沒有什么特別之處，只是超過一個以上的用例共同遵循或者執(zhí)行的業(yè)務規(guī)則。有的公共業(yè)務規(guī)則是為其它模塊提供的“接口”。一般情況下，一個子模塊的公共業(yè)務規(guī)則放在一個獨立的公共業(yè)務規(guī)則文檔中；公共業(yè)務規(guī)則的編號為：BR-nnn-XXX，（nnn為獨立公共業(yè)務規(guī)則文檔中業(yè)務規(guī)則連續(xù)編號的序號；XXX為三位的子模塊編碼）；公共規(guī)則一定要抽取，避免冗余陳述。業(yè)務規(guī)則描述結構對于軟件需求的描述，根據(jù)要描述的需求的特性的不同，可以采用要點說明式的描述，也可以借鑒結構式軟件開發(fā)方法，按照業(yè)務邏輯的結構進行描述。結構式描述共有三種結構方式：順序結構、分支結構、循環(huán)結構。無論采用哪一種描述方式，都不允許通過“轉移”的方法實現(xiàn)業(yè)務邏輯，而是利用合理的結構體來實現(xiàn)各種業(yè)務邏輯關系。要點說明式對于業(yè)務邏輯非常簡單、或者沒有處理邏輯的需求，可以采用要點說明式的描述方式，通過若干個并列的說明條目，將需求描述清楚。例如：順序結構對于具有順序邏輯結構關系的需求，可以采用順序結構方式進行描述。順序結構的圖示：順序結構可以按照操作的先后順序逐條描寫。分支結構對于具有條件約束、滿足特定條件才能夠執(zhí)行的功能說明，可以采用分支結構方式進行描述。分支結構的圖示：對于分支結構，在需求文檔中使用“如果……則……”的語法進行描述，對于圖（a）的描述：如果《條件成立》，則《相應處理》對于圖（b）的描述：如果《條件成立》，則《相應處理1》否則《相應處理2》多重分支條件的描述（相當于CASE）：如果《條件1成立》，則《相應處理1》如果《條件2成立》，則《相應處理2》如果《條件3成立》，則《相應處理3》……循環(huán)結構對于需要重復處理、滿足特定條件才能夠結束的功能說明，可以采用循環(huán)結構方式進行描述。循環(huán)結構的圖示：（a）（b）在循環(huán)結構中，一定要首先給（指出）循環(huán)處理的，也可以用對象例1：例2：例3：混合結構一般情況下，對于一個比較復雜的需求，簡單地采用一種結構方式描述是不夠的，經(jīng)常是以上幾種結構方式相互嵌套的混合結構方式進行描述。注意事項不能引用另外某個過則（或流程）中的某幾個步驟，尤其是不連續(xù)的步驟。業(yè)務規(guī)則描述中的縮進規(guī)則層次關系。業(yè)務規(guī)則描述中的標號建議：。子用例的定義與描述所謂子用例，就是在UML中一個被其它用例所“包含”的用例。習慣稱“包含”用例為上級用例，“包含”稱為“引用”或“調用”。子用例的設計方法對于一個被引用的沒有界面的處理過程，也可以將其設計為公共業(yè)務規(guī)則。但是，具有獨立界面和操作過程的處理過程，必須將其設計為子用例；多個用例中具有相同的操作界面和操作過程，應該將這個相同的操作界面和操作過程設計為一個子用例；對于多個用例中具有相同的操作過程或功能，這個操作過程不是執(zhí)行者與系統(tǒng)之間交互進行的，可以將這個相同的操作過程或功能設計為一個子用例或者設計為一個公共業(yè)務規(guī)則；子用例中判斷上級調用用例的方法在合理的用例層次結構設計過程中，經(jīng)常會設計為：多個上級用例調用一個子用例，而子用例中的某一個處理功能又需要接收上級用例傳遞的參數(shù)來判斷是哪一個上級用例調用執(zhí)行的。在設計這種傳遞參數(shù)的時候，一定不要將用例編號設計為傳遞參數(shù)。因為，隨著系統(tǒng)功能的擴充，用例有可能增減，用例編號也有可能發(fā)生變化。一旦用例編號被用作為參數(shù)傳遞，用例編號的變化就會受到限制，或者需要修改用例、修改程序，或者忘記了修改用例和程序而使系統(tǒng)產(chǎn)生錯誤。一般正確的方案應該為：給每個上級用例設計一個不同的功能代碼（事務代碼）值，并且，每個上級用例在調用子用例的時候傳遞屬于的功能代碼參數(shù)值。子用例中通過判斷接收的功能代碼參數(shù)值來確定是哪一個上級用例調用執(zhí)行的。用例描述中的其它規(guī)范類、屬性、參數(shù)、值的書寫規(guī)則類名的書寫規(guī)則在用例描述文檔及業(yè)務規(guī)則文檔中，類名一定要放在引號“”中；在描寫類對象查找條件時，要按照“按照……條件在‘……’類中查找匹配對象”的書寫版式進行描寫；屬性名的書寫規(guī)則在用例描述文檔及業(yè)務規(guī)則文檔中對屬性名的描寫，在多屬性判斷的復合條件中一般情況下遵循開發(fā)語言的習慣，不放在引號（“”或‘’）中；但是為了清晰起見，在單獨使用屬性的場合下，可以象類的描述一樣，例如：檢查“資本化固定資產(chǎn)標識”屬性是否為“真”值，…參數(shù)名的書寫規(guī)則在用例描述文檔及業(yè)務規(guī)則文檔中對參數(shù)名的描寫，遵循開發(fā)語言的習慣，一般情況下不放在引號（“”或‘’）中；各種值的書寫規(guī)則在用例處理功能描述中，經(jīng)常會出現(xiàn)判斷某一個“值”的描述，這個值可以是類屬性值（或參數(shù)值、或枚舉值）。對于值描述的規(guī)范在用例描述文檔及業(yè)務規(guī)則文檔中對屬性值或參數(shù)值的直接描寫，遵循開發(fā)語言的習慣，一定要放在引號（“”或‘’）中。本書寫規(guī)則要求，要將值的描述放在引號（“”或‘’）中，而代碼值、或必要的注釋放在其后的括號中；例如：……、并且應用環(huán)境＝“營業(yè)費用-工資”、并且……一般情況下系統(tǒng)處理的都是代碼值，本規(guī)則要求，將使用的值的描述放在引號（“”或‘’）中，并且要求在其之后用括號“（）”給出代碼值（或必要的注釋性描述）。這樣做的必要性：含義清晰，不會引起歧義；開發(fā)人員讀文檔的時侯有助于快速理解文檔；修改這些值的時候一旦忘記了修改用例描述，事后容易發(fā)現(xiàn)問題、便于修改。例如：如果當前段對象的“轉出方規(guī)則”＝‘記賬金額’（1）（對應的處理功能描述）（……）用例描述中的注釋信息注釋要求用例描述文檔中需要必要注釋描述；簡要描述中/**/注釋章節(jié)注釋信息的描述描述一致性用例中的類的屬性一定要和TF表中的字段名保持一致。接口。新一代ERP系統(tǒng)中的幾個公共機制在新一代ERP系統(tǒng)中有一些公共機制會影響到系統(tǒng)開發(fā)及應用過程。有些公共機制對開發(fā)過程產(chǎn)生約束，開發(fā)必須遵循這些規(guī)范；有些公共機制的功能可以直接使用，在應用功能開發(fā)中幾乎可以不用再去考慮這些問題。刪除完整性檢查對于已經(jīng)被使用的一些主數(shù)據(jù)、設置數(shù)據(jù)等，一旦被其它數(shù)據(jù)所引用，就不允許對其執(zhí)行刪除操作，以避免系統(tǒng)內(nèi)產(chǎn)生不完整的數(shù)據(jù)。這種刪除確認檢查在整個系統(tǒng)內(nèi)采用一個統(tǒng)一實現(xiàn)機制，稱為“刪除完