sdtk-kit 0.3.0

package/assets/toolkit/toolkit/skills/sdtk-api-design-spec/references/FLOWCHART_CREATION_RULES.md

@@ -0,0 +1,397 @@
+# Flowchart Creation Rules for AI Agents (PlantUML)
+
+This document defines reusable rules for creating and updating API flowcharts in this project.
+Target files are usually API flow list documents (for example `*_api.txt`) and API YAML files (for example `docs/api/*.yaml`).
+
+## 1. Scope and Goal
+
+- Use PlantUML activity diagrams for API process flows.
+- Keep diagrams readable, implementation-aware, and consistent with current backend logic.
+- Prefer minimal-impact documentation changes when existing customer logic is already running.
+
+## 2. File and Diagram Structure
+
+- One API flow = one `@startuml ... @enduml` block.
+- If helper logic is extracted, add a separate `@startuml ... @enduml` block for that helper.
+- Keep API title in `partition`:
+  - `partition "POST  **/api/path/{company_uuid}**  Japanese summary" { ... }`
+- Optional helper flow style:
+  - `rectangle "Logic function name" { ... }`
+
+## 3. Mandatory Activity Syntax Rules
+
+- Every action line must end with `;`
+- Every `if (...) then (...)` must be closed by `endif`
+- Use `else (no)` and `then (yes)` labels explicitly for branch readability.
+- Use `repeat ... repeat while ...` only when loop behavior is required.
+
+## 4. Color/Highlight Rules (Non-deprecated)
+
+Use stereotype-based color syntax (new style), not old prefix style.
+
+- Correct:
+  - `:Return Error status = 100: Parameter invalid;<<#pink>>`
+  - `:Call query_search_by_keyword() function;<<#lightGreen>>`
+- Avoid deprecated old style:
+  - `#pink:...`
+  - `#lightGreen:...`
+
+## 5. Standard API Flow Skeleton
+
+```plantuml
+@startuml
+partition "POST  **/sample/path/{company_uuid}**  API summary" {
+  start
+  :Process authentication\\nCommon auth process;
+  :Validate parameter;
+  if (is valid) then (no)
+    :Return Error status = 100: Parameter invalid;<<#pink>>
+    stop
+  else (yes)
+  endif
+  :Main process;
+  :Close DB connection;
+  :Create api response;
+  stop
+}
+@enduml
+```
+
+## 6. Query-Building Style Rules
+
+When describing SQL-like logic in flowchart:
+
+- Build query in steps:
+  1. `Create search query and condition statement from request.data;`
+  2. `query = "...";`
+  3. `condition = "...";`
+  4. optional condition append blocks
+  5. `Compose full query: fullQuery = query + condition;`
+  6. apply order/paging
+  7. execute query
+
+- Keyword pattern:
+  - `LIKE '%data.info.keyword%'`
+- Order pattern:
+  - `Add order by data.info.order_flg data.info.order_type into fullQuery;`
+- Paging pattern:
+  - `Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;`
+
+### 6.1 Endpoint-level Mapping Must Be Explicit
+
+For keyword/order enhancements, always document mapping between request params and DB columns per endpoint.
+
+- `keyword` must list all searchable columns/tables.
+- `order_flg` must list allowed sort targets and mapped columns.
+- `order_type` must be documented as `asc/desc`.
+- If payload includes new fields that are not handled by current legacy code,
+  add explicit processing logic for those new fields in the helper flow.
+  Do not silently ignore newly introduced request fields.
+
+Example (`/bukken-manager/regno/customer/search/{company_uuid}`):
+- `keyword`:
+  - `CLD_DAT_CUSTOMER_REG_NO_INFO.customer_reg_no`
+  - `CLD_MST_LOCATION_INFO.location_name`
+  - `CLD_MST_REG_NO_TYPE_INFO.name`
+- `order_flg`:
+  - `customer_reg_no` / `location_name` / `name`
+- `order_type`:
+  - `asc` / `desc`
+
+## 7. Backward-Compatible Merge Pattern
+
+When new requirements are added to an existing API:
+
+- Keep current handler path for old request behavior.
+- Add conditional branch for new logic only when required params exist.
+- Recommended branch style:
+  - If all new params are null -> keep old logic
+  - Else -> call extracted helper function
+- Use this exact "no-impact first" branch when preserving customer legacy handlers:
+  - `if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)`
+  - `:Keep the current search logic handler: <existing_handler>();`
+  - `else (no)` -> call helper for new query logic
+- In the legacy branch, do not duplicate old internal sub-steps unless explicitly requested.
+  - Avoid extra lines like mapping/query detail when they are already part of existing handler behavior.
+  - Prefer one concise line:
+    - `:Keep the current search logic handler: <existing_handler>();`
+
+Example:
+
+```plantuml
+if (data.info.keyword null and data.info.order_flg null and data.info.order_type null) then (yes)
+  :Keep the current search logic handler: regno_search();
+else (no)
+  :Call query_search_by_keyword() function;<<#lightGreen>>
+endif
+```
+
+## 8. Helper Function Diagram Pattern
+
+```plantuml
+@startuml
+rectangle "Logic query search by keyword" {
+  :query_search_by_keyword();<<#lightGreen>>
+  :Create search query and condition statement from request.data;
+  :query = "...";
+  :condition = "...";
+  if (data.info.keyword not null) then (yes)
+    :condition += "...";
+  else (no)
+  endif
+  :Compose full query:\\nfullQuery = query + condition;
+  :Add order by data.info.order_flg data.info.order_type into fullQuery;
+  :Add "LIMIT = data.info.limit OFFSET = data.info.offset" into fullQuery;
+  :Execute fullQuery and get data;
+  :return return_datas;
+}
+@enduml
+```
+
+### 8.1 Helper Naming Rule
+
+- Use helper names that include endpoint domain to avoid collisions across many APIs.
+- Recommended:
+  - `query_search_by_keyword()` for generic case
+  - `query_search_by_keyword_customer_regno()` for customer-regno endpoint
+
+### 8.2 Legacy Fallback Rule (Search APIs)
+
+- When modernizing an existing search endpoint, explicitly describe legacy fallback behavior:
+  - soft-delete flag fallback from existing code path (if any)
+  - default order fallback when `order_flg/order_type` is absent
+  - default filters applied when optional inputs are null
+- Keep these fallback notes visible in flowchart text to avoid behavior drift.
+
+### 8.3 Extended Filter Branch/Response Rule
+
+- If new optional filter fields are added, include all of them in the no-impact branch check.
+- When relation-based filters are used, explicitly show join/filter logic in helper flow.
+- If response contains multiple typed lists, keep each list explicit in flowchart/YAML (for example `data.<entity>_info[]`) and include summary metadata such as `count` when applicable.
+
+## 9. Path Canonicalization Rule
+
+- If YAML path and actual route path are different, use the confirmed actual route path in flowchart.
+- Always prioritize route path defined in backend code (`urls.py`) over YAML documentation.
+- If route path cannot be found in code, fallback to YAML path and mark it as assumed/temporary.
+- Always confirm this with user before finalizing.
+
+## 9A. API Endpoint Design Rules (Project Standard)
+
+These rules must be applied when creating/updating API flowcharts and YAML in this project.
+
+- Use singular object keyword in endpoint path:
+  - Correct: `/invoice`, `/assignment`, `/personal-schedule`
+  - Avoid: `/invoices`, `/assignments`
+- Use canonical business-domain keywords from glossary/spec terminology.
+- Avoid ambiguous aliases when official domain terms exist.
+- Use action keywords that describe behavior clearly:
+  - List: `.../list/...`
+  - Update: `.../edit/...`
+  - Delete: `.../delete/...`
+  - Multi-create: `.../multi-create`
+  - Avoid vague action keyword `bulk` when behavior is multi-create.
+
+### 9A.1 Endpoint Pattern
+
+- List API:
+  - `GET /{object}/list/{company_uuid}/{bukken_uuid}`
+- Create API:
+  - `POST /{object}/{company_uuid}/{bukken_uuid}`
+- Edit API:
+  - `POST /{object}/edit/{company_uuid}/{object_uuid}`
+- Detail API:
+  - `GET /{object}/edit/{company_uuid}/{object_uuid}`
+- Delete API:
+  - `POST /{object}/delete/{company_uuid}/{object_uuid}`
+
+### 9A.2 HTTP Method Policy
+
+- Do not use `PUT` for update APIs. Use `POST .../edit/{uuid}`.
+- Do not use `DELETE` method for delete APIs. Use `POST .../delete/{uuid}`.
+
+### 9A.3 Canonical Examples
+
+- Invoice sample:
+  - `GET /invoice/list/{company_uuid}/{bukken_uuid}`
+  - `POST /invoice/{company_uuid}/{bukken_uuid}`
+  - `POST /invoice/edit/{company_uuid}/{invoice_uuid}`
+  - `GET /invoice/edit/{company_uuid}/{invoice_uuid}`
+  - `POST /invoice/delete/{company_uuid}/{bukken_uuid}`
+
+## 9B. General Design and Documentation Governance Rules
+
+Apply the rules below as cross-project standards for API YAML and flowchart generation.
+These rules complement section `9A` (path syntax + method policy) and avoid redefining it.
+
+### 9B.1 Rule Precedence and Consistency
+
+- Endpoint naming/method conventions must follow section `9A`.
+- If a feature needs an exception from `9A`, document the reason and get explicit confirmation before finalizing.
+- Keep terminology consistent across path, request/response schema, flowchart labels, and API summary tables.
+
+### 9B.2 Parameter Placement Rule
+
+- Path parameters: identity and routing keys (`{company_uuid}`, `{resource_uuid}`).
+- Query parameters: lightweight filtering/sorting/paging.
+- Request body: complex/multi-field search criteria.
+- If retrieval requires many filter fields, prefer dedicated `POST .../search` over overloaded query strings.
+
+### 9B.3 Read Contract Shape Rule (List vs Search)
+
+- Use list-style read API for simple retrieval contracts.
+- Use search-style read API when filter logic is complex or payload-based.
+- If one endpoint forces heavy client-side matching/filtering for different screen modes, split read endpoints by view purpose.
+
+### 9B.4 Endpoint Split vs Merge Decision Rule
+
+- Split endpoints when:
+  - view/use-case shaping is materially different
+  - one endpoint causes excessive client orchestration
+- Merge endpoints/datasets when:
+  - data is always consumed together under the same filter context
+  - separate endpoints only add latency and maintenance cost
+- Record split/merge rationale in API description and flowchart notes.
+
+### 9B.5 Reuse vs New Endpoint Rule
+
+- Reuse existing endpoints only when request/response contract is truly compatible with target screen logic.
+- If existing API is semantically close but contract-incompatible, create a bounded new endpoint for that use case.
+- Mark endpoint lifecycle in docs via `API Type` classification (see `9B.8`).
+
+### 9B.6 Namespace and Path Redundancy Rule
+
+- Separate namespaces by bounded context/domain.
+- Avoid repeating parent namespace meaning in child path segments.
+- Keep paths concise but semantically clear.
+
+### 9B.7 Screen-to-API Traceability Rule
+
+- Every UI flow/action section must map:
+  - trigger/action
+  - called API
+  - response fields used for rendering
+- Explicitly mark when a single endpoint serves multiple actions (initial load, search, refresh, etc.).
+
+### 9B.8 API List Governance Rule (Markdown Specs)
+
+- API summary tables must include at least:
+  - `No`
+  - `Method`
+  - `Endpoint`
+  - `API Type`
+  - `Description`
+- Group APIs by delivery status for planning visibility:
+  1. `New`
+  2. `Deferred`
+  3. `Existing (reuse)`
+- After regrouping, renumber `No` sequentially.
+
+### 9B.9 Change Management Rule
+
+- For every endpoint rename/add/remove/merge:
+  - update endpoint detail sections
+  - update API summary tables
+  - update screen-to-API mapping
+  - append a new row in document history
+- Preserve old history rows; never rewrite historical entries.
+
+### 9B.10 Canonical Response Envelope Rule
+
+- Use one canonical response envelope across a bounded module/feature.
+- Keep the envelope shape consistent in YAML examples, flowchart return nodes, and markdown endpoint tables.
+- Recommended normalized envelope keys:
+  - `status`
+  - `msg`
+  - `data`
+  - `format_version`
+- If a legacy API has a different wrapper, document it explicitly as an exception.
+
+### 9B.11 Business Status Rule
+
+- Business execution result must be represented in response body `status` (not only by HTTP code).
+- Flowchart branches must map to business status outcomes, including validation and duplicate/conflict-like results.
+- Document endpoint-level status code matrix in API docs when branching is non-trivial.
+- HTTP status policy can vary by system profile, but body `status` must remain deterministic.
+
+### 9B.12 Request Body Wrapper Rule
+
+- For write/search APIs that use POST payloads, prefer a stable top-level wrapper object:
+  - `data: { ... }`
+- Keep filter/search fields under `data` when criteria are complex or nested.
+- If legacy contracts do not use wrapper objects, document exception and compatibility reason.
+
+### 9B.13 Traceability Metadata Rule
+
+- YAML should include explicit traceability metadata for each endpoint (for example `x-traceability`).
+- Minimum mapping targets:
+  - BR (business rule)
+  - UC (use case)
+  - AC (acceptance criteria)
+- Flow list and markdown API docs should preserve the same mapping IDs to keep cross-artifact traceability.
+
+### 9B.14 Language and Encoding Governance
+
+- EN artifact set must use English narrative consistently.
+- Save generated markdown/YAML as UTF-8 and remove mojibake/corrupted characters before handoff.
+- If source input is VI/JP, keep original text only in dedicated appendix/quotation blocks when needed for traceability.
+
+### 9B.15 Abbreviations and Table Numbering Governance
+
+- For generated markdown specs, include an `Abbreviations` section near the top when acronyms are used.
+- Apply `No` column and sequential renumbering policy by following section `9B.8`.
+
+## 9C. Project Profile Overlay Rule (Cross-Project Reuse)
+
+- Separate reusable core rules from system-specific constraints.
+- Keep system-specific choices in a project profile layer, for example:
+  - fixed HTTP policy patterns
+  - datetime timezone/local-naive policy
+  - method conventions such as POST-based edit/delete
+- When reusing these rules for a new system, adopt core rules first, then explicitly decide profile overrides.
+- Do not silently promote one system profile as global default for all projects.
+
+## 10. Wording Rules
+
+- Use concrete action verbs:
+  - `Select ...`
+  - `Update ...`
+  - `Insert ...`
+  - `Create api response;`
+- For existing behavior preservation, use explicit wording:
+  - `Keep the current search logic handler: <function>();`
+- Do not add redundant response details if globally standardized.
+  - Prefer `:Create api response;` over verbose wrappers.
+
+## 11. Error/Status Rules in Flow Text
+
+- Parameter validation error: usually `status = 100` (unless API-specific rule says otherwise).
+- Temporary unknown error code policy may use `status = 900` if already agreed.
+- Keep status usage consistent with confirmed project decisions.
+
+## 12. Common Preview Errors and Fixes
+
+- Error: `Cannot find group ... @enduml`
+  - Cause: missing `endif` or malformed action statement
+  - Fix: close all branches and ensure each action line ends with `;`
+
+- Warning: `This syntax is deprecated...`
+  - Cause: old color syntax (`#pink:...`, `#lightGreen:...`)
+  - Fix: move color marker to end of action:
+    - `:...;<<#pink>>`
+    - `:...;<<#lightGreen>>`
+
+## 13. Final Checklist Before Handoff
+
+- Diagram renders in PlantUML Preview without error.
+- No deprecated color syntax warnings.
+- All `if` blocks have matching `endif`.
+- New logic branch does not remove old logic path unless explicitly requested.
+- SQL condition/order/paging statements match agreed spec.
+- API path and method match the confirmed actual route (use YAML path only when they are identical).
+- Response envelope is consistent with module-level canonical contract.
+- Business `status` mapping is explicit in both YAML and flow branches.
+- POST search/write payload wrapper (`data`) is consistent (or exception documented).
+- Traceability links (BR/UC/AC) are present and consistent across artifacts.
+- EN/UTF-8 quality check passed (no mixed-language drift, no mojibake).
+