diff --git a/docs/about/contribute.md b/docs/about/contribute.md index 6658413d..00973658 100644 --- a/docs/about/contribute.md +++ b/docs/about/contribute.md @@ -1,117 +1,117 @@ -# 幫助 POS 系統 +# Contributing to the POS System -大家好!很開心有人想幫助 POS 系統,你的幫忙會讓這應用程式更好的! +Hello everyone! We're thrilled that you're interested in helping improve the POS system. Your contributions will make this application even better! -本 POS 系統是一個開源的專案,並且由各方貢獻者一點一點把這產品建構起來。我們很高興有你的加入。無論你有多少時間和能力,你的付出我們都給予高度感謝。有很多種貢獻方式: +This POS system is an open-source project, built bit by bit by various contributors. We're excited to have you join us. Regardless of how much time or skill you can offer, we deeply appreciate your contributions. There are many ways to contribute: -- [改善文件](#改善文件) -- [回報程式害蟲](#如何回報程式害蟲) -- [提出新功能或改善功能](#提出新功能或改善功能) -- [設計外觀和整體架構](#調整使用者介面) -- 透過留言回應其他人的 [issue]({{ site.github.repository_url }}/issues) -- [直接撰寫程式碼改善 POS 系統](#怎麼提出程式碼上的異動) +- [Improve Documentation](#improve-documentation) +- [Report Bugs](#how-to-report-bugs) +- [Propose New Features or Enhancements](#propose-new-features-or-enhancements) +- [Design and Interface Improvements](#adjust-the-user-interface) +- Respond to other people's [issues]({{ site.github.repository_url }}/issues) +- [Directly Write Code to Improve the POS System](#how-to-submit-code-changes) -遵守以下的準則,會加速整個系統開發的流程和進度。當然,我們也會提供相應的幫助,如:確認 issue 的定位、確認改善和幫助完成最終的 PR。 +Following the guidelines below will accelerate the development process. We also provide assistance, such as verifying issues, confirming improvements, and helping finalize pull requests (PRs). -> 什麼是 [PR](https://gitbook.tw/chapters/github/pull-request.html)? +> What is a [PR](https://gitbook.tw/chapters/github/pull-request.html)? -## 你需要任何幫助嗎? +## Need Any Help? -若你有任何不知道怎麼處理的事情並未涵蓋進本文章,歡迎[來信](mailto:{{ site.social-network-links.email }})。或者你也可以直接[開一個 issue]({{ site.github.repository_url }}/issues/new) 來詢問,也許大家也有和你一樣的問題,我們一起來解決吧 😬。 +If you encounter any issues not covered in this document, feel free to [email us](mailto:{{ site.social-network-links.email }}). Alternatively, you can [open an issue]({{ site.github.repository_url }}/issues/new) to ask your question. Others might have the same question, and we can solve it together 😬. -## 改善文件 +## Improve Documentation -也許你在閱讀文件時,覺得語意怪怪的,或唸起來卡卡的,這代表這段落可能不是那麼完美。你可以先看看有沒有[類似的 issue]({{ site.github.repository_url }}/labels/document)。如果沒有,請[提交相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=document.md&title=)。 +If you find the documentation unclear or awkward while reading it, it likely needs improvement. First, check if there are any [related issues]({{ site.github.repository_url }}/labels/document). If not, please [submit a related issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=document.md&title=). -除此之外,在某些情況你可能也需要改善文件: +In addition, consider improving the documentation if you: -- 有錯字。 -- 需要增加一些圖,來幫助理解。 -- 補充文件或外站連結。 -- 當你添加新的功能時,也請記得補上相關的文件。 -- 當你想要找某些資訊時,卻沒辦法在第一個尋找的地方找到,那我們就應該在那個地方補上這類文件資訊。 +- Find typos. +- Think additional diagrams could help with understanding. +- Want to add supplementary documents or external links. +- Add new features and need to update the relevant documentation. +- Can't find information where you'd expect it, indicating the need to add it there. -在進行[程式異動](#怎麼提出程式碼上的異動)時要注意,在執行 `git checkout -b my-branch-name` 之前,應將主分支先切到 `gh-pages`,請執行 `git checkout gh-pages` 後在執行上述指令。並且,當你完成程式異動時,請記得在合併時同樣選擇 `gh-pages` 作為要求合併的分支。 +When making [code changes](#how-to-submit-code-changes), remember to switch the main branch to `gh-pages` before creating a new branch with `git checkout -b my-branch-name`. Run `git checkout gh-pages` before the above command. When merging, select `gh-pages` as the base branch. -## 如何回報程式害蟲 +## How to Report Bugs -哇哩咧,被你找到 bug 了!請先看看你找到的害蟲是否[已經被回報了]({{ site.github.repository_url }}/labels/bug)。如果還沒有類似的害蟲,請[提交相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=bug_report.md&title=)。 +Found a bug? First, check if it has [already been reported]({{ site.github.repository_url }}/labels/bug). If not, please [submit a related issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=bug_report.md&title=). -這裡有幾個小技巧幫助你撰寫出一個好的害蟲通報文件: +Here are some tips for writing a good bug report: -- 說明明確的問題(例如,「出現錯誤」和「製作產品菜單時,若設定相同名字仍可以建立成功」)。 -- 你怎麼產生這個問題的? -- 你預期應該要有什麼結果卻得到什麼結果。 -- 確保你已經使用最新版本的應用程式。 -- 說明你使用的手機型號和版本。 -- 一隻害蟲一個 issue,若你發現兩個問題,請發兩個 issue。 -- 就算你不知道該怎麼解決這些問題,幫助其他人重現問題可以加速問題的發現。 -- 若你發現任何安全性的問題,請不要發 issue,相對的,請發信到 ,會有人來專門處理。 +- Clearly describe the issue (e.g., "error occurs" vs. "creating a product menu allows identical names to be set successfully"). +- Explain how you encountered the issue. +- State the expected outcome versus the actual result. +- Ensure you're using the latest version of the app. +- Specify your device model and OS version. +- Report one bug per issue; submit separate issues for multiple bugs. +- Even if you don't know how to fix the issue, helping others reproduce it can speed up resolution. +- For security issues, do not open an issue. Instead, email for specialized handling. -## 提出新功能或改善功能 +## Propose New Features or Enhancements -如果你發現任何希望要有的功能而本 POS 系統並沒有,那你可能並不孤單,很多人都想要有該功能。很多現有的功能都是透過使用者的回饋才慢慢增加的。 +If you have an idea for a feature that the POS system lacks, you're likely not alone. Many features have been added based on user feedback. -我們非常歡迎提出新功能,但是思考一下是否該功能和 POS 系統是有關係的,你可以提出想法大家一起來討論看看本功能實作的價值。請提出足夠的細節和可行性,並且說明一下該功能試圖解決的問題。 +We welcome new feature proposals. Ensure the feature relates to the POS system and provide enough detail and feasibility. Explain the problem the feature aims to solve. -再次感謝你提出想法幫助本產品更好,開始[建立相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=feature_request.md&title=) 吧! +Thank you for helping improve the product. Start [creating a related issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=feature_request.md&title=)! -## 調整使用者介面 +## Adjust the User Interface -一個好的應用程式必須要有好的使用者介面,這包括應外觀設計和使用者操作順暢度。若你認為某區塊的顏色應該配上新的色彩,那我們就來試試看吧!請發出[相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=design.md&title=)。 +A good application needs a well-designed user interface, including both aesthetics and user experience. If you think a particular section needs a color change, let's try it! Please submit a [related issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=design.md&title=). -這裡也提供幾點應注意的事項: +Consider the following: -- 由於外觀和顏色是較為主觀的東西,每次調整,可能都會需要部分使用者的支持,例如按讚,才會考慮。 -- 請提供前後變更的相關截圖,幫助 PR 流程的進展。 -- 調整顏色應設定於定值,而非在特定元件上的變數。 +- Design changes are subjective; user support (e.g., likes) may be required for consideration. +- Provide before-and-after screenshots to aid the PR process. +- Set colors in constants rather than component-specific variables. -## 第一次嘗試貢獻 +## First-Time Contribution -我們很開心你願意貢獻本專案。若你不確定如何開始做任何幫忙,建議你可以看看關於[good first issue]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22good+first+issue%22),來看看什麼是好的 issue。除此之外[help wanted]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22help+wanted%22)也是一個對於不知如何幫忙的人下手的好地方。 +We're delighted you want to contribute. If you're unsure where to start, check the [good first issue]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22good+first+issue%22) label for suitable issues. Also, the [help wanted]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22help+wanted%22) label is a good place to find tasks needing assistance. -- Good first issues - 應該只會包含少數幾行程式碼的修正和一組單元測試。 -- Help wanted issues - 可能會需要一些能力和經驗,但卻是一個特別需要大家幫忙的地方。 +- Good first issues usually involve minor code changes and a unit test. +- Help wanted issues might require more skill and experience but are areas needing help. -> 歡迎你透過 issue 或信箱提出任何問題,大家都是從初學者開始的唷 😺 +> Feel free to ask questions via issue or email. Everyone starts as a beginner 😺. -## 怎麼提出程式碼上的異動 +## How to Submit Code Changes -如要提出程式碼上的異動這裡有幾個建議方針去執行。 +Here are some guidelines for submitting code changes: -- 若你是製作外觀上的改變,請提供截圖說明改善前後的差異。 -- 遵循 Flutter 程式碼[指南](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo)。 -- 若你是改動使用者會接觸到的功能,請記得更新相關的文件。 -- 每個 PR 應該執行一個功能或處理一個害蟲。若你有多個功能或害蟲,請提交多個 PR。 -- 不要改變和你要做的事情沒關的檔案。 -- [撰寫好的 commit 訊息](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)。 +- For UI changes, provide before-and-after screenshots. +- Follow the Flutter code [style guide](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo). +- Update relevant documentation for any user-facing changes. +- Each PR should address one feature or bug. Submit separate PRs for multiple changes. +- Avoid modifying unrelated files. +- [Write good commit messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -以下是執行程式碼改動的順序。 +Steps for code changes: -- [Fork]({{ site.github.repository_url }}/fork) 並且複製本專案。 -- 安裝必要檔案:`flutter pub get`。 -- 安裝輔助工具:`flutter run build_runner build`。 -- 確保你本地端可以正確執行:`flutter test`。 -- 建立新的分支:`git checkout -b my-branch-name` -- 改動你要改的地方,並建立測試。 -- 推到你 fork 的專案後提交 PR:`git push -u origin my-branch-name` -- 你可以休息一下了 😆,會有人來處理你的 PR 並把他合併進主要分支。 +- [Fork]({{ site.github.repository_url }}/fork) and clone the project. +- Install necessary dependencies: `flutter pub get`. +- Install helper tools: `flutter run build_runner build`. +- Ensure local tests pass: `flutter test`. +- Create a new branch: `git checkout -b my-branch-name`. +- Make your changes and add tests. +- Push to your fork and submit a PR: `git push -u origin my-branch-name`. +- Take a break 😆. Someone will review and merge your PR. -等不及想試試看提交你的第一個 PR 了嗎?你可以閱讀 GitHub 官方文件關於[如何貢獻 Open Source](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)。 +Excited to submit your first PR? Check out GitHub's [How to Contribute to Open Source](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) guide. -## 如何準備本地端環境 +## How to Set Up the Local Environment -詳見[本地端開發](../maintenance/development.md)。 +See [Local Development](../maintenance/development.md). -## 如何進行測試 +## How to Run Tests -詳見[本地端開發](../maintenance/development.md)。 +See [Local Development](../maintenance/development.md). -## Code of conduct +## Code of Conduct -This project is governed by [the Contributor Covenant Code of Conduct](../CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. +This project follows the [Contributor Covenant Code of Conduct](../CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. -## 其他有用資源 +## Additional Resources - [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/) - [Using Pull Requests](https://help.github.com/articles/using-pull-requests/) diff --git a/docs/about/contribute.zh.md b/docs/about/contribute.zh.md new file mode 100644 index 00000000..2e8da59e --- /dev/null +++ b/docs/about/contribute.zh.md @@ -0,0 +1,119 @@ +# 幫助 POS 系統 + +大家好!很開心有人想幫助 POS 系統,你的幫忙會讓這應用程式更好的! + +本 POS 系統是一個開源的專案,並且由各方貢獻者一點一點把這產品建構起來。我們很高興有你的加入。無論你有多少時間和能力,你的付出我們都給予高度感謝。有很多種貢獻方式: + +- [改善文件](#改善文件) +- [回報程式害蟲](#如何回報程式害蟲) +- [提出新功能或改善功能](#提出新功能或改善功能) +- [設計外觀和整體架構](#調整使用者介面) +- 透過留言回應其他人的 [issue]({{ site.github.repository_url }}/issues) +- [直接撰寫程式碼改善 POS 系統](#怎麼提出程式碼上的異動) + +遵守以下的準則,會加速整個系統開發的流程和進度。當然,我們也會提供相應的幫助,如:確認 issue 的定位、確認改善和幫助完成最終的 PR。 + +> 什麼是 [PR](https://gitbook.tw/chapters/github/pull-request.html)? + +## 你需要任何幫助嗎? + +若你有任何不知道怎麼處理的事情並未涵蓋進本文章,歡迎[來信](mailto:{{ site.social-network-links.email }})。或者你也可以直接[開一個 issue]({{ site.github.repository_url }}/issues/new) 來詢問,也許大家也有和你一樣的問題,我們一起來解決吧 😬。 + +## 改善文件 + +也許你在閱讀文件時,覺得語意怪怪的,或唸起來卡卡的,這代表這段落可能不是那麼完美。你可以先看看有沒有[類似的 issue]({{ site.github.repository_url }}/labels/document)。如果沒有,請[提交相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=document.md&title=)。 + +除此之外,在某些情況你可能也需要改善文件: + +- 有錯字。 +- 需要增加一些圖,來幫助理解。 +- 補充文件或外站連結。 +- 當你添加新的功能時,也請記得補上相關的文件。 +- 當你想要找某些資訊時,卻沒辦法在第一個尋找的地方找到,那我們就應該在那個地方補上這類文件資訊。 + +在進行[程式異動](#怎麼提出程式碼上的異動)時要注意,在執行 `git checkout -b my-branch-name` 之前,應將主分支先切到 `gh-pages`,請執行 `git checkout gh-pages` 後在執行上述指令。並且,當你完成程式異動時,請記得在合併時同樣選擇 `gh-pages` 作為要求合併的分支。 + +## 如何回報程式害蟲 + +哇哩咧,被你找到 bug 了!請先看看你找到的害蟲是否[已經被回報了]({{ site.github.repository_url }}/labels/bug)。如果還沒有類似的害蟲,請[提交相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=bug_report.md&title=)。 + +這裡有幾個小技巧幫助你撰寫出一個好的害蟲通報文件: + +- 說明明確的問題(例如,「出現錯誤」和「製作產品菜單時,若設定相同名字仍可以建立成功」)。 +- 你怎麼產生這個問題的? +- 你預期應該要有什麼結果卻得到什麼結果。 +- 確保你已經使用最新版本的應用程式。 +- 說明你使用的手機型號和版本。 +- 一隻害蟲一個 issue,若你發現兩個問題,請發兩個 issue。 +- 就算你不知道該怎麼解決這些問題,幫助其他人重現問題可以加速問題的發現。 +- 若你發現任何安全性的問題,請不要發 issue,相對的,請發信到 ,會有人來專門處理。 + +## 提出新功能或改善功能 + +如果你發現任何希望要有的功能而本 POS 系統並沒有,那你可能並不孤單,很多人都想要有該功能。很多現有的功能都是透過使用者的回饋才慢慢增加的。 + +我們非常歡迎提出新功能,但是思考一下是否該功能和 POS 系統是有關係的,你可以提出想法大家一起來討論看看本功能實作的價值。請提出足夠的細節和可行性,並且說明一下該功能試圖解決的問題。 + +再次感謝你提出想法幫助本產品更好,開始[建立相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=feature_request.md&title=) 吧! + +## 調整使用者介面 + +一個好的應用程式必須要有好的使用者介面,這包括應外觀設計和使用者操作順暢度。若你認為某區塊的顏色應該配上新的色彩,那我們就來試試看吧!請發出[相關的 issue]({{ site.github.repository_url }}/issues/new?assignees=&labels=&template=design.md&title=)。 + +這裡也提供幾點應注意的事項: + +- 由於外觀和顏色是較為主觀的東西,每次調整,可能都會需要部分使用者的支持,例如按讚,才會考慮。 +- 請提供前後變更的相關截圖,幫助 PR 流程的進展。 +- 調整顏色應設定於定值,而非在特定元件上的變數。 + +## 第一次嘗試貢獻 + +我們很開心你願意貢獻本專案。若你不確定如何開始做任何幫忙,建議你可以看看關於[good first issue]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22good+first+issue%22),來看看什麼是好的 issue。除此之外[help wanted]({{ site.github.repository_url }}/issues?q=is%3Aissue+label%3A%22help+wanted%22)也是一個對於不知如何幫忙的人下手的好地方。 + +- Good first issues - 應該只會包含少數幾行程式碼的修正和一組單元測試。 +- Help wanted issues - 可能會需要一些能力和經驗,但卻是一個特別需要大家幫忙的地方。 + +> 歡迎你透過 issue 或信箱提出任何問題,大家都是從初學者開始的唷 😺 + +## 怎麼提出程式碼上的異動 + +如要提出程式碼上的異動這裡有幾個建議方針去執行。 + +- 若你是製作外觀上的改變,請提供截圖說明改善前後的差異。 +- 遵循 Flutter 程式碼[指南](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo)。 +- 若你是改動使用者會接觸到的功能,請記得更新相關的文件。 +- 每個 PR 應該執行一個功能或處理一個害蟲。若你有多個功能或害蟲,請提交多個 PR。 +- 不要改變和你要做的事情沒關的檔案。 +- [撰寫好的 commit 訊息](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)。 + +以下是執行程式碼改動的順序。 + +- [Fork]({{ site.github.repository_url }}/fork) 並且複製本專案。 +- 安裝必要檔案:`flutter pub get`。 +- 安裝輔助工具:`flutter run build_runner build`。 +- 確保你本地端可以正確執行:`flutter test`。 +- 建立新的分支:`git checkout -b my-branch-name` +- 改動你要改的地方,並建立測試。 +- 推到你 fork 的專案後提交 PR:`git push -u origin my-branch-name` +- 你可以休息一下了 😆,會有人來處理你的 PR 並把他合併進主要分支。 + +等不及想試試看提交你的第一個 PR 了嗎?你可以閱讀 GitHub 官方文件關於[如何貢獻 Open Source](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)。 + +## 如何準備本地端環境 + +詳見[本地端開發](../maintenance/development.md)。 + +## 如何進行測試 + +詳見[本地端開發](../maintenance/development.md)。 + +## Code of conduct + +This project is governed by [the Contributor Covenant Code of Conduct](../CODE_OF_CONDUCT.md). +By participating, you are expected to uphold this code. + +## 其他有用資源 + +- [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/) +- [Using Pull Requests](https://help.github.com/articles/using-pull-requests/) +- [GitHub Help](https://help.github.com) diff --git a/docs/about/structure.md b/docs/about/structure.md index ebc33db8..1392e7a4 100644 --- a/docs/about/structure.md +++ b/docs/about/structure.md @@ -1,24 +1,30 @@ -# 架構 +# Architecture -使用 [Flutter](https://flutter.dev) 去撰寫所有應用程式相關邏輯, -他提供很多素材去做學習,包括各種應用程式的完成品, -如 [Gallery](https://github.com/flutter/gallery) 和其他[小範例](https://github.com/flutter/samples)。 +We use [Flutter](https://flutter.dev) to write all application-related logic. +Flutter provides a wealth of resources for learning, +including complete applications like [Gallery](https://github.com/flutter/gallery) +and various [samples](https://github.com/flutter/samples). -Flutter 透過 [Skia](https://skia.org) 來做繪圖工具, -在所有平台(macOS、Linux、Windows、Website、iOS APP、Android APP)中都利用該套件直接和底層 OS 接觸, -減少和各平台的接口接觸,進而達到能在眾平台中統一介面。 +Flutter uses [Skia](https://skia.org) as its graphics engine, +enabling direct interaction with the underlying OS on all platforms +(macOS, Linux, Windows, Web, iOS, Android). +This minimizes the need for platform-specific interfaces, +allowing a unified interface across multiple platforms. -當然,在一些特殊情境上,仍需要單獨處理平台的設定。 -例如,iOS 的通知,便需要在 XCode 和 [AppStoreConnect](http://appstoreconnect.apple.com) 中設定。 -但整體的商務邏輯和應用程式設計都可以直接使用 Flutter 撰寫。 +Of course, in certain scenarios, specific platform configurations are required. +For example, iOS notifications need to be set up in XCode and [AppStoreConnect](http://appstoreconnect.apple.com). +However, the overall business logic and application design can be written directly using Flutter. -Flutter 是一個框架,撰寫其框架的語言是 [Dart](https://dart.dev), -其風格類似於很多物件導向的語言。個人是覺得和其他語言沒什麼差別,主要是覺得他和 IDE 融合得很好,撰寫起來很方便,相關文件也很充足。 -這有幾個詳細說明的文章,無聊可以讀讀, -[10-good-reasons-why-you-should-learn-dart](https://medium.com/hackernoon/10-good-reasons-why-you-should-learn-dart-4b257708a332)、 -[why-flutter-uses-dart](https://hackernoon.com/why-flutter-uses-dart-dd635a054ebf)。 +Flutter is a framework, and the language used to write it is [Dart](https://dart.dev). +Dart's style is similar to many object-oriented languages. +Personally, I find it no different from other languages, +mainly because it integrates well with IDEs, making it convenient to write. +The documentation is also extensive. Here are a few detailed articles worth reading: -如果想馬上來試試,可以玩玩看他們的線上 [compiler](https://dartpad.dev/?null_safety=true)。 +- [10 good reasons why you should learn Dart](https://medium.com/hackernoon/10-good-reasons-why-you-should-learn-dart-4b257708a332) +- [Why Flutter uses Dart](https://hackernoon.com/why-flutter-uses-dart-dd635a054ebf) + +If you want to try it out right away, you can play with their online [compiler](https://dartpad.dev/?null_safety=true). ## POS 系統在 Flutter 之上的架構 diff --git a/docs/about/structure.zh.md b/docs/about/structure.zh.md new file mode 100644 index 00000000..ebc33db8 --- /dev/null +++ b/docs/about/structure.zh.md @@ -0,0 +1,187 @@ +# 架構 + +使用 [Flutter](https://flutter.dev) 去撰寫所有應用程式相關邏輯, +他提供很多素材去做學習,包括各種應用程式的完成品, +如 [Gallery](https://github.com/flutter/gallery) 和其他[小範例](https://github.com/flutter/samples)。 + +Flutter 透過 [Skia](https://skia.org) 來做繪圖工具, +在所有平台(macOS、Linux、Windows、Website、iOS APP、Android APP)中都利用該套件直接和底層 OS 接觸, +減少和各平台的接口接觸,進而達到能在眾平台中統一介面。 + +當然,在一些特殊情境上,仍需要單獨處理平台的設定。 +例如,iOS 的通知,便需要在 XCode 和 [AppStoreConnect](http://appstoreconnect.apple.com) 中設定。 +但整體的商務邏輯和應用程式設計都可以直接使用 Flutter 撰寫。 + +Flutter 是一個框架,撰寫其框架的語言是 [Dart](https://dart.dev), +其風格類似於很多物件導向的語言。個人是覺得和其他語言沒什麼差別,主要是覺得他和 IDE 融合得很好,撰寫起來很方便,相關文件也很充足。 +這有幾個詳細說明的文章,無聊可以讀讀, +[10-good-reasons-why-you-should-learn-dart](https://medium.com/hackernoon/10-good-reasons-why-you-should-learn-dart-4b257708a332)、 +[why-flutter-uses-dart](https://hackernoon.com/why-flutter-uses-dart-dd635a054ebf)。 + +如果想馬上來試試,可以玩玩看他們的線上 [compiler](https://dartpad.dev/?null_safety=true)。 + +## POS 系統在 Flutter 之上的架構 + +這裡嘗試讓初入的人了解應用程式架構。 + +### 主要架構 + +```text +. +├── assets/ - 各種圖片,未來可能會放字體 +├── lib/ - 主要邏輯 +│ ├── components/ - 各種 UI 輔助元件 +│ ├── constants/ - 各種定死的標準,例如外觀顏色,常用圖標 +│ ├── helpers/ - 各地方常用函示,例如 Log +│ ├── l10n/ - 應用程式內的文字,和各語言的翻譯(實質僅有 zh-TW) +│ ├── models/ - 物件,例如產品、成份等等。會在這裡和 Services 接觸而非 UI 裡面 +│ ├── services/ - 和應用程式外部溝通的工具,例如 DB +│ ├── settings/ - 使用者可以調整的設定,例如主題、語言和外觀 +│ ├── ui/ - 應用程式主要外觀設計 +│ ├── main.dart - 處理 Services、Models 和 Firebase 的初始化 +│ ├── my_app.dart - 建置主體 APP 位置 +│ ├── routes.dart - 放置應用程式路徑位置 +│ └── translator.dart - 讓應用程式不需要每次都呼叫很長的翻譯物件 +└── test/ - 單元和元件測試,架構和 lib/ 一樣 +``` + +### Components + +```text +components/ - 各種 UI 輔助元件 +├── dialog/ - 對話框 +│ ├── confirm_dialog - 確認通知 +│ ├── delete_dialog - 刪除通知 +│ ├── single_text_dialog - 可輸入文字的對話框 +│ └── slider_text_dialog - 滑動有數字屬性的對話框 +├── mixin/ - 輔助型元件 +│ └── item_modal - 編輯物件(如產品、成分)用的模組 +├── models/ - 和物件有關的 UI 元件 +├── scaffold/ - 框架類元件 +│ ├── item_list_scaffold - 目前僅有設定時會用到,未來可能會直接搬到 setting_screen +│ └── reorderable_scaffold - 可以重新排列物件的框架 +└── style/ - 不會過 test 的元件 + └── ... - 小東西,不列舉 +``` + +### Constants + +```text +constants/ - 各種定死的標準,例如外觀顏色,常用圖標 +├── app_themes - 外觀顏色 +├── constant - 數字類的標準,如 padding、margin 的大小 +└── icons - 常用圖標 +``` + +### Helpers + +```text +helpers/ - 各地方常用函示,例如 Log +├── exporter/ - 包裝匯出資料的 API +├── formater/ - 格式化資料 +├── launcher - 包裝「點擊連結會跳出瀏覽器」 +├── logger - 輸出,包括輸出到 Firebase Analytics +├── util - 雜項 +└── validator - 驗證輸入的工具,例如文字必須為數字且必須大於一 +``` + +### Models + +```text +models/ - 物件,例如產品、成份等等。會在這裡和 Services 接觸而非 UI 裡面 +├── constumer/ - 菜單 +│ ├── customer_setting_option - 顧客設定的選項 +│ └── customer_setting - 顧客設定 +├── menu/ - 菜單 +│ ├── catalog - 產品種類 +│ ├── product_ingredient - 產品的成分 +│ ├── product_quantity - 產品的份量 +│ └── product - 產品 +├── objects/ - 用來做 I/O 的物件 +│ ├── cashier_object - 收銀機的物件 +│ ├── customer_object - 顧客設定的物件 +│ ├── menu_object - 菜單的物件 +│ ├── order_attributeobject - 訂單屬性(上面的顧客設定) +│ ├── order_object - 訂單的物件 +│ └── stock_object - 庫存的物件 +├── order/ - 訂單 +│ └── order_product - 訂單的產品設定 +├── repository/ - 物件庫 +│ ├── cart_ingredients - 訂單時,產品的成份管理 +│ ├── cart - 訂單的物件庫,購物車 +│ ├── cashier - 收銀機的物件庫 +│ ├── customer_settings - 顧客設定的物件庫 +│ ├── menu - 菜單的物件庫 +│ ├── quantities - 份量的物件庫 +│ ├── replenisher - 補貨的物件庫 +│ ├── seller - 點單的物件庫,賣家,用來處理把訂單丟進 DB +│ └── stock - 庫存的物件庫,雖然 inventory 這名稱比較適合,但為時已晚 +├── stock/ - 庫存 +│ ├── ingredient - 庫存的成份 +│ ├── quantity - 庫存的成分數量 +│ └── replenishment - 庫存的補貨 +├── model_object - object 的基本物件 +├── model - model 的基本物件 +├── repository - repository 的基本物件 +└── xfile - 包裝檔案系統的 API +``` + +### Services + +```text +services/ - 和應用程式外部溝通的工具,例如 DB +├── auth - 驗證邏輯,使用者的登入等等 +├── cache - 記錄使用者的設定和行為,例如是否看過 tutorial +├── database - 紀錄點單等多筆的資料,Sqlite +├── database_migrations - database 不同版本時整合的紀錄 +├── image_dumper - 管理 image 的存取 +└── storage - 紀錄菜單和庫存等高變種的資料,NoSQL +``` + +### Settings + +```text +settings/ - 使用者可以調整的設定,例如主題、語言 +├── cashier_warning - 收銀機的告警設定 +├── collect_event - 收集使用者錯誤訊息設定 +├── currency - 幣種,目前尚無使用,僅是預先做好,未來有需要可以開 +├── language - 語言 +├── order_awakening - 點餐時是否關閉螢幕的設定 +├── order_outlook - 點餐時的外觀設定 +├── order_product_axis_count - 點餐時的外觀設定 +├── theme - 主題,目前僅有日光和暗色 +├── setting - 設定的介面 +└── settings_provier - 管理所有設定的介面 +``` + +### UI + +基本的框架為: + +```text +feature/ - 特定功能 +├── ... - 功能下的子功能,若有會列出來 +├── widgets/ - 功能的輔助物件,不會在下表中列出來 +└── feature_screen - 功能的架構,不會在下表中列出來 +``` + +各介面: + +```text +ui/ - 應用程式主要外觀設計 +├── analysis/ - 分析點單 +├── cashier/ - 收銀機 +│ └── changer - 換錢 +├── customer/ - 顧客設定 +├── home/ - 主頁 +├── menu/ - 菜單 +│ ├── catalog/ - 產品種類 +│ └── product/ - 產品 +├── order/ - 點單 +│ ├── cart - 購物車 +│ └── cashier - 結帳 +├── setting/ - 設定 +└── stock/ - 庫存 + ├── quantity - 成分數量 + └── replenishment - 補貨 +``` diff --git a/docs/maintenance/bump-dependencies.md b/docs/maintenance/bump-dependencies.md index 394dd14b..716dd87a 100644 --- a/docs/maintenance/bump-dependencies.md +++ b/docs/maintenance/bump-dependencies.md @@ -1,12 +1,12 @@ -# 更新相依套件 +# Update Dependencies -分三種: +There are three types: -- dependencies,直接依賴的套件 -- dev_dependencies,開發環境依賴的套件 -- transitive,依賴套件的依賴套件 +- dependencies: Direct dependencies +- dev_dependencies: Development environment dependencies +- transitive: Dependencies of the dependencies -## 如何查找哪些套件需要更新 +## How to Check Which Packages Need Updating ```bash $ make outdated @@ -22,23 +22,23 @@ dev_dependencies: dev_package *1.0.0 *1.0.0 *1.1.0 1.1.0 ``` -但要注意幾件事: +Note the following: -- `Current` 代表現在的版本 -- `Upgradable` 代表依據[版本限制](https://dart.dev/tools/pub/dependencies#version-constraints)所能升級的最高版本 -- `Resolvable` 代表在和現有環境(主要是 dart/flutter 版本)不衝突的情況下可升級的最高版本 -- `Latest` 代表這個套件目前最新的版本 +- `Current`: The current version +- `Upgradable`: The highest version upgradable according to [version constraints](https://dart.dev/tools/pub/dependencies#version-constraints) +- `Resolvable`: The highest version upgradable without conflicting with the current environment (mainly Dart/Flutter version) +- `Latest`: The latest version of the package -## 如何升級 +## How to Upgrade -根據上面得到想要升級的版本後 +After identifying the version to upgrade to: flutter pub upgrade some_package -這樣的方式可以同時升級 Transitive 的套件。 +This method also upgrades transitive dependencies. -## 更新之後 +## After Updating -請記得重新跑一次 Mock,因為新版本的套件可能會有新的 API: +Remember to rerun the mock process, as new versions of packages may introduce new APIs: make mock diff --git a/docs/maintenance/bump-dependencies.zh.md b/docs/maintenance/bump-dependencies.zh.md new file mode 100644 index 00000000..394dd14b --- /dev/null +++ b/docs/maintenance/bump-dependencies.zh.md @@ -0,0 +1,44 @@ +# 更新相依套件 + +分三種: + +- dependencies,直接依賴的套件 +- dev_dependencies,開發環境依賴的套件 +- transitive,依賴套件的依賴套件 + +## 如何查找哪些套件需要更新 + +```bash +$ make outdated +Showing outdated packages. +[*] indicates versions that are not the latest available. + +Package Name Current Upgradable Resolvable Latest + +direct dependencies: +some_package *3.2.0 *3.2.0 *3.2.0 4.0.0 + +dev_dependencies: +dev_package *1.0.0 *1.0.0 *1.1.0 1.1.0 +``` + +但要注意幾件事: + +- `Current` 代表現在的版本 +- `Upgradable` 代表依據[版本限制](https://dart.dev/tools/pub/dependencies#version-constraints)所能升級的最高版本 +- `Resolvable` 代表在和現有環境(主要是 dart/flutter 版本)不衝突的情況下可升級的最高版本 +- `Latest` 代表這個套件目前最新的版本 + +## 如何升級 + +根據上面得到想要升級的版本後 + + flutter pub upgrade some_package + +這樣的方式可以同時升級 Transitive 的套件。 + +## 更新之後 + +請記得重新跑一次 Mock,因為新版本的套件可能會有新的 API: + + make mock diff --git a/docs/maintenance/deployment.md b/docs/maintenance/deployment.md index 9836fc08..692a77e1 100644 --- a/docs/maintenance/deployment.md +++ b/docs/maintenance/deployment.md @@ -1,17 +1,17 @@ -# 部署流程 +# Deployment Process -分為三個環境: +Divided into three environments: -- `internal`:內部測試用。 -- `beta`:對外的測試,同樣的檔案會推展到 `promote_to_production`。 -- `promote_to_production`:把 `beta` 的版本推到線上。 +- `internal`: For internal testing. +- `beta`: For external testing. The same files will be pushed to `promote_to_production`. +- `promote_to_production`: Pushes the `beta` version to production. -分別的部署方式如下: +Deployment steps for each environment are as follows: - `internal` - 1. 執行 `make bump` 後,根據想要更新的版本輸入。 + 1. Run `make bump` and input the desired version update. - `beta` - 1. 執行 `make bump-beta`。 + 1. Run `make bump-beta`. - `promote_to_production` - 1. 把 GitHub 的 [draft release](https://github.com/evan361425/flutter-pos-system/releases) publish 出來。 - 2. 確認都沒問題後,可以把舊的 tag 清掉:`make clean-version` + 1. Publish the [draft release](https://github.com/evan361425/flutter-pos-system/releases) on GitHub. + 2. After confirming everything is fine, you can clean up old tags: `make clean-version`. diff --git a/docs/maintenance/deployment.zh.md b/docs/maintenance/deployment.zh.md new file mode 100644 index 00000000..9836fc08 --- /dev/null +++ b/docs/maintenance/deployment.zh.md @@ -0,0 +1,17 @@ +# 部署流程 + +分為三個環境: + +- `internal`:內部測試用。 +- `beta`:對外的測試,同樣的檔案會推展到 `promote_to_production`。 +- `promote_to_production`:把 `beta` 的版本推到線上。 + +分別的部署方式如下: + +- `internal` + 1. 執行 `make bump` 後,根據想要更新的版本輸入。 +- `beta` + 1. 執行 `make bump-beta`。 +- `promote_to_production` + 1. 把 GitHub 的 [draft release](https://github.com/evan361425/flutter-pos-system/releases) publish 出來。 + 2. 確認都沒問題後,可以把舊的 tag 清掉:`make clean-version` diff --git a/docs/maintenance/development.md b/docs/maintenance/development.md index 8b2608ce..d6e6afbb 100644 --- a/docs/maintenance/development.md +++ b/docs/maintenance/development.md @@ -1,15 +1,15 @@ -# 本地端開發 +# Local Development -正常程式碼開發只需要: +For regular code development, simply run: flutter pub get -就可以安裝你需要的東西了,但如果你想要建置應用程式,你需要三個東西: +This will install the necessary dependencies. However, if you want to build the application, you need three things: -- `/android/.jks`,這是用來存放你的鑰匙的,確保你就是這個應用程式的擁有者,你可以這樣產生: +- `/android/.jks`: This is for storing your keys to ensure ownership of the application. You can generate it with: ```bash -# 假設 為 my-jks +# Assuming is my-jks keytool -genkey -v -keystore android/app/my-jks.jks \ -alias possystem \ -keyalg RSA \ @@ -19,9 +19,9 @@ keytool -genkey -v -keystore android/app/my-jks.jks \ -dname 'CN=possystem, OU=possystem, O=possystem, L=Unknown, ST=Unknown, C=Unknown' ``` -- `/android/key.properties`,用來告訴建置應用程式時,你的鑰匙放哪裡,他裡面需要這些東西(依照上述產生範例): +- `/android/key.properties`: This file tells the build process where your key is located. It should contain the following (based on the example above): - `keyAlias=possystem` - - `keyPassword=possystem`,keyPassword 如果你沒特別設定,預設和 storePassword 一樣 + - `keyPassword=possystem` (If not specifically set, it defaults to the same as storePassword) - `storeFile=my-jks.jks` - `storePassword=possystem` @@ -33,9 +33,7 @@ printf "keyAlias=%s\nkeyPassword=%s\nstoreFile=%s\nstorePassword=%s" \ 'possystem' > android/key.properties ``` -- `/android/app/google-services.json`, - 你可以到 [Firebase Console](https://console.firebase.google.com/) 去產生, - 但是記得要在 *專案設定* 裡面去設定剛剛產生的金鑰 SHA 憑證指紋,你可以這樣輸出: +- `/android/app/google-services.json`: This can be generated from the [Firebase Console](https://console.firebase.google.com/). Remember to configure the SHA certificate fingerprint in *Project Settings* using: ```bash $ keytool -list -keystore android/app/my-jks.jks --storepass possystem @@ -48,24 +46,22 @@ mykey, May 18, 2024, PrivateKeyEntry, Certificate fingerprint (SHA-256): 6F:14:57:54:CC:26:0A:4C:70:E3:28:1D:CE:D0:73:3F:72:19:49:96:8F:9A:1B:31:A5:E2:96:E4:44:14:E1:A1 ``` -- 最後請更改 `/lib/firebase_compatible_options.dart` 裡面最下面的 `androidDebug` 設定。 - 你可以 `dart pub global activate flutterfire_cli` 安裝指令套件後 `flutterfire configure`, - 然後把產生的檔案的設定資訊複製到 `firebase_compatible_options.dart` 中。 +- Finally, update the `androidDebug` setting at the bottom of `/lib/firebase_compatible_options.dart`. You can install the command-line tool with `dart pub global activate flutterfire_cli` and then run `flutterfire configure`. Copy the generated configuration into `firebase_compatible_options.dart`. -## 測試 +## Testing -在開始執行測試之前,你可以先把 mock 檔案準備好: +Before running tests, prepare the mock files: make mock -當想要開始測試,你可以: +To start testing: make test -如果想要測試加上 coverage,你可以: +To run tests with coverage: make test-coverage -最後產出的覆蓋率就可以打開以網頁格式打開: +The generated coverage report can be viewed in a web format: open coverage/html/index.html diff --git a/docs/maintenance/development.zh.md b/docs/maintenance/development.zh.md new file mode 100644 index 00000000..8b2608ce --- /dev/null +++ b/docs/maintenance/development.zh.md @@ -0,0 +1,71 @@ +# 本地端開發 + +正常程式碼開發只需要: + + flutter pub get + +就可以安裝你需要的東西了,但如果你想要建置應用程式,你需要三個東西: + +- `/android/.jks`,這是用來存放你的鑰匙的,確保你就是這個應用程式的擁有者,你可以這樣產生: + +```bash +# 假設 為 my-jks +keytool -genkey -v -keystore android/app/my-jks.jks \ + -alias possystem \ + -keyalg RSA \ + -keysize 2048 \ + -validity 10000 \ + -storepass possystem \ + -dname 'CN=possystem, OU=possystem, O=possystem, L=Unknown, ST=Unknown, C=Unknown' +``` + +- `/android/key.properties`,用來告訴建置應用程式時,你的鑰匙放哪裡,他裡面需要這些東西(依照上述產生範例): + - `keyAlias=possystem` + - `keyPassword=possystem`,keyPassword 如果你沒特別設定,預設和 storePassword 一樣 + - `storeFile=my-jks.jks` + - `storePassword=possystem` + +```bash +printf "keyAlias=%s\nkeyPassword=%s\nstoreFile=%s\nstorePassword=%s" \ + 'possystem' \ + 'possystem' \ + 'my-jks.jks' \ + 'possystem' > android/key.properties +``` + +- `/android/app/google-services.json`, + 你可以到 [Firebase Console](https://console.firebase.google.com/) 去產生, + 但是記得要在 *專案設定* 裡面去設定剛剛產生的金鑰 SHA 憑證指紋,你可以這樣輸出: + +```bash +$ keytool -list -keystore android/app/my-jks.jks --storepass possystem +Keystore type: PKCS12 +Keystore provider: SUN + +Your keystore contains 1 entry + +mykey, May 18, 2024, PrivateKeyEntry, +Certificate fingerprint (SHA-256): 6F:14:57:54:CC:26:0A:4C:70:E3:28:1D:CE:D0:73:3F:72:19:49:96:8F:9A:1B:31:A5:E2:96:E4:44:14:E1:A1 +``` + +- 最後請更改 `/lib/firebase_compatible_options.dart` 裡面最下面的 `androidDebug` 設定。 + 你可以 `dart pub global activate flutterfire_cli` 安裝指令套件後 `flutterfire configure`, + 然後把產生的檔案的設定資訊複製到 `firebase_compatible_options.dart` 中。 + +## 測試 + +在開始執行測試之前,你可以先把 mock 檔案準備好: + + make mock + +當想要開始測試,你可以: + + make test + +如果想要測試加上 coverage,你可以: + + make test-coverage + +最後產出的覆蓋率就可以打開以網頁格式打開: + + open coverage/html/index.html diff --git a/mkdocs.yaml b/mkdocs.yaml index 7f79c1c4..e68422a0 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -71,10 +71,10 @@ extra: property: G-P67FD9XP83 alternate: - name: English - link: /en/ + link: /flutter-pos-system/en/ lang: en - name: 繁體中文 - link: /zh/ + link: /flutter-pos-system/zh/ lang: zh plugins: