sdtk-kit 0.3.0 → 0.3.2

package/assets/toolkit/toolkit/templates/docs/api/API_DESIGN_CREATION_RULES.md

@@ -1,212 +1,16 @@
-# API Design Creation Rules for AI Agents (Excel Template)
+# API DESIGN CREATION RULES (Compatibility Note)
 
-This document defines reusable rules for creating API design documents in Excel format based on `Example/Docs/API/API_design.xlsx`.
+This file is kept only for backward compatibility.
 
-## 1. Scope and Goal
+Do not use this file as the primary source of truth anymore.
+The active rule source for API design detail and API flowchart behavior is now:
+- `API_DESIGN_FLOWCHART_CREATION_RULES_FINAL.md` (root)
+- `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md` (toolkit)
 
-- Reuse one consistent Excel structure for API contract documentation.
-- Keep flow, endpoint parameters, request schema, response schema, and revision history in one workbook.
-- Keep generated sheets deterministic and review-friendly.
-
-## 2. Source Template Baseline
-
-| No | Sheet Pattern | Purpose |
-| ---: | --- | --- |
-| 1 | `History` | Global workbook change history |
-| 2 | `API detail (...)` | One API per sheet |
-
-Observed baseline in `API_design.xlsx`:
-- 1 history sheet.
-- 5 API detail sheets (list/create/detail/update/logical delete).
-
-## 3. Workbook Rules
-
-### 3.1 Sheet Naming
-
-- Use one API per sheet.
-- Recommended naming style:
-  - `API detail (<domain action>)`
-- Keep API sheet order stable (for example: list -> create -> detail -> update -> delete).
-
-### 3.2 History Sheet
-
-- Keep `History` as the first sheet.
-- Header layout:
-  - `A3=Date`
-  - `C3=Version`
-  - `F3=Editor`
-  - `M3=Edit content`
-- Append rows only. Do not rewrite historical rows.
-
-## 4. API Detail Sheet Layout
-
-### 4.1 Header Metadata Block
-
-Use this label/value map:
-
-| No | Label Cell Group | Value Cell Group | Meaning |
-| ---: | --- | --- | --- |
-| 1 | `Q1:X1` | `Y1:AQ1` | System name |
-| 2 | `Q2:X2` | `Y2:AQ2` | System ID |
-| 3 | `Q3:X3` | `Y3:AQ3` | Subsystem name |
-| 4 | `Q4:X4` | `Y4:AQ4` | Function name |
-| 5 | `AR1:AV1` | `AW1:BC1` | Created by |
-| 6 | `AR2:AV2` | `AW2:BC2` | Created date |
-| 7 | `AR3:AV3` | `AW3:BC3` | Revised by |
-| 8 | `AR4:AV4` | `AW4:BC4` | Revised date |
-
-Also keep document title block:
-- `A1:P4` = document title area.
-
-### 4.2 Mandatory Section Order
-
-Each API sheet must keep this order:
-1. Process flow section
-2. `Parameters:`
-3. Request parameter section (JSON format)
-4. Success response section (JSON format)
-5. Error response section (JSON format)
-
-### 4.3 Endpoint Title Placement
-
-- Put endpoint summary at top flow area: `B7`.
-  - Format: `<METHOD> <PATH> <summary>`
-- Repeat the same endpoint summary in contract area:
-  - Column `A`, one row above `Parameters:`.
-- Both endpoint strings must be identical.
-
-### 4.4 Flowchart Placement
-
-- Put PlantUML text in `BG8` (multi-line content in one cell).
-- `BG6` can contain tool/reference note.
-- Helper + main flows can be placed in one cell value if clearly separated.
-- Flow syntax/content standards follow:
-  - `Example/Docs/API/FLOWCHART_CREATION_RULES.md`
-
-## 5. Endpoint and Parameter Rules
-
-### 5.1 Path Parameter Block
-
-- Anchor row: column `B` equals `Parameters:`.
-- Parameter rows:
-  - parameter key in column `C`
-  - description in column `K`
-- Include every path placeholder from endpoint path.
-- Keep parameter order aligned with placeholder order.
-
-### 5.2 Consistency Checks
-
-- Every `{placeholder}` in path must exist exactly once in the parameter rows.
-- Avoid duplicate parameter names unless explicitly documented.
-- Remove stale parameter rows after endpoint rename.
-
-## 6. Request/Response Table Rules
-
-### 6.1 Common Column Model
-
-| No | Column Group | Meaning |
-| ---: | --- | --- |
-| 1 | `A:B` | Row No |
-| 2 | `C:J` | Item label |
-| 3 | `K:N` | Hierarchy level 1 |
-| 4 | `O:R` | Hierarchy level 2 |
-| 5 | `S:V` | Hierarchy level 3 |
-| 6 | `W:Z` | Hierarchy level 4 |
-| 7 | `AA:AD` | Hierarchy level 5 |
-| 8 | `AE:AH` | Hierarchy level 6 |
-| 9 | `AI:AK` | Data type |
-
-### 6.2 Request Header Mode
-
-For write/search request tables, include:
-- `No`
-- `Item Name`
-- `Item`
-- `Type`
-- `Format`
-- `Length`
-- `Required`
-
-Column groups:
-- `AL:AN` -> `Format`
-- `AO:AP` -> `Length`
-- `AQ:AR` -> `Required`
-
-### 6.3 Response Header Mode
-
-For response tables, include:
-- `No`
-- `Item Name`
-- `Item`
-- `Type`
-- `Note`
-
-Column group:
-- `AL:AN` -> `Note`
-
-### 6.4 GET Request Body Rule
-
-- If API has no JSON request body, set request body to:
-  - `None`
-
-### 6.5 Hierarchy Modeling Rule
-
-- Use hierarchy columns (level 1 to level 6) to represent nesting.
-- Represent root wrapper explicitly (for example `data`).
-- For array object children, define parent array node first, then child fields at deeper levels.
-
-## 7. Status and Error Contract Rules
-
-- Success response must include `status` at minimum.
-- Error response must include:
-  - `status`
-  - `data` (message or detail payload)
-- If status detail references an external code table, note that in response notes.
-
-## 8. Type and Format Rules
-
-- Use stable type keywords:
-  - `string`
-  - `integer`
-  - `number`
-  - `object`
-  - `array`
-- If datetime format is constrained, write it in `Format` or `Note` (for example `yyyymmddHHMMSS`).
-- Business constraints (constant flags, nullable behavior, etc.) go to `Note`.
-
-## 9. Recommended Generation Procedure
-
-1. Duplicate an existing API detail sheet.
-2. Update metadata fields (`Q..BC` blocks).
-3. Update endpoint title in `B7`.
-4. Update PlantUML in `BG8`.
-5. Update repeated endpoint title above `Parameters:`.
-6. Update path parameters (`C/K` rows).
-7. Update request section:
-   - `None` for no-body APIs.
-   - request table for body APIs.
-8. Update success response table.
-9. Update error response table.
-10. Append one new row in `History`.
-
-## 10. Quality Gate Checklist Before Handoff
-
-- Section order is complete and unchanged.
-- Endpoint title in `B7` matches the endpoint title above `Parameters:`.
-- Path placeholders and parameter rows are 1:1 matched.
-- Request/response sections use correct header mode.
-- `No` is sequential in every table.
-- Hierarchy columns reflect actual payload nesting.
-- `status` and error payload structure are documented.
-- PlantUML in `BG8` matches endpoint behavior.
-- `History` has a new appended entry.
-
-## 11. Known Pitfalls and Prevention
-
-| No | Pitfall | Prevention Rule |
-| ---: | --- | --- |
-| 1 | Endpoint placeholder renamed but parameter rows not synced | Run path-vs-parameter check for every API sheet |
-| 2 | Request/response headers mixed (`Note` vs `Required`) | Use section-specific header mode only |
-| 3 | Nested array fields placed at wrong hierarchy level | Define parent array first, then child fields deeper |
-| 4 | Endpoint summary mismatch between top and contract blocks | Maintain a single canonical endpoint title string and reuse it |
+Use that file for:
+- API design detail markdown structure
+- flowchart integration and synchronization rules
+- error section rules
+- flow summary / notes / login rules
 
+This compatibility note should remain only until all references are migrated.

package/assets/toolkit/toolkit/templates/docs/api/API_DESIGN_DETAIL_TEMPLATE.md

@@ -55,8 +55,7 @@ stop
 ## 3. Generation Notes
 
 - This file should be generated/updated by skill `sdtk-api-design-spec`.
-- Rules source: `templates/docs/api/API_DESIGN_CREATION_RULES.md`.
+- Rules source: `templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md`.
 - Contract source:
   - `docs/api/{{FEATURE_PASCAL}}_API.yaml`
   - `docs/api/{{FEATURE_SNAKE}}_api_flow_list.txt`
-

package/assets/toolkit/toolkit/templates/docs/api/API_DESIGN_FLOWCHART_CREATION_RULES.md

@@ -0,0 +1,451 @@
+# API DESIGN + FLOWCHART CREATION RULES FINAL
+
+This file is the canonical rule set for:
+- API flow source (`*_api_flow_list.txt`)
+- PlantUML API flowcharts
+- API design detail markdown (`*_API_DESIGN_DETAIL.md`)
+
+Use `YAML_CREATION_RULES_FINAL.md` as the source of truth for endpoint contract design.
+
+The rules below include the 2026-03-03 flow-style refinements extracted from the Whiteboard API flowchart review.
+
+## 1. Final Review Result
+
+After the final pass on `docs/api/schedule_whiteboard_api_flow_list.txt`, there are no remaining critical style mismatches that should block reuse of the current flowchart-writing rules.
+
+Current state:
+- All API blocks use visible API header lines.
+- Search-like APIs use query-builder style.
+- CRUD/detail APIs no longer overuse search-style `fullQuery` construction.
+- Batch create uses batch-create style instead of search-style query-builder.
+- `api_design_detail.md` has been regenerated and is aligned with the current flow source.
+
+Accepted low-priority exceptions:
+- `POST /file-manager/env/{company_uuid}` uses pseudo `UPSERT` wording. This is acceptable because it is a shared upsert-style API, not a search API.
+- `GET /api/whiteboard/assignment/{company_uuid}/{sagyo_assign_uuid}` still uses a fixed `query = ...` + `LEFT JOIN ...` style. This is intentional and acceptable for a fixed-detail API.
+
+## 2. Source of Extracted Rules
+
+These rules were extracted by comparing:
+- `docs/api/schedule_whiteboard_api_flow_list.txt`
+- `docs/api/api_design_detail.md`
+- `Example/Docs/API/bukken-api-flowchart-list.txt`
+
+Primary sample references:
+- `POST /bukken/{company_uuid}` style
+- `POST /bukken/edit/{company_uuid}/{bukken_uuid}` style
+- `POST /bukken/delete-parmanent/{company_uuid}/{bukken_uuid}` style
+- `GET /bukken/info/{company_uuid}/{bukken_uuid}` style
+- search API query-builder style shown in the Bukken sample helper flow
+
+## 3. Core Flowchart Writing Rules
+
+### Rule A. Add a visible API header for every block
+
+Every API block must start with a visible API header line, for example:
+
+```text
+API: <METHOD> <PATH>  <Short Title>
+```
+
+Project-specific variants such as `笆API:` are acceptable only when encoding is stable.
+
+Reason:
+- Matches the sample style.
+- Makes raw flow-list files scannable before rendering.
+- Reduces ambiguity when one file contains many APIs.
+
+### Rule B. Use one `@startuml` block per API when generator mapping depends on block count
+
+If the markdown/API-design generator maps flow blocks to API endpoints by block count/order:
+- keep exactly one main `@startuml ... @enduml` block per API
+- do not split helper flows into extra standalone blocks unless the generator is updated accordingly
+
+Reason:
+- Avoids breaking flow-to-endpoint mapping in generated `*_API_DESIGN_DETAIL.md`.
+
+### Rule C. Flow style must match API type
+
+Do not use one style for every API.
+Choose the flow style based on the API purpose:
+
+1. Search/List/Lookup APIs
+- Use query-builder style.
+
+2. Create APIs
+- Use CRUD create style.
+
+3. Edit APIs
+- Use CRUD update style.
+
+4. Delete APIs
+- Use CRUD delete style.
+
+5. Detail APIs
+- Use fixed-record read style.
+
+6. Batch create APIs
+- Use batch-create style with loop.
+
+Reason:
+- This is the main difference between the sample Bukken flowchart style and the over-generalized Whiteboard draft.
+
+## 4. Search / List API Rules
+
+Applies to:
+- assignment search APIs
+- reserve employee/customer-employee search APIs
+- duplicate-check / lookup APIs that are effectively query-based
+- shared env lookup APIs when they dynamically build lookup conditions
+
+### Rule D. Search APIs should use query-builder style
+
+Preferred structure:
+
+```text
+:Create search query and condition statement from request.data.info;
+:query = "SELECT ... FROM ...";
+:query += " LEFT JOIN ...";
+:condition = "WHERE ...";
+...
+:order_by = "ORDER BY ...";
+:Compose full query:\nfullQuery = query + " " + condition;
+:Add order_by into fullQuery;
+:Execute fullQuery and get data;
+:Close DB connection;
+:Create api response;
+```
+
+### Rule E. Use uppercase table/column names inside pseudo-SQL
+
+Inside SQL-like action text:
+- use uppercase table names
+- use uppercase column names where practical
+
+Good:
+- `CLD_DAT_BUKKEN_INFO`
+- `CLD_DAT_BUKKEN_SAGYO_ASSIGN_INFO`
+
+Avoid:
+- lowercase-only SQL object names in pseudo-SQL lines
+
+Reason:
+- Matches the sample style and improves visual separation between logic text and table identifiers.
+
+### Rule E-1. Do not use fake helper-function wording unless a helper flow is defined
+
+Do not write:
+- `Call search_logic_function(parameters)`
+- `Execute search_logic_function(parameters)`
+
+unless the flow source also contains a real helper sub-flow block that defines that function logic.
+
+If the helper is not actually defined in the same source:
+- write the processing step directly inline
+
+Good:
+- `Create search query and condition statement from request.data.info;`
+- `Create duplicate check query and condition statement from request.data.info;`
+
+Reason:
+- Avoids implying a reusable sub-flow that does not exist.
+- Keeps the flow self-contained and accurate.
+
+### Rule F. Dynamic array filters should use object-based wording
+
+For array filters, use the sample-like loop style:
+
+```text
+if (data.info.department_uuids not null && data.info.department_uuids not empty) then (yes)
+  :condition += " AND ( 1 != 1 ";
+  repeat
+    :Get departmentObject from data.info.department_uuids;
+    :condition += " OR E.DEPARTMENT_UUID = <departmentObject.uuid>";
+  repeat while (more value data?) is (yes)
+  ->no;
+  :condition += " )";
+else (no)
+endif
+```
+
+Do not use overly simplified wording like:
+- `Add department filter`
+
+Reason:
+- The sample explicitly shows how OR-group conditions are built.
+
+### Rule G. Search APIs should not describe response shaping internals
+
+Avoid lines such as:
+- `Compute duplicate_assign ...`
+- `Group data into ...`
+- `Return data.xxx[]`
+- `Aggregate created_count ...` (for non-batch search flows)
+
+Instead end the flow at:
+- query completed
+- DB connection closed
+- API response created
+
+Reason:
+- The response structure is already defined in YAML.
+- Flowchart should focus on processing logic, not renderer-side or response-object assembly internals.
+
+### Rule H. Explicit `ORDER BY` is required when output order matters
+
+If the endpoint contract depends on a specific order:
+- define `order_by = "ORDER BY ..."`
+- then add it into `fullQuery`
+
+Do not leave ordering implicit.
+
+## 5. Create API Rules
+
+Applies to:
+- single create APIs
+
+### Rule I. Create APIs should use `Insert into ... with parameter value`
+
+Preferred style:
+
+```text
+:Insert into CLD_DAT_XXX with parameter value
+field_a = param.data.info.field_a
+field_b = param.data.info.field_b
+create_dt = now;
+:GET inserted_xxx_uuid = XXX_UUID value when Insert into CLD_DAT_XXX;
+:Close DB connection;
+:Create api response;
+```
+
+### Rule J. Do not over-describe query-builder logic inside create flows
+
+Avoid using:
+- `query = "SELECT 1 ..."`
+- `condition = ...`
+- `Compose full query ...`
+
+inside normal create flows.
+
+If duplicate/business validation is needed:
+- describe it as a business step only
+
+Example:
+- `Check overlap conflicts with current parameter value;`
+
+Reason:
+- This matches the sample create style and keeps flow readable.
+
+## 6. Edit API Rules
+
+Applies to:
+- update APIs
+
+### Rule K. Edit APIs should follow `Select existing -> Update with parameter value`
+
+Preferred structure:
+
+```text
+:Get target_uuid from endpoint;
+:Select from CLD_DAT_XXX with target_uuid and del_flg = 0;
+if (record exists) then (yes)
+else (no)
+  :Return error status = 140 ...;
+  stop
+endif
+:Check business rule if needed;
+:Update CLD_DAT_XXX with parameter value
+field_a = param.data.info.field_a
+field_b = param.data.info.field_b
+update_dt = now
+where target_uuid = target_uuid;
+:Close DB connection;
+:Create api response;
+```
+
+### Rule L. Keep business checks short inside edit flows
+
+If edit has duplicate overlap or other business validation:
+- keep it as one business step
+- do not expand it into a full search-style query-builder
+
+Good:
+- `Check overlap conflicts excluding current xxx_uuid;`
+
+Avoid:
+- full `query/condition/fullQuery` sequence inside edit flow
+
+## 7. Delete API Rules
+
+Applies to:
+- logical delete
+- physical delete
+
+### Rule M. Delete APIs should follow `Select existing -> Delete/Update -> Close -> Response`
+
+Preferred structure:
+
+```text
+:Get target_uuid from endpoint;
+:Select from CLD_DAT_XXX with target_uuid and del_flg = 0;
+if (record exists) then (yes)
+else (no)
+  :Return error status = 140 ...;
+  stop
+endif
+:Update CLD_DAT_XXX with parameter value
+del_flg = 1,
+update_dt = now
+where target_uuid = target_uuid;
+:Close DB connection;
+:Create api response;
+```
+
+If the API is truly permanent delete:
+- use `Delete ... with key is ...`
+
+Rule:
+- style may mirror permanent-delete sample
+- but business semantics must still match the actual API contract
+
+## 8. Detail API Rules
+
+Applies to:
+- read-one / detail APIs
+
+### Rule N. Detail APIs may use a fixed query, but not search-style dynamic query-builder
+
+Allowed:
+
+```text
+:Get target_uuid from endpoint;
+:query = "SELECT ... FROM CLD_DAT_XXX WHERE TARGET_UUID = target_uuid";
+:query += " LEFT JOIN ...";
+:Execute query and get data;
+if (record exists) then (yes)
+...
+:Close DB connection;
+:Create api response;
+```
+
+Avoid:
+- `condition = ...`
+- `Compose full query ...`
+- dynamic filter loops
+
+Reason:
+- Detail APIs are fixed-record lookups, not flexible searches.
+
+## 9. Batch Create API Rules
+
+Applies to:
+- APIs that create multiple records in one request
+
+### Rule O. Batch create APIs should use create-style logic with a loop
+
+Preferred structure:
+
+```text
+:Create target date list ...;
+...
+repeat
+  :Build per-item datetime/value;
+  :Check business conflict with current target date parameter value;
+  if (duplicate and skip = false) then (yes)
+    :Append skipped result ...;
+  else (no)
+    :Insert into CLD_DAT_XXX with parameter value
+    ...
+    :GET inserted_xxx_uuid = XXX_UUID value when Insert into CLD_DAT_XXX;
+    :Append created result ...;
+  endif
+repeat while (has next target item?) is (yes)
+:Build batch result list and summary counts;
+:Close DB connection;
+:Create api response;
+```
+
+### Rule P. Do not use search-style query-builder in batch-create loops
+
+Avoid inside the loop:
+- `query = "SELECT 1 ..."`
+- `condition = ...`
+- `Compose full query ...`
+
+Even when duplicate validation exists, batch create should still read like a create flow with looped business validation.
+
+## 10. Shared System API Rules
+
+Applies to:
+- APIs reused from another module but documented in feature flowchart
+
+### Rule Q. Shared lookup APIs may still use query-builder style if they behave like lookup/search
+
+Example:
+- environment lookup APIs that build conditions from request array items
+
+Allowed:
+- `query = ...`
+- `condition = ...`
+- `Compose full query ...`
+
+### Rule R. Shared upsert APIs should use action-oriented wording, not search wording
+
+Example:
+
+```text
+:Create Environment Manager upsert statement from request.data;
+:query = "UPSERT CLD_DAT_ENV_INFO";
+:Resolve target row by ...;
+:Set VALUE / NUMVALUE ...;
+:Execute upsert statement;
+:Close DB connection;
+:Create api response;
+```
+
+Reason:
+- Keeps style aligned with operation type.
+
+## 11. Error / Connection / Ending Rules
+
+### Rule S. Keep auth and validation at the top
+
+Use the common pattern:
+- authentication
+- permission
+- validation
+- business processing
+- DB close
+- response
+
+### Rule T. `Close DB connection;` should be near the end of the main flow
+
+Preferred:
+- after DB processing finishes
+- before `Create api response;`
+
+Avoid:
+- excessive `Close DB connection;` inside every inner loop branch unless the logic truly requires separate connections
+
+### Rule U. End with `Create api response;`
+
+Use a simple terminal response action.
+
+Do not over-specify:
+- HTTP 200
+- response JSON object construction
+- field-by-field response shaping
+
+unless there is a concrete reason the sample style requires it.
+
+## 12. Non-Flow Logic That Should Stay Out of the Flowchart
+
+Do not put these into the flow unless they are the core processing logic:
+- FE-only rendering logic
+- detailed response nesting assembly
+- UI display-specific transformations already described by YAML schema
+
+Reason:
+- Flowchart should describe processing logic.
+- YAML and endpoint docs already define the response contract.
+

package/assets/toolkit/toolkit/templates/docs/api/API_ENDPOINTS_TEMPLATE.md

@@ -63,7 +63,7 @@ Current version: `v1` (confirm final path policy in BA/ARCH decisions).
 - DateTime: `YYYY-MM-DDTHH:mm:ss` (or timezone-aware per project decision)
 
 ### 1.5 Endpoint Naming Convention
-- Apply `FLOWCHART_CREATION_RULES.md` (API endpoint design + governance rules).
+- Apply `YAML_CREATION_RULES.md` for API contract rules and `API_DESIGN_FLOWCHART_CREATION_RULES.md` for flow/depth alignment.
 - Keep resource naming and method policy consistent across all sections.
 
 ---