sdtk-kit 0.3.8 → 1.0.0

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/FLOW_ACTION_SPEC_CREATION_RULES.md

@@ -1,200 +0,0 @@
-# Flow Action Spec Creation Rules for AI Agents
-
-This document defines reusable rules for creating and updating screen flow-action specifications
-(for example `docs/specs/*_FLOW_ACTION_SPEC.md`).
-
-## 1. Scope and Goal
-
-- Produce a screen-level specification that is traceable from BA/ARCH to FE/BE implementation.
-- Keep one source of truth for:
-  - screen flow
-  - UI items and actions
-  - API calls per action
-  - screen-to-API mapping
-- Keep documentation implementation-aware and review-friendly.
-
-## 2. Mandatory Document Structure
-
-A flow-action spec should include, at minimum:
-
-1. `Abbreviations`
-2. `Feature overview`
-3. `Assumptions`
-4. `Screen flow action` (with PlantUML)
-5. `Screen layout spec by flow action`
-6. `System processing flow`
-7. `Open questions`
-8. `Screen - API mapping`
-9. `Document history`
-
-If a section is not in scope, keep the section and mark explicitly as `N/A` with reason.
-
-## 3. Table Standards
-
-- Every table must include a `No` column (sequential numbering).
-- Use stable headers for action tables:
-  - `No | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
-- Use stable headers for API mapping tables:
-  - `No | Trigger/When | UI item (No / Item Name) | API to call | Data usage / Notes`
-- Use stable headers for screen mapping:
-  - `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
-- Table rows must keep column count consistent with the header (no broken or merged rows).
-- Avoid single-line merged content that collapses multiple logical items into one table row.
-
-### 3.1 Action Table Mapping Completion Rules
-
-- After API endpoint spec and database spec are available, the action-table columns `Attribute`, `DB Column`, `Size`, and `Default Value` must not be left blank when the mapping can be derived from current source-of-truth inputs.
-- Fill these four columns only after the relevant API contract and DB schema are stable enough to be treated as the current source of truth for the active phase.
-- Source priority for filling the four columns:
-  1. `docs/api/*_ENDPOINTS.md` and OpenAPI YAML for request/response contract
-  2. `docs/database/DATABASE_SPEC_*.md` for physical column names, nullability, storage shape, and query-source aliases
-  3. confirmed flow/business rules for default state and behavior
-  4. design source (Figma/Excel) for screen label and control type only
-- `Attribute` rules:
-  - input item: use the canonical request payload path
-  - display item: use the canonical response path
-  - UI-only item: use `ui.*` namespace
-- `DB Column` rules:
-  - use physical DB column names or query-source aliases from the API/database spec
-  - if multiple columns participate, list them explicitly
-  - if the control is UI-only, write `N/A`
-- `Size` rules:
-  - document data format/type, not pixel width
-  - prefer canonical forms such as `uuid`, `DATE (YYYY-MM-DD)`, `DATETIME`, `TIME (HH:mm)`, `boolean`, `array[uuid]`, `enum(...)`, `JSON string`
-  - prefer DB storage type first; if not available, fall back to API schema type/format
-- `Default Value` rules:
-  - use confirmed business, UI, or runtime defaults
-  - if the default comes from settings or environment, state that clearly
-  - if not finalized, use `TBD` and keep or raise an open-question reference in `Note`
-- If screen labels conflict with canonical API/DB naming, preserve the original screen label in the visible screen columns, but keep `Attribute` and `DB Column` aligned to API/DB source of truth and explain the mismatch in `Note`.
-
-### 3.2 Language and Encoding Standards (EN Artifacts)
-
-- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
-- JP labels, if provided by the input, should be kept in a clearly marked appendix or note column, not in the default item table columns.
-- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
-- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
-- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
-- Keep canonical terminology stable across documents (for example: `bukken`, `sagyo`, `customer employee`).
-
-### 3.3 Markdown Structure Hygiene
-
-- Keep each heading on its own line; do not concatenate multiple headings/sections on one line.
-- Keep metadata blocks (`Information`, `Note`, `Behavior notes`) as structured bullet blocks, not single compressed lines.
-- Keep image, table, and separator (`---`) boundaries explicit to preserve parser/render stability.
-
-### 3.4 Assumptions Section
-
-- Every flow-action spec must include a top-level `## Assumptions` section.
-- Use this table format exactly: `# | Assumption | Verified | Risk if wrong`.
-- Keep assumptions explicit when downstream mapping or behavior depends on an unresolved decision.
-- If an assumption affects UI behavior, API mapping, or DB mapping, reflect the risk in `Note` and keep or raise the related `OQ-xx` item.
-
-## 4. Item Numbering and Duplication Rules
-
-- Use one numbering mode only: `global across document`.
-- Number values must increase across all action tables in the document.
-- Avoid duplicate item descriptions for the same UI control across screens unless behavior differs.
-- If duplicate number is intentional (rare), annotate reason in `Note`.
-
-## 5. Screen Section Rules
-
-For each screen section:
-
-- Provide metadata:
-  - official screen name
-  - Screen ID
-  - Design Source Type
-  - Design Source Reference
-- Embed one representative image per screen (from Figma, screenshot, or generated layout).
-- Provide one action table.
-- Provide one API mapping table.
-- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
-
-## 5.1 Design Source Modes
-
-Each screen section must declare a design source using one of these modes:
-
-| Mode | When | Design Source Reference |
-|------|------|----------------------|
-| `source-backed` | Figma URL or screenshot is available | Figma URL or screenshot path |
-| `generated-draft` | No Figma/screenshot, but feature has UI scope | Section reference in `docs/design/DESIGN_LAYOUT_[FEATURE_KEY].md` |
-| `none` | Feature has no UI scope for this screen | State `N/A - no UI scope` |
-
-Rules:
-- For UI-scope features, `none` is only valid when the specific screen truly has no visual layout.
-- When using `generated-draft`, the `DESIGN_LAYOUT_[FEATURE_KEY].md` must exist before the flow-action spec is finalized.
-- The flow-action spec and the design-layout doc must remain separate documents.
-- When Figma becomes available later, update the source mode from `generated-draft` to `source-backed`.
-
-## 6. API Traceability Rules
-
-- Every actionable UI event that changes state must map to a write API.
-- Every data-loading UI event must map to a read/search API.
-- If one endpoint serves multiple actions (initial load, search, refresh), state this explicitly.
-- If no API is called for an action, state `No API` and explain why.
-
-## 7. PlantUML Rules for Screen Flow
-
-- Use valid PlantUML syntax and renderability checks before handoff.
-- Use `\\n` for multi-line labels in nodes.
-- Keep diagram at navigation/action level (not low-level SQL or backend internals).
-- Ensure screen names in PlantUML match section names in layout spec.
-
-## 8. Data Source and Asset Rules
-
-- Prioritize source order:
-  1. Confirmed design source (for example Figma)
-  2. Confirmed requirement files (Excel/spec)
-  3. User-provided screenshots
-- Store images in repository-relative paths.
-- Do not keep temporary local absolute paths in markdown.
-
-### 8.1 Rendered Screen Images for Generated-Draft Screens
-
-When `Design Source Type` is `generated-draft`:
-- Screen preview images may be rendered from `DESIGN_LAYOUT_[FEATURE_KEY].md` PlantUML SALT wireframes.
-- Renderer: `toolkit/skills/sdtk-design-layout/scripts/render_design_layout_images.py`
-- Expected output path: `docs/specs/assets/<feature_snake>/screens/<screen_id>.svg`
-- If the rendered `.svg` file exists, use it as the `Screen image:` reference.
-- If rendering is unavailable or the `.svg` does not exist, replace the image line with:
-  `> Screen image not rendered in this environment. See Design Source Reference for layout.`
-- Do not leave a broken image reference pointing to a non-existent file.
-
-## 9. Consistency with Other Specs
-
-- Align terms with:
-  - BA spec glossary
-  - API endpoints spec
-  - Database spec
-- If terminology differs across docs, raise an open question and add a temporary mapping note.
-- Keep endpoint paths in flow-action spec consistent with API endpoint spec.
-
-## 10. Open Questions and Uncertainty Handling
-
-- Capture unresolved items in `Open questions` table.
-- Do not invent UI behavior or API contracts when source is ambiguous.
-- Mark uncertain mappings as `Draft` and include impacted files/sections.
-
-## 11. Change Management
-
-- On each update:
-  - update impacted screen sections
-  - update API mapping tables
-  - update screen-to-API mapping summary
-  - append one row in document history
-- Never overwrite past history rows.
-
-## 12. Final Checklist Before Handoff
-
-- PlantUML renders successfully.
-- All mandatory sections exist.
-- All tables include `No`.
-- Numbering is global across the document (no resets).
-- No broken image links (for `generated-draft` screens: `.svg` exists or render-skipped note is present).
-- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
-- Assumptions section exists and unresolved assumptions are traceable.
-- Open questions are explicit and traceable.
-- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
-- No mojibake/encoding corruption markers.
-- Headings/tables are structurally clean (no merged lines that break readability/traceability).

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/excel-image-export.md

@@ -1,51 +0,0 @@
-# Export anh tu Excel (sheet co hinh/shape) - tranh vo layout & loi anh trang
-
-## Khi nao can
-
-- Sheet `画面遷移` hoac `画面|...` chua hinh (picture/shape) thay vi text trong cell.
-- Can anh de embed vao markdown hoac overlay so.
-
-## Loi da gap & nguyen nhan
-
-1) `Chart.Export()` ra PNG trang (~1.3KB)
-- Nguyen nhan: Excel COM export chart/picture khong on dinh voi group/picture phuc tap.
-
-2) Sai duong dan thu muc anh khi SaveAs HTML
-- Excel tao folder anh theo quy uoc: `<basename>.files`
-- Vi du: `export.html` -> folder `export.files` (khong phai `export.html.files`).
-
-3) Excel COM crash / OLE error `0x800a01a8`
-- Nguyen nhan pho bien: goi `Quit()` nham instance Excel dang duoc attach boi COM (dac biet khi dung `Dispatch`).
-
-4) Marker 2 chu so bi mat digit (10 hien thi nhu 1)
-- Nguyen nhan: oval qua nho + wrap/align khong chuan.
-
-## Cach lam khuyen nghi (tu dong)
-
-Dung script trong repo, vi du:
-`Requirements/_generate_numbered_screen_images.py`
-
-Script nen dam bao:
-- Flatten group + SaveAs HTML de lay PNG that (tranh PNG trang).
-- Dung `DispatchEx` khi mo Excel rieng de overlay len PNG (tranh crash do Quit nham instance).
-- Tang size oval + tat WordWrap de hien thi du 2-3 chu so.
-- Su dung dung quy uoc `.files` folder khi export HTML.
-
-Chay (vi du, tai project root):
-```powershell
-python Requirements\_generate_numbered_screen_images.py
-```
-
-## Cach lam thu cong (fallback)
-
-1) Mo Excel -> chon vung UI can export (picture/group) -> Copy as Picture.
-2) Paste sang sheet trong hoac workbook moi.
-3) Save As -> "Web Page (*.htm; *.html)".
-4) Vao folder `<basename>.files` -> chon file `imageXXX.png` co kich thuoc phu hop nhat.
-5) Copy sang `docs/specs/assets/[feature_snake]/screens/` va dat ten theo convention.
-
-## Luu y khi script fail do ten Picture thay doi
-
-Neu script tham chieu theo `picture_name` (vd: `Picture 4`, `Picture 7`), khi Excel doi ten:
-- Mo Excel -> chon picture -> xem/doi ten trong Selection Pane, hoac
-- Cap nhat lai `picture_name` trong script.

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/figma-mcp.md

@@ -1,54 +0,0 @@
-# Figma MCP: lay layout/style/tokens + export anh
-
-## Parse URL Figma
-
-Mau URL:
-`https://www.figma.com/design/<fileKey>/<fileName>?node-id=<nodeId>&m=dev&t=...`
-
-- `fileKey` = segment sau `/design/`.
-- `nodeId`:
-  - query param `node-id=1-2695`
-  - chuyen sang format API: `1:2695` (thay `-` bang `:`).
-
-## Lay du lieu layout/style (uu tien)
-
-Dung MCP:
-- `mcp__figma__get_figma_data`
-  - Input: `fileKey`, `nodeId`
-  - Goi y: thu `depth=2` hoac `depth=3` (tang dan neu thieu thong tin).
-
-Khi tong hop vao `docs/specs/[FEATURE_KEY]_FIGMA_LAYOUT.md`, giu khung:
-- Design Structure: frame dimensions, components/instances, key layers, variants/properties.
-- Styling Data: color (Hex/RGB), typography (font/size/weight/line-height), shadow/opacity/border.
-- Layout Information: padding/gap/alignment, width/height, border radius.
-- Design Tokens: color/typography/spacing tokens neu co ten style (vd: `style_...`).
-
-## Rate-limit 429 / du lieu thieu
-
-Neu gap `429 Too Many Requests`:
-1) Giam `depth` va thu lai.
-2) Cho va retry (backoff 20s -> 40s -> 80s).
-3) Neu van fail: de trong cac muc khong lay duoc va ghi note ro ly do 429.
-
-Khong tu bịa mau/typography/token khi khong co du lieu.
-
-## Export anh man hinh
-
-Dung MCP:
-- `mcp__figma__download_figma_images`
-  - Input: `fileKey`, danh sach `nodes` (nodeId), `fileName` (png), `pngScale` (thuong 2).
-
-Luu y ve `localPath`:
-- Mot so moi truong chan duong dan tuyet doi.
-- Dung thu muc tuong doi trong repo (vd: `Requirements/_tmp/figma_downloads`) roi copy anh ve:
-  - `docs/specs/assets/[feature_snake]/screens/`
-
-## Quy uoc dat ten file anh
-
-Khuyen nghi dat ten on dinh de embed lau dai, vi du:
-- `screen_3_1_main.png`
-- `screen_3_2_search.png`
-- `screen_3_3_dialog.png`
-- `screen_3_3_dialog_numbered.png`
-
-Neu dung anh tu Excel thay the, van giu cung naming de tranh sua nhieu link trong markdown.

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/references/numbering-rules.md

@@ -1,76 +0,0 @@
-# Quy tắc đánh số UI item (Flow Action Spec)
-
-## Mục tiêu
-
-- Gắn số lên ảnh màn hình để người đọc map nhanh sang bảng action.
-- Đánh số **toàn cục**, tăng dần theo thứ tự màn hình trong flow.
-- **Không trùng số** giữa các item mới.
-- **Không lặp mô tả** item đã xuất hiện ở màn hình trước.
-
-## Quy ước “item đã xuất hiện”
-
-Xem item là “đã xuất hiện” nếu:
-- Cùng ý nghĩa chức năng và cùng vị trí/khu vực UI (dù ở chế độ view khác).
-- Đã được đánh số trong một màn hình trước đó.
-
-Hệ quả:
-- Màn hình sau **không thêm dòng mới** vào bảng action cho item này.
-- Nếu cần người đọc định vị, vẫn có thể giữ số trên ảnh (để đối chiếu), nhưng ghi chú trong section: “Đã mô tả ở màn X (No Y)”.
-
-## Cách làm chuẩn (không đoán khi thiếu dữ liệu)
-
-1) Xác định thứ tự màn hình trong flow (mặc định theo danh sách Figma + luồng `画面遷移`).
-2) Tạo “sổ tay đánh số” (mapping) dạng:
-   - `key` (tên/nhãn JP + loại control + khu vực)
-   - `value` (số No)
-3) Với từng màn hình:
-   - Liệt kê item tương tác cần mô tả (button/link/selectbox/checkbox…).
-   - Nếu item mới: cấp số tiếp theo và thêm vào mapping.
-   - Nếu item cũ: không cấp số mới, không lặp mô tả.
-4) Nếu **chưa xác định được vị trí đặt số trên ảnh**:
-   - Yêu cầu user cung cấp ảnh có đánh dấu hoặc chỉ rõ vị trí (tỷ lệ/tọa độ/ô Excel).
-   - Không tự suy đoán vị trí.
-
-## Nguồn dữ liệu tham khảo
-
-- Excel: sheet `画面|作業員割付` (bảng mô tả + cột BK thường chứa ký hiệu số tròn ㉕/㉖…)
-  - Ví dụ:
-    - `BK205`: `㉕リスト表示切替ボタン`
-    - `BK245`: `㉖マグネット表示切替ボタン`
-- Ảnh/screenshot đã được user đánh số (nguồn xác thực tốt nhất).
-- Ảnh export từ Figma/Excel để overlay số.
-
-## Case lỗi đã gặp & cách tránh
-
-### 1) Trùng số “1” trong màn Search / Edit
-
-Nguyên nhân thường gặp:
-- Overlay tool chỉ đọc được “1” khi marker là 2 chữ số (10,11,12…).
-
-Cách tránh:
-- Khi tạo marker (oval) cho 2+ chữ số, tăng kích thước tối thiểu (>= 32px) và tắt WordWrap.
-- Nếu lấy marker từ Excel, đảm bảo marker trong Excel hiển thị đúng 2 chữ số trước khi export.
-
-### 2) Excel spec bị “duplicate numbering” (ví dụ ㉑ xuất hiện 2 lần)
-
-Nguyên nhân:
-- Dữ liệu Excel gốc bị trùng ký hiệu số.
-
-Cách xử lý:
-- Ưu tiên theo logic UI + screenshot user xác nhận.
-- Renumber phần bị duplicate theo số tiếp theo (vd: 21 bị trùng → “đóng/xoá/search” thành 22/23/24 theo thứ tự thao tác).
-- Ghi chú rõ “Excel có duplicate; đã chuẩn hoá lại theo sequence toàn cục”.
-
-### 3) Item đã mô tả ở màn trước vẫn bị lặp trong bảng màn sau
-
-Cách tránh:
-- Trước khi thêm dòng vào bảng, đối chiếu mapping toàn cục.
-- Nếu cần nhắc lại, chỉ thêm bullet note “đã mô tả ở …”, không thêm dòng mới trong bảng.
-
-## Ví dụ theo dự án tham chiếu
-
-- Màn 3.1 (Bukken View): đã đánh số 1–9.
-- Màn 3.2 (Search): tiếp tục 10–24.
-- Màn 3.3 (Bukken Magnet): chỉ đánh số 25 cho nút chuyển List.
-- Màn 3.4 (Bukken List): chỉ đánh số 26 cho nút chuyển Magnet.
-- Màn 3.7 (Worker Magnet): chỉ đánh số các item mới theo yêu cầu (vd: selectbox 物件名, nút 検索, checkbox 複数日登録モード).

package/assets/toolkit/toolkit/skills/sdtk-screen-design-spec/scripts/renumber_flow_action_spec_global.py

@@ -1,136 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-
-TABLE_ROW_RE = re.compile(r"^\|.*\|\s*$")
-TABLE_SEP_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|\s*$")
-
-
-def _split_table_row(line: str) -> list[str]:
-    return [p.strip() for p in line.strip().strip("|").split("|")]
-
-
-def _read_text(path: Path) -> tuple[str, str]:
-    for enc in ("utf-8-sig", "utf-8", "cp1252"):
-        try:
-            return path.read_text(encoding=enc), enc
-        except UnicodeDecodeError:
-            continue
-    return path.read_text(errors="replace"), "utf-8"
-
-
-def _make_row(cells: list[str]) -> str:
-    return "| " + " | ".join(cells) + " |"
-
-
-def renumber_action_tables(md_text: str) -> tuple[str, int, int]:
-    lines = md_text.splitlines()
-    out = lines[:]
-
-    expected_no = 1
-    touched = 0
-    rows = 0
-
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-        if i + 1 < len(lines) and TABLE_ROW_RE.match(line) and TABLE_ROW_RE.match(lines[i + 1]):
-            header = _split_table_row(line)
-            if not TABLE_SEP_RE.match(lines[i + 1]):
-                i += 1
-                continue
-
-            lowered = [h.lower() for h in header]
-            if "action" not in lowered or "description" not in lowered:
-                i += 1
-                continue
-            if "no" in lowered:
-                no_index = lowered.index("no")
-            elif "no." in lowered:
-                no_index = lowered.index("no.")
-            else:
-                i += 1
-                continue
-
-            j = i + 2
-            while j < len(lines) and TABLE_ROW_RE.match(lines[j]):
-                row = _split_table_row(lines[j])
-                if len(row) <= no_index:
-                    j += 1
-                    continue
-
-                try:
-                    current_no = int(row[no_index])
-                except ValueError:
-                    j += 1
-                    continue
-
-                rows += 1
-                if current_no != expected_no:
-                    row[no_index] = str(expected_no)
-                    out[j] = _make_row(row)
-                    touched += 1
-                expected_no += 1
-                j += 1
-
-            i = j
-            continue
-
-        i += 1
-
-    return "\n".join(out) + "\n", rows, touched
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description="Renumber action table `No` fields globally in *_FLOW_ACTION_SPEC.md"
-    )
-    parser.add_argument("--spec", required=True, help="Path to *_FLOW_ACTION_SPEC.md")
-    parser.add_argument(
-        "--write",
-        action="store_true",
-        help="Write changes to file. Without this flag, runs in dry-run mode.",
-    )
-    args = parser.parse_args()
-
-    try:
-        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-        sys.stderr.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
-    except Exception:
-        pass
-
-    spec_path = Path(args.spec)
-    if not spec_path.exists():
-        print(f"[ERROR] Not found: {spec_path}", file=sys.stderr)
-        return 2
-
-    text, enc = _read_text(spec_path)
-    new_text, rows, touched = renumber_action_tables(text)
-
-    print(f"Checked: {spec_path}")
-    print(f"- Numbered action rows: {rows}")
-    print(f"- Rows changed: {touched}")
-    print(f"- Mode: {'write' if args.write else 'dry-run'}")
-
-    if touched == 0:
-        print("[OK] Already globally numbered.")
-        return 0
-
-    if not args.write:
-        print("[INFO] Re-run with --write to apply changes.")
-        return 1
-
-    if enc not in ("utf-8", "utf-8-sig"):
-        enc = "utf-8"
-    spec_path.write_text(new_text, encoding=enc)
-    print("[OK] Updated file with global numbering.")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
-