Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Дмитрий
|
04d2e418d5 |
@@ -1,146 +0,0 @@
|
||||
<!-- adr-kit-guide v0.13.0 -->
|
||||
<!-- Canonical project-side ADR guide. Copied from the plugin's templates/adr-kit-guide.md to .claude/adr-kit-guide.md by /adr-kit:init, /adr-kit:upgrade, and /adr-kit:setup. -->
|
||||
<!-- This file is plain markdown — readable by Claude Code, headless `claude -p`, shell scripts in pre-commit hooks, evaluator scripts, and any agent that doesn't process @-imports. Do not embed Claude-Code-specific syntax inside this file. -->
|
||||
|
||||
# ADR Kit Guide
|
||||
|
||||
This project uses [adr-kit](https://github.com/rvdbreemen/adr-kit) to manage Architecture Decision Records. The kit ships:
|
||||
|
||||
- a project-side guide (this file) referenced from `CLAUDE.md`,
|
||||
- a library of slash commands and a subagent for ADR authorship,
|
||||
- a pre-commit hook that catches code changes drifting outside accepted ADRs.
|
||||
|
||||
ADR files live at `docs/adr/ADR-NNN-kebab-case-title.md`. They are versioned, immutable once accepted, and the durable record of *why* the codebase looks the way it does.
|
||||
|
||||
## Three operating modes
|
||||
|
||||
| Mode | When | Entry point |
|
||||
|---|---|---|
|
||||
| **Init / bootstrap** | Once per project: scan source + docs, propose a starter ADR set, hook the kit into `CLAUDE.md`, install the pre-commit hook | `/adr-kit:init` |
|
||||
| **Per-commit verification** | Every `git commit`: declarative-rule check **plus** Claude Sonnet LLM judge for `llm_judge: true` ADRs in one batched call. Default-on as of v0.13.0. Falls back to declarative-only when the `claude` CLI is unavailable | `.githooks/pre-commit` (auto) |
|
||||
| **On-demand invocation** | Mid-session: write a new ADR, judge a staged diff, supersede an existing decision | `/adr-kit:adr`, `/adr-kit:judge`, `adr-generator` subagent |
|
||||
|
||||
## Slash commands
|
||||
|
||||
| Command | Purpose | User-only? |
|
||||
|---|---|---|
|
||||
| `/adr-kit:init` | One-shot project bootstrap (audit codebase, generate ADRs, install hook). Combines `setup` + audit + `install-hooks`. | yes |
|
||||
| `/adr-kit:adr` | Author a single ADR (delegates to `adr-generator` subagent; runs four verification gates). | no — model can self-call |
|
||||
| `/adr-kit:judge` | Interactive judge against a staged diff. Runs declarative checks + in-session LLM check for `llm_judge: true` ADRs. Walks resolution paths on violation. | no — model can self-call |
|
||||
| `/adr-kit:lint` | Validate existing ADRs against the four verification gates. | yes |
|
||||
| `/adr-kit:migrate` | Rewrite legacy ADRs into canonical format. | yes |
|
||||
| `/adr-kit:setup` | Append `## ADR Kit` block to `CLAUDE.md` (idempotent). | yes |
|
||||
| `/adr-kit:upgrade` | Migrate v0.11 → v0.12 footprint without re-running the heavy audit. | yes |
|
||||
| `/adr-kit:install-hooks` | Install or uninstall the pre-commit hook. | yes |
|
||||
|
||||
## The four verification gates
|
||||
|
||||
An ADR cannot move from `Proposed` to `Accepted` until all four pass.
|
||||
|
||||
1. **Completeness** — every required section is present and non-empty: Status, Context, Decision, Alternatives Considered (≥ 2), Consequences (positive + negative), Related Decisions, References. Plus filename matches `ADR-NNN-kebab-case.md` and the heading number agrees.
|
||||
2. **Evidence** — Context or References cites at least one concrete external/internal artefact (incident, profiling data, code path, RFC, vendor doc). No hand-waving justifications.
|
||||
3. **Clarity** — Decision section names a single concrete choice (not a survey), uses imperative voice, no hedging language ("perhaps", "we should consider"). Identifiers (file paths, function names, config keys) are traceable.
|
||||
4. **Consistency** — filename, heading number, and any cross-references resolve. No duplicate ADR numbers in the directory.
|
||||
|
||||
`bin/adr-lint` enforces Completeness and Consistency deterministically. Evidence and Clarity are heuristic; opt in via `--gates evidence,clarity` or run `/adr-kit:lint` to use the LLM-aware skill.
|
||||
|
||||
## Authoring workflow (`/adr-kit:adr` or `adr-generator`)
|
||||
|
||||
1. Identify the architecturally significant change (architecture, NFRs, interfaces, dependencies, build/CI tooling). Refactors and bug fixes within existing patterns do NOT need an ADR.
|
||||
2. Invoke `/adr-kit:adr` (or the `adr-generator` subagent). Provide: title, context with concrete forces, ≥ 2 alternatives with rejection reasons, consequences (both directions), related ADRs.
|
||||
3. The agent applies the four gates and writes `docs/adr/ADR-NNN-…md` with `Status: Proposed`.
|
||||
4. Human review. Iterate until all gates pass.
|
||||
5. Flip Status to `Accepted, YYYY-MM-DD` after explicit human approval. **Never self-approve.**
|
||||
6. If the decision touches code in a mechanically expressible way, add an `Enforcement` block (see below) so the pre-commit hook can guard the boundary.
|
||||
|
||||
## Enforcement block (v0.12+)
|
||||
|
||||
Optional `## Enforcement` section at the end of an ADR. Fenced JSON code block, parsed by `bin/adr-judge`. Schema: plugin's `schemas/adr-enforcement.schema.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"forbid_pattern": [
|
||||
{ "pattern": "\\bArduinoJson\\b", "path_glob": "src/**/*.{ino,cpp,h}",
|
||||
"message": "Use snprintf_P + sendJsonMapEntry; ArduinoJson fragments the heap (ADR-042)." }
|
||||
],
|
||||
"forbid_import": [
|
||||
{ "pattern": "^#include\\s+<ArduinoJson\\.h>", "path_glob": "src/**" }
|
||||
],
|
||||
"require_pattern": [],
|
||||
"llm_judge": false
|
||||
}
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
- `forbid_pattern` — regex must NOT match any added line in the diff (lines starting with `+`, excluding `+++` markers).
|
||||
- `forbid_import` — same engine as `forbid_pattern`; the separate name documents intent.
|
||||
- `require_pattern` — regex must match at least once in the post-diff content of any file matching `path_glob`.
|
||||
- `llm_judge: true` — Claude Sonnet evaluates the diff against this ADR's `## Decision` text at commit time (default-on as of v0.13.0). The pre-commit hook batches all `llm_judge: true` ADRs into one Sonnet call and blocks the commit on `VIOLATION`. Falls back gracefully (advisory only, exit 0) when the `claude` CLI is missing.
|
||||
- ADRs with no Enforcement block are skipped silently by the judge.
|
||||
|
||||
**Path globs** support `**` (recursive). Examples: `src/**/*.py`, `tests/**`, `**/Makefile`.
|
||||
|
||||
## Pre-commit hook
|
||||
|
||||
After `/adr-kit:init` (or `/adr-kit:install-hooks`), every `git commit` runs `bin/adr-judge` on the staged diff with two passes:
|
||||
|
||||
- **Declarative pass** — fast, regex-only, no LLM. A violation exits non-zero and blocks the commit.
|
||||
- **LLM pass (Sonnet, default-on as of v0.13.0)** — all `llm_judge: true` ADRs are batched into one `claude -p --model claude-sonnet-4-6` call. Sonnet returns a per-ADR JSON verdict; any `VIOLATION` blocks the commit with the model's one-sentence reason. Falls back gracefully when the `claude` CLI is missing or unauthenticated — never blocks a legitimate commit due to tooling drift.
|
||||
|
||||
**Cost shape** (typical project, 50 `llm_judge` ADRs, small diff): roughly $0.10–0.30 per commit on Sonnet 4.6 with prompt caching. Latency 5–10s. Configurable via `judge.llm_model` / `judge.llm_timeout_seconds` / `judge.llm_cmd` in `docs/adr/.adr-kit.json`.
|
||||
|
||||
**Knobs:**
|
||||
|
||||
- Disable LLM pass per commit: `ADR_KIT_NO_LLM=1 git commit -m "…"`
|
||||
- Disable hook entirely per commit: `ADR_KIT_HOOK_DISABLE=1 git commit -m "…"`
|
||||
- Switch model: set `judge.llm_model: "claude-haiku-4-5"` in `.adr-kit.json` for higher throughput at lower cost.
|
||||
- Remove permanently: `/adr-kit:install-hooks --uninstall`
|
||||
|
||||
## Supersession (changing a decision)
|
||||
|
||||
Accepted ADRs are immutable. To change a decision:
|
||||
|
||||
1. Author a new ADR with the next number. Status `Proposed`. The Decision should explain what changes and why now.
|
||||
2. In its Related Decisions: `Supersedes ADR-OLD`.
|
||||
3. After the new ADR is `Accepted`: edit ONLY the old ADR's Status line to `Superseded by ADR-NEW, YYYY-MM-DD.` Leave every other section untouched — the old decision's content is the historical record.
|
||||
|
||||
Never edit Decision, Context, Consequences, or Alternatives of an Accepted/Deprecated ADR. The Status line is the only permitted change.
|
||||
|
||||
## Code review checks
|
||||
|
||||
When reviewing a PR, apply these seven checks (Check 7 added in v0.12):
|
||||
|
||||
1. **ADR exists** for any architecturally significant change in the PR (new dep, interface change, NFR shift, build tooling change). Missing → request the author to invoke `/adr-kit:adr` or `adr-generator`.
|
||||
2. **ADR is linked** in the PR description (path or relative URL).
|
||||
3. **No violation** of Accepted ADRs in the diff. Cross-reference against `docs/adr/README.md` and the Enforcement blocks. The pre-commit hook should have caught this; if it didn't, the ADR is missing rules or wasn't installed.
|
||||
4. **Supersession chain is correct** — old ADR's Status updated, new ADR cross-references, content immutability preserved.
|
||||
5. **All four gates pass** on any new/modified ADR. Cite the failing gate when blocking ("fails Evidence gate — no concrete reference in Context").
|
||||
6. **Legacy non-compliance has a remediation plan** — pre-existing violations that this PR doesn't fix should at least carry a `// TODO(ADR-NNN): align` or a backlog entry, not be silently ignored.
|
||||
7. **Enforcement block is set appropriately** on any new Accepted ADR with a code surface. Either declarative rules, OR `llm_judge: true`, OR an explicit "manual review only" note in the ADR body explaining why the rule cannot be expressed mechanically. Missing block on a code-touching ADR is a smell.
|
||||
|
||||
## Anti-rationalisation guards
|
||||
|
||||
When `/adr-kit:adr` is asked to write or accept an ADR, it actively pushes back on these nine common excuses (see plugin's `skills/adr/SKILL.md` for the full text):
|
||||
|
||||
- "It's just a small change" — the rule is "architecturally significant", not "large".
|
||||
- "We can decide later" — later is now; defer = decide.
|
||||
- "Everyone knows this" — undocumented tacit knowledge is the problem ADRs solve.
|
||||
- "It's documented in the code" — code shows what, not why.
|
||||
- "We'll do it the same as last time" — name "last time" with an ADR reference.
|
||||
- "There's only one option" — there are always alternatives; "do nothing" is one.
|
||||
- "It's reversible" — most architecture is partially reversible; the ADR captures the *current* commitment.
|
||||
- "It's a refactor" — pure refactors don't need ADRs; *new patterns* introduced during refactoring do.
|
||||
- "We don't have time" — opportunity cost of skipping is a future maintainer hunting for the why.
|
||||
|
||||
## Plugin-side deep dives
|
||||
|
||||
This guide is the project's own copy. For agents inside Claude Code, the plugin auto-loads richer instructions:
|
||||
|
||||
- Plugin path (locale-dependent): `~/.claude/plugins/cache/rvdbreemen-adr-kit/adr-kit/<version>/`
|
||||
- `instructions/adr.coding.md` — per-developer rules (when to invoke the agent, supersession workflow, Definition of Done).
|
||||
- `instructions/adr.review.md` — the seven review checks with citation templates.
|
||||
- `skills/adr/SKILL.md` — full anti-rationalisation guard list, gate definitions, code examples.
|
||||
- `agents/adr-generator.md` — the subagent prompt.
|
||||
|
||||
If you're working outside Claude Code (in a hook, a CI job, or a different agent), this file (`.claude/adr-kit-guide.md`) is your one-stop reference. Keep it in version control with the rest of the project.
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
name: pest-parallel-debugger
|
||||
description: |
|
||||
Diagnose Pest 4 --parallel test failures in the Лидерра CRM project.
|
||||
Classifies failures as (a) real failure, (b) quirk 72 (Redis supplier:session
|
||||
race в subdir-only), (c) quirk 73 (cumulative state on long sessions),
|
||||
(d) quirk 77 (unique-key collision в bulk-action tests with Faker-generated names),
|
||||
or (e) other — escalate. Falsifies hypotheses with actual command runs.
|
||||
tools: Read, Grep, Bash
|
||||
---
|
||||
|
||||
# Pest --parallel debugger agent — Лидерра
|
||||
|
||||
You are diagnosing a Pest 4 --parallel test failure in the Лидерра CRM project. Read-only diagnosis; recommend fixes, do not apply them.
|
||||
|
||||
## Known quirks (from memory feedback_environment.md, verified 2026-05-13)
|
||||
|
||||
1. **Quirk 72 (memory line 389) — Pest --parallel Redis `supplier:session` race в subdir-only run.**
|
||||
- Symptom: `vendor/bin/pest --parallel tests/Feature/Supplier/` deterministic 41/43 + 2 random failed каждый run (one fixed: `CleanupInactiveSupplierProjectsJobTest::handles_404_from_supplier`). Single-file isolated 8/8 passes.
|
||||
- Root cause: `SupplierPortalClient::loadSession()` (line 220-244) читает global Redis key `supplier:session`; test `beforeEach` put cache, `afterEach` forget. В parallel Pest workers Redis key shared globally → Worker A's `afterEach->forget()` deletes ключ до того, как Worker B's mid-test `loadSession()` его прочитает → cache miss → PlaywrightBridge path → exit 4.
|
||||
- Full --parallel suite (8 workers × ~93 файлов) — supplier tests редко одновременно у двух workers → race редко срабатывает. Full passes 742/739/0/3 ✅.
|
||||
- Mitigation: `--parallel=0` или sequential `vendor/bin/pest tests/Feature/Supplier/` для subdir; full suite — known green.
|
||||
|
||||
2. **Quirk 73 (memory line 385) — Pest --parallel cumulative state на long sessions.**
|
||||
- Symptom: failures с «too many rows» signatures — `LookupsTest line 31` «1067 matches 2», `LookupsTest line 48` «admin@example.ru vs Абрам К.», `ProjectExtensionsTest line 89` «7677 identical to 1».
|
||||
- Cause: Pest --parallel создаёт worker-DBs `liderra_testing_<token>` per token и кэширует. Migrations не пересоздаются между runs без `--recreate-databases`. Tests используют `DatabaseTransactions` (не `RefreshDatabase` — `Pest.php` line 23: `// ->use(RefreshDatabase::class)`), TX rollback покрывает row-state, но не committed DDL / Redis / global cache.
|
||||
- Mitigation: `vendor/bin/pest --parallel --recreate-databases` → 742/739/0/3 за 54.9s. `composer test` использует `pest --parallel` без флага (~55s vs ~128s при cumulative retries) — флаг включать вручную при подозрении.
|
||||
|
||||
3. **Quirk 77 (memory feedback_environment.md, added 13.05.2026 day +1) — Pest --parallel deterministic unique-key collision на `projects(tenant_id, name)` в bulk-action tests.**
|
||||
- Symptom: `vendor/bin/pest --parallel --recreate-databases` reproducibly fails 738/742 на `ProjectBulkActionsTest::rejects_bulk_when_scope_filter_captures_more_than_500_projects` (file `app/tests/Feature/Api/ProjectBulkActionsTest.php:194-206`). Signature `SQLSTATE[23505] projects_tenant_id_name_key — (tenant_id, name)=(<id>, "<faker-3words>")`. Tenant_id varies per run (~50 apart — per-worker auto-increment).
|
||||
- Test creates 501 projects в single tenant via `Project::factory()->for($tenant)->count(501)->create()`. ProjectFactory.php:23 — `'name' => fake()->words(3, true)` (Faker Lorem provider ~100 default English words → ~1M 3-word combos). Birthday paradox math для 501 samples из ~1M combos → ~12.5% per-test failure probability — НЕ deterministic в isolation. Reproducible-in-parallel-but-not-sequential pattern suggests worker state sharing (shared Faker seed via PHP global state? Eloquent factory caching?). Full RCA pending.
|
||||
- Sequential `vendor/bin/pest tests/Feature/Api/ProjectBulkActionsTest.php` passes 14/14 ✅. Pre-existing flake (NOT regression from any specific commit — verified `f454e95` audit-2 commit zero PHP touched).
|
||||
- Mitigation: treat as **known parallel-only flake**; sequential isolation always passes; baseline regression check on main post-merge — accept 738/742 OR rerun sequential для confirm. Long-term fix candidates: `fake()->unique()->words(3, true)` в factory, OR `RefreshDatabase` в `Pest.php` line 18, OR explicit Faker seed per-test.
|
||||
|
||||
**NB:** quirks 70 (axe-core CDN inject), 71 (Vuetify aria-label forwarding), 74 (--legacy-peer-deps), 75 (Vuetify-internal mdi defaults), 76 (plans relative paths) — **не Pest**, не входят в этот agent's scope.
|
||||
|
||||
## Diagnostic pipeline
|
||||
|
||||
Given a failure output (paste from user OR capture from `./vendor/bin/pest --parallel`):
|
||||
|
||||
1. **Capture exact failure.** Какой test file:line failed? Assertion message?
|
||||
2. **Hypothesis 1 — real failure.** Read failing test + production code. Catches real bug? If yes — fix the code.
|
||||
3. **Hypothesis 2 — quirk 72 (Redis `supplier:session` race).** Failing test в `tests/Feature/Supplier/*`? Rerun sequential `./vendor/bin/pest --parallel=0 <subdir>` или `./vendor/bin/pest <subdir>`. If passes — race. Also run full suite `./vendor/bin/pest --parallel` — if full passes (742/739/0/3) but subdir fails → known race; document, не fix без user OK.
|
||||
4. **Hypothesis 3 — quirk 73 (cumulative state).** Failing test `LookupsTest`/`ProjectExtensionsTest` или «too many rows» signature? Rerun `./vendor/bin/pest --parallel --recreate-databases`. If passes → cumulative; baseline restored.
|
||||
5. **Hypothesis 4 — quirk 77 (unique-key collision в bulk-action tests).** Failing test creates ≥500 records of one model в single tenant с Faker-generated unique field? Pattern: `SQLSTATE[23505]` + `_tenant_id_<col>_key` constraint name + Faker-style value в DETAIL. Rerun sequential `./vendor/bin/pest <test-file>` — if passes 14/14 → quirk 77 confirmed; document as known parallel-only flake, не fix без user OK (root cause не fully RCA'd).
|
||||
6. **Hypothesis 5 — other.** If none of above → escalate с raw output + tested hypotheses + outcome per hypothesis.
|
||||
|
||||
## Output format
|
||||
|
||||
```text
|
||||
Pest --parallel debugger report
|
||||
|
||||
Failure: <file>:<line>
|
||||
Assertion: <message>
|
||||
|
||||
Hypothesis 1 (real failure): <falsified|confirmed|untested>
|
||||
Evidence: <test code summary + production code review with file:line pins>
|
||||
Hypothesis 2 (quirk 72 Redis supplier:session race): <falsified|confirmed|untested>
|
||||
Evidence: <command + output>
|
||||
Hypothesis 3 (quirk 73 cumulative state): <falsified|confirmed|untested>
|
||||
Evidence: <command + output>
|
||||
Hypothesis 4 (quirk 77 unique-key collision): <falsified|confirmed|untested>
|
||||
Evidence: <command + output>
|
||||
|
||||
Conclusion: <real fix needed | quirk 72 — known race document | quirk 73 — recreate-databases fixed | quirk 77 — known parallel-only flake document | other — escalate>
|
||||
Recommendation: <next step for user>
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- Falsify hypotheses с actual command runs, не speculate.
|
||||
- Capture raw output, не summaries.
|
||||
- Никогда "should pass" — только "passed with `<cmd>`" or "failed with `<cmd>` + `<output>`".
|
||||
- Каждое утверждение про код — с `file:line` pin'ом.
|
||||
- If unsure — escalate, do not guess.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Не fix code — only diagnose + recommend.
|
||||
- Не run full --parallel for >5 min без user OK (полный прогон ~55-128s OK).
|
||||
- Vitest (frontend) failures — separate concern.
|
||||
- a11y / Vuetify quirks — see separate quirks 70-71 in memory; not this agent.
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
name: rls-reviewer
|
||||
description: |
|
||||
Review RLS (Row-Level Security) compliance on migration commits/PRs.
|
||||
Use when reviewing changes to db/schema.sql or db/migrations/ that add
|
||||
or modify tables. Specialized for Лидерра's 5-role architecture
|
||||
(crm_app_user, crm_app_admin, crm_supplier_worker BYPASSRLS,
|
||||
crm_readonly, crm_migrator). Reports orphan policies, missing tenant_id
|
||||
columns, inconsistent GRANTs, missing CHANGELOG entries.
|
||||
For manually checking a single named table before commit - use the /rls-check skill.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
---
|
||||
|
||||
# RLS reviewer agent — Лидерра
|
||||
|
||||
You are reviewing a database migration or schema change for RLS (Row-Level Security) compliance in the Лидерра CRM project. Read-only review — DO NOT edit files.
|
||||
|
||||
## Контекст проекта
|
||||
|
||||
PostgreSQL 16 с 5 ролями (db/00_create_roles.sql + db/02_grants.sql):
|
||||
|
||||
1. `crm_app_user` — regular tenant user; RLS enforced via `current_setting('app.current_tenant_id')`.
|
||||
2. `crm_app_admin` — tenant admin; RLS enforced, broader policies.
|
||||
3. `crm_supplier_worker` — SaaS-level worker (BYPASSRLS) для supplier integration jobs.
|
||||
4. `crm_readonly` — read-only для reports; RLS enforced.
|
||||
5. `crm_migrator` — DDL role для Laravel migrations; RLS bypassed via session.
|
||||
|
||||
Каждая tenant-scoped таблица должна иметь:
|
||||
|
||||
- `tenant_id UUID NOT NULL REFERENCES tenants(id)` колонка.
|
||||
- `ALTER TABLE <name> ENABLE ROW LEVEL SECURITY;`.
|
||||
- Минимум 2 политики: SELECT (tenant scope `tenant_id = current_setting('app.current_tenant_id')::uuid`), ALL (admin scope).
|
||||
- GRANT'ы для 5 ролей в `db/02_grants.sql`.
|
||||
|
||||
SaaS-level таблицы (e.g., `supplier_csv_reconcile_log`, `system_settings`) exempt от tenant_id; должны иметь explicit `-- SaaS-level` comment.
|
||||
|
||||
Каждое schema change требует записи в `db/CHANGELOG_schema.md` (CLAUDE.md §5 п.8).
|
||||
|
||||
## Граница со скилом /rls-check
|
||||
|
||||
`rls-reviewer` (этот агент) и скил `/rls-check`
|
||||
(`.claude/skills/rls-check/SKILL.md`) оба проверяют RLS. Правило выбора:
|
||||
|
||||
- Есть diff / ветка / PR с изменениями БД, набор таблиц заранее не известен →
|
||||
**этот агент**.
|
||||
- Знаешь имя одной конкретной таблицы, проверка вручную перед коммитом →
|
||||
**скил `/rls-check <table>`**.
|
||||
|
||||
Этот агент прогоняет **7 статических пунктов** чеклиста. Живой дымовой тест
|
||||
(`pest --filter RlsSmokeTest`) намеренно **не входит** в агентский чеклист:
|
||||
запуск Pest в ревью-субагенте медленный и задевает гонки `--parallel`
|
||||
(квирки 72/77, см. `.claude/agents/pest-parallel-debugger.md`). Живой дымовой
|
||||
тест — 8-я строка скила `/rls-check`. 7 пунктов агента === первые 7 строк
|
||||
вывода скила (общее статическое ядро).
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Read target migration файл OR `db/schema.sql` diff (use `git diff HEAD~1 -- db/schema.sql` или указанные изменения).
|
||||
2. Для каждой added/modified таблицы — run 7-item checklist:
|
||||
- tenant_id column (или SaaS-level comment).
|
||||
- ENABLE RLS.
|
||||
- SELECT policy для crm_app_user.
|
||||
- ALL policy для crm_app_admin (или per-convention).
|
||||
- 5-role GRANTs в db/02_grants.sql.
|
||||
- db/CHANGELOG_schema.md entry.
|
||||
- squawk passes (`./bin/squawk.exe <file>`).
|
||||
3. Cross-check `db/02_grants.sql` для matching GRANTs.
|
||||
4. Cross-check `db/CHANGELOG_schema.md` для entry.
|
||||
5. Run `./bin/squawk.exe db/schema.sql 2>&1 | tail -10` и capture issues.
|
||||
6. Output structured report:
|
||||
|
||||
```text
|
||||
RLS Review — <table_name>
|
||||
[✅/❌] tenant_id column present
|
||||
[✅/❌] ENABLE ROW LEVEL SECURITY
|
||||
[✅/❌] SELECT policy for crm_app_user
|
||||
[✅/❌] ALL policy for crm_app_admin
|
||||
[✅/❌] 5-role GRANTs in db/02_grants.sql
|
||||
[✅/❌] db/CHANGELOG_schema.md entry
|
||||
[✅/❌] squawk passes (0 issues)
|
||||
Issues:
|
||||
- <file>:<line>:<col> <message>
|
||||
Pass: <N>/7
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- READ-ONLY — не edit files, только report.
|
||||
- Falsify с actual command runs, не speculate.
|
||||
- SaaS-level exemption — accept если explicit comment present; flag если comment отсутствует.
|
||||
- Partitioned tables (e.g., `lead_charges` partitioned by month) — verify policy применяется к parent + children.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- General SQL style (squawk handles).
|
||||
- Business logic review (other agents).
|
||||
- Performance review (separate concern).
|
||||
- Проверка одной названной таблицы вручную перед коммитом + живой дымовой
|
||||
тест — сценарий скила `/rls-check`, не агента.
|
||||
|
||||
## Verification protocol
|
||||
|
||||
Каждое утверждение про код — с `file:line` как pin'ом. "Looks correct" / "should pass" — запрещено. Только "passed with command X — output Y" or "failed with command X — output Y".
|
||||
@@ -1,239 +0,0 @@
|
||||
---
|
||||
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(git show:*), Bash(git remote show:*), Read, Glob, Grep, LS, Task
|
||||
description: Complete a security review of the pending changes on the current branch
|
||||
---
|
||||
|
||||
You are a senior security engineer conducting a focused security review of the changes on this branch.
|
||||
|
||||
GIT STATUS:
|
||||
|
||||
```
|
||||
!`git status`
|
||||
```
|
||||
|
||||
FILES MODIFIED:
|
||||
|
||||
```
|
||||
!`git diff --name-only origin/HEAD...`
|
||||
```
|
||||
|
||||
COMMITS:
|
||||
|
||||
```
|
||||
!`git log --no-decorate origin/HEAD...`
|
||||
```
|
||||
|
||||
DIFF CONTENT:
|
||||
|
||||
```
|
||||
!`git diff --merge-base origin/HEAD`
|
||||
```
|
||||
|
||||
Review the complete diff above. This contains all code changes in the PR.
|
||||
|
||||
OBJECTIVE:
|
||||
Perform a security-focused code review to identify HIGH-CONFIDENCE security vulnerabilities that could have real exploitation potential. This is not a general code review - focus ONLY on security implications newly added by this PR. Do not comment on existing security concerns.
|
||||
|
||||
CRITICAL INSTRUCTIONS:
|
||||
|
||||
1. MINIMIZE FALSE POSITIVES: Only flag issues where you're >80% confident of actual exploitability
|
||||
2. AVOID NOISE: Skip theoretical issues, style concerns, or low-impact findings
|
||||
3. FOCUS ON IMPACT: Prioritize vulnerabilities that could lead to unauthorized access, data breaches, or system compromise
|
||||
4. EXCLUSIONS: Do NOT report the following issue types:
|
||||
- Denial of Service (DOS) vulnerabilities, even if they allow service disruption
|
||||
- Secrets or sensitive data stored on disk (these are handled by other processes)
|
||||
- Rate limiting or resource exhaustion issues
|
||||
|
||||
SECURITY CATEGORIES TO EXAMINE:
|
||||
|
||||
**Input Validation Vulnerabilities:**
|
||||
|
||||
- SQL injection via unsanitized user input
|
||||
- Command injection in system calls or subprocesses
|
||||
- XXE injection in XML parsing
|
||||
- Template injection in templating engines
|
||||
- NoSQL injection in database queries
|
||||
- Path traversal in file operations
|
||||
|
||||
**Authentication & Authorization Issues:**
|
||||
|
||||
- Authentication bypass logic
|
||||
- Privilege escalation paths
|
||||
- Session management flaws
|
||||
- JWT token vulnerabilities
|
||||
- Authorization logic bypasses
|
||||
|
||||
**Crypto & Secrets Management:**
|
||||
|
||||
- Hardcoded API keys, passwords, or tokens
|
||||
- Weak cryptographic algorithms or implementations
|
||||
- Improper key storage or management
|
||||
- Cryptographic randomness issues
|
||||
- Certificate validation bypasses
|
||||
|
||||
**Injection & Code Execution:**
|
||||
|
||||
- Remote code execution via deseralization
|
||||
- Pickle injection in Python
|
||||
- YAML deserialization vulnerabilities
|
||||
- Eval injection in dynamic code execution
|
||||
- XSS vulnerabilities in web applications (reflected, stored, DOM-based)
|
||||
|
||||
**Data Exposure:**
|
||||
|
||||
- Sensitive data logging or storage
|
||||
- PII handling violations
|
||||
- API endpoint data leakage
|
||||
- Debug information exposure
|
||||
|
||||
Additional notes:
|
||||
|
||||
- Even if something is only exploitable from the local network, it can still be a HIGH severity issue
|
||||
|
||||
ANALYSIS METHODOLOGY:
|
||||
|
||||
Phase 1 - Repository Context Research (Use file search tools):
|
||||
|
||||
- Identify existing security frameworks and libraries in use
|
||||
- Look for established secure coding patterns in the codebase
|
||||
- Examine existing sanitization and validation patterns
|
||||
- Understand the project's security model and threat model
|
||||
|
||||
Phase 2 - Comparative Analysis:
|
||||
|
||||
- Compare new code changes against existing security patterns
|
||||
- Identify deviations from established secure practices
|
||||
- Look for inconsistent security implementations
|
||||
- Flag code that introduces new attack surfaces
|
||||
|
||||
Phase 3 - Vulnerability Assessment:
|
||||
|
||||
- Examine each modified file for security implications
|
||||
- Trace data flow from user inputs to sensitive operations
|
||||
- Look for privilege boundaries being crossed unsafely
|
||||
- Identify injection points and unsafe deserialization
|
||||
|
||||
REQUIRED OUTPUT FORMAT:
|
||||
|
||||
You MUST output your findings in markdown. The markdown output should contain the file, line number, severity, category (e.g. `sql_injection` or `xss`), description, exploit scenario, and fix recommendation.
|
||||
|
||||
For example:
|
||||
|
||||
# Vuln 1: XSS: `foo.py:42`
|
||||
|
||||
- Severity: High
|
||||
- Description: User input from `username` parameter is directly interpolated into HTML without escaping, allowing reflected XSS attacks
|
||||
- Exploit Scenario: Attacker crafts URL like `/bar?q=<script>alert(document.cookie)</script>` to execute JavaScript in victim's browser, enabling session hijacking or data theft
|
||||
- Recommendation: Use Flask's escape() function or Jinja2 templates with auto-escaping enabled for all user inputs rendered in HTML
|
||||
|
||||
SEVERITY GUIDELINES:
|
||||
|
||||
- **HIGH**: Directly exploitable vulnerabilities leading to RCE, data breach, or authentication bypass
|
||||
- **MEDIUM**: Vulnerabilities requiring specific conditions but with significant impact
|
||||
- **LOW**: Defense-in-depth issues or lower-impact vulnerabilities
|
||||
|
||||
CONFIDENCE SCORING:
|
||||
|
||||
- 0.9-1.0: Certain exploit path identified, tested if possible
|
||||
- 0.8-0.9: Clear vulnerability pattern with known exploitation methods
|
||||
- 0.7-0.8: Suspicious pattern requiring specific conditions to exploit
|
||||
- Below 0.7: Don't report (too speculative)
|
||||
|
||||
FINAL REMINDER:
|
||||
Focus on HIGH and MEDIUM findings only. Better to miss some theoretical issues than flood the report with false positives. Each finding should be something a security engineer would confidently raise in a PR review.
|
||||
|
||||
FALSE POSITIVE FILTERING:
|
||||
|
||||
> You do not need to run commands to reproduce the vulnerability, just read the code to determine if it is a real vulnerability. Do not use the bash tool or write to any files.
|
||||
>
|
||||
> HARD EXCLUSIONS - Automatically exclude findings matching these patterns:
|
||||
>
|
||||
> 1. Denial of Service (DOS) vulnerabilities or resource exhaustion attacks.
|
||||
> 2. Secrets or credentials stored on disk if they are otherwise secured.
|
||||
> 3. Rate limiting concerns or service overload scenarios.
|
||||
> 4. Memory consumption or CPU exhaustion issues.
|
||||
> 5. Lack of input validation on non-security-critical fields without proven security impact.
|
||||
> 6. Input sanitization concerns for GitHub Action workflows unless they are clearly triggerable via untrusted input.
|
||||
> 7. A lack of hardening measures. Code is not expected to implement all security best practices, only flag concrete vulnerabilities.
|
||||
> 8. Race conditions or timing attacks that are theoretical rather than practical issues. Only report a race condition if it is concretely problematic.
|
||||
> 9. Vulnerabilities related to outdated third-party libraries. These are managed separately and should not be reported here.
|
||||
> 10. Memory safety issues such as buffer overflows or use-after-free-vulnerabilities are impossible in rust. Do not report memory safety issues in rust or any other memory safe languages.
|
||||
> 11. Files that are only unit tests or only used as part of running tests.
|
||||
> 12. Log spoofing concerns. Outputting un-sanitized user input to logs is not a vulnerability.
|
||||
> 13. SSRF vulnerabilities that only control the path. SSRF is only a concern if it can control the host or protocol.
|
||||
> 14. Including user-controlled content in AI system prompts is not a vulnerability.
|
||||
> 15. Regex injection. Injecting untrusted content into a regex is not a vulnerability.
|
||||
> 16. Regex DOS concerns.
|
||||
> 17. Insecure documentation. Do not report any findings in documentation files such as markdown files.
|
||||
> 18. A lack of audit logs is not a vulnerability.
|
||||
>
|
||||
> PRECEDENTS -
|
||||
>
|
||||
> 1. Logging high value secrets in plaintext is a vulnerability. Logging URLs is assumed to be safe.
|
||||
> 2. UUIDs can be assumed to be unguessable and do not need to be validated.
|
||||
> 3. Environment variables and CLI flags are trusted values. Attackers are generally not able to modify them in a secure environment. Any attack that relies on controlling an environment variable is invalid.
|
||||
> 4. Resource management issues such as memory or file descriptor leaks are not valid.
|
||||
> 5. Subtle or low impact web vulnerabilities such as tabnabbing, XS-Leaks, prototype pollution, and open redirects should not be reported unless they are extremely high confidence.
|
||||
> 6. React and Angular are generally secure against XSS. These frameworks do not need to sanitize or escape user input unless it is using dangerouslySetInnerHTML, bypassSecurityTrustHtml, or similar methods. Do not report XSS vulnerabilities in React or Angular components or tsx files unless they are using unsafe methods.
|
||||
> 7. Most vulnerabilities in github action workflows are not exploitable in practice. Before validating a github action workflow vulnerability ensure it is concrete and has a very specific attack path.
|
||||
> 8. A lack of permission checking or authentication in client-side JS/TS code is not a vulnerability. Client-side code is not trusted and does not need to implement these checks, they are handled on the server-side. The same applies to all flows that send untrusted data to the backend, the backend is responsible for validating and sanitizing all inputs.
|
||||
> 9. Only include MEDIUM findings if they are obvious and concrete issues.
|
||||
> 10. Most vulnerabilities in ipython notebooks (*.ipynb files) are not exploitable in practice. Before validating a notebook vulnerability ensure it is concrete and has a very specific attack path where untrusted input can trigger the vulnerability.
|
||||
> 11. Logging non-PII data is not a vulnerability even if the data may be sensitive. Only report logging vulnerabilities if they expose sensitive information such as secrets, passwords, or personally identifiable information (PII).
|
||||
> 12. Command injection vulnerabilities in shell scripts are generally not exploitable in practice since shell scripts generally do not run with untrusted user input. Only report command injection vulnerabilities in shell scripts if they are concrete and have a very specific attack path for untrusted input.
|
||||
>
|
||||
> SIGNAL QUALITY CRITERIA - For remaining findings, assess:
|
||||
>
|
||||
> 1. Is there a concrete, exploitable vulnerability with a clear attack path?
|
||||
> 2. Does this represent a real security risk vs theoretical best practice?
|
||||
> 3. Are there specific code locations and reproduction steps?
|
||||
> 4. Would this finding be actionable for a security team?
|
||||
>
|
||||
> For each finding, assign a confidence score from 1-10:
|
||||
>
|
||||
> - 1-3: Low confidence, likely false positive or noise
|
||||
> - 4-6: Medium confidence, needs investigation
|
||||
> - 7-10: High confidence, likely true vulnerability
|
||||
|
||||
PROJECT FALSE-POSITIVE GUIDANCE (Лидерра):
|
||||
|
||||
> This section is project-specific (Лидерра CRM — Laravel 13 + Vue 3 multi-tenant SaaS).
|
||||
> Apply it alongside the HARD EXCLUSIONS and PRECEDENTS above when filtering findings.
|
||||
>
|
||||
> EXPECTED — treat as NOT a finding:
|
||||
>
|
||||
> 1. Missing application-layer tenant checks where the table has PostgreSQL Row-Level
|
||||
> Security. Tenant isolation is enforced at the DB layer (`SET LOCAL
|
||||
> app.current_tenant_id` via the `SetTenantContext` middleware; 5 DB roles; 39 RLS
|
||||
> policies — see `docs/adr/ADR-002-multitenancy-postgres-rls.md`). DO still flag
|
||||
> queued jobs or code running as the `crm_supplier_worker` role (which is BYPASSRLS)
|
||||
> that read/write tenant-scoped tables WITHOUT an explicit `where('tenant_id', ...)`.
|
||||
> 2. The `tools/*.mjs` economy / ruflo hook scripts using `child_process.spawnSync`
|
||||
> or `process.env`. These are intentional local CLI hooks, not user-facing or
|
||||
> network-reachable code paths.
|
||||
> 3. Hardcoded-secret findings already covered by gitleaks (pre-commit + pre-push).
|
||||
> Do NOT re-report unless a NEW hardcoded credential is introduced by this diff.
|
||||
> 4. Test factories / seeders (`*Factory.php`, `*Seeder.php`) using `Faker` or
|
||||
> predictable values — test-only, per HARD EXCLUSION 11.
|
||||
>
|
||||
> PRIORITISE for this project:
|
||||
>
|
||||
> 1. HMAC / signature verification gaps on inbound webhooks (supplier lead intake).
|
||||
> 2. Signed-URL generation and validation (report file downloads, e.g. the reports
|
||||
> `/api/reports/jobs/{id}/file` endpoint).
|
||||
> 3. `auth:sanctum` + tenant middleware coverage on `/api/*` routes — a missing guard
|
||||
> is a cross-tenant data-leak vector (cf. the J1 / CTO-18 fix).
|
||||
> 4. Personal-data (ПДн) handling under 152-ФЗ — exposure of subject data in
|
||||
> responses, logs, or exports.
|
||||
> 5. Mass-assignment on Eloquent models (`$fillable` / `$guarded` gaps) reachable
|
||||
> from a request.
|
||||
|
||||
START ANALYSIS:
|
||||
|
||||
Begin your analysis now. Do this in 3 steps:
|
||||
|
||||
1. Use a sub-task to identify vulnerabilities. Use the repository exploration tools to understand the codebase context, then analyze the PR changes for security implications. In the prompt for this sub-task, include all of the above.
|
||||
2. Then for each vulnerability identified by the above sub-task, create a new sub-task to filter out false-positives. Launch these sub-tasks as parallel sub-tasks. In the prompt for these sub-tasks, include everything in the "FALSE POSITIVE FILTERING" instructions (including the "PROJECT FALSE-POSITIVE GUIDANCE (Лидерра)" block).
|
||||
3. Filter out any vulnerabilities where the sub-task reported a confidence less than 8.
|
||||
|
||||
Your final reply must contain the markdown report and nothing else.
|
||||
@@ -1 +0,0 @@
|
||||
# CCPM epic/task store — see docs/projects/README.md
|
||||
@@ -1 +0,0 @@
|
||||
# CCPM PRD store — see docs/projects/README.md
|
||||
@@ -37,26 +37,6 @@
|
||||
]
|
||||
},
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node -e \"const f=process.env.CLAUDE_FILE_PATH||''; const pd=process.env.CLAUDE_PROJECT_DIR||''; const path=require('path'); if (f && pd && path.resolve(f) === path.resolve(pd, 'CLAUDE.md')) { process.stderr.write('\\n[hook] WARNING: Direct edit of root CLAUDE.md detected. Per CLAUDE.md §5 п.10, prefer /claude-md-management:revise-claude-md or /claude-md-management:claude-md-improver. If invoked via that skill, this warning is informational.\\n'); }\""
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "Task",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node \"C:/моя/проекты/портал crm/Документация/tools/subagent-prompt-prefix.mjs\""
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
@@ -66,26 +46,6 @@
|
||||
"command": "node -e \"const f=process.env.CLAUDE_FILE_PATH||''; if(/\\\\.md$/i.test(f) && !/CLAUDE\\\\.md$/i.test(f)) { require('child_process').spawnSync('npx',['-y','markdownlint-cli2','--fix',f],{stdio:'inherit',shell:true}); }\""
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node -e \"const f=process.env.CLAUDE_FILE_PATH||''; const n=f.replace(/\\\\\\\\/g,'/'); if (/(^|\\\\/)db\\\\/schema\\\\.sql$/i.test(n)) { process.stdout.write('\\n[hook] REMINDER: You modified db/schema.sql. Per CLAUDE.md §5 п.8, add a corresponding entry to db/CHANGELOG_schema.md before committing.\\n'); }\""
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "node tools/observer-stop-hook.mjs",
|
||||
"timeout": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,69 +0,0 @@
|
||||
---
|
||||
name: audit-portal
|
||||
description: Запускать при полном аудите портала Лидерры — периодической сквозной проверке качества и безопасности (статанализ, тесты, схема БД, security, UI-smoke, a11y, coverage, bundle, pre-prod). Триггеры — «провести аудит портала», «полный аудит», «portal audit», подготовка к pre-prod или релизу.
|
||||
---
|
||||
|
||||
# Audit Portal — 14-фазный аудит портала
|
||||
|
||||
## Когда использовать
|
||||
|
||||
Периодический сквозной аудит всего портала Лидерры. Прецеденты — аудиты #1
|
||||
(2026-05-12), #2 (2026-05-13), #3 (2026-05-14). НЕ для точечной проверки одного
|
||||
файла или фичи — для этого прямой инструмент (`/regression`, `/security-review`,
|
||||
Pest).
|
||||
|
||||
## 14 фаз
|
||||
|
||||
Фазы последовательны; фаза 2 — 4 параллельных субагента. Каждая фаза пишет
|
||||
находки в `docs/superpowers/audits/<дата>-portal-full-audit-findings.md`, секция
|
||||
`## Phase N`. BLOCKED-пункты — в `<дата>-portal-full-audit-blocked.md`.
|
||||
|
||||
| # | Фаза | Инструмент |
|
||||
|---|---|---|
|
||||
| 1 | Pre-flight — ветка/HEAD, delta-коммиты, `composer`/`npm install`, skeleton-файлы аудита | git, composer, npm |
|
||||
| 2 | Статанализ — ×4 параллельных субагента | A backend: pint+stan+composer audit · B frontend: eslint+vue-tsc+prettier+knip · C docs: markdownlint+cspell+lychee · D SQL: squawk+pgFormatter |
|
||||
| 3 | Тестовые своды | Pest --parallel + sequential, Vitest, Histoire build, Vite build |
|
||||
| 4 | Целостность схемы — root tables, RLS-политики (инвариант 39), 5 user-функций поимённо, orphan-FK, header drift | Laravel Boost MCP (`database-query`) |
|
||||
| 5 | Security — перечислить CI-workflows ПЕРВЫМ, gitleaks delta + полная история + no-git | gitleaks, `ls .github/workflows/`, `/security-review` + Trail of Bits плагины |
|
||||
| 6 | UI-smoke — обход 24 маршрутов: рендер, 0 JS-ошибок, иконки | Playwright MCP |
|
||||
| 7 | Кросс-док целостность — версии нормативки, schema-маркер, `routes/web.php`, `.mcp.json` | Read, Grep, Select-String |
|
||||
| 8 | A11y — Pa11y на 4 guest-URL + axe-core на auth-views | Pa11y, axe-core через Playwright |
|
||||
| 9 | Coverage — Vitest --coverage, сверка с baseline | `@vitest/coverage-v8` |
|
||||
| 10 | Bundle — Vite build + анализ чанков vs baseline | `parse-bundle-analyze.mjs` |
|
||||
| 11 | Pre-prod + TODO-sweep — schedule, RUNBOOK, `.env.example` diff, Sentry SDK, TODO/FIXME | `artisan schedule:list`, `composer show`, Select-String |
|
||||
| 12 | Категоризация + fix-loop — rollup P0–P3; P0/P1 чинятся через TDD (failing test → fix → `test:parallel`) | Pest, Vitest, git |
|
||||
| 13 | Финальная регрессия | Pest --parallel, Vitest, Vite build, gitleaks, lychee |
|
||||
| 14 | Report + memory + push | Write, `git push` (pre-push: gitleaks-full-history + lychee) |
|
||||
|
||||
Нумерация — Audit #3 (самый свежий). Audit #2 использовал Phase 0–14 с иным
|
||||
порядком a11y / coverage / bundle; при расхождении — версия выше.
|
||||
|
||||
## Рубрика серьёзности
|
||||
|
||||
- **P0** — блокирует production / data corruption / security incident.
|
||||
- **P1** — нарушение функциональности / failing test / type error / a11y violation.
|
||||
- **P2** — warning / style / dead code / stale doc.
|
||||
- **P3** — cosmetic / nice-to-have.
|
||||
|
||||
Fix-eligibility: `[FIX-NOW]` — P0/P1, ≤30 мин, atomic-коммит на находку;
|
||||
`[FIX-DEFER]` — P2/P3, только запись в findings, без кода; `[BLOCKED]` — нужно
|
||||
явное «закрываем» от заказчика → `blocked.md` (категории Q.HARD / Q.PRODUCT /
|
||||
Q.DEFER / Q.INFO).
|
||||
|
||||
## Методология
|
||||
|
||||
- Каждая фаза завершается `git commit` находок. После каждых 3 коммитов —
|
||||
self-review §8 (метрики схемы, версии нормативки).
|
||||
- Регрессия в фазе 12/13 → `systematic-debugging` (≥3 гипотезы) → rollback или
|
||||
forward-fix → перепрогон фазы.
|
||||
- Hard-stop'ы decision-tree: не менять `db/schema.sql`, не закрывать
|
||||
Б-/CTO-/Ю-/Диз-/DO-/OPEN- без явного «закрываем», не ставить пакеты, не
|
||||
править корневой `CLAUDE.md` напрямую, не делать force-push.
|
||||
- BLOCKED-находка, требующая решения владельца → в реестр `Открытые_вопросы`
|
||||
через скил `q-item-add`.
|
||||
|
||||
## Не использовать когда
|
||||
|
||||
- Нужна одна проверка (тест / lint / security одного диффа) — прямой инструмент
|
||||
или `/regression quick`.
|
||||
- Точечный security-review диффа ветки — `/security-review` напрямую.
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
name: billing-audit
|
||||
description: Аудит денежной корректности биллинг-кода Лидерры — money-инварианты при правке/ревью списаний, тарифов и баланса. Используй при «проверь списание», «аудит биллинга», «не теряются ли копейки», «идемпотентно ли списание», «корректна ли тарифная ступень», «что значит дрейф CsvReconcile», «провенанс charge_source». НЕ для моделирования процесса (process-modeling), поиска узких мест (process-analysis), security-аудита (D3), РСБУ/налогов (ru-tax-accounting), метрик выручки (product-management).
|
||||
---
|
||||
|
||||
# Billing Audit — аудит денежной корректности биллинга Лидерры
|
||||
|
||||
Проектный скил раздела C6 карты «Финансы — биллинг и тарификация». Проверяет
|
||||
**денежные инварианты** биллинг-подсистемы при правке или ревью кода. Объект —
|
||||
корректность *начисления* (не процесс, не безопасность, не учёт/налоги).
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Правка/ревью кода в `app/app/Services/Billing/**`, `app/app/Jobs/Supplier/CsvReconcileJob.php`,
|
||||
моделей `PricingTier`/`LeadCharge`, контроллеров биллинга.
|
||||
- Вопрос «безопасно ли это денежно?» по списанию, тарифу, балансу, сверке.
|
||||
|
||||
## Процедура аудита (5 инвариантов)
|
||||
|
||||
Полный чек-лист с проверками и ссылками на файлы — `references/invariants.md`.
|
||||
|
||||
1. **Сохранение суммы** — все денежные операции через `bcmath` (bcadd/bcsub/bcmul/bcdiv,
|
||||
scale фиксирован), никаких float; prepaid→₽ конвертация без потери копеек.
|
||||
2. **Идемпотентность списания** — один лид = одно списание; повтор/ретрай джоба
|
||||
не дублирует начисление (проверить уникальный ключ / advisory-lock / upsert).
|
||||
3. **Корректность тарифной ступени** — `PricingTierResolver` выбирает верную из 7
|
||||
ступеней по объёму; границы ступеней (включительно/исключительно) однозначны.
|
||||
4. **Дрейф сверки** — `CsvReconcileJob` порог >5%: что сравнивается, что значит дрейф,
|
||||
куда смотреть (рассинхрон поставки vs ошибка тарифа).
|
||||
5. **Провенанс charge_source** — каждое списание имеет прослеживаемый источник
|
||||
(`charge_source`); ручные/авто/CSV-восстановленные различимы.
|
||||
|
||||
## Границы
|
||||
|
||||
- ≠ `process-modeling` #52 / `process-analysis` #53 — те про *поток/процесс*; billing-audit про *деньги в коде*.
|
||||
- ≠ D3 audit-security (#39/#40) — те про *безопасность*; billing-audit про *денежную корректность*.
|
||||
- ≠ `ru-tax-accounting` #63 — тот про *учёт/налоги* (выход биллинга → налоговая база); billing-audit про *начисление*.
|
||||
- ≠ `product-management:metrics-review` #42 — тот про *метрики выручки*; billing-audit про *корректность*.
|
||||
|
||||
## Связано
|
||||
|
||||
- Reuse: Boost #10 (модели), Pest #18 (тесты инвариантов), Larastan #12 (bcmath/без float), Sentry #34 / Redis #35 (runtime/очередь).
|
||||
- ADR-012 (граница finance-tooling C6/C7).
|
||||
@@ -1,22 +0,0 @@
|
||||
{
|
||||
"skill": "billing-audit",
|
||||
"positive": [
|
||||
"проверь корректность списания за лид",
|
||||
"аудит денежной логики биллинга",
|
||||
"не теряются ли копейки в prepaid→рублёвом балансе",
|
||||
"идемпотентно ли списание при ретрае",
|
||||
"правильно ли резолвится тарифная ступень",
|
||||
"что значит дрейф >5% в CsvReconcile",
|
||||
"проверь провенанс charge_source",
|
||||
"ревью PricingTierResolver на ошибки округления",
|
||||
"ledger двойной баланс — где может утечь сумма",
|
||||
"audit charge invariants before merge"
|
||||
],
|
||||
"near_miss": [
|
||||
{"prompt": "смоделируй BPMN процесса списания", "expect": "process-modeling #52"},
|
||||
{"prompt": "где узкое место в воронке оплат", "expect": "process-analysis #53"},
|
||||
{"prompt": "security-аудит платёжного эндпоинта", "expect": "D3 audit-security / Semgrep"},
|
||||
{"prompt": "посчитай РСБУ-проводки по выручке", "expect": "ru-tax-accounting #63"},
|
||||
{"prompt": "метрика MRR за месяц", "expect": "product-management metrics-review #42"}
|
||||
]
|
||||
}
|
||||
@@ -1,46 +0,0 @@
|
||||
# Денежные инварианты биллинга Лидерры — чек-лист аудита
|
||||
|
||||
Объект-файлы (на момент 20.05.2026):
|
||||
|
||||
- `app/app/Services/Billing/PricingTierResolver.php` — резолюция 7 ступеней (pure).
|
||||
- `app/app/Services/Billing/LedgerService.php` — двойной баланс prepaid→₽ (bcmath).
|
||||
- `app/app/Services/Billing/BillingTopupService.php` — пополнение.
|
||||
- `app/app/Services/Billing/ChargeResult.php` — DTO результата списания.
|
||||
- `app/app/Models/PricingTier.php`, `app/app/Models/LeadCharge.php`.
|
||||
- `app/app/Repositories/PricingTierRepository.php`.
|
||||
- `app/app/Jobs/Supplier/CsvReconcileJob.php` — hourly сверка, алерт дрейфа >5%.
|
||||
- `app/app/Http/Controllers/Api/{AdminPricingTiersController,AdminBillingController,BillingController,TenantChargesController}.php`.
|
||||
|
||||
## I1. Сохранение суммы (bcmath, без float)
|
||||
|
||||
- [ ] Все арифметические операции с деньгами — `bcadd`/`bcsub`/`bcmul`/`bcdiv`/`bccomp` с явным `scale`.
|
||||
- [ ] Нет `+`/`-`/`*`/`/` над денежными значениями (Larastan/grep на float-арифметику в Billing).
|
||||
- [ ] prepaid→₽: конвертация округляет детерминированно (TRUNC/округление вниз в пользу tenant — свериться с кодом), сумма prepaid + ₽ не «исчезает».
|
||||
- [ ] Денежные колонки — целочисленные копейки или DECIMAL, не float/double.
|
||||
|
||||
## I2. Идемпотентность списания
|
||||
|
||||
- [ ] Один лид → одно списание: уникальность по (lead_id) или advisory-lock в `LedgerService`.
|
||||
- [ ] Ретрай `ImportLeadsJob`/`CsvReconcileJob` не создаёт дубль `lead_charges`.
|
||||
- [ ] Транзакция + `lockForUpdate` на балансе при мутации (TOCTOU — см. Sprint 3 lockForUpdate).
|
||||
|
||||
## I3. Корректность тарифной ступени
|
||||
|
||||
- [ ] `PricingTierResolver` выбирает ступень по объёму `delivered_in_month` верно на границах.
|
||||
- [ ] Границы ступеней непрерывны (нет дыр/перекрытий между 7 ступенями).
|
||||
- [ ] Pest покрывает граничные значения (ступень N → N+1).
|
||||
|
||||
## I4. Дрейф сверки CsvReconcile
|
||||
|
||||
- [ ] Порог >5% — что сравнивается (поставка поставщика vs начислено) → `supplier_csv_reconcile_log`.
|
||||
- [ ] Дрейф = рассинхрон поставки (норм) ИЛИ ошибка тарифа (баг) — различить по `charge_source`.
|
||||
|
||||
## I5. Провенанс charge_source
|
||||
|
||||
- [ ] Каждое `lead_charges.charge_source` заполнено и прослеживаемо.
|
||||
- [ ] Авто/ручное/CSV-восстановленное (`recovered_from_csv_at`) различимы.
|
||||
|
||||
## Reuse-инструменты
|
||||
|
||||
Boost #10 (Eloquent-introspection), Pest #18 + pest-parallel-debugger (тесты + race),
|
||||
Larastan #12 (статанализ bcmath), Sentry MCP #34 (runtime списаний), Redis MCP #35 (очередь сверки), context7 #60 (доки bcmath).
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
name: brain-retro
|
||||
description: Use ONCE PER SPRINT (or by explicit user invocation "брейн-ретро") to aggregate evidence from docs/observer/episodes-*.jsonl + notes/*.md and propose regulatory candidates. Read-only — never edits Tooling/Pravila/PSR_v1 automatically; only proposes.
|
||||
---
|
||||
|
||||
# Brain Retro
|
||||
|
||||
Aggregator over observer evidence. Reads JSONL + optional MD notes, surfaces candidates for normative updates. User decides what to apply.
|
||||
|
||||
## When to invoke
|
||||
|
||||
- Explicit user request: «брейн-ретро» / «сделай brain-retro» / `/brain-retro`.
|
||||
- Periodic — owner discretion (e.g. end of sprint).
|
||||
- NOT auto-invoked.
|
||||
|
||||
## What it does NOT do
|
||||
|
||||
- Does NOT edit `docs/Tooling_v8_3.md`, `docs/Pravila_raboty_Claude_v1_1.md`, `docs/Plugin_stack_rules_v1.md`, `CLAUDE.md`, or any normative file.
|
||||
- Does NOT write to `docs/observer/episodes-*.jsonl` (read-only).
|
||||
- Does NOT trigger automatic memory updates.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. **Determine period**: ask user «за какой период» or default to «since last brain-retro» (find latest `docs/observer/notes/YYYY-MM-DD-brain-retro-*.md`).
|
||||
2. **Read evidence**: glob `docs/observer/episodes-YYYY-MM.jsonl` for the period; read all lines as JSON.
|
||||
3. **Read optional notes**: glob `docs/observer/notes/*.md` filtered by date.
|
||||
4. **Update read-counter**: run `node tools/observer-of-observer.mjs record`. This atomically bumps `docs/observer/.read-counter.json` `last_read_at` to now and increments `read_count_last_period`. (Side-effect — used by C3 observer-of-observer for 54-week self-prune detection.)
|
||||
5. **Run the deterministic analyzer**: `node tools/brain-retro-analyzer.mjs docs/observer/episodes-YYYY-MM.jsonl` (pass every monthly file in the period). It returns JSON with `episodeCount`, `observerErrorCount`, `tasks` (episodes grouped into tasks), `causalChains` (error→fix candidates) and `factorMatrix` (outcome distribution per factor). The analyzer deduplicates the routing-gate double-write and infers the true `outcome` of each episode from the next episode's `prompt_signal` — never trust the stored `outcome` (it is `unknown` at write time).
|
||||
6. **Aggregate** per `references/aggregation-template.md` — fill the Factor analysis matrix from the analyzer's `factorMatrix`, the task groups from `tasks`, the causal-chain candidates from `causalChains`.
|
||||
7. **Propose candidates** — clearly separated section «Candidates for owner review». Each candidate has rationale + suggested edit + rejection-option.
|
||||
8. **Save retro note**: `docs/observer/notes/YYYY-MM-DD-brain-retro.md` with full aggregation.
|
||||
8a. **Refresh STATUS.md**: `node tools/status-md-generator.mjs` — auto-rebuild dashboard so it reflects the just-finished retro (`Last /brain-retro: 0 day(s) ago`, current episode count, refreshed C1–C5 controller statuses). Without this, STATUS.md only updates on the next git commit.
|
||||
9. **Report to user**: high-signal summary.
|
||||
|
||||
## Output anatomy
|
||||
|
||||
See `references/aggregation-template.md`.
|
||||
|
||||
## Behavioral rule reminders
|
||||
|
||||
- **«Не использован ≠ проблема» (условное, Pravila §16.4 v1.36)** — when reporting node usage counts, distinguish two cases:
|
||||
1. **Unused + no profile task in episodes** → capability-readiness, do NOT flag.
|
||||
2. **Unused + profile task present (missed activation)** → mandatory section in the report. Cite `tools/observer-classification-map.json` for the classification→node mapping and `tools/.node-dormancy.json` for DEFERRED exclusions. NEVER mark unused-by-design nodes as «zombie» / «removal candidate».
|
||||
- **No auto-edit** — every regulatory suggestion is a candidate, not an action.
|
||||
@@ -1,142 +0,0 @@
|
||||
# Brain-retro aggregation template
|
||||
|
||||
## Period
|
||||
|
||||
YYYY-MM-DD .. YYYY-MM-DD ({N} sessions)
|
||||
|
||||
## Path-type distribution
|
||||
|
||||
| path_type | count | % |
|
||||
|---|---|---|
|
||||
| regulated | A | x% |
|
||||
| improvised | B | y% |
|
||||
| alternative | C | z% |
|
||||
| mixed | D | w% |
|
||||
|
||||
## Outcome distribution
|
||||
|
||||
| outcome | count |
|
||||
|---|---|
|
||||
| success | M |
|
||||
| partial | N |
|
||||
| failure | O |
|
||||
| aborted | P |
|
||||
|
||||
## Top nodes used (from `skill_invoked` events)
|
||||
|
||||
| node | times used | first / last |
|
||||
|---|---|---|
|
||||
|
||||
## Factor analysis matrix (v2 — from `tools/brain-retro-analyzer.mjs`)
|
||||
|
||||
Outcome distribution per factor value. Source: the analyzer’s `factorMatrix`.
|
||||
Outcome is the *inferred* outcome (next-prompt sentiment), not the stored
|
||||
`unknown`. The factor `decision_provenance` directly answers the owner’s
|
||||
question — "is the rework mine or the router’s?"
|
||||
|
||||
For each factor below, render a table: factor value × outcome counts
|
||||
(`success` / `partial` / `rework` / `unknown`).
|
||||
|
||||
### decision_provenance (autonomous vs user_directed_method)
|
||||
|
||||
| provenance | success | partial | rework | unknown |
|
||||
|---|---|---|---|---|
|
||||
|
||||
### economy_level
|
||||
|
||||
| economy_level | success | partial | rework | unknown |
|
||||
|---|---|---|---|---|
|
||||
|
||||
### model · post_compaction · task_size bucket
|
||||
|
||||
(one table each — same columns)
|
||||
|
||||
### node_chosen · task_classification
|
||||
|
||||
(one table each — same columns)
|
||||
|
||||
## Missed Activations (Pravila §16.4 v1.36)
|
||||
|
||||
Surface candidates where a profile-classified task ran with `node_chosen === 'direct'` and at least one non-dormant recommended node was available. The analyzer returns `missedActivations: { totalMissed, byNode, byClassification }` — render the two breakdowns below.
|
||||
|
||||
**Source:** `analyze(episodes, { classificationMap, dormancy }).missedActivations`.
|
||||
|
||||
### By node
|
||||
|
||||
| Node | Episodes missed | Classifications hit |
|
||||
|---|---|---|
|
||||
| #NN | N | refactor (a), bugfix (b) |
|
||||
|
||||
### By classification
|
||||
|
||||
| Classification | Missed episodes | Top recommended nodes (non-dormant) |
|
||||
|---|---|---|
|
||||
| refactor | N | #11, #12, #43 |
|
||||
|
||||
**Interpretation guide:**
|
||||
|
||||
- High count on one node → router-miss pattern. Suggest updating `tools/observer-classification-map.json` or a workflow nudge.
|
||||
- Spread across many nodes with classification leaning to `other` → the classification dictionary may need refinement (separate concern, not a missed activation).
|
||||
- All zero → either no profile work this period, or the router is operating cleanly.
|
||||
|
||||
**NOT to be auto-applied:** these are candidates for human review in retro, not commits or hook blocks.
|
||||
|
||||
## Episodes → tasks (from analyzer `tasks`)
|
||||
|
||||
| task_ref | episodes | turns that are rework |
|
||||
|---|---|---|
|
||||
|
||||
## Causal-chain candidates (from analyzer `causalChains`)
|
||||
|
||||
| from (errored episode) | to (later episode) | shared files |
|
||||
|---|---|---|
|
||||
|
||||
## Observer health
|
||||
|
||||
- `observerErrorCount` from the analyzer — observer_error markers in the period.
|
||||
Non-zero = the observer failed silently somewhere; investigate.
|
||||
|
||||
## Canonical chains L1–L13+ hit rate (from analyzer `factorMatrix.chain_ref`)
|
||||
|
||||
| chain | times | outcome split | notes |
|
||||
|---|---|---|---|
|
||||
|
||||
Each node may belong to several L (a multi-chain episode is counted in each).
|
||||
`null` = episodes outside any chain (`direct` + nodes not in L1–L13+) — **not a
|
||||
problem** per `memory/feedback_brain_unused_tools_not_problem`.
|
||||
|
||||
## Improvised chains (path_type=improvised, repeated ≥2)
|
||||
|
||||
| node-set | times | candidate L13+? |
|
||||
|---|---|---|
|
||||
|
||||
## chain_divergence cases
|
||||
|
||||
| canonical | chosen | reason | recurring? |
|
||||
|---|---|---|---|
|
||||
|
||||
## Top error classes
|
||||
|
||||
| error class | count | recovery pattern |
|
||||
|---|---|---|
|
||||
|
||||
## confusion_marker hot-spots
|
||||
|
||||
| context | count |
|
||||
|---|---|
|
||||
|
||||
## Candidates for owner review
|
||||
|
||||
### Candidate 1: `<title>`
|
||||
|
||||
- **Type**: new canonical chain L13+ / new ADR / boundary clarification / etc.
|
||||
- **Evidence**: refs to JSONL lines (file:line).
|
||||
- **Suggested action**: `<concrete edit>`.
|
||||
- **Cost / risk**: `<brief>`.
|
||||
|
||||
(repeat for each candidate; could be 0)
|
||||
|
||||
## Informational metrics (NOT alerts)
|
||||
|
||||
- Nodes used at least once this period: K / 60+
|
||||
- Nodes never used since beginning of observer logs: L / 67 — **not a problem if there was no profile task** per Pravila §16.4 v1.36 and [feedback_brain_unused_tools_not_problem](../../../memory/feedback_brain_unused_tools_not_problem.md). See `## Missed Activations` above for profile-task-present cases.
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
name: ccpm
|
||||
description: "CCPM - spec-driven project management: PRD → Epic → GitHub Issues → parallel agents → shipped code. Use this skill for anything in the software delivery lifecycle: writing a PRD ('write a PRD for X', 'let's plan X', 'scope this out'), parsing a PRD into an epic, decomposing an epic into tasks, syncing to GitHub ('sync the X epic', 'push tasks to github'), starting work on an issue ('start working on issue N', 'let's work on issue N'), analyzing parallel work streams, running standups ('standup', 'run the standup'), checking status ('what's next', 'what's blocked', 'what are we working on'), closing issues, or merging an epic. Use ccpm any time the user is talking about shipping a feature, managing work, or tracking progress — even if they don't say 'ccpm' or 'PRD'. Do NOT use for: debugging code, writing tests, reviewing PRs, or raw GitHub issue/PR operations with no delivery context."
|
||||
---
|
||||
|
||||
# CCPM - Claude Code Project Manager
|
||||
|
||||
A spec-driven development workflow: PRD → Epic → GitHub Issues → Parallel Agents → Shipped Code.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
Requirements live in files, not heads. Every feature starts as a PRD, becomes a technical epic, decomposes into GitHub issues, and gets executed by parallel agents with full traceability.
|
||||
|
||||
## File Conventions
|
||||
|
||||
Before doing anything, read `references/conventions.md` for path standards, frontmatter schemas, and GitHub operation rules. These apply to all phases.
|
||||
|
||||
## The Five Phases
|
||||
|
||||
### 1. Plan — Capture requirements
|
||||
|
||||
**When**: User wants to define a new feature, product requirement, or scope of work.
|
||||
**Read**: `references/plan.md`
|
||||
**Covers**: Writing PRDs through guided brainstorming, converting PRDs to technical epics.
|
||||
|
||||
### 2. Structure — Break it down
|
||||
|
||||
**When**: An epic exists and needs to be decomposed into concrete tasks.
|
||||
**Read**: `references/structure.md`
|
||||
**Covers**: Epic decomposition into numbered task files with dependencies and parallelization.
|
||||
|
||||
### 3. Sync — Push to GitHub
|
||||
|
||||
**When**: Local epic/tasks need to become GitHub issues, progress needs to be posted as comments, or a bug is found and needs a linked issue created.
|
||||
**Read**: `references/sync.md`
|
||||
**Covers**: Epic sync (epic + tasks → GitHub issues), issue sync (progress comments), closing issues/epics, bug reporting against completed issues.
|
||||
|
||||
### 4. Execute — Start building
|
||||
|
||||
**When**: User wants to start working on one or more GitHub issues with parallel agents.
|
||||
**Read**: `references/execute.md`
|
||||
**Covers**: Issue analysis (parallel work stream identification), launching parallel agents, coordinating worktrees.
|
||||
|
||||
### 5. Track — Know where things stand
|
||||
|
||||
**When**: User asks for status, standup report, what's blocked, what's next, or needs to validate state.
|
||||
**Read**: `references/track.md`
|
||||
**Covers**: Status, standup, search, in-progress, next priority, blocked items, validation.
|
||||
|
||||
---
|
||||
|
||||
## Script-First Rule
|
||||
|
||||
For deterministic operations — anything that reads and reports without needing reasoning — always run the bash script directly rather than doing the work manually:
|
||||
|
||||
| What the user wants | Script to run |
|
||||
|---|---|
|
||||
| Project status | `bash references/scripts/status.sh` |
|
||||
| Standup report | `bash references/scripts/standup.sh` |
|
||||
| List all epics | `bash references/scripts/epic-list.sh` |
|
||||
| Show epic details | `bash references/scripts/epic-show.sh <name>` |
|
||||
| Epic status | `bash references/scripts/epic-status.sh <name>` |
|
||||
| List PRDs | `bash references/scripts/prd-list.sh` |
|
||||
| PRD status | `bash references/scripts/prd-status.sh` |
|
||||
| Search issues/tasks | `bash references/scripts/search.sh <query>` |
|
||||
| What's in progress | `bash references/scripts/in-progress.sh` |
|
||||
| What's next | `bash references/scripts/next.sh` |
|
||||
| What's blocked | `bash references/scripts/blocked.sh` |
|
||||
| Validate project state | `bash references/scripts/validate.sh` |
|
||||
|
||||
Use the LLM for work that requires reasoning: writing PRDs, analyzing parallelism, launching agents, synthesizing updates.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```
|
||||
Plan a feature: "I want to build X" or "create a PRD for X"
|
||||
Parse to epic: "turn the X PRD into an epic"
|
||||
Decompose: "break down the X epic into tasks"
|
||||
Sync to GitHub: "push the X epic to GitHub"
|
||||
Start an issue: "start working on issue 42"
|
||||
Check status: "what's our status" / "standup"
|
||||
What's next: "what should I work on next"
|
||||
Merge epic: "merge the X epic"
|
||||
Report a bug: "found a bug in issue 42" / "testing issue 42 revealed X"
|
||||
```
|
||||
@@ -1,178 +0,0 @@
|
||||
# Conventions — File Formats, Paths & Rules
|
||||
|
||||
Read this before doing any file operations across all phases.
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── prds/
|
||||
│ └── <feature-name>.md # Product requirement documents
|
||||
├── epics/
|
||||
│ ├── <feature-name>/
|
||||
│ │ ├── epic.md # Technical epic
|
||||
│ │ ├── <N>.md # Task files (named by GitHub issue number after sync)
|
||||
│ │ ├── <N>-analysis.md # Parallel work stream analysis
|
||||
│ │ ├── github-mapping.md # Issue number → URL mapping
|
||||
│ │ ├── execution-status.md # Active agents tracker
|
||||
│ │ └── updates/
|
||||
│ │ └── <issue_N>/
|
||||
│ │ ├── stream-A.md # Per-agent progress
|
||||
│ │ ├── progress.md # Overall issue progress
|
||||
│ │ └── execution.md # Execution state
|
||||
│ └── archived/
|
||||
│ └── <feature-name>/ # Completed epics
|
||||
└── context/ # Project context docs (separate system)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Schemas
|
||||
|
||||
### PRD (.claude/prds/<name>.md)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <feature-name> # kebab-case, matches filename
|
||||
description: <one-liner> # used in lists and summaries
|
||||
status: backlog | active | completed
|
||||
created: <ISO 8601> # date -u +"%Y-%m-%dT%H:%M:%SZ"
|
||||
---
|
||||
```
|
||||
|
||||
### Epic (.claude/epics/<name>/epic.md)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <feature-name>
|
||||
status: backlog | in-progress | completed
|
||||
created: <ISO 8601>
|
||||
updated: <ISO 8601>
|
||||
progress: 0% # recalculated when tasks close
|
||||
prd: .claude/prds/<name>.md
|
||||
github: https://github.com/<owner>/<repo>/issues/<N> # set on sync
|
||||
---
|
||||
```
|
||||
|
||||
### Task (.claude/epics/<name>/<N>.md)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <Task Title>
|
||||
status: open | in-progress | closed
|
||||
created: <ISO 8601>
|
||||
updated: <ISO 8601>
|
||||
github: https://github.com/<owner>/<repo>/issues/<N> # set on sync
|
||||
depends_on: [] # issue numbers this must wait for
|
||||
parallel: true # can run concurrently with non-conflicting tasks
|
||||
conflicts_with: [] # issue numbers that touch the same files
|
||||
---
|
||||
```
|
||||
|
||||
### Progress (.claude/epics/<name>/updates/<N>/progress.md)
|
||||
|
||||
```yaml
|
||||
---
|
||||
issue: <N>
|
||||
started: <ISO 8601>
|
||||
last_sync: <ISO 8601>
|
||||
completion: 0%
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Datetime Rule
|
||||
|
||||
Always get real current datetime from the system — never use placeholder text:
|
||||
|
||||
```bash
|
||||
date -u +"%Y-%m-%dT%H:%M:%SZ"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter Update Pattern
|
||||
|
||||
When updating a single frontmatter field in an existing file:
|
||||
|
||||
```bash
|
||||
sed -i.bak "/^<field>:/c\\<field>: <value>" <file>
|
||||
rm <file>.bak
|
||||
```
|
||||
|
||||
When stripping frontmatter to get body content for GitHub:
|
||||
|
||||
```bash
|
||||
sed '1,/^---$/d; 1,/^---$/d' <file> > /tmp/body.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Operations
|
||||
|
||||
### Repository Safety Check (run before any write operation)
|
||||
|
||||
```bash
|
||||
remote_url=$(git remote get-url origin 2>/dev/null || echo "")
|
||||
if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
|
||||
echo "❌ Cannot write to the CCPM template repository."
|
||||
echo "Update remote: git remote set-url origin https://github.com/YOUR/REPO.git"
|
||||
exit 1
|
||||
fi
|
||||
REPO=$(echo "$remote_url" | sed 's|.*github.com[:/]||' | sed 's|\.git$||')
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Don't pre-check authentication. Run the `gh` command and handle failure:
|
||||
|
||||
```bash
|
||||
gh <command> || echo "❌ GitHub CLI failed. Run: gh auth login"
|
||||
```
|
||||
|
||||
### Getting Issue Numbers
|
||||
|
||||
```bash
|
||||
# From a task file's github field:
|
||||
grep 'github:' <file> | grep -oE '[0-9]+$'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git / Worktree Conventions
|
||||
|
||||
- One branch per epic: `epic/<name>`
|
||||
- Worktrees live at `../epic-<name>/` (sibling to project root)
|
||||
- Always start branches from an up-to-date main:
|
||||
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
git worktree add ../epic-<name> -b epic/<name>
|
||||
```
|
||||
|
||||
- Commit format inside epics: `Issue #<N>: <description>`
|
||||
- Never use `--force` in any git operation
|
||||
|
||||
---
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- Feature names: kebab-case, lowercase, letters/numbers/hyphens, starts with a letter
|
||||
- Task files before sync: `001.md`, `002.md`, ... (sequential)
|
||||
- Task files after sync: renamed to GitHub issue number (e.g., `1234.md`)
|
||||
- Labels applied on sync: `epic`, `epic:<name>`, `feature` (for epics); `task`, `epic:<name>` (for tasks)
|
||||
|
||||
---
|
||||
|
||||
## Epic Progress Calculation
|
||||
|
||||
```bash
|
||||
total=$(ls .claude/epics/<name>/[0-9]*.md 2>/dev/null | wc -l)
|
||||
closed=$(grep -l '^status: closed' .claude/epics/<name>/[0-9]*.md 2>/dev/null | wc -l)
|
||||
progress=$((closed * 100 / total))
|
||||
```
|
||||
|
||||
Update epic frontmatter when any task closes.
|
||||
@@ -1,223 +0,0 @@
|
||||
# Execute — Start Building with Parallel Agents
|
||||
|
||||
This phase covers analyzing GitHub issues for parallel work streams and launching agents to execute them.
|
||||
|
||||
---
|
||||
|
||||
## Issue Analysis
|
||||
|
||||
**Trigger**: User wants to understand how to parallelize work on an issue before starting.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Find the local task file: check `.claude/epics/*/<N>.md` first, then search for `github:.*issues/<N>` in frontmatter.
|
||||
- If not found: "❌ No local task for issue #<N>. Run a sync first."
|
||||
|
||||
### Process
|
||||
|
||||
Get issue details: `gh issue view <N> --json title,body,labels`
|
||||
|
||||
Read the local task file fully. Identify independent work streams by asking:
|
||||
|
||||
- Which files will be created/modified?
|
||||
- Which changes can happen simultaneously without conflict?
|
||||
- What are the dependencies between changes?
|
||||
|
||||
**Common stream patterns:**
|
||||
|
||||
- Database Layer: schema, migrations, models
|
||||
- Service Layer: business logic, data access
|
||||
- API Layer: endpoints, validation, middleware
|
||||
- UI Layer: components, pages, styles
|
||||
- Test Layer: unit tests, integration tests
|
||||
|
||||
Create `.claude/epics/<epic_name>/<N>-analysis.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
issue: <N>
|
||||
title: <title>
|
||||
analyzed: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
|
||||
estimated_hours: <total>
|
||||
parallelization_factor: <1.0-5.0>
|
||||
---
|
||||
|
||||
# Parallel Work Analysis: Issue #<N>
|
||||
|
||||
## Overview
|
||||
|
||||
## Parallel Streams
|
||||
|
||||
### Stream A: <Name>
|
||||
**Scope**:
|
||||
**Files**:
|
||||
**Can Start**: immediately
|
||||
**Estimated Hours**:
|
||||
**Dependencies**: none
|
||||
|
||||
### Stream B: <Name>
|
||||
**Scope**:
|
||||
**Files**:
|
||||
**Can Start**: after Stream A
|
||||
**Dependencies**: Stream A
|
||||
|
||||
## Coordination Points
|
||||
### Shared Files
|
||||
### Sequential Requirements
|
||||
|
||||
## Conflict Risk Assessment
|
||||
|
||||
## Parallelization Strategy
|
||||
|
||||
## Expected Timeline
|
||||
- With parallel execution: <max_stream_hours>h wall time
|
||||
- Without: <sum_all_hours>h
|
||||
- Efficiency gain: <pct>%
|
||||
```
|
||||
|
||||
**Output**: "✅ Analysis complete for issue #<N> — N parallel streams identified. Ready to start? Say: start issue <N>"
|
||||
|
||||
---
|
||||
|
||||
## Starting an Issue
|
||||
|
||||
**Trigger**: User wants to begin work on a specific GitHub issue.
|
||||
|
||||
### Preflight
|
||||
|
||||
1. Verify issue exists and is open: `gh issue view <N> --json state,title,labels,body`
|
||||
2. Find local task file (as above).
|
||||
3. Check for analysis file: `.claude/epics/*/<N>-analysis.md` — if missing, run analysis first (or do both in sequence: analyze then start).
|
||||
4. Verify epic worktree exists: `git worktree list | grep "epic-<name>"` — if not: "❌ No worktree. Sync the epic first."
|
||||
|
||||
### Process
|
||||
|
||||
**Step 1 — Read the analysis**, identify which streams can start immediately vs. which have dependencies.
|
||||
|
||||
**Step 2 — Create progress tracking:**
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/epics/<epic>/updates/<N>
|
||||
current_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
```
|
||||
|
||||
Create `.claude/epics/<epic>/updates/<N>/stream-<X>.md` for each stream:
|
||||
|
||||
```markdown
|
||||
---
|
||||
issue: <N>
|
||||
stream: <stream_name>
|
||||
started: <datetime>
|
||||
status: in_progress
|
||||
---
|
||||
## Scope
|
||||
## Progress
|
||||
- Starting implementation
|
||||
```
|
||||
|
||||
**Step 3 — Launch parallel agents** for each stream that can start immediately:
|
||||
|
||||
```yaml
|
||||
Task:
|
||||
description: "Issue #<N> Stream <X>"
|
||||
subagent_type: "general-purpose"
|
||||
prompt: |
|
||||
You are working on Issue #<N> in the epic worktree at: ../epic-<name>/
|
||||
|
||||
Your stream: <stream_name>
|
||||
Your scope — files to modify: <file_patterns>
|
||||
Work to complete: <stream_description>
|
||||
|
||||
Instructions:
|
||||
1. Read full task from: .claude/epics/<epic>/<N>.md
|
||||
2. Read analysis from: .claude/epics/<epic>/<N>-analysis.md
|
||||
3. Work ONLY in your assigned files
|
||||
4. Commit frequently: "Issue #<N>: <specific change>"
|
||||
5. Update progress in: .claude/epics/<epic>/updates/<N>/stream-<X>.md
|
||||
6. If you need to touch files outside your scope, note it in your progress file and wait
|
||||
7. Never use --force on git operations
|
||||
|
||||
Complete your stream's work and mark status: completed when done.
|
||||
```
|
||||
|
||||
Streams with unmet dependencies are queued — launch them as their dependencies complete.
|
||||
|
||||
**Step 4 — Assign on GitHub:**
|
||||
|
||||
```bash
|
||||
gh issue edit <N> --add-assignee @me --add-label "in-progress"
|
||||
```
|
||||
|
||||
**Step 5 — Create execution status file** at `.claude/epics/<epic>/updates/<N>/execution.md`:
|
||||
|
||||
```markdown
|
||||
## Active Streams
|
||||
- Stream A: <name> — Started <time>
|
||||
- Stream B: <name> — Started <time>
|
||||
|
||||
## Queued
|
||||
- Stream C: <name> — Waiting on Stream A
|
||||
|
||||
## Completed
|
||||
(none yet)
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
✅ Started work on issue #<N>
|
||||
|
||||
Launched N agents:
|
||||
Stream A: <name> ✓ Started
|
||||
Stream B: <name> ✓ Started
|
||||
Stream C: <name> ⏸ Waiting (depends on A)
|
||||
|
||||
Monitor: check progress in .claude/epics/<epic>/updates/<N>/
|
||||
Sync updates: "sync issue <N>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Starting a Full Epic
|
||||
|
||||
**Trigger**: User wants to launch parallel agents across all ready issues in an epic at once.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify `.claude/epics/<name>/epic.md` exists and has a `github:` field (i.e., it's been synced).
|
||||
- Check for uncommitted changes: `git status --porcelain` — block if dirty.
|
||||
- Verify epic branch exists: `git branch -a | grep "epic/<name>"`
|
||||
|
||||
### Process
|
||||
|
||||
**Step 1 — Read all task files** in `.claude/epics/<name>/`. Parse frontmatter for `status`, `depends_on`, `parallel`.
|
||||
|
||||
**Step 2 — Categorize tasks:**
|
||||
|
||||
- Ready: status=open, no unmet depends_on
|
||||
- Blocked: has unmet depends_on
|
||||
- In Progress: already has an execution file
|
||||
- Complete: status=closed
|
||||
|
||||
**Step 3 — Analyze any ready tasks** that don't have an analysis file yet (run issue analysis inline).
|
||||
|
||||
**Step 4 — Launch agents** for all ready tasks following the same per-issue agent launch pattern above.
|
||||
|
||||
**Step 5 — Create/update** `.claude/epics/<name>/execution-status.md` with all active agents and queued issues.
|
||||
|
||||
**Step 6 — As agents complete**, check if blocked issues are now unblocked and launch those agents.
|
||||
|
||||
---
|
||||
|
||||
## Agent Coordination Rules
|
||||
|
||||
When multiple agents work in the same worktree simultaneously:
|
||||
|
||||
- Each agent works only on files in its assigned stream scope.
|
||||
- Agents commit frequently with `Issue #<N>: <description>` format.
|
||||
- Before modifying a shared file, check `git status <file>` — if another agent has it modified, wait and pull first.
|
||||
- Agents sync via commits: `git pull --rebase origin epic/<name>` before starting new file work.
|
||||
- Conflicts are never auto-resolved — agents report them and pause.
|
||||
- No `--force` flags ever.
|
||||
|
||||
Shared files that commonly need coordination (types, config, package.json) should be handled by one designated stream; others pull after that commit.
|
||||
@@ -1,111 +0,0 @@
|
||||
# Plan — Capture Requirements
|
||||
|
||||
This phase turns an idea into a structured PRD, then converts the PRD into a technical epic ready for decomposition.
|
||||
|
||||
---
|
||||
|
||||
## Writing a PRD
|
||||
|
||||
**Trigger**: User wants to plan a new feature, product requirement, or area of work.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Check if `.claude/prds/<name>.md` already exists — if so, confirm overwrite before proceeding.
|
||||
- Ensure `.claude/prds/` directory exists; create it if not.
|
||||
- Feature name must be kebab-case (lowercase, letters/numbers/hyphens, starts with a letter). If not: "❌ Feature name must be kebab-case. Example: user-auth, payment-v2"
|
||||
|
||||
### Process
|
||||
|
||||
Conduct a genuine brainstorming session before writing anything. Ask the user:
|
||||
|
||||
- What problem does this solve?
|
||||
- Who are the users affected?
|
||||
- What does success look like?
|
||||
- What's explicitly out of scope?
|
||||
- What are the constraints (tech, time, resources)?
|
||||
|
||||
Then write `.claude/prds/<name>.md` with this frontmatter and structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <feature-name>
|
||||
description: <one-line summary>
|
||||
status: backlog
|
||||
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
|
||||
---
|
||||
|
||||
# PRD: <feature-name>
|
||||
|
||||
## Executive Summary
|
||||
## Problem Statement
|
||||
## User Stories
|
||||
## Functional Requirements
|
||||
## Non-Functional Requirements
|
||||
## Success Criteria
|
||||
## Constraints & Assumptions
|
||||
## Out of Scope
|
||||
## Dependencies
|
||||
```
|
||||
|
||||
**Quality gates before saving:**
|
||||
|
||||
- No placeholder text in any section
|
||||
- User stories include acceptance criteria
|
||||
- Success criteria are measurable
|
||||
- Out of scope is explicitly listed
|
||||
|
||||
**After creation**: Confirm "✅ PRD created: `.claude/prds/<name>.md`" and suggest: "Ready to create technical epic? Say: parse the <name> PRD"
|
||||
|
||||
---
|
||||
|
||||
## Parsing a PRD into a Technical Epic
|
||||
|
||||
**Trigger**: User wants to convert an existing PRD into a technical implementation plan.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify `.claude/prds/<name>.md` exists with valid frontmatter (name, description, status, created).
|
||||
- Check if `.claude/epics/<name>/epic.md` already exists — confirm overwrite if so.
|
||||
|
||||
### Process
|
||||
|
||||
Read the PRD fully, then produce `.claude/epics/<name>/epic.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <feature-name>
|
||||
status: backlog
|
||||
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
|
||||
progress: 0%
|
||||
prd: .claude/prds/<name>.md
|
||||
github: (will be set on sync)
|
||||
---
|
||||
|
||||
# Epic: <feature-name>
|
||||
|
||||
## Overview
|
||||
## Architecture Decisions
|
||||
## Technical Approach
|
||||
### Frontend Components
|
||||
### Backend Services
|
||||
### Infrastructure
|
||||
## Implementation Strategy
|
||||
## Task Breakdown Preview
|
||||
## Dependencies
|
||||
## Success Criteria (Technical)
|
||||
## Estimated Effort
|
||||
```
|
||||
|
||||
**Key constraints:**
|
||||
|
||||
- Aim for ≤10 tasks total — prefer simplicity over completeness.
|
||||
- Look for ways to leverage existing functionality before creating new code.
|
||||
- Identify parallelization opportunities in the task breakdown preview.
|
||||
|
||||
**After creation**: Confirm "✅ Epic created: `.claude/epics/<name>/epic.md`" and suggest: "Ready to decompose into tasks? Say: decompose the <name> epic"
|
||||
|
||||
---
|
||||
|
||||
## Editing a PRD or Epic
|
||||
|
||||
Read the file first, make targeted edits preserving all frontmatter. Update the `updated` frontmatter field with current datetime.
|
||||
@@ -1,67 +0,0 @@
|
||||
#!/bin/bash
|
||||
echo "Getting tasks..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "🚫 Blocked Tasks"
|
||||
echo "================"
|
||||
echo ""
|
||||
|
||||
found=0
|
||||
|
||||
for epic_dir in .claude/epics/*/; do
|
||||
[ -d "$epic_dir" ] || continue
|
||||
epic_name=$(basename "$epic_dir")
|
||||
|
||||
for task_file in "$epic_dir"/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
|
||||
# Check if task is open
|
||||
status=$(grep "^status:" "$task_file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" != "open" ] && [ -n "$status" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Check for dependencies
|
||||
deps_line=$(grep "^depends_on:" "$task_file" | head -1)
|
||||
if [ -n "$deps_line" ]; then
|
||||
deps=$(echo "$deps_line" | sed 's/^depends_on: *//' | sed 's/^\[//' | sed 's/\]$//' | sed 's/,/ /g' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
|
||||
[ -z "$deps" ] && deps=""
|
||||
else
|
||||
deps=""
|
||||
fi
|
||||
|
||||
if [ -n "$deps" ] && [ "$deps" != "depends_on:" ]; then
|
||||
task_name=$(grep "^name:" "$task_file" | head -1 | sed 's/^name: *//')
|
||||
task_num=$(basename "$task_file" .md)
|
||||
|
||||
echo "⏸️ Task #$task_num - $task_name"
|
||||
echo " Epic: $epic_name"
|
||||
echo " Blocked by: [$deps]"
|
||||
|
||||
# Check status of dependencies
|
||||
open_deps=""
|
||||
for dep in $deps; do
|
||||
dep_file="$epic_dir$dep.md"
|
||||
if [ -f "$dep_file" ]; then
|
||||
dep_status=$(grep "^status:" "$dep_file" | head -1 | sed 's/^status: *//')
|
||||
[ "$dep_status" = "open" ] && open_deps="$open_deps #$dep"
|
||||
fi
|
||||
done
|
||||
|
||||
[ -n "$open_deps" ] && echo " Waiting for:$open_deps"
|
||||
echo ""
|
||||
((found++))
|
||||
fi
|
||||
done
|
||||
done
|
||||
|
||||
if [ $found -eq 0 ]; then
|
||||
echo "No blocked tasks found!"
|
||||
echo ""
|
||||
echo "💡 All tasks with dependencies are either completed or in progress."
|
||||
else
|
||||
echo "📊 Total blocked: $found tasks"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,94 +0,0 @@
|
||||
#!/bin/bash
|
||||
echo "Getting epics..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
[ ! -d ".claude/epics" ] && echo "📁 No epics directory found. Create your first epic with: /pm:prd-parse <feature-name>" && exit 0
|
||||
[ -z "$(ls -d .claude/epics/*/ 2>/dev/null)" ] && echo "📁 No epics found. Create your first epic with: /pm:prd-parse <feature-name>" && exit 0
|
||||
|
||||
echo "📚 Project Epics"
|
||||
echo "================"
|
||||
echo ""
|
||||
|
||||
# Initialize arrays to store epics by status
|
||||
planning_epics=""
|
||||
in_progress_epics=""
|
||||
completed_epics=""
|
||||
|
||||
# Process all epics
|
||||
for dir in .claude/epics/*/; do
|
||||
[ -d "$dir" ] || continue
|
||||
[ -f "$dir/epic.md" ] || continue
|
||||
|
||||
# Extract metadata
|
||||
n=$(grep "^name:" "$dir/epic.md" | head -1 | sed 's/^name: *//')
|
||||
s=$(grep "^status:" "$dir/epic.md" | head -1 | sed 's/^status: *//' | tr '[:upper:]' '[:lower:]')
|
||||
p=$(grep "^progress:" "$dir/epic.md" | head -1 | sed 's/^progress: *//')
|
||||
g=$(grep "^github:" "$dir/epic.md" | head -1 | sed 's/^github: *//')
|
||||
|
||||
# Defaults
|
||||
[ -z "$n" ] && n=$(basename "$dir")
|
||||
[ -z "$p" ] && p="0%"
|
||||
|
||||
# Count tasks
|
||||
t=$(ls "$dir"/[0-9]*.md 2>/dev/null | wc -l)
|
||||
|
||||
# Format output with GitHub issue number if available
|
||||
if [ -n "$g" ]; then
|
||||
i=$(echo "$g" | grep -o '/[0-9]*$' | tr -d '/')
|
||||
entry=" 📋 ${dir}epic.md (#$i) - $p complete ($t tasks)"
|
||||
else
|
||||
entry=" 📋 ${dir}epic.md - $p complete ($t tasks)"
|
||||
fi
|
||||
|
||||
# Categorize by status (handle various status values)
|
||||
case "$s" in
|
||||
planning|draft|"")
|
||||
planning_epics="${planning_epics}${entry}\n"
|
||||
;;
|
||||
in-progress|in_progress|active|started)
|
||||
in_progress_epics="${in_progress_epics}${entry}\n"
|
||||
;;
|
||||
completed|complete|done|closed|finished)
|
||||
completed_epics="${completed_epics}${entry}\n"
|
||||
;;
|
||||
*)
|
||||
# Default to planning for unknown statuses
|
||||
planning_epics="${planning_epics}${entry}\n"
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Display categorized epics
|
||||
echo "📝 Planning:"
|
||||
if [ -n "$planning_epics" ]; then
|
||||
echo -e "$planning_epics" | sed '/^$/d'
|
||||
else
|
||||
echo " (none)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "🚀 In Progress:"
|
||||
if [ -n "$in_progress_epics" ]; then
|
||||
echo -e "$in_progress_epics" | sed '/^$/d'
|
||||
else
|
||||
echo " (none)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "✅ Completed:"
|
||||
if [ -n "$completed_epics" ]; then
|
||||
echo -e "$completed_epics" | sed '/^$/d'
|
||||
else
|
||||
echo " (none)"
|
||||
fi
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "📊 Summary"
|
||||
total=$(ls -d .claude/epics/*/ 2>/dev/null | wc -l)
|
||||
tasks=$(find .claude/epics -name "[0-9]*.md" 2>/dev/null | wc -l)
|
||||
echo " Total epics: $total"
|
||||
echo " Total tasks: $tasks"
|
||||
|
||||
exit 0
|
||||
@@ -1,91 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
epic_name="$1"
|
||||
|
||||
if [ -z "$epic_name" ]; then
|
||||
echo "❌ Please provide an epic name"
|
||||
echo "Usage: /pm:epic-show <epic-name>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Getting epic..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
epic_dir=".claude/epics/$epic_name"
|
||||
epic_file="$epic_dir/epic.md"
|
||||
|
||||
if [ ! -f "$epic_file" ]; then
|
||||
echo "❌ Epic not found: $epic_name"
|
||||
echo ""
|
||||
echo "Available epics:"
|
||||
for dir in .claude/epics/*/; do
|
||||
[ -d "$dir" ] && echo " • $(basename "$dir")"
|
||||
done
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Display epic details
|
||||
echo "📚 Epic: $epic_name"
|
||||
echo "================================"
|
||||
echo ""
|
||||
|
||||
# Extract metadata
|
||||
status=$(grep "^status:" "$epic_file" | head -1 | sed 's/^status: *//')
|
||||
progress=$(grep "^progress:" "$epic_file" | head -1 | sed 's/^progress: *//')
|
||||
github=$(grep "^github:" "$epic_file" | head -1 | sed 's/^github: *//')
|
||||
created=$(grep "^created:" "$epic_file" | head -1 | sed 's/^created: *//')
|
||||
|
||||
echo "📊 Metadata:"
|
||||
echo " Status: ${status:-planning}"
|
||||
echo " Progress: ${progress:-0%}"
|
||||
[ -n "$github" ] && echo " GitHub: $github"
|
||||
echo " Created: ${created:-unknown}"
|
||||
echo ""
|
||||
|
||||
# Show tasks
|
||||
echo "📝 Tasks:"
|
||||
task_count=0
|
||||
open_count=0
|
||||
closed_count=0
|
||||
|
||||
for task_file in "$epic_dir"/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
|
||||
task_num=$(basename "$task_file" .md)
|
||||
task_name=$(grep "^name:" "$task_file" | head -1 | sed 's/^name: *//')
|
||||
task_status=$(grep "^status:" "$task_file" | head -1 | sed 's/^status: *//')
|
||||
parallel=$(grep "^parallel:" "$task_file" | head -1 | sed 's/^parallel: *//')
|
||||
|
||||
if [ "$task_status" = "closed" ] || [ "$task_status" = "completed" ]; then
|
||||
echo " ✅ #$task_num - $task_name"
|
||||
((closed_count++))
|
||||
else
|
||||
echo " ⬜ #$task_num - $task_name"
|
||||
[ "$parallel" = "true" ] && echo -n " (parallel)"
|
||||
((open_count++))
|
||||
fi
|
||||
|
||||
((task_count++))
|
||||
done
|
||||
|
||||
if [ $task_count -eq 0 ]; then
|
||||
echo " No tasks created yet"
|
||||
echo " Run: /pm:epic-decompose $epic_name"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📈 Statistics:"
|
||||
echo " Total tasks: $task_count"
|
||||
echo " Open: $open_count"
|
||||
echo " Closed: $closed_count"
|
||||
[ $task_count -gt 0 ] && echo " Completion: $((closed_count * 100 / task_count))%"
|
||||
|
||||
# Next actions
|
||||
echo ""
|
||||
echo "💡 Actions:"
|
||||
[ $task_count -eq 0 ] && echo " • Decompose into tasks: /pm:epic-decompose $epic_name"
|
||||
[ -z "$github" ] && [ $task_count -gt 0 ] && echo " • Sync to GitHub: /pm:epic-sync $epic_name"
|
||||
[ -n "$github" ] && [ "$status" != "completed" ] && echo " • Start work: /pm:epic-start $epic_name"
|
||||
|
||||
exit 0
|
||||
@@ -1,90 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
epic_name="$1"
|
||||
|
||||
if [ -z "$epic_name" ]; then
|
||||
echo "❌ Please specify an epic name"
|
||||
echo "Usage: /pm:epic-status <epic-name>"
|
||||
echo ""
|
||||
echo "Available epics:"
|
||||
for dir in .claude/epics/*/; do
|
||||
[ -d "$dir" ] && echo " • $(basename "$dir")"
|
||||
done
|
||||
exit 1
|
||||
else
|
||||
# Show status for specific epic
|
||||
epic_dir=".claude/epics/$epic_name"
|
||||
epic_file="$epic_dir/epic.md"
|
||||
|
||||
if [ ! -f "$epic_file" ]; then
|
||||
echo "❌ Epic not found: $epic_name"
|
||||
echo ""
|
||||
echo "Available epics:"
|
||||
for dir in .claude/epics/*/; do
|
||||
[ -d "$dir" ] && echo " • $(basename "$dir")"
|
||||
done
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📚 Epic Status: $epic_name"
|
||||
echo "================================"
|
||||
echo ""
|
||||
|
||||
# Extract metadata
|
||||
status=$(grep "^status:" "$epic_file" | head -1 | sed 's/^status: *//')
|
||||
progress=$(grep "^progress:" "$epic_file" | head -1 | sed 's/^progress: *//')
|
||||
github=$(grep "^github:" "$epic_file" | head -1 | sed 's/^github: *//')
|
||||
|
||||
# Count tasks
|
||||
total=0
|
||||
open=0
|
||||
closed=0
|
||||
blocked=0
|
||||
|
||||
# Use find to safely iterate over task files
|
||||
for task_file in "$epic_dir"/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
((total++))
|
||||
|
||||
task_status=$(grep "^status:" "$task_file" | head -1 | sed 's/^status: *//')
|
||||
deps=$(grep "^depends_on:" "$task_file" | head -1 | sed 's/^depends_on: *\[//' | sed 's/\]//')
|
||||
|
||||
if [ "$task_status" = "closed" ] || [ "$task_status" = "completed" ]; then
|
||||
((closed++))
|
||||
elif [ -n "$deps" ] && [ "$deps" != "depends_on:" ]; then
|
||||
((blocked++))
|
||||
else
|
||||
((open++))
|
||||
fi
|
||||
done
|
||||
|
||||
# Display progress bar
|
||||
if [ $total -gt 0 ]; then
|
||||
percent=$((closed * 100 / total))
|
||||
filled=$((percent * 20 / 100))
|
||||
empty=$((20 - filled))
|
||||
|
||||
echo -n "Progress: ["
|
||||
[ $filled -gt 0 ] && printf '%0.s█' $(seq 1 $filled)
|
||||
[ $empty -gt 0 ] && printf '%0.s░' $(seq 1 $empty)
|
||||
echo "] $percent%"
|
||||
else
|
||||
echo "Progress: No tasks created"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📊 Breakdown:"
|
||||
echo " Total tasks: $total"
|
||||
echo " ✅ Completed: $closed"
|
||||
echo " 🔄 Available: $open"
|
||||
echo " ⏸️ Blocked: $blocked"
|
||||
|
||||
[ -n "$github" ] && echo ""
|
||||
[ -n "$github" ] && echo "🔗 GitHub: $github"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,71 +0,0 @@
|
||||
#!/bin/bash
|
||||
echo "Helping..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "📚 Claude Code PM - Project Management System"
|
||||
echo "============================================="
|
||||
echo ""
|
||||
echo "🎯 Quick Start Workflow"
|
||||
echo " 1. /pm:prd-new <name> - Create a new PRD"
|
||||
echo " 2. /pm:prd-parse <name> - Convert PRD to epic"
|
||||
echo " 3. /pm:epic-decompose <name> - Break into tasks"
|
||||
echo " 4. /pm:epic-sync <name> - Push to GitHub"
|
||||
echo " 5. /pm:epic-start <name> - Start parallel execution"
|
||||
echo ""
|
||||
echo "📄 PRD Commands"
|
||||
echo " /pm:prd-new <name> - Launch brainstorming for new product requirement"
|
||||
echo " /pm:prd-parse <name> - Convert PRD to implementation epic"
|
||||
echo " /pm:prd-list - List all PRDs"
|
||||
echo " /pm:prd-edit <name> - Edit existing PRD"
|
||||
echo " /pm:prd-status - Show PRD implementation status"
|
||||
echo ""
|
||||
echo "📚 Epic Commands"
|
||||
echo " /pm:epic-decompose <name> - Break epic into task files"
|
||||
echo " /pm:epic-sync <name> - Push epic and tasks to GitHub"
|
||||
echo " /pm:epic-oneshot <name> - Decompose and sync in one command"
|
||||
echo " /pm:epic-list - List all epics"
|
||||
echo " /pm:epic-show <name> - Display epic and its tasks"
|
||||
echo " /pm:epic-status [name] - Show epic progress"
|
||||
echo " /pm:epic-close <name> - Mark epic as complete"
|
||||
echo " /pm:epic-edit <name> - Edit epic details"
|
||||
echo " /pm:epic-refresh <name> - Update epic progress from tasks"
|
||||
echo " /pm:epic-start <name> - Launch parallel agent execution"
|
||||
echo ""
|
||||
echo "📝 Issue Commands"
|
||||
echo " /pm:issue-show <num> - Display issue and sub-issues"
|
||||
echo " /pm:issue-status <num> - Check issue status"
|
||||
echo " /pm:issue-start <num> - Begin work with specialized agent"
|
||||
echo " /pm:issue-sync <num> - Push updates to GitHub"
|
||||
echo " /pm:issue-close <num> - Mark issue as complete"
|
||||
echo " /pm:issue-reopen <num> - Reopen closed issue"
|
||||
echo " /pm:issue-edit <num> - Edit issue details"
|
||||
echo " /pm:issue-analyze <num> - Analyze for parallel work streams"
|
||||
echo ""
|
||||
echo "🔄 Workflow Commands"
|
||||
echo " /pm:next - Show next priority tasks"
|
||||
echo " /pm:status - Overall project dashboard"
|
||||
echo " /pm:standup - Daily standup report"
|
||||
echo " /pm:blocked - Show blocked tasks"
|
||||
echo " /pm:in-progress - List work in progress"
|
||||
echo ""
|
||||
echo "🔗 Sync Commands"
|
||||
echo " /pm:sync - Full bidirectional sync with GitHub"
|
||||
echo " /pm:import <issue> - Import existing GitHub issues"
|
||||
echo ""
|
||||
echo "🔧 Maintenance Commands"
|
||||
echo " /pm:validate - Check system integrity"
|
||||
echo " /pm:clean - Archive completed work"
|
||||
echo " /pm:search <query> - Search across all content"
|
||||
echo ""
|
||||
echo "⚙️ Setup Commands"
|
||||
echo " /pm:init - Install dependencies and configure GitHub"
|
||||
echo " /pm:help - Show this help message"
|
||||
echo ""
|
||||
echo "💡 Tips"
|
||||
echo " • Use /pm:next to find available work"
|
||||
echo " • Run /pm:status for quick overview"
|
||||
echo " • Epic workflow: prd-new → prd-parse → epic-decompose → epic-sync"
|
||||
echo " • View README.md for complete documentation"
|
||||
|
||||
exit 0
|
||||
@@ -1,74 +0,0 @@
|
||||
#!/bin/bash
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "🔄 In Progress Work"
|
||||
echo "==================="
|
||||
echo ""
|
||||
|
||||
# Check for active work in updates directories
|
||||
found=0
|
||||
|
||||
if [ -d ".claude/epics" ]; then
|
||||
for updates_dir in .claude/epics/*/updates/*/; do
|
||||
[ -d "$updates_dir" ] || continue
|
||||
|
||||
issue_num=$(basename "$updates_dir")
|
||||
epic_name=$(basename $(dirname $(dirname "$updates_dir")))
|
||||
|
||||
if [ -f "$updates_dir/progress.md" ]; then
|
||||
completion=$(grep "^completion:" "$updates_dir/progress.md" | head -1 | sed 's/^completion: *//')
|
||||
[ -z "$completion" ] && completion="0%"
|
||||
|
||||
# Get task name from the task file
|
||||
task_file=".claude/epics/$epic_name/$issue_num.md"
|
||||
if [ -f "$task_file" ]; then
|
||||
task_name=$(grep "^name:" "$task_file" | head -1 | sed 's/^name: *//')
|
||||
else
|
||||
task_name="Unknown task"
|
||||
fi
|
||||
|
||||
echo "📝 Issue #$issue_num - $task_name"
|
||||
echo " Epic: $epic_name"
|
||||
echo " Progress: $completion complete"
|
||||
|
||||
# Check for recent updates
|
||||
if [ -f "$updates_dir/progress.md" ]; then
|
||||
last_update=$(grep "^last_sync:" "$updates_dir/progress.md" | head -1 | sed 's/^last_sync: *//')
|
||||
[ -n "$last_update" ] && echo " Last update: $last_update"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
((found++))
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
# Also check for in-progress epics
|
||||
echo "📚 Active Epics:"
|
||||
for epic_dir in .claude/epics/*/; do
|
||||
[ -d "$epic_dir" ] || continue
|
||||
[ -f "$epic_dir/epic.md" ] || continue
|
||||
|
||||
status=$(grep "^status:" "$epic_dir/epic.md" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" = "in-progress" ] || [ "$status" = "active" ]; then
|
||||
epic_name=$(grep "^name:" "$epic_dir/epic.md" | head -1 | sed 's/^name: *//')
|
||||
progress=$(grep "^progress:" "$epic_dir/epic.md" | head -1 | sed 's/^progress: *//')
|
||||
[ -z "$epic_name" ] && epic_name=$(basename "$epic_dir")
|
||||
[ -z "$progress" ] && progress="0%"
|
||||
|
||||
echo " • $epic_name - $progress complete"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
if [ $found -eq 0 ]; then
|
||||
echo "No active work items found."
|
||||
echo ""
|
||||
echo "💡 Start work with: /pm:next"
|
||||
else
|
||||
echo "📊 Total active items: $found"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,192 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "Initializing..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo " ██████╗ ██████╗██████╗ ███╗ ███╗"
|
||||
echo "██╔════╝██╔════╝██╔══██╗████╗ ████║"
|
||||
echo "██║ ██║ ██████╔╝██╔████╔██║"
|
||||
echo "╚██████╗╚██████╗██║ ██║ ╚═╝ ██║"
|
||||
echo " ╚═════╝ ╚═════╝╚═╝ ╚═╝ ╚═╝"
|
||||
|
||||
echo "┌─────────────────────────────────┐"
|
||||
echo "│ Claude Code Project Management │"
|
||||
echo "│ by https://x.com/aroussi │"
|
||||
echo "└─────────────────────────────────┘"
|
||||
echo "https://github.com/automazeio/ccpm"
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "🚀 Initializing Claude Code PM System"
|
||||
echo "======================================"
|
||||
echo ""
|
||||
|
||||
# Check for required tools
|
||||
echo "🔍 Checking dependencies..."
|
||||
|
||||
# Check gh CLI
|
||||
if command -v gh &> /dev/null; then
|
||||
echo " ✅ GitHub CLI (gh) installed"
|
||||
else
|
||||
echo " ❌ GitHub CLI (gh) not found"
|
||||
echo ""
|
||||
echo " Installing gh..."
|
||||
if command -v brew &> /dev/null; then
|
||||
brew install gh
|
||||
elif command -v apt-get &> /dev/null; then
|
||||
sudo apt-get update && sudo apt-get install gh
|
||||
else
|
||||
echo " Please install GitHub CLI manually: https://cli.github.com/"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# Check gh auth status
|
||||
echo ""
|
||||
echo "🔐 Checking GitHub authentication..."
|
||||
if gh auth status &> /dev/null; then
|
||||
echo " ✅ GitHub authenticated"
|
||||
else
|
||||
echo " ⚠️ GitHub not authenticated"
|
||||
echo " Running: gh auth login"
|
||||
gh auth login
|
||||
fi
|
||||
|
||||
# Check for gh-sub-issue extension
|
||||
echo ""
|
||||
echo "📦 Checking gh extensions..."
|
||||
if gh extension list | grep -q "yahsan2/gh-sub-issue"; then
|
||||
echo " ✅ gh-sub-issue extension installed"
|
||||
else
|
||||
echo " 📥 Installing gh-sub-issue extension..."
|
||||
gh extension install yahsan2/gh-sub-issue
|
||||
fi
|
||||
|
||||
# Create directory structure
|
||||
echo ""
|
||||
echo "📁 Creating directory structure..."
|
||||
mkdir -p .claude/prds
|
||||
mkdir -p .claude/epics
|
||||
mkdir -p .claude/rules
|
||||
mkdir -p .claude/agents
|
||||
mkdir -p .claude/scripts/pm
|
||||
echo " ✅ Directories created"
|
||||
|
||||
# Copy scripts if in main repo
|
||||
if [ -d "scripts/pm" ] && [ ! "$(pwd)" = *"/.claude"* ]; then
|
||||
echo ""
|
||||
echo "📝 Copying PM scripts..."
|
||||
cp -r scripts/pm/* .claude/scripts/pm/
|
||||
chmod +x .claude/scripts/pm/*.sh
|
||||
echo " ✅ Scripts copied and made executable"
|
||||
fi
|
||||
|
||||
# Check for git
|
||||
echo ""
|
||||
echo "🔗 Checking Git configuration..."
|
||||
if git rev-parse --git-dir > /dev/null 2>&1; then
|
||||
echo " ✅ Git repository detected"
|
||||
|
||||
# Check remote
|
||||
if git remote -v | grep -q origin; then
|
||||
remote_url=$(git remote get-url origin)
|
||||
echo " ✅ Remote configured: $remote_url"
|
||||
|
||||
# Check if remote is the CCPM template repository
|
||||
if [[ "$remote_url" == *"automazeio/ccpm"* ]] || [[ "$remote_url" == *"automazeio/ccpm.git"* ]]; then
|
||||
echo ""
|
||||
echo " ⚠️ WARNING: Your remote origin points to the CCPM template repository!"
|
||||
echo " This means any issues you create will go to the template repo, not your project."
|
||||
echo ""
|
||||
echo " To fix this:"
|
||||
echo " 1. Fork the repository or create your own on GitHub"
|
||||
echo " 2. Update your remote:"
|
||||
echo " git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_REPO.git"
|
||||
echo ""
|
||||
else
|
||||
# Create GitHub labels if this is a GitHub repository
|
||||
if gh repo view &> /dev/null; then
|
||||
echo ""
|
||||
echo "🏷️ Creating GitHub labels..."
|
||||
|
||||
# Create base labels with improved error handling
|
||||
epic_created=false
|
||||
task_created=false
|
||||
|
||||
if gh label create "epic" --color "0E8A16" --description "Epic issue containing multiple related tasks" --force 2>/dev/null; then
|
||||
epic_created=true
|
||||
elif gh label list 2>/dev/null | grep -q "^epic"; then
|
||||
epic_created=true # Label already exists
|
||||
fi
|
||||
|
||||
if gh label create "task" --color "1D76DB" --description "Individual task within an epic" --force 2>/dev/null; then
|
||||
task_created=true
|
||||
elif gh label list 2>/dev/null | grep -q "^task"; then
|
||||
task_created=true # Label already exists
|
||||
fi
|
||||
|
||||
# Report results
|
||||
if $epic_created && $task_created; then
|
||||
echo " ✅ GitHub labels created (epic, task)"
|
||||
elif $epic_created || $task_created; then
|
||||
echo " ⚠️ Some GitHub labels created (epic: $epic_created, task: $task_created)"
|
||||
else
|
||||
echo " ❌ Could not create GitHub labels (check repository permissions)"
|
||||
fi
|
||||
else
|
||||
echo " ℹ️ Not a GitHub repository - skipping label creation"
|
||||
fi
|
||||
fi
|
||||
else
|
||||
echo " ⚠️ No remote configured"
|
||||
echo " Add with: git remote add origin <url>"
|
||||
fi
|
||||
else
|
||||
echo " ⚠️ Not a git repository"
|
||||
echo " Initialize with: git init"
|
||||
fi
|
||||
|
||||
# Create CLAUDE.md if it doesn't exist
|
||||
if [ ! -f "CLAUDE.md" ]; then
|
||||
echo ""
|
||||
echo "📄 Creating CLAUDE.md..."
|
||||
cat > CLAUDE.md << 'EOF'
|
||||
# CLAUDE.md
|
||||
|
||||
> Think carefully and implement the most concise solution that changes as little code as possible.
|
||||
|
||||
## Project-Specific Instructions
|
||||
|
||||
Add your project-specific instructions here.
|
||||
|
||||
## Testing
|
||||
|
||||
Always run tests before committing:
|
||||
- `npm test` or equivalent for your stack
|
||||
|
||||
## Code Style
|
||||
|
||||
Follow existing patterns in the codebase.
|
||||
EOF
|
||||
echo " ✅ CLAUDE.md created"
|
||||
fi
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "✅ Initialization Complete!"
|
||||
echo "=========================="
|
||||
echo ""
|
||||
echo "📊 System Status:"
|
||||
gh --version | head -1
|
||||
echo " Extensions: $(gh extension list | wc -l) installed"
|
||||
echo " Auth: $(gh auth status 2>&1 | grep -o 'Logged in to [^ ]*' || echo 'Not authenticated')"
|
||||
echo ""
|
||||
echo "🎯 Next Steps:"
|
||||
echo " 1. Create your first PRD: /pm:prd-new <feature-name>"
|
||||
echo " 2. View help: /pm:help"
|
||||
echo " 3. Check status: /pm:status"
|
||||
echo ""
|
||||
echo "📚 Documentation: README.md"
|
||||
|
||||
exit 0
|
||||
@@ -1,61 +0,0 @@
|
||||
#!/bin/bash
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "📋 Next Available Tasks"
|
||||
echo "======================="
|
||||
echo ""
|
||||
|
||||
# Find tasks that are open and have no dependencies or whose dependencies are closed
|
||||
found=0
|
||||
|
||||
for epic_dir in .claude/epics/*/; do
|
||||
[ -d "$epic_dir" ] || continue
|
||||
epic_name=$(basename "$epic_dir")
|
||||
|
||||
for task_file in "$epic_dir"/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
|
||||
# Check if task is open
|
||||
status=$(grep "^status:" "$task_file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" != "open" ] && [ -n "$status" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Check dependencies
|
||||
deps_line=$(grep "^depends_on:" "$task_file" | head -1)
|
||||
if [ -n "$deps_line" ]; then
|
||||
deps=$(echo "$deps_line" | sed 's/^depends_on: *//' | sed 's/^\[//' | sed 's/\]$//' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
|
||||
[ -z "$deps" ] && deps=""
|
||||
else
|
||||
deps=""
|
||||
fi
|
||||
|
||||
# If no dependencies or empty, task is available
|
||||
if [ -z "$deps" ] || [ "$deps" = "depends_on:" ]; then
|
||||
task_name=$(grep "^name:" "$task_file" | head -1 | sed 's/^name: *//')
|
||||
task_num=$(basename "$task_file" .md)
|
||||
parallel=$(grep "^parallel:" "$task_file" | head -1 | sed 's/^parallel: *//')
|
||||
|
||||
echo "✅ Ready: #$task_num - $task_name"
|
||||
echo " Epic: $epic_name"
|
||||
[ "$parallel" = "true" ] && echo " 🔄 Can run in parallel"
|
||||
echo ""
|
||||
((found++))
|
||||
fi
|
||||
done
|
||||
done
|
||||
|
||||
if [ $found -eq 0 ]; then
|
||||
echo "No available tasks found."
|
||||
echo ""
|
||||
echo "💡 Suggestions:"
|
||||
echo " • Check blocked tasks: /pm:blocked"
|
||||
echo " • View all tasks: /pm:epic-list"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📊 Summary: $found tasks ready to start"
|
||||
|
||||
exit 0
|
||||
@@ -1,89 +0,0 @@
|
||||
# !/bin/bash
|
||||
# Check if PRD directory exists
|
||||
if [ ! -d ".claude/prds" ]; then
|
||||
echo "📁 No PRD directory found. Create your first PRD with: /pm:prd-new <feature-name>"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check for PRD files
|
||||
if ! ls .claude/prds/*.md >/dev/null 2>&1; then
|
||||
echo "📁 No PRDs found. Create your first PRD with: /pm:prd-new <feature-name>"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Initialize counters
|
||||
backlog_count=0
|
||||
in_progress_count=0
|
||||
implemented_count=0
|
||||
total_count=0
|
||||
|
||||
echo "Getting PRDs..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
|
||||
echo "📋 PRD List"
|
||||
echo "==========="
|
||||
echo ""
|
||||
|
||||
# Display by status groups
|
||||
echo "🔍 Backlog PRDs:"
|
||||
for file in .claude/prds/*.md; do
|
||||
[ -f "$file" ] || continue
|
||||
status=$(grep "^status:" "$file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" = "backlog" ] || [ "$status" = "draft" ] || [ -z "$status" ]; then
|
||||
name=$(grep "^name:" "$file" | head -1 | sed 's/^name: *//')
|
||||
desc=$(grep "^description:" "$file" | head -1 | sed 's/^description: *//')
|
||||
[ -z "$name" ] && name=$(basename "$file" .md)
|
||||
[ -z "$desc" ] && desc="No description"
|
||||
# echo " 📋 $name - $desc"
|
||||
echo " 📋 $file - $desc"
|
||||
((backlog_count++))
|
||||
fi
|
||||
((total_count++))
|
||||
done
|
||||
[ $backlog_count -eq 0 ] && echo " (none)"
|
||||
|
||||
echo ""
|
||||
echo "🔄 In-Progress PRDs:"
|
||||
for file in .claude/prds/*.md; do
|
||||
[ -f "$file" ] || continue
|
||||
status=$(grep "^status:" "$file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" = "in-progress" ] || [ "$status" = "active" ]; then
|
||||
name=$(grep "^name:" "$file" | head -1 | sed 's/^name: *//')
|
||||
desc=$(grep "^description:" "$file" | head -1 | sed 's/^description: *//')
|
||||
[ -z "$name" ] && name=$(basename "$file" .md)
|
||||
[ -z "$desc" ] && desc="No description"
|
||||
# echo " 📋 $name - $desc"
|
||||
echo " 📋 $file - $desc"
|
||||
((in_progress_count++))
|
||||
fi
|
||||
done
|
||||
[ $in_progress_count -eq 0 ] && echo " (none)"
|
||||
|
||||
echo ""
|
||||
echo "✅ Implemented PRDs:"
|
||||
for file in .claude/prds/*.md; do
|
||||
[ -f "$file" ] || continue
|
||||
status=$(grep "^status:" "$file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" = "implemented" ] || [ "$status" = "completed" ] || [ "$status" = "done" ]; then
|
||||
name=$(grep "^name:" "$file" | head -1 | sed 's/^name: *//')
|
||||
desc=$(grep "^description:" "$file" | head -1 | sed 's/^description: *//')
|
||||
[ -z "$name" ] && name=$(basename "$file" .md)
|
||||
[ -z "$desc" ] && desc="No description"
|
||||
# echo " 📋 $name - $desc"
|
||||
echo " 📋 $file - $desc"
|
||||
((implemented_count++))
|
||||
fi
|
||||
done
|
||||
[ $implemented_count -eq 0 ] && echo " (none)"
|
||||
|
||||
# Display summary
|
||||
echo ""
|
||||
echo "📊 PRD Summary"
|
||||
echo " Total PRDs: $total_count"
|
||||
echo " Backlog: $backlog_count"
|
||||
echo " In-Progress: $in_progress_count"
|
||||
echo " Implemented: $implemented_count"
|
||||
|
||||
exit 0
|
||||
@@ -1,63 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "📄 PRD Status Report"
|
||||
echo "===================="
|
||||
echo ""
|
||||
|
||||
if [ ! -d ".claude/prds" ]; then
|
||||
echo "No PRD directory found."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
total=$(ls .claude/prds/*.md 2>/dev/null | wc -l)
|
||||
[ $total -eq 0 ] && echo "No PRDs found." && exit 0
|
||||
|
||||
# Count by status
|
||||
backlog=0
|
||||
in_progress=0
|
||||
implemented=0
|
||||
|
||||
for file in .claude/prds/*.md; do
|
||||
[ -f "$file" ] || continue
|
||||
status=$(grep "^status:" "$file" | head -1 | sed 's/^status: *//')
|
||||
|
||||
case "$status" in
|
||||
backlog|draft|"") ((backlog++)) ;;
|
||||
in-progress|active) ((in_progress++)) ;;
|
||||
implemented|completed|done) ((implemented++)) ;;
|
||||
*) ((backlog++)) ;;
|
||||
esac
|
||||
done
|
||||
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
# Display chart
|
||||
echo "📊 Distribution:"
|
||||
echo "================"
|
||||
|
||||
echo ""
|
||||
echo " Backlog: $(printf '%-3d' $backlog) [$(printf '%0.s█' $(seq 1 $((backlog*20/total))))]"
|
||||
echo " In Progress: $(printf '%-3d' $in_progress) [$(printf '%0.s█' $(seq 1 $((in_progress*20/total))))]"
|
||||
echo " Implemented: $(printf '%-3d' $implemented) [$(printf '%0.s█' $(seq 1 $((implemented*20/total))))]"
|
||||
echo ""
|
||||
echo " Total PRDs: $total"
|
||||
|
||||
# Recent activity
|
||||
echo ""
|
||||
echo "📅 Recent PRDs (last 5 modified):"
|
||||
ls -t .claude/prds/*.md 2>/dev/null | head -5 | while read file; do
|
||||
name=$(grep "^name:" "$file" | head -1 | sed 's/^name: *//')
|
||||
[ -z "$name" ] && name=$(basename "$file" .md)
|
||||
echo " • $name"
|
||||
done
|
||||
|
||||
# Suggestions
|
||||
echo ""
|
||||
echo "💡 Next Actions:"
|
||||
[ $backlog -gt 0 ] && echo " • Parse backlog PRDs to epics: /pm:prd-parse <name>"
|
||||
[ $in_progress -gt 0 ] && echo " • Check progress on active PRDs: /pm:epic-status <name>"
|
||||
[ $total -eq 0 ] && echo " • Create your first PRD: /pm:prd-new <name>"
|
||||
|
||||
exit 0
|
||||
@@ -1,71 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
query="$1"
|
||||
|
||||
if [ -z "$query" ]; then
|
||||
echo "❌ Please provide a search query"
|
||||
echo "Usage: /pm:search <query>"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Searching for '$query'..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "🔍 Search results for: '$query'"
|
||||
echo "================================"
|
||||
echo ""
|
||||
|
||||
# Search in PRDs
|
||||
if [ -d ".claude/prds" ]; then
|
||||
echo "📄 PRDs:"
|
||||
results=$(grep -l -i "$query" .claude/prds/*.md 2>/dev/null)
|
||||
if [ -n "$results" ]; then
|
||||
for file in $results; do
|
||||
name=$(basename "$file" .md)
|
||||
matches=$(grep -c -i "$query" "$file")
|
||||
echo " • $name ($matches matches)"
|
||||
done
|
||||
else
|
||||
echo " No matches"
|
||||
fi
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Search in Epics
|
||||
if [ -d ".claude/epics" ]; then
|
||||
echo "📚 Epics:"
|
||||
results=$(find .claude/epics -name "epic.md" -exec grep -l -i "$query" {} \; 2>/dev/null)
|
||||
if [ -n "$results" ]; then
|
||||
for file in $results; do
|
||||
epic_name=$(basename $(dirname "$file"))
|
||||
matches=$(grep -c -i "$query" "$file")
|
||||
echo " • $epic_name ($matches matches)"
|
||||
done
|
||||
else
|
||||
echo " No matches"
|
||||
fi
|
||||
echo ""
|
||||
fi
|
||||
|
||||
# Search in Tasks
|
||||
if [ -d ".claude/epics" ]; then
|
||||
echo "📝 Tasks:"
|
||||
results=$(find .claude/epics -name "[0-9]*.md" -exec grep -l -i "$query" {} \; 2>/dev/null | head -10)
|
||||
if [ -n "$results" ]; then
|
||||
for file in $results; do
|
||||
epic_name=$(basename $(dirname "$file"))
|
||||
task_num=$(basename "$file" .md)
|
||||
echo " • Task #$task_num in $epic_name"
|
||||
done
|
||||
else
|
||||
echo " No matches"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Summary
|
||||
total=$(find .claude -name "*.md" -exec grep -l -i "$query" {} \; 2>/dev/null | wc -l)
|
||||
echo ""
|
||||
echo "📊 Total files with matches: $total"
|
||||
|
||||
exit 0
|
||||
@@ -1,86 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "📅 Daily Standup - $(date '+%Y-%m-%d')"
|
||||
echo "================================"
|
||||
echo ""
|
||||
|
||||
today=$(date '+%Y-%m-%d')
|
||||
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "📝 Today's Activity:"
|
||||
echo "===================="
|
||||
echo ""
|
||||
|
||||
# Find files modified today
|
||||
recent_files=$(find .claude -name "*.md" -mtime -1 2>/dev/null)
|
||||
|
||||
if [ -n "$recent_files" ]; then
|
||||
# Count by type
|
||||
prd_count=$(echo "$recent_files" | grep -c "/prds/" 2>/dev/null | tr -d '[:space:]')
|
||||
epic_count=$(echo "$recent_files" | grep -c "/epic.md" 2>/dev/null | tr -d '[:space:]')
|
||||
task_count=$(echo "$recent_files" | grep -c "/[0-9]*.md" 2>/dev/null | tr -d '[:space:]')
|
||||
update_count=$(echo "$recent_files" | grep -c "/updates/" 2>/dev/null | tr -d '[:space:]')
|
||||
prd_count=${prd_count:-0}; epic_count=${epic_count:-0}; task_count=${task_count:-0}; update_count=${update_count:-0}
|
||||
|
||||
[ "$prd_count" -gt 0 ] && echo " • Modified $prd_count PRD(s)"
|
||||
[ "$epic_count" -gt 0 ] && echo " • Updated $epic_count epic(s)"
|
||||
[ "$task_count" -gt 0 ] && echo " • Worked on $task_count task(s)"
|
||||
[ "$update_count" -gt 0 ] && echo " • Posted $update_count progress update(s)"
|
||||
else
|
||||
echo " No activity recorded today"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "🔄 Currently In Progress:"
|
||||
# Show active work items
|
||||
for updates_dir in .claude/epics/*/updates/*/; do
|
||||
[ -d "$updates_dir" ] || continue
|
||||
if [ -f "$updates_dir/progress.md" ]; then
|
||||
issue_num=$(basename "$updates_dir")
|
||||
epic_name=$(basename $(dirname $(dirname "$updates_dir")))
|
||||
completion=$(grep "^completion:" "$updates_dir/progress.md" | head -1 | sed 's/^completion: *//')
|
||||
echo " • Issue #$issue_num ($epic_name) - ${completion:-0%} complete"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "⏭️ Next Available Tasks:"
|
||||
# Show top 3 available tasks
|
||||
count=0
|
||||
for epic_dir in .claude/epics/*/; do
|
||||
[ -d "$epic_dir" ] || continue
|
||||
for task_file in "$epic_dir"/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
status=$(grep "^status:" "$task_file" | head -1 | sed 's/^status: *//')
|
||||
if [ "$status" != "open" ] && [ -n "$status" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
deps_line=$(grep "^depends_on:" "$task_file" | head -1)
|
||||
if [ -n "$deps_line" ]; then
|
||||
deps=$(echo "$deps_line" | sed 's/^depends_on: *//' | sed 's/^\[//' | sed 's/\]$//' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
|
||||
[ -z "$deps" ] && deps=""
|
||||
else
|
||||
deps=""
|
||||
fi
|
||||
if [ -z "$deps" ] || [ "$deps" = "depends_on:" ]; then
|
||||
task_name=$(grep "^name:" "$task_file" | head -1 | sed 's/^name: *//')
|
||||
task_num=$(basename "$task_file" .md)
|
||||
echo " • #$task_num - $task_name"
|
||||
((count++))
|
||||
[ $count -ge 3 ] && break 2
|
||||
fi
|
||||
done
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "📊 Quick Stats:"
|
||||
total_tasks=$(find .claude/epics -name "[0-9]*.md" 2>/dev/null | wc -l)
|
||||
open_tasks=$(find .claude/epics -name "[0-9]*.md" -exec grep -l "^status: *open" {} \; 2>/dev/null | wc -l)
|
||||
closed_tasks=$(find .claude/epics -name "[0-9]*.md" -exec grep -l "^status: *closed" {} \; 2>/dev/null | wc -l)
|
||||
echo " Tasks: $open_tasks open, $closed_tasks closed, $total_tasks total"
|
||||
|
||||
exit 0
|
||||
@@ -1,42 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "Getting status..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
|
||||
echo "📊 Project Status"
|
||||
echo "================"
|
||||
echo ""
|
||||
|
||||
echo "📄 PRDs:"
|
||||
if [ -d ".claude/prds" ]; then
|
||||
total=$(ls .claude/prds/*.md 2>/dev/null | wc -l)
|
||||
echo " Total: $total"
|
||||
else
|
||||
echo " No PRDs found"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📚 Epics:"
|
||||
if [ -d ".claude/epics" ]; then
|
||||
total=$(ls -d .claude/epics/*/ 2>/dev/null | grep -v '/archived/$' | wc -l)
|
||||
echo " Total: $total"
|
||||
else
|
||||
echo " No epics found"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📝 Tasks:"
|
||||
if [ -d ".claude/epics" ]; then
|
||||
total=$(find .claude/epics -path "*/archived/*" -prune -o -name "[0-9]*.md" -print 2>/dev/null | wc -l)
|
||||
open=$(find .claude/epics -path "*/archived/*" -prune -o -name "[0-9]*.md" -print 2>/dev/null | xargs grep -l "^status: *open" 2>/dev/null | wc -l)
|
||||
closed=$(find .claude/epics -path "*/archived/*" -prune -o -name "[0-9]*.md" -print 2>/dev/null | xargs grep -l "^status: *closed" 2>/dev/null | wc -l)
|
||||
echo " Open: $open"
|
||||
echo " Closed: $closed"
|
||||
echo " Total: $total"
|
||||
else
|
||||
echo " No tasks found"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,96 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
echo "Validating PM System..."
|
||||
echo ""
|
||||
echo ""
|
||||
|
||||
echo "🔍 Validating PM System"
|
||||
echo "======================="
|
||||
echo ""
|
||||
|
||||
errors=0
|
||||
warnings=0
|
||||
|
||||
# Check directory structure
|
||||
echo "📁 Directory Structure:"
|
||||
[ -d ".claude" ] && echo " ✅ .claude directory exists" || { echo " ❌ .claude directory missing"; ((errors++)); }
|
||||
[ -d ".claude/prds" ] && echo " ✅ PRDs directory exists" || echo " ⚠️ PRDs directory missing"
|
||||
[ -d ".claude/epics" ] && echo " ✅ Epics directory exists" || echo " ⚠️ Epics directory missing"
|
||||
[ -d ".claude/rules" ] && echo " ✅ Rules directory exists" || echo " ⚠️ Rules directory missing"
|
||||
echo ""
|
||||
|
||||
# Check for orphaned files
|
||||
echo "🗂️ Data Integrity:"
|
||||
|
||||
# Check epics have epic.md files
|
||||
for epic_dir in .claude/epics/*/; do
|
||||
[ -d "$epic_dir" ] || continue
|
||||
if [ ! -f "$epic_dir/epic.md" ]; then
|
||||
echo " ⚠️ Missing epic.md in $(basename "$epic_dir")"
|
||||
((warnings++))
|
||||
fi
|
||||
done
|
||||
|
||||
# Check for tasks without epics
|
||||
orphaned=$(find .claude -name "[0-9]*.md" -not -path ".claude/epics/*/*" 2>/dev/null | wc -l)
|
||||
[ $orphaned -gt 0 ] && echo " ⚠️ Found $orphaned orphaned task files" && ((warnings++))
|
||||
|
||||
# Check for broken references
|
||||
echo ""
|
||||
echo "🔗 Reference Check:"
|
||||
|
||||
for task_file in .claude/epics/*/[0-9]*.md; do
|
||||
[ -f "$task_file" ] || continue
|
||||
|
||||
deps_line=$(grep "^depends_on:" "$task_file" | head -1)
|
||||
if [ -n "$deps_line" ]; then
|
||||
deps=$(echo "$deps_line" | sed 's/^depends_on: *//' | sed 's/^\[//' | sed 's/\]$//' | sed 's/,/ /g' | sed 's/^[[:space:]]*//' | sed 's/[[:space:]]*$//')
|
||||
[ -z "$deps" ] && deps=""
|
||||
else
|
||||
deps=""
|
||||
fi
|
||||
if [ -n "$deps" ] && [ "$deps" != "depends_on:" ]; then
|
||||
epic_dir=$(dirname "$task_file")
|
||||
for dep in $deps; do
|
||||
if [ ! -f "$epic_dir/$dep.md" ]; then
|
||||
echo " ⚠️ Task $(basename "$task_file" .md) references missing task: $dep"
|
||||
((warnings++))
|
||||
fi
|
||||
done
|
||||
fi
|
||||
done
|
||||
|
||||
if [ $warnings -eq 0 ] && [ $errors -eq 0 ]; then
|
||||
echo " ✅ All references valid"
|
||||
fi
|
||||
|
||||
# Check frontmatter
|
||||
echo ""
|
||||
echo "📝 Frontmatter Validation:"
|
||||
invalid=0
|
||||
|
||||
for file in $(find .claude -name "*.md" -path "*/epics/*" -o -path "*/prds/*" 2>/dev/null); do
|
||||
if ! grep -q "^---" "$file"; then
|
||||
echo " ⚠️ Missing frontmatter: $(basename "$file")"
|
||||
((invalid++))
|
||||
fi
|
||||
done
|
||||
|
||||
[ $invalid -eq 0 ] && echo " ✅ All files have frontmatter"
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo "📊 Validation Summary:"
|
||||
echo " Errors: $errors"
|
||||
echo " Warnings: $warnings"
|
||||
echo " Invalid files: $invalid"
|
||||
|
||||
if [ $errors -eq 0 ] && [ $warnings -eq 0 ] && [ $invalid -eq 0 ]; then
|
||||
echo ""
|
||||
echo "✅ System is healthy!"
|
||||
else
|
||||
echo ""
|
||||
echo "💡 Run /pm:clean to fix some issues automatically"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@@ -1,111 +0,0 @@
|
||||
# Structure — Break Down an Epic
|
||||
|
||||
This phase converts a technical epic into concrete, numbered task files with dependency and parallelization metadata.
|
||||
|
||||
---
|
||||
|
||||
## Epic Decomposition
|
||||
|
||||
**Trigger**: User wants to break an epic into actionable tasks.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify `.claude/epics/<name>/epic.md` exists with valid frontmatter.
|
||||
- If numbered task files (001.md, 002.md...) already exist in the epic directory, list them and confirm deletion before recreating.
|
||||
- If epic status is "completed", warn the user before proceeding.
|
||||
|
||||
### Process
|
||||
|
||||
Read the epic fully. Analyze for parallelism — which pieces of work can happen simultaneously without file conflicts?
|
||||
|
||||
**Task types to consider:**
|
||||
|
||||
- Setup: environment, scaffolding, dependencies
|
||||
- Data: models, schemas, migrations
|
||||
- API: endpoints, services, integration
|
||||
- UI: components, pages, styling
|
||||
- Tests: unit, integration, e2e
|
||||
- Docs: README, API docs, changelogs
|
||||
|
||||
**Parallelization strategy by epic size:**
|
||||
|
||||
- Small (<5 tasks): create sequentially
|
||||
- Medium (5–10 tasks): batch into 2–3 groups, spawn parallel Task agents
|
||||
- Large (>10 tasks): analyze dependencies first, launch parallel agents (max 5 concurrent), create dependent tasks after prerequisites
|
||||
|
||||
For parallel creation, use the Task tool:
|
||||
|
||||
```yaml
|
||||
Task:
|
||||
description: "Create task files batch N"
|
||||
subagent_type: "general-purpose"
|
||||
prompt: |
|
||||
Create task files for epic: <name>
|
||||
Tasks to create: [list 3-4 tasks]
|
||||
Save to: .claude/epics/<name>/001.md, 002.md, etc.
|
||||
Follow the task file format exactly.
|
||||
Return: list of files created.
|
||||
```
|
||||
|
||||
### Task File Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: <Task Title>
|
||||
status: open
|
||||
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
|
||||
updated: <same as created>
|
||||
github: (will be set on sync)
|
||||
depends_on: []
|
||||
parallel: true
|
||||
conflicts_with: []
|
||||
---
|
||||
|
||||
# Task: <Task Title>
|
||||
|
||||
## Description
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ]
|
||||
|
||||
## Technical Details
|
||||
|
||||
## Dependencies
|
||||
|
||||
## Effort Estimate
|
||||
- Size: XS/S/M/L/XL
|
||||
- Hours: N
|
||||
|
||||
## Definition of Done
|
||||
- [ ] Code implemented
|
||||
- [ ] Tests written and passing
|
||||
- [ ] Code reviewed
|
||||
```
|
||||
|
||||
**Numbering**: sequential 001.md, 002.md, etc. Tasks are renamed to GitHub issue numbers after sync — do not hard-code dependencies by filename, use the `depends_on` array.
|
||||
|
||||
### After Creating All Tasks
|
||||
|
||||
Append a summary to the epic file:
|
||||
|
||||
```markdown
|
||||
## Tasks Created
|
||||
- [ ] 001.md - <Title> (parallel: true/false)
|
||||
- [ ] 002.md - <Title> (parallel: true/false)
|
||||
|
||||
Total tasks: N
|
||||
Parallel tasks: N
|
||||
Sequential tasks: N
|
||||
Estimated total effort: N hours
|
||||
```
|
||||
|
||||
**After completion**: Confirm "✅ Created N tasks for epic: <name>" and suggest: "Ready to push to GitHub? Say: sync the <name> epic"
|
||||
|
||||
---
|
||||
|
||||
## Dependency Rules
|
||||
|
||||
- `depends_on` lists task numbers that must complete before this task can start.
|
||||
- `parallel: true` means the task can run concurrently with others it doesn't conflict with.
|
||||
- `conflicts_with` lists tasks that touch the same files — these cannot run in parallel.
|
||||
- Circular dependencies are an error — check before finalizing.
|
||||
@@ -1,315 +0,0 @@
|
||||
# Sync — Push to GitHub & Track Progress
|
||||
|
||||
This phase covers pushing local epics/tasks to GitHub as issues, syncing progress as comments, and closing issues when work is done.
|
||||
|
||||
---
|
||||
|
||||
## Repository Safety Check
|
||||
|
||||
**Always run this before any GitHub write operation:**
|
||||
|
||||
```bash
|
||||
remote_url=$(git remote get-url origin 2>/dev/null || echo "")
|
||||
if [[ "$remote_url" == *"automazeio/ccpm"* ]]; then
|
||||
echo "❌ Cannot sync to the CCPM template repository."
|
||||
echo "Update remote: git remote set-url origin https://github.com/YOUR/REPO.git"
|
||||
exit 1
|
||||
fi
|
||||
REPO=$(echo "$remote_url" | sed 's|.*github.com[:/]||' | sed 's|\.git$||')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Epic Sync — Push Epic + Tasks to GitHub
|
||||
|
||||
**Trigger**: User wants to push a local epic and its tasks to GitHub as issues.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify `.claude/epics/<name>/epic.md` exists.
|
||||
- Verify numbered task files exist — if none: "❌ No tasks to sync. Decompose the epic first."
|
||||
|
||||
### Process
|
||||
|
||||
**Step 1 — Create epic issue:**
|
||||
|
||||
Strip frontmatter from epic.md, then:
|
||||
|
||||
```bash
|
||||
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/<name>/epic.md > /tmp/epic-body.md
|
||||
epic_number=$(gh issue create \
|
||||
--repo "$REPO" \
|
||||
--title "Epic: <name>" \
|
||||
--body-file /tmp/epic-body.md \
|
||||
--label "epic,epic:<name>,feature" \
|
||||
--json number -q .number)
|
||||
```
|
||||
|
||||
**Step 2 — Create task sub-issues:**
|
||||
|
||||
Check if `gh-sub-issue` extension is available:
|
||||
|
||||
```bash
|
||||
if gh extension list | grep -q "yahsan2/gh-sub-issue"; then
|
||||
use_subissues=true
|
||||
fi
|
||||
```
|
||||
|
||||
For <5 tasks: create sequentially.
|
||||
For ≥5 tasks: use parallel Task agents (3-4 tasks per batch).
|
||||
|
||||
Per task:
|
||||
|
||||
```bash
|
||||
sed '1,/^---$/d; 1,/^---$/d' <task_file> > /tmp/task-body.md
|
||||
task_number=$(gh issue create \
|
||||
--repo "$REPO" \
|
||||
--title "<task_name>" \
|
||||
--body-file /tmp/task-body.md \
|
||||
--label "task,epic:<name>" \
|
||||
--json number -q .number)
|
||||
# or with sub-issues:
|
||||
# gh sub-issue create --parent $epic_number ...
|
||||
```
|
||||
|
||||
**Step 3 — Rename task files and update references:**
|
||||
|
||||
After all issues are created, rename `001.md` → `<issue_number>.md` and update all `depends_on`/`conflicts_with` arrays to use real issue numbers (not sequential numbers).
|
||||
|
||||
```bash
|
||||
# Build old→new mapping, then for each task file:
|
||||
sed -i.bak "s/\b001\b/<new_num_1>/g" <file> # repeat for each mapping
|
||||
mv 001.md <new_num>.md
|
||||
```
|
||||
|
||||
**Step 4 — Update frontmatter:**
|
||||
|
||||
```bash
|
||||
current_date=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
# Update github: and updated: fields in epic.md and each task file
|
||||
github_url="https://github.com/$REPO/issues/<number>"
|
||||
sed -i.bak "/^github:/c\\github: $github_url" <file>
|
||||
sed -i.bak "/^updated:/c\\updated: $current_date" <file>
|
||||
rm <file>.bak
|
||||
```
|
||||
|
||||
**Step 5 — Create worktree for the epic:**
|
||||
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
git worktree add ../epic-<name> -b epic/<name>
|
||||
```
|
||||
|
||||
**Step 6 — Create github-mapping.md:**
|
||||
|
||||
```markdown
|
||||
# GitHub Issue Mapping
|
||||
Epic: #<N> - https://github.com/<repo>/issues/<N>
|
||||
Tasks:
|
||||
- #<N>: <title> - https://github.com/<repo>/issues/<N>
|
||||
Synced: <datetime>
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
✅ Synced epic <name> to GitHub
|
||||
Epic: #<N>
|
||||
Tasks: N sub-issues
|
||||
Worktree: ../epic-<name>
|
||||
Next: "start working on issue <N>" or "start the <name> epic"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue Sync — Post Progress to GitHub
|
||||
|
||||
**Trigger**: User wants to sync local development progress to a GitHub issue as a comment.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify issue exists: `gh issue view <N> --json state`
|
||||
- Check `.claude/epics/*/updates/<N>/` exists with a `progress.md` file.
|
||||
- Check `last_sync` in progress.md — if synced <5 minutes ago, confirm before proceeding.
|
||||
|
||||
### Process
|
||||
|
||||
Gather updates from `.claude/epics/<epic>/updates/<N>/` (progress.md, notes.md, commits.md).
|
||||
|
||||
Format and post a comment:
|
||||
|
||||
```bash
|
||||
gh issue comment <N> --body-file /tmp/update-comment.md
|
||||
```
|
||||
|
||||
Comment format:
|
||||
|
||||
```markdown
|
||||
## 🔄 Progress Update - <date>
|
||||
|
||||
### ✅ Completed Work
|
||||
### 🔄 In Progress
|
||||
### 📝 Technical Notes
|
||||
### 📊 Acceptance Criteria Status
|
||||
### 🚀 Next Steps
|
||||
### ⚠️ Blockers
|
||||
|
||||
---
|
||||
*Progress: N% | Synced at <timestamp>*
|
||||
```
|
||||
|
||||
After posting: update `last_sync` in progress.md frontmatter, update `updated` in the task file.
|
||||
|
||||
Add sync marker to local files to prevent duplicate comments:
|
||||
|
||||
```markdown
|
||||
<!-- SYNCED: <datetime> -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Closing an Issue
|
||||
|
||||
**Trigger**: User marks a task complete.
|
||||
|
||||
### Process
|
||||
|
||||
1. Find the local task file (`.claude/epics/*/<N>.md`).
|
||||
2. Update frontmatter: `status: closed`, `updated: <now>`.
|
||||
3. Post completion comment:
|
||||
|
||||
```bash
|
||||
echo "✅ Task completed — all acceptance criteria met." | gh issue comment <N> --body-file -
|
||||
gh issue close <N>
|
||||
```
|
||||
1. Check off the task in the epic issue body:
|
||||
|
||||
```bash
|
||||
gh issue view <epic_N> --json body -q .body > /tmp/epic-body.md
|
||||
sed -i "s/- \[ \] #<N>/- [x] #<N>/" /tmp/epic-body.md
|
||||
gh issue edit <epic_N> --body-file /tmp/epic-body.md
|
||||
```
|
||||
1. Recalculate and update epic progress: `progress = closed_tasks / total_tasks * 100`
|
||||
|
||||
---
|
||||
|
||||
## Merging an Epic
|
||||
|
||||
**Trigger**: User wants to merge a completed epic back to main.
|
||||
|
||||
### Preflight
|
||||
|
||||
- Verify worktree `../epic-<name>` exists.
|
||||
- Check for uncommitted changes in the worktree — block if dirty.
|
||||
- Warn if any task issues are still open.
|
||||
|
||||
### Process
|
||||
|
||||
```bash
|
||||
# From worktree: run project tests if detectable
|
||||
cd ../epic-<name>
|
||||
# detect and run: npm test / pytest / cargo test / go test / etc.
|
||||
|
||||
# From main repo:
|
||||
git checkout main && git pull origin main
|
||||
git merge epic/<name> --no-ff -m "Merge epic: <name>"
|
||||
git push origin main
|
||||
|
||||
# Cleanup
|
||||
git worktree remove ../epic-<name>
|
||||
git branch -d epic/<name>
|
||||
git push origin --delete epic/<name>
|
||||
|
||||
# Archive
|
||||
mkdir -p .claude/epics/archived/
|
||||
mv .claude/epics/<name> .claude/epics/archived/
|
||||
|
||||
# Close GitHub issues
|
||||
epic_issue=$(grep 'github:' .claude/epics/archived/<name>/epic.md | grep -oE '[0-9]+$')
|
||||
gh issue close $epic_issue -c "Epic completed and merged to main"
|
||||
```
|
||||
|
||||
Update epic.md frontmatter: `status: completed`.
|
||||
|
||||
---
|
||||
|
||||
## Reporting a Bug Against a Completed Issue
|
||||
|
||||
**Trigger**: User finds a bug while testing a completed or in-progress issue — e.g. "found a bug in issue 42", "email validation is broken, came up while testing issue 42".
|
||||
|
||||
The workflow should stay automated: create a linked bug task without losing context from the original issue.
|
||||
|
||||
### Process
|
||||
|
||||
**Step 1 — Read the original issue for context:**
|
||||
|
||||
```bash
|
||||
gh issue view <original_N> --json title,body,labels
|
||||
```
|
||||
|
||||
Also read the local task file if it exists: `.claude/epics/*/<original_N>.md`
|
||||
|
||||
**Step 2 — Create a local bug task file:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Bug: <short description>
|
||||
status: open
|
||||
created: <run: date -u +"%Y-%m-%dT%H:%M:%SZ">
|
||||
updated: <same>
|
||||
github: (will be set on sync)
|
||||
depends_on: []
|
||||
parallel: false
|
||||
conflicts_with: []
|
||||
bug_for: <original_N>
|
||||
---
|
||||
|
||||
# Bug: <short description>
|
||||
|
||||
## Context
|
||||
Found while working on / testing issue #<original_N>: <original title>
|
||||
|
||||
## Description
|
||||
<what's broken>
|
||||
|
||||
## Steps to Reproduce
|
||||
<steps>
|
||||
|
||||
## Expected vs Actual
|
||||
- Expected:
|
||||
- Actual:
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] Bug is fixed
|
||||
- [ ] Original issue #<original_N> behaviour is unaffected
|
||||
|
||||
## Effort Estimate
|
||||
- Size: XS/S
|
||||
```
|
||||
|
||||
Save to `.claude/epics/<same_epic_as_original>/bug-<original_N>-<slug>.md`
|
||||
|
||||
**Step 3 — Create a linked GitHub issue:**
|
||||
|
||||
```bash
|
||||
gh issue create \
|
||||
--repo "$REPO" \
|
||||
--title "Bug: <short description>" \
|
||||
--body "$(cat /tmp/bug-body.md)" \
|
||||
--label "bug,epic:<epic_name>" \
|
||||
--json number -q .number
|
||||
```
|
||||
|
||||
The issue body should open with `Fixes / follow-up to #<original_N>` so GitHub auto-links them.
|
||||
|
||||
**Step 4 — Update the local file** with the GitHub issue number and rename to `<new_N>.md`.
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
✅ Bug issue created: #<new_N> — "Bug: <short description>"
|
||||
Linked to: #<original_N>
|
||||
Epic: <epic_name>
|
||||
|
||||
Start fixing it: "start working on issue <new_N>"
|
||||
```
|
||||
@@ -1,165 +0,0 @@
|
||||
# Track — Know Where Things Stand
|
||||
|
||||
Tracking operations use bash scripts directly for speed and consistency. The LLM is not needed for these — just run the script and present the output.
|
||||
|
||||
---
|
||||
|
||||
## Script-First Rule
|
||||
|
||||
All tracking operations have a corresponding bash script. Run the script; do not reconstruct the output manually.
|
||||
|
||||
Scripts live in `references/scripts/` relative to this skill, but need to run from the **project root** (where `.claude/` lives). Run them as:
|
||||
|
||||
```bash
|
||||
bash <skill_path>/references/scripts/<script>.sh [args]
|
||||
```
|
||||
|
||||
Or if ccpm is installed project-locally:
|
||||
|
||||
```bash
|
||||
bash ccpm/scripts/pm/<script>.sh [args]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Status
|
||||
|
||||
**Trigger**: "what's our status", "project status", "overview"
|
||||
|
||||
```bash
|
||||
bash references/scripts/status.sh
|
||||
```
|
||||
|
||||
Shows: active epics, open issues count, recent activity.
|
||||
|
||||
---
|
||||
|
||||
## Standup Report
|
||||
|
||||
**Trigger**: "standup", "daily standup", "what did we do", "morning update"
|
||||
|
||||
```bash
|
||||
bash references/scripts/standup.sh
|
||||
```
|
||||
|
||||
Shows: what was completed yesterday, what's in progress today, any blockers.
|
||||
|
||||
---
|
||||
|
||||
## List Epics
|
||||
|
||||
**Trigger**: "list epics", "show epics", "what epics do we have"
|
||||
|
||||
```bash
|
||||
bash references/scripts/epic-list.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Show Epic Details
|
||||
|
||||
**Trigger**: "show the <name> epic", "epic details for <name>"
|
||||
|
||||
```bash
|
||||
bash references/scripts/epic-show.sh <name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Epic Status
|
||||
|
||||
**Trigger**: "status of the <name> epic", "how far along is <name>"
|
||||
|
||||
```bash
|
||||
bash references/scripts/epic-status.sh <name>
|
||||
```
|
||||
|
||||
Shows: task completion breakdown, active agents, blocking issues.
|
||||
|
||||
---
|
||||
|
||||
## List PRDs
|
||||
|
||||
**Trigger**: "list PRDs", "what PRDs do we have", "show backlog"
|
||||
|
||||
```bash
|
||||
bash references/scripts/prd-list.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PRD Status
|
||||
|
||||
**Trigger**: "PRD status", "which PRDs are parsed", "what's in backlog"
|
||||
|
||||
```bash
|
||||
bash references/scripts/prd-status.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Search
|
||||
|
||||
**Trigger**: "search for <query>", "find issues about <topic>", "look for <term>"
|
||||
|
||||
```bash
|
||||
bash references/scripts/search.sh "<query>"
|
||||
```
|
||||
|
||||
Searches local task files, PRDs, and epics for the query term.
|
||||
|
||||
---
|
||||
|
||||
## What's In Progress
|
||||
|
||||
**Trigger**: "what's in progress", "what are we working on", "active work"
|
||||
|
||||
```bash
|
||||
bash references/scripts/in-progress.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
**Trigger**: "what should I work on next", "what's next", "next priority"
|
||||
|
||||
```bash
|
||||
bash references/scripts/next.sh
|
||||
```
|
||||
|
||||
Shows highest-priority open tasks with no blocking dependencies.
|
||||
|
||||
---
|
||||
|
||||
## What's Blocked
|
||||
|
||||
**Trigger**: "what's blocked", "any blockers", "what can't we move on"
|
||||
|
||||
```bash
|
||||
bash references/scripts/blocked.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validate Project State
|
||||
|
||||
**Trigger**: "validate", "check project state", "is everything consistent"
|
||||
|
||||
```bash
|
||||
bash references/scripts/validate.sh
|
||||
```
|
||||
|
||||
Checks: frontmatter consistency, orphaned files, missing GitHub links, dependency integrity.
|
||||
|
||||
---
|
||||
|
||||
## When Scripts Fail
|
||||
|
||||
If a script fails or the output needs interpretation (e.g., an error in the output, or the user asks "what does this mean"), then step in to explain. But always run the script first — don't guess at what status/standup output would look like.
|
||||
|
||||
If `.claude/` directory doesn't exist at all, the project hasn't been initialized. Direct the user to run:
|
||||
|
||||
```bash
|
||||
bash references/scripts/init.sh
|
||||
```
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
name: data-scientist
|
||||
description: Expert data scientist for advanced analytics, machine learning, and statistical modeling. Handles complex data analysis, predictive modeling, and business intelligence.
|
||||
---
|
||||
|
||||
## Use this skill when
|
||||
|
||||
- Working on data scientist tasks or workflows
|
||||
- Needing guidance, best practices, or checklists for data scientist
|
||||
|
||||
## Do not use this skill when
|
||||
|
||||
- The task is unrelated to data scientist
|
||||
- You need a different domain or tool outside this scope
|
||||
|
||||
## Instructions
|
||||
|
||||
- Clarify goals, constraints, and required inputs.
|
||||
- Apply relevant best practices and validate outcomes.
|
||||
- Provide actionable steps and verification.
|
||||
|
||||
You are a data scientist specializing in advanced analytics, machine learning, statistical modeling, and data-driven business insights.
|
||||
|
||||
## Purpose
|
||||
|
||||
Expert data scientist combining strong statistical foundations with modern machine learning techniques and business acumen. Masters the complete data science workflow from exploratory data analysis to production model deployment, with deep expertise in statistical methods, ML algorithms, and data visualization for actionable business insights.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Statistical Analysis & Methodology
|
||||
|
||||
- Descriptive statistics, inferential statistics, and hypothesis testing
|
||||
- Experimental design: A/B testing, multivariate testing, randomized controlled trials
|
||||
- Causal inference: natural experiments, difference-in-differences, instrumental variables
|
||||
- Time series analysis: ARIMA, Prophet, seasonal decomposition, forecasting
|
||||
- Survival analysis and duration modeling for customer lifecycle analysis
|
||||
- Bayesian statistics and probabilistic modeling with PyMC3, Stan
|
||||
- Statistical significance testing, p-values, confidence intervals, effect sizes
|
||||
- Power analysis and sample size determination for experiments
|
||||
|
||||
### Machine Learning & Predictive Modeling
|
||||
|
||||
- Supervised learning: linear/logistic regression, decision trees, random forests, XGBoost, LightGBM
|
||||
- Unsupervised learning: clustering (K-means, hierarchical, DBSCAN), PCA, t-SNE, UMAP
|
||||
- Deep learning: neural networks, CNNs, RNNs, LSTMs, transformers with PyTorch/TensorFlow
|
||||
- Ensemble methods: bagging, boosting, stacking, voting classifiers
|
||||
- Model selection and hyperparameter tuning with cross-validation and Optuna
|
||||
- Feature engineering: selection, extraction, transformation, encoding categorical variables
|
||||
- Dimensionality reduction and feature importance analysis
|
||||
- Model interpretability: SHAP, LIME, feature attribution, partial dependence plots
|
||||
|
||||
### Data Analysis & Exploration
|
||||
|
||||
- Exploratory data analysis (EDA) with statistical summaries and visualizations
|
||||
- Data profiling: missing values, outliers, distributions, correlations
|
||||
- Univariate and multivariate analysis techniques
|
||||
- Cohort analysis and customer segmentation
|
||||
- Market basket analysis and association rule mining
|
||||
- Anomaly detection and fraud detection algorithms
|
||||
- Root cause analysis using statistical and ML approaches
|
||||
- Data storytelling and narrative building from analysis results
|
||||
|
||||
### Programming & Data Manipulation
|
||||
|
||||
- Python ecosystem: pandas, NumPy, scikit-learn, SciPy, statsmodels
|
||||
- R programming: dplyr, ggplot2, caret, tidymodels, shiny for statistical analysis
|
||||
- SQL for data extraction and analysis: window functions, CTEs, advanced joins
|
||||
- Big data processing: PySpark, Dask for distributed computing
|
||||
- Data wrangling: cleaning, transformation, merging, reshaping large datasets
|
||||
- Database interactions: PostgreSQL, MySQL, BigQuery, Snowflake, MongoDB
|
||||
- Version control and reproducible analysis with Git, Jupyter notebooks
|
||||
- Cloud platforms: AWS SageMaker, Azure ML, GCP Vertex AI
|
||||
|
||||
### Data Visualization & Communication
|
||||
|
||||
- Advanced plotting with matplotlib, seaborn, plotly, altair
|
||||
- Interactive dashboards with Streamlit, Dash, Shiny, Tableau, Power BI
|
||||
- Business intelligence visualization best practices
|
||||
- Statistical graphics: distribution plots, correlation matrices, regression diagnostics
|
||||
- Geographic data visualization and mapping with folium, geopandas
|
||||
- Real-time monitoring dashboards for model performance
|
||||
- Executive reporting and stakeholder communication
|
||||
- Data storytelling techniques for non-technical audiences
|
||||
|
||||
### Business Analytics & Domain Applications
|
||||
|
||||
#### Marketing Analytics
|
||||
|
||||
- Customer lifetime value (CLV) modeling and prediction
|
||||
- Attribution modeling: first-touch, last-touch, multi-touch attribution
|
||||
- Marketing mix modeling (MMM) for budget optimization
|
||||
- Campaign effectiveness measurement and incrementality testing
|
||||
- Customer segmentation and persona development
|
||||
- Recommendation systems for personalization
|
||||
- Churn prediction and retention modeling
|
||||
- Price elasticity and demand forecasting
|
||||
|
||||
#### Financial Analytics
|
||||
|
||||
- Credit risk modeling and scoring algorithms
|
||||
- Portfolio optimization and risk management
|
||||
- Fraud detection and anomaly monitoring systems
|
||||
- Algorithmic trading strategy development
|
||||
- Financial time series analysis and volatility modeling
|
||||
- Stress testing and scenario analysis
|
||||
- Regulatory compliance analytics (Basel, GDPR, etc.)
|
||||
- Market research and competitive intelligence analysis
|
||||
|
||||
#### Operations Analytics
|
||||
|
||||
- Supply chain optimization and demand planning
|
||||
- Inventory management and safety stock optimization
|
||||
- Quality control and process improvement using statistical methods
|
||||
- Predictive maintenance and equipment failure prediction
|
||||
- Resource allocation and capacity planning models
|
||||
- Network analysis and optimization problems
|
||||
- Simulation modeling for operational scenarios
|
||||
- Performance measurement and KPI development
|
||||
|
||||
### Advanced Analytics & Specialized Techniques
|
||||
|
||||
- Natural language processing: sentiment analysis, topic modeling, text classification
|
||||
- Computer vision: image classification, object detection, OCR applications
|
||||
- Graph analytics: network analysis, community detection, centrality measures
|
||||
- Reinforcement learning for optimization and decision making
|
||||
- Multi-armed bandits for online experimentation
|
||||
- Causal machine learning and uplift modeling
|
||||
- Synthetic data generation using GANs and VAEs
|
||||
- Federated learning for distributed model training
|
||||
|
||||
### Model Deployment & Productionization
|
||||
|
||||
- Model serialization and versioning with MLflow, DVC
|
||||
- REST API development for model serving with Flask, FastAPI
|
||||
- Batch prediction pipelines and real-time inference systems
|
||||
- Model monitoring: drift detection, performance degradation alerts
|
||||
- A/B testing frameworks for model comparison in production
|
||||
- Containerization with Docker for model deployment
|
||||
- Cloud deployment: AWS Lambda, Azure Functions, GCP Cloud Run
|
||||
- Model governance and compliance documentation
|
||||
|
||||
### Data Engineering for Analytics
|
||||
|
||||
- ETL/ELT pipeline development for analytics workflows
|
||||
- Data pipeline orchestration with Apache Airflow, Prefect
|
||||
- Feature stores for ML feature management and serving
|
||||
- Data quality monitoring and validation frameworks
|
||||
- Real-time data processing with Kafka, streaming analytics
|
||||
- Data warehouse design for analytics use cases
|
||||
- Data catalog and metadata management for discoverability
|
||||
- Performance optimization for analytical queries
|
||||
|
||||
### Experimental Design & Measurement
|
||||
|
||||
- Randomized controlled trials and quasi-experimental designs
|
||||
- Stratified randomization and block randomization techniques
|
||||
- Power analysis and minimum detectable effect calculations
|
||||
- Multiple hypothesis testing and false discovery rate control
|
||||
- Sequential testing and early stopping rules
|
||||
- Matched pairs analysis and propensity score matching
|
||||
- Difference-in-differences and synthetic control methods
|
||||
- Treatment effect heterogeneity and subgroup analysis
|
||||
|
||||
## Behavioral Traits
|
||||
|
||||
- Approaches problems with scientific rigor and statistical thinking
|
||||
- Balances statistical significance with practical business significance
|
||||
- Communicates complex analyses clearly to non-technical stakeholders
|
||||
- Validates assumptions and tests model robustness thoroughly
|
||||
- Focuses on actionable insights rather than just technical accuracy
|
||||
- Considers ethical implications and potential biases in analysis
|
||||
- Iterates quickly between hypotheses and data-driven validation
|
||||
- Documents methodology and ensures reproducible analysis
|
||||
- Stays current with statistical methods and ML advances
|
||||
- Collaborates effectively with business stakeholders and technical teams
|
||||
|
||||
## Knowledge Base
|
||||
|
||||
- Statistical theory and mathematical foundations of ML algorithms
|
||||
- Business domain knowledge across marketing, finance, and operations
|
||||
- Modern data science tools and their appropriate use cases
|
||||
- Experimental design principles and causal inference methods
|
||||
- Data visualization best practices for different audience types
|
||||
- Model evaluation metrics and their business interpretations
|
||||
- Cloud analytics platforms and their capabilities
|
||||
- Data ethics, bias detection, and fairness in ML
|
||||
- Storytelling techniques for data-driven presentations
|
||||
- Current trends in data science and analytics methodologies
|
||||
|
||||
## Response Approach
|
||||
|
||||
1. **Understand business context** and define clear analytical objectives
|
||||
2. **Explore data thoroughly** with statistical summaries and visualizations
|
||||
3. **Apply appropriate methods** based on data characteristics and business goals
|
||||
4. **Validate results rigorously** through statistical testing and cross-validation
|
||||
5. **Communicate findings clearly** with visualizations and actionable recommendations
|
||||
6. **Consider practical constraints** like data quality, timeline, and resources
|
||||
7. **Plan for implementation** including monitoring and maintenance requirements
|
||||
8. **Document methodology** for reproducibility and knowledge sharing
|
||||
|
||||
## Example Interactions
|
||||
|
||||
- "Analyze customer churn patterns and build a predictive model to identify at-risk customers"
|
||||
- "Design and analyze A/B test results for a new website feature with proper statistical testing"
|
||||
- "Perform market basket analysis to identify cross-selling opportunities in retail data"
|
||||
- "Build a demand forecasting model using time series analysis for inventory planning"
|
||||
- "Analyze the causal impact of marketing campaigns on customer acquisition"
|
||||
- "Create customer segmentation using clustering techniques and business metrics"
|
||||
- "Develop a recommendation system for e-commerce product suggestions"
|
||||
- "Investigate anomalies in financial transactions and build fraud detection models"
|
||||
|
||||
## Limitations
|
||||
|
||||
- Use this skill only when the task clearly matches the scope described above.
|
||||
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||
|
||||
---
|
||||
|
||||
> **Provenance (A11 «ML / AI-разработка»):** vendored into Лидерра 2026-05-17 from
|
||||
> [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills)
|
||||
> `skills/data-scientist`. Skill content is licensed **CC BY 4.0**; repository
|
||||
> tooling is MIT. Aggregator frontmatter (`risk`/`source`/`date_added`) dropped on
|
||||
> vendor. See `docs/ml/README.md` for the A11 toolset and boundaries.
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
name: discovery-interview
|
||||
description: Структурированное интервью-discovery ПЕРЕД проектированием. Два режима. FEATURE — заказчик описывает проблему, боль или цель без готового решения («менеджеры жалуются на…», «сделки теряются», «хочу чтобы…»): JTBD-интервью вскрывает проблему до решения и отдаёт discovery-brief в brainstorming. SYSTEM — запрос ориентации по проекту («сориентируй», «где мы сейчас», «что в тулчейне / на карте», «catch-up по…»): синтез по мета-слою (карта, CLAUDE.md, MEMORY, Открытые_вопросы, Tooling, git log). SKIP — чёткий директив на реализацию («интегрируй X», «закрой находку Y», «поправь Z»): это не discovery. SKIP — анализ бизнес-процесса из кода или диагностика просадки измеримой метрики/конверсии («как устроен процесс X», «process discovery», «где узкое место», «почему просела конверсия»): это skill process-analysis. Используй при «discovery interview», «проведи discovery», «сориентируй по проекту» и при расплывчатом проблемном запросе, даже если слово «discovery» не названо.
|
||||
---
|
||||
|
||||
# Discovery Interview
|
||||
|
||||
Структурированное интервью, которое вскрывает **проблему** прежде, чем кто-либо
|
||||
начнёт проектировать решение. Два режима — FEATURE (интервью заказчика перед
|
||||
фичей) и SYSTEM (интервью-ориентация по состоянию проекта).
|
||||
|
||||
Зачем скил существует: запрос вида «менеджеры жалуются на X» или «хочу, чтобы Y» —
|
||||
это симптом, не задача. Уйдёшь сразу в дизайн — спроектируешь решение не той
|
||||
проблемы. Discovery interview удерживает разговор в проблемном поле ровно столько,
|
||||
сколько нужно, чтобы понять *настоящую* потребность, и только потом передаёт
|
||||
эстафету проектированию.
|
||||
|
||||
## Когда какой режим
|
||||
|
||||
| Запрос | Действие |
|
||||
|---|---|
|
||||
| Заказчик описал проблему / боль / цель без решения | режим **FEATURE** |
|
||||
| Заказчик просит сориентировать по проекту | режим **SYSTEM** |
|
||||
| Заказчик дал чёткий директив («сделай X», «интегрируй Y») | скил не нужен — работай напрямую |
|
||||
| Вопрос про устройство бизнес-процесса из кода | скил `process-analysis`, не этот |
|
||||
|
||||
## Несущий принцип — три слоя-источника
|
||||
|
||||
Этот скил соседствует со скилом `process-analysis` (раздел C10 карты). Чтобы не
|
||||
дублировать его, способности разведены по **слою данных**, с которым работают:
|
||||
|
||||
| Способность | Слой-источник | Метод |
|
||||
|---|---|---|
|
||||
| `process-analysis` | app-код — `routes/`, `app/Jobs`, `audit_*` | реконструкция бизнес-процесса из кода |
|
||||
| discovery-interview **FEATURE** | голова заказчика | интервью человека |
|
||||
| discovery-interview **SYSTEM** | мета-слой — карта, CLAUDE.md, MEMORY, Открытые_вопросы, Tooling, git log | интервью + синтез |
|
||||
|
||||
Правило разведения: если ответ добывается **чтением кода** — это `process-analysis`.
|
||||
Если ответ лежит в голове заказчика или в управляющих документах — это
|
||||
discovery-interview.
|
||||
|
||||
## Режим FEATURE
|
||||
|
||||
### Триггер
|
||||
|
||||
Заказчик описывает проблему, боль, раздражение или цель — но НЕ готовое решение.
|
||||
Признаки: «менеджеры жалуются…», «X теряется», «неудобно делать Y», «хочу, чтобы…»,
|
||||
«было бы хорошо, если…».
|
||||
|
||||
### SKIP
|
||||
|
||||
Не запускай FEATURE, если запрос — чёткий директив на реализацию: «интегрируй X»,
|
||||
«закрой находку Y», «поправь Z», «добавь endpoint». Проблема уже понята заказчиком,
|
||||
discovery только затормозит. Работай напрямую — или через `brainstorming`, если
|
||||
дизайн решения нетривиален.
|
||||
|
||||
Не запускай FEATURE и если запрос — **диагностика просадки измеримой метрики или
|
||||
конверсии** («почему падает конверсия B2», «где теряем в воронке», «почему лиды не
|
||||
доходят до оплаты»). Ответ там добывается анализом кода и audit-данных — это скил
|
||||
`process-analysis`. FEATURE — про UX-боль и желаемые возможности, не про диагностику
|
||||
чисел.
|
||||
|
||||
### Процесс
|
||||
|
||||
1. **Один вопрос за раз.** Не вываливай список — это интервью, не анкета. Ответ на
|
||||
первый вопрос определяет второй.
|
||||
2. **Спрашивай про прошлое поведение, не про гипотетику.** «Расскажи, как ты делал
|
||||
это в последний раз» сильнее, чем «как бы ты хотел». Люди плохо предсказывают
|
||||
своё поведение и точно помнят прошлое.
|
||||
3. **Копай до корня — «5 почему».** Первая названная проблема обычно симптом.
|
||||
4. **Не задавай наводящих вопросов.** «Тебе мешает отсутствие фильтра?» подсказывает
|
||||
ответ. Спроси открыто: «что именно замедляет тебя на этом экране?».
|
||||
5. **Поняв проблему — собери discovery-brief и остановись.** Не проектируй решение —
|
||||
это работа `brainstorming`.
|
||||
|
||||
Банк вопросов по шагам JTBD — `references/jtbd-questions.md`.
|
||||
|
||||
### Артефакт — discovery-brief
|
||||
|
||||
Проблема · JTBD (какую работу заказчик «нанимает» решение сделать) · Текущий обходной
|
||||
путь · Цена боли (время / деньги / частота) · Сигнал успеха (как поймём, что закрыто)
|
||||
· Ограничения. Шаблон — `docs/discovery/templates/discovery-brief.md`.
|
||||
|
||||
### Хэндофф
|
||||
|
||||
discovery-brief — это вход для `brainstorming`. Передай brief как готовую проблемную
|
||||
секцию: `brainstorming` берёт её и переходит к решению — он **не перезадаёт** уже
|
||||
выясненные вопросы. discovery-interview отвечает за «что за проблема», brainstorming —
|
||||
за «что построим». Отдельным файлом FEATURE-brief не сохраняется — он вливается в
|
||||
спеку brainstorming.
|
||||
|
||||
## Режим SYSTEM
|
||||
|
||||
### Триггер
|
||||
|
||||
Заказчик просит сориентировать его по состоянию проекта: «сориентируй», «где мы
|
||||
сейчас», «что у нас по X», «что в тулчейне / на карте», «catch-up».
|
||||
|
||||
### SKIP
|
||||
|
||||
Не запускай SYSTEM, если вопрос про устройство **бизнес-процесса** («как устроен
|
||||
процесс сделок», «process discovery», «где узкое место в воронке») — это скил
|
||||
`process-analysis`, он читает код. SYSTEM отвечает на «где мы в проекте», не «как
|
||||
работает процесс X».
|
||||
|
||||
### Процесс
|
||||
|
||||
1. **Короткое уточнение scope** — что именно ориентировать? Весь проект, конкретный
|
||||
раздел, тулчейн, открытые вопросы? Без scope ответ будет рыхлым.
|
||||
2. **Синтез по мета-слою:** карта `docs/automation-graph.html`, `CLAUDE.md`, MEMORY,
|
||||
`docs/Открытые_вопросы_*.md`, `docs/Tooling_*.md`, `git log`.
|
||||
3. **Запрет:** не читай `app/`-код для реконструкции процессов — это исключительный
|
||||
метод `process-analysis`. SYSTEM работает только с мета-слоем.
|
||||
4. **Выдай синтез**, а не пересказ документа целиком — ответ на запрос ориентации с
|
||||
пинами на источники.
|
||||
|
||||
### Артефакт — system-snapshot
|
||||
|
||||
Если ориентация существенная — сохрани `docs/discovery/YYYY-MM-DD-<тема>.md` по
|
||||
шаблону `docs/discovery/templates/system-snapshot.md`. Мелкий устный ответ файла не
|
||||
требует.
|
||||
|
||||
## JTBD-дисциплина (общая для обоих режимов)
|
||||
|
||||
- **Один вопрос за раз** — интервью, не анкета.
|
||||
- **Прошлое, не гипотетика** — «когда это случилось в последний раз?».
|
||||
- **«5 почему»** — корень, не симптом.
|
||||
- **Не наводи** — открытые вопросы, без подсказанного ответа.
|
||||
- **Слушай, не защищай** — если заказчик критикует существующее, не оправдывай его,
|
||||
копай дальше.
|
||||
|
||||
## Границы
|
||||
|
||||
- **`brainstorming`** — проектирование решения. discovery-interview вскрывает проблему
|
||||
и передаёт brief; brainstorming проектирует. Не дублируй его вопросы.
|
||||
- **`process-analysis`** (раздел C10) — анализ as-is бизнес-процесса из кода и
|
||||
диагностика метрик/конверсии. Если ответ требует чтения `routes/` / `app/Jobs` /
|
||||
`audit_*` или расчёта метрик процесса — это `process-analysis`, не этот скил.
|
||||
- **`audit-portal`** — качественный вердикт о здоровье портала. SYSTEM даёт
|
||||
ориентацию («где мы»), не вердикт («здорово ли»).
|
||||
- **Интервью конечных пользователей Лидерры** — вне этого скила (defer post-Б-1; для
|
||||
методологии user research — `design:user-research`).
|
||||
@@ -1,26 +0,0 @@
|
||||
{
|
||||
"skill_name": "discovery-interview",
|
||||
"note": "Триггер-eval: should_trigger=true → должен вызваться discovery-interview; false → должен сработать другой инструмент (expected_skill). Особое внимание — near-miss к process-analysis (C10).",
|
||||
"evals": [
|
||||
{ "id": 1, "should_trigger": true, "expected_skill": "discovery-interview/FEATURE", "prompt": "менеджеры жалуются что не видят, какие сделки сегодня надо обзвонить — каждое утро роются в фильтрах вручную" },
|
||||
{ "id": 2, "should_trigger": false, "expected_skill": "process-analysis", "prompt": "у меня ощущение что лиды из B2 проседают по конверсии, но не пойму почему — хочу разобраться" },
|
||||
{ "id": 3, "should_trigger": true, "expected_skill": "discovery-interview/FEATURE", "prompt": "хочу чтобы поставщики сами видели свой баланс, а то постоянно пишут в поддержку спрашивают" },
|
||||
{ "id": 4, "should_trigger": true, "expected_skill": "discovery-interview/FEATURE", "prompt": "проведи discovery interview по идее напоминаний — я пока сам не уверен что именно нужно" },
|
||||
{ "id": 5, "should_trigger": true, "expected_skill": "discovery-interview/FEATURE", "prompt": "не нравится как сейчас сделана выгрузка отчётов, неудобно, давай покопаем что не так" },
|
||||
{ "id": 6, "should_trigger": true, "expected_skill": "discovery-interview/FEATURE", "prompt": "клиенты часто отваливаются на этапе оплаты, надо понять что там за проблема" },
|
||||
{ "id": 7, "should_trigger": true, "expected_skill": "discovery-interview/SYSTEM", "prompt": "сориентируй меня — где мы сейчас по проекту, что закрыто что нет" },
|
||||
{ "id": 8, "should_trigger": true, "expected_skill": "discovery-interview/SYSTEM", "prompt": "что у нас вообще в тулчейне по безопасности, я запутался" },
|
||||
{ "id": 9, "should_trigger": true, "expected_skill": "discovery-interview/SYSTEM", "prompt": "вернулся после недели отсутствия, сделай catch-up что произошло по проекту" },
|
||||
{ "id": 10, "should_trigger": true, "expected_skill": "discovery-interview/SYSTEM", "prompt": "что там на карте в разделе биллинга, какие узлы" },
|
||||
{ "id": 11, "should_trigger": false, "expected_skill": "process-analysis", "prompt": "как устроен процесс обработки сделки от создания до закрытия — пройди по коду" },
|
||||
{ "id": 12, "should_trigger": false, "expected_skill": "process-analysis", "prompt": "где узкое место в воронке лидов, какой шаг тормозит" },
|
||||
{ "id": 13, "should_trigger": false, "expected_skill": "process-analysis", "prompt": "сделай process discovery по джобам импорта лидов" },
|
||||
{ "id": 14, "should_trigger": false, "expected_skill": "process-analysis", "prompt": "посчитай метрики процесса: cycle time по статусам сделок" },
|
||||
{ "id": 15, "should_trigger": false, "expected_skill": "directive (no skill)", "prompt": "интегрируй openapi-mcp-server в .mcp.json" },
|
||||
{ "id": 16, "should_trigger": false, "expected_skill": "directive (no skill)", "prompt": "закрой находку аудита G7 по AdminBillingController" },
|
||||
{ "id": 17, "should_trigger": false, "expected_skill": "systematic-debugging", "prompt": "поправь падающий тест RlsSmokeTest, он валится на teardown" },
|
||||
{ "id": 18, "should_trigger": false, "expected_skill": "directive (no skill)", "prompt": "добавь endpoint POST /api/deals/{id}/archive" },
|
||||
{ "id": 19, "should_trigger": false, "expected_skill": "write-spec / brainstorming", "prompt": "напиши спеку для фичи мультивалютного биллинга" },
|
||||
{ "id": 20, "should_trigger": false, "expected_skill": "audit-portal", "prompt": "проведи полный аудит портала перед релизом" }
|
||||
]
|
||||
}
|
||||
@@ -1,45 +0,0 @@
|
||||
# Банк вопросов JTBD — режим FEATURE
|
||||
|
||||
Вопросы для discovery-интервью. Задавать **по одному**, адаптируя формулировку под
|
||||
контекст. Все вопросы — про прошлое поведение, без подсказанного ответа.
|
||||
|
||||
## 1. Вскрыть проблему
|
||||
|
||||
- Расскажи, что произошло в последний раз, когда [ситуация]?
|
||||
- Что именно тебя в этом раздражало или замедляло?
|
||||
- Как часто это случается?
|
||||
|
||||
## 2. Текущий обходной путь
|
||||
|
||||
- Как ты решаешь это сейчас?
|
||||
- Что делаешь, когда [проблема] происходит?
|
||||
- Кто ещё это делает и как?
|
||||
|
||||
## 3. Цена боли
|
||||
|
||||
- Сколько времени это съедает за неделю?
|
||||
- Что случается, если не сделать это вовремя?
|
||||
- Были случаи, когда из-за этого что-то сорвалось?
|
||||
|
||||
## 4. JTBD — какую работу «нанимают» решение сделать
|
||||
|
||||
- Если бы это работало идеально — что бы ты перестал делать руками?
|
||||
- Какого результата ты на самом деле добиваешься?
|
||||
|
||||
## 5. Сигнал успеха
|
||||
|
||||
- Как ты поймёшь, что проблема закрыта?
|
||||
- Что должно стать видимо иначе?
|
||||
|
||||
## 6. Ограничения
|
||||
|
||||
- Что нельзя ломать или менять?
|
||||
- Есть ли срок?
|
||||
|
||||
## Антипаттерны
|
||||
|
||||
- **Наводящий вопрос** («тебе мешает отсутствие X?») — подсказывает ответ; заказчик
|
||||
согласится из вежливости.
|
||||
- **Гипотетика** («как бы ты хотел?») — люди плохо предсказывают своё поведение.
|
||||
- **Список вопросов разом** — это анкета, не интервью; теряется ветвление по ответам.
|
||||
- **Принять первый ответ за корень** — копай «5 почему» до настоящей причины.
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
name: laravel-backend-patterns
|
||||
description: Backend-конвенции Лидерры (Laravel 13) — как писать controller→service→job, RLS-aware Eloquent, деньги через bcmath/LedgerService, идемпотентные джобы, partition-aware запросы. Используй при «как писать backend в Лидерре», «паттерн контроллера/сервиса/джоба», scaffolding новой backend-фичи. НЕ для generic-паттернов (architecture-patterns #38), аудита денег (billing-audit #62), РСБУ/налогов (ru-tax-accounting), security-аудита (D3).
|
||||
---
|
||||
|
||||
# Laravel Backend Patterns — конвенции backend-кода Лидерры
|
||||
|
||||
Проектный скил, который описывает **как здесь пишут backend**, а не как рекомендует generic-Laravel.
|
||||
При scaffolding новой фичи или ревью кода — сверяться с пятью конвенциями ниже.
|
||||
Детальные примеры с образцами кода и антипаттернами — в `references/conventions.md`.
|
||||
|
||||
## 1. Слоистость: Controller → FormRequest → Service → Job
|
||||
|
||||
Контроллер тонкий: принимает FormRequest, делегирует Service, возвращает JSON-ответ.
|
||||
Бизнес-логика — в Service; асинхронная работа — в Job.
|
||||
Слои зафиксированы в `app/deptrac.yaml` (13 слоёв, pre-commit gate job 10).
|
||||
|
||||
Подробнее: `references/conventions.md` §1.
|
||||
|
||||
## 2. RLS-aware Eloquent и middleware `tenant`
|
||||
|
||||
Middleware `SetTenantContext` оборачивает HTTP-запрос в транзакцию и выполняет
|
||||
`SET LOCAL app.current_tenant_id = X`, обеспечивая RLS-изоляцию между tenant'ами.
|
||||
**КРИТИЧНО**: очередные джобы выполняются под ролью `crm_supplier_worker` (BYPASSRLS),
|
||||
поэтому RLS не фильтрует. Каждый запрос в джобе **обязан** содержать явный
|
||||
`where('tenant_id', $tenantId)` или устанавливать `SET LOCAL` вручную внутри транзакции.
|
||||
|
||||
Подробнее: `references/conventions.md` §2.
|
||||
|
||||
## 3. Деньги — только через bcmath и LedgerService
|
||||
|
||||
Все денежные операции — `bcadd` / `bcsub` / `bcmul` / `bcdiv` / `bccomp` со строковыми операндами
|
||||
и фиксированным `scale`. Никаких операторов `+` / `-` / `*` / `/` над деньгами, никакого `float`.
|
||||
Точка входа для биллингового списания — `LedgerService::chargeForDelivery()`.
|
||||
Аудит денежных инвариантов кода — скил `billing-audit` (#62); здесь — только конвенция написания.
|
||||
|
||||
Подробнее: `references/conventions.md` §3.
|
||||
|
||||
## 4. Идемпотентные джобы через advisory lock
|
||||
|
||||
Повторный запуск джоба не должен дублировать результат.
|
||||
Паттерн: `pg_advisory_xact_lock(composite_bigint)` внутри транзакции — сериализует
|
||||
конкурентные обработки одного (tenant_id, source_crm_id). Дополнительно: `lockForUpdate`
|
||||
на строку Tenant защищает баланс от TOCTOU при конкурентных списаниях.
|
||||
|
||||
Подробнее: `references/conventions.md` §4.
|
||||
|
||||
## 5. Partition-aware запросы для `deals` и `supplier_lead_costs`
|
||||
|
||||
Таблицы `deals` и `supplier_lead_costs` секционированы по `RANGE (received_at)`.
|
||||
Запросы к этим таблицам должны включать условие по `received_at` (или `created_at`
|
||||
для `supplier_lead_costs`) — это включает pruning и предотвращает full-scan всех партиций.
|
||||
|
||||
Подробнее: `references/conventions.md` §5.
|
||||
|
||||
## Связано
|
||||
|
||||
- `billing-audit` #62 — аудит денежной корректности (I1–I5 инварианты).
|
||||
- `architecture-patterns` #38 — общие паттерны архитектуры (не Лидерра-специфика).
|
||||
- Boost #10 — Eloquent introspection, документация Laravel 13.
|
||||
- Larastan #12 — статанализ PHP (ловит float-арифметику на деньгах).
|
||||
- ADR-005 — deptrac architecture-fitness gate.
|
||||
@@ -1,10 +0,0 @@
|
||||
{
|
||||
"skill": "laravel-backend-patterns",
|
||||
"cases": [
|
||||
{"prompt": "как написать контроллер для новой backend-фичи в Лидерре", "should_trigger": true},
|
||||
{"prompt": "как правильно списать деньги в джобе под crm_supplier_worker", "should_trigger": true},
|
||||
{"prompt": "проверь, не теряются ли копейки в списании", "should_trigger": false, "expected": "billing-audit"},
|
||||
{"prompt": "опиши Clean Architecture в общем", "should_trigger": false, "expected": "architecture-patterns"},
|
||||
{"prompt": "учёт выручки по РСБУ", "should_trigger": false, "expected": "ru-tax-accounting"}
|
||||
]
|
||||
}
|
||||
@@ -1,280 +0,0 @@
|
||||
# Backend-конвенции Лидерры — детальный справочник
|
||||
|
||||
Образцы ниже — реальный код из `app/` (Laravel 13, PHP 8.3).
|
||||
Указаны конкретные `file:line` на момент 20.05.2026.
|
||||
|
||||
---
|
||||
|
||||
## §1. Слоистость: Controller → FormRequest → Service → Job
|
||||
|
||||
### Правило
|
||||
|
||||
Контроллер принимает FormRequest (валидация), делегирует Service (бизнес-логика),
|
||||
при необходимости Service dispatch'ит Job (асинхрон). Контроллер не содержит бизнес-логики.
|
||||
Слои задокументированы в `app/deptrac.yaml` — 13 слоёв:
|
||||
Controller, Request, Resource, Middleware, Service, Job, Console, Repository,
|
||||
Model, Mail, Rule, Exception, Provider.
|
||||
Допустимые направления зависимостей — только вниз по иерархии (deptrac gate, lefthook job 10).
|
||||
|
||||
### Образец из кода
|
||||
|
||||
`app/app/Http/Controllers/Api/ProjectController.php:87–90` — контроллер тонкий:
|
||||
|
||||
```php
|
||||
/** POST /api/projects */
|
||||
public function store(StoreProjectRequest $request): JsonResponse
|
||||
{
|
||||
$project = $this->projects->create($request->user()->tenant, $request->validated());
|
||||
|
||||
return response()->json(['data' => new ProjectResource($project)], 201);
|
||||
}
|
||||
```
|
||||
|
||||
`app/app/Http/Requests/StoreProjectRequest.php:18–44` — вся валидация в FormRequest:
|
||||
|
||||
```php
|
||||
public function rules(): array
|
||||
{
|
||||
$base = [
|
||||
'name' => ['required', 'string', 'max:255'],
|
||||
'signal_type' => ['required', Rule::in(['site', 'call', 'sms'])],
|
||||
'daily_limit_target' => ['required', 'integer', 'min:1', 'max:10000'],
|
||||
'regions' => ['present', 'array'],
|
||||
'regions.*' => ['integer', 'between:1,89'],
|
||||
'delivery_days_mask' => ['required', 'integer', 'min:1', 'max:127'],
|
||||
];
|
||||
// ... conditional rules by signal_type
|
||||
return $base;
|
||||
}
|
||||
```
|
||||
|
||||
`app/app/Services/Billing/LedgerService.php` — бизнес-логика в Service.
|
||||
`app/app/Jobs/ProcessWebhookJob.php` — асинхрон в Job.
|
||||
|
||||
### Антипаттерн
|
||||
|
||||
```php
|
||||
// ПЛОХО: бизнес-логика в контроллере
|
||||
public function store(Request $request): JsonResponse
|
||||
{
|
||||
$tier = PricingTier::where('min_leads', '<=', $count)->orderBy('min_leads', 'desc')->first();
|
||||
$price = $tier->price_per_lead_kopecks * $count; // float-арифметика + логика тира прямо здесь
|
||||
Deal::create([...]);
|
||||
return response()->json(['ok' => true]);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §2. RLS-aware Eloquent и middleware `tenant`
|
||||
|
||||
### Правило
|
||||
|
||||
Middleware `SetTenantContext` (`app/app/Http/Middleware/SetTenantContext.php`) оборачивает
|
||||
каждый HTTP-запрос в транзакцию и выполняет `SET LOCAL app.current_tenant_id = X`,
|
||||
после чего RLS-политики PostgreSQL автоматически фильтруют строки по tenant.
|
||||
|
||||
**КРИТИЧНО для джобов**: очередные джобы Laravel выполняются в отдельном процессе вне
|
||||
HTTP-стека. Роль `crm_supplier_worker` (connection `pgsql_supplier`) имеет атрибут
|
||||
BYPASSRLS — RLS-политики для неё **не применяются**. Любой запрос в таком джобе без
|
||||
явного `where('tenant_id', $tenantId)` вернёт строки всех tenant'ов.
|
||||
|
||||
Правило: в каждом джобе либо устанавливай `SET LOCAL` внутри транзакции (паттерн
|
||||
`ProcessWebhookJob`/`ImportLeadsJob`), либо добавляй явный `where('tenant_id', ...)`.
|
||||
|
||||
### Образец из кода
|
||||
|
||||
`app/app/Http/Middleware/SetTenantContext.php:36–43` — HTTP-путь:
|
||||
|
||||
```php
|
||||
DB::beginTransaction();
|
||||
try {
|
||||
DB::statement('SET LOCAL app.current_tenant_id = ' . $tenantId);
|
||||
$response = $next($request);
|
||||
DB::commit();
|
||||
return $response;
|
||||
} catch (\Throwable $e) {
|
||||
DB::rollBack();
|
||||
throw $e;
|
||||
}
|
||||
```
|
||||
|
||||
`app/app/Jobs/ImportLeadsJob.php:92–96` — джоб устанавливает `SET LOCAL` вручную:
|
||||
|
||||
```php
|
||||
return DB::transaction(function (): ?ImportLog {
|
||||
DB::statement('SET LOCAL app.current_tenant_id = ' . $this->tenantId);
|
||||
return ImportLog::query()->find($this->importLogId);
|
||||
});
|
||||
```
|
||||
|
||||
`app/app/Jobs/ProcessWebhookJob.php:80–86` — аналогичный паттерн в webhook-джобе:
|
||||
|
||||
```php
|
||||
DB::transaction(function () use ($duplicateDetector): void {
|
||||
DB::statement('SET LOCAL app.current_tenant_id = ' . $this->tenantId);
|
||||
$tenant = Tenant::query()
|
||||
->whereKey($this->tenantId)
|
||||
->lockForUpdate()
|
||||
->first();
|
||||
```
|
||||
|
||||
### Антипаттерн
|
||||
|
||||
```php
|
||||
// ПЛОХО: джоб под crm_supplier_worker без SET LOCAL и без where tenant_id
|
||||
// → вернёт все строки всех tenant'ов (BYPASSRLS не фильтрует)
|
||||
public function handle(): void
|
||||
{
|
||||
$logs = ImportLog::query()->where('status', 'pending')->get(); // ВСЕ tenant'ы!
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §3. Деньги — только через bcmath и LedgerService
|
||||
|
||||
### Правило
|
||||
|
||||
Все арифметические операции с деньгами (рубли, копейки) — исключительно через
|
||||
функции `bcmath` с явным `scale`. Операнды передаются строками.
|
||||
Никаких PHP `float`, никакого `+` / `-` / `*` / `/` над денежными значениями.
|
||||
|
||||
Точка входа для списания за лид — `LedgerService::chargeForDelivery()`.
|
||||
Этот метод реализует dual-balance flow (prepaid-лиды → `balance_leads`, рубли → `balance_rub`).
|
||||
Вызывается **внутри открытой транзакции** с `lockForUpdate(Tenant)` — см. §4.
|
||||
|
||||
Аудит денежных инвариантов (I1–I5) — скил `billing-audit` (#62). Здесь — конвенция написания.
|
||||
|
||||
### Образец из кода
|
||||
|
||||
`app/app/Services/Billing/LedgerService.php:64–65` — конвертация копеек в рубли:
|
||||
|
||||
```php
|
||||
$amountRub = bcdiv((string) $priceKopecks, '100', 2);
|
||||
$newBalanceRub = bcsub((string) $lockedTenant->balance_rub, $amountRub, 2);
|
||||
```
|
||||
|
||||
`app/app/Services/Billing/LedgerService.php:124–125` — сравнение балансов:
|
||||
|
||||
```php
|
||||
$balanceKopecks = bcmul((string) $tenant->balance_rub, '100', 0);
|
||||
if (bccomp($balanceKopecks, (string) $priceKopecks, 0) >= 0) {
|
||||
return 'rub';
|
||||
}
|
||||
```
|
||||
|
||||
### Антипаттерн
|
||||
|
||||
```php
|
||||
// ПЛОХО: float-арифметика теряет копейки
|
||||
$price = $tier->price_per_lead_kopecks / 100; // float
|
||||
$newBalance = $tenant->balance_rub - $price; // потеря точности при накоплении
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §4. Идемпотентные джобы через advisory lock
|
||||
|
||||
### Правило
|
||||
|
||||
Повторный запуск джоба (ретрай, краш, дубль cron) не должен создавать дублирующие
|
||||
записи. Паттерн: `pg_advisory_xact_lock(bigint)` внутри транзакции сериализует все
|
||||
конкурентные обработки одного (tenant_id, source_crm_id).
|
||||
|
||||
Дополнительно для мутаций баланса: `lockForUpdate` на строку Tenant — защита от
|
||||
TOCTOU (между чтением баланса и его обновлением другой воркер не должен изменить значение).
|
||||
|
||||
### Образец из кода
|
||||
|
||||
`app/app/Jobs/ProcessWebhookJob.php:293–296` — advisory lock перед upsert:
|
||||
|
||||
```php
|
||||
// pg_advisory_xact_lock(bigint): верхние 32 бита = tenant_id, нижние 32 = source_crm_id
|
||||
$lockKey = (($tenant->id & 0xFFFFFFFF) << 32) | ($sourceCrmId & 0xFFFFFFFF);
|
||||
DB::statement('SELECT pg_advisory_xact_lock(?)', [$lockKey]);
|
||||
```
|
||||
|
||||
`app/app/Services/Import/HistoricalImportService.php:145–147` — тот же паттерн в сервисе:
|
||||
|
||||
```php
|
||||
// advisory lock (tenant_id, source_crm_id) — сериализует upsert (§6.5)
|
||||
$lockKey = (($tenantId & 0xFFFFFFFF) << 32) | ($row->sourceCrmId & 0xFFFFFFFF);
|
||||
DB::statement('SELECT pg_advisory_xact_lock(?)', [$lockKey]);
|
||||
```
|
||||
|
||||
`app/app/Jobs/RouteSupplierLeadJob.php:210–213` — lockForUpdate на Tenant перед списанием:
|
||||
|
||||
```php
|
||||
$tenant = Tenant::query()
|
||||
->whereKey($project->tenant_id)
|
||||
->lockForUpdate()
|
||||
->firstOrFail();
|
||||
```
|
||||
|
||||
Для overlap-защиты долгоживущих джобов (cron) — `Cache::lock` (Redis):
|
||||
`app/app/Jobs/Supplier/CsvReconcileJob.php:69–74`:
|
||||
|
||||
```php
|
||||
$lock = $lockStore->lock(self::LOCK_NAME, self::LOCK_TTL_SECONDS);
|
||||
if (! $lock->get()) {
|
||||
Log::info('csv_reconcile.skipped_overlap');
|
||||
return;
|
||||
}
|
||||
```
|
||||
|
||||
### Антипаттерн
|
||||
|
||||
```php
|
||||
// ПЛОХО: нет lock — два конкурентных воркера создают два deal для одного vid
|
||||
$existing = Deal::where('source_crm_id', $vid)->where('tenant_id', $tenantId)->first();
|
||||
if (!$existing) {
|
||||
Deal::create([...]); // race condition: оба воркера видят null и оба создают
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## §5. Partition-aware запросы для `deals` и `supplier_lead_costs`
|
||||
|
||||
### Правило
|
||||
|
||||
Таблицы `deals` и `supplier_lead_costs` секционированы по `PARTITION BY RANGE (received_at)`.
|
||||
Запросы должны содержать условие по `received_at` (ключ партиционирования) — это позволяет
|
||||
PostgreSQL выполнять partition pruning и не сканировать все партиции.
|
||||
Запрос без `WHERE received_at ...` делает full-scan всех партиций.
|
||||
|
||||
### Образец из кода
|
||||
|
||||
`db/schema.sql:1658` — партиционирование `deals`:
|
||||
|
||||
```sql
|
||||
) PARTITION BY RANGE (received_at);
|
||||
```
|
||||
|
||||
`db/schema.sql:2361` — партиционирование `supplier_lead_costs`:
|
||||
|
||||
```sql
|
||||
) PARTITION BY RANGE (received_at);
|
||||
```
|
||||
|
||||
`app/app/Services/DuplicateDetector.php:49` — запрос к `deals` с ключом партиции:
|
||||
|
||||
```php
|
||||
->where('received_at', '>=', $windowStart)
|
||||
```
|
||||
|
||||
`app/app/Jobs/Supplier/CsvReconcileJob.php:113` — запрос к `supplier_leads` с ключом:
|
||||
|
||||
```php
|
||||
->where('received_at', '>=', $windowStart)
|
||||
```
|
||||
|
||||
### Антипаттерн
|
||||
|
||||
```php
|
||||
// ПЛОХО: запрос к deals без received_at — full-scan всех партиций
|
||||
$deals = Deal::where('tenant_id', $tenantId)
|
||||
->where('phone', $phone)
|
||||
->get(); // сканирует deals_2026_05, deals_2026_06, ... все партиции
|
||||
```
|
||||
@@ -1,7 +0,0 @@
|
||||
Copyright 2026 WH-2099
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
name: mermaid
|
||||
description: Generate Mermaid diagrams from user requirements. Supports flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, and 18 more diagram types.
|
||||
allowed-tools: Read Write Edit
|
||||
metadata:
|
||||
argument-hint: "[diagram description or requirements]"
|
||||
---
|
||||
|
||||
# Mermaid Diagram Generator
|
||||
|
||||
Generate high-quality Mermaid diagram code based on user requirements.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Understand Requirements**: Analyze user description to determine the most suitable diagram type
|
||||
2. **Read Documentation**: Read the corresponding syntax reference for the diagram type
|
||||
3. **Generate Code**: Generate Mermaid code following the specification
|
||||
4. **Apply Styling**: Apply appropriate themes and style configurations
|
||||
|
||||
## Diagram Type Reference
|
||||
|
||||
Select the appropriate diagram type and read the corresponding documentation:
|
||||
|
||||
| Type | Documentation | Use Cases |
|
||||
| ---- | ------------- | --------- |
|
||||
| Flowchart | [flowchart.md](references/flowchart.md) | Processes, decisions, steps |
|
||||
| Sequence Diagram | [sequenceDiagram.md](references/sequenceDiagram.md) | Interactions, messaging, API calls |
|
||||
| Class Diagram | [classDiagram.md](references/classDiagram.md) | Class structure, inheritance, associations |
|
||||
| State Diagram | [stateDiagram.md](references/stateDiagram.md) | State machines, state transitions |
|
||||
| ER Diagram | [entityRelationshipDiagram.md](references/entityRelationshipDiagram.md) | Database design, entity relationships |
|
||||
| Gantt Chart | [gantt.md](references/gantt.md) | Project planning, timelines |
|
||||
| Pie Chart | [pie.md](references/pie.md) | Proportions, distributions |
|
||||
| Mindmap | [mindmap.md](references/mindmap.md) | Hierarchical structures, knowledge graphs |
|
||||
| Timeline | [timeline.md](references/timeline.md) | Historical events, milestones |
|
||||
| Git Graph | [gitgraph.md](references/gitgraph.md) | Branches, merges, versions |
|
||||
| Quadrant Chart | [quadrantChart.md](references/quadrantChart.md) | Four-quadrant analysis |
|
||||
| Requirement Diagram | [requirementDiagram.md](references/requirementDiagram.md) | Requirements traceability |
|
||||
| C4 Diagram | [c4.md](references/c4.md) | System architecture (C4 model) |
|
||||
| Sankey Diagram | [sankey.md](references/sankey.md) | Flow, conversions |
|
||||
| XY Chart | [xyChart.md](references/xyChart.md) | Line charts, bar charts |
|
||||
| Block Diagram | [block.md](references/block.md) | System components, modules |
|
||||
| Packet Diagram | [packet.md](references/packet.md) | Network protocols, data structures |
|
||||
| Kanban | [kanban.md](references/kanban.md) | Task management, workflows |
|
||||
| Architecture Diagram | [architecture.md](references/architecture.md) | System architecture |
|
||||
| Radar Chart | [radar.md](references/radar.md) | Multi-dimensional comparison |
|
||||
| Treemap | [treemap.md](references/treemap.md) | Hierarchical data visualization |
|
||||
| User Journey | [userJourney.md](references/userJourney.md) | User experience flows |
|
||||
| ZenUML | [zenuml.md](references/zenuml.md) | Sequence diagrams (code style) |
|
||||
|
||||
## Configuration & Themes
|
||||
|
||||
- [Theming](references/config-theming.md) - Custom colors and styles
|
||||
- [Directives](references/config-directives.md) - Diagram-level configuration
|
||||
- [Layouts](references/config-layouts.md) - Layout direction and spacing
|
||||
- [Configuration](references/config-configuration.md) - Global settings
|
||||
- [Math](references/config-math.md) - LaTeX math support
|
||||
|
||||
## Output Specification
|
||||
|
||||
Generated Mermaid code should:
|
||||
|
||||
1. Be wrapped in ```mermaid code blocks
|
||||
2. Have correct syntax that renders directly
|
||||
3. Have clear structure with proper line breaks and indentation
|
||||
4. Use semantic node naming
|
||||
5. Include styling when needed to improve visual appearance
|
||||
|
||||
## Example Output
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Start] --> B{Condition}
|
||||
B -->|Yes| C[Execute]
|
||||
B -->|No| D[End]
|
||||
C --> D
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
User requirements: $ARGUMENTS
|
||||
@@ -1,227 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/architecture.md](../../packages/mermaid/src/docs/syntax/architecture.md).
|
||||
|
||||
# Architecture Diagrams Documentation (v11.1.0+)
|
||||
|
||||
> In the context of mermaid-js, the architecture diagram is used to show the relationship between services and resources commonly found within the Cloud or CI/CD deployments. In an architecture diagram, services (nodes) are connected by edges. Related services can be placed within groups to better illustrate how they are organized.
|
||||
|
||||
## Example
|
||||
|
||||
```mermaid-example
|
||||
architecture-beta
|
||||
group api(cloud)[API]
|
||||
|
||||
service db(database)[Database] in api
|
||||
service disk1(disk)[Storage] in api
|
||||
service disk2(disk)[Storage] in api
|
||||
service server(server)[Server] in api
|
||||
|
||||
db:L -- R:server
|
||||
disk1:T -- B:server
|
||||
disk2:T -- B:db
|
||||
```
|
||||
|
||||
```mermaid
|
||||
architecture-beta
|
||||
group api(cloud)[API]
|
||||
|
||||
service db(database)[Database] in api
|
||||
service disk1(disk)[Storage] in api
|
||||
service disk2(disk)[Storage] in api
|
||||
service server(server)[Server] in api
|
||||
|
||||
db:L -- R:server
|
||||
disk1:T -- B:server
|
||||
disk2:T -- B:db
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
The building blocks of an architecture are `groups`, `services`, `edges`, and `junctions`.
|
||||
|
||||
For supporting components, icons are declared by surrounding the icon name with `()`, while labels are declared by surrounding the text with `[]`.
|
||||
|
||||
To begin an architecture diagram, use the keyword `architecture-beta`, followed by your groups, services, edges, and junctions. While each of the 3 building blocks can be declared in any order, care must be taken to ensure the identifier was previously declared by another component.
|
||||
|
||||
### Groups
|
||||
|
||||
The syntax for declaring a group is:
|
||||
|
||||
```
|
||||
group {group id}({icon name})[{title}] (in {parent id})?
|
||||
```
|
||||
|
||||
Put together:
|
||||
|
||||
```
|
||||
group public_api(cloud)[Public API]
|
||||
```
|
||||
|
||||
creates a group identified as `public_api`, uses the icon `cloud`, and has the label `Public API`.
|
||||
|
||||
Additionally, groups can be placed within a group using the optional `in` keyword
|
||||
|
||||
```
|
||||
group private_api(cloud)[Private API] in public_api
|
||||
```
|
||||
|
||||
### Services
|
||||
|
||||
The syntax for declaring a service is:
|
||||
|
||||
```
|
||||
service {service id}({icon name})[{title}] (in {parent id})?
|
||||
```
|
||||
|
||||
Put together:
|
||||
|
||||
```
|
||||
service database1(database)[My Database]
|
||||
```
|
||||
|
||||
creates the service identified as `database1`, using the icon `database`, with the label `My Database`.
|
||||
|
||||
If the service belongs to a group, it can be placed inside it through the optional `in` keyword
|
||||
|
||||
```
|
||||
service database1(database)[My Database] in private_api
|
||||
```
|
||||
|
||||
### Edges
|
||||
|
||||
The syntax for declaring an edge is:
|
||||
|
||||
```
|
||||
{serviceId}{{group}}?:{T|B|L|R} {<}?--{>}? {T|B|L|R}:{serviceId}{{group}}?
|
||||
```
|
||||
|
||||
#### Edge Direction
|
||||
|
||||
The side of the service the edge comes out of is specified by adding a colon (`:`) to the side of the service connecting to the arrow and adding `L|R|T|B`
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
db:R -- L:server
|
||||
```
|
||||
|
||||
creates an edge between the services `db` and `server`, with the edge coming out of the right of `db` and the left of `server`.
|
||||
|
||||
```
|
||||
db:T -- L:server
|
||||
```
|
||||
|
||||
creates a 90 degree edge between the services `db` and `server`, with the edge coming out of the top of `db` and the left of `server`.
|
||||
|
||||
#### Arrows
|
||||
|
||||
Arrows can be added to each side of an edge by adding `<` before the direction on the left, and/or `>` after the direction on the right.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
subnet:R --> L:gateway
|
||||
```
|
||||
|
||||
creates an edge with the arrow going into the `gateway` service
|
||||
|
||||
#### Edges out of Groups
|
||||
|
||||
To have an edge go from a group to another group or service within another group, the `{group}` modifier can be added after the `serviceId`.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
service server[Server] in groupOne
|
||||
service subnet[Subnet] in groupTwo
|
||||
|
||||
server{group}:B --> T:subnet{group}
|
||||
```
|
||||
|
||||
creates an edge going out of `groupOne`, adjacent to `server`, and into `groupTwo`, adjacent to `subnet`.
|
||||
|
||||
It's important to note that `groupId`s cannot be used for specifying edges and the `{group}` modifier can only be used for services within a group.
|
||||
|
||||
### Junctions
|
||||
|
||||
Junctions are a special type of node which acts as a potential 4-way split between edges.
|
||||
|
||||
The syntax for declaring a junction is:
|
||||
|
||||
```
|
||||
junction {junction id} (in {parent id})?
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
architecture-beta
|
||||
service left_disk(disk)[Disk]
|
||||
service top_disk(disk)[Disk]
|
||||
service bottom_disk(disk)[Disk]
|
||||
service top_gateway(internet)[Gateway]
|
||||
service bottom_gateway(internet)[Gateway]
|
||||
junction junctionCenter
|
||||
junction junctionRight
|
||||
|
||||
left_disk:R -- L:junctionCenter
|
||||
top_disk:B -- T:junctionCenter
|
||||
bottom_disk:T -- B:junctionCenter
|
||||
junctionCenter:R -- L:junctionRight
|
||||
top_gateway:B -- T:junctionRight
|
||||
bottom_gateway:T -- B:junctionRight
|
||||
```
|
||||
|
||||
```mermaid
|
||||
architecture-beta
|
||||
service left_disk(disk)[Disk]
|
||||
service top_disk(disk)[Disk]
|
||||
service bottom_disk(disk)[Disk]
|
||||
service top_gateway(internet)[Gateway]
|
||||
service bottom_gateway(internet)[Gateway]
|
||||
junction junctionCenter
|
||||
junction junctionRight
|
||||
|
||||
left_disk:R -- L:junctionCenter
|
||||
top_disk:B -- T:junctionCenter
|
||||
bottom_disk:T -- B:junctionCenter
|
||||
junctionCenter:R -- L:junctionRight
|
||||
top_gateway:B -- T:junctionRight
|
||||
bottom_gateway:T -- B:junctionRight
|
||||
```
|
||||
|
||||
## Icons
|
||||
|
||||
By default, architecture diagram supports the following icons: `cloud`, `database`, `disk`, `internet`, `server`.
|
||||
Users can use any of the 200,000+ icons available in iconify.design, or add other custom icons, by [registering an icon pack](../config/icons.md).
|
||||
|
||||
After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.
|
||||
|
||||
```mermaid-example
|
||||
architecture-beta
|
||||
group api(logos:aws-lambda)[API]
|
||||
|
||||
service db(logos:aws-aurora)[Database] in api
|
||||
service disk1(logos:aws-glacier)[Storage] in api
|
||||
service disk2(logos:aws-s3)[Storage] in api
|
||||
service server(logos:aws-ec2)[Server] in api
|
||||
|
||||
db:L -- R:server
|
||||
disk1:T -- B:server
|
||||
disk2:T -- B:db
|
||||
```
|
||||
|
||||
```mermaid
|
||||
architecture-beta
|
||||
group api(logos:aws-lambda)[API]
|
||||
|
||||
service db(logos:aws-aurora)[Database] in api
|
||||
service disk1(logos:aws-glacier)[Storage] in api
|
||||
service disk2(logos:aws-s3)[Storage] in api
|
||||
service server(logos:aws-ec2)[Server] in api
|
||||
|
||||
db:L -- R:server
|
||||
disk1:T -- B:server
|
||||
disk2:T -- B:db
|
||||
```
|
||||
@@ -1,753 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/block.md](../../packages/mermaid/src/docs/syntax/block.md).
|
||||
|
||||
# Block Diagrams Documentation
|
||||
|
||||
## Introduction to Block Diagrams
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
A
|
||||
B["A wide one in the middle"]
|
||||
C
|
||||
end
|
||||
space
|
||||
D
|
||||
ID --> D
|
||||
C --> D
|
||||
style B fill:#969,stroke:#333,stroke-width:4px
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
A
|
||||
B["A wide one in the middle"]
|
||||
C
|
||||
end
|
||||
space
|
||||
D
|
||||
ID --> D
|
||||
C --> D
|
||||
style B fill:#969,stroke:#333,stroke-width:4px
|
||||
```
|
||||
|
||||
### Definition and Purpose
|
||||
|
||||
Block diagrams are an intuitive and efficient way to represent complex systems, processes, or architectures visually. They are composed of blocks and connectors, where blocks represent the fundamental components or functions, and connectors show the relationship or flow between these components. This method of diagramming is essential in various fields such as engineering, software development, and process management.
|
||||
|
||||
The primary purpose of block diagrams is to provide a high-level view of a system, allowing for easy understanding and analysis without delving into the intricate details of each component. This makes them particularly useful for simplifying complex systems and for explaining the overall structure and interaction of components within a system.
|
||||
|
||||
Many people use mermaid flowcharts for this purpose. A side-effect of this is that the automatic layout sometimes move shapes to positions that the diagram maker does not want. Block diagrams use a different approach. In this diagram we give the author full control over where the shapes are positioned.
|
||||
|
||||
### General Use Cases
|
||||
|
||||
Block diagrams have a wide range of applications across various industries and disciplines. Some of the key use cases include:
|
||||
|
||||
- **Software Architecture**: In software development, block diagrams can be used to illustrate the architecture of a software application. This includes showing how different modules or services interact, data flow, and high-level component interaction.
|
||||
|
||||
- **Network Diagrams**: Block diagrams are ideal for representing network architectures in IT and telecommunications. They can depict how different network devices and services are interconnected, including routers, switches, firewalls, and the flow of data across the network.
|
||||
|
||||
- **Process Flowcharts**: In business and manufacturing, block diagrams can be employed to create process flowcharts. These flowcharts represent various stages of a business or manufacturing process, helping to visualize the sequence of steps, decision points, and the flow of control.
|
||||
|
||||
- **Electrical Systems**: Engineers use block diagrams to represent electrical systems and circuitry. They can illustrate the high-level structure of an electrical system, the interaction between different electrical components, and the flow of electrical currents.
|
||||
|
||||
- **Educational Purposes**: Block diagrams are also extensively used in educational materials to explain complex concepts and systems in a simplified manner. They help in breaking down and visualizing scientific theories, engineering principles, and technological systems.
|
||||
|
||||
These examples demonstrate the versatility of block diagrams in providing clear and concise representations of complex systems. Their simplicity and clarity make them a valuable tool for professionals across various fields to communicate complex ideas effectively.
|
||||
|
||||
In the following sections, we will delve into the specifics of creating and manipulating block diagrams using Mermaid, covering everything from basic syntax to advanced configurations and styling.
|
||||
|
||||
Creating block diagrams with Mermaid is straightforward and accessible. This section introduces the basic syntax and structure needed to start building simple diagrams. Understanding these foundational concepts is key to efficiently utilizing Mermaid for more complex diagramming tasks.
|
||||
|
||||
### Simple Block Diagrams
|
||||
|
||||
#### Basic Structure
|
||||
|
||||
At its core, a block diagram consists of blocks representing different entities or components. In Mermaid, these blocks are easily created using simple text labels. The most basic form of a block diagram can be a series of blocks without any connectors.
|
||||
|
||||
**Example - Simple Block Diagram**:
|
||||
To create a simple block diagram with three blocks labeled 'a', 'b', and 'c', the syntax is as follows:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
a b c
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
a b c
|
||||
```
|
||||
|
||||
This example will produce a horizontal sequence of three blocks. Each block is automatically spaced and aligned for optimal readability.
|
||||
|
||||
### Defining the number of columns to use
|
||||
|
||||
#### Column Usage
|
||||
|
||||
While simple block diagrams are linear and straightforward, more complex systems may require a structured layout. Mermaid allows for the organization of blocks into multiple columns, facilitating the creation of more intricate and detailed diagrams.
|
||||
|
||||
**Example - Multi-Column Diagram:**
|
||||
In scenarios where you need to distribute blocks across multiple columns, you can specify the number of columns and arrange the blocks accordingly. Here's how to create a block diagram with three columns and four blocks, where the fourth block appears in a second row:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
a b c d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
a b c d
|
||||
```
|
||||
|
||||
This syntax instructs Mermaid to arrange the blocks 'a', 'b', 'c', and 'd' across three columns, wrapping to the next row as needed. This feature is particularly useful for representing layered or multi-tiered systems, such as network layers or hierarchical structures.
|
||||
|
||||
These basic building blocks of Mermaid's block diagrams provide a foundation for more complex diagramming. The simplicity of the syntax allows for quick creation and iteration of diagrams, making it an efficient tool for visualizing ideas and concepts. In the next section, we'll explore advanced block configuration options, including setting block widths and creating composite blocks.
|
||||
|
||||
## 3. Advanced Block Configuration
|
||||
|
||||
Building upon the basics, this section delves into more advanced features of block diagramming in Mermaid. These features allow for greater flexibility and complexity in diagram design, accommodating a wider range of use cases and scenarios.
|
||||
|
||||
### Setting Block Width
|
||||
|
||||
#### Spanning Multiple Columns
|
||||
|
||||
In more complex diagrams, you may need blocks that span multiple columns to emphasize certain components or to represent larger entities. Mermaid allows for the adjustment of block widths to cover multiple columns, enhancing the diagram's readability and structure.
|
||||
|
||||
**Example - Block Spanning Multiple Columns**:
|
||||
To create a block diagram where one block spans across two columns, you can specify the desired width for each block:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
a["A label"] b:2 c:2 d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
a["A label"] b:2 c:2 d
|
||||
```
|
||||
|
||||
In this example, the block labeled "A labels" spans one column, while blocks 'b', 'c' span 2 columns, and 'd' is again allocated its own column. This flexibility in block sizing is crucial for accurately representing systems with components of varying significance or size.
|
||||
|
||||
### Creating Composite Blocks
|
||||
|
||||
#### Nested Blocks
|
||||
|
||||
Composite blocks, or blocks within blocks, are an advanced feature in Mermaid's block diagram syntax. They allow for the representation of nested or hierarchical systems, where one component encompasses several subcomponents.
|
||||
|
||||
**Example - Composite Blocks:**
|
||||
Creating a composite block involves defining a parent block and then nesting other blocks within it. Here's how to define a composite block with nested elements:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
block
|
||||
D
|
||||
end
|
||||
A["A: I am a wide one"]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
block
|
||||
D
|
||||
end
|
||||
A["A: I am a wide one"]
|
||||
```
|
||||
|
||||
In this syntax, 'D' is a nested block within a larger parent block. This feature is particularly useful for depicting complex structures, such as a server with multiple services or a department within a larger organizational framework.
|
||||
|
||||
### Column Width Dynamics
|
||||
|
||||
#### Adjusting Widths
|
||||
|
||||
Mermaid also allows for dynamic adjustment of column widths based on the content of the blocks. The width of the columns is determined by the widest block in the column, ensuring that the diagram remains balanced and readable.
|
||||
|
||||
**Example - Dynamic Column Widths:**
|
||||
In diagrams with varying block sizes, Mermaid automatically adjusts the column widths to fit the largest block in each column. Here's an example:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
a:3
|
||||
block:group1:2
|
||||
columns 2
|
||||
h i j k
|
||||
end
|
||||
g
|
||||
block:group2:3
|
||||
%% columns auto (default)
|
||||
l m n o p q r
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
a:3
|
||||
block:group1:2
|
||||
columns 2
|
||||
h i j k
|
||||
end
|
||||
g
|
||||
block:group2:3
|
||||
%% columns auto (default)
|
||||
l m n o p q r
|
||||
end
|
||||
```
|
||||
|
||||
This example demonstrates how Mermaid dynamically adjusts the width of the columns to accommodate the widest block, in this case, 'a' and the composite block 'e'. This dynamic adjustment is essential for creating visually balanced and easy-to-understand diagrams.
|
||||
|
||||
**Merging Blocks Horizontally:**
|
||||
In scenarios where you need to stack blocks horizontally, you can use column width to accomplish the task. Blocks can be arranged vertically by putting them in a single column. Here is how you can create a block diagram in which 4 blocks are stacked on top of each other:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
block
|
||||
columns 1
|
||||
a["A label"] b c d
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
block
|
||||
columns 1
|
||||
a["A label"] b c d
|
||||
end
|
||||
```
|
||||
|
||||
In this example, the width of the merged block dynamically adjusts to the width of the largest child block.
|
||||
|
||||
With these advanced configuration options, Mermaid's block diagrams can be tailored to represent a wide array of complex systems and structures. The flexibility offered by these features enables users to create diagrams that are both informative and visually appealing. In the following sections, we will explore further capabilities, including different block shapes and linking options.
|
||||
|
||||
## 4. Block Varieties and Shapes
|
||||
|
||||
Mermaid's block diagrams are not limited to standard rectangular shapes. A variety of block shapes are available, allowing for a more nuanced and tailored representation of different types of information or entities. This section outlines the different block shapes you can use in Mermaid and their specific applications.
|
||||
|
||||
### Standard and Special Block Shapes
|
||||
|
||||
Mermaid supports a range of block shapes to suit different diagramming needs, from basic geometric shapes to more specialized forms.
|
||||
|
||||
#### Example - Round Edged Block
|
||||
|
||||
To create a block with round edges, which can be used to represent a softer or more flexible component:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1("This is the text in the box")
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1("This is the text in the box")
|
||||
```
|
||||
|
||||
#### Example - Stadium-Shaped Block
|
||||
|
||||
A stadium-shaped block, resembling an elongated circle, can be used for components that are process-oriented:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1(["This is the text in the box"])
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1(["This is the text in the box"])
|
||||
```
|
||||
|
||||
#### Example - Subroutine Shape
|
||||
|
||||
For representing subroutines or contained processes, a block with double vertical lines is useful:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1[["This is the text in the box"]]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1[["This is the text in the box"]]
|
||||
```
|
||||
|
||||
#### Example - Cylindrical Shape
|
||||
|
||||
The cylindrical shape is ideal for representing databases or storage components:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1[("Database")]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1[("Database")]
|
||||
```
|
||||
|
||||
#### Example - Circle Shape
|
||||
|
||||
A circle can be used for centralized or pivotal components:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1(("This is the text in the circle"))
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1(("This is the text in the circle"))
|
||||
```
|
||||
|
||||
#### Example - Asymmetric, Rhombus, and Hexagon Shapes
|
||||
|
||||
For decision points, use a rhombus, and for unique or specialized processes, asymmetric and hexagon shapes can be utilized:
|
||||
|
||||
**Asymmetric**
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1>"This is the text in the box"]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1>"This is the text in the box"]
|
||||
```
|
||||
|
||||
**Rhombus**
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1{"This is the text in the box"}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1{"This is the text in the box"}
|
||||
```
|
||||
|
||||
**Hexagon**
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1{{"This is the text in the box"}}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1{{"This is the text in the box"}}
|
||||
```
|
||||
|
||||
#### Example - Parallelogram and Trapezoid Shapes
|
||||
|
||||
Parallelogram and trapezoid shapes are perfect for inputs/outputs and transitional processes:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1[/"This is the text in the box"/]
|
||||
id2[\"This is the text in the box"\]
|
||||
A[/"Christmas"\]
|
||||
B[\"Go shopping"/]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1[/"This is the text in the box"/]
|
||||
id2[\"This is the text in the box"\]
|
||||
A[/"Christmas"\]
|
||||
B[\"Go shopping"/]
|
||||
```
|
||||
|
||||
#### Example - Double Circle
|
||||
|
||||
For highlighting critical or high-priority components, a double circle can be effective:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1((("This is the text in the circle")))
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1((("This is the text in the circle")))
|
||||
```
|
||||
|
||||
### Block Arrows and Space Blocks
|
||||
|
||||
Mermaid also offers unique shapes like block arrows and space blocks for directional flow and spacing.
|
||||
|
||||
#### Example - Block Arrows
|
||||
|
||||
Block arrows can visually indicate direction or flow within a process:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
blockArrowId<["Label"]>(right)
|
||||
blockArrowId2<["Label"]>(left)
|
||||
blockArrowId3<["Label"]>(up)
|
||||
blockArrowId4<["Label"]>(down)
|
||||
blockArrowId5<["Label"]>(x)
|
||||
blockArrowId6<["Label"]>(y)
|
||||
blockArrowId7<["Label"]>(x, down)
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
blockArrowId<["Label"]>(right)
|
||||
blockArrowId2<["Label"]>(left)
|
||||
blockArrowId3<["Label"]>(up)
|
||||
blockArrowId4<["Label"]>(down)
|
||||
blockArrowId5<["Label"]>(x)
|
||||
blockArrowId6<["Label"]>(y)
|
||||
blockArrowId7<["Label"]>(x, down)
|
||||
```
|
||||
|
||||
#### Example - Space Blocks
|
||||
|
||||
Space blocks can be used to create intentional empty spaces in the diagram, which is useful for layout and readability:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
a space b
|
||||
c d e
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
a space b
|
||||
c d e
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
ida space:3 idb idc
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
ida space:3 idb idc
|
||||
```
|
||||
|
||||
Note that you can set how many columns the space block occupied using the number notation `space:num` where num is a number indicating the num columns width. You can also use `space` which defaults to one column.
|
||||
|
||||
The variety of shapes and special blocks in Mermaid enhances the expressive power of block diagrams, allowing for more accurate and context-specific representations. These options give users the flexibility to create diagrams that are both informative and visually appealing. In the next sections, we will explore the ways to connect these blocks and customize their appearance.
|
||||
|
||||
### Standard and Special Block Shapes
|
||||
|
||||
Discuss the various shapes available for blocks, including standard shapes and special forms like block arrows and space blocks.
|
||||
|
||||
## 5. Connecting Blocks with Edges
|
||||
|
||||
One of the key features of block diagrams in Mermaid is the ability to connect blocks using various types of edges or links. This section explores the different ways blocks can be interconnected to represent relationships and flows between components.
|
||||
|
||||
### Basic Linking and Arrow Types
|
||||
|
||||
The most fundamental aspect of connecting blocks is the use of arrows or links. These connectors depict the relationships or the flow of information between the blocks. Mermaid offers a range of arrow types to suit different diagramming needs.
|
||||
|
||||
**Example - Basic Links**
|
||||
|
||||
A simple link with an arrow can be created to show direction or flow from one block to another:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A space B
|
||||
A-->B
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A space B
|
||||
A-->B
|
||||
```
|
||||
|
||||
This example illustrates a direct connection from block 'A' to block 'B', using a straightforward arrow.
|
||||
|
||||
This syntax creates a line connecting 'A' and 'B', implying a relationship or connection without indicating a specific direction.
|
||||
|
||||
### Text on Links
|
||||
|
||||
In addition to connecting blocks, it's often necessary to describe or label the relationship. Mermaid allows for the inclusion of text on links, providing context to the connections.
|
||||
|
||||
Example - Text with Links
|
||||
To add text to a link, the syntax includes the text within the link definition:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A space:2 B
|
||||
A-- "X" -->B
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A space:2 B
|
||||
A-- "X" -->B
|
||||
```
|
||||
|
||||
This example show how to add descriptive text to the links, enhancing the information conveyed by the diagram.
|
||||
|
||||
Example - Edges and Styles:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
A
|
||||
B["A wide one in the middle"]
|
||||
C
|
||||
end
|
||||
space
|
||||
D
|
||||
ID --> D
|
||||
C --> D
|
||||
style B fill:#939,stroke:#333,stroke-width:4px
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 1
|
||||
db(("DB"))
|
||||
blockArrowId6<[" "]>(down)
|
||||
block:ID
|
||||
A
|
||||
B["A wide one in the middle"]
|
||||
C
|
||||
end
|
||||
space
|
||||
D
|
||||
ID --> D
|
||||
C --> D
|
||||
style B fill:#939,stroke:#333,stroke-width:4px
|
||||
```
|
||||
|
||||
## 6. Styling and Customization
|
||||
|
||||
Beyond the structure and layout of block diagrams, Mermaid offers extensive styling options. These customization features allow for the creation of more visually distinctive and informative diagrams. This section covers how to apply individual styles to blocks and how to use classes for consistent styling across multiple elements.
|
||||
|
||||
### Individual Block Styling
|
||||
|
||||
Mermaid enables detailed styling of individual blocks, allowing you to apply various CSS properties such as color, stroke, and border thickness. This feature is especially useful for highlighting specific parts of a diagram or for adhering to certain visual themes.
|
||||
|
||||
#### Example - Styling a Single Block
|
||||
|
||||
To apply custom styles to a block, you can use the `style` keyword followed by the block identifier and the desired CSS properties:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
id1 space id2
|
||||
id1("Start")-->id2("Stop")
|
||||
style id1 fill:#636,stroke:#333,stroke-width:4px
|
||||
style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
id1 space id2
|
||||
id1("Start")-->id2("Stop")
|
||||
style id1 fill:#636,stroke:#333,stroke-width:4px
|
||||
style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### Class Styling
|
||||
|
||||
Mermaid enables applying styling to classes, which could make styling easier if you want to apply a certain set of styles to multiple elements, as you could just link those elements to a class.
|
||||
|
||||
#### Example - Styling a Single Class
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A space B
|
||||
A-->B
|
||||
classDef blue fill:#6e6ce6,stroke:#333,stroke-width:4px;
|
||||
class A blue
|
||||
style B fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A space B
|
||||
A-->B
|
||||
classDef blue fill:#6e6ce6,stroke:#333,stroke-width:4px;
|
||||
class A blue
|
||||
style B fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
In this example, a class named 'blue' is defined and applied to block 'A', while block 'B' receives individual styling. This demonstrates the flexibility of Mermaid in applying both shared and unique styles within the same diagram.
|
||||
|
||||
The ability to style blocks individually or through classes provides a powerful tool for enhancing the visual impact and clarity of block diagrams. Whether emphasizing certain elements or maintaining a cohesive design across the diagram, these styling capabilities are central to effective diagramming. The next sections will present practical examples and use cases, followed by tips for troubleshooting common issues.
|
||||
|
||||
### 7. Practical Examples and Use Cases
|
||||
|
||||
The versatility of Mermaid's block diagrams becomes evident when applied to real-world scenarios. This section provides practical examples demonstrating the application of various features discussed in previous sections. These examples showcase how block diagrams can be used to represent complex systems and processes in an accessible and informative manner.
|
||||
|
||||
### Detailed Examples Illustrating Various Features
|
||||
|
||||
Combining the elements of structure, linking, and styling, we can create comprehensive diagrams that serve specific purposes in different contexts.
|
||||
|
||||
#### Example - System Architecture
|
||||
|
||||
Illustrating a simple software system architecture with interconnected components:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
Frontend blockArrowId6<[" "]>(right) Backend
|
||||
space:2 down<[" "]>(down)
|
||||
Disk left<[" "]>(left) Database[("Database")]
|
||||
|
||||
classDef front fill:#696,stroke:#333;
|
||||
classDef back fill:#969,stroke:#333;
|
||||
class Frontend front
|
||||
class Backend,Database back
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
Frontend blockArrowId6<[" "]>(right) Backend
|
||||
space:2 down<[" "]>(down)
|
||||
Disk left<[" "]>(left) Database[("Database")]
|
||||
|
||||
classDef front fill:#696,stroke:#333;
|
||||
classDef back fill:#969,stroke:#333;
|
||||
class Frontend front
|
||||
class Backend,Database back
|
||||
```
|
||||
|
||||
This example shows a basic architecture with a frontend, backend, and database. The blocks are styled to differentiate between types of components.
|
||||
|
||||
#### Example - Business Process Flow
|
||||
|
||||
Representing a business process flow with decision points and multiple stages:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
columns 3
|
||||
Start(("Start")) space:2
|
||||
down<[" "]>(down) space:2
|
||||
Decision{{"Make Decision"}} right<["Yes"]>(right) Process1["Process A"]
|
||||
downAgain<["No"]>(down) space r3<["Done"]>(down)
|
||||
Process2["Process B"] r2<["Done"]>(right) End(("End"))
|
||||
|
||||
style Start fill:#969;
|
||||
style End fill:#696;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
columns 3
|
||||
Start(("Start")) space:2
|
||||
down<[" "]>(down) space:2
|
||||
Decision{{"Make Decision"}} right<["Yes"]>(right) Process1["Process A"]
|
||||
downAgain<["No"]>(down) space r3<["Done"]>(down)
|
||||
Process2["Process B"] r2<["Done"]>(right) End(("End"))
|
||||
|
||||
style Start fill:#969;
|
||||
style End fill:#696;
|
||||
```
|
||||
|
||||
These practical examples and scenarios underscore the utility of Mermaid block diagrams in simplifying and effectively communicating complex information across various domains.
|
||||
|
||||
The next section, 'Troubleshooting and Common Issues', will provide insights into resolving common challenges encountered when working with Mermaid block diagrams, ensuring a smooth diagramming experience.
|
||||
|
||||
## 8. Troubleshooting and Common Issues
|
||||
|
||||
Working with Mermaid block diagrams can sometimes present challenges, especially as the complexity of the diagrams increases. This section aims to provide guidance on resolving common issues and offers tips for managing more intricate diagram structures.
|
||||
|
||||
### Common Syntax Errors
|
||||
|
||||
Understanding and avoiding common syntax errors is key to a smooth experience with Mermaid diagrams.
|
||||
|
||||
#### Example - Incorrect Linking
|
||||
|
||||
A common mistake is incorrect linking syntax, which can lead to unexpected results or broken diagrams:
|
||||
|
||||
```
|
||||
block
|
||||
A - B
|
||||
```
|
||||
|
||||
**Correction**:
|
||||
Ensure that links between blocks are correctly specified with arrows (--> or ---) to define the direction and type of connection. Also remember that one of the fundamentals for block diagram is to give the author full control of where the boxes are positioned so in the example you need to add a space between the boxes:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A space B
|
||||
A --> B
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A space B
|
||||
A --> B
|
||||
```
|
||||
|
||||
#### Example - Misplaced Styling
|
||||
|
||||
Applying styles in the wrong context or with incorrect syntax can lead to blocks not being styled as intended:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A
|
||||
style A fill#969;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A
|
||||
style A fill#969;
|
||||
```
|
||||
|
||||
**Correction:**
|
||||
Correct the syntax by ensuring proper separation of style properties with commas and using the correct CSS property format:
|
||||
|
||||
```mermaid-example
|
||||
block
|
||||
A
|
||||
style A fill:#969,stroke:#333;
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
block
|
||||
A
|
||||
style A fill:#969,stroke:#333;
|
||||
|
||||
```
|
||||
|
||||
### Tips for Complex Diagram Structures
|
||||
|
||||
Managing complexity in Mermaid diagrams involves planning and employing best practices.
|
||||
|
||||
#### Modular Design
|
||||
|
||||
Break down complex diagrams into smaller, more manageable components. This approach not only makes the diagram easier to understand but also simplifies the creation and maintenance process.
|
||||
|
||||
#### Consistent Styling
|
||||
|
||||
Use classes to maintain consistent styling across similar elements. This not only saves time but also ensures a cohesive and professional appearance.
|
||||
|
||||
#### Comments and Documentation
|
||||
|
||||
Use comments with `%%` within the Mermaid syntax to document the purpose of various parts of the diagram. This practice is invaluable for maintaining clarity, especially when working in teams or returning to a diagram after some time.
|
||||
|
||||
With these troubleshooting tips and best practices, you can effectively manage and resolve common issues in Mermaid block diagrams. The final section, 'Conclusion', will summarize the key points covered in this documentation and invite user feedback for continuous improvement.
|
||||
@@ -1,619 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/c4.md](../../packages/mermaid/src/docs/syntax/c4.md).
|
||||
|
||||
# C4 Diagrams
|
||||
|
||||
> C4 Diagram: This is an experimental diagram for now. The syntax and properties can change in future releases. Proper documentation will be provided when the syntax is stable.
|
||||
|
||||
Mermaid's C4 diagram syntax is compatible with plantUML. See example below:
|
||||
|
||||
```mermaid-example
|
||||
C4Context
|
||||
title System Context diagram for Internet Banking System
|
||||
Enterprise_Boundary(b0, "BankBoundary0") {
|
||||
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
|
||||
Person(customerB, "Banking Customer B")
|
||||
Person_Ext(customerC, "Banking Customer C", "desc")
|
||||
|
||||
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
|
||||
|
||||
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
|
||||
|
||||
Enterprise_Boundary(b1, "BankBoundary") {
|
||||
|
||||
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
System_Boundary(b2, "BankBoundary2") {
|
||||
System(SystemA, "Banking System A")
|
||||
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
|
||||
}
|
||||
|
||||
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
|
||||
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
|
||||
|
||||
Boundary(b3, "BankBoundary3", "boundary") {
|
||||
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
|
||||
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
BiRel(customerA, SystemAA, "Uses")
|
||||
BiRel(SystemAA, SystemE, "Uses")
|
||||
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
|
||||
Rel(SystemC, customerA, "Sends e-mails to")
|
||||
|
||||
UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
|
||||
UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
|
||||
UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
|
||||
UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
|
||||
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
|
||||
|
||||
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
||||
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title System Context diagram for Internet Banking System
|
||||
Enterprise_Boundary(b0, "BankBoundary0") {
|
||||
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
|
||||
Person(customerB, "Banking Customer B")
|
||||
Person_Ext(customerC, "Banking Customer C", "desc")
|
||||
|
||||
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
|
||||
|
||||
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
|
||||
|
||||
Enterprise_Boundary(b1, "BankBoundary") {
|
||||
|
||||
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
System_Boundary(b2, "BankBoundary2") {
|
||||
System(SystemA, "Banking System A")
|
||||
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
|
||||
}
|
||||
|
||||
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
|
||||
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
|
||||
|
||||
Boundary(b3, "BankBoundary3", "boundary") {
|
||||
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
|
||||
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
BiRel(customerA, SystemAA, "Uses")
|
||||
BiRel(SystemAA, SystemE, "Uses")
|
||||
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
|
||||
Rel(SystemC, customerA, "Sends e-mails to")
|
||||
|
||||
UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
|
||||
UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
|
||||
UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
|
||||
UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
|
||||
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
|
||||
|
||||
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
||||
|
||||
|
||||
```
|
||||
|
||||
For an example, see the source code demos/index.html
|
||||
|
||||
5 types of C4 charts are supported.
|
||||
|
||||
- System Context (C4Context)
|
||||
- Container diagram (C4Container)
|
||||
- Component diagram (C4Component)
|
||||
- Dynamic diagram (C4Dynamic)
|
||||
- Deployment diagram (C4Deployment)
|
||||
|
||||
Please refer to the linked document [C4-PlantUML syntax](https://github.com/plantuml-stdlib/C4-PlantUML/blob/master/README.md) for how to write the C4 diagram.
|
||||
|
||||
C4 diagram is fixed style, such as css color, so different css is not provided under different skins.
|
||||
updateElementStyle and UpdateElementStyle are written in the diagram last part. updateElementStyle is inconsistent with the original definition and updates the style of the relationship, including the offset of the text label relative to the original position.
|
||||
|
||||
The layout does not use a fully automated layout algorithm. The position of shapes is adjusted by changing the order in which statements are written. So there is no plan to support the following Layout statements.
|
||||
The number of shapes per row and the number of boundaries can be adjusted using UpdateLayoutConfig.
|
||||
|
||||
- Layout
|
||||
- Lay_U, Lay_Up
|
||||
- Lay_D, Lay_Down
|
||||
- Lay_L, Lay_Left
|
||||
- Lay_R, Lay_Right
|
||||
|
||||
The following unfinished features are not supported in the short term.
|
||||
|
||||
- [ ] sprite
|
||||
|
||||
- [ ] tags
|
||||
|
||||
- [ ] link
|
||||
|
||||
- [ ] Legend
|
||||
|
||||
- [x] System Context
|
||||
- [x] Person(alias, label, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] Person_Ext
|
||||
- [x] System(alias, label, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] SystemDb
|
||||
- [x] SystemQueue
|
||||
- [x] System_Ext
|
||||
- [x] SystemDb_Ext
|
||||
- [x] SystemQueue_Ext
|
||||
- [x] Boundary(alias, label, ?type, ?tags, $link)
|
||||
- [x] Enterprise_Boundary(alias, label, ?tags, $link)
|
||||
- [x] System_Boundary
|
||||
|
||||
- [x] Container diagram
|
||||
- [x] Container(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] ContainerDb
|
||||
- [x] ContainerQueue
|
||||
- [x] Container_Ext
|
||||
- [x] ContainerDb_Ext
|
||||
- [x] ContainerQueue_Ext
|
||||
- [x] Container_Boundary(alias, label, ?tags, $link)
|
||||
|
||||
- [x] Component diagram
|
||||
- [x] Component(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] ComponentDb
|
||||
- [x] ComponentQueue
|
||||
- [x] Component_Ext
|
||||
- [x] ComponentDb_Ext
|
||||
- [x] ComponentQueue_Ext
|
||||
|
||||
- [x] Dynamic diagram
|
||||
- [x] RelIndex(index, from, to, label, ?tags, $link)
|
||||
|
||||
- [x] Deployment diagram
|
||||
- [x] Deployment_Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link): short name of Deployment_Node()
|
||||
- [x] Node_L(alias, label, ?type, ?descr, ?sprite, ?tags, $link): left aligned Node()
|
||||
- [x] Node_R(alias, label, ?type, ?descr, ?sprite, ?tags, $link): right aligned Node()
|
||||
|
||||
- [x] Relationship Types
|
||||
- [x] Rel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)
|
||||
- [x] BiRel (bidirectional relationship)
|
||||
- [x] Rel_U, Rel_Up
|
||||
- [x] Rel_D, Rel_Down
|
||||
- [x] Rel_L, Rel_Left
|
||||
- [x] Rel_R, Rel_Right
|
||||
- [x] Rel_Back
|
||||
- [x] RelIndex \* Compatible with C4-PlantUML syntax, but ignores the index parameter. The sequence number is determined by the order in which the rel statements are written.
|
||||
|
||||
- [ ] Custom tags/stereotypes support and skin param updates
|
||||
- [ ] AddElementTag(tagStereo, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new element tag. The styles of the tagged elements are updated and the tag is displayed in the calculated legend.
|
||||
- [ ] AddRelTag(tagStereo, ?textColor, ?lineColor, ?lineStyle, ?sprite, ?techn, ?legendText, ?legendSprite): Introduces a new Relationship tag. The styles of the tagged relationships are updated and the tag is displayed in the calculated legend.
|
||||
- [x] UpdateElementStyle(elementName, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite): This call updates the default style of the elements (component, ...) and creates no additional legend entry.
|
||||
- [x] UpdateRelStyle(from, to, ?textColor, ?lineColor, ?offsetX, ?offsetY): This call updates the default relationship colors and creates no additional legend entry. Two new parameters, offsetX and offsetY, are added to set the offset of the original position of the text.
|
||||
- [ ] RoundedBoxShape(): This call returns the name of the rounded box shape and can be used as ?shape argument.
|
||||
- [ ] EightSidedShape(): This call returns the name of the eight sided shape and can be used as ?shape argument.
|
||||
- [ ] DashedLine(): This call returns the name of the dashed line and can be used as ?lineStyle argument.
|
||||
- [ ] DottedLine(): This call returns the name of the dotted line and can be used as ?lineStyle argument.
|
||||
- [ ] BoldLine(): This call returns the name of the bold line and can be used as ?lineStyle argument.
|
||||
- [x] UpdateLayoutConfig(?c4ShapeInRow, ?c4BoundaryInRow): New. This call updates the default c4ShapeInRow(4) and c4BoundaryInRow(2).
|
||||
|
||||
There are two ways to assign parameters with question marks. One uses the non-named parameter assignment method in the order of the parameters, and the other uses the named parameter assignment method, where the name must start with a $ symbol.
|
||||
|
||||
Example: UpdateRelStyle(from, to, ?textColor, ?lineColor, ?offsetX, ?offsetY)
|
||||
|
||||
```
|
||||
UpdateRelStyle(customerA, bankA, "red", "blue", "-40", "60")
|
||||
UpdateRelStyle(customerA, bankA, $offsetX="-40", $offsetY="60", $lineColor="blue", $textColor="red")
|
||||
UpdateRelStyle(customerA, bankA, $offsetY="60")
|
||||
|
||||
```
|
||||
|
||||
## C4 System Context Diagram (C4Context)
|
||||
|
||||
```mermaid-example
|
||||
C4Context
|
||||
title System Context diagram for Internet Banking System
|
||||
Enterprise_Boundary(b0, "BankBoundary0") {
|
||||
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
|
||||
Person(customerB, "Banking Customer B")
|
||||
Person_Ext(customerC, "Banking Customer C", "desc")
|
||||
|
||||
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
|
||||
|
||||
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
|
||||
|
||||
Enterprise_Boundary(b1, "BankBoundary") {
|
||||
|
||||
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
System_Boundary(b2, "BankBoundary2") {
|
||||
System(SystemA, "Banking System A")
|
||||
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
|
||||
}
|
||||
|
||||
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
|
||||
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
|
||||
|
||||
Boundary(b3, "BankBoundary3", "boundary") {
|
||||
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
|
||||
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
BiRel(customerA, SystemAA, "Uses")
|
||||
BiRel(SystemAA, SystemE, "Uses")
|
||||
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
|
||||
Rel(SystemC, customerA, "Sends e-mails to")
|
||||
|
||||
UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
|
||||
UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
|
||||
UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
|
||||
UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
|
||||
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
|
||||
|
||||
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title System Context diagram for Internet Banking System
|
||||
Enterprise_Boundary(b0, "BankBoundary0") {
|
||||
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
|
||||
Person(customerB, "Banking Customer B")
|
||||
Person_Ext(customerC, "Banking Customer C", "desc")
|
||||
|
||||
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
|
||||
|
||||
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
|
||||
|
||||
Enterprise_Boundary(b1, "BankBoundary") {
|
||||
|
||||
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
System_Boundary(b2, "BankBoundary2") {
|
||||
System(SystemA, "Banking System A")
|
||||
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts. next line.")
|
||||
}
|
||||
|
||||
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
|
||||
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
|
||||
|
||||
Boundary(b3, "BankBoundary3", "boundary") {
|
||||
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank.")
|
||||
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
BiRel(customerA, SystemAA, "Uses")
|
||||
BiRel(SystemAA, SystemE, "Uses")
|
||||
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
|
||||
Rel(SystemC, customerA, "Sends e-mails to")
|
||||
|
||||
UpdateElementStyle(customerA, $fontColor="red", $bgColor="grey", $borderColor="red")
|
||||
UpdateRelStyle(customerA, SystemAA, $textColor="blue", $lineColor="blue", $offsetX="5")
|
||||
UpdateRelStyle(SystemAA, SystemE, $textColor="blue", $lineColor="blue", $offsetY="-10")
|
||||
UpdateRelStyle(SystemAA, SystemC, $textColor="blue", $lineColor="blue", $offsetY="-40", $offsetX="-50")
|
||||
UpdateRelStyle(SystemC, customerA, $textColor="red", $lineColor="red", $offsetX="-50", $offsetY="20")
|
||||
|
||||
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
|
||||
|
||||
```
|
||||
|
||||
## C4 Container diagram (C4Container)
|
||||
|
||||
```mermaid-example
|
||||
C4Container
|
||||
title Container diagram for Internet Banking System
|
||||
|
||||
System_Ext(email_system, "E-Mail System", "The internal Microsoft Exchange system", $tags="v1.0")
|
||||
Person(customer, Customer, "A customer of the bank, with personal bank accounts", $tags="v1.0")
|
||||
|
||||
Container_Boundary(c1, "Internet Banking") {
|
||||
Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all the Internet banking functionality to customers via their web browser")
|
||||
Container_Ext(mobile_app, "Mobile App", "C#, Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device")
|
||||
Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the static content and the Internet banking SPA")
|
||||
ContainerDb(database, "Database", "SQL Database", "Stores user registration information, hashed auth credentials, access logs, etc.")
|
||||
ContainerDb_Ext(backend_api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via API")
|
||||
|
||||
}
|
||||
|
||||
System_Ext(banking_system, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
Rel(customer, web_app, "Uses", "HTTPS")
|
||||
UpdateRelStyle(customer, web_app, $offsetY="60", $offsetX="90")
|
||||
Rel(customer, spa, "Uses", "HTTPS")
|
||||
UpdateRelStyle(customer, spa, $offsetY="-40")
|
||||
Rel(customer, mobile_app, "Uses")
|
||||
UpdateRelStyle(customer, mobile_app, $offsetY="-30")
|
||||
|
||||
Rel(web_app, spa, "Delivers")
|
||||
UpdateRelStyle(web_app, spa, $offsetX="130")
|
||||
Rel(spa, backend_api, "Uses", "async, JSON/HTTPS")
|
||||
Rel(mobile_app, backend_api, "Uses", "async, JSON/HTTPS")
|
||||
Rel_Back(database, backend_api, "Reads from and writes to", "sync, JDBC")
|
||||
|
||||
Rel(email_system, customer, "Sends e-mails to")
|
||||
UpdateRelStyle(email_system, customer, $offsetX="-45")
|
||||
Rel(backend_api, email_system, "Sends e-mails using", "sync, SMTP")
|
||||
UpdateRelStyle(backend_api, email_system, $offsetY="-60")
|
||||
Rel(backend_api, banking_system, "Uses", "sync/async, XML/HTTPS")
|
||||
UpdateRelStyle(backend_api, banking_system, $offsetY="-50", $offsetX="-140")
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Container
|
||||
title Container diagram for Internet Banking System
|
||||
|
||||
System_Ext(email_system, "E-Mail System", "The internal Microsoft Exchange system", $tags="v1.0")
|
||||
Person(customer, Customer, "A customer of the bank, with personal bank accounts", $tags="v1.0")
|
||||
|
||||
Container_Boundary(c1, "Internet Banking") {
|
||||
Container(spa, "Single-Page App", "JavaScript, Angular", "Provides all the Internet banking functionality to customers via their web browser")
|
||||
Container_Ext(mobile_app, "Mobile App", "C#, Xamarin", "Provides a limited subset of the Internet banking functionality to customers via their mobile device")
|
||||
Container(web_app, "Web Application", "Java, Spring MVC", "Delivers the static content and the Internet banking SPA")
|
||||
ContainerDb(database, "Database", "SQL Database", "Stores user registration information, hashed auth credentials, access logs, etc.")
|
||||
ContainerDb_Ext(backend_api, "API Application", "Java, Docker Container", "Provides Internet banking functionality via API")
|
||||
|
||||
}
|
||||
|
||||
System_Ext(banking_system, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
Rel(customer, web_app, "Uses", "HTTPS")
|
||||
UpdateRelStyle(customer, web_app, $offsetY="60", $offsetX="90")
|
||||
Rel(customer, spa, "Uses", "HTTPS")
|
||||
UpdateRelStyle(customer, spa, $offsetY="-40")
|
||||
Rel(customer, mobile_app, "Uses")
|
||||
UpdateRelStyle(customer, mobile_app, $offsetY="-30")
|
||||
|
||||
Rel(web_app, spa, "Delivers")
|
||||
UpdateRelStyle(web_app, spa, $offsetX="130")
|
||||
Rel(spa, backend_api, "Uses", "async, JSON/HTTPS")
|
||||
Rel(mobile_app, backend_api, "Uses", "async, JSON/HTTPS")
|
||||
Rel_Back(database, backend_api, "Reads from and writes to", "sync, JDBC")
|
||||
|
||||
Rel(email_system, customer, "Sends e-mails to")
|
||||
UpdateRelStyle(email_system, customer, $offsetX="-45")
|
||||
Rel(backend_api, email_system, "Sends e-mails using", "sync, SMTP")
|
||||
UpdateRelStyle(backend_api, email_system, $offsetY="-60")
|
||||
Rel(backend_api, banking_system, "Uses", "sync/async, XML/HTTPS")
|
||||
UpdateRelStyle(backend_api, banking_system, $offsetY="-50", $offsetX="-140")
|
||||
|
||||
```
|
||||
|
||||
## C4 Component diagram (C4Component)
|
||||
|
||||
```mermaid-example
|
||||
C4Component
|
||||
title Component diagram for Internet Banking System - API Application
|
||||
|
||||
Container(spa, "Single Page Application", "javascript and angular", "Provides all the internet banking functionality to customers via their web browser.")
|
||||
Container(ma, "Mobile App", "Xamarin", "Provides a limited subset to the internet banking functionality to customers via their mobile device.")
|
||||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
System_Ext(mbs, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
Container_Boundary(api, "API Application") {
|
||||
Component(sign, "Sign In Controller", "MVC Rest Controller", "Allows users to sign in to the internet banking system")
|
||||
Component(accounts, "Accounts Summary Controller", "MVC Rest Controller", "Provides customers with a summary of their bank accounts")
|
||||
Component(security, "Security Component", "Spring Bean", "Provides functionality related to singing in, changing passwords, etc.")
|
||||
Component(mbsfacade, "Mainframe Banking System Facade", "Spring Bean", "A facade onto the mainframe banking system.")
|
||||
|
||||
Rel(sign, security, "Uses")
|
||||
Rel(accounts, mbsfacade, "Uses")
|
||||
Rel(security, db, "Read & write to", "JDBC")
|
||||
Rel(mbsfacade, mbs, "Uses", "XML/HTTPS")
|
||||
}
|
||||
|
||||
Rel_Back(spa, sign, "Uses", "JSON/HTTPS")
|
||||
Rel(spa, accounts, "Uses", "JSON/HTTPS")
|
||||
|
||||
Rel(ma, sign, "Uses", "JSON/HTTPS")
|
||||
Rel(ma, accounts, "Uses", "JSON/HTTPS")
|
||||
|
||||
UpdateRelStyle(spa, sign, $offsetY="-40")
|
||||
UpdateRelStyle(spa, accounts, $offsetX="40", $offsetY="40")
|
||||
|
||||
UpdateRelStyle(ma, sign, $offsetX="-90", $offsetY="40")
|
||||
UpdateRelStyle(ma, accounts, $offsetY="-40")
|
||||
|
||||
UpdateRelStyle(sign, security, $offsetX="-160", $offsetY="10")
|
||||
UpdateRelStyle(accounts, mbsfacade, $offsetX="140", $offsetY="10")
|
||||
UpdateRelStyle(security, db, $offsetY="-40")
|
||||
UpdateRelStyle(mbsfacade, mbs, $offsetY="-40")
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Component
|
||||
title Component diagram for Internet Banking System - API Application
|
||||
|
||||
Container(spa, "Single Page Application", "javascript and angular", "Provides all the internet banking functionality to customers via their web browser.")
|
||||
Container(ma, "Mobile App", "Xamarin", "Provides a limited subset to the internet banking functionality to customers via their mobile device.")
|
||||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
System_Ext(mbs, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
|
||||
|
||||
Container_Boundary(api, "API Application") {
|
||||
Component(sign, "Sign In Controller", "MVC Rest Controller", "Allows users to sign in to the internet banking system")
|
||||
Component(accounts, "Accounts Summary Controller", "MVC Rest Controller", "Provides customers with a summary of their bank accounts")
|
||||
Component(security, "Security Component", "Spring Bean", "Provides functionality related to singing in, changing passwords, etc.")
|
||||
Component(mbsfacade, "Mainframe Banking System Facade", "Spring Bean", "A facade onto the mainframe banking system.")
|
||||
|
||||
Rel(sign, security, "Uses")
|
||||
Rel(accounts, mbsfacade, "Uses")
|
||||
Rel(security, db, "Read & write to", "JDBC")
|
||||
Rel(mbsfacade, mbs, "Uses", "XML/HTTPS")
|
||||
}
|
||||
|
||||
Rel_Back(spa, sign, "Uses", "JSON/HTTPS")
|
||||
Rel(spa, accounts, "Uses", "JSON/HTTPS")
|
||||
|
||||
Rel(ma, sign, "Uses", "JSON/HTTPS")
|
||||
Rel(ma, accounts, "Uses", "JSON/HTTPS")
|
||||
|
||||
UpdateRelStyle(spa, sign, $offsetY="-40")
|
||||
UpdateRelStyle(spa, accounts, $offsetX="40", $offsetY="40")
|
||||
|
||||
UpdateRelStyle(ma, sign, $offsetX="-90", $offsetY="40")
|
||||
UpdateRelStyle(ma, accounts, $offsetY="-40")
|
||||
|
||||
UpdateRelStyle(sign, security, $offsetX="-160", $offsetY="10")
|
||||
UpdateRelStyle(accounts, mbsfacade, $offsetX="140", $offsetY="10")
|
||||
UpdateRelStyle(security, db, $offsetY="-40")
|
||||
UpdateRelStyle(mbsfacade, mbs, $offsetY="-40")
|
||||
|
||||
```
|
||||
|
||||
## C4 Dynamic diagram (C4Dynamic)
|
||||
|
||||
```mermaid-example
|
||||
C4Dynamic
|
||||
title Dynamic diagram for Internet Banking System - API Application
|
||||
|
||||
ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
|
||||
Container_Boundary(b, "API Application") {
|
||||
Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.")
|
||||
Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.")
|
||||
}
|
||||
Rel(c1, c2, "Submits credentials to", "JSON/HTTPS")
|
||||
Rel(c2, c3, "Calls isAuthenticated() on")
|
||||
Rel(c3, c4, "select * from users where username = ?", "JDBC")
|
||||
|
||||
UpdateRelStyle(c1, c2, $textColor="red", $offsetY="-40")
|
||||
UpdateRelStyle(c2, c3, $textColor="red", $offsetX="-40", $offsetY="60")
|
||||
UpdateRelStyle(c3, c4, $textColor="red", $offsetY="-40", $offsetX="10")
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Dynamic
|
||||
title Dynamic diagram for Internet Banking System - API Application
|
||||
|
||||
ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
|
||||
Container_Boundary(b, "API Application") {
|
||||
Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.")
|
||||
Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.")
|
||||
}
|
||||
Rel(c1, c2, "Submits credentials to", "JSON/HTTPS")
|
||||
Rel(c2, c3, "Calls isAuthenticated() on")
|
||||
Rel(c3, c4, "select * from users where username = ?", "JDBC")
|
||||
|
||||
UpdateRelStyle(c1, c2, $textColor="red", $offsetY="-40")
|
||||
UpdateRelStyle(c2, c3, $textColor="red", $offsetX="-40", $offsetY="60")
|
||||
UpdateRelStyle(c3, c4, $textColor="red", $offsetY="-40", $offsetX="10")
|
||||
|
||||
```
|
||||
|
||||
## C4 Deployment diagram (C4Deployment)
|
||||
|
||||
```mermaid-example
|
||||
C4Deployment
|
||||
title Deployment Diagram for Internet Banking System - Live
|
||||
|
||||
Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){
|
||||
Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.")
|
||||
}
|
||||
|
||||
Deployment_Node(comp, "Customer's computer", "Microsoft Windows or Apple macOS"){
|
||||
Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox,<br/> Apple Safari or Microsoft Edge"){
|
||||
Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.")
|
||||
}
|
||||
}
|
||||
|
||||
Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){
|
||||
Deployment_Node(dn, "bigbank-api*** x8", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bb2, "bigbank-web*** x4", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){
|
||||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS") {
|
||||
Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c") {
|
||||
ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Rel(mobile, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel(spa, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel_U(web, spa, "Delivers to the customer's web browser")
|
||||
Rel(api, db, "Reads from and writes to", "JDBC")
|
||||
Rel(api, db2, "Reads from and writes to", "JDBC")
|
||||
Rel_R(db, db2, "Replicates data to")
|
||||
|
||||
UpdateRelStyle(spa, api, $offsetY="-40")
|
||||
UpdateRelStyle(web, spa, $offsetY="-40")
|
||||
UpdateRelStyle(api, db, $offsetY="-20", $offsetX="5")
|
||||
UpdateRelStyle(api, db2, $offsetX="-40", $offsetY="-20")
|
||||
UpdateRelStyle(db, db2, $offsetY="-10")
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
C4Deployment
|
||||
title Deployment Diagram for Internet Banking System - Live
|
||||
|
||||
Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){
|
||||
Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.")
|
||||
}
|
||||
|
||||
Deployment_Node(comp, "Customer's computer", "Microsoft Windows or Apple macOS"){
|
||||
Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox,<br/> Apple Safari or Microsoft Edge"){
|
||||
Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.")
|
||||
}
|
||||
}
|
||||
|
||||
Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){
|
||||
Deployment_Node(dn, "bigbank-api*** x8", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bb2, "bigbank-web*** x4", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||||
Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){
|
||||
Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){
|
||||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS") {
|
||||
Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c") {
|
||||
ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Rel(mobile, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel(spa, api, "Makes API calls to", "json/HTTPS")
|
||||
Rel_U(web, spa, "Delivers to the customer's web browser")
|
||||
Rel(api, db, "Reads from and writes to", "JDBC")
|
||||
Rel(api, db2, "Reads from and writes to", "JDBC")
|
||||
Rel_R(db, db2, "Replicates data to")
|
||||
|
||||
UpdateRelStyle(spa, api, $offsetY="-40")
|
||||
UpdateRelStyle(web, spa, $offsetY="-40")
|
||||
UpdateRelStyle(api, db, $offsetY="-20", $offsetX="5")
|
||||
UpdateRelStyle(api, db2, $offsetX="-40", $offsetY="-20")
|
||||
UpdateRelStyle(db, db2, $offsetY="-10")
|
||||
|
||||
```
|
||||
|
||||
<!--- cspell:ignore bigbank bigbankdb techn mbsfacade --->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,72 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/configuration.md](../../packages/mermaid/src/docs/config/configuration.md).
|
||||
|
||||
# Configuration
|
||||
|
||||
When mermaid starts, configuration is extracted to determine a configuration to be used for a diagram. There are 3 sources for configuration:
|
||||
|
||||
- The default configuration
|
||||
- Overrides at the site level are set by the initialize call, and will be applied to all diagrams in the site/app. The term for this is the **siteConfig**.
|
||||
- Frontmatter (v10.5.0+) - diagram authors can update selected configuration parameters in the frontmatter of the diagram. These are applied to the render config.
|
||||
- Directives (Deprecated by Frontmatter) - diagram authors can update selected configuration parameters directly in the diagram code via directives. These are applied to the render config.
|
||||
|
||||
**The render config** is configuration that is used when rendering by applying these configurations.
|
||||
|
||||
## Frontmatter config
|
||||
|
||||
The entire mermaid configuration (except the secure configs) can be overridden by the diagram author in the frontmatter of the diagram. The frontmatter is a YAML block at the top of the diagram.
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: Hello Title
|
||||
config:
|
||||
theme: base
|
||||
themeVariables:
|
||||
primaryColor: "#00ff00"
|
||||
---
|
||||
flowchart
|
||||
Hello --> World
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: Hello Title
|
||||
config:
|
||||
theme: base
|
||||
themeVariables:
|
||||
primaryColor: "#00ff00"
|
||||
---
|
||||
flowchart
|
||||
Hello --> World
|
||||
|
||||
```
|
||||
|
||||
## Theme configuration
|
||||
|
||||
## Starting mermaid
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
Site->>mermaid: initialize
|
||||
Site->>mermaid: content loaded
|
||||
mermaid->>mermaidAPI: init
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Site->>mermaid: initialize
|
||||
Site->>mermaid: content loaded
|
||||
mermaid->>mermaidAPI: init
|
||||
```
|
||||
|
||||
## Initialize
|
||||
|
||||
The initialize call is applied **only once**. It is called by the site integrator in order to override the default configuration at a site level.
|
||||
|
||||
## configApi.reset
|
||||
|
||||
This method resets the configuration for a diagram to the overall site configuration, which is the configuration provided by the site integrator. Before each rendering of a diagram, reset is called at the very beginning.
|
||||
@@ -1,342 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/directives.md](../../packages/mermaid/src/docs/config/directives.md).
|
||||
|
||||
# Directives
|
||||
|
||||
> **Warning**
|
||||
> Directives are deprecated from v10.5.0. Please use the `config` key in frontmatter to pass configuration. See [Configuration](./configuration.md) for more details.
|
||||
|
||||
## Directives
|
||||
|
||||
Directives give a diagram author the capability to alter the appearance of a diagram before rendering by changing the applied configuration.
|
||||
|
||||
The significance of having directives is that you have them available while writing the diagram, and can modify the default global and diagram-specific configurations. So, directives are applied on top of the default configuration. The beauty of directives is that you can use them to alter configuration settings for a specific diagram, i.e. at an individual level.
|
||||
|
||||
While directives allow you to change most of the default configuration settings, there are some that are not available, for security reasons. Also, you have the _option to define the set of configurations_ that you wish to allow diagram authors to override with directives.
|
||||
|
||||
## Types of Directives options
|
||||
|
||||
Mermaid basically supports two types of configuration options to be overridden by directives.
|
||||
|
||||
1. _General/Top Level configurations_ : These are the configurations that are available and applied to all the diagram. **Some of the most important top-level** configurations are:
|
||||
- theme
|
||||
- fontFamily
|
||||
- logLevel
|
||||
- securityLevel
|
||||
- startOnLoad
|
||||
- secure
|
||||
|
||||
2. _Diagram-specific configurations_ : These are the configurations that are available and applied to a specific diagram. For each diagram there are specific configuration that will alter how that particular diagram looks and behaves.
|
||||
For example, `mirrorActors` is a configuration that is specific to the `SequenceDiagram` and alters whether the actors are mirrored or not. So this config is available only for the `SequenceDiagram` type.
|
||||
|
||||
**NOTE:** Not all configuration options are listed here. To get hold of all the configuration options, please refer to the [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
|
||||
|
||||
> **Note**
|
||||
> We plan to publish a complete list of top-level configurations & diagram-specific configurations with their possible values in the docs soon.
|
||||
|
||||
## Declaring directives
|
||||
|
||||
Now that we have defined the types of configurations that are available, we can learn how to declare directives.
|
||||
A directive always starts and ends with `%%` signs with directive text in between, like `%% {directive_text} %%`.
|
||||
|
||||
Here the structure of a directive text is like a nested key-value pair map or a JSON object with root being _init_. Where all the general configurations are defined in the top level, and all the diagram specific configurations are defined one level deeper with diagram type as key/root for that section.
|
||||
|
||||
The following code snippet shows the structure of a directive:
|
||||
|
||||
```
|
||||
%%{
|
||||
init: {
|
||||
"theme": "dark",
|
||||
"fontFamily": "monospace",
|
||||
"logLevel": "info",
|
||||
"htmlLabels": true,
|
||||
"flowchart": {
|
||||
"curve": "linear"
|
||||
},
|
||||
"sequence": {
|
||||
"mirrorActors": true
|
||||
}
|
||||
}
|
||||
}%%
|
||||
```
|
||||
|
||||
You can also define the directives in a single line, like this:
|
||||
|
||||
```
|
||||
%%{init: { **insert configuration options here** } }%%
|
||||
```
|
||||
|
||||
For example, the following code snippet:
|
||||
|
||||
```
|
||||
%%{init: { "sequence": { "mirrorActors":false }}}%%
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
The JSON object that is passed as {**argument**} must be valid key value pairs and encased in quotation marks or it will be ignored.
|
||||
Valid Key Value pairs can be found in config.
|
||||
|
||||
Example with a simple graph:
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
|
||||
graph LR
|
||||
A-->B
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
|
||||
graph LR
|
||||
A-->B
|
||||
```
|
||||
|
||||
Here the directive declaration will set the `logLevel` to `debug` and the `theme` to `dark` for a rendered mermaid diagram, changing the appearance of the diagram itself.
|
||||
|
||||
Note: You can use 'init' or 'initialize' as both are acceptable as init directives. Also note that `%%init%%` and `%%initialize%%` directives will be grouped together after they are parsed.
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
|
||||
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
|
||||
...
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
|
||||
%%{initialize: { 'logLevel': 'fatal', "theme":'dark', 'startOnLoad': true } }%%
|
||||
...
|
||||
```
|
||||
|
||||
For example, parsing the above generates a single `%%init%%` JSON object below, combining the two directives and carrying over the last value given for `loglevel`:
|
||||
|
||||
```json
|
||||
{
|
||||
"logLevel": "fatal",
|
||||
"theme": "dark",
|
||||
"startOnLoad": true
|
||||
}
|
||||
```
|
||||
|
||||
This will then be sent to `mermaid.initialize(...)` for rendering.
|
||||
|
||||
## Directive Examples
|
||||
|
||||
Now that the concept of directives has been explained, let us see some more examples of directive usage:
|
||||
|
||||
### Changing theme via directive
|
||||
|
||||
The following code snippet changes `theme` to `forest`:
|
||||
|
||||
`%%{init: { "theme": "forest" } }%%`
|
||||
|
||||
Possible theme values are: `default`, `base`, `dark`, `forest` and `neutral`.
|
||||
Default Value is `default`.
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { "theme": "forest" } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { "theme": "forest" } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
### Changing fontFamily via directive
|
||||
|
||||
The following code snippet changes fontFamily to Trebuchet MS, Verdana, Arial, Sans-Serif:
|
||||
|
||||
`%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%`
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { "fontFamily": "Trebuchet MS, Verdana, Arial, Sans-Serif" } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
### Changing logLevel via directive
|
||||
|
||||
The following code snippet changes `logLevel` to `2`:
|
||||
|
||||
`%%{init: { "logLevel": 2 } }%%`
|
||||
|
||||
Possible `logLevel` values are:
|
||||
|
||||
- `1` for _debug_,
|
||||
- `2` for _info_
|
||||
- `3` for _warn_
|
||||
- `4` for _error_
|
||||
- `5` for _only fatal errors_
|
||||
|
||||
Default Value is `5`.
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { "logLevel": 2 } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { "logLevel": 2 } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
```
|
||||
|
||||
### Changing flowchart config via directive
|
||||
|
||||
Some common flowchart configurations are:
|
||||
|
||||
- ~~_htmlLabels_~~: Deprecated, [prefer setting this at the root level](/config/schema-docs/config#htmllabels).
|
||||
- _curve_: linear/curve
|
||||
- _diagramPadding_: number
|
||||
- _useMaxWidth_: number
|
||||
|
||||
For a complete list of flowchart configurations, see [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
|
||||
_Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs._
|
||||
|
||||
The following code snippet changes flowchart config:
|
||||
|
||||
```
|
||||
%%{init: { "htmlLabels": true, "flowchart": { "curve": "linear" } } }%%
|
||||
```
|
||||
|
||||
Here we are overriding only the flowchart config, and not the general config, setting `htmlLabels` to `true` and `curve` to `linear`.
|
||||
|
||||
> **Warning**
|
||||
> **Deprecated:** `flowchart.htmlLabels` has been deprecated from (v\<MERMAID_RELEASE_VERSION>+). Use the global `htmlLabels` configuration instead. For example, instead of `"flowchart": { "htmlLabels": true }`, use `"htmlLabels": true` at the top level.
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { "flowchart": { "htmlLabels": true, "curve": "linear" } } }%%
|
||||
graph TD
|
||||
A(Forest) --> B[/Another/]
|
||||
A --> C[End]
|
||||
subgraph section
|
||||
B
|
||||
C
|
||||
end
|
||||
```
|
||||
|
||||
### Changing Sequence diagram config via directive
|
||||
|
||||
Some common sequence diagram configurations are:
|
||||
|
||||
- _width_: number
|
||||
- _height_: number
|
||||
- _messageAlign_: left, center, right
|
||||
- _mirrorActors_: boolean
|
||||
- _useMaxWidth_: boolean
|
||||
- _rightAngles_: boolean
|
||||
- _showSequenceNumbers_: boolean
|
||||
- _wrap_: boolean
|
||||
|
||||
For a complete list of sequence diagram configurations, see [defaultConfig.ts](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/defaultConfig.ts) in the source code.
|
||||
_Soon we plan to publish a complete list of all diagram-specific configurations updated in the docs._
|
||||
|
||||
So, `wrap` by default has a value of `false` for sequence diagrams.
|
||||
|
||||
Let us see an example:
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
|
||||
Alice->Bob: Good.
|
||||
Bob->Alice: Cool
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
|
||||
Alice->Bob: Good.
|
||||
Bob->Alice: Cool
|
||||
```
|
||||
|
||||
Now let us enable wrap for sequence diagrams.
|
||||
|
||||
The following code snippet changes sequence diagram config for `wrap` to `true`:
|
||||
|
||||
`%%{init: { "sequence": { "wrap": true} } }%%`
|
||||
|
||||
By applying that snippet to the diagram above, `wrap` will be enabled:
|
||||
|
||||
```mermaid-example
|
||||
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
|
||||
sequenceDiagram
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
|
||||
Alice->Bob: Good.
|
||||
Bob->Alice: Cool
|
||||
```
|
||||
|
||||
```mermaid
|
||||
%%{init: { "sequence": { "wrap": true, "width":300 } } }%%
|
||||
sequenceDiagram
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Fine, how did your mother like the book I suggested? And did you catch the new book about alien invasion?
|
||||
Alice->Bob: Good.
|
||||
Bob->Alice: Cool
|
||||
```
|
||||
@@ -1,40 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/layouts.md](../../packages/mermaid/src/docs/config/layouts.md).
|
||||
|
||||
# Layouts
|
||||
|
||||
This page lists the available layout algorithms supported in Mermaid diagrams.
|
||||
|
||||
## Supported Layouts
|
||||
|
||||
- **elk**: [ELK (Eclipse Layout Kernel)](https://www.eclipse.org/elk/)
|
||||
- **tidy-tree**: Tidy tree layout for hierarchical diagrams [Tidy Tree Configuration](/config/tidy-tree)
|
||||
- **cose-bilkent**: Cose Bilkent layout for force-directed graphs
|
||||
- **dagre**: Dagre layout for layered graphs
|
||||
|
||||
## How to Use
|
||||
|
||||
You can specify the layout in your diagram's YAML config or initialization options. For example:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
layout: elk
|
||||
---
|
||||
graph TD;
|
||||
A-->B;
|
||||
B-->C;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
layout: elk
|
||||
---
|
||||
graph TD;
|
||||
A-->B;
|
||||
B-->C;
|
||||
```
|
||||
@@ -1,96 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/math.md](../../packages/mermaid/src/docs/config/math.md).
|
||||
|
||||
# Math Configuration (v10.9.0+)
|
||||
|
||||
Mermaid supports rendering mathematical expressions through the [KaTeX](https://katex.org/) typesetter.
|
||||
|
||||
## Usage
|
||||
|
||||
To render math within a diagram, surround the mathematical expression with the `$$` delimiter.
|
||||
|
||||
Note that at the moment, the only supported diagrams are below:
|
||||
|
||||
### Flowcharts
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
A["$$x^2$$"] -->|"$$\sqrt{x+3}$$"| B("$$\frac{1}{2}$$")
|
||||
A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\pi r^2$$")
|
||||
B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
|
||||
C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["$$x^2$$"] -->|"$$\sqrt{x+3}$$"| B("$$\frac{1}{2}$$")
|
||||
A -->|"$$\overbrace{a+b+c}^{\text{note}}$$"| C("$$\pi r^2$$")
|
||||
B --> D("$$x = \begin{cases} a &\text{if } b \\ c &\text{if } d \end{cases}$$")
|
||||
C --> E("$$x(t)=c_1\begin{bmatrix}-\cos{t}+\sin{t}\\ 2\cos{t} \end{bmatrix}e^{2t}$$")
|
||||
```
|
||||
|
||||
### Sequence
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant 1 as $$\alpha$$
|
||||
participant 2 as $$\beta$$
|
||||
1->>2: Solve: $$\sqrt{2+2}$$
|
||||
2-->>1: Answer: $$2$$
|
||||
Note right of 2: $$\sqrt{2+2}=\sqrt{4}=2$$
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant 1 as $$\alpha$$
|
||||
participant 2 as $$\beta$$
|
||||
1->>2: Solve: $$\sqrt{2+2}$$
|
||||
2-->>1: Answer: $$2$$
|
||||
Note right of 2: $$\sqrt{2+2}=\sqrt{4}=2$$
|
||||
```
|
||||
|
||||
## Legacy Support
|
||||
|
||||
By default, MathML is used for rendering mathematical expressions. If you have users on [unsupported browsers](https://caniuse.com/?search=mathml), `legacyMathML` can be set in the config to fall back to CSS rendering. Note that **you must provide KaTeX's stylesheets on your own** as they do not come bundled with Mermaid.
|
||||
|
||||
Example with legacy mode enabled (the latest version of KaTeX's stylesheet can be found on their [docs](https://katex.org/docs/browser.html)):
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<!-- KaTeX requires the use of the HTML5 doctype. Without it, KaTeX may not render properly -->
|
||||
<html lang="en">
|
||||
<head>
|
||||
<!-- Please ensure the stylesheet's version matches with the KaTeX version in your package-lock -->
|
||||
<link
|
||||
rel="stylesheet"
|
||||
href="https://cdn.jsdelivr.net/npm/katex@{version_number}/dist/katex.min.css"
|
||||
integrity="sha384-{hash}"
|
||||
crossorigin="anonymous"
|
||||
/>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<script type="module">
|
||||
import mermaid from './mermaid.esm.mjs';
|
||||
mermaid.initialize({
|
||||
legacyMathML: true,
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Handling Rendering Differences
|
||||
|
||||
Due to differences between default fonts across operating systems and browser's MathML implementations, inconsistent results can be seen across platforms. If having consistent results are important, or the most optimal rendered results are desired, `forceLegacyMathML` can be enabled in the config.
|
||||
|
||||
This option will always use KaTeX's stylesheet instead of only when MathML is not supported (as with `legacyMathML`). Note that only `forceLegacyMathML` needs to be set.
|
||||
|
||||
If including KaTeX's stylesheet is not a concern, enabling this option is recommended to avoid scenarios where no MathML implementation within a browser provides the desired output (as seen below).
|
||||
|
||||
|
||||
@@ -1,246 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/theming.md](../../packages/mermaid/src/docs/config/theming.md).
|
||||
|
||||
# Theme Configuration
|
||||
|
||||
Dynamic and integrated theme configuration was introduced in Mermaid version 8.7.0.
|
||||
|
||||
Themes can now be customized at the site-wide level, or on individual Mermaid diagrams. For site-wide theme customization, the `initialize` call is used. For diagram specific customization, frontmatter config is used.
|
||||
|
||||
## Available Themes
|
||||
|
||||
1. [**default**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-default.js) - This is the default theme for all diagrams.
|
||||
|
||||
2. [**neutral**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-neutral.js) - This theme is great for black and white documents that will be printed.
|
||||
|
||||
3. [**dark**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-dark.js) - This theme goes well with dark-colored elements or dark-mode.
|
||||
|
||||
4. [**forest**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-forest.js) - This theme contains shades of green.
|
||||
|
||||
5. [**base**](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/themes/theme-base.js) - This is the only theme that can be modified. Use this theme as the base for customizations.
|
||||
|
||||
## Site-wide Theme
|
||||
|
||||
To customize themes site-wide, call the `initialize` method on the `mermaid`.
|
||||
|
||||
Example of `initialize` call setting `theme` to `base`:
|
||||
|
||||
```javascript
|
||||
mermaid.initialize({
|
||||
securityLevel: 'loose',
|
||||
theme: 'base',
|
||||
});
|
||||
```
|
||||
|
||||
## Diagram-specific Themes
|
||||
|
||||
To customize the theme of an individual diagram, use frontmatter config.
|
||||
|
||||
Example of frontmatter config setting the `theme` to `forest`:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
graph TD
|
||||
a --> b
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
graph TD
|
||||
a --> b
|
||||
```
|
||||
|
||||
> **Reminder**: the only theme that can be customized is the `base` theme. The following section covers how to use `themeVariables` for customizations.
|
||||
|
||||
## Customizing Themes with `themeVariables`
|
||||
|
||||
To make a custom theme, modify `themeVariables` via frontmatter config.
|
||||
|
||||
You will need to use the [base](#available-themes) theme as it is the only modifiable theme.
|
||||
|
||||
| Parameter | Description | Type | Properties |
|
||||
| -------------- | ---------------------------------- | ------ | ----------------------------------------------------------------------------------- |
|
||||
| themeVariables | Modifiable with frontmatter config | Object | `primaryColor`, `primaryTextColor`, `lineColor` ([see full list](#theme-variables)) |
|
||||
|
||||
Example of modifying `themeVariables` using frontmatter config:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
theme: 'base'
|
||||
themeVariables:
|
||||
primaryColor: '#BB2528'
|
||||
primaryTextColor: '#fff'
|
||||
primaryBorderColor: '#7C0000'
|
||||
lineColor: '#F8B229'
|
||||
secondaryColor: '#006100'
|
||||
tertiaryColor: '#fff'
|
||||
---
|
||||
graph TD
|
||||
A[Christmas] -->|Get money| B(Go shopping)
|
||||
B --> C{Let me think}
|
||||
B --> G[/Another/]
|
||||
C ==>|One| D[Laptop]
|
||||
C -->|Two| E[iPhone]
|
||||
C -->|Three| F[fa:fa-car Car]
|
||||
subgraph section
|
||||
C
|
||||
D
|
||||
E
|
||||
F
|
||||
G
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
theme: 'base'
|
||||
themeVariables:
|
||||
primaryColor: '#BB2528'
|
||||
primaryTextColor: '#fff'
|
||||
primaryBorderColor: '#7C0000'
|
||||
lineColor: '#F8B229'
|
||||
secondaryColor: '#006100'
|
||||
tertiaryColor: '#fff'
|
||||
---
|
||||
graph TD
|
||||
A[Christmas] -->|Get money| B(Go shopping)
|
||||
B --> C{Let me think}
|
||||
B --> G[/Another/]
|
||||
C ==>|One| D[Laptop]
|
||||
C -->|Two| E[iPhone]
|
||||
C -->|Three| F[fa:fa-car Car]
|
||||
subgraph section
|
||||
C
|
||||
D
|
||||
E
|
||||
F
|
||||
G
|
||||
end
|
||||
```
|
||||
|
||||
## Color and Color Calculation
|
||||
|
||||
To ensure diagram readability, the default value of certain variables is calculated or derived from other variables. For example, `primaryBorderColor` is derived from the `primaryColor` variable. So if the `primaryColor` variable is customized, Mermaid will adjust `primaryBorderColor` automatically. Adjustments can mean a color inversion, a hue change, a darkening/lightening by 10%, etc.
|
||||
|
||||
The theming engine will only recognize hex colors and not color names. So, the value `#ff0000` will work, but `red` will not.
|
||||
|
||||
## Theme Variables
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| -------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| darkMode | false | Affects how derived colors are calculated. Set value to `true` for dark mode. |
|
||||
| background | #f4f4f4 | Used to calculate color for items that should either be background colored or contrasting to the background |
|
||||
| fontFamily | trebuchet ms, verdana, arial | Font family for diagram text |
|
||||
| fontSize | 16px | Font size in pixels |
|
||||
| primaryColor | #fff4dd | Color to be used as background in nodes, other colors will be derived from this |
|
||||
| primaryTextColor | calculated from darkMode #ddd/#333 | Color to be used as text color in nodes using `primaryColor` |
|
||||
| secondaryColor | calculated from primaryColor | |
|
||||
| primaryBorderColor | calculated from primaryColor | Color to be used as border in nodes using `primaryColor` |
|
||||
| secondaryBorderColor | calculated from secondaryColor | Color to be used as border in nodes using `secondaryColor` |
|
||||
| secondaryTextColor | calculated from secondaryColor | Color to be used as text color in nodes using `secondaryColor` |
|
||||
| tertiaryColor | calculated from primaryColor | |
|
||||
| tertiaryBorderColor | calculated from tertiaryColor | Color to be used as border in nodes using `tertiaryColor` |
|
||||
| tertiaryTextColor | calculated from tertiaryColor | Color to be used as text color in nodes using `tertiaryColor` |
|
||||
| noteBkgColor | #fff5ad | Color used as background in notes |
|
||||
| noteTextColor | #333 | Text color in note rectangles |
|
||||
| noteBorderColor | calculated from noteBkgColor | Border color in note rectangles |
|
||||
| lineColor | calculated from background | |
|
||||
| textColor | calculated from primaryTextColor | Text in diagram over the background for instance text on labels and on signals in sequence diagram or the title in Gantt diagram |
|
||||
| mainBkg | calculated from primaryColor | Background in flowchart objects like rects/circles, class diagram classes, sequence diagram etc |
|
||||
| errorBkgColor | tertiaryColor | Color for syntax error message |
|
||||
| errorTextColor | tertiaryTextColor | Color for syntax error message |
|
||||
|
||||
## Flowchart Variables
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| ------------------- | ------------------------------ | --------------------------- |
|
||||
| nodeBorder | primaryBorderColor | Node Border Color |
|
||||
| clusterBkg | tertiaryColor | Background in subgraphs |
|
||||
| clusterBorder | tertiaryBorderColor | Cluster Border Color |
|
||||
| defaultLinkColor | lineColor | Link Color |
|
||||
| titleColor | tertiaryTextColor | Title Color |
|
||||
| edgeLabelBackground | calculated from secondaryColor | |
|
||||
| nodeTextColor | primaryTextColor | Color for text inside Nodes |
|
||||
|
||||
## Sequence Diagram Variables
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| --------------------- | ------------------------------ | --------------------------- |
|
||||
| actorBkg | mainBkg | Actor Background Color |
|
||||
| actorBorder | primaryBorderColor | Actor Border Color |
|
||||
| actorTextColor | primaryTextColor | Actor Text Color |
|
||||
| actorLineColor | actorBorder | Actor Line Color |
|
||||
| signalColor | textColor | Signal Color |
|
||||
| signalTextColor | textColor | Signal Text Color |
|
||||
| labelBoxBkgColor | actorBkg | Label Box Background Color |
|
||||
| labelBoxBorderColor | actorBorder | Label Box Border Color |
|
||||
| labelTextColor | actorTextColor | Label Text Color |
|
||||
| loopTextColor | actorTextColor | Loop Text Color |
|
||||
| activationBorderColor | calculated from secondaryColor | Activation Border Color |
|
||||
| activationBkgColor | secondaryColor | Activation Background Color |
|
||||
| sequenceNumberColor | calculated from lineColor | Sequence Number Color |
|
||||
|
||||
## Pie Diagram Variables
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| ------------------- | ------------------------------ | ------------------------------------------ |
|
||||
| pie1 | primaryColor | Fill for 1st section in pie diagram |
|
||||
| pie2 | secondaryColor | Fill for 2nd section in pie diagram |
|
||||
| pie3 | calculated from tertiary | Fill for 3rd section in pie diagram |
|
||||
| pie4 | calculated from primaryColor | Fill for 4th section in pie diagram |
|
||||
| pie5 | calculated from secondaryColor | Fill for 5th section in pie diagram |
|
||||
| pie6 | calculated from tertiaryColor | Fill for 6th section in pie diagram |
|
||||
| pie7 | calculated from primaryColor | Fill for 7th section in pie diagram |
|
||||
| pie8 | calculated from primaryColor | Fill for 8th section in pie diagram |
|
||||
| pie9 | calculated from primaryColor | Fill for 9th section in pie diagram |
|
||||
| pie10 | calculated from primaryColor | Fill for 10th section in pie diagram |
|
||||
| pie11 | calculated from primaryColor | Fill for 11th section in pie diagram |
|
||||
| pie12 | calculated from primaryColor | Fill for 12th section in pie diagram |
|
||||
| pieTitleTextSize | 25px | Title text size |
|
||||
| pieTitleTextColor | taskTextDarkColor | Title text color |
|
||||
| pieSectionTextSize | 17px | Text size of individual section labels |
|
||||
| pieSectionTextColor | textColor | Text color of individual section labels |
|
||||
| pieLegendTextSize | 17px | Text size of labels in diagram legend |
|
||||
| pieLegendTextColor | taskTextDarkColor | Text color of labels in diagram legend |
|
||||
| pieStrokeColor | black | Border color of individual pie sections |
|
||||
| pieStrokeWidth | 2px | Border width of individual pie sections |
|
||||
| pieOuterStrokeWidth | 2px | Border width of pie diagram's outer circle |
|
||||
| pieOuterStrokeColor | black | Border color of pie diagram's outer circle |
|
||||
| pieOpacity | 0.7 | Opacity of individual pie sections |
|
||||
|
||||
## State Colors
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| ------------- | ---------------- | -------------------------------------------- |
|
||||
| labelColor | primaryTextColor | |
|
||||
| altBackground | tertiaryColor | Used for background in deep composite states |
|
||||
|
||||
## Class Colors
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| --------- | ------------- | ------------------------------- |
|
||||
| classText | textColor | Color of Text in class diagrams |
|
||||
|
||||
## User Journey Colors
|
||||
|
||||
| Variable | Default value | Description |
|
||||
| --------- | ------------------------------ | --------------------------------------- |
|
||||
| fillType0 | primaryColor | Fill for 1st section in journey diagram |
|
||||
| fillType1 | secondaryColor | Fill for 2nd section in journey diagram |
|
||||
| fillType2 | calculated from primaryColor | Fill for 3rd section in journey diagram |
|
||||
| fillType3 | calculated from secondaryColor | Fill for 4th section in journey diagram |
|
||||
| fillType4 | calculated from primaryColor | Fill for 5th section in journey diagram |
|
||||
| fillType5 | calculated from secondaryColor | Fill for 6th section in journey diagram |
|
||||
| fillType6 | calculated from primaryColor | Fill for 7th section in journey diagram |
|
||||
| fillType7 | calculated from secondaryColor | Fill for 8th section in journey diagram |
|
||||
@@ -1,89 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/tidy-tree.md](../../packages/mermaid/src/docs/config/tidy-tree.md).
|
||||
|
||||
# Tidy-tree Layout
|
||||
|
||||
The **tidy-tree** layout arranges nodes in a hierarchical, tree-like structure. It is especially useful for diagrams where parent-child relationships are important, such as mindmaps.
|
||||
|
||||
## Features
|
||||
|
||||
- Organizes nodes in a tidy, non-overlapping tree
|
||||
- Ideal for mindmaps and hierarchical data
|
||||
- Automatically adjusts spacing for readability
|
||||
|
||||
## Example Usage
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
layout: tidy-tree
|
||||
---
|
||||
mindmap
|
||||
root((mindmap is a long thing))
|
||||
A
|
||||
B
|
||||
C
|
||||
D
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
layout: tidy-tree
|
||||
---
|
||||
mindmap
|
||||
root((mindmap is a long thing))
|
||||
A
|
||||
B
|
||||
C
|
||||
D
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
layout: tidy-tree
|
||||
---
|
||||
mindmap
|
||||
root((mindmap))
|
||||
Origins
|
||||
Long history
|
||||
::icon(fa fa-book)
|
||||
Popularisation
|
||||
British popular psychology author Tony Buzan
|
||||
Research
|
||||
On effectiveness<br/>and features
|
||||
On Automatic creation
|
||||
Uses
|
||||
Creative techniques
|
||||
Strategic planning
|
||||
Argument mapping
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
layout: tidy-tree
|
||||
---
|
||||
mindmap
|
||||
root((mindmap))
|
||||
Origins
|
||||
Long history
|
||||
::icon(fa fa-book)
|
||||
Popularisation
|
||||
British popular psychology author Tony Buzan
|
||||
Research
|
||||
On effectiveness<br/>and features
|
||||
On Automatic creation
|
||||
Uses
|
||||
Creative techniques
|
||||
Strategic planning
|
||||
Argument mapping
|
||||
```
|
||||
|
||||
## Note
|
||||
|
||||
- Currently, tidy-tree is primarily supported for mindmap diagrams.
|
||||
@@ -1,670 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/entityRelationshipDiagram.md](../../packages/mermaid/src/docs/syntax/entityRelationshipDiagram.md).
|
||||
|
||||
# Entity Relationship Diagrams
|
||||
|
||||
> An entity–relationship model (or ER model) describes interrelated things of interest in a specific domain of knowledge. A basic ER model is composed of entity types (which classify the things of interest) and specifies relationships that can exist between entities (instances of those entity types) [Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model).
|
||||
|
||||
Note that practitioners of ER modelling almost always refer to _entity types_ simply as _entities_. For example the `CUSTOMER` entity _type_ would be referred to simply as the `CUSTOMER` entity. This is so common it would be inadvisable to do anything else, but technically an entity is an abstract _instance_ of an entity type, and this is what an ER diagram shows - abstract instances, and the relationships between them. This is why entities are always named using singular nouns.
|
||||
|
||||
Mermaid can render ER diagrams
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: Order example
|
||||
---
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: Order example
|
||||
---
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
||||
```
|
||||
|
||||
Entity names are often capitalised, although there is no accepted standard on this, and it is not required in Mermaid.
|
||||
|
||||
Relationships between entities are represented by lines with end markers representing cardinality. Mermaid uses the most popular crow's foot notation. The crow's foot intuitively conveys the possibility of many instances of the entity that it connects to.
|
||||
|
||||
ER diagrams can be used for various purposes, ranging from abstract logical models devoid of any implementation details, through to physical models of relational database tables. It can be useful to include attribute definitions on ER diagrams to aid comprehension of the purpose and meaning of entities. These do not necessarily need to be exhaustive; often a small subset of attributes is enough. Mermaid allows them to be defined in terms of their _type_ and _name_.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
When including attributes on ER diagrams, you must decide whether to include foreign keys as attributes. This probably depends on how closely you are trying to represent relational table structures. If your diagram is a _logical_ model which is not meant to imply a relational implementation, then it is better to leave these out because the associative relationships already convey the way that entities are associated. For example, a JSON data structure can implement a one-to-many relationship without the need for foreign key properties, using arrays. Similarly an object-oriented programming language may use pointers or references to collections. Even for models that are intended for relational implementation, you might decide that inclusion of foreign key attributes duplicates information already portrayed by the relationships, and does not add meaning to entities. Ultimately, it's your choice.
|
||||
|
||||
## Syntax
|
||||
|
||||
### Entities and Relationships
|
||||
|
||||
Mermaid syntax for ER diagrams is compatible with PlantUML, with an extension to label the relationship. Each statement consists of the following parts:
|
||||
|
||||
```
|
||||
<first-entity> [<relationship> <second-entity> : <relationship-label>]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `first-entity` is the name of an entity. Names support any unicode characters and can include spaces if surrounded by double quotes (e.g. "name with space").
|
||||
- `relationship` describes the way that both entities inter-relate. See below.
|
||||
- `second-entity` is the name of the other entity.
|
||||
- `relationship-label` describes the relationship from the perspective of the first entity.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
PROPERTY ||--|{ ROOM : contains
|
||||
```
|
||||
|
||||
This statement can be read as _a property contains one or more rooms, and a room is part of one and only one property_. You can see that the label here is from the first entity's perspective: a property contains a room, but a room does not contain a property. When considered from the perspective of the second entity, the equivalent label is usually very easy to infer. (Some ER diagrams label relationships from both perspectives, but this is not supported here, and is usually superfluous).
|
||||
|
||||
Only the `first-entity` part of a statement is mandatory. This makes it possible to show an entity with no relationships, which can be useful during iterative construction of diagrams. If any other parts of a statement are specified, then all parts are mandatory.
|
||||
|
||||
#### Unicode text
|
||||
|
||||
Entity names, relationships, and attributes all support unicode text.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
"This ❤ Unicode"
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
"This ❤ Unicode"
|
||||
```
|
||||
|
||||
#### Markdown formatting
|
||||
|
||||
Markdown formatting and text is also supported.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
"This **is** _Markdown_"
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
"This **is** _Markdown_"
|
||||
```
|
||||
|
||||
### Relationship Syntax
|
||||
|
||||
The `relationship` part of each statement can be broken down into three sub-components:
|
||||
|
||||
- the cardinality of the first entity with respect to the second
|
||||
- whether the relationship confers identity on a 'child' entity
|
||||
- the cardinality of the second entity with respect to the first
|
||||
|
||||
Cardinality is a property that describes how many elements of another entity can be related to the entity in question. In the above example a `PROPERTY` can have one or more `ROOM` instances associated to it, whereas a `ROOM` can only be associated with one `PROPERTY`. In each cardinality marker there are two characters. The outermost character represents a maximum value, and the innermost character represents a minimum value. The table below summarises possible cardinalities.
|
||||
|
||||
| Value (left) | Value (right) | Meaning |
|
||||
| :----------: | :-----------: | ----------------------------- |
|
||||
| `\|o` | `o\|` | Zero or one |
|
||||
| `\|\|` | `\|\|` | Exactly one |
|
||||
| `}o` | `o{` | Zero or more (no upper limit) |
|
||||
| `}\|` | `\|{` | One or more (no upper limit) |
|
||||
|
||||
**Aliases**
|
||||
|
||||
| Value (left) | Value (right) | Alias for |
|
||||
| :----------: | :-----------: | ------------ |
|
||||
| one or zero | one or zero | Zero or one |
|
||||
| zero or one | zero or one | Zero or one |
|
||||
| one or more | one or more | One or more |
|
||||
| one or many | one or many | One or more |
|
||||
| many(1) | many(1) | One or more |
|
||||
| 1+ | 1+ | One or more |
|
||||
| zero or more | zero or more | Zero or more |
|
||||
| zero or many | zero or many | Zero or more |
|
||||
| many(0) | many(0) | Zero or more |
|
||||
| 0+ | 0+ | Zero or more |
|
||||
| only one | only one | Exactly one |
|
||||
| 1 | 1 | Exactly one |
|
||||
|
||||
### Identification
|
||||
|
||||
Relationships may be classified as either _identifying_ or _non-identifying_ and these are rendered with either solid or dashed lines respectively. This is relevant when one of the entities in question cannot have independent existence without the other. For example a firm that insures people to drive cars might need to store data on `NAMED-DRIVER`s. In modelling this we might start out by observing that a `CAR` can be driven by many `PERSON` instances, and a `PERSON` can drive many `CAR`s - both entities can exist without the other, so this is a non-identifying relationship that we might specify in Mermaid as: `PERSON }|..|{ CAR : "driver"`. Note the two dots in the middle of the relationship that will result in a dashed line being drawn between the two entities. But when this many-to-many relationship is resolved into two one-to-many relationships, we observe that a `NAMED-DRIVER` cannot exist without both a `PERSON` and a `CAR` - the relationships become identifying and would be specified using hyphens, which translate to a solid line:
|
||||
|
||||
| Value | Alias for |
|
||||
| :---: | :---------------: |
|
||||
| -- | _identifying_ |
|
||||
| .. | _non-identifying_ |
|
||||
|
||||
**Aliases**
|
||||
|
||||
| Value | Alias for |
|
||||
| :-----------: | :---------------: |
|
||||
| to | _identifying_ |
|
||||
| optionally to | _non-identifying_ |
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
PERSON }o..o{ NAMED-DRIVER : is
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
PERSON }o..o{ NAMED-DRIVER : is
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR 1 to zero or more NAMED-DRIVER : allows
|
||||
PERSON many(0) optionally to 0+ NAMED-DRIVER : is
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR 1 to zero or more NAMED-DRIVER : allows
|
||||
PERSON many(0) optionally to 0+ NAMED-DRIVER : is
|
||||
```
|
||||
|
||||
### Attributes
|
||||
|
||||
Attributes can be defined for entities by specifying the entity name followed by a block containing multiple `type name` pairs, where a block is delimited by an opening `{` and a closing `}`. The attributes are rendered inside the entity boxes. For example:
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON ||--o{ NAMED-DRIVER : is
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON ||--o{ NAMED-DRIVER : is
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
```
|
||||
|
||||
The `type` values must begin with an alphabetic character and may contain digits, hyphens, underscores, parentheses and square brackets. The `name` values follow a similar format to `type`, but may start with an asterisk as another option to indicate an attribute is a primary key. Other than that, there are no restrictions, and there is no implicit set of valid data types.
|
||||
|
||||
### Entity Name Aliases
|
||||
|
||||
An alias can be added to an entity using square brackets. If provided, the alias will be showed in the diagram instead of the entity name. Alias names follow all of the same rules as entity names.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
p[Person] {
|
||||
string firstName
|
||||
string lastName
|
||||
}
|
||||
a["Customer Account"] {
|
||||
string email
|
||||
}
|
||||
p ||--o| a : has
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
p[Person] {
|
||||
string firstName
|
||||
string lastName
|
||||
}
|
||||
a["Customer Account"] {
|
||||
string email
|
||||
}
|
||||
p ||--o| a : has
|
||||
```
|
||||
|
||||
#### Attribute Keys and Comments
|
||||
|
||||
Attributes may also have a `key` or comment defined. Keys can be `PK`, `FK` or `UK`, for Primary Key, Foreign Key or Unique Key (markdown formatting and unicode is not supported for keys). To specify multiple key constraints on a single attribute, separate them with a comma (e.g., `PK, FK`). A `comment` is defined by double quotes at the end of an attribute. Comments themselves cannot have double-quote characters in them.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
CAR {
|
||||
string registrationNumber PK
|
||||
string make
|
||||
string model
|
||||
string[] parts
|
||||
}
|
||||
PERSON ||--o{ NAMED-DRIVER : is
|
||||
PERSON {
|
||||
string driversLicense PK "The license #"
|
||||
string(99) firstName "Only 99 characters are allowed"
|
||||
string lastName
|
||||
string phone UK
|
||||
int age
|
||||
}
|
||||
NAMED-DRIVER {
|
||||
string carRegistrationNumber PK, FK
|
||||
string driverLicence PK, FK
|
||||
}
|
||||
MANUFACTURER only one to zero or more CAR : makes
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR ||--o{ NAMED-DRIVER : allows
|
||||
CAR {
|
||||
string registrationNumber PK
|
||||
string make
|
||||
string model
|
||||
string[] parts
|
||||
}
|
||||
PERSON ||--o{ NAMED-DRIVER : is
|
||||
PERSON {
|
||||
string driversLicense PK "The license #"
|
||||
string(99) firstName "Only 99 characters are allowed"
|
||||
string lastName
|
||||
string phone UK
|
||||
int age
|
||||
}
|
||||
NAMED-DRIVER {
|
||||
string carRegistrationNumber PK, FK
|
||||
string driverLicence PK, FK
|
||||
}
|
||||
MANUFACTURER only one to zero or more CAR : makes
|
||||
```
|
||||
|
||||
### Direction
|
||||
|
||||
The direction statement declares the direction of the diagram.
|
||||
|
||||
This declares that the diagram is oriented from top to bottom (`TB`). This can be reversed to be oriented from bottom to top (`BT`).
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
direction TB
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
direction TB
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
This declares that the diagram is oriented from left to right (`LR`). This can be reversed to be oriented from right to left (`RL`).
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
direction LR
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
direction LR
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
CUSTOMER {
|
||||
string name
|
||||
string custNumber
|
||||
string sector
|
||||
}
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
ORDER {
|
||||
int orderNumber
|
||||
string deliveryAddress
|
||||
}
|
||||
LINE-ITEM {
|
||||
string productCode
|
||||
int quantity
|
||||
float pricePerUnit
|
||||
}
|
||||
```
|
||||
|
||||
Possible diagram orientations are:
|
||||
|
||||
- TB - Top to bottom
|
||||
- BT - Bottom to top
|
||||
- RL - Right to left
|
||||
- LR - Left to right
|
||||
|
||||
### Styling a node
|
||||
|
||||
It is possible to apply specific styles such as a thicker border or a different background color to a node.
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
id1||--||id2 : label
|
||||
style id1 fill:#f9f,stroke:#333,stroke-width:4px
|
||||
style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
id1||--||id2 : label
|
||||
style id1 fill:#f9f,stroke:#333,stroke-width:4px
|
||||
style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
It is also possible to attach styles to a list of nodes in one statement:
|
||||
|
||||
```
|
||||
style nodeId1,nodeId2 styleList
|
||||
```
|
||||
|
||||
#### Classes
|
||||
|
||||
More convenient than defining the style every time is to define a class of styles and attach this class to the nodes that
|
||||
should have a different look.
|
||||
|
||||
A class definition looks like the example below:
|
||||
|
||||
```
|
||||
classDef className fill:#f9f,stroke:#333,stroke-width:4px
|
||||
```
|
||||
|
||||
It is also possible to define multiple classes in one statement:
|
||||
|
||||
```
|
||||
classDef firstClassName,secondClassName font-size:12pt
|
||||
```
|
||||
|
||||
Attachment of a class to a node is done as per below:
|
||||
|
||||
```
|
||||
class nodeId1 className
|
||||
```
|
||||
|
||||
It is also possible to attach a class to a list of nodes in one statement:
|
||||
|
||||
```
|
||||
class nodeId1,nodeId2 className
|
||||
```
|
||||
|
||||
Multiple classes can be attached at the same time as well:
|
||||
|
||||
```
|
||||
class nodeId1,nodeId2 className1,className2
|
||||
```
|
||||
|
||||
A shorter form of adding a class is to attach the classname to the node using the `:::`operator as per below:
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
direction TB
|
||||
CAR:::someclass {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON:::someclass {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
HOUSE:::someclass
|
||||
|
||||
classDef someclass fill:#f96
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
direction TB
|
||||
CAR:::someclass {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON:::someclass {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
HOUSE:::someclass
|
||||
|
||||
classDef someclass fill:#f96
|
||||
```
|
||||
|
||||
This form can be used when declaring relationships between entities:
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
PERSON:::foo ||--|| CAR : owns
|
||||
PERSON o{--|| HOUSE:::bar : has
|
||||
|
||||
classDef foo stroke:#f00
|
||||
classDef bar stroke:#0f0
|
||||
classDef foobar stroke:#00f
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
PERSON:::foo ||--|| CAR : owns
|
||||
PERSON o{--|| HOUSE:::bar : has
|
||||
|
||||
classDef foo stroke:#f00
|
||||
classDef bar stroke:#0f0
|
||||
classDef foobar stroke:#00f
|
||||
```
|
||||
|
||||
Similar to the class statement, the shorthand syntax can also apply multiple classes at once:
|
||||
|
||||
```
|
||||
nodeId:::className1,className2
|
||||
```
|
||||
|
||||
### Default class
|
||||
|
||||
If a class is named default it will be assigned to all classes without specific class definitions.
|
||||
|
||||
```
|
||||
classDef default fill:#f9f,stroke:#333,stroke-width:4px;
|
||||
```
|
||||
|
||||
> **Note:** Custom styles from style or other class statements take priority and will overwrite the default styles. (e.g. The `default` class gives nodes a background color of pink but the `blue` class will give that node a background color of blue if applied.)
|
||||
|
||||
```mermaid-example
|
||||
erDiagram
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
PERSON:::foo ||--|| CAR : owns
|
||||
PERSON o{--|| HOUSE:::bar : has
|
||||
|
||||
classDef default fill:#f9f,stroke-width:4px
|
||||
classDef foo stroke:#f00
|
||||
classDef bar stroke:#0f0
|
||||
classDef foobar stroke:#00f
|
||||
```
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
CAR {
|
||||
string registrationNumber
|
||||
string make
|
||||
string model
|
||||
}
|
||||
PERSON {
|
||||
string firstName
|
||||
string lastName
|
||||
int age
|
||||
}
|
||||
PERSON:::foo ||--|| CAR : owns
|
||||
PERSON o{--|| HOUSE:::bar : has
|
||||
|
||||
classDef default fill:#f9f,stroke-width:4px
|
||||
classDef foo stroke:#f00
|
||||
classDef bar stroke:#0f0
|
||||
classDef foobar stroke:#00f
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Layout
|
||||
|
||||
The layout of the diagram is handled by [`render()`](../config/setup/mermaid/interfaces/Mermaid.md#render). The default layout is dagre.
|
||||
|
||||
For larger or more-complex diagrams, you can alternatively apply the ELK (Eclipse Layout Kernel) layout using your YAML frontmatter's `config`. For more information, see [Customizing ELK Layout](../intro/syntax-reference.md#customizing-elk-layout).
|
||||
|
||||
```yaml
|
||||
---
|
||||
config:
|
||||
layout: elk
|
||||
---
|
||||
```
|
||||
|
||||
Your Mermaid code should be similar to the following:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: Order example
|
||||
config:
|
||||
layout: elk
|
||||
---
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: Order example
|
||||
config:
|
||||
layout: elk
|
||||
---
|
||||
erDiagram
|
||||
CUSTOMER ||--o{ ORDER : places
|
||||
ORDER ||--|{ LINE-ITEM : contains
|
||||
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
|
||||
```
|
||||
|
||||
> **Note**
|
||||
> Note that the site needs to use mermaid version 9.4+ for this to work and have this featured enabled in the lazy-loading configuration.
|
||||
|
||||
<!--- cspell:locale en,en-gb --->
|
||||
@@ -1,301 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/examples.md](../../packages/mermaid/src/docs/syntax/examples.md).
|
||||
|
||||
# Examples
|
||||
|
||||
This page contains a collection of examples of diagrams and charts that can be created through mermaid and its myriad applications.
|
||||
|
||||
**If you wish to learn how to support mermaid on your webpage, read the [Beginner's Guide](../config/usage.md?id=usage).**
|
||||
|
||||
**If you wish to learn about mermaid's syntax, Read the [Diagram Syntax](../syntax/flowchart.md?id=flowcharts-basic-syntax) section.**
|
||||
|
||||
## Basic Pie Chart
|
||||
|
||||
```mermaid-example
|
||||
pie title NETFLIX
|
||||
"Time spent looking for movie" : 90
|
||||
"Time spent watching it" : 10
|
||||
```
|
||||
|
||||
```mermaid
|
||||
pie title NETFLIX
|
||||
"Time spent looking for movie" : 90
|
||||
"Time spent watching it" : 10
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
pie title What Voldemort doesn't have?
|
||||
"FRIENDS" : 2
|
||||
"FAMILY" : 3
|
||||
"NOSE" : 45
|
||||
```
|
||||
|
||||
```mermaid
|
||||
pie title What Voldemort doesn't have?
|
||||
"FRIENDS" : 2
|
||||
"FAMILY" : 3
|
||||
"NOSE" : 45
|
||||
```
|
||||
|
||||
## Basic sequence diagram
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
Alice ->> Bob: Hello Bob, how are you?
|
||||
Bob-->>John: How about you John?
|
||||
Bob--x Alice: I am good thanks!
|
||||
Bob-x John: I am good thanks!
|
||||
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
|
||||
|
||||
Bob-->Alice: Checking with John...
|
||||
Alice->John: Yes... John, how are you?
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Alice ->> Bob: Hello Bob, how are you?
|
||||
Bob-->>John: How about you John?
|
||||
Bob--x Alice: I am good thanks!
|
||||
Bob-x John: I am good thanks!
|
||||
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
|
||||
|
||||
Bob-->Alice: Checking with John...
|
||||
Alice->John: Yes... John, how are you?
|
||||
```
|
||||
|
||||
## Basic flowchart
|
||||
|
||||
```mermaid-example
|
||||
graph LR
|
||||
A[Square Rect] -- Link text --> B((Circle))
|
||||
A --> C(Round Rect)
|
||||
B --> D{Rhombus}
|
||||
C --> D
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Square Rect] -- Link text --> B((Circle))
|
||||
A --> C(Round Rect)
|
||||
B --> D{Rhombus}
|
||||
C --> D
|
||||
```
|
||||
|
||||
## Larger flowchart with some styling
|
||||
|
||||
```mermaid-example
|
||||
graph TB
|
||||
sq[Square shape] --> ci((Circle shape))
|
||||
|
||||
subgraph A
|
||||
od>Odd shape]-- Two line<br/>edge comment --> ro
|
||||
di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape)
|
||||
di==>ro2(Rounded square shape)
|
||||
end
|
||||
|
||||
%% Notice that no text in shape are added here instead that is appended further down
|
||||
e --> od3>Really long text with linebreak<br>in an Odd shape]
|
||||
|
||||
%% Comments after double percent signs
|
||||
e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز)
|
||||
|
||||
cyr[Cyrillic]-->cyr2((Circle shape Начало));
|
||||
|
||||
classDef green fill:#9f6,stroke:#333,stroke-width:2px;
|
||||
classDef orange fill:#f96,stroke:#333,stroke-width:4px;
|
||||
class sq,e green
|
||||
class di orange
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
sq[Square shape] --> ci((Circle shape))
|
||||
|
||||
subgraph A
|
||||
od>Odd shape]-- Two line<br/>edge comment --> ro
|
||||
di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape)
|
||||
di==>ro2(Rounded square shape)
|
||||
end
|
||||
|
||||
%% Notice that no text in shape are added here instead that is appended further down
|
||||
e --> od3>Really long text with linebreak<br>in an Odd shape]
|
||||
|
||||
%% Comments after double percent signs
|
||||
e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز)
|
||||
|
||||
cyr[Cyrillic]-->cyr2((Circle shape Начало));
|
||||
|
||||
classDef green fill:#9f6,stroke:#333,stroke-width:2px;
|
||||
classDef orange fill:#f96,stroke:#333,stroke-width:4px;
|
||||
class sq,e green
|
||||
class di orange
|
||||
```
|
||||
|
||||
## SequenceDiagram: Loops, alt and opt
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
loop Daily query
|
||||
Alice->>Bob: Hello Bob, how are you?
|
||||
alt is sick
|
||||
Bob->>Alice: Not so good :(
|
||||
else is well
|
||||
Bob->>Alice: Feeling fresh like a daisy
|
||||
end
|
||||
|
||||
opt Extra response
|
||||
Bob->>Alice: Thanks for asking
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
loop Daily query
|
||||
Alice->>Bob: Hello Bob, how are you?
|
||||
alt is sick
|
||||
Bob->>Alice: Not so good :(
|
||||
else is well
|
||||
Bob->>Alice: Feeling fresh like a daisy
|
||||
end
|
||||
|
||||
opt Extra response
|
||||
Bob->>Alice: Thanks for asking
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## SequenceDiagram: Message to self in loop
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: Hello John, how are you?
|
||||
loop HealthCheck
|
||||
John->>John: Fight against hypochondria
|
||||
end
|
||||
Note right of John: Rational thoughts<br/>prevail...
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Alice
|
||||
participant Bob
|
||||
Alice->>John: Hello John, how are you?
|
||||
loop HealthCheck
|
||||
John->>John: Fight against hypochondria
|
||||
end
|
||||
Note right of John: Rational thoughts<br/>prevail...
|
||||
John-->>Alice: Great!
|
||||
John->>Bob: How about you?
|
||||
Bob-->>John: Jolly good!
|
||||
```
|
||||
|
||||
## Sequence Diagram: Blogging app service communication
|
||||
|
||||
```mermaid-example
|
||||
sequenceDiagram
|
||||
participant web as Web Browser
|
||||
participant blog as Blog Service
|
||||
participant account as Account Service
|
||||
participant mail as Mail Service
|
||||
participant db as Storage
|
||||
|
||||
Note over web,db: The user must be logged in to submit blog posts
|
||||
web->>+account: Logs in using credentials
|
||||
account->>db: Query stored accounts
|
||||
db->>account: Respond with query result
|
||||
|
||||
alt Credentials not found
|
||||
account->>web: Invalid credentials
|
||||
else Credentials found
|
||||
account->>-web: Successfully logged in
|
||||
|
||||
Note over web,db: When the user is authenticated, they can now submit new posts
|
||||
web->>+blog: Submit new post
|
||||
blog->>db: Store post data
|
||||
|
||||
par Notifications
|
||||
blog--)mail: Send mail to blog subscribers
|
||||
blog--)db: Store in-site notifications
|
||||
and Response
|
||||
blog-->>-web: Successfully posted
|
||||
end
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant web as Web Browser
|
||||
participant blog as Blog Service
|
||||
participant account as Account Service
|
||||
participant mail as Mail Service
|
||||
participant db as Storage
|
||||
|
||||
Note over web,db: The user must be logged in to submit blog posts
|
||||
web->>+account: Logs in using credentials
|
||||
account->>db: Query stored accounts
|
||||
db->>account: Respond with query result
|
||||
|
||||
alt Credentials not found
|
||||
account->>web: Invalid credentials
|
||||
else Credentials found
|
||||
account->>-web: Successfully logged in
|
||||
|
||||
Note over web,db: When the user is authenticated, they can now submit new posts
|
||||
web->>+blog: Submit new post
|
||||
blog->>db: Store post data
|
||||
|
||||
par Notifications
|
||||
blog--)mail: Send mail to blog subscribers
|
||||
blog--)db: Store in-site notifications
|
||||
and Response
|
||||
blog-->>-web: Successfully posted
|
||||
end
|
||||
end
|
||||
|
||||
```
|
||||
|
||||
## A commit flow diagram.
|
||||
|
||||
```mermaid-example
|
||||
gitGraph:
|
||||
commit "Ashish"
|
||||
branch newbranch
|
||||
checkout newbranch
|
||||
commit id:"1111"
|
||||
commit tag:"test"
|
||||
checkout main
|
||||
commit type: HIGHLIGHT
|
||||
commit
|
||||
merge newbranch
|
||||
commit
|
||||
branch b2
|
||||
commit
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gitGraph:
|
||||
commit "Ashish"
|
||||
branch newbranch
|
||||
checkout newbranch
|
||||
commit id:"1111"
|
||||
commit tag:"test"
|
||||
checkout main
|
||||
commit type: HIGHLIGHT
|
||||
commit
|
||||
merge newbranch
|
||||
commit
|
||||
branch b2
|
||||
commit
|
||||
```
|
||||
|
||||
<!--- cspell:ignore Ashish newbranch --->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,708 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/gantt.md](../../packages/mermaid/src/docs/syntax/gantt.md).
|
||||
|
||||
# Gantt diagrams
|
||||
|
||||
> A Gantt chart is a type of bar chart, first developed by Karol Adamiecki in 1896, and independently by Henry Gantt in the 1910s, that illustrates a project schedule and the amount of time it would take for any one project to finish. Gantt charts illustrate number of days between the start and finish dates of the terminal elements and summary elements of a project.
|
||||
|
||||
## A note to users
|
||||
|
||||
Gantt Charts will record each scheduled task as one continuous bar that extends from the left to the right. The x axis represents time and the y records the different tasks and the order in which they are to be completed.
|
||||
|
||||
It is important to remember that when a date, day, or collection of dates specific to a task are "excluded", the Gantt Chart will accommodate those changes by extending an equal number of days, towards the right, not by creating a gap inside the task.
|
||||
As shown here 
|
||||
|
||||
However, if the excluded dates are between two tasks that are set to start consecutively, the excluded dates will be skipped graphically and left blank, and the following task will begin after the end of the excluded dates.
|
||||
As shown here 
|
||||
|
||||
A Gantt chart is useful for tracking the amount of time it would take before a project is finished, but it can also be used to graphically represent "non-working days", with a few tweaks.
|
||||
|
||||
Mermaid can render Gantt diagrams as SVG, PNG or a MarkDown link that can be pasted into docs.
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
dateFormat YYYY-MM-DD
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
section Another
|
||||
Task in Another :2014-01-12, 12d
|
||||
another task :24d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
dateFormat YYYY-MM-DD
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
section Another
|
||||
Task in Another :2014-01-12, 12d
|
||||
another task :24d
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
dateFormat YYYY-MM-DD
|
||||
title Adding GANTT diagram functionality to mermaid
|
||||
excludes weekends
|
||||
%% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
|
||||
|
||||
section A section
|
||||
Completed task :done, des1, 2014-01-06,2014-01-08
|
||||
Active task :active, des2, 2014-01-09, 3d
|
||||
Future task : des3, after des2, 5d
|
||||
Future task2 : des4, after des3, 5d
|
||||
|
||||
section Critical tasks
|
||||
Completed task in the critical line :crit, done, 2014-01-06,24h
|
||||
Implement parser and jison :crit, done, after des1, 2d
|
||||
Create tests for parser :crit, active, 3d
|
||||
Future task in critical line :crit, 5d
|
||||
Create tests for renderer :2d
|
||||
Add to mermaid :until isadded
|
||||
Functionality added :milestone, isadded, 2014-01-25, 0d
|
||||
|
||||
section Documentation
|
||||
Describe gantt syntax :active, a1, after des1, 3d
|
||||
Add gantt diagram to demo page :after a1 , 20h
|
||||
Add another diagram to demo page :doc1, after a1 , 48h
|
||||
|
||||
section Last section
|
||||
Describe gantt syntax :after doc1, 3d
|
||||
Add gantt diagram to demo page :20h
|
||||
Add another diagram to demo page :48h
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
dateFormat YYYY-MM-DD
|
||||
title Adding GANTT diagram functionality to mermaid
|
||||
excludes weekends
|
||||
%% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
|
||||
|
||||
section A section
|
||||
Completed task :done, des1, 2014-01-06,2014-01-08
|
||||
Active task :active, des2, 2014-01-09, 3d
|
||||
Future task : des3, after des2, 5d
|
||||
Future task2 : des4, after des3, 5d
|
||||
|
||||
section Critical tasks
|
||||
Completed task in the critical line :crit, done, 2014-01-06,24h
|
||||
Implement parser and jison :crit, done, after des1, 2d
|
||||
Create tests for parser :crit, active, 3d
|
||||
Future task in critical line :crit, 5d
|
||||
Create tests for renderer :2d
|
||||
Add to mermaid :until isadded
|
||||
Functionality added :milestone, isadded, 2014-01-25, 0d
|
||||
|
||||
section Documentation
|
||||
Describe gantt syntax :active, a1, after des1, 3d
|
||||
Add gantt diagram to demo page :after a1 , 20h
|
||||
Add another diagram to demo page :doc1, after a1 , 48h
|
||||
|
||||
section Last section
|
||||
Describe gantt syntax :after doc1, 3d
|
||||
Add gantt diagram to demo page :20h
|
||||
Add another diagram to demo page :48h
|
||||
```
|
||||
|
||||
Tasks are by default sequential. A task start date defaults to the end date of the preceding task.
|
||||
|
||||
A colon, `:`, separates the task title from its metadata.
|
||||
Metadata items are separated by a comma, `,`. Valid tags are `active`, `done`, `crit`, and `milestone`. Tags are optional, but if used, they must be specified first.
|
||||
After processing the tags, the remaining metadata items are interpreted as follows:
|
||||
|
||||
1. If a single item is specified, it determines when the task ends. It can either be a specific date/time or a duration. If a duration is specified, it is added to the start date of the task to determine the end date of the task, taking into account any exclusions.
|
||||
2. If two items are specified, the last item is interpreted as in the previous case. The first item can either specify an explicit start date/time (in the format specified by `dateFormat`) or reference another task using `after <otherTaskID> [[otherTaskID2 [otherTaskID3]]...]`. In the latter case, the start date of the task will be set according to the latest end date of any referenced task.
|
||||
3. If three items are specified, the last two will be interpreted as in the previous case. The first item will denote the ID of the task, which can be referenced using the `later <taskID>` syntax.
|
||||
|
||||
| Metadata syntax | Start date | End date | ID |
|
||||
| ---------------------------------------------------- | --------------------------------------------------- | ----------------------------------------------------- | -------- |
|
||||
| `<taskID>, <startDate>, <endDate>` | `startdate` as interpreted using `dateformat` | `endDate` as interpreted using `dateformat` | `taskID` |
|
||||
| `<taskID>, <startDate>, <length>` | `startdate` as interpreted using `dateformat` | Start date + `length` | `taskID` |
|
||||
| `<taskID>, after <otherTaskId>, <endDate>` | End date of previously specified task `otherTaskID` | `endDate` as interpreted using `dateformat` | `taskID` |
|
||||
| `<taskID>, after <otherTaskId>, <length>` | End date of previously specified task `otherTaskID` | Start date + `length` | `taskID` |
|
||||
| `<taskID>, <startDate>, until <otherTaskId>` | `startdate` as interpreted using `dateformat` | Start date of previously specified task `otherTaskID` | `taskID` |
|
||||
| `<taskID>, after <otherTaskId>, until <otherTaskId>` | End date of previously specified task `otherTaskID` | Start date of previously specified task `otherTaskID` | `taskID` |
|
||||
| `<startDate>, <endDate>` | `startdate` as interpreted using `dateformat` | `enddate` as interpreted using `dateformat` | n/a |
|
||||
| `<startDate>, <length>` | `startdate` as interpreted using `dateformat` | Start date + `length` | n/a |
|
||||
| `after <otherTaskID>, <endDate>` | End date of previously specified task `otherTaskID` | `enddate` as interpreted using `dateformat` | n/a |
|
||||
| `after <otherTaskID>, <length>` | End date of previously specified task `otherTaskID` | Start date + `length` | n/a |
|
||||
| `<startDate>, until <otherTaskId>` | `startdate` as interpreted using `dateformat` | Start date of previously specified task `otherTaskID` | n/a |
|
||||
| `after <otherTaskId>, until <otherTaskId>` | End date of previously specified task `otherTaskID` | Start date of previously specified task `otherTaskID` | n/a |
|
||||
| `<endDate>` | End date of preceding task | `enddate` as interpreted using `dateformat` | n/a |
|
||||
| `<length>` | End date of preceding task | Start date + `length` | n/a |
|
||||
| `until <otherTaskId>` | End date of preceding task | Start date of previously specified task `otherTaskID` | n/a |
|
||||
|
||||
> **Note**
|
||||
> Support for keyword `until` was added in (v10.9.0+). This can be used to define a task which is running until some other specific task or milestone starts.
|
||||
|
||||
For simplicity, the table does not show the use of multiple tasks listed with the `after` keyword. Here is an example of how to use it and how it's interpreted:
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
apple :a, 2017-07-20, 1w
|
||||
banana :crit, b, 2017-07-23, 1d
|
||||
cherry :active, c, after b a, 1d
|
||||
kiwi :d, 2017-07-20, until b c
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
apple :a, 2017-07-20, 1w
|
||||
banana :crit, b, 2017-07-23, 1d
|
||||
cherry :active, c, after b a, 1d
|
||||
kiwi :d, 2017-07-20, until b c
|
||||
```
|
||||
|
||||
### Title
|
||||
|
||||
The `title` is an _optional_ string to be displayed at the top of the Gantt chart to describe the chart as a whole.
|
||||
|
||||
### Excludes
|
||||
|
||||
The `excludes` is an _optional_ attribute that accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".
|
||||
These date will be marked on the graph, and be excluded from the duration calculation of tasks. Meaning that if there are excluded dates during a task interval, the number of 'skipped' days will be added to the end of the task to ensure the duration is as specified in the code.
|
||||
|
||||
#### Weekend (v\11.0.0+)
|
||||
|
||||
When excluding weekends, it is possible to configure the weekends to be either Friday and Saturday or Saturday and Sunday. By default weekends are Saturday and Sunday.
|
||||
To define the weekend start day, there is an _optional_ attribute `weekend` that can be added in a new line followed by either `friday` or `saturday`.
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
title A Gantt Diagram Excluding Fri - Sat weekends
|
||||
dateFormat YYYY-MM-DD
|
||||
excludes weekends
|
||||
weekend friday
|
||||
section Section
|
||||
A task :a1, 2024-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title A Gantt Diagram Excluding Fri - Sat weekends
|
||||
dateFormat YYYY-MM-DD
|
||||
excludes weekends
|
||||
weekend friday
|
||||
section Section
|
||||
A task :a1, 2024-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
```
|
||||
|
||||
### Section statements
|
||||
|
||||
You can divide the chart into various sections, for example to separate different parts of a project like development and documentation.
|
||||
|
||||
To do so, start a line with the `section` keyword and give it a name. (Note that unlike with the [title for the entire chart](#title), this name is _required_.
|
||||
|
||||
### Milestones
|
||||
|
||||
You can add milestones to the diagrams. Milestones differ from tasks as they represent a single instant in time and are identified by the keyword `milestone`. Below is an example on how to use milestones. As you may notice, the exact location of the milestone is determined by the initial date for the milestone and the "duration" of the task this way: _initial date_+_duration_/2.
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
dateFormat HH:mm
|
||||
axisFormat %H:%M
|
||||
Initial milestone : milestone, m1, 17:49, 2m
|
||||
Task A : 10m
|
||||
Task B : 5m
|
||||
Final milestone : milestone, m2, 18:08, 4m
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
dateFormat HH:mm
|
||||
axisFormat %H:%M
|
||||
Initial milestone : milestone, m1, 17:49, 2m
|
||||
Task A : 10m
|
||||
Task B : 5m
|
||||
Final milestone : milestone, m2, 18:08, 4m
|
||||
```
|
||||
|
||||
### Vertical Markers
|
||||
|
||||
The `vert` keyword lets you add vertical lines to your Gantt chart, making it easy to highlight important dates like deadlines, events, or checkpoints. These markers extend across the entire chart and are positioned based on the date you provide. Unlike milestones, vertical markers don’t take up a row. They’re purely visual reference points that help break up the timeline and make important moments easier to spot.
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
dateFormat HH:mm
|
||||
axisFormat %H:%M
|
||||
Initial vert : vert, v1, 17:30, 2m
|
||||
Task A : 3m
|
||||
Task B : 8m
|
||||
Final vert : vert, v2, 17:58, 4m
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
dateFormat HH:mm
|
||||
axisFormat %H:%M
|
||||
Initial vert : vert, v1, 17:30, 2m
|
||||
Task A : 3m
|
||||
Task B : 8m
|
||||
Final vert : vert, v2, 17:58, 4m
|
||||
```
|
||||
|
||||
## Setting dates
|
||||
|
||||
`dateFormat` defines the format of the date **input** of your gantt elements. How these dates are represented in the rendered chart **output** are defined by `axisFormat`.
|
||||
|
||||
### Input date format
|
||||
|
||||
The default input date format is `YYYY-MM-DD`. You can define your custom `dateFormat`.
|
||||
|
||||
```markdown
|
||||
dateFormat YYYY-MM-DD
|
||||
```
|
||||
|
||||
The following formatting options are supported:
|
||||
|
||||
| Input | Example | Description |
|
||||
| ---------- | -------------- | ------------------------------------------------------ |
|
||||
| `YYYY` | 2014 | 4 digit year |
|
||||
| `YY` | 14 | 2 digit year |
|
||||
| `Q` | 1..4 | Quarter of year. Sets month to first month in quarter. |
|
||||
| `M MM` | 1..12 | Month number |
|
||||
| `MMM MMMM` | January..Dec | Month name in locale set by `dayjs.locale()` |
|
||||
| `D DD` | 1..31 | Day of month |
|
||||
| `Do` | 1st..31st | Day of month with ordinal |
|
||||
| `DDD DDDD` | 1..365 | Day of year |
|
||||
| `X` | 1410715640.579 | Unix timestamp |
|
||||
| `x` | 1410715640579 | Unix ms timestamp |
|
||||
| `H HH` | 0..23 | 24 hour time |
|
||||
| `h hh` | 1..12 | 12 hour time used with `a A`. |
|
||||
| `a A` | am pm | Post or ante meridiem |
|
||||
| `m mm` | 0..59 | Minutes |
|
||||
| `s ss` | 0..59 | Seconds |
|
||||
| `S` | 0..9 | Tenths of a second |
|
||||
| `SS` | 0..99 | Hundreds of a second |
|
||||
| `SSS` | 0..999 | Thousandths of a second |
|
||||
| `Z ZZ` | +12:00 | Offset from UTC as +-HH:mm, +-HHmm, or Z |
|
||||
|
||||
More info in: <https://day.js.org/docs/en/parse/string-format/>
|
||||
|
||||
### Output date format on the axis
|
||||
|
||||
The default output date format is `YYYY-MM-DD`. You can define your custom `axisFormat`, like `2020-Q1` for the first quarter of the year 2020.
|
||||
|
||||
```markdown
|
||||
axisFormat %Y-%m-%d
|
||||
```
|
||||
|
||||
The following formatting strings are supported:
|
||||
|
||||
| Format | Definition |
|
||||
| ------ | ------------------------------------------------------------------------------------------ |
|
||||
| %a | abbreviated weekday name |
|
||||
| %A | full weekday name |
|
||||
| %b | abbreviated month name |
|
||||
| %B | full month name |
|
||||
| %c | date and time, as "%a %b %e %H:%M:%S %Y" |
|
||||
| %d | zero-padded day of the month as a decimal number \[01,31] |
|
||||
| %e | space-padded day of the month as a decimal number \[ 1,31]; equivalent to %\_d |
|
||||
| %H | hour (24-hour clock) as a decimal number \[00,23] |
|
||||
| %I | hour (12-hour clock) as a decimal number \[01,12] |
|
||||
| %j | day of the year as a decimal number \[001,366] |
|
||||
| %m | month as a decimal number \[01,12] |
|
||||
| %M | minute as a decimal number \[00,59] |
|
||||
| %L | milliseconds as a decimal number \[000, 999] |
|
||||
| %p | either AM or PM |
|
||||
| %S | second as a decimal number \[00,61] |
|
||||
| %U | week number of the year (Sunday as the first day of the week) as a decimal number \[00,53] |
|
||||
| %w | weekday as a decimal number \[0(Sunday),6] |
|
||||
| %W | week number of the year (Monday as the first day of the week) as a decimal number \[00,53] |
|
||||
| %x | date, as "%m/%d/%Y" |
|
||||
| %X | time, as "%H:%M:%S" |
|
||||
| %y | year without century as a decimal number \[00,99] |
|
||||
| %Y | year with century as a decimal number |
|
||||
| %Z | time zone offset, such as "-0700" |
|
||||
| %% | a literal "%" character |
|
||||
|
||||
More info in: <https://github.com/d3/d3-time-format/tree/v4.0.0#locale_format>
|
||||
|
||||
### Axis ticks (v10.3.0+)
|
||||
|
||||
The default output ticks are auto. You can custom your `tickInterval`, like `1day` or `1week`.
|
||||
|
||||
```markdown
|
||||
tickInterval 1day
|
||||
```
|
||||
|
||||
The pattern is:
|
||||
|
||||
```javascript
|
||||
/^([1-9][0-9]*)(millisecond|second|minute|hour|day|week|month)$/;
|
||||
```
|
||||
|
||||
More info in: <https://github.com/d3/d3-time#interval_every>
|
||||
|
||||
Week-based `tickInterval`s start the week on sunday by default. If you wish to specify another weekday on which the `tickInterval` should start, use the `weekday` option:
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
tickInterval 1week
|
||||
weekday monday
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
tickInterval 1week
|
||||
weekday monday
|
||||
```
|
||||
|
||||
> **Warning**
|
||||
> `millisecond` and `second` support was added in v10.3.0
|
||||
|
||||
## Output in compact mode
|
||||
|
||||
The compact mode allows you to display multiple tasks in the same row. Compact mode can be enabled for a gantt chart by setting the display mode of the graph via preceding YAML settings.
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
displayMode: compact
|
||||
---
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
dateFormat YYYY-MM-DD
|
||||
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :a2, 2014-01-20, 25d
|
||||
Another one :a3, 2014-02-10, 20d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
displayMode: compact
|
||||
---
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
dateFormat YYYY-MM-DD
|
||||
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :a2, 2014-01-20, 25d
|
||||
Another one :a3, 2014-02-10, 20d
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
Comments can be entered within a gantt chart, which will be ignored by the parser. Comments need to be on their own line and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax.
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
%% This is a comment
|
||||
dateFormat YYYY-MM-DD
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
section Another
|
||||
Task in Another :2014-01-12, 12d
|
||||
another task :24d
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title A Gantt Diagram
|
||||
%% This is a comment
|
||||
dateFormat YYYY-MM-DD
|
||||
section Section
|
||||
A task :a1, 2014-01-01, 30d
|
||||
Another task :after a1, 20d
|
||||
section Another
|
||||
Task in Another :2014-01-12, 12d
|
||||
another task :24d
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
Styling of the Gantt diagram is done by defining a number of CSS classes. During rendering, these classes are extracted from the file located at src/diagrams/gantt/styles.js
|
||||
|
||||
### Classes used
|
||||
|
||||
| Class | Description |
|
||||
| --------------------- | ---------------------------------------------------------------------- |
|
||||
| grid.tick | Styling for the Grid Lines |
|
||||
| grid.path | Styling for the Grid's borders |
|
||||
| .taskText | Task Text Styling |
|
||||
| .taskTextOutsideRight | Styling for Task Text that exceeds the activity bar towards the right. |
|
||||
| .taskTextOutsideLeft | Styling for Task Text that exceeds the activity bar, towards the left. |
|
||||
| todayMarker | Toggle and Styling for the "Today Marker" |
|
||||
|
||||
### Sample stylesheet
|
||||
|
||||
```css
|
||||
.grid .tick {
|
||||
stroke: lightgrey;
|
||||
opacity: 0.3;
|
||||
shape-rendering: crispEdges;
|
||||
}
|
||||
.grid path {
|
||||
stroke-width: 0;
|
||||
}
|
||||
|
||||
#tag {
|
||||
color: white;
|
||||
background: #fa283d;
|
||||
width: 150px;
|
||||
position: absolute;
|
||||
display: none;
|
||||
padding: 3px 6px;
|
||||
margin-left: -80px;
|
||||
font-size: 11px;
|
||||
}
|
||||
|
||||
#tag:before {
|
||||
border: solid transparent;
|
||||
content: ' ';
|
||||
height: 0;
|
||||
left: 50%;
|
||||
margin-left: -5px;
|
||||
position: absolute;
|
||||
width: 0;
|
||||
border-width: 10px;
|
||||
border-bottom-color: #fa283d;
|
||||
top: -20px;
|
||||
}
|
||||
.taskText {
|
||||
fill: white;
|
||||
text-anchor: middle;
|
||||
}
|
||||
.taskTextOutsideRight {
|
||||
fill: black;
|
||||
text-anchor: start;
|
||||
}
|
||||
.taskTextOutsideLeft {
|
||||
fill: black;
|
||||
text-anchor: end;
|
||||
}
|
||||
```
|
||||
|
||||
## Today marker
|
||||
|
||||
You can style or hide the marker for the current date. To style it, add a value for the `todayMarker` key.
|
||||
|
||||
```
|
||||
todayMarker stroke-width:5px,stroke:#0f0,opacity:0.5
|
||||
```
|
||||
|
||||
To hide the marker, set `todayMarker` to `off`.
|
||||
|
||||
```
|
||||
todayMarker off
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
It is possible to adjust the margins for rendering the gantt diagram.
|
||||
|
||||
This is done by defining the `ganttConfig` part of the configuration object.
|
||||
How to use the CLI is described in the [mermaidCLI](../config/mermaidCLI.md) page.
|
||||
|
||||
mermaid.ganttConfig can be set to a JSON string with config parameters or the corresponding object.
|
||||
|
||||
```javascript
|
||||
mermaid.ganttConfig = {
|
||||
titleTopMargin: 25, // Margin top for the text over the diagram
|
||||
barHeight: 20, // The height of the bars in the graph
|
||||
barGap: 4, // The margin between the different activities in the gantt diagram
|
||||
topPadding: 75, // Margin between title and gantt diagram and between axis and gantt diagram.
|
||||
rightPadding: 75, // The space allocated for the section name to the right of the activities
|
||||
leftPadding: 75, // The space allocated for the section name to the left of the activities
|
||||
gridLineStartPadding: 10, // Vertical starting position of the grid lines
|
||||
fontSize: 12, // Font size
|
||||
sectionFontSize: 24, // Font size for sections
|
||||
numberSectionStyles: 1, // The number of alternating section styles
|
||||
axisFormat: '%d/%m', // Date/time format of the axis
|
||||
tickInterval: '1week', // Axis ticks
|
||||
topAxis: true, // When this flag is set, date labels will be added to the top of the chart
|
||||
displayMode: 'compact', // Turns compact mode on
|
||||
weekday: 'sunday', // On which day a week-based interval should start
|
||||
};
|
||||
```
|
||||
|
||||
### Possible configuration params:
|
||||
|
||||
| Param | Description | Default value |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
|
||||
| mirrorActor | Turns on/off the rendering of actors below the diagram as well as above it | false |
|
||||
| bottomMarginAdj | Adjusts how far down the graph ended. Wide borders styles with css could generate unwanted clipping which is why this config param exists. | 1 |
|
||||
|
||||
## Interaction
|
||||
|
||||
It is possible to bind a click event to a task. The click can lead to either a javascript callback or to a link which will be opened in the current browser tab. **Note**: This functionality is disabled when using `securityLevel='strict'` and enabled when using `securityLevel='loose'`.
|
||||
|
||||
```
|
||||
click taskId call callback(arguments)
|
||||
click taskId href URL
|
||||
```
|
||||
|
||||
- taskId is the id of the task
|
||||
- callback is the name of a javascript function defined on the page displaying the graph, the function will be called with the taskId as the parameter if no other arguments are specified.
|
||||
|
||||
Beginner's tip—a full example using interactive links in an HTML context:
|
||||
|
||||
```html
|
||||
<body>
|
||||
<pre class="mermaid">
|
||||
gantt
|
||||
dateFormat YYYY-MM-DD
|
||||
|
||||
section Clickable
|
||||
Visit mermaidjs :active, cl1, 2014-01-07, 3d
|
||||
Print arguments :cl2, after cl1, 3d
|
||||
Print task :cl3, after cl2, 3d
|
||||
|
||||
click cl1 href "https://mermaidjs.github.io/"
|
||||
click cl2 call printArguments("test1", "test2", test3)
|
||||
click cl3 call printTask()
|
||||
</pre>
|
||||
|
||||
<script>
|
||||
const printArguments = function (arg1, arg2, arg3) {
|
||||
alert('printArguments called with arguments: ' + arg1 + ', ' + arg2 + ', ' + arg3);
|
||||
};
|
||||
const printTask = function (taskId) {
|
||||
alert('taskId: ' + taskId);
|
||||
};
|
||||
const config = {
|
||||
startOnLoad: true,
|
||||
securityLevel: 'loose',
|
||||
};
|
||||
mermaid.initialize(config);
|
||||
</script>
|
||||
</body>
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Bar chart (using gantt chart)
|
||||
|
||||
```mermaid-example
|
||||
gantt
|
||||
title Git Issues - days since last update
|
||||
dateFormat X
|
||||
axisFormat %s
|
||||
section Issue19062
|
||||
71 : 0, 71
|
||||
section Issue19401
|
||||
36 : 0, 36
|
||||
section Issue193
|
||||
34 : 0, 34
|
||||
section Issue7441
|
||||
9 : 0, 9
|
||||
section Issue1300
|
||||
5 : 0, 5
|
||||
```
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title Git Issues - days since last update
|
||||
dateFormat X
|
||||
axisFormat %s
|
||||
section Issue19062
|
||||
71 : 0, 71
|
||||
section Issue19401
|
||||
36 : 0, 36
|
||||
section Issue193
|
||||
34 : 0, 34
|
||||
section Issue7441
|
||||
9 : 0, 9
|
||||
section Issue1300
|
||||
5 : 0, 5
|
||||
```
|
||||
|
||||
### Timeline (with comments, CSS, config in frontmatter)
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
# Frontmatter config, YAML comments
|
||||
title: Ignored if specified in chart
|
||||
displayMode: compact #gantt specific setting but works at this level too
|
||||
config:
|
||||
# theme: forest
|
||||
# themeCSS: " #item36 { fill: CadetBlue } "
|
||||
themeCSS: " // YAML supports multiline strings using a newline markers: \n
|
||||
#item36 { fill: CadetBlue } \n
|
||||
|
||||
// Custom marker workaround CSS from forum (below) \n
|
||||
rect[id^=workaround] { height: calc(100% - 50px) ; transform: translate(9px, 25px); y: 0; width: 1.5px; stroke: none; fill: red; } \n
|
||||
text[id^=workaround] { fill: red; y: 100%; font-size: 15px;}
|
||||
"
|
||||
gantt:
|
||||
useWidth: 400
|
||||
rightPadding: 0
|
||||
topAxis: true #false
|
||||
numberSectionStyles: 2
|
||||
---
|
||||
gantt
|
||||
title Timeline - Gantt Sampler
|
||||
dateFormat YYYY
|
||||
axisFormat %y
|
||||
%% this next line doesn't recognise 'decade' or 'year', but will silently ignore
|
||||
tickInterval 1decade
|
||||
|
||||
section Issue19062
|
||||
71 : item71, 1900, 1930
|
||||
section Issue19401
|
||||
36 : item36, 1913, 1935
|
||||
section Issue1300
|
||||
94 : item94, 1910, 1915
|
||||
5 : item5, 1920, 1925
|
||||
0 : milestone, item0, 1918, 1s
|
||||
9 : vert, 1906, 1s %% not yet official
|
||||
64 : workaround, 1923, 1s %% custom CSS object https://github.com/mermaid-js/mermaid/issues/3250
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
# Frontmatter config, YAML comments
|
||||
title: Ignored if specified in chart
|
||||
displayMode: compact #gantt specific setting but works at this level too
|
||||
config:
|
||||
# theme: forest
|
||||
# themeCSS: " #item36 { fill: CadetBlue } "
|
||||
themeCSS: " // YAML supports multiline strings using a newline markers: \n
|
||||
#item36 { fill: CadetBlue } \n
|
||||
|
||||
// Custom marker workaround CSS from forum (below) \n
|
||||
rect[id^=workaround] { height: calc(100% - 50px) ; transform: translate(9px, 25px); y: 0; width: 1.5px; stroke: none; fill: red; } \n
|
||||
text[id^=workaround] { fill: red; y: 100%; font-size: 15px;}
|
||||
"
|
||||
gantt:
|
||||
useWidth: 400
|
||||
rightPadding: 0
|
||||
topAxis: true #false
|
||||
numberSectionStyles: 2
|
||||
---
|
||||
gantt
|
||||
title Timeline - Gantt Sampler
|
||||
dateFormat YYYY
|
||||
axisFormat %y
|
||||
%% this next line doesn't recognise 'decade' or 'year', but will silently ignore
|
||||
tickInterval 1decade
|
||||
|
||||
section Issue19062
|
||||
71 : item71, 1900, 1930
|
||||
section Issue19401
|
||||
36 : item36, 1913, 1935
|
||||
section Issue1300
|
||||
94 : item94, 1910, 1915
|
||||
5 : item5, 1920, 1925
|
||||
0 : milestone, item0, 1918, 1s
|
||||
9 : vert, 1906, 1s %% not yet official
|
||||
64 : workaround, 1923, 1s %% custom CSS object https://github.com/mermaid-js/mermaid/issues/3250
|
||||
```
|
||||
|
||||
<!--- cspell:ignore isadded --->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,161 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/kanban.md](../../packages/mermaid/src/docs/syntax/kanban.md).
|
||||
|
||||
# Mermaid Kanban Diagram Documentation
|
||||
|
||||
Mermaid’s Kanban diagram allows you to create visual representations of tasks moving through different stages of a workflow. This guide explains how to use the Kanban diagram syntax, based on the provided example.
|
||||
|
||||
## Overview
|
||||
|
||||
A Kanban diagram in Mermaid starts with the kanban keyword, followed by the definition of columns (stages) and tasks within those columns.
|
||||
|
||||
```mermaid-example
|
||||
kanban
|
||||
column1[Column Title]
|
||||
task1[Task Description]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
kanban
|
||||
column1[Column Title]
|
||||
task1[Task Description]
|
||||
```
|
||||
|
||||
## Defining Columns
|
||||
|
||||
Columns represent the different stages in your workflow, such as “Todo,” “In Progress,” “Done,” etc. Each column is defined using a unique identifier and a title enclosed in square brackets.
|
||||
|
||||
**Syntax:**
|
||||
|
||||
```
|
||||
columnId[Column Title]
|
||||
```
|
||||
|
||||
- columnId: A unique identifier for the column.
|
||||
- \[Column Title]: The title displayed on the column header.
|
||||
|
||||
Like this `id1[Todo]`
|
||||
|
||||
## Adding Tasks to Columns
|
||||
|
||||
Tasks are listed under their respective columns with an indentation. Each task also has a unique identifier and a description enclosed in square brackets.
|
||||
|
||||
**Syntax:**
|
||||
|
||||
```
|
||||
taskId[Task Description]
|
||||
```
|
||||
|
||||
```
|
||||
• taskId: A unique identifier for the task.
|
||||
• [Task Description]: The description of the task.
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
docs[Create Documentation]
|
||||
```
|
||||
|
||||
## Adding Metadata to Tasks
|
||||
|
||||
You can include additional metadata for each task using the @{ ... } syntax. Metadata can contain key-value pairs like assigned, ticket, priority, etc. This will be rendered added to the rendering of the node.
|
||||
|
||||
## Supported Metadata Keys
|
||||
|
||||
```
|
||||
• assigned: Specifies who is responsible for the task.
|
||||
• ticket: Links the task to a ticket or issue number.
|
||||
• priority: Indicates the urgency of the task. Allowed values: 'Very High', 'High', 'Low' and 'Very Low'
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
kanban
|
||||
todo[Todo]
|
||||
id3[Update Database Function]@{ ticket: MC-2037, assigned: 'knsv', priority: 'High' }
|
||||
```
|
||||
|
||||
```mermaid
|
||||
kanban
|
||||
todo[Todo]
|
||||
id3[Update Database Function]@{ ticket: MC-2037, assigned: 'knsv', priority: 'High' }
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
You can customize the Kanban diagram using a configuration block at the beginning of your markdown file. This is useful for setting global settings like a base URL for tickets. Currently there is one configuration option for kanban diagrams `ticketBaseUrl`. This can be set as in the following example:
|
||||
|
||||
```yaml
|
||||
---
|
||||
config:
|
||||
kanban:
|
||||
ticketBaseUrl: 'https://yourproject.atlassian.net/browse/#TICKET#'
|
||||
---
|
||||
```
|
||||
|
||||
When the kanban item has an assigned ticket number the ticket number in the diagram will have a link to an external system where the ticket is defined. The `ticketBaseUrl` sets the base URL to the external system and #TICKET# is replaced with the ticket value from task metadata to create a valid link.
|
||||
|
||||
## Full Example
|
||||
|
||||
Below is the full Kanban diagram based on the provided example:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
kanban:
|
||||
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
|
||||
---
|
||||
kanban
|
||||
Todo
|
||||
[Create Documentation]
|
||||
docs[Create Blog about the new diagram]
|
||||
[In progress]
|
||||
id6[Create renderer so that it works in all cases. We also add some extra text here for testing purposes. And some more just for the extra flare.]
|
||||
id9[Ready for deploy]
|
||||
id8[Design grammar]@{ assigned: 'knsv' }
|
||||
id10[Ready for test]
|
||||
id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
|
||||
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
|
||||
id11[Done]
|
||||
id5[define getData]
|
||||
id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
|
||||
id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
|
||||
|
||||
id12[Can't reproduce]
|
||||
id3[Weird flickering in Firefox]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
kanban:
|
||||
ticketBaseUrl: 'https://mermaidchart.atlassian.net/browse/#TICKET#'
|
||||
---
|
||||
kanban
|
||||
Todo
|
||||
[Create Documentation]
|
||||
docs[Create Blog about the new diagram]
|
||||
[In progress]
|
||||
id6[Create renderer so that it works in all cases. We also add some extra text here for testing purposes. And some more just for the extra flare.]
|
||||
id9[Ready for deploy]
|
||||
id8[Design grammar]@{ assigned: 'knsv' }
|
||||
id10[Ready for test]
|
||||
id4[Create parsing tests]@{ ticket: MC-2038, assigned: 'K.Sveidqvist', priority: 'High' }
|
||||
id66[last item]@{ priority: 'Very Low', assigned: 'knsv' }
|
||||
id11[Done]
|
||||
id5[define getData]
|
||||
id2[Title of diagram is more than 100 chars when user duplicates diagram with 100 char]@{ ticket: MC-2036, priority: 'Very High'}
|
||||
id3[Update DB function]@{ ticket: MC-2037, assigned: knsv, priority: 'High' }
|
||||
|
||||
id12[Can't reproduce]
|
||||
id3[Weird flickering in Firefox]
|
||||
```
|
||||
|
||||
In conclusion, creating a Kanban diagram in Mermaid is a straightforward process that effectively visualizes your workflow. Start by using the kanban keyword to initiate the diagram. Define your columns with unique identifiers and titles to represent different stages of your project. Under each column, list your tasks—also with unique identifiers—and provide detailed descriptions as needed. Remember that proper indentation is crucial; tasks must be indented under their parent columns to maintain the correct structure.
|
||||
|
||||
You can enhance your diagram by adding optional metadata to tasks using the @{ ... } syntax, which allows you to include additional context such as assignee, ticket numbers, and priority levels. For further customization, utilize the configuration block at the top of your file to set global options like ticketBaseUrl for linking tickets directly from your diagram.
|
||||
|
||||
By adhering to these guidelines—ensuring unique identifiers, proper indentation, and utilizing metadata and configuration options—you can create a comprehensive and customized Kanban board that effectively maps out your project’s workflow using Mermaid.
|
||||
@@ -1,335 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/mindmap.md](../../packages/mermaid/src/docs/syntax/mindmap.md).
|
||||
|
||||
# Mindmap
|
||||
|
||||
> Mindmap: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
|
||||
|
||||
"A mind map is a diagram used to visually organize information into a hierarchy, showing relationships among pieces of the whole. It is often created around a single concept, drawn as an image in the center of a blank page, to which associated representations of ideas such as images, words and parts of words are added. Major ideas are connected directly to the central concept, and other ideas branch out from those major ideas." Wikipedia
|
||||
|
||||
### An example of a mindmap.
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
root((mindmap))
|
||||
Origins
|
||||
Long history
|
||||
::icon(fa fa-book)
|
||||
Popularisation
|
||||
British popular psychology author Tony Buzan
|
||||
Research
|
||||
On effectiveness<br/>and features
|
||||
On Automatic creation
|
||||
Uses
|
||||
Creative techniques
|
||||
Strategic planning
|
||||
Argument mapping
|
||||
Tools
|
||||
Pen and paper
|
||||
Mermaid
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
root((mindmap))
|
||||
Origins
|
||||
Long history
|
||||
::icon(fa fa-book)
|
||||
Popularisation
|
||||
British popular psychology author Tony Buzan
|
||||
Research
|
||||
On effectiveness<br/>and features
|
||||
On Automatic creation
|
||||
Uses
|
||||
Creative techniques
|
||||
Strategic planning
|
||||
Argument mapping
|
||||
Tools
|
||||
Pen and paper
|
||||
Mermaid
|
||||
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
The syntax for creating Mindmaps is simple and relies on indentation for setting the levels in the hierarchy.
|
||||
|
||||
In the following example you can see how there are 3 different levels. One with starting at the left of the text and another level with two rows starting at the same column, defining the node A. At the end there is one more level where the text is indented further than the previous lines defining the nodes B and C.
|
||||
|
||||
```
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
In summary is a simple text outline where there is one node at the root level called `Root` which has one child `A`. `A` in turn has two children `B`and `C`. In the diagram below we can see this rendered as a mindmap.
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
In this way we can use a text outline to generate a hierarchical mindmap.
|
||||
|
||||
## Different shapes
|
||||
|
||||
Mermaid mindmaps can show nodes using different shapes. When specifying a shape for a node the syntax is similar to flowchart nodes, with an id followed by the shape definition and with the text within the shape delimiters. Where possible we try/will try to keep the same shapes as for flowcharts, even though they are not all supported from the start.
|
||||
|
||||
Mindmap can show the following shapes:
|
||||
|
||||
### Square
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id[I am a square]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id[I am a square]
|
||||
```
|
||||
|
||||
### Rounded square
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id(I am a rounded square)
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id(I am a rounded square)
|
||||
```
|
||||
|
||||
### Circle
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id((I am a circle))
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id((I am a circle))
|
||||
```
|
||||
|
||||
### Bang
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id))I am a bang((
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id))I am a bang((
|
||||
```
|
||||
|
||||
### Cloud
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id)I am a cloud(
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id)I am a cloud(
|
||||
```
|
||||
|
||||
### Hexagon
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id{{I am a hexagon}}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id{{I am a hexagon}}
|
||||
```
|
||||
|
||||
### Default
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
I am the default shape
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
I am the default shape
|
||||
```
|
||||
|
||||
More shapes will be added, beginning with the shapes available in flowcharts.
|
||||
|
||||
# Icons and classes
|
||||
|
||||
## Icons
|
||||
|
||||
As with flowcharts you can add icons to your nodes but with an updated syntax. The styling for the font based icons are added during the integration so that they are available for the web page. _This is not something a diagram author can do but has to be done with the site administrator or the integrator_. Once the icon fonts are in place you add them to the mind map nodes using the `::icon()` syntax. You place the classes for the icon within the parenthesis like in the following example where icons for material design and [Font Awesome 5](https://fontawesome.com/v5/search?o=r&m=free) are displayed. The intention is that this approach should be used for all diagrams supporting icons. **Experimental feature:** This wider scope is also the reason Mindmaps are experimental as this syntax and approach could change.
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
::icon(fa fa-book)
|
||||
B(B)
|
||||
::icon(mdi mdi-skull-outline)
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
::icon(fa fa-book)
|
||||
B(B)
|
||||
::icon(mdi mdi-skull-outline)
|
||||
```
|
||||
|
||||
## Classes
|
||||
|
||||
Again the syntax for adding classes is similar to flowcharts. You can add classes using a triple colon following a number of css classes separated by space. In the following example one of the nodes has two custom classes attached urgent turning the background red and the text white and large increasing the font size:
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
Root
|
||||
A[A]
|
||||
:::urgent large
|
||||
B(B)
|
||||
C
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
Root
|
||||
A[A]
|
||||
:::urgent large
|
||||
B(B)
|
||||
C
|
||||
```
|
||||
|
||||
_These classes need to be supplied by the site administrator._
|
||||
|
||||
## Unclear indentation
|
||||
|
||||
The actual indentation does not really matter only compared with the previous rows. If we take the previous example and disrupt it a little we can see how the calculations are performed. Let us start with placing C with a smaller indentation than `B` but larger then `A`.
|
||||
|
||||
```
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
This outline is unclear as `B` clearly is a child of `A` but when we move on to `C` the clarity is lost. `C` is neither a child of `B` with a higher indentation nor does it have the same indentation as `B`. The only thing that is clear is that the first node with smaller indentation, indicating a parent, is A. Then Mermaid relies on this known truth and compensates for the unclear indentation and selects `A` as a parent of `C` leading till the same diagram with `B` and `C` as siblings.
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
Root
|
||||
A
|
||||
B
|
||||
C
|
||||
```
|
||||
|
||||
## Markdown Strings
|
||||
|
||||
The "Markdown Strings" feature enhances mind maps by offering a more versatile string type, which supports text formatting options such as bold and italics, and automatically wraps text within labels.
|
||||
|
||||
```mermaid-example
|
||||
mindmap
|
||||
id1["`**Root** with
|
||||
a second line
|
||||
Unicode works too: 🤓`"]
|
||||
id2["`The dog in **the** hog... a *very long text* that wraps to a new line`"]
|
||||
id3[Regular labels still works]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
mindmap
|
||||
id1["`**Root** with
|
||||
a second line
|
||||
Unicode works too: 🤓`"]
|
||||
id2["`The dog in **the** hog... a *very long text* that wraps to a new line`"]
|
||||
id3[Regular labels still works]
|
||||
```
|
||||
|
||||
Formatting:
|
||||
|
||||
- For bold text, use double asterisks \*\* before and after the text.
|
||||
- For italics, use single asterisks \* before and after the text.
|
||||
- With traditional strings, you needed to add <br> tags for text to wrap in nodes. However, markdown strings automatically wrap text when it becomes too long and allows you to start a new line by simply using a newline character instead of a <br> tag.
|
||||
|
||||
## Integrating with your library/website.
|
||||
|
||||
Mindmap uses the experimental lazy loading & async rendering features which could change in the future. From version 9.4.0 this diagram is included in mermaid but use lazy loading in order to keep the size of mermaid down. This is important in order to be able to add additional diagrams going forward.
|
||||
|
||||
You can still use the pre 9.4.0 method to add mermaid with mindmaps to a web page:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@9.3.0/dist/mermaid.esm.min.mjs';
|
||||
import mindmap from 'https://cdn.jsdelivr.net/npm/@mermaid-js/mermaid-mindmap@9.3.0/dist/mermaid-mindmap.esm.min.mjs';
|
||||
await mermaid.registerExternalDiagrams([mindmap]);
|
||||
</script>
|
||||
```
|
||||
|
||||
From version 9.4.0 you can simplify this code to:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||||
</script>
|
||||
```
|
||||
|
||||
You can also refer the [implementation in the live editor](https://github.com/mermaid-js/mermaid-live-editor/blob/develop/src/lib/util/mermaid.ts) to see how the async loading is done.
|
||||
|
||||
<!---
|
||||
cspell:locale en,en-gb
|
||||
cspell:ignore Buzan
|
||||
--->
|
||||
|
||||
## Layouts
|
||||
|
||||
Mermaid also supports a Tidy Tree layout for mindmaps.
|
||||
|
||||
```
|
||||
---
|
||||
config:
|
||||
layout: tidy-tree
|
||||
---
|
||||
mindmap
|
||||
root((mindmap is a long thing))
|
||||
A
|
||||
B
|
||||
C
|
||||
D
|
||||
```
|
||||
|
||||
Instructions to add and register tidy-tree layout are present in [Tidy Tree Configuration](/config/tidy-tree)
|
||||
@@ -1,153 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/packet.md](../../packages/mermaid/src/docs/syntax/packet.md).
|
||||
|
||||
# Packet Diagram (v11.0.0+)
|
||||
|
||||
## Introduction
|
||||
|
||||
A packet diagram is a visual representation used to illustrate the structure and contents of a network packet. Network packets are the fundamental units of data transferred over a network.
|
||||
|
||||
## Usage
|
||||
|
||||
This diagram type is particularly useful for developers, network engineers, educators, and students who require a clear and concise way to represent the structure of network packets.
|
||||
|
||||
## Syntax
|
||||
|
||||
```
|
||||
packet
|
||||
start: "Block name" %% Single-bit block
|
||||
start-end: "Block name" %% Multi-bit blocks
|
||||
... More Fields ...
|
||||
```
|
||||
|
||||
### Bits Syntax (v11.7.0+)
|
||||
|
||||
Using start and end bit counts can be difficult, especially when modifying a design. For this we add a bit count field, which starts from the end of the previous field automagically. Use `+<count>` to set the number of bits, thus:
|
||||
|
||||
```
|
||||
packet
|
||||
+1: "Block name" %% Single-bit block
|
||||
+8: "Block name" %% 8-bit block
|
||||
9-15: "Manually set start and end, it's fine to mix and match"
|
||||
... More Fields ...
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: "TCP Packet"
|
||||
---
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
64-95: "Acknowledgment Number"
|
||||
96-99: "Data Offset"
|
||||
100-105: "Reserved"
|
||||
106: "URG"
|
||||
107: "ACK"
|
||||
108: "PSH"
|
||||
109: "RST"
|
||||
110: "SYN"
|
||||
111: "FIN"
|
||||
112-127: "Window"
|
||||
128-143: "Checksum"
|
||||
144-159: "Urgent Pointer"
|
||||
160-191: "(Options and Padding)"
|
||||
192-255: "Data (variable length)"
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
packet
|
||||
title UDP Packet
|
||||
+16: "Source Port"
|
||||
+16: "Destination Port"
|
||||
32-47: "Length"
|
||||
48-63: "Checksum"
|
||||
64-95: "Data (variable length)"
|
||||
```
|
||||
|
||||
```mermaid
|
||||
packet
|
||||
title UDP Packet
|
||||
+16: "Source Port"
|
||||
+16: "Destination Port"
|
||||
32-47: "Length"
|
||||
48-63: "Checksum"
|
||||
64-95: "Data (variable length)"
|
||||
```
|
||||
|
||||
## Details of Syntax
|
||||
|
||||
- **Ranges**: Each line after the title represents a different field in the packet. The range (e.g., `0-15`) indicates the bit positions in the packet.
|
||||
- **Field Description**: A brief description of what the field represents, enclosed in quotes.
|
||||
|
||||
## Configuration
|
||||
|
||||
Please refer to the [configuration](/config/schema-docs/config-defs-packet-diagram-config.html) guide for details.
|
||||
|
||||
<!--
|
||||
|
||||
Theme variables are not currently working due to a mermaid bug. The passed values are not being propagated into styles function.
|
||||
|
||||
## Theme Variables
|
||||
|
||||
| Property | Description | Default Value |
|
||||
| ---------------- | -------------------------- | ------------- |
|
||||
| byteFontSize | Font size of the bytes | '10px' |
|
||||
| startByteColor | Color of the starting byte | 'black' |
|
||||
| endByteColor | Color of the ending byte | 'black' |
|
||||
| labelColor | Color of the labels | 'black' |
|
||||
| labelFontSize | Font size of the labels | '12px' |
|
||||
| titleColor | Color of the title | 'black' |
|
||||
| titleFontSize | Font size of the title | '14px' |
|
||||
| blockStrokeColor | Color of the block stroke | 'black' |
|
||||
| blockStrokeWidth | Width of the block stroke | '1' |
|
||||
| blockFillColor | Fill color of the block | '#efefef' |
|
||||
|
||||
## Example on config and theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
packet:
|
||||
showBits: true
|
||||
themeVariables:
|
||||
packet:
|
||||
startByteColor: red
|
||||
---
|
||||
packet
|
||||
0-15: "Source Port"
|
||||
16-31: "Destination Port"
|
||||
32-63: "Sequence Number"
|
||||
```
|
||||
|
||||
-->
|
||||
@@ -1,93 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/pie.md](../../packages/mermaid/src/docs/syntax/pie.md).
|
||||
|
||||
# Pie chart diagrams
|
||||
|
||||
> A pie chart (or a circle chart) is a circular statistical graphic, which is divided into slices to illustrate numerical proportion. In a pie chart, the arc length of each slice (and consequently its central angle and area), is proportional to the quantity it represents. While it is named for its resemblance to a pie which has been sliced, there are variations on the way it can be presented. The earliest known pie chart is generally credited to William Playfair's Statistical Breviary of 1801
|
||||
> -Wikipedia
|
||||
|
||||
Mermaid can render Pie Chart diagrams.
|
||||
|
||||
```mermaid-example
|
||||
pie title Pets adopted by volunteers
|
||||
"Dogs" : 386
|
||||
"Cats" : 85
|
||||
"Rats" : 15
|
||||
```
|
||||
|
||||
```mermaid
|
||||
pie title Pets adopted by volunteers
|
||||
"Dogs" : 386
|
||||
"Cats" : 85
|
||||
"Rats" : 15
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
Drawing a pie chart is really simple in mermaid.
|
||||
|
||||
- Start with `pie` keyword to begin the diagram
|
||||
- `showData` to render the actual data values after the legend text. This is **_OPTIONAL_**
|
||||
- Followed by `title` keyword and its value in string to give a title to the pie-chart. This is **_OPTIONAL_**
|
||||
- Followed by dataSet. Pie slices will be ordered clockwise in the same order as the labels.
|
||||
- `label` for a section in the pie diagram within `" "` quotes.
|
||||
- Followed by `:` colon as separator
|
||||
- Followed by `positive numeric value` (supported up to two decimal places)
|
||||
|
||||
**Note:**
|
||||
|
||||
> Pie chart values must be **positive numbers greater than zero**.
|
||||
> **Negative values are not allowed** and will result in an error.
|
||||
|
||||
\[pie] \[showData] (OPTIONAL)
|
||||
\[title] \[titlevalue] (OPTIONAL)
|
||||
"\[datakey1]" : \[dataValue1]
|
||||
"\[datakey2]" : \[dataValue2]
|
||||
"\[datakey3]" : \[dataValue3]
|
||||
.
|
||||
.
|
||||
|
||||
## Example
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
pie:
|
||||
textPosition: 0.5
|
||||
themeVariables:
|
||||
pieOuterStrokeWidth: "5px"
|
||||
---
|
||||
pie showData
|
||||
title Key elements in Product X
|
||||
"Calcium" : 42.96
|
||||
"Potassium" : 50.05
|
||||
"Magnesium" : 10.01
|
||||
"Iron" : 5
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
pie:
|
||||
textPosition: 0.5
|
||||
themeVariables:
|
||||
pieOuterStrokeWidth: "5px"
|
||||
---
|
||||
pie showData
|
||||
title Key elements in Product X
|
||||
"Calcium" : 42.96
|
||||
"Potassium" : 50.05
|
||||
"Magnesium" : 10.01
|
||||
"Iron" : 5
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Possible pie diagram configuration parameters:
|
||||
|
||||
| Parameter | Description | Default value |
|
||||
| -------------- | ------------------------------------------------------------------------------------------------------------ | ------------- |
|
||||
| `textPosition` | The axial position of the pie slice labels, from 0.0 at the center to 1.0 at the outside edge of the circle. | `0.75` |
|
||||
@@ -1,267 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/quadrantChart.md](../../packages/mermaid/src/docs/syntax/quadrantChart.md).
|
||||
|
||||
# Quadrant Chart
|
||||
|
||||
> A quadrant chart is a visual representation of data that is divided into four quadrants. It is used to plot data points on a two-dimensional grid, with one variable represented on the x-axis and another variable represented on the y-axis. The quadrants are determined by dividing the chart into four equal parts based on a set of criteria that is specific to the data being analyzed. Quadrant charts are often used to identify patterns and trends in data, and to prioritize actions based on the position of data points within the chart. They are commonly used in business, marketing, and risk management, among other fields.
|
||||
|
||||
## Example
|
||||
|
||||
```mermaid-example
|
||||
quadrantChart
|
||||
title Reach and engagement of campaigns
|
||||
x-axis Low Reach --> High Reach
|
||||
y-axis Low Engagement --> High Engagement
|
||||
quadrant-1 We should expand
|
||||
quadrant-2 Need to promote
|
||||
quadrant-3 Re-evaluate
|
||||
quadrant-4 May be improved
|
||||
Campaign A: [0.3, 0.6]
|
||||
Campaign B: [0.45, 0.23]
|
||||
Campaign C: [0.57, 0.69]
|
||||
Campaign D: [0.78, 0.34]
|
||||
Campaign E: [0.40, 0.34]
|
||||
Campaign F: [0.35, 0.78]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
quadrantChart
|
||||
title Reach and engagement of campaigns
|
||||
x-axis Low Reach --> High Reach
|
||||
y-axis Low Engagement --> High Engagement
|
||||
quadrant-1 We should expand
|
||||
quadrant-2 Need to promote
|
||||
quadrant-3 Re-evaluate
|
||||
quadrant-4 May be improved
|
||||
Campaign A: [0.3, 0.6]
|
||||
Campaign B: [0.45, 0.23]
|
||||
Campaign C: [0.57, 0.69]
|
||||
Campaign D: [0.78, 0.34]
|
||||
Campaign E: [0.40, 0.34]
|
||||
Campaign F: [0.35, 0.78]
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
> **Note**
|
||||
> If there are no points available in the chart both **axis** text and **quadrant** will be rendered in the center of the respective quadrant.
|
||||
> If there are points **x-axis** labels will rendered from the left of the respective quadrant also they will be displayed at the bottom of the chart, and **y-axis** labels will be rendered at the bottom of the respective quadrant, the quadrant text will render at the top of the respective quadrant.
|
||||
|
||||
> **Note**
|
||||
> For points x and y value min value is 0 and max value is 1.
|
||||
|
||||
### Title
|
||||
|
||||
The title is a short description of the chart and it will always render on top of the chart.
|
||||
|
||||
#### Example
|
||||
|
||||
```
|
||||
quadrantChart
|
||||
title This is a sample example
|
||||
```
|
||||
|
||||
### x-axis
|
||||
|
||||
The x-axis determines what text would be displayed in the x-axis. In x-axis there is two part **left** and **right** you can pass **both** or you can pass only **left**. The statement should start with `x-axis` then the `left axis text` followed by the delimiter `-->` then `right axis text`.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `x-axis <text> --> <text>` both the left and right axis text will be rendered.
|
||||
2. `x-axis <text>` only the left axis text will be rendered.
|
||||
|
||||
### y-axis
|
||||
|
||||
The y-axis determines what text would be displayed in the y-axis. In y-axis there is two part **top** and **bottom** you can pass **both** or you can pass only **bottom**. The statement should start with `y-axis` then the `bottom axis text` followed by the delimiter `-->` then `top axis text`.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `y-axis <text> --> <text>` both the bottom and top axis text will be rendered.
|
||||
2. `y-axis <text>` only the bottom axis text will be rendered.
|
||||
|
||||
### Quadrants text
|
||||
|
||||
The `quadrant-[1,2,3,4]` determine what text would be displayed inside the quadrants.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `quadrant-1 <text>` determine what text will be rendered inside the top right quadrant.
|
||||
2. `quadrant-2 <text>` determine what text will be rendered inside the top left quadrant.
|
||||
3. `quadrant-3 <text>` determine what text will be rendered inside the bottom left quadrant.
|
||||
4. `quadrant-4 <text>` determine what text will be rendered inside the bottom right quadrant.
|
||||
|
||||
### Points
|
||||
|
||||
Points are used to plot a circle inside the quadrantChart. The syntax is `<text>: [x, y]` here x and y value is in the range 0 - 1.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `Point 1: [0.75, 0.80]` here the Point 1 will be drawn in the top right quadrant.
|
||||
2. `Point 2: [0.35, 0.24]` here the Point 2 will be drawn in the bottom left quadrant.
|
||||
|
||||
## Chart Configurations
|
||||
|
||||
| Parameter | Description | Default value |
|
||||
| --------------------------------- | -------------------------------------------------------------------------------------------------- | :-----------: |
|
||||
| chartWidth | Width of the chart | 500 |
|
||||
| chartHeight | Height of the chart | 500 |
|
||||
| titlePadding | Top and Bottom padding of the title | 10 |
|
||||
| titleFontSize | Title font size | 20 |
|
||||
| quadrantPadding | Padding outside all the quadrants | 5 |
|
||||
| quadrantTextTopPadding | Quadrant text top padding when text is drawn on top ( not data points are there) | 5 |
|
||||
| quadrantLabelFontSize | Quadrant text font size | 16 |
|
||||
| quadrantInternalBorderStrokeWidth | Border stroke width inside the quadrants | 1 |
|
||||
| quadrantExternalBorderStrokeWidth | Quadrant external border stroke width | 2 |
|
||||
| xAxisLabelPadding | Top and bottom padding of x-axis text | 5 |
|
||||
| xAxisLabelFontSize | X-axis texts font size | 16 |
|
||||
| xAxisPosition | Position of x-axis (top , bottom) if there are points the x-axis will always be rendered in bottom | 'top' |
|
||||
| yAxisLabelPadding | Left and Right padding of y-axis text | 5 |
|
||||
| yAxisLabelFontSize | Y-axis texts font size | 16 |
|
||||
| yAxisPosition | Position of y-axis (left , right) | 'left' |
|
||||
| pointTextPadding | Padding between point and the below text | 5 |
|
||||
| pointLabelFontSize | Point text font size | 12 |
|
||||
| pointRadius | Radius of the point to be drawn | 5 |
|
||||
|
||||
## Chart Theme Variables
|
||||
|
||||
| Parameter | Description |
|
||||
| -------------------------------- | --------------------------------------- |
|
||||
| quadrant1Fill | Fill color of the top right quadrant |
|
||||
| quadrant2Fill | Fill color of the top left quadrant |
|
||||
| quadrant3Fill | Fill color of the bottom left quadrant |
|
||||
| quadrant4Fill | Fill color of the bottom right quadrant |
|
||||
| quadrant1TextFill | Text color of the top right quadrant |
|
||||
| quadrant2TextFill | Text color of the top left quadrant |
|
||||
| quadrant3TextFill | Text color of the bottom left quadrant |
|
||||
| quadrant4TextFill | Text color of the bottom right quadrant |
|
||||
| quadrantPointFill | Points fill color |
|
||||
| quadrantPointTextFill | Points text color |
|
||||
| quadrantXAxisTextFill | X-axis text color |
|
||||
| quadrantYAxisTextFill | Y-axis text color |
|
||||
| quadrantInternalBorderStrokeFill | Quadrants inner border color |
|
||||
| quadrantExternalBorderStrokeFill | Quadrants outer border color |
|
||||
| quadrantTitleFill | Title color |
|
||||
|
||||
## Example on config and theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
quadrantChart:
|
||||
chartWidth: 400
|
||||
chartHeight: 400
|
||||
themeVariables:
|
||||
quadrant1TextFill: "ff0000"
|
||||
---
|
||||
quadrantChart
|
||||
x-axis Urgent --> Not Urgent
|
||||
y-axis Not Important --> "Important ❤"
|
||||
quadrant-1 Plan
|
||||
quadrant-2 Do
|
||||
quadrant-3 Delegate
|
||||
quadrant-4 Delete
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
quadrantChart:
|
||||
chartWidth: 400
|
||||
chartHeight: 400
|
||||
themeVariables:
|
||||
quadrant1TextFill: "ff0000"
|
||||
---
|
||||
quadrantChart
|
||||
x-axis Urgent --> Not Urgent
|
||||
y-axis Not Important --> "Important ❤"
|
||||
quadrant-1 Plan
|
||||
quadrant-2 Do
|
||||
quadrant-3 Delegate
|
||||
quadrant-4 Delete
|
||||
```
|
||||
|
||||
### Point styling
|
||||
|
||||
Points can either be styled directly or with defined shared classes
|
||||
|
||||
1. Direct styling
|
||||
|
||||
```md
|
||||
Point A: [0.9, 0.0] radius: 12
|
||||
Point B: [0.8, 0.1] color: #ff3300, radius: 10
|
||||
Point C: [0.7, 0.2] radius: 25, color: #00ff33, stroke-color: #10f0f0
|
||||
Point D: [0.6, 0.3] radius: 15, stroke-color: #00ff0f, stroke-width: 5px ,color: #ff33f0
|
||||
```
|
||||
|
||||
2. Classes styling
|
||||
|
||||
```md
|
||||
Point A:::class1: [0.9, 0.0]
|
||||
Point B:::class2: [0.8, 0.1]
|
||||
Point C:::class3: [0.7, 0.2]
|
||||
Point D:::class3: [0.7, 0.2]
|
||||
classDef class1 color: #109060
|
||||
classDef class2 color: #908342, radius : 10, stroke-color: #310085, stroke-width: 10px
|
||||
classDef class3 color: #f00fff, radius : 10
|
||||
```
|
||||
|
||||
#### Available styles:
|
||||
|
||||
| Parameter | Description |
|
||||
| ------------ | ---------------------------------------------------------------------- |
|
||||
| color | Fill color of the point |
|
||||
| radius | Radius of the point |
|
||||
| stroke-width | Border width of the point |
|
||||
| stroke-color | Border color of the point (useless when stroke-width is not specified) |
|
||||
|
||||
> **Note**
|
||||
> Order of preference:
|
||||
>
|
||||
> 1. Direct styles
|
||||
> 2. Class styles
|
||||
> 3. Theme styles
|
||||
|
||||
## Example on styling
|
||||
|
||||
```mermaid-example
|
||||
quadrantChart
|
||||
title Reach and engagement of campaigns
|
||||
x-axis Low Reach --> High Reach
|
||||
y-axis Low Engagement --> High Engagement
|
||||
quadrant-1 We should expand
|
||||
quadrant-2 Need to promote
|
||||
quadrant-3 Re-evaluate
|
||||
quadrant-4 May be improved
|
||||
Campaign A: [0.9, 0.0] radius: 12
|
||||
Campaign B:::class1: [0.8, 0.1] color: #ff3300, radius: 10
|
||||
Campaign C: [0.7, 0.2] radius: 25, color: #00ff33, stroke-color: #10f0f0
|
||||
Campaign D: [0.6, 0.3] radius: 15, stroke-color: #00ff0f, stroke-width: 5px ,color: #ff33f0
|
||||
Campaign E:::class2: [0.5, 0.4]
|
||||
Campaign F:::class3: [0.4, 0.5] color: #0000ff
|
||||
classDef class1 color: #109060
|
||||
classDef class2 color: #908342, radius : 10, stroke-color: #310085, stroke-width: 10px
|
||||
classDef class3 color: #f00fff, radius : 10
|
||||
```
|
||||
|
||||
```mermaid
|
||||
quadrantChart
|
||||
title Reach and engagement of campaigns
|
||||
x-axis Low Reach --> High Reach
|
||||
y-axis Low Engagement --> High Engagement
|
||||
quadrant-1 We should expand
|
||||
quadrant-2 Need to promote
|
||||
quadrant-3 Re-evaluate
|
||||
quadrant-4 May be improved
|
||||
Campaign A: [0.9, 0.0] radius: 12
|
||||
Campaign B:::class1: [0.8, 0.1] color: #ff3300, radius: 10
|
||||
Campaign C: [0.7, 0.2] radius: 25, color: #00ff33, stroke-color: #10f0f0
|
||||
Campaign D: [0.6, 0.3] radius: 15, stroke-color: #00ff0f, stroke-width: 5px ,color: #ff33f0
|
||||
Campaign E:::class2: [0.5, 0.4]
|
||||
Campaign F:::class3: [0.4, 0.5] color: #0000ff
|
||||
classDef class1 color: #109060
|
||||
classDef class2 color: #908342, radius : 10, stroke-color: #310085, stroke-width: 10px
|
||||
classDef class3 color: #f00fff, radius : 10
|
||||
```
|
||||
@@ -1,269 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/radar.md](../../packages/mermaid/src/docs/syntax/radar.md).
|
||||
|
||||
# Radar Diagram (v11.6.0+)
|
||||
|
||||
## Introduction
|
||||
|
||||
A radar diagram is a simple way to plot low-dimensional data in a circular format.
|
||||
|
||||
It is also known as a **radar chart**, **spider chart**, **star chart**, **cobweb chart**, **polar chart**, or **Kiviat diagram**.
|
||||
|
||||
## Usage
|
||||
|
||||
This diagram type is particularly useful for developers, data scientists, and engineers who require a clear and concise way to represent data in a circular format.
|
||||
|
||||
It is commonly used to graphically summarize and compare the performance of multiple entities across multiple dimensions.
|
||||
|
||||
## Syntax
|
||||
|
||||
```md
|
||||
radar-beta
|
||||
axis A, B, C, D, E
|
||||
curve c1{1,2,3,4,5}
|
||||
curve c2{5,4,3,2,1}
|
||||
... More Fields ...
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: "Grades"
|
||||
---
|
||||
radar-beta
|
||||
axis m["Math"], s["Science"], e["English"]
|
||||
axis h["History"], g["Geography"], a["Art"]
|
||||
curve a["Alice"]{85, 90, 80, 70, 75, 90}
|
||||
curve b["Bob"]{70, 75, 85, 80, 90, 85}
|
||||
|
||||
max 100
|
||||
min 0
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: "Grades"
|
||||
---
|
||||
radar-beta
|
||||
axis m["Math"], s["Science"], e["English"]
|
||||
axis h["History"], g["Geography"], a["Art"]
|
||||
curve a["Alice"]{85, 90, 80, 70, 75, 90}
|
||||
curve b["Bob"]{70, 75, 85, 80, 90, 85}
|
||||
|
||||
max 100
|
||||
min 0
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
radar-beta
|
||||
title Restaurant Comparison
|
||||
axis food["Food Quality"], service["Service"], price["Price"]
|
||||
axis ambiance["Ambiance"]
|
||||
|
||||
curve a["Restaurant A"]{4, 3, 2, 4}
|
||||
curve b["Restaurant B"]{3, 4, 3, 3}
|
||||
curve c["Restaurant C"]{2, 3, 4, 2}
|
||||
curve d["Restaurant D"]{2, 2, 4, 3}
|
||||
|
||||
graticule polygon
|
||||
max 5
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
radar-beta
|
||||
title Restaurant Comparison
|
||||
axis food["Food Quality"], service["Service"], price["Price"]
|
||||
axis ambiance["Ambiance"]
|
||||
|
||||
curve a["Restaurant A"]{4, 3, 2, 4}
|
||||
curve b["Restaurant B"]{3, 4, 3, 3}
|
||||
curve c["Restaurant C"]{2, 3, 4, 2}
|
||||
curve d["Restaurant D"]{2, 2, 4, 3}
|
||||
|
||||
graticule polygon
|
||||
max 5
|
||||
|
||||
```
|
||||
|
||||
## Details of Syntax
|
||||
|
||||
### Title
|
||||
|
||||
`title`: The title is an optional field that allows to render a title at the top of the radar diagram.
|
||||
|
||||
```
|
||||
radar-beta
|
||||
title Title of the Radar Diagram
|
||||
...
|
||||
```
|
||||
|
||||
### Axis
|
||||
|
||||
`axis`: The axis keyword is used to define the axes of the radar diagram.
|
||||
|
||||
Each axis is represented by an ID and an optional label.
|
||||
|
||||
Multiple axes can be defined in a single line.
|
||||
|
||||
```
|
||||
radar-beta
|
||||
axis id1["Label1"]
|
||||
axis id2["Label2"], id3["Label3"]
|
||||
...
|
||||
```
|
||||
|
||||
### Curve
|
||||
|
||||
`curve`: The curve keyword is used to define the data points for a curve in the radar diagram.
|
||||
|
||||
Each curve is represented by an ID, an optional label, and a list of values.
|
||||
|
||||
Values can be defined by a list of numbers or a list of key-value pairs. If key-value pairs are used, the key represents the axis ID and the value represents the data point. Else, the data points are assumed to be in the order of the axes defined.
|
||||
|
||||
Multiple curves can be defined in a single line.
|
||||
|
||||
```
|
||||
radar-beta
|
||||
axis axis1, axis2, axis3
|
||||
curve id1["Label1"]{1, 2, 3}
|
||||
curve id2["Label2"]{4, 5, 6}, id3{7, 8, 9}
|
||||
curve id4{ axis3: 30, axis1: 20, axis2: 10 }
|
||||
...
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
- `showLegend`: The showLegend keyword is used to show or hide the legend in the radar diagram. The legend is shown by default.
|
||||
- `max`: The maximum value for the radar diagram. This is used to scale the radar diagram. If not provided, the maximum value is calculated from the data points.
|
||||
- `min`: The minimum value for the radar diagram. This is used to scale the radar diagram. If not provided, the minimum value is `0`.
|
||||
- `graticule`: The graticule keyword is used to define the type of graticule to be rendered in the radar diagram. The graticule can be `circle` or `polygon`. If not provided, the default graticule is `circle`.
|
||||
- `ticks`: The ticks keyword is used to define the number of ticks on the graticule. It is the number of concentric circles or polygons drawn to indicate the scale of the radar diagram. If not provided, the default number of ticks is `5`.
|
||||
|
||||
```
|
||||
radar-beta
|
||||
...
|
||||
showLegend true
|
||||
max 100
|
||||
min 0
|
||||
graticule circle
|
||||
ticks 5
|
||||
...
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Please refer to the [configuration](/config/schema-docs/config-defs-radar-diagram-config.html) guide for details.
|
||||
|
||||
| Parameter | Description | Default Value |
|
||||
| --------------- | ---------------------------------------- | ------------- |
|
||||
| width | Width of the radar diagram | `600` |
|
||||
| height | Height of the radar diagram | `600` |
|
||||
| marginTop | Top margin of the radar diagram | `50` |
|
||||
| marginBottom | Bottom margin of the radar diagram | `50` |
|
||||
| marginLeft | Left margin of the radar diagram | `50` |
|
||||
| marginRight | Right margin of the radar diagram | `50` |
|
||||
| axisScaleFactor | Scale factor for the axis | `1` |
|
||||
| axisLabelFactor | Factor to adjust the axis label position | `1.05` |
|
||||
| curveTension | Tension for the rounded curves | `0.17` |
|
||||
|
||||
## Theme Variables
|
||||
|
||||
### Global Theme Variables
|
||||
|
||||
> **Note**
|
||||
> The default values for these variables depend on the theme used. To override the default values, set the desired values in the themeVariables section of the configuration:
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> config:
|
||||
> themeVariables:
|
||||
> cScale0: "#FF0000"
|
||||
> cScale1: "#00FF00"
|
||||
>
|
||||
> ---
|
||||
|
||||
Radar charts support the color scales `cScale${i}` where `i` is a number from `0` to the theme's maximum number of colors in its color scale. Usually, the maximum number of colors is `12`.
|
||||
|
||||
| Property | Description |
|
||||
| ---------- | ------------------------------ |
|
||||
| fontSize | Font size of the title |
|
||||
| titleColor | Color of the title |
|
||||
| cScale${i} | Color scale for the i-th curve |
|
||||
|
||||
### Radar Style Options
|
||||
|
||||
> **Note**
|
||||
> Specific variables for radar resides inside the `radar` key. To set the radar style options, use this syntax.
|
||||
>
|
||||
> ---
|
||||
>
|
||||
> config:
|
||||
> themeVariables:
|
||||
> radar:
|
||||
> axisColor: "#FF0000"
|
||||
>
|
||||
> ---
|
||||
|
||||
| Property | Description | Default Value |
|
||||
| -------------------- | ---------------------------- | ------------- |
|
||||
| axisColor | Color of the axis lines | `black` |
|
||||
| axisStrokeWidth | Width of the axis lines | `1` |
|
||||
| axisLabelFontSize | Font size of the axis labels | `12px` |
|
||||
| curveOpacity | Opacity of the curves | `0.7` |
|
||||
| curveStrokeWidth | Width of the curves | `2` |
|
||||
| graticuleColor | Color of the graticule | `black` |
|
||||
| graticuleOpacity | Opacity of the graticule | `0.5` |
|
||||
| graticuleStrokeWidth | Width of the graticule | `1` |
|
||||
| legendBoxSize | Size of the legend box | `10` |
|
||||
| legendFontSize | Font size of the legend | `14px` |
|
||||
|
||||
## Example on config and theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
radar:
|
||||
axisScaleFactor: 0.25
|
||||
curveTension: 0.1
|
||||
theme: base
|
||||
themeVariables:
|
||||
cScale0: "#FF0000"
|
||||
cScale1: "#00FF00"
|
||||
cScale2: "#0000FF"
|
||||
radar:
|
||||
curveOpacity: 0
|
||||
---
|
||||
radar-beta
|
||||
axis A, B, C, D, E
|
||||
curve c1{1,2,3,4,5}
|
||||
curve c2{5,4,3,2,1}
|
||||
curve c3{3,3,3,3,3}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
radar:
|
||||
axisScaleFactor: 0.25
|
||||
curveTension: 0.1
|
||||
theme: base
|
||||
themeVariables:
|
||||
cScale0: "#FF0000"
|
||||
cScale1: "#00FF00"
|
||||
cScale2: "#0000FF"
|
||||
radar:
|
||||
curveOpacity: 0
|
||||
---
|
||||
radar-beta
|
||||
axis A, B, C, D, E
|
||||
curve c1{1,2,3,4,5}
|
||||
curve c2{5,4,3,2,1}
|
||||
curve c3{3,3,3,3,3}
|
||||
```
|
||||
|
||||
<!--- cspell:ignore Kiviat --->
|
||||
@@ -1,495 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/requirementDiagram.md](../../packages/mermaid/src/docs/syntax/requirementDiagram.md).
|
||||
|
||||
# Requirement Diagram
|
||||
|
||||
> A Requirement diagram provides a visualization for requirements and their connections, to each other and other documented elements. The modeling specs follow those defined by SysML v1.6.
|
||||
|
||||
Rendering requirements is straightforward.
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
test_entity - satisfies -> test_req
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
test_entity - satisfies -> test_req
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
There are three types of components to a requirement diagram: requirement, element, and relationship.
|
||||
|
||||
The grammar for defining each is defined below. Words denoted in angle brackets, such as `<word>`, are enumerated keywords that have options elaborated in a table. `user_defined_...` is use in any place where user input is expected.
|
||||
|
||||
An important note on user text: all input can be surrounded in quotes or not. For example, both `id: "here is an example"` and `id: here is an example` are both valid. However, users must be careful with unquoted input. The parser will fail if another keyword is detected.
|
||||
|
||||
### Requirement
|
||||
|
||||
A requirement definition contains a requirement type, name, id, text, risk, and verification method. The syntax follows:
|
||||
|
||||
```
|
||||
<type> user_defined_name {
|
||||
id: user_defined_id
|
||||
text: user_defined text
|
||||
risk: <risk>
|
||||
verifymethod: <method>
|
||||
}
|
||||
```
|
||||
|
||||
Type, risk, and method are enumerations defined in SysML.
|
||||
|
||||
| Keyword | Options |
|
||||
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| Type | requirement, functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraint |
|
||||
| Risk | Low, Medium, High |
|
||||
| VerificationMethod | Analysis, Inspection, Test, Demonstration |
|
||||
|
||||
### Element
|
||||
|
||||
An element definition contains an element name, type, and document reference. These three are all user defined. The element feature is intended to be lightweight but allow requirements to be connected to portions of other documents.
|
||||
|
||||
```
|
||||
element user_defined_name {
|
||||
type: user_defined_type
|
||||
docref: user_defined_ref
|
||||
}
|
||||
```
|
||||
|
||||
### Markdown Formatting
|
||||
|
||||
In places where user defined text is possible (like names, requirement text, element docref, etc.), you can:
|
||||
|
||||
- Surround the text in quotes: `"example text"`
|
||||
- Use markdown formatting inside quotes: `"**bold text** and *italics*"`
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement "__test_req__" {
|
||||
id: 1
|
||||
text: "*italicized text* **bold text**"
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement "__test_req__" {
|
||||
id: 1
|
||||
text: "*italicized text* **bold text**"
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
```
|
||||
|
||||
### Relationship
|
||||
|
||||
Relationships are comprised of a source node, destination node, and relationship type.
|
||||
|
||||
Each follows the definition format of
|
||||
|
||||
```
|
||||
{name of source} - <type> -> {name of destination}
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
{name of destination} <- <type> - {name of source}
|
||||
```
|
||||
|
||||
"name of source" and "name of destination" should be names of requirement or element nodes defined elsewhere.
|
||||
|
||||
A relationship type can be one of contains, copies, derives, satisfies, verifies, refines, or traces.
|
||||
|
||||
Each relationship is labeled in the diagram.
|
||||
|
||||
## Larger Example
|
||||
|
||||
This example uses all features of the diagram.
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
functionalRequirement test_req2 {
|
||||
id: 1.1
|
||||
text: the second test text.
|
||||
risk: low
|
||||
verifymethod: inspection
|
||||
}
|
||||
|
||||
performanceRequirement test_req3 {
|
||||
id: 1.2
|
||||
text: the third test text.
|
||||
risk: medium
|
||||
verifymethod: demonstration
|
||||
}
|
||||
|
||||
interfaceRequirement test_req4 {
|
||||
id: 1.2.1
|
||||
text: the fourth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
physicalRequirement test_req5 {
|
||||
id: 1.2.2
|
||||
text: the fifth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
designConstraint test_req6 {
|
||||
id: 1.2.3
|
||||
text: the sixth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
element test_entity2 {
|
||||
type: word doc
|
||||
docRef: reqs/test_entity
|
||||
}
|
||||
|
||||
element test_entity3 {
|
||||
type: "test suite"
|
||||
docRef: github.com/all_the_tests
|
||||
}
|
||||
|
||||
|
||||
test_entity - satisfies -> test_req2
|
||||
test_req - traces -> test_req2
|
||||
test_req - contains -> test_req3
|
||||
test_req3 - contains -> test_req4
|
||||
test_req4 - derives -> test_req5
|
||||
test_req5 - refines -> test_req6
|
||||
test_entity3 - verifies -> test_req5
|
||||
test_req <- copies - test_entity2
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
functionalRequirement test_req2 {
|
||||
id: 1.1
|
||||
text: the second test text.
|
||||
risk: low
|
||||
verifymethod: inspection
|
||||
}
|
||||
|
||||
performanceRequirement test_req3 {
|
||||
id: 1.2
|
||||
text: the third test text.
|
||||
risk: medium
|
||||
verifymethod: demonstration
|
||||
}
|
||||
|
||||
interfaceRequirement test_req4 {
|
||||
id: 1.2.1
|
||||
text: the fourth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
physicalRequirement test_req5 {
|
||||
id: 1.2.2
|
||||
text: the fifth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
designConstraint test_req6 {
|
||||
id: 1.2.3
|
||||
text: the sixth test text.
|
||||
risk: medium
|
||||
verifymethod: analysis
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
element test_entity2 {
|
||||
type: word doc
|
||||
docRef: reqs/test_entity
|
||||
}
|
||||
|
||||
element test_entity3 {
|
||||
type: "test suite"
|
||||
docRef: github.com/all_the_tests
|
||||
}
|
||||
|
||||
|
||||
test_entity - satisfies -> test_req2
|
||||
test_req - traces -> test_req2
|
||||
test_req - contains -> test_req3
|
||||
test_req3 - contains -> test_req4
|
||||
test_req4 - derives -> test_req5
|
||||
test_req5 - refines -> test_req6
|
||||
test_entity3 - verifies -> test_req5
|
||||
test_req <- copies - test_entity2
|
||||
```
|
||||
|
||||
## Direction
|
||||
|
||||
The diagram can be rendered in different directions using the `direction` statement. Valid values are:
|
||||
|
||||
- `TB` - Top to Bottom (default)
|
||||
- `BT` - Bottom to Top
|
||||
- `LR` - Left to Right
|
||||
- `RL` - Right to Left
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
direction LR
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
test_entity - satisfies -> test_req
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
direction LR
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: the test text.
|
||||
risk: high
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
test_entity - satisfies -> test_req
|
||||
```
|
||||
|
||||
## Styling
|
||||
|
||||
Requirements and elements can be styled using direct styling or classes. As a rule of thumb, when applying styles or classes, it accepts a list of requirement or element names and a list of class names allowing multiple assignments at a time (The only exception is the shorthand syntax `:::` which can assign multiple classes but only to one requirement or element at a time).
|
||||
|
||||
### Direct Styling
|
||||
|
||||
Use the `style` keyword to apply CSS styles directly:
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: styling example
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
style test_req fill:#ffa,stroke:#000, color: green
|
||||
style test_entity fill:#f9f,stroke:#333, color: blue
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: styling example
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
style test_req fill:#ffa,stroke:#000, color: green
|
||||
style test_entity fill:#f9f,stroke:#333, color: blue
|
||||
```
|
||||
|
||||
### Class Definitions
|
||||
|
||||
Define reusable styles using `classDef`:
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: "class styling example"
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:4px
|
||||
classDef test fill:#ffa,stroke:#000
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req {
|
||||
id: 1
|
||||
text: "class styling example"
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:4px
|
||||
classDef test fill:#ffa,stroke:#000
|
||||
```
|
||||
|
||||
### Default class
|
||||
|
||||
If a class is named default it will be applied to all nodes. Specific styles and classes should be defined afterwards to override the applied default styling.
|
||||
|
||||
```
|
||||
classDef default fill:#f9f,stroke:#333,stroke-width:4px;
|
||||
```
|
||||
|
||||
### Applying Classes
|
||||
|
||||
Classes can be applied in two ways:
|
||||
|
||||
1. Using the `class` keyword:
|
||||
|
||||
```
|
||||
class test_req,test_entity important
|
||||
```
|
||||
|
||||
2. Using the shorthand syntax with `:::` either during the definition or afterwards:
|
||||
|
||||
```
|
||||
requirement test_req:::important {
|
||||
id: 1
|
||||
text: class styling example
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
```
|
||||
|
||||
```
|
||||
element test_elem {
|
||||
}
|
||||
|
||||
test_elem:::myClass
|
||||
```
|
||||
|
||||
### Combined Example
|
||||
|
||||
```mermaid-example
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req:::important {
|
||||
id: 1
|
||||
text: "class styling example"
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
classDef important font-weight:bold
|
||||
|
||||
class test_entity important
|
||||
style test_entity fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
```mermaid
|
||||
requirementDiagram
|
||||
|
||||
requirement test_req:::important {
|
||||
id: 1
|
||||
text: "class styling example"
|
||||
risk: low
|
||||
verifymethod: test
|
||||
}
|
||||
|
||||
element test_entity {
|
||||
type: simulation
|
||||
}
|
||||
|
||||
classDef important font-weight:bold
|
||||
|
||||
class test_entity important
|
||||
style test_entity fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
<!--- cspell:ignore reqs --->
|
||||
@@ -1,305 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/sankey.md](../../packages/mermaid/src/docs/syntax/sankey.md).
|
||||
|
||||
# Sankey diagram (v10.3.0+)
|
||||
|
||||
> A sankey diagram is a visualization used to depict a flow from one set of values to another.
|
||||
|
||||
> **Warning**
|
||||
> This is an experimental diagram. Its syntax are very close to plain CSV, but it is to be extended in the nearest future.
|
||||
|
||||
The things being connected are called nodes and the connections are called links.
|
||||
|
||||
## Example
|
||||
|
||||
This example taken from [observable](https://observablehq.com/@d3/sankey/2?collection=@d3/d3-sankey). It may be rendered a little bit differently, though, in terms of size and colors.
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
sankey:
|
||||
showValues: false
|
||||
---
|
||||
sankey
|
||||
|
||||
Agricultural 'waste',Bio-conversion,124.729
|
||||
Bio-conversion,Liquid,0.597
|
||||
Bio-conversion,Losses,26.862
|
||||
Bio-conversion,Solid,280.322
|
||||
Bio-conversion,Gas,81.144
|
||||
Biofuel imports,Liquid,35
|
||||
Biomass imports,Solid,35
|
||||
Coal imports,Coal,11.606
|
||||
Coal reserves,Coal,63.965
|
||||
Coal,Solid,75.571
|
||||
District heating,Industry,10.639
|
||||
District heating,Heating and cooling - commercial,22.505
|
||||
District heating,Heating and cooling - homes,46.184
|
||||
Electricity grid,Over generation / exports,104.453
|
||||
Electricity grid,Heating and cooling - homes,113.726
|
||||
Electricity grid,H2 conversion,27.14
|
||||
Electricity grid,Industry,342.165
|
||||
Electricity grid,Road transport,37.797
|
||||
Electricity grid,Agriculture,4.412
|
||||
Electricity grid,Heating and cooling - commercial,40.858
|
||||
Electricity grid,Losses,56.691
|
||||
Electricity grid,Rail transport,7.863
|
||||
Electricity grid,Lighting & appliances - commercial,90.008
|
||||
Electricity grid,Lighting & appliances - homes,93.494
|
||||
Gas imports,Ngas,40.719
|
||||
Gas reserves,Ngas,82.233
|
||||
Gas,Heating and cooling - commercial,0.129
|
||||
Gas,Losses,1.401
|
||||
Gas,Thermal generation,151.891
|
||||
Gas,Agriculture,2.096
|
||||
Gas,Industry,48.58
|
||||
Geothermal,Electricity grid,7.013
|
||||
H2 conversion,H2,20.897
|
||||
H2 conversion,Losses,6.242
|
||||
H2,Road transport,20.897
|
||||
Hydro,Electricity grid,6.995
|
||||
Liquid,Industry,121.066
|
||||
Liquid,International shipping,128.69
|
||||
Liquid,Road transport,135.835
|
||||
Liquid,Domestic aviation,14.458
|
||||
Liquid,International aviation,206.267
|
||||
Liquid,Agriculture,3.64
|
||||
Liquid,National navigation,33.218
|
||||
Liquid,Rail transport,4.413
|
||||
Marine algae,Bio-conversion,4.375
|
||||
Ngas,Gas,122.952
|
||||
Nuclear,Thermal generation,839.978
|
||||
Oil imports,Oil,504.287
|
||||
Oil reserves,Oil,107.703
|
||||
Oil,Liquid,611.99
|
||||
Other waste,Solid,56.587
|
||||
Other waste,Bio-conversion,77.81
|
||||
Pumped heat,Heating and cooling - homes,193.026
|
||||
Pumped heat,Heating and cooling - commercial,70.672
|
||||
Solar PV,Electricity grid,59.901
|
||||
Solar Thermal,Heating and cooling - homes,19.263
|
||||
Solar,Solar Thermal,19.263
|
||||
Solar,Solar PV,59.901
|
||||
Solid,Agriculture,0.882
|
||||
Solid,Thermal generation,400.12
|
||||
Solid,Industry,46.477
|
||||
Thermal generation,Electricity grid,525.531
|
||||
Thermal generation,Losses,787.129
|
||||
Thermal generation,District heating,79.329
|
||||
Tidal,Electricity grid,9.452
|
||||
UK land based bioenergy,Bio-conversion,182.01
|
||||
Wave,Electricity grid,19.013
|
||||
Wind,Electricity grid,289.366
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
sankey:
|
||||
showValues: false
|
||||
---
|
||||
sankey
|
||||
|
||||
Agricultural 'waste',Bio-conversion,124.729
|
||||
Bio-conversion,Liquid,0.597
|
||||
Bio-conversion,Losses,26.862
|
||||
Bio-conversion,Solid,280.322
|
||||
Bio-conversion,Gas,81.144
|
||||
Biofuel imports,Liquid,35
|
||||
Biomass imports,Solid,35
|
||||
Coal imports,Coal,11.606
|
||||
Coal reserves,Coal,63.965
|
||||
Coal,Solid,75.571
|
||||
District heating,Industry,10.639
|
||||
District heating,Heating and cooling - commercial,22.505
|
||||
District heating,Heating and cooling - homes,46.184
|
||||
Electricity grid,Over generation / exports,104.453
|
||||
Electricity grid,Heating and cooling - homes,113.726
|
||||
Electricity grid,H2 conversion,27.14
|
||||
Electricity grid,Industry,342.165
|
||||
Electricity grid,Road transport,37.797
|
||||
Electricity grid,Agriculture,4.412
|
||||
Electricity grid,Heating and cooling - commercial,40.858
|
||||
Electricity grid,Losses,56.691
|
||||
Electricity grid,Rail transport,7.863
|
||||
Electricity grid,Lighting & appliances - commercial,90.008
|
||||
Electricity grid,Lighting & appliances - homes,93.494
|
||||
Gas imports,Ngas,40.719
|
||||
Gas reserves,Ngas,82.233
|
||||
Gas,Heating and cooling - commercial,0.129
|
||||
Gas,Losses,1.401
|
||||
Gas,Thermal generation,151.891
|
||||
Gas,Agriculture,2.096
|
||||
Gas,Industry,48.58
|
||||
Geothermal,Electricity grid,7.013
|
||||
H2 conversion,H2,20.897
|
||||
H2 conversion,Losses,6.242
|
||||
H2,Road transport,20.897
|
||||
Hydro,Electricity grid,6.995
|
||||
Liquid,Industry,121.066
|
||||
Liquid,International shipping,128.69
|
||||
Liquid,Road transport,135.835
|
||||
Liquid,Domestic aviation,14.458
|
||||
Liquid,International aviation,206.267
|
||||
Liquid,Agriculture,3.64
|
||||
Liquid,National navigation,33.218
|
||||
Liquid,Rail transport,4.413
|
||||
Marine algae,Bio-conversion,4.375
|
||||
Ngas,Gas,122.952
|
||||
Nuclear,Thermal generation,839.978
|
||||
Oil imports,Oil,504.287
|
||||
Oil reserves,Oil,107.703
|
||||
Oil,Liquid,611.99
|
||||
Other waste,Solid,56.587
|
||||
Other waste,Bio-conversion,77.81
|
||||
Pumped heat,Heating and cooling - homes,193.026
|
||||
Pumped heat,Heating and cooling - commercial,70.672
|
||||
Solar PV,Electricity grid,59.901
|
||||
Solar Thermal,Heating and cooling - homes,19.263
|
||||
Solar,Solar Thermal,19.263
|
||||
Solar,Solar PV,59.901
|
||||
Solid,Agriculture,0.882
|
||||
Solid,Thermal generation,400.12
|
||||
Solid,Industry,46.477
|
||||
Thermal generation,Electricity grid,525.531
|
||||
Thermal generation,Losses,787.129
|
||||
Thermal generation,District heating,79.329
|
||||
Tidal,Electricity grid,9.452
|
||||
UK land based bioenergy,Bio-conversion,182.01
|
||||
Wave,Electricity grid,19.013
|
||||
Wind,Electricity grid,289.366
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
The idea behind syntax is that a user types `sankey` keyword first, then pastes raw CSV below and get the result.
|
||||
|
||||
It implements CSV standard as [described here](https://www.ietf.org/rfc/rfc4180.txt) with subtle **differences**:
|
||||
|
||||
- CSV must contain **3 columns only**
|
||||
- It is **allowed** to have **empty lines** without comma separators for visual purposes
|
||||
|
||||
### Basic
|
||||
|
||||
It is implied that 3 columns inside CSV should represent `source`, `target` and `value` accordingly:
|
||||
|
||||
```mermaid-example
|
||||
sankey
|
||||
|
||||
%% source,target,value
|
||||
Electricity grid,Over generation / exports,104.453
|
||||
Electricity grid,Heating and cooling - homes,113.726
|
||||
Electricity grid,H2 conversion,27.14
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sankey
|
||||
|
||||
%% source,target,value
|
||||
Electricity grid,Over generation / exports,104.453
|
||||
Electricity grid,Heating and cooling - homes,113.726
|
||||
Electricity grid,H2 conversion,27.14
|
||||
```
|
||||
|
||||
### Empty Lines
|
||||
|
||||
CSV does not support empty lines without comma delimiters by default. But you can add them if needed:
|
||||
|
||||
```mermaid-example
|
||||
sankey
|
||||
|
||||
Bio-conversion,Losses,26.862
|
||||
|
||||
Bio-conversion,Solid,280.322
|
||||
|
||||
Bio-conversion,Gas,81.144
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sankey
|
||||
|
||||
Bio-conversion,Losses,26.862
|
||||
|
||||
Bio-conversion,Solid,280.322
|
||||
|
||||
Bio-conversion,Gas,81.144
|
||||
```
|
||||
|
||||
### Commas
|
||||
|
||||
If you need to have a comma, wrap it in double quotes:
|
||||
|
||||
```mermaid-example
|
||||
sankey
|
||||
|
||||
Pumped heat,"Heating and cooling, homes",193.026
|
||||
Pumped heat,"Heating and cooling, commercial",70.672
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sankey
|
||||
|
||||
Pumped heat,"Heating and cooling, homes",193.026
|
||||
Pumped heat,"Heating and cooling, commercial",70.672
|
||||
```
|
||||
|
||||
### Double Quotes
|
||||
|
||||
If you need to have double quote, put a pair of them inside quoted string:
|
||||
|
||||
```mermaid-example
|
||||
sankey
|
||||
|
||||
Pumped heat,"Heating and cooling, ""homes""",193.026
|
||||
Pumped heat,"Heating and cooling, ""commercial""",70.672
|
||||
```
|
||||
|
||||
```mermaid
|
||||
sankey
|
||||
|
||||
Pumped heat,"Heating and cooling, ""homes""",193.026
|
||||
Pumped heat,"Heating and cooling, ""commercial""",70.672
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
You can customize link colors, node alignments and diagram dimensions.
|
||||
|
||||
```html
|
||||
<script>
|
||||
const config = {
|
||||
startOnLoad: true,
|
||||
securityLevel: 'loose',
|
||||
sankey: {
|
||||
width: 800,
|
||||
height: 400,
|
||||
linkColor: 'source',
|
||||
nodeAlignment: 'left',
|
||||
},
|
||||
};
|
||||
mermaid.initialize(config);
|
||||
</script>
|
||||
```
|
||||
|
||||
### Links Coloring
|
||||
|
||||
You can adjust links' color by setting `linkColor` to one of those:
|
||||
|
||||
- `source` - link will be of a source node color
|
||||
- `target` - link will be of a target node color
|
||||
- `gradient` - link color will be smoothly transient between source and target node colors
|
||||
- hex code of color, like `#a1a1a1`
|
||||
|
||||
### Node Alignment
|
||||
|
||||
Graph layout can be changed by setting `nodeAlignment` to:
|
||||
|
||||
- `justify`
|
||||
- `center`
|
||||
- `left`
|
||||
- `right`
|
||||
|
||||
<!--- cspell:ignore Ngas bioenergy biofuel --->
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,672 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/stateDiagram.md](../../packages/mermaid/src/docs/syntax/stateDiagram.md).
|
||||
|
||||
# State diagrams
|
||||
|
||||
> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
|
||||
> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
|
||||
> case, while at other times this is a reasonable abstraction." Wikipedia
|
||||
|
||||
Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
|
||||
it easier for users to share diagrams between mermaid and plantUml.
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
title: Simple sample
|
||||
---
|
||||
stateDiagram-v2
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
title: Simple sample
|
||||
---
|
||||
stateDiagram-v2
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
Older renderer:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
|
||||
a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
|
||||
**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
|
||||
the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
|
||||
|
||||
## States
|
||||
|
||||
A state can be declared in multiple ways. The simplest way is to define a state with just an id:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
stateId
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
stateId
|
||||
```
|
||||
|
||||
Another way is by using the state keyword with a description as per below:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
state "This is a state description" as s2
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state "This is a state description" as s2
|
||||
```
|
||||
|
||||
Another way to define a state with a description is to define the state id followed by a colon and the description:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
s2 : This is a state description
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
s2 : This is a state description
|
||||
```
|
||||
|
||||
## Transitions
|
||||
|
||||
Transitions are path/edges when one state passes into another. This is represented using text arrow, "-->".
|
||||
|
||||
When you define a transition between two states and the states are not already defined, the undefined states are defined
|
||||
with the id from the transition. You can later add descriptions to states defined this way.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
s1 --> s2
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
s1 --> s2
|
||||
```
|
||||
|
||||
It is possible to add text to a transition to describe what it represents:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
s1 --> s2: A transition
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
s1 --> s2: A transition
|
||||
```
|
||||
|
||||
## Start and End
|
||||
|
||||
There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and
|
||||
the direction of the transition to it defines it either as a start or a stop state.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> s1
|
||||
s1 --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> s1
|
||||
s1 --> [*]
|
||||
```
|
||||
|
||||
## Composite states
|
||||
|
||||
In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
|
||||
have several internal states. These are called composite states in this terminology.
|
||||
|
||||
In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
|
||||
state between {}. You can name a composite state on a separate line just like a simple state. See the example below:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
state First {
|
||||
[*] --> second
|
||||
second --> [*]
|
||||
}
|
||||
|
||||
[*] --> NamedComposite
|
||||
NamedComposite: Another Composite
|
||||
state NamedComposite {
|
||||
[*] --> namedSimple
|
||||
namedSimple --> [*]
|
||||
namedSimple: Another simple
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
state First {
|
||||
[*] --> second
|
||||
second --> [*]
|
||||
}
|
||||
|
||||
[*] --> NamedComposite
|
||||
NamedComposite: Another Composite
|
||||
state NamedComposite {
|
||||
[*] --> namedSimple
|
||||
namedSimple --> [*]
|
||||
namedSimple: Another simple
|
||||
}
|
||||
```
|
||||
|
||||
You can do this in several layers:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
|
||||
state First {
|
||||
[*] --> Second
|
||||
|
||||
state Second {
|
||||
[*] --> second
|
||||
second --> Third
|
||||
|
||||
state Third {
|
||||
[*] --> third
|
||||
third --> [*]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
|
||||
state First {
|
||||
[*] --> Second
|
||||
|
||||
state Second {
|
||||
[*] --> second
|
||||
second --> Third
|
||||
|
||||
state Third {
|
||||
[*] --> third
|
||||
third --> [*]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also define transitions also between composite states:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
First --> Second
|
||||
First --> Third
|
||||
|
||||
state First {
|
||||
[*] --> fir
|
||||
fir --> [*]
|
||||
}
|
||||
state Second {
|
||||
[*] --> sec
|
||||
sec --> [*]
|
||||
}
|
||||
state Third {
|
||||
[*] --> thi
|
||||
thi --> [*]
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> First
|
||||
First --> Second
|
||||
First --> Third
|
||||
|
||||
state First {
|
||||
[*] --> fir
|
||||
fir --> [*]
|
||||
}
|
||||
state Second {
|
||||
[*] --> sec
|
||||
sec --> [*]
|
||||
}
|
||||
state Third {
|
||||
[*] --> thi
|
||||
thi --> [*]
|
||||
}
|
||||
```
|
||||
|
||||
_You cannot define transitions between internal states belonging to different composite states_
|
||||
|
||||
## Choice
|
||||
|
||||
Sometimes you need to model a choice between two or more paths, you can do so using <\<choice>>.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
state if_state <<choice>>
|
||||
[*] --> IsPositive
|
||||
IsPositive --> if_state
|
||||
if_state --> False: if n < 0
|
||||
if_state --> True : if n >= 0
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state if_state <<choice>>
|
||||
[*] --> IsPositive
|
||||
IsPositive --> if_state
|
||||
if_state --> False: if n < 0
|
||||
if_state --> True : if n >= 0
|
||||
```
|
||||
|
||||
## Forks
|
||||
|
||||
It is possible to specify a fork in the diagram using <\<fork>> <\<join>>.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
state fork_state <<fork>>
|
||||
[*] --> fork_state
|
||||
fork_state --> State2
|
||||
fork_state --> State3
|
||||
|
||||
state join_state <<join>>
|
||||
State2 --> join_state
|
||||
State3 --> join_state
|
||||
join_state --> State4
|
||||
State4 --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
state fork_state <<fork>>
|
||||
[*] --> fork_state
|
||||
fork_state --> State2
|
||||
fork_state --> State3
|
||||
|
||||
state join_state <<join>>
|
||||
State2 --> join_state
|
||||
State3 --> join_state
|
||||
join_state --> State4
|
||||
State4 --> [*]
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
|
||||
|
||||
Here you can choose to put the note to the _right of_ or to the _left of_ a node.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
State1: The state with a note
|
||||
note right of State1
|
||||
Important information! You can write
|
||||
notes.
|
||||
end note
|
||||
State1 --> State2
|
||||
note left of State2 : This is the note to the left.
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
State1: The state with a note
|
||||
note right of State1
|
||||
Important information! You can write
|
||||
notes.
|
||||
end note
|
||||
State1 --> State2
|
||||
note left of State2 : This is the note to the left.
|
||||
```
|
||||
|
||||
## Concurrency
|
||||
|
||||
As in plantUml you can specify concurrency using the -- symbol.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
|
||||
state Active {
|
||||
[*] --> NumLockOff
|
||||
NumLockOff --> NumLockOn : EvNumLockPressed
|
||||
NumLockOn --> NumLockOff : EvNumLockPressed
|
||||
--
|
||||
[*] --> CapsLockOff
|
||||
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
||||
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
||||
--
|
||||
[*] --> ScrollLockOff
|
||||
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
||||
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Active
|
||||
|
||||
state Active {
|
||||
[*] --> NumLockOff
|
||||
NumLockOff --> NumLockOn : EvNumLockPressed
|
||||
NumLockOn --> NumLockOff : EvNumLockPressed
|
||||
--
|
||||
[*] --> CapsLockOff
|
||||
CapsLockOff --> CapsLockOn : EvCapsLockPressed
|
||||
CapsLockOn --> CapsLockOff : EvCapsLockPressed
|
||||
--
|
||||
[*] --> ScrollLockOff
|
||||
ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
|
||||
ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
|
||||
}
|
||||
```
|
||||
|
||||
## Setting the direction of the diagram
|
||||
|
||||
With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
|
||||
example.
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
direction LR
|
||||
[*] --> A
|
||||
A --> B
|
||||
B --> C
|
||||
state B {
|
||||
direction LR
|
||||
a --> b
|
||||
}
|
||||
B --> D
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
direction LR
|
||||
[*] --> A
|
||||
A --> B
|
||||
B --> C
|
||||
state B {
|
||||
direction LR
|
||||
a --> b
|
||||
}
|
||||
B --> D
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
|
||||
own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
|
||||
newline will be treated as a comment, including any diagram syntax
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram-v2
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
%% this is a comment
|
||||
Still --> Moving
|
||||
Moving --> Still %% another comment
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Still
|
||||
Still --> [*]
|
||||
%% this is a comment
|
||||
Still --> Moving
|
||||
Moving --> Still %% another comment
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
```
|
||||
|
||||
## Styling with classDefs
|
||||
|
||||
As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
|
||||
state or states in the diagram.
|
||||
|
||||
**These are the current limitations with state diagram classDefs:**
|
||||
|
||||
1. Cannot be applied to start or end states
|
||||
2. Cannot be applied to or within composite states
|
||||
|
||||
_These are in development and will be available in a future version._
|
||||
|
||||
You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
|
||||
like a _CSS class_)
|
||||
followed by _a name for the style,_
|
||||
and then one or more _property-value pairs_. Each _property-value pair_ is
|
||||
a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
|
||||
|
||||
Here is an example of a classDef with just one property-value pair:
|
||||
|
||||
```txt
|
||||
classDef movement font-style:italic;
|
||||
```
|
||||
|
||||
where
|
||||
|
||||
- the _name_ of the style is `movement`
|
||||
- the only _property_ is `font-style` and its _value_ is `italic`
|
||||
|
||||
If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
|
||||
|
||||
Here is an example with three property-value pairs:
|
||||
|
||||
```txt
|
||||
classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
|
||||
```
|
||||
|
||||
where
|
||||
|
||||
- the _name_ of the style is `badBadEvent`
|
||||
- the first _property_ is `fill` and its _value_ is `#f00`
|
||||
- the second _property_ is `color` and its _value_ is `white`
|
||||
- the third _property_ is `font-weight` and its _value_ is `bold`
|
||||
- the fourth _property_ is `stroke-width` and its _value_ is `2px`
|
||||
- the fifth _property_ is `stroke` and its _value_ is `yellow`
|
||||
|
||||
### Apply classDef styles to states
|
||||
|
||||
There are two ways to apply a `classDef` style to a state:
|
||||
|
||||
1. use the `class` keyword to apply a classDef style to one or more states in a single statement, or
|
||||
2. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
|
||||
to/from another state)
|
||||
|
||||
#### 1. `class` statement
|
||||
|
||||
A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
|
||||
|
||||
```txt
|
||||
class [one or more state names, separated by commas] [name of a style defined with classDef]
|
||||
```
|
||||
|
||||
Here is an example applying the `badBadEvent` style to a state named `Crash`:
|
||||
|
||||
```txt
|
||||
class Crash badBadEvent
|
||||
```
|
||||
|
||||
Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
|
||||
|
||||
```txt
|
||||
class Moving, Crash movement
|
||||
```
|
||||
|
||||
Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
|
||||
and `badBadEvent`
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
direction TB
|
||||
|
||||
accTitle: This is the accessible title
|
||||
accDescr: This is an accessible description
|
||||
|
||||
classDef notMoving fill:white
|
||||
classDef movement font-style:italic
|
||||
classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
|
||||
|
||||
[*]--> Still
|
||||
Still --> [*]
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
|
||||
class Still notMoving
|
||||
class Moving, Crash movement
|
||||
class Crash badBadEvent
|
||||
class end badBadEvent
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
direction TB
|
||||
|
||||
accTitle: This is the accessible title
|
||||
accDescr: This is an accessible description
|
||||
|
||||
classDef notMoving fill:white
|
||||
classDef movement font-style:italic
|
||||
classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
|
||||
|
||||
[*]--> Still
|
||||
Still --> [*]
|
||||
Still --> Moving
|
||||
Moving --> Still
|
||||
Moving --> Crash
|
||||
Crash --> [*]
|
||||
|
||||
class Still notMoving
|
||||
class Moving, Crash movement
|
||||
class Crash badBadEvent
|
||||
class end badBadEvent
|
||||
```
|
||||
|
||||
#### 2. `:::` operator to apply a style to a state
|
||||
|
||||
You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
|
||||
|
||||
```txt
|
||||
[state]:::[style name]
|
||||
```
|
||||
|
||||
You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
direction TB
|
||||
|
||||
accTitle: This is the accessible title
|
||||
accDescr: This is an accessible description
|
||||
|
||||
classDef notMoving fill:white
|
||||
classDef movement font-style:italic;
|
||||
classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
|
||||
|
||||
[*] --> Still:::notMoving
|
||||
Still --> [*]
|
||||
Still --> Moving:::movement
|
||||
Moving --> Still
|
||||
Moving --> Crash:::movement
|
||||
Crash:::badBadEvent --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
direction TB
|
||||
|
||||
accTitle: This is the accessible title
|
||||
accDescr: This is an accessible description
|
||||
|
||||
classDef notMoving fill:white
|
||||
classDef movement font-style:italic;
|
||||
classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
|
||||
|
||||
[*] --> Still:::notMoving
|
||||
Still --> [*]
|
||||
Still --> Moving:::movement
|
||||
Moving --> Still
|
||||
Moving --> Crash:::movement
|
||||
Crash:::badBadEvent --> [*]
|
||||
```
|
||||
|
||||
## Spaces in state names
|
||||
|
||||
Spaces can be added to a state by first defining the state with an id and then referencing the id later.
|
||||
|
||||
In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
|
||||
After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
|
||||
and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).
|
||||
(**yswsii** has been styled so that it is different from the other states.)
|
||||
|
||||
```mermaid-example
|
||||
stateDiagram
|
||||
classDef yourState font-style:italic,font-weight:bold,fill:white
|
||||
|
||||
yswsii: Your state with spaces in it
|
||||
[*] --> yswsii:::yourState
|
||||
[*] --> SomeOtherState
|
||||
SomeOtherState --> YetAnotherState
|
||||
yswsii --> YetAnotherState
|
||||
YetAnotherState --> [*]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
stateDiagram
|
||||
classDef yourState font-style:italic,font-weight:bold,fill:white
|
||||
|
||||
yswsii: Your state with spaces in it
|
||||
[*] --> yswsii:::yourState
|
||||
[*] --> SomeOtherState
|
||||
SomeOtherState --> YetAnotherState
|
||||
yswsii --> YetAnotherState
|
||||
YetAnotherState --> [*]
|
||||
```
|
||||
|
||||
<!--- cspell:ignore yswsii --->
|
||||
@@ -1,540 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/timeline.md](../../packages/mermaid/src/docs/syntax/timeline.md).
|
||||
|
||||
# Timeline Diagram
|
||||
|
||||
> Timeline: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
|
||||
|
||||
"A timeline is a type of diagram used to illustrate a chronology of events, dates, or periods of time. It is usually presented graphically to indicate the passing of time, and it is usually organized chronologically. A basic timeline presents a list of events in chronological order, usually using dates as markers. A timeline can also be used to show the relationship between events, such as the relationship between the events of a person's life" [(Wikipedia)](https://en.wikipedia.org/wiki/Timeline).
|
||||
|
||||
### An example of a timeline
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook
|
||||
: Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook
|
||||
: Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
The syntax for creating Timeline diagram is simple. You always start with the `timeline` keyword to let mermaid know that you want to create a timeline diagram.
|
||||
|
||||
After that there is a possibility to add a title to the timeline. This is done by adding a line with the keyword `title` followed by the title text.
|
||||
|
||||
Then you add the timeline data, where you always start with a time period, followed by a colon and then the text for the event. Optionally you can add a second colon and then the text for the event. So, you can have one or more events per time period.
|
||||
|
||||
```json
|
||||
{time period} : {event}
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```json
|
||||
{time period} : {event} : {event}
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```json
|
||||
{time period} : {event}
|
||||
: {event}
|
||||
: {event}
|
||||
```
|
||||
|
||||
**NOTE**: Both time period and event are simple text, and not limited to numbers.
|
||||
|
||||
Let us look at the syntax for the example above.
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
```
|
||||
|
||||
In this way we can use a text outline to generate a timeline diagram.
|
||||
The sequence of time period and events is important, as it will be used to draw the timeline. The first time period will be placed at the left side of the timeline, and the last time period will be placed at the right side of the timeline.
|
||||
|
||||
Similarly, the first event will be placed at the top for that specific time period, and the last event will be placed at the bottom.
|
||||
|
||||
## Grouping of time periods in sections/ages
|
||||
|
||||
You can group time periods in sections/ages. This is done by adding a line with the keyword `section` followed by the section name.
|
||||
|
||||
All subsequent time periods will be placed in this section until a new section is defined.
|
||||
|
||||
If no section is defined, all time periods will be placed in the default section.
|
||||
|
||||
Let us look at an example, where we have grouped the time periods in sections.
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title Timeline of Industrial Revolution
|
||||
section 17th-20th century
|
||||
Industry 1.0 : Machinery, Water power, Steam <br>power
|
||||
Industry 2.0 : Electricity, Internal combustion engine, Mass production
|
||||
Industry 3.0 : Electronics, Computers, Automation
|
||||
section 21st century
|
||||
Industry 4.0 : Internet, Robotics, Internet of Things
|
||||
Industry 5.0 : Artificial intelligence, Big data, 3D printing
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title Timeline of Industrial Revolution
|
||||
section 17th-20th century
|
||||
Industry 1.0 : Machinery, Water power, Steam <br>power
|
||||
Industry 2.0 : Electricity, Internal combustion engine, Mass production
|
||||
Industry 3.0 : Electronics, Computers, Automation
|
||||
section 21st century
|
||||
Industry 4.0 : Internet, Robotics, Internet of Things
|
||||
Industry 5.0 : Artificial intelligence, Big data, 3D printing
|
||||
```
|
||||
|
||||
As you can see, the time periods are placed in the sections, and the sections are placed in the order they are defined.
|
||||
|
||||
All time periods and events under a given section follow a similar color scheme. This is done to make it easier to see the relationship between time periods and events.
|
||||
|
||||
## Wrapping of text for long time-periods or events
|
||||
|
||||
By default, the text for time-periods and events will be wrapped if it is too long. This is done to avoid that the text is drawn outside the diagram.
|
||||
|
||||
You can also use `<br>` to force a line break.
|
||||
|
||||
Let us look at another example, where we have a long time period, and a long event.
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title England's History Timeline
|
||||
section Stone Age
|
||||
7600 BC : Britain's oldest known house was built in Orkney, Scotland
|
||||
6000 BC : Sea levels rise and Britain becomes an island.<br> The people who live here are hunter-gatherers.
|
||||
section Bronze Age
|
||||
2300 BC : People arrive from Europe and settle in Britain. <br>They bring farming and metalworking.
|
||||
: New styles of pottery and ways of burying the dead appear.
|
||||
2200 BC : The last major building works are completed at Stonehenge.<br> People now bury their dead in stone circles.
|
||||
: The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title England's History Timeline
|
||||
section Stone Age
|
||||
7600 BC : Britain's oldest known house was built in Orkney, Scotland
|
||||
6000 BC : Sea levels rise and Britain becomes an island.<br> The people who live here are hunter-gatherers.
|
||||
section Bronze Age
|
||||
2300 BC : People arrive from Europe and settle in Britain. <br>They bring farming and metalworking.
|
||||
: New styles of pottery and ways of burying the dead appear.
|
||||
2200 BC : The last major building works are completed at Stonehenge.<br> People now bury their dead in stone circles.
|
||||
: The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
|
||||
|
||||
```
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title MermaidChart 2023 Timeline
|
||||
section 2023 Q1 <br> Release Personal Tier
|
||||
Bullet 1 : sub-point 1a : sub-point 1b
|
||||
: sub-point 1c
|
||||
Bullet 2 : sub-point 2a : sub-point 2b
|
||||
section 2023 Q2 <br> Release XYZ Tier
|
||||
Bullet 3 : sub-point <br> 3a : sub-point 3b
|
||||
: sub-point 3c
|
||||
Bullet 4 : sub-point 4a : sub-point 4b
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title MermaidChart 2023 Timeline
|
||||
section 2023 Q1 <br> Release Personal Tier
|
||||
Bullet 1 : sub-point 1a : sub-point 1b
|
||||
: sub-point 1c
|
||||
Bullet 2 : sub-point 2a : sub-point 2b
|
||||
section 2023 Q2 <br> Release XYZ Tier
|
||||
Bullet 3 : sub-point <br> 3a : sub-point 3b
|
||||
: sub-point 3c
|
||||
Bullet 4 : sub-point 4a : sub-point 4b
|
||||
```
|
||||
|
||||
## Styling of time periods and events
|
||||
|
||||
As explained earlier, each section has a color scheme, and each time period and event under a section follow the similar color scheme.
|
||||
|
||||
However, if there is no section defined, then we have two possibilities:
|
||||
|
||||
1. Style time periods individually, i.e. each time period(and its corresponding events) will have its own color scheme. This is the DEFAULT behavior.
|
||||
|
||||
```mermaid-example
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
|
||||
```
|
||||
|
||||
**NOTE**: that there are no sections defined, and each time period and its corresponding events will have its own color scheme.
|
||||
|
||||
2. Disable the multiColor option using the `disableMultiColor` option. This will make all time periods and events follow the same color scheme.
|
||||
|
||||
You will need to add this option either via mermaid.initialize function or directives.
|
||||
|
||||
```javascript
|
||||
mermaid.initialize({
|
||||
theme: 'base',
|
||||
startOnLoad: true,
|
||||
logLevel: 0,
|
||||
timeline: {
|
||||
disableMulticolor: false,
|
||||
},
|
||||
...
|
||||
...
|
||||
```
|
||||
|
||||
let us look at same example, where we have disabled the multiColor option.
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'base'
|
||||
timeline:
|
||||
disableMulticolor: true
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'base'
|
||||
timeline:
|
||||
disableMulticolor: true
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
|
||||
```
|
||||
|
||||
### Customizing Color scheme
|
||||
|
||||
You can customize the color scheme using the `cScale0` to `cScale11` theme variables, which will change the background colors. Mermaid allows you to set unique colors for up-to 12 sections, where `cScale0` variable will drive the value of the first section or time-period, `cScale1` will drive the value of the second section and so on.
|
||||
In case you have more than 12 sections, the color scheme will start to repeat.
|
||||
|
||||
If you also want to change the foreground color of a section, you can do so use theme variables corresponding `cScaleLabel0` to `cScaleLabel11` variables.
|
||||
|
||||
**NOTE**: Default values for these theme variables are picked from the selected theme. If you want to override the default values, you can use the `initialize` call to add your custom theme variable values.
|
||||
|
||||
Example:
|
||||
|
||||
Now let's override the default values for the `cScale0` to `cScale2` variables:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'default'
|
||||
themeVariables:
|
||||
cScale0: '#ff0000'
|
||||
cScaleLabel0: '#ffffff'
|
||||
cScale1: '#00ff00'
|
||||
cScale2: '#0000ff'
|
||||
cScaleLabel2: '#ffffff'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'default'
|
||||
themeVariables:
|
||||
cScale0: '#ff0000'
|
||||
cScaleLabel0: '#ffffff'
|
||||
cScale1: '#00ff00'
|
||||
cScale2: '#0000ff'
|
||||
cScaleLabel2: '#ffffff'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
|
||||
```
|
||||
|
||||
See how the colors are changed to the values specified in the theme variables.
|
||||
|
||||
## Themes
|
||||
|
||||
Mermaid supports a bunch of pre-defined themes which you can use to find the right one for you. PS: you can actually override an existing theme's variable to get your own custom theme going. Learn more about [theming your diagram](../config/theming.md).
|
||||
|
||||
The following are the different pre-defined theme options:
|
||||
|
||||
- `base`
|
||||
- `forest`
|
||||
- `dark`
|
||||
- `default`
|
||||
- `neutral`
|
||||
|
||||
**NOTE**: To change theme you can either use the `initialize` call or _directives_. Learn more about [directives](../config/directives.md)
|
||||
Let's put them to use, and see how our sample diagram looks in different themes:
|
||||
|
||||
### Base Theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'base'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'base'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
### Forest Theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'forest'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'forest'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
### Dark Theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'dark'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'dark'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
### Default Theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'default'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'default'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
### Neutral Theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'neutral'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
logLevel: 'debug'
|
||||
theme: 'neutral'
|
||||
---
|
||||
timeline
|
||||
title History of Social Media Platform
|
||||
2002 : LinkedIn
|
||||
2004 : Facebook : Google
|
||||
2005 : YouTube
|
||||
2006 : Twitter
|
||||
2007 : Tumblr
|
||||
2008 : Instagram
|
||||
2010 : Pinterest
|
||||
```
|
||||
|
||||
## Integrating with your library/website
|
||||
|
||||
Timeline uses experimental lazy loading & async rendering features which could change in the future.The lazy loading is important in order to be able to add additional diagrams going forward.
|
||||
|
||||
You can use this method to add mermaid including the timeline diagram to a web page:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
|
||||
</script>
|
||||
```
|
||||
|
||||
You can also refer the [implementation in the live editor](https://github.com/mermaid-js/mermaid-live-editor/blob/develop/src/lib/util/mermaid.ts) to see how the async loading is done.
|
||||
@@ -1,353 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/treemap.md](../../packages/mermaid/src/docs/syntax/treemap.md).
|
||||
|
||||
# Treemap Diagram
|
||||
|
||||
> A treemap diagram displays hierarchical data as a set of nested rectangles. Each branch of the tree is represented by a rectangle, which is then tiled with smaller rectangles representing sub-branches.
|
||||
|
||||
> **Warning**
|
||||
> This is a new diagram type in Mermaid. Its syntax may evolve in future versions.
|
||||
|
||||
## Introduction
|
||||
|
||||
Treemap diagrams are an effective way to visualize hierarchical data and show proportions between categories and subcategories. The size of each rectangle is proportional to the value it represents, making it easy to compare different parts of a hierarchy.
|
||||
|
||||
Treemap diagrams are particularly useful for:
|
||||
|
||||
- Visualizing hierarchical data structures
|
||||
- Comparing proportions between categories
|
||||
- Displaying large amounts of hierarchical data in a limited space
|
||||
- Identifying patterns and outliers in hierarchical data
|
||||
|
||||
## Syntax
|
||||
|
||||
```
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2"
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20
|
||||
"Leaf 2.2": 25
|
||||
```
|
||||
|
||||
### Node Definition
|
||||
|
||||
Nodes in a treemap are defined using the following syntax:
|
||||
|
||||
- **Section/Parent nodes**: Defined with quoted text `"Section Name"`
|
||||
- **Leaf nodes with values**: Defined with quoted text followed by a colon and value `"Leaf Name": value`
|
||||
- **Hierarchy**: Created using indentation (spaces or tabs)
|
||||
- **Styling**: Nodes can be styled using the `:::class` syntax
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Treemap
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
### Hierarchical Treemap
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Products"
|
||||
"Electronics"
|
||||
"Phones": 50
|
||||
"Computers": 30
|
||||
"Accessories": 20
|
||||
"Clothing"
|
||||
"Men's": 40
|
||||
"Women's": 40
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Products"
|
||||
"Electronics"
|
||||
"Phones": 50
|
||||
"Computers": 30
|
||||
"Accessories": 20
|
||||
"Clothing"
|
||||
"Men's": 40
|
||||
"Women's": 40
|
||||
```
|
||||
|
||||
### Treemap with Styling
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2":::class1
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20:::class1
|
||||
"Leaf 2.2": 25
|
||||
"Leaf 2.3": 12
|
||||
|
||||
classDef class1 fill:red,color:blue,stroke:#FFD600;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Section 1"
|
||||
"Leaf 1.1": 12
|
||||
"Section 1.2":::class1
|
||||
"Leaf 1.2.1": 12
|
||||
"Section 2"
|
||||
"Leaf 2.1": 20:::class1
|
||||
"Leaf 2.2": 25
|
||||
"Leaf 2.3": 12
|
||||
|
||||
classDef class1 fill:red,color:blue,stroke:#FFD600;
|
||||
```
|
||||
|
||||
## Styling and Configuration
|
||||
|
||||
Treemap diagrams can be customized using Mermaid's styling and configuration options.
|
||||
|
||||
### Using classDef for Styling
|
||||
|
||||
You can define custom styles for nodes using the `classDef` syntax, which is a standard feature across many Mermaid diagram types:
|
||||
|
||||
```mermaid-example
|
||||
treemap-beta
|
||||
"Main"
|
||||
"A": 20
|
||||
"B":::important
|
||||
"B1": 10
|
||||
"B2": 15
|
||||
"C": 5
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:2px;
|
||||
```
|
||||
|
||||
```mermaid
|
||||
treemap-beta
|
||||
"Main"
|
||||
"A": 20
|
||||
"B":::important
|
||||
"B1": 10
|
||||
"B2": 15
|
||||
"C": 5
|
||||
|
||||
classDef important fill:#f96,stroke:#333,stroke-width:2px;
|
||||
```
|
||||
|
||||
### Theme Configuration
|
||||
|
||||
You can customize the colors of your treemap using the theme configuration:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
theme: 'forest'
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
### Diagram Padding
|
||||
|
||||
You can adjust the padding around the treemap diagram using the `diagramPadding` configuration option:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
diagramPadding: 200
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
diagramPadding: 200
|
||||
---
|
||||
treemap-beta
|
||||
"Category A"
|
||||
"Item A1": 10
|
||||
"Item A2": 20
|
||||
"Category B"
|
||||
"Item B1": 15
|
||||
"Item B2": 25
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
The treemap diagram supports the following configuration options:
|
||||
|
||||
| Option | Description | Default |
|
||||
| -------------- | --------------------------------------------------------------------------- | ------- |
|
||||
| useMaxWidth | When true, the diagram width is set to 100% and scales with available space | true |
|
||||
| padding | Internal padding between nodes | 10 |
|
||||
| diagramPadding | Padding around the entire diagram | 8 |
|
||||
| showValues | Whether to show values in the treemap | true |
|
||||
| nodeWidth | Width of nodes | 100 |
|
||||
| nodeHeight | Height of nodes | 40 |
|
||||
| borderWidth | Width of borders | 1 |
|
||||
| valueFontSize | Font size for values | 12 |
|
||||
| labelFontSize | Font size for labels | 14 |
|
||||
| valueFormat | Format for values (see Value Formatting section) | ',' |
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Value Formatting
|
||||
|
||||
Values in treemap diagrams can be formatted to display in different ways using the `valueFormat` configuration option. This option primarily uses [D3's format specifiers](https://github.com/d3/d3-format#locale_format) to control how numbers are displayed, with some additional special cases for common formats.
|
||||
|
||||
Some common format patterns:
|
||||
|
||||
- `,` - Thousands separator (default)
|
||||
- `$` - Add dollar sign
|
||||
- `.1f` - Show one decimal place
|
||||
- `.1%` - Show as percentage with one decimal place
|
||||
- `$0,0` - Dollar sign with thousands separator
|
||||
- `$.2f` - Dollar sign with 2 decimal places
|
||||
- `$,.2f` - Dollar sign with thousands separator and 2 decimal places
|
||||
|
||||
The treemap diagram supports both standard D3 format specifiers and some common currency formats that combine the dollar sign with other formatting options.
|
||||
|
||||
Example with currency formatting:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$0,0'
|
||||
---
|
||||
treemap-beta
|
||||
"Budget"
|
||||
"Operations"
|
||||
"Salaries": 700000
|
||||
"Equipment": 200000
|
||||
"Supplies": 100000
|
||||
"Marketing"
|
||||
"Advertising": 400000
|
||||
"Events": 100000
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$0,0'
|
||||
---
|
||||
treemap-beta
|
||||
"Budget"
|
||||
"Operations"
|
||||
"Salaries": 700000
|
||||
"Equipment": 200000
|
||||
"Supplies": 100000
|
||||
"Marketing"
|
||||
"Advertising": 400000
|
||||
"Events": 100000
|
||||
```
|
||||
|
||||
Example with percentage formatting:
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$.1%'
|
||||
---
|
||||
treemap-beta
|
||||
"Market Share"
|
||||
"Company A": 0.35
|
||||
"Company B": 0.25
|
||||
"Company C": 0.15
|
||||
"Others": 0.25
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treemap:
|
||||
valueFormat: '$.1%'
|
||||
---
|
||||
treemap-beta
|
||||
"Market Share"
|
||||
"Company A": 0.35
|
||||
"Company B": 0.25
|
||||
"Company C": 0.15
|
||||
"Others": 0.25
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
Treemap diagrams are commonly used for:
|
||||
|
||||
1. **Financial Data**: Visualizing budget allocations, market shares, or portfolio compositions
|
||||
2. **File System Analysis**: Showing disk space usage by folders and files
|
||||
3. **Population Demographics**: Displaying population distribution across regions and subregions
|
||||
4. **Product Hierarchies**: Visualizing product categories and their sales volumes
|
||||
5. **Organizational Structures**: Representing departments and team sizes in a company
|
||||
|
||||
## Limitations
|
||||
|
||||
- Treemap diagrams work best when the data has a natural hierarchy
|
||||
- Very small values may be difficult to see or label in a treemap diagram
|
||||
- Deep hierarchies (many levels) can be challenging to represent clearly
|
||||
- Treemap diagrams are not well suited for representing data with negative values
|
||||
|
||||
## Related Diagrams
|
||||
|
||||
If treemap diagrams don't suit your needs, consider these alternatives:
|
||||
|
||||
- [**Pie Charts**](./pie.md): For simple proportion comparisons without hierarchy
|
||||
- **Sunburst Diagrams**: For hierarchical data with a radial layout (yet to be released in Mermaid).
|
||||
- [**Sankey Diagrams**](./sankey.md): For flow-based hierarchical data
|
||||
|
||||
## Notes
|
||||
|
||||
The treemap diagram implementation in Mermaid is designed to be simple to use while providing powerful visualization capabilities. As this is a newer diagram type, feedback and feature requests are welcome through the Mermaid GitHub repository.
|
||||
@@ -1,42 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/userJourney.md](../../packages/mermaid/src/docs/syntax/userJourney.md).
|
||||
|
||||
# User Journey Diagram
|
||||
|
||||
> User journeys describe at a high level of detail exactly what steps different users take to complete a specific task within a system, application or website. This technique shows the current (as-is) user workflow, and reveals areas of improvement for the to-be workflow. (Wikipedia)
|
||||
|
||||
Mermaid can render user journey diagrams:
|
||||
|
||||
```mermaid-example
|
||||
journey
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
```
|
||||
|
||||
```mermaid
|
||||
journey
|
||||
title My working day
|
||||
section Go to work
|
||||
Make tea: 5: Me
|
||||
Go upstairs: 3: Me
|
||||
Do work: 1: Me, Cat
|
||||
section Go home
|
||||
Go downstairs: 5: Me
|
||||
Sit down: 5: Me
|
||||
```
|
||||
|
||||
Each user journey is split into sections, these describe the part of the task
|
||||
the user is trying to complete.
|
||||
|
||||
Tasks syntax is `Task name: <score>: <comma separated list of actors>`
|
||||
|
||||
Score is a number between 1 and 5, inclusive.
|
||||
@@ -1,250 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/xyChart.md](../../packages/mermaid/src/docs/syntax/xyChart.md).
|
||||
|
||||
# XY Chart
|
||||
|
||||
> In the context of mermaid-js, the XY chart is a comprehensive charting module that encompasses various types of charts that utilize both x-axis and y-axis for data representation. Presently, it includes two fundamental chart types: the bar chart and the line chart. These charts are designed to visually display and analyze data that involve two numerical variables.
|
||||
|
||||
> It's important to note that while the current implementation of mermaid-js includes these two chart types, the framework is designed to be dynamic and adaptable. Therefore, it has the capacity for expansion and the inclusion of additional chart types in the future. This means that users can expect an evolving suite of charting options within the XY chart module, catering to various data visualization needs as new chart types are introduced over time.
|
||||
|
||||
## Example
|
||||
|
||||
```mermaid-example
|
||||
xychart
|
||||
title "Sales Revenue"
|
||||
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
|
||||
y-axis "Revenue (in $)" 4000 --> 11000
|
||||
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
xychart
|
||||
title "Sales Revenue"
|
||||
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
|
||||
y-axis "Revenue (in $)" 4000 --> 11000
|
||||
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
> **Note**
|
||||
> All text values that contain only one word can be written without `"`. If a text value has many words in it, specifically if it contains spaces, enclose the value in `"`
|
||||
|
||||
### Orientations
|
||||
|
||||
The chart can be drawn horizontal or vertical, default value is vertical.
|
||||
|
||||
```
|
||||
xychart horizontal
|
||||
...
|
||||
```
|
||||
|
||||
### Title
|
||||
|
||||
The title is a short description of the chart and it will always render on top of the chart.
|
||||
|
||||
#### Example
|
||||
|
||||
```
|
||||
xychart
|
||||
title "This is a simple example"
|
||||
...
|
||||
```
|
||||
|
||||
> **Note**
|
||||
> If the title is a single word one no need to use `"`, but if it has space `"` is needed
|
||||
|
||||
### x-axis
|
||||
|
||||
The x-axis primarily serves as a categorical value, although it can also function as a numeric range value when needed.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `x-axis title min --> max` x-axis will function as numeric with the given range
|
||||
2. `x-axis "title with space" [cat1, "cat2 with space", cat3]` x-axis if categorical, categories are text type
|
||||
|
||||
### y-axis
|
||||
|
||||
The y-axis is employed to represent numerical range values, it cannot have categorical values.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `y-axis title min --> max`
|
||||
2. `y-axis title` it will only add the title, the range will be auto generated from data.
|
||||
|
||||
> **Note**
|
||||
> Both x and y axis are optional if not provided we will try to create the range
|
||||
|
||||
### Line chart
|
||||
|
||||
A line chart offers the capability to graphically depict lines.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `line [2.3, 45, .98, -3.4]` it can have all valid numeric values.
|
||||
|
||||
### Bar chart
|
||||
|
||||
A bar chart offers the capability to graphically depict bars.
|
||||
|
||||
#### Example
|
||||
|
||||
1. `bar [2.3, 45, .98, -3.4]` it can have all valid numeric values.
|
||||
|
||||
#### Simplest example
|
||||
|
||||
The only two things required are the chart name (`xychart`) and one data set. So you will be able to draw a chart with a simple config like
|
||||
|
||||
```
|
||||
xychart
|
||||
line [+1.3, .6, 2.4, -.34]
|
||||
```
|
||||
|
||||
## Chart Configurations
|
||||
|
||||
| Parameter | Description | Default value |
|
||||
| ------------------------ | ------------------------------------------------------------- | :-----------: |
|
||||
| width | Width of the chart | 700 |
|
||||
| height | Height of the chart | 500 |
|
||||
| titlePadding | Top and Bottom padding of the title | 10 |
|
||||
| titleFontSize | Title font size | 20 |
|
||||
| showTitle | Title to be shown or not | true |
|
||||
| xAxis | xAxis configuration | AxisConfig |
|
||||
| yAxis | yAxis configuration | AxisConfig |
|
||||
| chartOrientation | 'vertical' or 'horizontal' | 'vertical' |
|
||||
| plotReservedSpacePercent | Minimum space plots will take inside the chart | 50 |
|
||||
| showDataLabel | Should show the value corresponding to the bar within the bar | false |
|
||||
|
||||
### AxisConfig
|
||||
|
||||
| Parameter | Description | Default value |
|
||||
| ------------- | ------------------------------------ | :-----------: |
|
||||
| showLabel | Show axis labels or tick values | true |
|
||||
| labelFontSize | Font size of the label to be drawn | 14 |
|
||||
| labelPadding | Top and Bottom padding of the label | 5 |
|
||||
| showTitle | Axis title to be shown or not | true |
|
||||
| titleFontSize | Axis title font size | 16 |
|
||||
| titlePadding | Top and Bottom padding of Axis title | 5 |
|
||||
| showTick | Tick to be shown or not | true |
|
||||
| tickLength | How long the tick will be | 5 |
|
||||
| tickWidth | How width the tick will be | 2 |
|
||||
| showAxisLine | Axis line to be shown or not | true |
|
||||
| axisLineWidth | Thickness of the axis line | 2 |
|
||||
|
||||
## Chart Theme Variables
|
||||
|
||||
Themes for xychart reside inside the `xychart` attribute, allowing customization through the following syntax:
|
||||
|
||||
```yaml
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
titleColor: '#ff0000'
|
||||
---
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| backgroundColor | Background color of the whole chart |
|
||||
| titleColor | Color of the Title text |
|
||||
| xAxisLabelColor | Color of the x-axis labels |
|
||||
| xAxisTitleColor | Color of the x-axis title |
|
||||
| xAxisTickColor | Color of the x-axis tick |
|
||||
| xAxisLineColor | Color of the x-axis line |
|
||||
| yAxisLabelColor | Color of the y-axis labels |
|
||||
| yAxisTitleColor | Color of the y-axis title |
|
||||
| yAxisTickColor | Color of the y-axis tick |
|
||||
| yAxisLineColor | Color of the y-axis line |
|
||||
| plotColorPalette | String of colors separated by comma e.g. "#f3456, #43445" |
|
||||
|
||||
### Setting Colors for Lines and Bars
|
||||
|
||||
To set the color for lines and bars, use the `plotColorPalette` parameter. Colors in the palette will correspond sequentially to the elements in your chart (e.g., first bar/line will use the first color specified in the palette).
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
plotColorPalette: '#000000, #0000FF, #00FF00, #FF0000'
|
||||
---
|
||||
xychart
|
||||
title "Different Colors in xyChart"
|
||||
x-axis "categoriesX" ["Category 1", "Category 2", "Category 3", "Category 4"]
|
||||
y-axis "valuesY" 0 --> 50
|
||||
%% Black line
|
||||
line [10,20,30,40]
|
||||
%% Blue bar
|
||||
bar [20,30,25,35]
|
||||
%% Green bar
|
||||
bar [15,25,20,30]
|
||||
%% Red line
|
||||
line [5,15,25,35]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
themeVariables:
|
||||
xyChart:
|
||||
plotColorPalette: '#000000, #0000FF, #00FF00, #FF0000'
|
||||
---
|
||||
xychart
|
||||
title "Different Colors in xyChart"
|
||||
x-axis "categoriesX" ["Category 1", "Category 2", "Category 3", "Category 4"]
|
||||
y-axis "valuesY" 0 --> 50
|
||||
%% Black line
|
||||
line [10,20,30,40]
|
||||
%% Blue bar
|
||||
bar [20,30,25,35]
|
||||
%% Green bar
|
||||
bar [15,25,20,30]
|
||||
%% Red line
|
||||
line [5,15,25,35]
|
||||
```
|
||||
|
||||
## Example on config and theme
|
||||
|
||||
```mermaid-example
|
||||
---
|
||||
config:
|
||||
xyChart:
|
||||
width: 900
|
||||
height: 600
|
||||
showDataLabel: true
|
||||
themeVariables:
|
||||
xyChart:
|
||||
titleColor: "#ff0000"
|
||||
---
|
||||
xychart
|
||||
title "Sales Revenue"
|
||||
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
|
||||
y-axis "Revenue (in $)" 4000 --> 11000
|
||||
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
```
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
xyChart:
|
||||
width: 900
|
||||
height: 600
|
||||
showDataLabel: true
|
||||
themeVariables:
|
||||
xyChart:
|
||||
titleColor: "#ff0000"
|
||||
---
|
||||
xychart
|
||||
title "Sales Revenue"
|
||||
x-axis [jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec]
|
||||
y-axis "Revenue (in $)" 4000 --> 11000
|
||||
bar [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
line [5000, 6000, 7500, 8200, 9500, 10500, 11000, 10200, 9200, 8500, 7000, 6000]
|
||||
```
|
||||
@@ -1,474 +0,0 @@
|
||||
> **Warning**
|
||||
>
|
||||
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
|
||||
>
|
||||
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/zenuml.md](../../packages/mermaid/src/docs/syntax/zenuml.md).
|
||||
|
||||
# ZenUML
|
||||
|
||||
> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
|
||||
|
||||
Mermaid can render sequence diagrams with [ZenUML](https://zenuml.com). Note that ZenUML uses a different
|
||||
syntax than the original Sequence Diagram in mermaid.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Demo
|
||||
Alice->John: Hello John, how are you?
|
||||
John->Alice: Great!
|
||||
Alice->John: See you later!
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Demo
|
||||
Alice->John: Hello John, how are you?
|
||||
John->Alice: Great!
|
||||
Alice->John: See you later!
|
||||
```
|
||||
|
||||
## Syntax
|
||||
|
||||
### Participants
|
||||
|
||||
The participants can be defined implicitly as in the first example on this page. The participants or actors are
|
||||
rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a
|
||||
different order than how they appear in the first message. It is possible to specify the actor's order of
|
||||
appearance by doing the following:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Declare participant (optional)
|
||||
Bob
|
||||
Alice
|
||||
Alice->Bob: Hi Bob
|
||||
Bob->Alice: Hi Alice
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Declare participant (optional)
|
||||
Bob
|
||||
Alice
|
||||
Alice->Bob: Hi Bob
|
||||
Bob->Alice: Hi Alice
|
||||
```
|
||||
|
||||
### Annotators
|
||||
|
||||
If you specifically want to use symbols instead of just rectangles with text you can do so by using the annotator syntax to declare participants as per below.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Annotators
|
||||
@Actor Alice
|
||||
@Database Bob
|
||||
Alice->Bob: Hi Bob
|
||||
Bob->Alice: Hi Alice
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Annotators
|
||||
@Actor Alice
|
||||
@Database Bob
|
||||
Alice->Bob: Hi Bob
|
||||
Bob->Alice: Hi Alice
|
||||
```
|
||||
|
||||
Here are the available annotators:
|
||||
|
||||
|
||||
### Aliases
|
||||
|
||||
The participants can have a convenient identifier and a descriptive label.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Aliases
|
||||
A as Alice
|
||||
J as John
|
||||
A->J: Hello John, how are you?
|
||||
J->A: Great!
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Aliases
|
||||
A as Alice
|
||||
J as John
|
||||
A->J: Hello John, how are you?
|
||||
J->A: Great!
|
||||
```
|
||||
|
||||
## Messages
|
||||
|
||||
Messages can be one of:
|
||||
|
||||
1. Sync message
|
||||
2. Async message
|
||||
3. Creation message
|
||||
4. Reply message
|
||||
|
||||
### Sync message
|
||||
|
||||
You can think of a sync (blocking) method in a programming language.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Sync message
|
||||
A.SyncMessage
|
||||
A.SyncMessage(with, parameters) {
|
||||
B.nestedSyncMessage()
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Sync message
|
||||
A.SyncMessage
|
||||
A.SyncMessage(with, parameters) {
|
||||
B.nestedSyncMessage()
|
||||
}
|
||||
```
|
||||
|
||||
### Async message
|
||||
|
||||
You can think of an async (non-blocking) method in a programming language.
|
||||
Fire an event and forget about it.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Async message
|
||||
Alice->Bob: How are you?
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Async message
|
||||
Alice->Bob: How are you?
|
||||
```
|
||||
|
||||
### Creation message
|
||||
|
||||
We use `new` keyword to create an object.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
new A1
|
||||
new A2(with, parameters)
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
new A1
|
||||
new A2(with, parameters)
|
||||
```
|
||||
|
||||
### Reply message
|
||||
|
||||
There are three ways to express a reply message:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
// 1. assign a variable from a sync message.
|
||||
a = A.SyncMessage()
|
||||
|
||||
// 1.1. optionally give the variable a type
|
||||
SomeType a = A.SyncMessage()
|
||||
|
||||
// 2. use return keyword
|
||||
A.SyncMessage() {
|
||||
return result
|
||||
}
|
||||
|
||||
// 3. use @return or @reply annotator on an async message
|
||||
@return
|
||||
A->B: result
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
// 1. assign a variable from a sync message.
|
||||
a = A.SyncMessage()
|
||||
|
||||
// 1.1. optionally give the variable a type
|
||||
SomeType a = A.SyncMessage()
|
||||
|
||||
// 2. use return keyword
|
||||
A.SyncMessage() {
|
||||
return result
|
||||
}
|
||||
|
||||
// 3. use @return or @reply annotator on an async message
|
||||
@return
|
||||
A->B: result
|
||||
```
|
||||
|
||||
The third way `@return` is rarely used, but it is useful when you want to return to one level up.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
title Reply message
|
||||
Client->A.method() {
|
||||
B.method() {
|
||||
if(condition) {
|
||||
return x1
|
||||
// return early
|
||||
@return
|
||||
A->Client: x11
|
||||
}
|
||||
}
|
||||
return x2
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
title Reply message
|
||||
Client->A.method() {
|
||||
B.method() {
|
||||
if(condition) {
|
||||
return x1
|
||||
// return early
|
||||
@return
|
||||
A->Client: x11
|
||||
}
|
||||
}
|
||||
return x2
|
||||
}
|
||||
```
|
||||
|
||||
## Nesting
|
||||
|
||||
Sync messages and Creation messages are naturally nestable with `{}`.
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
A.method() {
|
||||
B.nested_sync_method()
|
||||
B->C: nested async message
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
A.method() {
|
||||
B.nested_sync_method()
|
||||
B->C: nested async message
|
||||
}
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
It is possible to add comments to a sequence diagram with `// comment` syntax.
|
||||
Comments will be rendered above the messages or fragments. Comments on other places
|
||||
are ignored. Markdown is supported.
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
// a comment on a participant will not be rendered
|
||||
BookService
|
||||
// a comment on a message.
|
||||
// **Markdown** is supported.
|
||||
BookService.getBook()
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
// a comment on a participant will not be rendered
|
||||
BookService
|
||||
// a comment on a message.
|
||||
// **Markdown** is supported.
|
||||
BookService.getBook()
|
||||
```
|
||||
|
||||
## Loops
|
||||
|
||||
It is possible to express loops in a ZenUML diagram. This is done by any of the
|
||||
following notations:
|
||||
|
||||
1. while
|
||||
2. for
|
||||
3. forEach, foreach
|
||||
4. loop
|
||||
|
||||
```zenuml
|
||||
while(condition) {
|
||||
...statements...
|
||||
}
|
||||
```
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
Alice->John: Hello John, how are you?
|
||||
while(true) {
|
||||
John->Alice: Great!
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
Alice->John: Hello John, how are you?
|
||||
while(true) {
|
||||
John->Alice: Great!
|
||||
}
|
||||
```
|
||||
|
||||
## Alt
|
||||
|
||||
It is possible to express alternative paths in a sequence diagram. This is done by the notation
|
||||
|
||||
```zenuml
|
||||
if(condition1) {
|
||||
...statements...
|
||||
} else if(condition2) {
|
||||
...statements...
|
||||
} else {
|
||||
...statements...
|
||||
}
|
||||
```
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
if(is_sick) {
|
||||
Bob->Alice: Not so good :(
|
||||
} else {
|
||||
Bob->Alice: Feeling fresh like a daisy
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
if(is_sick) {
|
||||
Bob->Alice: Not so good :(
|
||||
} else {
|
||||
Bob->Alice: Feeling fresh like a daisy
|
||||
}
|
||||
```
|
||||
|
||||
## Opt
|
||||
|
||||
It is possible to render an `opt` fragment. This is done by the notation
|
||||
|
||||
```zenuml
|
||||
opt {
|
||||
...statements...
|
||||
}
|
||||
```
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Not so good :(
|
||||
opt {
|
||||
Bob->Alice: Thanks for asking
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
Alice->Bob: Hello Bob, how are you?
|
||||
Bob->Alice: Not so good :(
|
||||
opt {
|
||||
Bob->Alice: Thanks for asking
|
||||
}
|
||||
```
|
||||
|
||||
## Parallel
|
||||
|
||||
It is possible to show actions that are happening in parallel.
|
||||
|
||||
This is done by the notation
|
||||
|
||||
```zenuml
|
||||
par {
|
||||
statement1
|
||||
statement2
|
||||
statement3
|
||||
}
|
||||
```
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
par {
|
||||
Alice->Bob: Hello guys!
|
||||
Alice->John: Hello guys!
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
par {
|
||||
Alice->Bob: Hello guys!
|
||||
Alice->John: Hello guys!
|
||||
}
|
||||
```
|
||||
|
||||
## Try/Catch/Finally (Break)
|
||||
|
||||
It is possible to indicate a stop of the sequence within the flow (usually used to model exceptions).
|
||||
|
||||
This is done by the notation
|
||||
|
||||
```
|
||||
try {
|
||||
...statements...
|
||||
} catch {
|
||||
...statements...
|
||||
} finally {
|
||||
...statements...
|
||||
}
|
||||
```
|
||||
|
||||
See the example below:
|
||||
|
||||
```mermaid-example
|
||||
zenuml
|
||||
try {
|
||||
Consumer->API: Book something
|
||||
API->BookingService: Start booking process
|
||||
} catch {
|
||||
API->Consumer: show failure
|
||||
} finally {
|
||||
API->BookingService: rollback status
|
||||
}
|
||||
```
|
||||
|
||||
```mermaid
|
||||
zenuml
|
||||
try {
|
||||
Consumer->API: Book something
|
||||
API->BookingService: Start booking process
|
||||
} catch {
|
||||
API->Consumer: show failure
|
||||
} finally {
|
||||
API->BookingService: rollback status
|
||||
}
|
||||
```
|
||||
|
||||
## Integrating with your library/website.
|
||||
|
||||
Zenuml uses the experimental lazy loading & async rendering features which could change in the future.
|
||||
|
||||
You can use this method to add mermaid including the zenuml diagram to a web page:
|
||||
|
||||
```html
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
|
||||
import zenuml from 'https://cdn.jsdelivr.net/npm/@mermaid-js/mermaid-zenuml@0.1.0/dist/mermaid-zenuml.esm.min.mjs';
|
||||
await mermaid.registerExternalDiagrams([zenuml]);
|
||||
</script>
|
||||
```
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
name: pdn-152fz-audit
|
||||
description: Аудит защиты персональных данных Лидерры и соответствие 152-ФЗ. Режим 1 — техника (где лежат ПДн в схеме/коде, RLS, маскирование pg_anonymizer, утечки в логах/Sentry/CSV-экспортах, шифрование). Режим 2 — закон (хранение в РФ, согласия, сроки/удаление, реестр обработки, уведомление РКН, права субъекта pd_subject_request). Используй при «проверь ПДн», «утекают ли персональные данные», «соответствие 152-ФЗ», «где хранятся телефоны лидов», «маскируются ли данные в дампах». НЕ для денежной корректности (billing-audit), security-аудита кода (D3/Semgrep), юридического оформления договоров/политик (D2 право), generic-угроз (threat-model #72).
|
||||
---
|
||||
|
||||
# ПДн 152-ФЗ Аудит — защита персональных данных Лидерры
|
||||
|
||||
Проектный скил раздела A8 карты «Информационная безопасность». Проверяет
|
||||
**защиту персональных данных** и соответствие Федеральному закону №152-ФЗ
|
||||
«О персональных данных» для SaaS-портала, обрабатывающего телефоны лидов
|
||||
и данные клиентов-компаний перед выходом в продакшен.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Вопрос «не утекают ли ПДн в логи / Sentry / CSV-экспорты?»
|
||||
- Проверка технической защиты ПДн перед запуском (RLS, маскирование, шифрование).
|
||||
- Оценка соответствия 152-ФЗ: хранение в РФ, согласия, права субъекта, реестр.
|
||||
- Ревью кода, затрагивающего `deals`, `users`, `pd_subject_requests`,
|
||||
`pd_processing_log`, `supplier_leads` или CSV-импорт/экспорт лидов.
|
||||
|
||||
## Два режима
|
||||
|
||||
### Режим 1 — Технический аудит ПДн
|
||||
|
||||
Проверяет, что персональные данные физически защищены в коде и схеме БД.
|
||||
|
||||
Вопросы:
|
||||
|
||||
- Какие таблицы/колонки содержат ПДн? Под RLS ли они?
|
||||
- Маскируются ли ПДн в дампах (pg_anonymizer)?
|
||||
- Не утекают ли phone/email/ФИО в Laravel-логи, Sentry, `activity_log.context`,
|
||||
`auth_log`, `supplier_leads.raw_payload`?
|
||||
- Зашифрованы ли чувствительные поля в покое (totp_secret)?
|
||||
- Защищены ли CSV-экспорты лидов (signed URL + аудит в `pd_processing_log`)?
|
||||
|
||||
**Запустить:** пройти по чек-листу `references/checklist.md` → Раздел 1.
|
||||
|
||||
### Режим 2 — Соответствие 152-ФЗ
|
||||
|
||||
Проверяет правовую и процессную сторону обработки ПДн.
|
||||
|
||||
Вопросы:
|
||||
|
||||
- Хранятся ли ПДн на территории РФ?
|
||||
- Зафиксированы ли согласия субъектов ПДн (`tenant_consents`)?
|
||||
- Есть ли механизм обращений субъектов (`pd_subject_requests` + дедлайн 30 дней)?
|
||||
- Ведётся ли журнал обработки ПДн (`pd_processing_log`)?
|
||||
- Уведомлен ли РКН? Есть ли реестр обработки?
|
||||
- Реализовано ли право на ограничение обработки (`processing_restricted`)?
|
||||
|
||||
**Запустить:** пройти по чек-листу `references/checklist.md` → Раздел 2.
|
||||
|
||||
## Границы
|
||||
|
||||
- ≠ `billing-audit` #62 — тот про *денежную корректность начислений*; pdn-152fz-audit про *персональные данные*.
|
||||
- ≠ D3 «audit-security» (#39/#40 Trail of Bits / Semgrep) — те про *security-уязвимости кода*; pdn-152fz-audit про *данные субъектов ПДн*.
|
||||
- ≠ D2 «Право / договоры» — там юридическое оформление (политика обработки, договор с оператором); pdn-152fz-audit про *технику и процедуры*.
|
||||
- ≠ `threat-model` #72 — тот про *моделирование угроз*; pdn-152fz-audit про *конкретные ПДн в конкретных таблицах*.
|
||||
|
||||
## Связано
|
||||
|
||||
- Reuse: Boost #10 (SQL-запросы к схеме), Semgrep #25 (статанализ кода на утечки),
|
||||
Sentry MCP #34 (проверка runtime-маскирования), pg_anonymizer #29 (дампы).
|
||||
- ADR-013 (infosec-tooling A8).
|
||||
- Нормативная основа: ФЗ-152 ст.18 (уведомление РКН), ст.21 ч.5 (ограничение
|
||||
обработки), ст.22 (реестр операторов), ст.14 (права субъекта).
|
||||
@@ -1,10 +0,0 @@
|
||||
{
|
||||
"skill": "pdn-152fz-audit",
|
||||
"cases": [
|
||||
{"prompt": "проверь, не утекают ли телефоны лидов в логи", "should_trigger": true},
|
||||
{"prompt": "соответствует ли портал 152-ФЗ перед запуском", "should_trigger": true},
|
||||
{"prompt": "проверь, не теряются ли копейки в списании", "should_trigger": false, "expected": "billing-audit"},
|
||||
{"prompt": "смоделируй угрозы при выходе портала в интернет", "should_trigger": false, "expected": "threat-model"},
|
||||
{"prompt": "составь договор обработки персональных данных", "should_trigger": false, "expected": "D2 право"}
|
||||
]
|
||||
}
|
||||
@@ -1,202 +0,0 @@
|
||||
# ПДн 152-ФЗ — чек-лист аудита Лидерры
|
||||
|
||||
Основан на реальных артефактах проекта (db/schema.sql v8.26, 21.05.2026).
|
||||
|
||||
## Таблицы-носители ПДн (инвентарь)
|
||||
|
||||
| Таблица | ПДн-колонки | Тип субъекта |
|
||||
|---|---|---|
|
||||
| `deals` | `phone`, `phones` (JSONB), `contact_name`, `city` | лид (физлицо) |
|
||||
| `supplier_leads` | `phone`, `raw_payload` (JSONB — весь payload поставщика) | лид (физлицо) |
|
||||
| `users` | `email`, `first_name`, `last_name`, `phone`, `totp_secret` | пользователь-клиент |
|
||||
| `tenants` | `contact_email`, `organization_name` | организация-клиент |
|
||||
| `auth_log` | `email` (при login_failed для неизвестного пользователя) | пользователь |
|
||||
| `pd_subject_requests` | `subject_email`, `subject_phone`, `subject_full_name` | субъект ПДн |
|
||||
| `impersonation_tokens` | косвенно (связь user — admin) | пользователь |
|
||||
| `import_log` | `filename`, `file_path` (может содержать имя файла с ПДн) | лид (косвенно) |
|
||||
|
||||
---
|
||||
|
||||
## Раздел 1 — Технический аудит ПДн
|
||||
|
||||
### Т1. RLS на таблицах-носителях ПДн
|
||||
|
||||
- [ ] `deals` — `ENABLE ROW LEVEL SECURITY` ✅ (подтверждено schema.sql:2780).
|
||||
Проверить: `FORCE ROW LEVEL SECURITY` не выставлен (только у `lead_charges`
|
||||
— там сильнее). Убедиться, что `crm_app_user` не BYPASSRLS.
|
||||
- [ ] `users` — RLS включён (schema.sql:2778). Политика `tenant_isolation` по
|
||||
`tenant_id`. Проверить: нет прямого SELECT * без `SET LOCAL app.current_tenant_id`.
|
||||
- [ ] `supplier_leads` — **RLS не включён** (таблица SaaS-уровня, schema.sql:1948).
|
||||
Это осознанное решение. Проверить: доступ только из воркера
|
||||
(`crm_supplier_worker` BYPASSRLS) с явным `WHERE tenant_id`.
|
||||
- [ ] `pd_subject_requests` — **RLS не включён** намеренно (saas-уровневая,
|
||||
schema.sql:2483). Доступ только через `crm_admin_user` BYPASSRLS.
|
||||
Проверить: tenant-приложение к таблице не обращается.
|
||||
- [ ] `auth_log` — RLS включён (schema.sql:2810). Политика `tenant_isolation`.
|
||||
Проверить: поле `email` в строке `login_failed` — не утекает ли email
|
||||
несуществующего пользователя в посторонний тенант.
|
||||
- [ ] `import_log` — RLS включён (schema.sql:2790).
|
||||
|
||||
### Т2. Маскирование ПДн в дампах (pg_anonymizer #29)
|
||||
|
||||
- [ ] **Проверить вручную:** OPEN-И-24 (schema.sql:113) — «pg_anonymizer процедура,
|
||||
документация в Прил. И, без изменений схемы». Расширение ставится в фазе 3
|
||||
(db/CHANGELOG_schema.md:625). На момент аудита — **расширение может быть не
|
||||
установлено**. Выполнить: `psql -c "SELECT extname FROM pg_extension WHERE extname='anon';"`.
|
||||
- [ ] Если pg_anonymizer установлен: проверить наличие `SECURITY LABEL` /
|
||||
`anon.mask_column` на колонках `deals.phone`, `deals.contact_name`,
|
||||
`users.email`, `users.first_name`, `users.last_name`.
|
||||
- [ ] Если pg_anonymizer **не установлен**: дампы (`pg_dump`) содержат ПДн в открытом
|
||||
виде — критический риск перед продакшеном. Требуется: либо установить
|
||||
расширение и настроить маски, либо запретить дампы с ПДн вне зашифрованного
|
||||
хранилища.
|
||||
|
||||
### Т3. Утечки ПДн в логи и Sentry
|
||||
|
||||
- [ ] **Sentry PII-scrubbing** (OPEN-И-16, schema.sql:68): конфигурация в
|
||||
`app/config/sentry.php` (narrative §22 «Sentry PII-scrubbing»).
|
||||
Проверить: whitelist событий задан; regex-маска `phone`/`email`/`password`/
|
||||
`secret`/`token`/`api_key` включена. Тест: намеренно вызвать ошибку с
|
||||
телефоном в payload и проверить Sentry-событие.
|
||||
- [ ] **Laravel-логи (`storage/logs/`)**: нет ли `Log::info`/`Log::debug` с
|
||||
`$deal->phone`, `$lead->phone`, `request()->all()` в необработанном виде.
|
||||
Grep: `Log::` + `phone\|email\|contact_name` в `app/app/`.
|
||||
- [ ] **`activity_log.context`** (JSONB, schema.sql:1775): поле `context` журнала
|
||||
действий по сделкам. Проверить: не пишется ли туда `phone`/`contact_name`
|
||||
полностью (должны быть только ID и маскированные значения).
|
||||
- [ ] **`supplier_leads.raw_payload`** (JSONB, schema.sql:1966): хранит весь
|
||||
webhook-payload от поставщика, включая телефон. Это осознанное хранение
|
||||
(нужно для дебага/реконсайла). Проверить: доступ ограничен только
|
||||
`crm_supplier_worker` + `crm_admin_user`; не отдаётся в tenant API.
|
||||
- [ ] **`auth_log.email`** (schema.sql:1458): email попадает в лог при `login_failed`
|
||||
для неизвестного адреса. Проверить: колонка не индексируется publicly,
|
||||
доступна только под RLS tenant-политикой.
|
||||
|
||||
### Т4. Шифрование чувствительных полей в покое
|
||||
|
||||
- [ ] **`users.totp_secret`** (schema.sql:723): комментарий «ШИФРУЕТСЯ `Crypt::encrypt`».
|
||||
Проверить: в коде Laravel используется `Crypt::encrypt`/`decrypt`, не plain TEXT.
|
||||
Grep: `totp_secret` в моделях/сервисах — нет ли прямого assignment без encrypt.
|
||||
- [ ] **`tenants.webhook_token`** (schema.sql:628): хранится в открытом виде как
|
||||
уникальный токен. Допустимо (по дизайну — это API-ключ, не пароль), но
|
||||
проверить: не логируется ли при ротации (`webhook_token_rotated_at`).
|
||||
- [ ] **Encryption at rest (диск/облако)**: Yandex Cloud `ru-central1` — проверить,
|
||||
включено ли шифрование диска/объектного хранилища на уровне YC-консоли.
|
||||
Это вне кода, но обязательно для 152-ФЗ.
|
||||
|
||||
### Т5. CSV-экспорт лидов и signed URL
|
||||
|
||||
- [ ] **`report_jobs`** (schema.sql:2313): `file_path` = `s3://bucket/path/file.xlsx`.
|
||||
Триггер `trg_report_jobs_export_log` (schema.sql:3096) автоматически пишет
|
||||
запись в `pd_processing_log` при INSERT. Проверить: триггер активен в prod.
|
||||
SQL: `SELECT tgname, tgenabled FROM pg_trigger WHERE tgname = 'trg_report_jobs_export_log';`
|
||||
- [ ] **Signed URL TTL**: schema.sql:3182 — «доступ через signed URL TTL 1 ч».
|
||||
Проверить в коде: `Storage::temporaryUrl(...)` с `now()->addHour()`.
|
||||
Файлы экспорта не доступны без аутентификации.
|
||||
- [ ] **`report_jobs.expires_at`**: автоудаление файла. Проверить: есть ли
|
||||
scheduled command / cleanup job, удаляющий S3-файл и обнуляющий `file_path`
|
||||
после `expires_at`.
|
||||
|
||||
### Т6. CSV-импорт исторических лидов
|
||||
|
||||
- [ ] **`import_log.file_path`** (schema.sql:1544): путь к загруженному CSV-файлу с
|
||||
ПДн. Проверить: файл хранится во временном/приватном location, не в
|
||||
публично доступном URL; удаляется после обработки.
|
||||
- [ ] **Проверить вручную:** содержит ли исторический CSV телефоны лидов в открытом
|
||||
виде в `storage/`? Если да — нужен cleanup после импорта.
|
||||
|
||||
---
|
||||
|
||||
## Раздел 2 — Соответствие 152-ФЗ
|
||||
|
||||
### З1. Хранение ПДн на территории РФ (ст.18.1 152-ФЗ)
|
||||
|
||||
- [ ] Облако: Yandex Cloud, регион `ru-central1` (Москва) — **✅ РФ**.
|
||||
Подтверждено в CLAUDE.md §2.
|
||||
- [ ] S3-хранилище файлов экспорта (`report_jobs.file_path`): убедиться, что
|
||||
Yandex Object Storage используется (не AWS S3 / GCS). Проверить
|
||||
`app/config/filesystems.php`.
|
||||
- [ ] Self-hosted Sentry: Yandex Cloud `ru-central1` — ✅ РФ (CLAUDE.md §2).
|
||||
Проверить: Sentry не проксирует события в eu.sentry.io / sentry.io (US).
|
||||
- [ ] Unisender Go (email): **Проверить вручную** — уточнить у Unisender
|
||||
расположение серверов; письма с ПДн (email адреса) передаются провайдеру.
|
||||
|
||||
### З2. Согласия субъектов ПДн (ст.6, ст.9 152-ФЗ)
|
||||
|
||||
- [ ] **`tenant_consents`** (schema.sql:2430): таблица согласий. Проверить:
|
||||
при регистрации тенанта записывается `consent_type='pd_processing'` с
|
||||
`document_version`, `ip_address`, `user_agent`, `given_at`.
|
||||
- [ ] Проверить: согласие на обработку ПДн лидов (телефоны физлиц) — не пользователя-
|
||||
клиента, а лидов. Лиды приходят от поставщика (crm.bp-gr.ru) — проверить
|
||||
договор с поставщиком (правовое основание обработки ст.6 ч.1 п.5 или п.4).
|
||||
**Проверить вручную** — вне schema (юридический документ).
|
||||
- [ ] `consent_type` значения: `pd_processing`, `marketing`, `oferta_v1` — убедиться,
|
||||
что consent_type='pd_processing' обязателен при регистрации (нет bypass).
|
||||
|
||||
### З3. Сроки хранения и удаление (ст.21 152-ФЗ)
|
||||
|
||||
- [ ] **Soft-delete в `deals`** (schema.sql:1648 `deleted_at`): после soft-delete
|
||||
данные остаются. Проверить: есть ли политика retention (hard-delete или
|
||||
анонимизация `phone`/`contact_name` через N дней после `deleted_at`).
|
||||
**Проверить вручную:** scheduled command для hard-delete сделок.
|
||||
- [ ] **`users.deleted_at`** (schema.sql:751): комментарий «soft delete + анонимизация».
|
||||
Проверить в коде: при soft-delete пользователя анонимизируются ли
|
||||
`email`/`first_name`/`last_name`/`phone`? Grep: `UserObserver` / `UserService`
|
||||
метод delete/anonymize.
|
||||
- [ ] **Право на удаление** (ст.21): обращение типа `request_type='deletion'` в
|
||||
`pd_subject_requests`. Проверить: есть ли процедура исполнения (скрипт/ручной
|
||||
процесс) удаления ПДн конкретного субъекта по `subject_phone`/`subject_email`
|
||||
из `deals`, `supplier_leads`, `activity_log`.
|
||||
|
||||
### З4. Журнал обработки ПДн (ст.18.1 152-ФЗ)
|
||||
|
||||
- [ ] **`pd_processing_log`** (schema.sql:2449): таблица журнала. RLS включён
|
||||
(schema.sql:2806), политика `tenant_isolation` (schema.sql:2846).
|
||||
Проверить: `subject_type`, `action`, `purpose` заполняются при
|
||||
ключевых операциях (просмотр сделки, экспорт, удаление).
|
||||
- [ ] **Триггер экспорта** `trg_report_jobs_export_log` (schema.sql:3096): AFTER
|
||||
INSERT на `report_jobs` → INSERT `pd_processing_log` с `action='exported'`.
|
||||
Закрывает требование ст.18 (учёт трансграничной передачи / выгрузки).
|
||||
- [ ] **Append-only hash chain** (schema.sql:63): `log_hash BYTEA` + триггеры
|
||||
`BEFORE UPDATE/DELETE` с `RAISE EXCEPTION`. Проверить: цепочка целостна.
|
||||
SQL: `SELECT id, log_hash IS NULL AS broken FROM pd_processing_log ORDER BY id DESC LIMIT 10;`
|
||||
|
||||
### З5. Обращения субъектов ПДн (ст.14 152-ФЗ)
|
||||
|
||||
- [ ] **`pd_subject_requests`** (schema.sql:2491): таблица обращений. Поля:
|
||||
`subject_email`, `subject_phone`, `subject_full_name`, `request_type`
|
||||
(`access`/`rectification`/`deletion`/`objection`), `deadline_at` (30 дней),
|
||||
`processing_restricted`.
|
||||
- [ ] **Триггер дедлайна** `trg_pd_subject_requests_deadline` (schema.sql:3165):
|
||||
функция `set_pd_subject_request_deadline()` заполняет `deadline_at =
|
||||
received_at + INTERVAL '30 days'` при INSERT/UPDATE.
|
||||
Проверить: `SELECT COUNT(*) FROM pd_subject_requests WHERE deadline_at IS NULL;`
|
||||
— должно быть 0.
|
||||
- [ ] **`processing_restricted`** (schema.sql:2514, ст.21 ч.5): при `TRUE`
|
||||
`ProcessingRestrictedException` блокирует операции с ПДн субъекта.
|
||||
Проверить в коде: `ProcessingRestrictionGuard` вызывается в сервисах
|
||||
перед mutable-операциями с `deals`/`users`.
|
||||
- [ ] Индекс (schema.sql:2519): `idx_pd_requests_restricted` — эффективный поиск
|
||||
активных ограничений. Проверить: он используется в `ProcessingRestrictionGuard`.
|
||||
|
||||
### З6. Уведомление РКН и реестр обработки (ст.22 152-ФЗ)
|
||||
|
||||
- [ ] **Проверить вручную:** подана ли заявка оператора в реестр Роскомнадзора
|
||||
на сайте pd.rkn.gov.ru? Это организационная мера, вне кода.
|
||||
- [ ] **Проверить вручную:** составлен ли внутренний реестр обработки ПДн
|
||||
(перечень категорий субъектов, целей, сроков, мер защиты)?
|
||||
Требование ст.22.1 ФЗ-152.
|
||||
- [ ] **`incidents_log`** (schema.sql:2535): при утечке ПДн — поле
|
||||
`related_pd_subject_request_ids BIGINT[]`. Проверить: есть ли внутренняя
|
||||
процедура уведомления РКН в течение 24 ч (ст.21.1, с 01.03.2023)?
|
||||
|
||||
### З7. Передача ПДн третьим лицам
|
||||
|
||||
- [ ] **Поставщик crm.bp-gr.ru**: получает запросы с телефонами лидов обратно
|
||||
при синхронизации статусов (`supplier_sync_log`). Проверить наличие договора
|
||||
на обработку ПДн по поручению (ст.6 ч.3 152-ФЗ).
|
||||
**Проверить вручную** — юридический документ.
|
||||
- [ ] **Unisender Go** (email-рассылки с именами пользователей):
|
||||
**Проверить вручную** — договор поручения на обработку ПДн.
|
||||
- [ ] **JivoSite** (helpdesk): передаются ли туда email/ФИО клиентов?
|
||||
**Проверить вручную**.
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
name: process-analysis
|
||||
description: Анализ и оптимизация существующего бизнес-процесса — process discovery (реконструкция as-is процесса из кода Laravel и audit-логов), поиск узких мест, трассировка требование→процесс, метрики и KPI процесса. Триггеры — «проанализируй процесс», «где узкое место», «process discovery», «как устроен процесс X», «метрики процесса», «оптимизируй процесс». Раздел C10 карты «Бизнес-процессы (общее)».
|
||||
---
|
||||
|
||||
# Process Analysis
|
||||
|
||||
Разбирает **существующий** бизнес-процесс: восстанавливает фактическую модель,
|
||||
находит узкие места, считает метрики. Парный скил к `process-modeling` — тот
|
||||
проектирует to-be, этот вскрывает as-is.
|
||||
|
||||
## Четыре режима
|
||||
|
||||
### 1. Process discovery — реконструкция as-is
|
||||
|
||||
Восстановить фактический процесс из артефактов кода (карта источников —
|
||||
`references/discovery.md`): маршруты + контроллеры (точки входа), джобы/события
|
||||
(асинхронные шаги), enum статусов + переходы (state-машина), audit-таблицы
|
||||
(фактические следы), cron/scheduler (периодические шаги). Итог — модель,
|
||||
которую можно передать `process-modeling` для отрисовки.
|
||||
|
||||
### 2. Bottleneck — поиск узких мест
|
||||
|
||||
Паттерны: ручной шаг между авто-шагами; шаг с ожиданием внешней системы; точка
|
||||
сериализации (advisory-lock, `lockForUpdate`); N+1 внутри шага; ретраи/таймауты;
|
||||
шаг с наибольшей долей исключений.
|
||||
Граница: это **процессные** узкие места. Runtime/код-производительность —
|
||||
`perf-analyzer` / скил `analysis:bottleneck-detect` (PA1).
|
||||
|
||||
### 3. Трассировка требование→процесс
|
||||
|
||||
Связать пункт ТЗ / `Открытые_вопросы` → шаги процесса → код (file:line) →
|
||||
тесты. Выявить шаги без требования (скрытая логика) и требования без
|
||||
реализации.
|
||||
|
||||
### 4. Метрики процесса
|
||||
|
||||
Определить KPI: throughput, cycle time, конверсия между статусами, доля
|
||||
исключений, объём ручного труда. Числа берутся из БД через `Boost`, не
|
||||
выдумываются.
|
||||
Граница: продуктовые метрики — плагин `product-management` (`/metrics-review`).
|
||||
|
||||
## Рабочий процесс
|
||||
|
||||
1. Определить режим (1-4) по запросу.
|
||||
2. Собрать факты из кода / БД / логов — никаких допущений без пинов (file:line).
|
||||
3. Выдать находки: модель / список узких мест / матрицу трассировки / таблицу
|
||||
метрик.
|
||||
4. Рекомендации направить в `process-modeling` (to-be) или в задачи. Этот скил
|
||||
код не правит.
|
||||
|
||||
## Границы
|
||||
|
||||
- **Проектирование to-be модели** — скил `process-modeling`.
|
||||
- **Runtime / код-производительность** — `perf-analyzer`,
|
||||
`analysis:bottleneck-detect` (PA1).
|
||||
- **Продуктовые метрики** — плагин `product-management`.
|
||||
- **Документ / change-request процесса** — плагин `operations`.
|
||||
- **Интервью заказчика про будущую фичу / ориентация по проекту** — скил
|
||||
`discovery-interview`. Тот вскрывает проблему до решения через интервью человека
|
||||
(режим FEATURE) и синтезирует мета-слой проекта (режим SYSTEM); этот скил — про
|
||||
вскрытие as-is процесса из app-кода. «process discovery», «как устроен процесс X»,
|
||||
«где узкое место» — сюда; «проведи discovery interview», «сориентируй по проекту» —
|
||||
в `discovery-interview`.
|
||||
- **Генерик-методология оптимизации процесса** — скил `process-optimization`
|
||||
плагина `operations`. Этот скил — про code-grounded discovery конкретного
|
||||
процесса Лидерры (вскрытие as-is), не про общую методологию и не про
|
||||
проектирование to-be.
|
||||
@@ -1,32 +0,0 @@
|
||||
# Process discovery — карта источников as-is процесса в Лидерре
|
||||
|
||||
Где в коде Лидерры лежат факты о фактическом бизнес-процессе.
|
||||
|
||||
## Источники
|
||||
|
||||
| Артефакт процесса | Где искать |
|
||||
|---|---|
|
||||
| Точки входа процесса | `app/routes/*.php` + `app/app/Http/Controllers/**` |
|
||||
| Синхронные шаги | методы контроллеров + `app/app/Services/**` |
|
||||
| Асинхронные шаги | `app/app/Jobs/**`, `app/app/Events/**` + listeners |
|
||||
| State-машина | enum/константы статусов + `db/schema.sql` (воронка — 14 статусов) |
|
||||
| Фактические следы выполнения | `audit_*` таблицы, `audit_chain_hash` (событийный лог) |
|
||||
| Периодические шаги | `app/app/Console/**` + scheduler (`partitions:create-months` и пр.) |
|
||||
| Бизнес-правила в шагах | `calc_lead_score` (SQL), `PricingTierResolver`, `LedgerService` |
|
||||
|
||||
## Метод
|
||||
|
||||
1. От **точки входа** (route → controller) пройти по вызовам до терминального
|
||||
состояния.
|
||||
2. Каждый `dispatch()` / событие — асинхронная ветка; проследить listener/job.
|
||||
3. Переход статуса = ребро state-машины; собрать все переходы в автомат.
|
||||
4. Свериться с **audit-логом**: фактический порядок событий в `audit_*` может
|
||||
расходиться с «проектным» — расхождение само по себе находка.
|
||||
5. Зафиксировать каждый шаг пином `file:line`; без пина — это допущение, не факт.
|
||||
|
||||
## Антипаттерны при discovery
|
||||
|
||||
- Принять «happy path» за весь процесс — исключения (catch, failed jobs,
|
||||
таймауты) тоже шаги.
|
||||
- Пропустить cron-шаги — они не видны из route-графа.
|
||||
- Доверять имени метода вместо его тела.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
name: process-modeling
|
||||
description: Моделирование бизнес-процесса — BPMN 2.0 (пулы, дорожки, задачи, гейтвеи, события), карты процессов, customer-journey / value-stream, RACI-матрицы, state-машины. Триггеры — «смоделируй процесс», «нарисуй BPMN», «карта процесса», «swimlane / дорожки», «customer journey», «RACI», проектирование state-машины (воронка сделок, цепочка джобов). Раздел C10 карты «Бизнес-процессы (общее)».
|
||||
---
|
||||
|
||||
# Process Modeling
|
||||
|
||||
Превращает словесное описание бизнес-процесса в формальную модель. Скил даёт
|
||||
**нотацию и методологию** — рендер диаграмм делегируется скилу `mermaid`
|
||||
(process-modeling не рендерит сам — конфликт-граница OPS1/BPMN1: mermaid
|
||||
остаётся рендер-SoT).
|
||||
|
||||
## Когда какой артефакт
|
||||
|
||||
| Нужно | Артефакт |
|
||||
|---|---|
|
||||
| Кто-что-в-каком-порядке делает, с ветвлениями | BPMN 2.0 / swimlane |
|
||||
| Сквозной поток end-to-end крупными блоками | Карта процесса (flowchart) |
|
||||
| Опыт клиента/лида по этапам + точки боли | Customer-journey map |
|
||||
| Поток создания ценности + потери и ожидания | Value-stream map |
|
||||
| Распределение ответственности по шагам | RACI-матрица |
|
||||
| Конечный автомат (статусы + переходы) | State-диаграмма |
|
||||
|
||||
## Рабочий процесс
|
||||
|
||||
1. **Собрать процесс** — уточнить: триггер (что запускает), участники (роли),
|
||||
шаги по порядку, ветвления и условия, итог, исключения. Неясное — один
|
||||
вопрос за раз.
|
||||
2. **Выбрать артефакт** по таблице выше.
|
||||
3. **Построить модель** в нотации (BPMN — см. `references/bpmn.md`).
|
||||
4. **Отрендерить** — передать исходник скилу `mermaid`.
|
||||
5. **Свериться** — модель не должна противоречить ТЗ / `db/schema.sql` /
|
||||
`Открытые_вопросы`. Процесс вне ТЗ И не в реестре открытых вопросов —
|
||||
hard-стоп (Pravila §7): не моделировать молча, поднять вопрос.
|
||||
|
||||
## BPMN 2.0 — ядро
|
||||
|
||||
Полная нотация и маппинг на mermaid — `references/bpmn.md`. Кратко:
|
||||
|
||||
- **Pool** — организация/система; **Lane** — роль внутри pool.
|
||||
- **Task** — атомарное действие; **Sub-process** — свёрнутый под-поток.
|
||||
- **Gateway** — ветвление: exclusive (XOR — один путь), parallel (AND — все
|
||||
пути), inclusive (OR — один и более).
|
||||
- **Event** — start / intermediate / end; типы: timer, message, error.
|
||||
- **Sequence flow** — порядок внутри pool; **Message flow** — между pool'ами.
|
||||
|
||||
## Границы
|
||||
|
||||
- **Рендер диаграмм** — скил `mermaid` (C10 OPS1/BPMN1). Этот скил исходник не
|
||||
рисует — отдаёт его mermaid.
|
||||
- **DDD-границы доменных процессов** — скил `architecture-patterns` (bounded
|
||||
context = граница бизнес-процесса).
|
||||
- **Документ процесса, change-request, оптимизация** — плагин `operations`
|
||||
(скилы `process-doc`, `change-request`, `process-optimization`).
|
||||
- **Анализ as-is процесса** (discovery, узкие места) — скил `process-analysis`.
|
||||
- Этот скил — про проектирование **to-be модели**, не про вскрытие as-is.
|
||||
@@ -1,56 +0,0 @@
|
||||
# BPMN 2.0 — справочник нотации и рендер в mermaid
|
||||
|
||||
mermaid не имеет нативного BPMN-рендера. BPMN-модель выражается через mermaid
|
||||
`flowchart` (swimlane через `subgraph` = дорожки) или `stateDiagram-v2`.
|
||||
|
||||
## Элементы BPMN → mermaid
|
||||
|
||||
| BPMN | Смысл | mermaid-выражение |
|
||||
|---|---|---|
|
||||
| Pool / Lane | организация / роль | `subgraph Роль ... end` |
|
||||
| Task | действие | прямоугольник `id[Текст]` |
|
||||
| Sub-process | свёрнутый поток | `id[[Текст]]` |
|
||||
| Start event | старт | `id((Старт))` |
|
||||
| End event | конец | `id((Конец))` |
|
||||
| Exclusive gateway (XOR) | один путь | ромб `id{Условие?}` + подписи на рёбрах |
|
||||
| Parallel gateway (AND) | все пути | ромб `id{И}` с несколькими исходящими |
|
||||
| Sequence flow | порядок | `-->` |
|
||||
| Message flow | между pool | `-.->` |
|
||||
|
||||
## Шаблон swimlane
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph Менеджер
|
||||
A((Старт)) --> B[Принять лид]
|
||||
B --> C{Лид валиден?}
|
||||
end
|
||||
subgraph Система
|
||||
C -->|да| D[Создать сделку]
|
||||
C -->|нет| E((Отклонён))
|
||||
D --> F((Сделка создана))
|
||||
end
|
||||
```
|
||||
|
||||
## State-машина
|
||||
|
||||
Для конечных автоматов (воронка сделок — 14 статусов из `db/schema.sql`)
|
||||
использовать `stateDiagram-v2`:
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> new
|
||||
new --> in_progress
|
||||
in_progress --> won
|
||||
in_progress --> lost
|
||||
won --> [*]
|
||||
lost --> [*]
|
||||
```
|
||||
|
||||
Статус-слаги — из `db/schema.sql` (источник истины воронки), не выдумывать.
|
||||
|
||||
## Правила
|
||||
|
||||
- Один gateway — один вопрос; каждое исходящее ребро подписано условием.
|
||||
- Каждый путь оканчивается end-событием (нет «висящих» задач).
|
||||
- Исключения (timer/error) моделировать явно, не прятать в «happy path».
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
name: q-item-add
|
||||
description: |
|
||||
Add a new open question (Q-item) to the registry docs/Открытые_вопросы_v8_3.md.
|
||||
Use ONLY when customer explicitly requests adding a new business/CTO/legal/design/devops/OPEN
|
||||
question to the registry. Walks through 6-step workflow: detect section, find next number,
|
||||
insert entry, update §0 counters, bump header/footer/changelog version, sync §0 row in CLAUDE.md.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Q-item-add — добавить новый Q-item в реестр Открытых_вопросов
|
||||
|
||||
## Когда использовать
|
||||
|
||||
ТОЛЬКО при явном запросе заказчика добавить новый вопрос. Pravila §2.2 — закрытие/добавление вопроса требует явного указания заказчика.
|
||||
|
||||
Invoke via `/q-item-add <Биз|CTO|Ю|Диз|DO|OPEN> "<question text>"`.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Detect section.** Открыть `docs/Открытые_вопросы_v8_3.md`, найти секцию по prefix:
|
||||
- `Биз-*` → section `## 13` (Бизнес).
|
||||
- `CTO-*` → section `## 3` (CTO/инженерные).
|
||||
- `Ю-*` → section `## 4` (Юридические).
|
||||
- `Диз-*` → section `## 5` (Дизайн).
|
||||
- `DO-*` → section `## 6` (DevOps/инфраструктура).
|
||||
- `OPEN-*` → section `## 7` (Прочие открытые).
|
||||
|
||||
2. **Find next number.** Grep последний номер в секции (e.g., max `Биз-31` → new = `Биз-32`).
|
||||
|
||||
```bash
|
||||
grep -oP '<prefix>-\d+' docs/Открытые_вопросы_v8_3.md | sort -t- -k2 -n | tail -1
|
||||
```
|
||||
|
||||
3. **Insert entry.** Добавить строку формата:
|
||||
|
||||
```markdown
|
||||
**<prefix>-N ⏸** от 2026-MM-DD: <question text>
|
||||
```
|
||||
|
||||
4. **Update §0 «Сводка».** Increment счётчик ⏸ для соответствующего prefix. Шапка `## 0` содержит таблицу типа `Биз 24 ✅ / 7 ⏸` — bump до `8 ⏸`. **Также** «Итого X / Y ✅ / Z ⏸» — bump соответствующие.
|
||||
|
||||
5. **Bump versions.** Header (`v1.83 от 13.05.2026 (day +1)` → `v1.84 от 13.05.2026 (day +1)`), footer (last line same), добавить запись в `## 9. История версий`.
|
||||
|
||||
6. **Sync CLAUDE.md.** В `CLAUDE.md` §0 row «Открытые вопросы» bump `v1.83+` → `v1.84+`. Помним: CLAUDE.md правится ТОЛЬКО через `/claude-md-management:revise-claude-md` (§5 п.10) — финальный шаг делегируем заказчику или этому skill'у через sub-invocation.
|
||||
|
||||
## Validation
|
||||
|
||||
После save:
|
||||
|
||||
```bash
|
||||
./bin/lychee.exe --config .lychee.toml docs/Открытые_вопросы_v8_3.md 2>&1 | tail -3
|
||||
```
|
||||
|
||||
Expected: 0 broken links.
|
||||
|
||||
Counter arithmetic check: sum of ✅ + ⏸ + 🟦 per prefix = total per prefix.
|
||||
|
||||
## Не использовать когда
|
||||
|
||||
- Заказчик говорит «закрываем X» — это closure (replace ⏸ → ✅ + дата), не addition. Skip skill, do targeted Edit.
|
||||
- Item уже существует с тем же текстом — duplicate; уточнить у заказчика или обновить existing.
|
||||
- Заказчик не давал явного «добавь X в реестр» — Pravila §2.2 запрещает proactive добавление.
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
name: regression
|
||||
description: |
|
||||
Run the project regression sweep and report a canonical status line + GREEN/RED/RED-INCOMPLETE verdict.
|
||||
Two tiers: `quick` (lint/format/type-check — seconds) and `full` (everything incl.
|
||||
Pest --parallel, Larastan, Vitest, Vite build, lychee, gitleaks — minutes).
|
||||
Claude auto-runs only `quick` (e.g. during verification-before-completion);
|
||||
`full` runs only on explicit `/regression full` or with user confirmation.
|
||||
---
|
||||
|
||||
# Regression — канонический регрессионный свод
|
||||
|
||||
## Когда использовать
|
||||
|
||||
Перед закрытием задачи/спринта (`full`) или для быстрого фидбэка по ходу работы
|
||||
(`quick`). Скилл инкапсулирует ~12 команд свода, разбросанных по `package.json`,
|
||||
`app/package.json`, `app/composer.json` и `lefthook.yml`, в один вызов с
|
||||
детерминированной канонической строкой и машинным вердиктом.
|
||||
|
||||
Invoke via `/regression [quick|full]` (без аргумента → `full`).
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Определить уровень из аргумента: `quick`, `full`, либо `full` по умолчанию.
|
||||
2. Запустить через Bash из корня репозитория:
|
||||
|
||||
```bash
|
||||
node .claude/skills/regression/run.mjs <tier>
|
||||
```
|
||||
|
||||
3. Показать пользователю полный вывод скрипта (таблица + каноническая строка +
|
||||
вердикт + вывод упавших проверок).
|
||||
4. Интерпретировать вердикт:
|
||||
- `GREEN` — свод чист, exit-код 0.
|
||||
- `RED` — перечислены упавшие проверки, exit-код 1; полный вывод каждой —
|
||||
после вердикта.
|
||||
- `RED-INCOMPLETE` — проверка не прогналась (нет бинаря), exit-код 1; свод
|
||||
неполон, зелёным признать нельзя. Если одновременно есть упавшие проверки,
|
||||
они тоже перечислены в строке вердикта.
|
||||
|
||||
## Уровни
|
||||
|
||||
- **`quick`** (6 проверок, секунды): Pint, ESLint, Prettier, vue-tsc,
|
||||
markdownlint, cspell.
|
||||
- **`full`** (12 проверок, минуты): всё из `quick` + Larastan, Pest `--parallel`,
|
||||
Vitest, Vite build, lychee, gitleaks.
|
||||
|
||||
## Правила инвокации (self-restraint)
|
||||
|
||||
- Claude **авто-запускает только `quick`** — в том числе в рамках
|
||||
`superpowers:verification-before-completion` перед claim «готово» / «passed» /
|
||||
«closed».
|
||||
- `full` Claude **сам не запускает** — только по явному `/regression full` от
|
||||
пользователя ИЛИ запросив подтверждение («запускаю полный свод, ~5–10 мин — ок?»).
|
||||
- Скилл **не правит `CLAUDE.md`** — он только печатает каноническую строку в
|
||||
stdout; вставка строки в `CLAUDE.md` — отдельно, через канал
|
||||
`claude-md-management` (`CLAUDE.md` §5 п.10).
|
||||
|
||||
## Caveats
|
||||
|
||||
- **Pest `--parallel` flake (квирки 72/73/77).** Если Pest показал 1–3 ошибки,
|
||||
похожие на Redis-race / cumulative-state / unique-key-collision, — перепрогнать
|
||||
`full` один раз ИЛИ свериться с агентом `pest-parallel-debugger` до объявления
|
||||
реального RED.
|
||||
- **ruflo daemon (квирк 93).** Перед baseline-критичным `full` рассмотреть
|
||||
`pm2 stop ruflo-daemon` — worker-jitter усиливает Pest-flake.
|
||||
- gitleaks и lychee: на Windows берутся из `bin\*.exe`, на Linux/Mac CI — из
|
||||
`PATH`. Отсутствие бинаря → `[⚠] SKIPPED` + вердикт `RED-INCOMPLETE`.
|
||||
|
||||
## Не использовать когда
|
||||
|
||||
- Нужна одна конкретная проверка — запусти её npm/composer-скрипт напрямую
|
||||
(быстрее, чем весь свод).
|
||||
- Pa11y и Semgrep SAST — это CI-tier, в свод намеренно не входят (см. дизайн-спек
|
||||
`docs/superpowers/specs/2026-05-16-regression-skill-design.md` §5).
|
||||
@@ -1,258 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
// .claude/skills/regression/run.mjs
|
||||
// Regression sweep orchestrator for the /regression skill.
|
||||
// Design: docs/superpowers/specs/2026-05-16-regression-skill-design.md
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { existsSync } from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath, pathToFileURL } from 'node:url';
|
||||
import process from 'node:process';
|
||||
|
||||
// ── pure: platform binary resolution ───────────────────────────────
|
||||
export function resolveBinary(name, platform = process.platform) {
|
||||
return platform === 'win32' ? `bin\\${name}.exe` : name;
|
||||
}
|
||||
|
||||
// ── pure: output header line ───────────────────────────────────────
|
||||
export function buildHeader(tier) {
|
||||
const head = `─ /regression ${tier} `;
|
||||
return head + '─'.repeat(Math.max(3, 48 - head.length));
|
||||
}
|
||||
|
||||
// ── pure: exit-code token ──────────────────────────────────────────
|
||||
export function parseExit(label, code) {
|
||||
return `${label} ${code}`;
|
||||
}
|
||||
|
||||
// ── pure: test-count parsers ───────────────────────────────────────
|
||||
export function parsePest(stdout) {
|
||||
// pest --parallel emits a single JSON line: {"tool":"pest","result":...,"tests":N,"passed":N,"skipped":N,...}
|
||||
const jsonMatch = stdout.match(/\{"tool"\s*:\s*"pest"[^}]+\}/);
|
||||
if (jsonMatch) {
|
||||
try {
|
||||
const j = JSON.parse(jsonMatch[0]);
|
||||
const passed = Number(j.passed ?? 0);
|
||||
const skipped = Number(j.skipped ?? 0);
|
||||
const total = Number(j.tests ?? passed + skipped);
|
||||
const failed = total - passed - skipped;
|
||||
return `Pest ${total}/${passed}/${skipped}sk/${Math.max(0, failed)}`;
|
||||
} catch { /* fall through to regex */ }
|
||||
}
|
||||
const passed = Number(stdout.match(/(\d+)\s+passed/)?.[1] ?? 0);
|
||||
const skipped = Number(stdout.match(/(\d+)\s+skipped/)?.[1] ?? 0);
|
||||
const failed = Number(stdout.match(/(\d+)\s+failed/)?.[1] ?? 0);
|
||||
return `Pest ${passed + skipped + failed}/${passed}/${skipped}sk/${failed}`;
|
||||
}
|
||||
|
||||
export function parseVitest(stdout) {
|
||||
const filesLine = stdout.match(/^.*Test Files.+$/m)?.[0] ?? '';
|
||||
const files = Number(filesLine.match(/(\d+)\s+passed/)?.[1] ?? 0);
|
||||
const line = stdout.match(/^\s*Tests\s+.+$/m)?.[0] ?? '';
|
||||
const passed = Number(line.match(/(\d+)\s+passed/)?.[1] ?? 0);
|
||||
const skipped = Number(line.match(/(\d+)\s+skipped/)?.[1] ?? 0);
|
||||
const failed = Number(line.match(/(\d+)\s+failed/)?.[1] ?? 0);
|
||||
return `Vitest ${files}f/${passed}/${skipped}sk/${failed}`;
|
||||
}
|
||||
|
||||
// ── pure: content parsers ──────────────────────────────────────────
|
||||
export function parseViteBuild(stdout) {
|
||||
const m = stdout.match(/built in ([\d.]+)\s*s/i);
|
||||
return `Vite build ${m ? m[1] : '?'}s`;
|
||||
}
|
||||
|
||||
export function parseLarastan(stdout) {
|
||||
const m = stdout.match(/Found (\d+) error/i);
|
||||
return `Larastan ${m ? m[1] : 0}`;
|
||||
}
|
||||
|
||||
export function parseGitleaks(stdout, code) {
|
||||
const commits = stdout.match(/(\d+)\s+commits?\s+scanned/i)?.[1] ?? '?';
|
||||
const leaks = code === 0
|
||||
? '0'
|
||||
: (stdout.match(/(\d+)\s+leaks?\s+found/i)?.[1]
|
||||
?? stdout.match(/leaks?\s+found:?\s*(\d+)/i)?.[1]
|
||||
?? '≥1');
|
||||
return `gitleaks ${leaks}/${commits}`;
|
||||
}
|
||||
|
||||
export function parseLychee(stdout) {
|
||||
const ok = stdout.match(/(\d+)\s+OK/)?.[1] ?? '?';
|
||||
const errors = stdout.match(/(\d+)\s+Errors?/i)?.[1] ?? '0';
|
||||
return `lychee ${ok}/${errors}`;
|
||||
}
|
||||
|
||||
// ── pure: verdict ──────────────────────────────────────────────────
|
||||
export function computeVerdict(results) {
|
||||
const skipped = results.filter((r) => r.skipped).map((r) => r.label);
|
||||
const failed = results
|
||||
.filter((r) => !r.skipped && r.code !== 0)
|
||||
.map((r) => r.label);
|
||||
if (skipped.length) return { verdict: 'RED-INCOMPLETE', exitCode: 1, failed, skipped };
|
||||
if (failed.length) return { verdict: 'RED', exitCode: 1, failed, skipped };
|
||||
return { verdict: 'GREEN', exitCode: 0, failed, skipped };
|
||||
}
|
||||
|
||||
// ── pure: output formatting ────────────────────────────────────────
|
||||
export function buildCanonicalLine(results) {
|
||||
return results.map((r) => r.token).join(' / ');
|
||||
}
|
||||
|
||||
export function formatRow(r) {
|
||||
const mark = r.skipped ? '⚠' : r.code === 0 ? '✅' : '❌';
|
||||
const label = r.label.padEnd(14);
|
||||
const status = r.skipped
|
||||
? 'SKIPPED — binary not found'
|
||||
: `${r.code} ${(r.ms / 1000).toFixed(1)}s`;
|
||||
return `[${mark}] ${label}${status}`;
|
||||
}
|
||||
|
||||
export function verdictLine(v, total) {
|
||||
if (v.verdict === 'GREEN') {
|
||||
return `🟢 GREEN — все ${total} проверок passed`;
|
||||
}
|
||||
if (v.verdict === 'RED-INCOMPLETE') {
|
||||
const tail = v.failed.length ? `; провал: ${v.failed.join(', ')}` : '';
|
||||
return `🟠 RED-INCOMPLETE — не прогналось: ${v.skipped.join(', ')}${tail}`;
|
||||
}
|
||||
return `🔴 RED — ${v.failed.length}/${total} failed: ${v.failed.join(', ')}`;
|
||||
}
|
||||
|
||||
// ── data: checks registry ──────────────────────────────────────────
|
||||
// Script-based checks carry `cmd`; binary-based checks carry `bin` + `argv`.
|
||||
// `parse(combinedOutput, exitCode)` → canonical token. `cwd`: '.' = repo root,
|
||||
// 'app' = the Laravel app. Execution order: quick checks first, then heavy.
|
||||
export const CHECKS = [
|
||||
{
|
||||
id: 'pint', label: 'Pint', tiers: ['quick', 'full'], cwd: 'app',
|
||||
cmd: 'composer pint:test', parse: (_o, c) => parseExit('Pint', c),
|
||||
},
|
||||
{
|
||||
id: 'eslint', label: 'ESLint', tiers: ['quick', 'full'], cwd: 'app',
|
||||
cmd: 'npm run lint:vue', parse: (_o, c) => parseExit('ESLint', c),
|
||||
},
|
||||
{
|
||||
id: 'prettier', label: 'Prettier', tiers: ['quick', 'full'], cwd: 'app',
|
||||
cmd: 'npm run format:check', parse: (_o, c) => parseExit('Prettier', c),
|
||||
},
|
||||
{
|
||||
id: 'vue-tsc', label: 'vue-tsc', tiers: ['quick', 'full'], cwd: 'app',
|
||||
cmd: 'npm run type-check', parse: (_o, c) => parseExit('vue-tsc', c),
|
||||
},
|
||||
{
|
||||
id: 'markdownlint', label: 'markdownlint', tiers: ['quick', 'full'], cwd: '.',
|
||||
cmd: 'npm run lint:md', parse: (_o, c) => parseExit('markdownlint', c),
|
||||
},
|
||||
{
|
||||
id: 'cspell', label: 'cspell', tiers: ['quick', 'full'], cwd: '.',
|
||||
cmd: 'npm run spell', parse: (_o, c) => parseExit('cspell', c),
|
||||
},
|
||||
{
|
||||
id: 'larastan', label: 'Larastan', tiers: ['full'], cwd: 'app',
|
||||
cmd: 'composer stan', parse: (o) => parseLarastan(o),
|
||||
},
|
||||
{
|
||||
id: 'pest', label: 'Pest', tiers: ['full'], cwd: 'app',
|
||||
cmd: 'composer test:parallel', parse: (o) => parsePest(o),
|
||||
},
|
||||
{
|
||||
id: 'vitest', label: 'Vitest', tiers: ['full'], cwd: 'app',
|
||||
cmd: 'npm run test:vue', parse: (o) => parseVitest(o),
|
||||
},
|
||||
{
|
||||
id: 'vite-build', label: 'Vite build', tiers: ['full'], cwd: 'app',
|
||||
cmd: 'npm run build', parse: (o) => parseViteBuild(o),
|
||||
},
|
||||
{
|
||||
id: 'lychee', label: 'lychee', tiers: ['full'], cwd: '.',
|
||||
bin: 'lychee',
|
||||
argv: ['--config', '.lychee.toml', 'docs/**/*.md', 'db/**/*.md', '*.md'],
|
||||
parse: (o) => parseLychee(o),
|
||||
},
|
||||
{
|
||||
id: 'gitleaks', label: 'gitleaks', tiers: ['full'], cwd: '.',
|
||||
bin: 'gitleaks',
|
||||
argv: ['detect', '--source', '.', '--no-banner', '--config', '.gitleaks.toml', '--redact'],
|
||||
parse: (o, c) => parseGitleaks(o, c),
|
||||
},
|
||||
];
|
||||
|
||||
// ── I/O: run one check ─────────────────────────────────────────────
|
||||
function runCheck(check, repoRoot) {
|
||||
const cwd = check.cwd === '.' ? repoRoot : path.join(repoRoot, check.cwd);
|
||||
const start = Date.now();
|
||||
const skippedResult = (reason) => ({
|
||||
id: check.id, label: check.label, skipped: true, code: null,
|
||||
ms: Date.now() - start, token: `${check.label} SKIPPED`, stdout: '', stderr: reason,
|
||||
});
|
||||
|
||||
let command;
|
||||
if (check.bin) {
|
||||
const bin = resolveBinary(check.bin);
|
||||
// bin/ executables: existsSync pre-check on Windows (the project ships
|
||||
// bin\gitleaks.exe / bin\lychee.exe; on POSIX they come from PATH).
|
||||
if (process.platform === 'win32' && !existsSync(path.join(repoRoot, bin))) {
|
||||
return skippedResult(`${bin} not found`);
|
||||
}
|
||||
command = [bin, ...check.argv].join(' ');
|
||||
} else {
|
||||
command = check.cmd;
|
||||
}
|
||||
|
||||
const res = spawnSync(command, {
|
||||
cwd, shell: true, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
|
||||
});
|
||||
const ms = Date.now() - start;
|
||||
// ENOENT (POSIX missing binary), POSIX shell exit 127 ("command not found"),
|
||||
// or the Windows cmd.exe "is not recognized" message → SKIPPED.
|
||||
const notFound = (res.error && res.error.code === 'ENOENT')
|
||||
|| res.status === 127
|
||||
|| /is not recognized as an internal or external command/i.test(res.stderr ?? '');
|
||||
if (notFound) {
|
||||
return skippedResult(`command not found: ${command}`);
|
||||
}
|
||||
const stdout = res.stdout ?? '';
|
||||
const stderr = res.stderr ?? '';
|
||||
const code = res.status ?? 1;
|
||||
const token = check.parse(`${stdout}\n${stderr}`, code);
|
||||
return { id: check.id, label: check.label, skipped: false, code, ms, token, stdout, stderr };
|
||||
}
|
||||
|
||||
// ── orchestrator ───────────────────────────────────────────────────
|
||||
export function main(argv) {
|
||||
const tier = argv[0] ?? 'full';
|
||||
if (tier !== 'quick' && tier !== 'full') {
|
||||
process.stderr.write(
|
||||
`regression: unknown argument "${tier}". Usage: run.mjs [quick|full]\n`,
|
||||
);
|
||||
process.exitCode = 2;
|
||||
return;
|
||||
}
|
||||
const repoRoot = fileURLToPath(new URL('../../../', import.meta.url));
|
||||
const checks = CHECKS.filter((c) => c.tiers.includes(tier));
|
||||
|
||||
process.stdout.write(`${buildHeader(tier)}\n`);
|
||||
const results = [];
|
||||
for (const check of checks) {
|
||||
const r = runCheck(check, repoRoot);
|
||||
results.push(r);
|
||||
process.stdout.write(`${formatRow(r)}\n`);
|
||||
}
|
||||
process.stdout.write(`${'─'.repeat(48)}\n`);
|
||||
process.stdout.write(`Canonical: ${buildCanonicalLine(results)}\n`);
|
||||
|
||||
const v = computeVerdict(results);
|
||||
process.stdout.write(`VERDICT: ${verdictLine(v, results.length)}\n`);
|
||||
|
||||
// Full output of failed checks, so failures are visible with file:line.
|
||||
for (const r of results) {
|
||||
if (!r.skipped && r.code !== 0) {
|
||||
process.stdout.write(`\n── ${r.label} output ──\n${r.stdout}\n${r.stderr}\n`);
|
||||
}
|
||||
}
|
||||
process.exitCode = v.exitCode;
|
||||
}
|
||||
|
||||
// Run main only when executed directly (not when imported by run.test.mjs).
|
||||
if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
|
||||
main(process.argv.slice(2));
|
||||
}
|
||||
@@ -1,213 +0,0 @@
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import process from 'node:process';
|
||||
import {
|
||||
resolveBinary, buildHeader, parseExit,
|
||||
parsePest, parseVitest,
|
||||
parseViteBuild, parseLarastan, parseGitleaks, parseLychee,
|
||||
computeVerdict,
|
||||
buildCanonicalLine, formatRow, verdictLine,
|
||||
CHECKS,
|
||||
} from './run.mjs';
|
||||
|
||||
test('resolveBinary: win32 → bin\\<name>.exe', () => {
|
||||
assert.equal(resolveBinary('gitleaks', 'win32'), 'bin\\gitleaks.exe');
|
||||
});
|
||||
test('resolveBinary: non-win32 → bare name on PATH', () => {
|
||||
assert.equal(resolveBinary('lychee', 'linux'), 'lychee');
|
||||
assert.equal(resolveBinary('lychee', 'darwin'), 'lychee');
|
||||
});
|
||||
|
||||
test('buildHeader: starts with the tier banner', () => {
|
||||
assert.ok(buildHeader('quick').startsWith('─ /regression quick '));
|
||||
assert.ok(buildHeader('full').startsWith('─ /regression full '));
|
||||
});
|
||||
test('buildHeader: is padded with dashes', () => {
|
||||
assert.ok(buildHeader('full').length >= 30);
|
||||
});
|
||||
|
||||
test('parseExit: builds "<label> <code>" token', () => {
|
||||
assert.equal(parseExit('Pint', 0), 'Pint 0');
|
||||
assert.equal(parseExit('ESLint', 1), 'ESLint 1');
|
||||
});
|
||||
|
||||
test('parsePest: passed + skipped, no failures → total derived', () => {
|
||||
const out = ' Tests: 3 skipped, 739 passed (2104 assertions)\n Duration: 71.23s';
|
||||
assert.equal(parsePest(out), 'Pest 742/739/3sk/0');
|
||||
});
|
||||
test('parsePest: with failures', () => {
|
||||
const out = ' Tests: 2 failed, 1 skipped, 736 passed (2090 assertions)';
|
||||
assert.equal(parsePest(out), 'Pest 739/736/1sk/2');
|
||||
});
|
||||
test('parsePest: passed only → zeros for skipped/failed', () => {
|
||||
assert.equal(parsePest(' Tests: 19 passed (44 assertions)'), 'Pest 19/19/0sk/0');
|
||||
});
|
||||
test('parsePest: JSON format (pest --parallel) passed + skipped', () => {
|
||||
const out = '{"tool":"pest","result":"passed","tests":793,"passed":790,"assertions":2391,"duration_ms":32200,"skipped":3}';
|
||||
assert.equal(parsePest(out), 'Pest 793/790/3sk/0');
|
||||
});
|
||||
test('parsePest: JSON format with failures', () => {
|
||||
const out = '{"tool":"pest","result":"failed","tests":793,"passed":788,"assertions":2380,"duration_ms":31000,"skipped":3}';
|
||||
assert.equal(parsePest(out), 'Pest 793/788/3sk/2');
|
||||
});
|
||||
test('parsePest: JSON format no skipped', () => {
|
||||
const out = '{"tool":"pest","result":"passed","tests":19,"passed":19,"assertions":44,"duration_ms":1711}';
|
||||
assert.equal(parsePest(out), 'Pest 19/19/0sk/0');
|
||||
});
|
||||
|
||||
test('parseVitest: files + passed + skipped', () => {
|
||||
const out = ' Test Files 92 passed (92)\n Tests 774 passed | 3 skipped (777)\n Duration 12.6s';
|
||||
assert.equal(parseVitest(out), 'Vitest 92f/774/3sk/0');
|
||||
});
|
||||
test('parseVitest: with failures, does not confuse "Test Files" with "Tests"', () => {
|
||||
const out = ' Test Files 2 failed | 90 passed (92)\n Tests 5 failed | 769 passed (774)';
|
||||
assert.equal(parseVitest(out), 'Vitest 90f/769/0sk/5');
|
||||
});
|
||||
|
||||
test('parseViteBuild: extracts build time', () => {
|
||||
assert.equal(parseViteBuild('✓ 312 modules transformed.\n✓ built in 2.03s'), 'Vite build 2.03s');
|
||||
});
|
||||
test('parseViteBuild: no match → "?"', () => {
|
||||
assert.equal(parseViteBuild('build crashed'), 'Vite build ?s');
|
||||
});
|
||||
|
||||
test('parseLarastan: clean → 0', () => {
|
||||
assert.equal(parseLarastan(' [OK] No errors'), 'Larastan 0');
|
||||
});
|
||||
test('parseLarastan: counts errors', () => {
|
||||
assert.equal(parseLarastan(' [ERROR] Found 2 errors'), 'Larastan 2');
|
||||
});
|
||||
|
||||
test('parseGitleaks: clean → 0 leaks', () => {
|
||||
const out = 'INF 442 commits scanned.\nINF no leaks found';
|
||||
assert.equal(parseGitleaks(out, 0), 'gitleaks 0/442');
|
||||
});
|
||||
test('parseGitleaks: leaks found (non-zero exit)', () => {
|
||||
const out = 'INF 442 commits scanned.\nWRN 3 leaks found';
|
||||
assert.equal(parseGitleaks(out, 1), 'gitleaks 3/442');
|
||||
});
|
||||
|
||||
test('parseLychee: OK + errors', () => {
|
||||
const out = '🔍 325 Total (in 9s)\n✅ 325 OK\n🚫 0 Errors';
|
||||
assert.equal(parseLychee(out), 'lychee 325/0');
|
||||
});
|
||||
test('parseLychee: with broken links', () => {
|
||||
const out = '🔍 327 Total\n✅ 325 OK\n🚫 2 Errors';
|
||||
assert.equal(parseLychee(out), 'lychee 325/2');
|
||||
});
|
||||
|
||||
test('computeVerdict: all exit 0 → GREEN, exit code 0', () => {
|
||||
const v = computeVerdict([
|
||||
{ label: 'Pint', code: 0, skipped: false },
|
||||
{ label: 'ESLint', code: 0, skipped: false },
|
||||
]);
|
||||
assert.equal(v.verdict, 'GREEN');
|
||||
assert.equal(v.exitCode, 0);
|
||||
assert.deepEqual(v.failed, []);
|
||||
});
|
||||
test('computeVerdict: one non-zero exit → RED, exit code 1', () => {
|
||||
const v = computeVerdict([
|
||||
{ label: 'Pint', code: 0, skipped: false },
|
||||
{ label: 'Larastan', code: 1, skipped: false },
|
||||
]);
|
||||
assert.equal(v.verdict, 'RED');
|
||||
assert.equal(v.exitCode, 1);
|
||||
assert.deepEqual(v.failed, ['Larastan']);
|
||||
});
|
||||
test('computeVerdict: a skipped check → RED-INCOMPLETE', () => {
|
||||
const v = computeVerdict([
|
||||
{ label: 'Pint', code: 0, skipped: false },
|
||||
{ label: 'gitleaks', code: null, skipped: true },
|
||||
]);
|
||||
assert.equal(v.verdict, 'RED-INCOMPLETE');
|
||||
assert.equal(v.exitCode, 1);
|
||||
assert.deepEqual(v.skipped, ['gitleaks']);
|
||||
});
|
||||
test('computeVerdict: skipped takes precedence over a failure', () => {
|
||||
const v = computeVerdict([
|
||||
{ label: 'Larastan', code: 1, skipped: false },
|
||||
{ label: 'lychee', code: null, skipped: true },
|
||||
]);
|
||||
assert.equal(v.verdict, 'RED-INCOMPLETE');
|
||||
assert.deepEqual(v.failed, ['Larastan']);
|
||||
assert.deepEqual(v.skipped, ['lychee']);
|
||||
});
|
||||
|
||||
test('buildCanonicalLine: joins tokens in result order with " / "', () => {
|
||||
const results = [
|
||||
{ token: 'Pint 0' }, { token: 'ESLint 0' }, { token: 'Pest 742/739/3sk/0' },
|
||||
];
|
||||
assert.equal(buildCanonicalLine(results), 'Pint 0 / ESLint 0 / Pest 742/739/3sk/0');
|
||||
});
|
||||
|
||||
test('formatRow: passed check → ✅ mark, label, code, time', () => {
|
||||
const row = formatRow({ label: 'Pint', code: 0, ms: 1800, skipped: false });
|
||||
assert.ok(row.startsWith('[✅] Pint'));
|
||||
assert.ok(row.includes('1.8s'));
|
||||
});
|
||||
test('formatRow: failed check → ❌ mark', () => {
|
||||
assert.ok(formatRow({ label: 'Larastan', code: 1, ms: 8400, skipped: false }).startsWith('[❌] Larastan'));
|
||||
});
|
||||
test('formatRow: skipped check → ⚠ mark + SKIPPED', () => {
|
||||
const row = formatRow({ label: 'gitleaks', code: null, ms: 0, skipped: true });
|
||||
assert.ok(row.startsWith('[⚠] gitleaks'));
|
||||
assert.ok(row.includes('SKIPPED'));
|
||||
});
|
||||
|
||||
test('verdictLine: GREEN', () => {
|
||||
const line = verdictLine({ verdict: 'GREEN', failed: [], skipped: [] }, 12);
|
||||
assert.ok(line.includes('🟢 GREEN'));
|
||||
assert.ok(line.includes('12'));
|
||||
});
|
||||
test('verdictLine: RED lists failed checks', () => {
|
||||
const line = verdictLine({ verdict: 'RED', failed: ['Larastan'], skipped: [] }, 12);
|
||||
assert.ok(line.includes('🔴 RED'));
|
||||
assert.ok(line.includes('Larastan'));
|
||||
});
|
||||
test('verdictLine: RED-INCOMPLETE lists skipped checks', () => {
|
||||
const line = verdictLine({ verdict: 'RED-INCOMPLETE', failed: [], skipped: ['gitleaks'] }, 12);
|
||||
assert.ok(line.includes('🟠 RED-INCOMPLETE'));
|
||||
assert.ok(line.includes('gitleaks'));
|
||||
});
|
||||
|
||||
test('CHECKS: quick tier has exactly 6 checks', () => {
|
||||
assert.equal(CHECKS.filter((c) => c.tiers.includes('quick')).length, 6);
|
||||
});
|
||||
test('CHECKS: full tier has exactly 12 checks', () => {
|
||||
assert.equal(CHECKS.filter((c) => c.tiers.includes('full')).length, 12);
|
||||
});
|
||||
test('CHECKS: quick is a strict subset of full', () => {
|
||||
const full = new Set(CHECKS.filter((c) => c.tiers.includes('full')).map((c) => c.id));
|
||||
for (const c of CHECKS.filter((c) => c.tiers.includes('quick'))) {
|
||||
assert.ok(full.has(c.id), `${c.id} in quick must also be in full`);
|
||||
}
|
||||
});
|
||||
test('CHECKS: every check has id, label, cwd, parse, and a command source', () => {
|
||||
for (const c of CHECKS) {
|
||||
assert.ok(c.id && c.label && c.cwd, `${c.id}: id/label/cwd`);
|
||||
assert.equal(typeof c.parse, 'function', `${c.id}: parse is a function`);
|
||||
assert.ok(c.cmd || (c.bin && Array.isArray(c.argv)), `${c.id}: has cmd or bin+argv`);
|
||||
}
|
||||
});
|
||||
test('CHECKS: ids are unique', () => {
|
||||
assert.equal(new Set(CHECKS.map((c) => c.id)).size, CHECKS.length);
|
||||
});
|
||||
|
||||
const RUN = fileURLToPath(new URL('./run.mjs', import.meta.url));
|
||||
|
||||
test('main: unknown argument → exit code 2 + error on stderr', () => {
|
||||
try {
|
||||
execFileSync(process.execPath, [RUN, 'bogus'], { encoding: 'utf8', stdio: 'pipe' });
|
||||
assert.fail('expected non-zero exit');
|
||||
} catch (err) {
|
||||
assert.equal(err.status, 2);
|
||||
assert.match(String(err.stderr), /unknown argument/i);
|
||||
}
|
||||
});
|
||||
test('main: importing run.mjs does not auto-run the sweep', () => {
|
||||
// If the import.meta guard were broken, importing run.mjs at the top of this
|
||||
// file would have spawned a full sweep. Reaching this assertion proves it did not.
|
||||
assert.ok(true);
|
||||
});
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
name: rls-check
|
||||
description: |
|
||||
Verify Row-Level Security on a new or modified table in db/schema.sql.
|
||||
Use when adding a new table, adding/removing tenant_id column, or modifying
|
||||
RLS policies. Walks through 7-step checklist (tenant_id, ENABLE RLS, 2+ policies,
|
||||
5-role GRANTs, db/CHANGELOG_schema.md entry, squawk, smoke test).
|
||||
For reviewing a diff, branch, or PR with DB changes - use the rls-reviewer agent.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# RLS-check — verify RLS на таблице
|
||||
|
||||
## Когда использовать
|
||||
|
||||
При добавлении или модификации таблицы в `db/schema.sql`, особенно перед коммитом. Инкапсулирует 7-item checklist; lefthook pre-commit job 7 (squawk) ловит только часть.
|
||||
|
||||
Invoke via `/rls-check <table_name>`.
|
||||
|
||||
## Граница с агентом rls-reviewer
|
||||
|
||||
`rls-check` (этот скил) и `rls-reviewer` (агент, `.claude/agents/rls-reviewer.md`)
|
||||
оба проверяют RLS, но в разных ситуациях. Правило выбора:
|
||||
|
||||
- Знаешь имя одной конкретной таблицы, проверка вручную перед коммитом →
|
||||
**`/rls-check <table>`** (этот скил).
|
||||
- Есть diff / ветка / PR с изменениями БД, набор таблиц заранее не известен →
|
||||
**агент `rls-reviewer`**.
|
||||
|
||||
Скил работает в основном контексте по одной названной таблице и прогоняет
|
||||
**8 строк вывода** — 7 статических пунктов + живой дымовой тест
|
||||
(`pest --filter RlsSmokeTest`, шаг 7). Агент работает в отдельном контексте
|
||||
субагента, разбирает diff/миграцию/PR и прогоняет только **7 статических**
|
||||
строк — дымовой тест намеренно не запускает.
|
||||
|
||||
Первые 7 строк вывода у обоих — общее статическое ядро (tenant_id, ENABLE RLS,
|
||||
SELECT/ALL политики, GRANT'ы 5 ролей, CHANGELOG, squawk). Это не дублирование:
|
||||
ядро проверок одно, сценарии вызова разные. Дымовой тест — только в скиле:
|
||||
запуск Pest в ревью-субагенте медленный и задевает гонки `--parallel`
|
||||
(квирки 72/77, см. `.claude/agents/pest-parallel-debugger.md`).
|
||||
|
||||
## Checklist
|
||||
|
||||
1. **tenant_id column.** Grep `db/schema.sql` для `CREATE TABLE <name>`. Verify:
|
||||
- `tenant_id UUID NOT NULL REFERENCES tenants(id)` присутствует, **OR**
|
||||
- SaaS-level exemption — explicit comment типа `-- SaaS-level: no tenant_id (justification)`.
|
||||
|
||||
```bash
|
||||
grep -A30 "CREATE TABLE.*\b<name>\b" db/schema.sql | grep -E "tenant_id|SaaS-level"
|
||||
```
|
||||
|
||||
2. **ENABLE RLS.** Должна быть строка `ALTER TABLE <name> ENABLE ROW LEVEL SECURITY;`.
|
||||
|
||||
```bash
|
||||
grep -E "ALTER TABLE\s+<name>\s+ENABLE ROW LEVEL SECURITY" db/schema.sql
|
||||
```
|
||||
|
||||
3. **Policies — минимум 2.**
|
||||
- SELECT для `crm_app_user`/`crm_app_admin` с tenant scope: `USING (tenant_id = current_setting('app.current_tenant_id')::uuid)`.
|
||||
- ALL для `crm_app_admin` (или per-table convention).
|
||||
- SaaS-level: BYPASSRLS role pattern (e.g., `crm_supplier_worker`).
|
||||
|
||||
```bash
|
||||
grep -B1 -A5 "ON <name>" db/schema.sql | grep "POLICY"
|
||||
```
|
||||
|
||||
4. **Role GRANTs.** В `db/02_grants.sql` должны быть GRANT'ы для 5 ролей. Проверить по pattern existing tables.
|
||||
|
||||
```bash
|
||||
grep -E "GRANT.*ON\s+<name>" db/02_grants.sql
|
||||
```
|
||||
|
||||
Expected: ≥5 GRANT statements (по одному на роль) или group GRANT.
|
||||
|
||||
5. **CHANGELOG entry.** В `db/CHANGELOG_schema.md` должна быть запись с датой + table name + summary (CLAUDE.md §5 п.8).
|
||||
|
||||
```bash
|
||||
grep "<name>" db/CHANGELOG_schema.md
|
||||
```
|
||||
|
||||
6. **squawk lint.**
|
||||
|
||||
```bash
|
||||
./bin/squawk.exe db/schema.sql 2>&1 | tail -10
|
||||
```
|
||||
|
||||
Expected: exit 0, no issues.
|
||||
|
||||
7. **Smoke test.** `tests/Feature/RlsSmokeTest.php` (или новый тест для конкретной таблицы) должен assert'ить, что user в tenant A не видит row из tenant B для новой таблицы.
|
||||
|
||||
```bash
|
||||
cd app && ./vendor/bin/pest --filter RlsSmokeTest 2>&1 | tail -10
|
||||
```
|
||||
|
||||
Expected: all assertions pass.
|
||||
|
||||
## Output
|
||||
|
||||
Print результат per item + total:
|
||||
|
||||
```text
|
||||
RLS-check: <table_name>
|
||||
[✅] tenant_id column
|
||||
[✅] ENABLE RLS
|
||||
[✅] SELECT policy
|
||||
[✅] ALL policy
|
||||
[✅] 5-role GRANTs
|
||||
[✅] CHANGELOG entry
|
||||
[✅] squawk passes
|
||||
[✅] smoke test passes
|
||||
Pass: 8/8
|
||||
```
|
||||
|
||||
Or failure listing: `[❌] tenant_id column missing — db/schema.sql:NNNN`.
|
||||
|
||||
## Не использовать когда
|
||||
|
||||
- Modifying existing well-RLS'd table без новых columns — overhead.
|
||||
- Tables explicitly outside RLS (e.g., Laravel `migrations`, `cache` — internal).
|
||||
- Проверяешь не одну названную таблицу, а diff/ветку/PR с изменениями БД —
|
||||
это сценарий агента `rls-reviewer`, не скила.
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
name: ru-tax-accounting
|
||||
description: Контекст РСБУ и налогов РФ (НК РФ, НДС/УСН) применительно к SaaS-выручке Лидерры за лиды. Используй при «учёт выручки по РСБУ», «НДС или УСН», «налоговая база по выручке», «налогооблагаемое событие», «выгрузка для бухгалтера», «проводки РСБУ». НЕ для денежной корректности кода (billing-audit), US-GAAP-отчётности (finance plugin), договоров (D1 право), ПДн (D2), сверки с банком (finance reconciliation).
|
||||
---
|
||||
|
||||
# RU Tax & Accounting — РСБУ/НК РФ контекст для выручки Лидерры
|
||||
|
||||
Проектный скил раздела C7 карты «Финансы — бухгалтерия и налоги». Переводит
|
||||
billing-выручку (выход C6) в **российский учётно-налоговый контекст** (РСБУ + НК РФ).
|
||||
Закрывает gap, который US-GAAP-плагин `finance` (#61) не покрывает.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- Вопрос «как это учесть/обложить по РФ-правилам?» по выручке/пополнениям/возвратам.
|
||||
- Подготовка выгрузок/пояснений для бухгалтера из billing-данных.
|
||||
- Определение налогооблагаемого события и налоговой базы.
|
||||
|
||||
## Содержание (см. references/ru-tax-context.md)
|
||||
|
||||
1. **Налоговые режимы РФ** — НДС (ОСНО) vs УСН (доходы / доходы-расходы); что применимо к SaaS за лиды.
|
||||
2. **Налогооблагаемое событие** — пополнение баланса (аванс) vs списание за лид (реализация) vs возврат.
|
||||
3. **Маппинг billing→база** — `lead_charges`/`LedgerService` → выручка → налоговая база; роль `charge_source`.
|
||||
4. **РСБУ vs управленческий** — отличие от US-GAAP-отчётов плагина finance; первичка/документы.
|
||||
5. **Выгрузки для бухгалтера** — какие данные и в каком разрезе извлечь (Boost/Pest как инструменты выгрузки).
|
||||
|
||||
## Границы
|
||||
|
||||
- ≠ `billing-audit` #62 — тот про *корректность начисления в коде*; ru-tax про *учёт/налог результата*.
|
||||
- ≠ `finance` plugin #61 — тот US-GAAP-механика (проводки/отчёты/сверка); ru-tax — РФ-специфика РСБУ/НК.
|
||||
- ≠ D1 «Юриспруденция/договорная» — там договоры/право; ru-tax — налоги.
|
||||
- ≠ D2 «Защита ПДн (152-ФЗ)» — там персональные данные; ru-tax — налоги.
|
||||
|
||||
## Ограничение
|
||||
|
||||
Бухгалтерия компании ведётся вне dev-репо (1С/аутсорс). Скил даёт **контекст и выгрузки**,
|
||||
не заменяет бухгалтера и не является налоговой консультацией. Реальный платёжный
|
||||
провайдер — DEFERRED (Б-1).
|
||||
|
||||
## Связано
|
||||
|
||||
- Вход: выручка из C6 (`lead_charges`, `LedgerService`).
|
||||
- Reuse: data-scientist #49 (финмодели), Boost #10 / Pest #18 (выгрузка), finance plugin #61 (US-механика).
|
||||
- ADR-012 (граница finance-tooling C6/C7).
|
||||
@@ -1,21 +0,0 @@
|
||||
{
|
||||
"skill": "ru-tax-accounting",
|
||||
"positive": [
|
||||
"как учесть выручку за лиды по РСБУ",
|
||||
"НДС или УСН для SaaS-выручки",
|
||||
"переведи billing-выручку в налоговую базу",
|
||||
"какое налогооблагаемое событие при пополнении баланса",
|
||||
"выгрузка lead_charges для бухгалтера",
|
||||
"проводки по РСБУ за списания",
|
||||
"налоговый режим для подписочной выручки портала",
|
||||
"что с НДС при возврате на баланс tenant",
|
||||
"налоговая база УСН доходы по выручке за лиды"
|
||||
],
|
||||
"near_miss": [
|
||||
{"prompt": "проверь идемпотентность списания", "expect": "billing-audit #62"},
|
||||
{"prompt": "US-GAAP financial statement", "expect": "finance plugin #61 financial-statements"},
|
||||
{"prompt": "договор с поставщиком лидов", "expect": "D1 юриспруденция"},
|
||||
{"prompt": "обработка ПДн при выгрузке", "expect": "D2 ПДн 152-ФЗ"},
|
||||
{"prompt": "сверка ledger с банком", "expect": "finance plugin #61 reconciliation"}
|
||||
]
|
||||
}
|
||||
@@ -1,40 +0,0 @@
|
||||
# РСБУ / НК РФ — контекст для выручки Лидерры за лиды
|
||||
|
||||
> Не налоговая консультация. Контекст для подготовки данных бухгалтеру.
|
||||
|
||||
## 1. Налоговые режимы РФ
|
||||
|
||||
- **ОСНО + НДС (НК РФ гл. 21)** — НДС 20% на реализацию услуг РФ. Электронные/рекламные
|
||||
услуги — проверить место реализации и применимые льготы.
|
||||
- **УСН (НК РФ гл. 26.2)** — «доходы» (6%) или «доходы минус расходы» (15%). Без НДС
|
||||
(кроме исключений). Типичный режим для раннего SaaS.
|
||||
- Применимый режим зависит от регистрации ООО (Б-1) — до закрытия Б-1 фиксируем как параметр.
|
||||
|
||||
## 2. Налогооблагаемое событие
|
||||
|
||||
- **Пополнение баланса** = аванс (предоплата). По НДС — момент определения базы может
|
||||
возникать на аванс; по УСН-доходы — доход по поступлению (кассовый метод).
|
||||
- **Списание за лид** = реализация услуги (закрытие аванса).
|
||||
- **Возврат на баланс / с баланса** = корректировка базы.
|
||||
- Различать по `lead_charges.charge_source` и операциям `LedgerService`.
|
||||
|
||||
## 3. Маппинг billing → налоговая база
|
||||
|
||||
| Billing-сущность | Учётный смысл |
|
||||
|---|---|
|
||||
| Пополнение (`BillingTopupService`) | Аванс / поступление |
|
||||
| Списание (`LedgerService`, `lead_charges`) | Реализация (выручка) |
|
||||
| `delivered_in_month` (`tenants`) | Объём для tier — не налог напрямую |
|
||||
| Возврат | Корректировка |
|
||||
|
||||
## 4. РСБУ vs управленческий / US-GAAP
|
||||
|
||||
- РСБУ — российский план счетов, первичные документы (акт/УПД), кассовый/начисление.
|
||||
- US-GAAP-скилы плагина `finance` (#61) — иная форма (income statement / balance sheet);
|
||||
применимы для *внутренней управленки*, не для РФ-отчётности.
|
||||
|
||||
## 5. Выгрузки для бухгалтера
|
||||
|
||||
- Реестр списаний за период: `lead_charges` (period, tenant, сумма, charge_source).
|
||||
- Реестр пополнений: операции `LedgerService` / `BillingTopupService`.
|
||||
- Инструменты выгрузки: Boost #10 (Eloquent/SQL), Pest #18 (фикстуры/проверки), `BillingSummaryProvider` (готовый отчёт-провайдер).
|
||||
@@ -1,68 +0,0 @@
|
||||
---
|
||||
name: security-go-live
|
||||
description: Единый go-live security-gate Лидерры перед публикацией в интернете — один воспроизводимый прогон всех проверок безопасности и вердикт «можно/нельзя в прод». Оркеструет ZAP (#68), Nuclei (#69), Ward (#70), pdn-152fz-audit (#71), threat-model (#72) + Semgrep #25 / Trivy #26 / gitleaks #8 / Trail of Bits #39. Используй при «прогон безопасности перед релизом», «можно ли выкатывать», «go-live security check», «финальная проверка безопасности». НЕ для полного 14-фазного аудита портала (audit-portal), отдельной проверки ПДн (pdn-152fz-audit #71) или угроз (threat-model #72).
|
||||
---
|
||||
|
||||
# Security Go-Live — единый gate безопасности перед публикацией
|
||||
|
||||
Проектный скил раздела A8 карты «Информационная безопасность». Запускает
|
||||
**один воспроизводимый прогон всех security-проверок** и выдаёт вердикт
|
||||
**GO / NO-GO** перед тем, как портал Лидерры становится доступным из интернета.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- «Прогони все проверки безопасности перед релизом»
|
||||
- «Можно ли выкатывать портал в прод по безопасности?»
|
||||
- «Go-live security check» / «финальная проверка безопасности»
|
||||
- «Готов ли портал к публикации со стороны ИБ?»
|
||||
|
||||
## Что это и чем НЕ является
|
||||
|
||||
**Это:** операционный gate — воспроизводимый чек-лист, который прогоняется
|
||||
каждый раз перед go-live и выдаёт конкретный вердикт с перечнем блокеров.
|
||||
|
||||
**Это НЕ:**
|
||||
|
||||
- ≠ `audit-portal` — тот 14-фазный сквозной аудит качества всего портала
|
||||
(статанализ, тесты, схема БД, UI-smoke, a11y, coverage, bundle и пр.);
|
||||
security-go-live — security-only срез, занимает часть дня, не несколько дней.
|
||||
- ≠ `pdn-152fz-audit` #71 — тот глубокий аудит персональных данных и 152-ФЗ;
|
||||
security-go-live вызывает его как один шаг, не заменяет.
|
||||
- ≠ `threat-model` #72 — тот строит модель угроз как документ (STRIDE, карта
|
||||
точек входа); security-go-live проверяет, что выявленные угрозы ЗАКРЫТЫ.
|
||||
|
||||
## Порядок прогона
|
||||
|
||||
Полная процедура — `references/gate.md`. Кратко:
|
||||
|
||||
1. **Статика** — gitleaks, Semgrep, Ward (config/env/deps/code), Trail of Bits.
|
||||
2. **ПДн / 152-ФЗ** — вызвать `pdn-152fz-audit` #71.
|
||||
3. **Угрозы** — вызвать `threat-model` #72, убедиться что топ-угрозы закрыты.
|
||||
4. **Динамика (локальная цель по умолчанию)** — Nuclei (`bin/nuclei.exe`),
|
||||
затем ZAP (spider + active scan). Боевой сервер — только по явной команде.
|
||||
5. **Вердикт** — GO / NO-GO с явным списком блокеров.
|
||||
|
||||
## Выход
|
||||
|
||||
```
|
||||
=== SECURITY GO-LIVE REPORT ===
|
||||
Дата: YYYY-MM-DD
|
||||
Версия схемы: <schema-version>
|
||||
Commit: <HEAD>
|
||||
|
||||
[ШАГИ 1-4 — результаты по каждому инструменту]
|
||||
|
||||
=== ВЕРДИКТ: GO ✅ / NO-GO ❌ ===
|
||||
Блокеры (critical/high): <список или "нет">
|
||||
Предупреждения (medium): <список или "нет">
|
||||
=== END ===
|
||||
```
|
||||
|
||||
## Связано
|
||||
|
||||
- `references/gate.md` — подробная процедура прогона + формат вердикта.
|
||||
- `pdn-152fz-audit` #71, `threat-model` #72 — вызываются как подшаги.
|
||||
- ZAP #68 (OWASP, DAST), Nuclei #69 (CLI `bin/nuclei.exe`), Ward #70 (Go CLI).
|
||||
- gitleaks #8, Semgrep #25, Trivy #26, Trail of Bits #39 — статика.
|
||||
- ADR-013 (infosec-tooling A8), `docs/security/nuclei-setup.md`,
|
||||
`docs/security/infosec-vet.md`.
|
||||
@@ -1,10 +0,0 @@
|
||||
{
|
||||
"skill": "security-go-live",
|
||||
"cases": [
|
||||
{"prompt": "прогони все проверки безопасности перед релизом", "should_trigger": true},
|
||||
{"prompt": "можно ли выкатывать портал в прод по безопасности", "should_trigger": true},
|
||||
{"prompt": "проведи полный аудит портала", "should_trigger": false, "expected": "audit-portal"},
|
||||
{"prompt": "проверь только персональные данные", "should_trigger": false, "expected": "pdn-152fz-audit"},
|
||||
{"prompt": "смоделируй угрозы", "should_trigger": false, "expected": "threat-model"}
|
||||
]
|
||||
}
|
||||
@@ -1,241 +0,0 @@
|
||||
# Security Go-Live Gate — процедура прогона и формат вердикта
|
||||
|
||||
Подробная пошаговая процедура для скила `security-go-live` (#73).
|
||||
Цель — один воспроизводимый прогон перед каждым выходом портала в интернет.
|
||||
|
||||
---
|
||||
|
||||
## Гарды
|
||||
|
||||
**IS8 — цель по умолчанию локальная.** Все динамические проверки (Nuclei, ZAP)
|
||||
направляются на локальную или тестовую копию портала (`127.0.0.1`). Боевой
|
||||
(`crm.bp-gr.ru` или любой публичный IP) — только по явной команде заказчика:
|
||||
«сканируй прод» / «сканируй боевой».
|
||||
|
||||
**IS7 — граница с `audit-portal`.** `security-go-live` — security-only gate:
|
||||
выдаёт GO/NO-GO по безопасности. Он не заменяет 14-фазный `audit-portal`
|
||||
(тесты, схема, UI-smoke, a11y, coverage, bundle и пр.). Перед первым
|
||||
production-деплоем рекомендуется прогнать `audit-portal` **и** `security-go-live`
|
||||
как два отдельных прогона; при плановых go-live (хотфикс/фича) — достаточно
|
||||
`security-go-live`.
|
||||
|
||||
---
|
||||
|
||||
## Шаг 1 — Статика (static analysis)
|
||||
|
||||
Запустить последовательно. Каждый инструмент фиксирует результат в разделе
|
||||
отчёта.
|
||||
|
||||
### 1.1 gitleaks — поиск секретов в истории
|
||||
|
||||
```powershell
|
||||
# Полная история
|
||||
.\bin\gitleaks.exe detect --source . --log-opts "--all"
|
||||
# Только staged/unstaged (перед коммитом)
|
||||
.\bin\gitleaks.exe protect --staged
|
||||
```
|
||||
|
||||
Ожидаемо: **0 утечек**. Любой leak = NO-GO (critical).
|
||||
|
||||
### 1.2 Semgrep — статический анализ кода
|
||||
|
||||
```powershell
|
||||
npm run sast
|
||||
```
|
||||
|
||||
Ожидаемо: **0 critical/high**. Medium — предупреждение (не блокер).
|
||||
|
||||
### 1.3 Ward — Laravel config / env / deps / code
|
||||
|
||||
Ward (#70) — Go-бинарь, замена заброшенного Enlightn. Сканирует:
|
||||
`.env` (8 проверок), `config/*.php` (13 проверок), зависимости Composer
|
||||
(через OSV.dev), код (секреты, injection, XSS, debug-артефакты, crypto,
|
||||
CORS/CSRF/mass-assignment, auth).
|
||||
|
||||
```powershell
|
||||
# Если Ward установлен (pending — нет тегов-релизов, pin по commit SHA)
|
||||
.\bin\ward.exe scan --path app/
|
||||
```
|
||||
|
||||
Если Ward **не установлен** (pending `docs/security/ward-setup.md`) — отметить
|
||||
в отчёте как `PENDING` и продолжить. Ward — не блокер установки gate,
|
||||
но должен быть установлен до первого реального go-live.
|
||||
|
||||
Ожидаемо: **0 critical**. High — разобрать вручную. Ошибки конфигурации
|
||||
(APP_DEBUG=true, слабые ключи, открытые CORS) = NO-GO если critical.
|
||||
|
||||
### 1.4 Trail of Bits — глубокий on-demand аудит (#39)
|
||||
|
||||
Вызывается вручную перед первым публичным релизом или при значительных
|
||||
изменениях security-периметра. Не требуется при каждом хотфиксе.
|
||||
|
||||
```
|
||||
/differential-review:diff-review # если ревьюим конкретный diff
|
||||
/audit-context-building:audit-context # для supply-chain аудита
|
||||
```
|
||||
|
||||
Результаты фиксируются в `docs/security/trail-of-bits-YYYY-MM-DD.md`.
|
||||
|
||||
---
|
||||
|
||||
## Шаг 2 — ПДн / 152-ФЗ
|
||||
|
||||
Вызвать скил `pdn-152fz-audit` (#71).
|
||||
|
||||
```
|
||||
/pdn-152fz-audit
|
||||
```
|
||||
|
||||
Прогнать оба режима:
|
||||
|
||||
- **Режим 1 (технический):** RLS на таблицах ПДн, маскирование pg_anonymizer,
|
||||
отсутствие phone/email в логах, pg_anonymizer в дампах.
|
||||
- **Режим 2 (соответствие 152-ФЗ):** хранение в РФ, согласия, права субъекта
|
||||
(`pd_subject_requests`), журнал обработки (`pd_processing_log`), уведомление РКН.
|
||||
|
||||
Итог: список нарушений (если есть). Нарушения Режима 1 уровня critical (ПДн
|
||||
в открытых логах/Sentry) = NO-GO.
|
||||
|
||||
---
|
||||
|
||||
## Шаг 3 — Угрозы (threat model)
|
||||
|
||||
Вызвать скил `threat-model` (#72) или открыть последний файл
|
||||
`docs/security/threat-model-YYYY-MM-DD.md`.
|
||||
|
||||
Цель: убедиться, что **топ-приоритетные угрозы из STRIDE** закрыты контрмерами
|
||||
(rate-limit на login, HMAC на webhook, Sanctum token-auth, CSRF, RLS).
|
||||
|
||||
Если актуальная модель угроз отсутствует (нет файла за последние 30 дней) —
|
||||
запустить `threat-model` перед динамикой.
|
||||
|
||||
---
|
||||
|
||||
## Шаг 4 — Динамика (dynamic analysis, локальная цель)
|
||||
|
||||
> **IS8:** по умолчанию цель — локальная копия. Убедиться, что приложение
|
||||
> запущено: `php artisan serve` → `http://127.0.0.1:8000`.
|
||||
|
||||
### 4.1 Nuclei — широкое сканирование (#69)
|
||||
|
||||
Nuclei установлен как CLI-бинарь `bin/nuclei.exe` (MIT, projectdiscovery,
|
||||
v3.8.0). **Не MCP-сервер.**
|
||||
|
||||
**Квирки native-Windows (обязательно соблюдать):**
|
||||
|
||||
1. **Цель — `127.0.0.1`, НЕ `localhost`.** Резолвер Nuclei не разрешает
|
||||
`localhost` на этой машине — цель будет пропущена (квирк зафиксирован в
|
||||
`docs/security/nuclei-setup.md`).
|
||||
2. **Низкий rate-limit для dev-сервера.** `php artisan serve` однопоточный;
|
||||
без ограничений Nuclei перегружает его ложными connection-ошибками.
|
||||
Всегда использовать `-rate-limit 20 -c 5`.
|
||||
|
||||
```powershell
|
||||
# Стандартный прогон (medium+)
|
||||
bin\nuclei.exe -u "http://127.0.0.1:8000" `
|
||||
-rate-limit 20 -c 5 -timeout 5 -duc `
|
||||
-severity medium,high,critical
|
||||
|
||||
# Только технологический стек (быстрый smoke)
|
||||
bin\nuclei.exe -u "http://127.0.0.1:8000" -tags tech `
|
||||
-rate-limit 20 -c 5 -timeout 5 -duc
|
||||
```
|
||||
|
||||
Если `bin/nuclei.exe` отсутствует — отметить `PENDING` и продолжить.
|
||||
Детали установки: `docs/security/nuclei-setup.md`.
|
||||
|
||||
Ожидаемо: **0 critical/high**. Medium — разобрать вручную.
|
||||
|
||||
### 4.2 ZAP — глубокое DAST (#68)
|
||||
|
||||
ZAP (#68) — официальный MCP add-on (`zaproxy/zap-extensions`, Apache-2.0),
|
||||
alpha v0.1.0. Требует Java 17+ и запущенного ZAP-демона.
|
||||
|
||||
Если ZAP **не установлен** (pending Java) — отметить `PENDING` и продолжить.
|
||||
Детали: `docs/security/zap-setup.md` (когда будет создан).
|
||||
|
||||
```
|
||||
# Через ZAP MCP (когда ZAP установлен)
|
||||
# 1. Запустить ZAP-демон: zaproxy -daemon -port 8080 -config api.key=<key>
|
||||
# 2. Spider
|
||||
ZapStartSpiderTool(url="http://127.0.0.1:8000", contextId=...)
|
||||
# 3. Active scan
|
||||
ZapStartActiveScanTool(url="http://127.0.0.1:8000", contextId=...)
|
||||
# 4. Отчёт
|
||||
ZapGenerateReportTool(...)
|
||||
```
|
||||
|
||||
Ожидаемо: **0 critical/high**. Medium — разобрать вручную.
|
||||
Critical/high из ZAP active scan = NO-GO.
|
||||
|
||||
---
|
||||
|
||||
## Шаг 5 — Сбор находок и вердикт
|
||||
|
||||
### Severity → статус
|
||||
|
||||
| Severity | Источник | Статус gate |
|
||||
|---|---|---|
|
||||
| critical | любой инструмент | **NO-GO** (блокер) |
|
||||
| high | любой инструмент | **NO-GO** (блокер) |
|
||||
| medium | любой инструмент | Предупреждение (не блокирует go-live, фиксируется) |
|
||||
| low / info | любой инструмент | Информационно |
|
||||
| PENDING | ZAP / Ward / Nuclei не установлены | Условный GO — инструменты должны быть установлены до публичного деплоя |
|
||||
|
||||
### Формат отчёта
|
||||
|
||||
```
|
||||
=== SECURITY GO-LIVE REPORT ===
|
||||
Дата: YYYY-MM-DD
|
||||
Версия схемы: vX.XX
|
||||
Commit: <git rev-parse HEAD>
|
||||
Цель: http://127.0.0.1:<port> (локальная копия)
|
||||
|
||||
--- ШАГ 1: СТАТИКА ---
|
||||
gitleaks: OK (0 утечек) / FAIL (<N> утечек)
|
||||
Semgrep: OK (0 critical/high) / FAIL (<список>)
|
||||
Ward: OK / FAIL (<список>) / PENDING (не установлен)
|
||||
Trail of Bits: OK / SKIP (не применимо к этому прогону)
|
||||
|
||||
--- ШАГ 2: ПДн / 152-ФЗ ---
|
||||
pdn-152fz-audit Режим 1: OK / FAIL (<список>)
|
||||
pdn-152fz-audit Режим 2: OK / ПРЕДУПРЕЖДЕНИЯ (<список>)
|
||||
|
||||
--- ШАГ 3: УГРОЗЫ ---
|
||||
threat-model: ЗАКРЫТЫ (файл docs/security/threat-model-YYYY-MM-DD.md)
|
||||
Незакрытые топ-угрозы: <список или "нет">
|
||||
|
||||
--- ШАГ 4: ДИНАМИКА ---
|
||||
Nuclei: OK (0 critical/high) / FAIL (<список>) / PENDING (не установлен)
|
||||
ZAP: OK (0 critical/high) / FAIL (<список>) / PENDING (не установлен)
|
||||
|
||||
=== ВЕРДИКТ: GO ✅ / NO-GO ❌ ===
|
||||
Блокеры (critical/high):
|
||||
- <инструмент>: <описание> — <рекомендация>
|
||||
(или "Блокеров нет")
|
||||
|
||||
Предупреждения (medium):
|
||||
- <инструмент>: <описание>
|
||||
(или "Предупреждений нет")
|
||||
|
||||
PENDING-инструменты (должны быть закрыты до публичного деплоя):
|
||||
- Ward #70: установка — docs/security/ward-setup.md
|
||||
- ZAP #68: установка — docs/security/zap-setup.md (pending Java)
|
||||
(или "Все инструменты установлены")
|
||||
=== END ===
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Типичные блокеры и действия
|
||||
|
||||
| Находка | Источник | Действие |
|
||||
|---|---|---|
|
||||
| APP\_DEBUG=true | Ward / Semgrep | Исправить `.env` перед деплоем |
|
||||
| Секрет в git-истории | gitleaks | Rotate + `git filter-repo`; НЕ деплоить |
|
||||
| ПДн в логах Laravel | pdn-152fz-audit | Убрать из LogChannel + Sentry scrubbing |
|
||||
| CSRF отключён | Ward | Проверить `VerifyCsrfToken` middleware |
|
||||
| Слабый APP\_KEY | Ward | `php artisan key:generate` |
|
||||
| Критическая CVE в зависимости | Semgrep / Ward | `composer update` или `npm update` |
|
||||
| SQL injection / XSS | ZAP / Nuclei | Исправить код, перепрогнать |
|
||||
| Незакрытая STRIDE-угроза | threat-model | Реализовать контрмеру или принять риск с заказчиком |
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: Project-local wrapper для superpowers:subagent-driven-development — добавляет обязательный git-safety verify-протокол per Pravila §15.1. Использовать вместо marketplace-варианта при работе с git-коммит-задачами в субагентах.
|
||||
---
|
||||
|
||||
# Subagent-Driven Development (project wrapper)
|
||||
|
||||
Этот скил — проектная обёртка над marketplace-скилом `superpowers:subagent-driven-development`. Дополняет его обязательным git-safety verify-протоколом per Pravila §15.1.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
Когда нужно делегировать задачу субагенту через Task tool — особенно git-коммит-задачи (Sprint 6 прецедент: Haiku-субагенты угнали ветку параллельной сессии).
|
||||
|
||||
## Что делать
|
||||
|
||||
1. **Откройте marketplace-скил** `superpowers:subagent-driven-development` для общего workflow (fresh subagent per task + two-stage review).
|
||||
2. **Перед каждой Task-инвокацией** прочитайте и выполните pre-spawn-чеклист — [references/git-safety-checklist.md](references/git-safety-checklist.md) §A.
|
||||
3. **После каждой Task-инвокации** прочитайте и выполните post-subagent-чеклист — там же §B.
|
||||
4. **Hard-rule §15.1** — git-коммит-задача = модель Sonnet/Opus, никогда Haiku. Read-only git-операции (`log`, `status`, `diff`, `rev-parse`, `branch --show-current`, `worktree list`) разрешены любой модели.
|
||||
|
||||
Хук `tools/subagent-prompt-prefix.mjs` (зарегистрирован в `.claude/settings.json`) автоматически инжектит git-safety заголовок в каждый Task-prompt — это **первая** линия защиты. Чеклист из этого скила — **вторая** линия (защита со стороны контроллера).
|
||||
|
||||
## Cross-refs
|
||||
|
||||
- Pravila §15.1 — hard-rule субагенты + git.
|
||||
- Spec: `docs/superpowers/specs/2026-05-18-parallel-sessions-coordination-design.md` §5.
|
||||
- Memory: `memory/feedback_subagent_git_reliability.md`.
|
||||
@@ -1,65 +0,0 @@
|
||||
# Git-safety Checklist для контроллера субагентов
|
||||
|
||||
Per Pravila §15.1 — выполнять каждый раз при делегировании задачи через Task tool.
|
||||
|
||||
## §A. Pre-spawn чеклист (до Task-инвокации)
|
||||
|
||||
1. **Резолвите 4 значения** (запишите у себя для post-check):
|
||||
|
||||
```bash
|
||||
git branch --show-current # → ожидаемая ветка
|
||||
git rev-parse HEAD # → pre-spawn parent SHA
|
||||
git rev-parse --show-toplevel # → worktree root
|
||||
pwd # → cwd
|
||||
```
|
||||
|
||||
2. **Выберите модель** субагенту:
|
||||
- Задача требует `git commit`/`push`/`stage`/`checkout`/`switch`/`merge`/`rebase`? → **Sonnet или Opus**, никогда Haiku (§15.1).
|
||||
- Только read-только `git log`/`status`/`diff`/`rev-parse` ИЛИ только Edit/Read/Grep? → любая модель.
|
||||
3. **Если задача правит нормативку из списка §15.2** (Pravila / CLAUDE.md / Tooling / PSR_v1 / MEMORY.md / Открытые_вопросы / docs/adr/* / db/schema.sql):
|
||||
|
||||
```bash
|
||||
git fetch origin && git log HEAD..origin/main --oneline
|
||||
```
|
||||
|
||||
Не пусто → **ребейз/merge до инвокации**, не после. Pre-flight также проверить `docs/sessions/CURRENT.md` на конфликт scope-files / version-claims.
|
||||
|
||||
## §B. Post-subagent чеклист (сразу после возврата субагента)
|
||||
|
||||
1. **`git rev-parse HEAD`** — сравнить с pre-spawn parent SHA.
|
||||
- Равно → субагент не коммитил (OK для Edit-задач без commit).
|
||||
- Отличается ровно одним коммитом, чей parent = pre-spawn HEAD → OK для commit-задач.
|
||||
- **Иначе → STOP, разбор инцидента.**
|
||||
2. **`git branch --show-current`** — сравнить с pre-spawn branch.
|
||||
- Не равно → **STOP, разбор инцидента** (Sprint 6 паттерн).
|
||||
3. **`git log -1 --format='%s%n%P'`** — проверить subject + parent последнего коммита.
|
||||
- Subject соответствует задаче?
|
||||
- Parent = pre-spawn HEAD?
|
||||
4. Если несколько коммитов — ручная проверка subject'ов каждого.
|
||||
|
||||
## §C. Red-flag-список — любой = hard-stop разбор
|
||||
|
||||
- `branch ≠ ожидаемая`;
|
||||
- `parent коммита ≠ pre-spawn HEAD` (висячий коммит / попадание на чужую ветку);
|
||||
- HEAD двинулся, но субагент в отчёте об этом не упомянул;
|
||||
- в diff'е есть файлы вне scope задачи.
|
||||
|
||||
## §D. Обязательный формат отчёта субагента
|
||||
|
||||
Субагент в конце ответа выписывает блок:
|
||||
|
||||
```
|
||||
=== GIT REPORT ===
|
||||
cwd: <pwd>
|
||||
branch: <git branch --show-current>
|
||||
HEAD: <git rev-parse HEAD>
|
||||
HEAD^: <git rev-parse HEAD^>
|
||||
status: <git status --short>
|
||||
=== END GIT REPORT ===
|
||||
```
|
||||
|
||||
Отсутствие блока = контроллер считает результат недостоверным и запускает §B-чеклист сам через Bash.
|
||||
|
||||
## §E. Соотношение с code-review
|
||||
|
||||
Двухстадийное review (Pravila §4.5 / PSR_v1 R10) сохраняется. Git-safety-чеклист **не заменяет** code-review — он стоит **до** него (нет смысла ревьюить diff, если он не в той ветке).
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
name: threat-model
|
||||
description: Моделирование угроз портала Лидерра по STRIDE — карта точек входа, что меняется при выходе в интернет, приоритизация защиты. Используй при «смоделируй угрозы», «откуда могут атаковать», «что защищать в первую очередь перед публикацией», «карта точек входа», «threat model / STRIDE». НЕ для аудита ПДн/152-ФЗ (pdn-152fz-audit #71), статического security-аудита кода (D3/Semgrep/Trail of Bits), generic архитектурных паттернов (architecture-patterns), go-live прогона (security-go-live #73).
|
||||
---
|
||||
|
||||
# Threat Model — моделирование угроз портала Лидерра
|
||||
|
||||
Проектный скил раздела A8 карты «Информационная безопасность». Применяет методологию
|
||||
**STRIDE** к реальным точкам входа портала и отвечает на главный вопрос перед
|
||||
публикацией: **что именно меняется, когда в систему может зайти любой из интернета**.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
- «Смоделируй угрозы» / «откуда могут атаковать» / «что защищать в первую очередь»
|
||||
- Подготовка к go-live — составление модели угроз как артефакта (отдельно от
|
||||
чек-листа запуска, который — в `security-go-live #73`)
|
||||
- Анализ конкретного эндпоинта: «насколько опасен открытый `/api/webhook/{token}`?»
|
||||
- Ответ на вопрос заказчика / регулятора «покажи модель угроз»
|
||||
|
||||
## Процедура STRIDE для Лидерры
|
||||
|
||||
Полный разбор точек входа и таблица угроз — `references/stride-portal.md`.
|
||||
|
||||
### Шаги
|
||||
|
||||
1. **Определить периметр** — что сейчас открыто наружу vs что будет открыто после
|
||||
публикации. Основа: список точек входа в `references/stride-portal.md`.
|
||||
2. **Пройти по STRIDE для каждой точки** — заполнить 6 строк (S/T/R/I/D/E).
|
||||
Опираться на таблицу в `references/stride-portal.md`; при новых эндпоинтах
|
||||
добавлять строки по тому же шаблону.
|
||||
3. **Оценить вероятность × ущерб** — приоритизировать по матрице из `references/stride-portal.md`.
|
||||
4. **Сформировать список контрмер** — что уже есть (RLS, HMAC, Sanctum, rate-limit),
|
||||
чего не хватает (rate-limit на login, WAF, 2FA enforcement, и т.д.).
|
||||
5. **Сохранить результат** в `docs/security/threat-model-YYYY-MM-DD.md`.
|
||||
|
||||
## Выход
|
||||
|
||||
Файл `docs/security/threat-model-<дата>.md` со структурой:
|
||||
|
||||
- Область действия (дата, версия схемы, commit)
|
||||
- Карта точек входа (таблица)
|
||||
- STRIDE по каждой точке
|
||||
- Дельта «был закрытый круг → стал интернет»
|
||||
- Приоритизированный список рисков с контрмерами
|
||||
|
||||
## Границы
|
||||
|
||||
- ≠ `pdn-152fz-audit` #71 — тот про *персональные данные и 152-ФЗ* (конкретные
|
||||
таблицы, согласия, права субъекта); threat-model про *вектора атак и защиту
|
||||
эндпоинтов*.
|
||||
- ≠ D3 audit-security (#39/#40 Trail of Bits / Semgrep) — те про *статический
|
||||
анализ кода на уязвимости*; threat-model про *архитектурную карту угроз*.
|
||||
- ≠ `architecture-patterns` #38 — тот generic-паттерны; threat-model — конкретный
|
||||
портал, конкретные маршруты.
|
||||
- ≠ `security-go-live` #73 — тот *прогоняет конкретный чек-лист* перед релизом
|
||||
(Nmap, заголовки, CVE, gitleaks, DAST); threat-model *строит модель угроз как
|
||||
документ* (вход для чек-листа и приоритизации работ).
|
||||
|
||||
## Связано
|
||||
|
||||
- `references/stride-portal.md` — детальная карта точек входа и STRIDE-таблица.
|
||||
- `pdn-152fz-audit` #71 — смежный аудит ПДн; часто запускается вместе с threat-model.
|
||||
- `security-go-live` #73 — операционный прогон после threat-model завершён.
|
||||
- D3 / Semgrep #25 / Trail of Bits #39 — статический анализ; дополняет threat-model
|
||||
на уровне кода.
|
||||
- ADR-013 (infosec-tooling A8).
|
||||
@@ -1,13 +0,0 @@
|
||||
{
|
||||
"skill": "threat-model",
|
||||
"cases": [
|
||||
{"prompt": "смоделируй угрозы при выходе портала в интернет", "should_trigger": true},
|
||||
{"prompt": "что защищать в первую очередь перед публикацией", "should_trigger": true},
|
||||
{"prompt": "откуда могут атаковать портал", "should_trigger": true},
|
||||
{"prompt": "составь карту точек входа", "should_trigger": true},
|
||||
{"prompt": "сделай threat model по STRIDE", "should_trigger": true},
|
||||
{"prompt": "проверь соответствие 152-ФЗ", "should_trigger": false, "expected": "pdn-152fz-audit"},
|
||||
{"prompt": "прогони все проверки безопасности перед релизом", "should_trigger": false, "expected": "security-go-live"},
|
||||
{"prompt": "просканируй код на уязвимости семгрепом", "should_trigger": false, "expected": "D3/Semgrep"}
|
||||
]
|
||||
}
|
||||
@@ -1,198 +0,0 @@
|
||||
# STRIDE — карта угроз портала Лидерра
|
||||
|
||||
Основан на реальных маршрутах `app/routes/web.php` (v8.26, 21.05.2026).
|
||||
Стек: Laravel 13 + Vue 3 + PostgreSQL 16 RLS + Redis, Yandex Cloud `ru-central1`.
|
||||
|
||||
---
|
||||
|
||||
## Карта точек входа
|
||||
|
||||
| # | Точка входа | Маршрут(ы) | Аутентификация |
|
||||
|---|---|---|---|
|
||||
| E1 | Вход / регистрация | `POST /api/auth/login`, `POST /api/auth/register` | Публичный |
|
||||
| E2 | 2FA и коды восстановления | `POST /api/auth/2fa/verify`, `POST /api/auth/2fa/recovery-use` | Публичный (pending-session) |
|
||||
| E3 | Сброс пароля | `POST /api/auth/forgot`, `POST /api/auth/reset-password` | Публичный |
|
||||
| E4 | Входящий webhook поставщика | `POST /api/webhook/supplier/{secret}` | URL-secret + IP-allowlist |
|
||||
| E5 | Входящий webhook тенанта | `POST /api/webhook/{token}` | URL-token + (prod: HMAC X-Webhook-Signature + rate-limit) |
|
||||
| E6 | API сделок | `GET/POST/PATCH/DELETE /api/deals`, `/api/deals/export`, `/api/deals/transition`, `/api/deals/restore` | Sanctum SPA + tenant |
|
||||
| E7 | API проектов | `GET/POST/PATCH/DELETE /api/projects/{id}`, `/api/projects/bulk`, `/api/projects/{id}/sync` | Sanctum SPA + tenant |
|
||||
| E8 | API импорта CSV | `POST /api/imports`, `GET /api/imports/{importLog}`, `/api/imports/unknown-statuses` | Sanctum SPA + tenant |
|
||||
| E9 | Lookup-эндпоинты | `GET /api/managers`, `GET /api/lead-statuses` | **Без auth** (открытые) |
|
||||
| E10 | Биллинг тенанта | `POST /api/billing/topup`, `GET /api/billing/wallet`, `/transactions`, `/invoices` | Sanctum SPA + tenant |
|
||||
| E11 | Charges ledger | `GET /api/billing/charges`, `POST /api/billing/charges/export` | Sanctum SPA + tenant |
|
||||
| E12 | API-ключи тенанта | `GET /api/api-keys`, `POST /api/api-keys/regenerate` | Sanctum SPA + tenant |
|
||||
| E13 | Webhook-настройки тенанта | `GET/PUT /api/tenants/me/webhook-settings`, `POST /api/webhooks/test` | Sanctum SPA + tenant |
|
||||
| E14 | Напоминания | `GET/POST/PATCH/DELETE /api/reminders/{id}` | Sanctum SPA + tenant |
|
||||
| E15 | Уведомления | `GET/PATCH/POST/DELETE /api/notifications/{id}` | Sanctum SPA + tenant |
|
||||
| E16 | Отчёты | `GET/POST/DELETE /api/reports/jobs/{id}`, `POST /{id}/retry`, `POST /{id}/cancel` | Sanctum SPA + tenant |
|
||||
| E17 | Скачивание отчёта | `GET /api/reports/jobs/{id}/file` | Signed URL (без Sanctum) |
|
||||
| E18 | Дашборд | `GET /api/dashboard/summary` | **Без auth** (MVP-заглушка) |
|
||||
| E19 | Профиль / уведомления-настройки | `GET/PATCH /api/auth/me`, `PATCH /api/auth/me/notification-preferences` | Sanctum SPA |
|
||||
| E20 | SaaS-admin: тенанты, биллинг, инциденты, система | `GET/PATCH /api/admin/**` | `saas-admin` middleware |
|
||||
| E21 | SaaS-admin: импersonation | `POST /api/admin/impersonation/init`, `/verify`, `/end` | `saas-admin` middleware |
|
||||
| E22 | SaaS-admin: supplier-integration | `GET/POST /api/admin/supplier-integration/**` | `saas-admin` middleware |
|
||||
| E23 | 2FA setup (авторизованный) | `POST /api/2fa/init`, `/confirm`, `/disable`, `/regenerate-recovery-codes` | Sanctum SPA |
|
||||
| E24 | SPA-оболочка | `GET /`, `/login`, `/register`, `/deals`, … (20+ маршрутов) | Без auth (Vue shell) |
|
||||
|
||||
---
|
||||
|
||||
## Дельта «закрытый круг → интернет»
|
||||
|
||||
До публикации портал доступен только команде (VPN или фиксированные IP).
|
||||
После публикации **любой актор из интернета** может обратиться к каждому публичному
|
||||
эндпоинту. Критические изменения:
|
||||
|
||||
| Изменение | Затронутые точки | Почему важно |
|
||||
|---|---|---|
|
||||
| Брутфорс и credential stuffing | E1 (login) | Нет rate-limit на `/api/auth/login` (на момент анализа) |
|
||||
| Энумерация пользователей | E1, E3 | Разные ответы на «существующий / несуществующий email» создают oracle |
|
||||
| Replay и forgery webhook | E4, E5 | Secret в URL виден в логах прокси/nginx; HMAC на E5 — «prod» (не в dev) |
|
||||
| Открытые lookup-эндпоинты | E9 | `GET /api/managers`, `GET /api/lead-statuses` без auth — раскрывают ФИО менеджеров |
|
||||
| Открытый дашборд | E18 | `GET /api/dashboard/summary` без auth — раскрывает KPI текущего тенанта |
|
||||
| DoS на artisan-сервере | Все | `php artisan serve` не держит нагрузку; нужен nginx/Octane |
|
||||
| SSRF через webhook-test | E13 | `POST /api/webhooks/test` отправляет запрос на URL из тела — риск SSRF во внутреннюю сеть YC |
|
||||
| Impersonation без prod-auth | E21 | `saas-admin` middleware в dev-режиме пропускает без проверки (`SAAS_ADMIN_TEST_BYPASS`) |
|
||||
| Signed URL без срока инвалидации | E17 | Отчёт с ПДн доступен 24 ч по ссылке без повторной аутентификации |
|
||||
|
||||
---
|
||||
|
||||
## STRIDE по точкам входа
|
||||
|
||||
### E1 — Вход / Регистрация (`POST /api/auth/login`, `POST /api/auth/register`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Брутфорс пароля, credential stuffing | Bcrypt-хеш пароля | Нет rate-limit на login |
|
||||
| **T** Tampering | Подмена `tenant_id` в теле запроса | `tenant_id` берётся из `auth()->user()`, не из тела | — |
|
||||
| **R** Repudiation | Отрицание входа | `auth_log` пишет login/logout | Нет IP + User-Agent в каждой записи |
|
||||
| **I** Info disclosure | Энумерация email через разные ответы | Unified-ответ на forgot (E3) | Login может раскрывать «нет такого пользователя» |
|
||||
| **D** DoS | Флуд регистраций, засорение БД | — | Нет captcha / email-верификации на register |
|
||||
| **E** Elevation | Регистрация с `is_admin=true` в теле | Mass-assignment guard (fillable) | Проверить `$fillable` в `User` — нет ли `role` |
|
||||
|
||||
### E2 — 2FA (`POST /api/auth/2fa/verify`, `POST /api/auth/2fa/recovery-use`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Брутфорс 6-значного TOTP | TOTP 30-сек окно | Нет rate-limit на `/2fa/verify` |
|
||||
| **T** Tampering | Подмена `pending_user_id` в session | Серверная session | Проверить изоляцию session между тенантами |
|
||||
| **R** Repudiation | Использование кода восстановления | `auth_log` | Фиксируется ли `recovery_used` событие? |
|
||||
| **I** Info disclosure | Тайминг-атака на сравнение TOTP | TOTP библиотека (constant-time?) | Проверить реализацию `verifyTwoFactor` |
|
||||
| **D** DoS | Флуд на `/2fa/verify` истощает session-store | — | Нет rate-limit |
|
||||
| **E** Elevation | Обход 2FA через `recovery-use` | Коды — одноразовые, хранятся hashed | Если коды в открытом виде — критично |
|
||||
|
||||
### E3 — Сброс пароля (`POST /api/auth/forgot`, `POST /api/auth/reset-password`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Захват аккаунта через сброс пароля чужого email | Токен по email | Нет rate-limit на `/forgot` |
|
||||
| **T** Tampering | Подмена токена сброса | Cryptographic token (Laravel default) | Проверить срок жизни токена (1 ч?) |
|
||||
| **R** Repudiation | — | — | — |
|
||||
| **I** Info disclosure | Энумерация email через тайминг ответа | Unified-ответ задокументирован в роутах | Проверить фактическую реализацию ответа |
|
||||
| **D** DoS | Флуд `/forgot` → очередь email | — | Нет rate-limit → перегрузка Unisender Go |
|
||||
| **E** Elevation | — | — | — |
|
||||
|
||||
### E4 — Webhook поставщика (`POST /api/webhook/supplier/{secret}`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Подделка запроса от crm.bp-gr.ru | URL-secret + IP allowlist (`system_settings.supplier_ip_allowlist`) | Secret виден в логах nginx/прокси |
|
||||
| **T** Tampering | Подмена payload (телефон, стоимость лида) | — | Нет HMAC на тело; только secret в URL |
|
||||
| **R** Repudiation | Отрицание доставки лида | `supplier_leads.raw_payload` | Нет timestamp-подписи для доказательства |
|
||||
| **I** Info disclosure | Secret в URL → в access-логах сервера | IP allowlist сужает круг | Ротация secret при компрометации? |
|
||||
| **D** DoS | Флуд поддельных лидов → списание баланса | IP allowlist | Если allowlist обходится (SSRF) |
|
||||
| **E** Elevation | Подмена `tenant_id` в payload | Берётся из `system_settings` глобально | Архитектурно корректно; проверить lookup |
|
||||
|
||||
### E5 — Webhook тенанта (`POST /api/webhook/{token}`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Запрос от неавторизованного источника | URL-token из `tenants.webhook_token`; HMAC X-Webhook-Signature (prod) | HMAC только в prod; dev уязвим |
|
||||
| **T** Tampering | Изменение payload в transit | HMAC-валидация (prod) | В dev отключена — нельзя тестировать на prod-данных |
|
||||
| **R** Repudiation | — | `supplier_leads.raw_payload` | — |
|
||||
| **I** Info disclosure | Token в URL виден в логах | Per-token rate-limit | Нет ротации token при смене API-ключа |
|
||||
| **D** DoS | Replay flood | Per-token rate-limit (prod) | Нет в dev |
|
||||
| **E** Elevation | Лид с завышенной ценой | Стоимость берётся из `PricingTierResolver`, не из payload | Архитектурно защищено |
|
||||
|
||||
### E9 — Открытые lookup-эндпоинты (`GET /api/managers`, `GET /api/lead-statuses`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | — | — | — |
|
||||
| **T** Tampering | — | — | — |
|
||||
| **R** Repudiation | — | — | — |
|
||||
| **I** Info disclosure | ФИО менеджеров без аутентификации | — | **Нет auth** — любой из интернета получает список менеджеров |
|
||||
| **D** DoS | Флуд запросами | — | Нет rate-limit |
|
||||
| **E** Elevation | — | — | — |
|
||||
|
||||
### E18 — Дашборд без auth (`GET /api/dashboard/summary`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **I** Info disclosure | KPI, баланс, активность тенанта без аутентификации | — | **MVP-заглушка**: auth не включён; в prod обязателен |
|
||||
| **D** DoS | Тяжёлый агрегационный запрос без auth | — | Доступен без токена |
|
||||
|
||||
### E20 — SaaS-admin (`GET/PATCH /api/admin/**`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Доступ к admin-панели без Yandex 360 SSO | `saas-admin` middleware (fail-closed 503 в prod) | SSO не реализован до Б-1; `SAAS_ADMIN_TEST_BYPASS` в prod = полный доступ |
|
||||
| **T** Tampering | Изменение тарифа, статуса тенанта без аудита | `saas_admin_audit_log` | — |
|
||||
| **R** Repudiation | Отрицание действий admin | `saas_admin_audit_log` | Нет подписи/2FA для деструктивных операций |
|
||||
| **I** Info disclosure | Данные всех тенантов | `saas-admin` middleware | SAAS_ADMIN_TEST_BYPASS=true в production = полный дамп |
|
||||
| **D** DoS | Bulk-delete тенантов | — | Нет подтверждения для деструктивных bulk-операций |
|
||||
| **E** Elevation | Impersonation любого тенанта | `saas-admin` middleware | Та же уязвимость через bypass |
|
||||
|
||||
### E21 — Impersonation (`POST /api/admin/impersonation/init`, `/verify`, `/end`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **S** Spoofing | Имперсонация без реального admin-права | `saas-admin` middleware | Bypass в dev/test режиме |
|
||||
| **T** Tampering | Изменение `admin_user_id` в токене | Token-based flow | Проверить, что token не forgeble |
|
||||
| **R** Repudiation | Отрицание сессии имперсонации | `impersonation_tokens` логирует | Нет нотификации целевому тенанту |
|
||||
| **E** Elevation | Получение прав тенанта через impersonation | Scope ограничен tenant-контекстом | Если RLS bypass во время импersонации |
|
||||
|
||||
### E13 — SSRF через webhook-test (`POST /api/webhooks/test`)
|
||||
|
||||
| Угроза | Описание | Текущий контроль | Пробел |
|
||||
|---|---|---|---|
|
||||
| **T** Tampering | Отправка запроса на внутренний адрес YC | — | **Нет фильтрации URL** — SSRF во внутреннюю сеть Yandex Cloud (metadata service 169.254.169.254) |
|
||||
| **I** Info disclosure | YC instance metadata (IAM-токен, настройки сети) | — | Критично: SSRF → metadata API → IAM credentials |
|
||||
|
||||
---
|
||||
|
||||
## Приоритизация рисков
|
||||
|
||||
Матрица: **Вероятность** (В — высокая / С — средняя / Н — низкая) ×
|
||||
**Ущерб** (К — критический / В — высокий / С — средний / Н — низкий).
|
||||
|
||||
| Приоритет | Риск | Точка | Вероятность | Ущерб | Контрмера |
|
||||
|---|---|---|---|---|---|
|
||||
| 🔴 P0 | SAAS_ADMIN_TEST_BYPASS=true в prod | E20, E21 | В | К | Убедиться, что флаг false в `.env.production`; fail-closed middleware |
|
||||
| 🔴 P0 | SSRF через `/api/webhooks/test` | E13 | С | К | Валидировать URL: запрещать RFC1918 + link-local + metadata-IP; использовать DNS-rebind защиту |
|
||||
| 🔴 P0 | `GET /api/dashboard/summary` без auth | E18 | В | В | Добавить `auth:sanctum + tenant` middleware до prod |
|
||||
| 🔴 P0 | `GET /api/managers`, `GET /api/lead-statuses` без auth | E9 | В | С | Добавить `auth:sanctum + tenant` |
|
||||
| 🟠 P1 | Нет rate-limit на login / forgot / 2fa/verify | E1, E2, E3 | В | В | Laravel Throttle middleware (e.g. `throttle:5,1`) |
|
||||
| 🟠 P1 | URL-secret поставщика виден в access-логах | E4 | С | В | Перевести на HMAC-заголовок; ротировать secret; закрыть логи |
|
||||
| 🟠 P1 | Флуд поддельных лидов → списание баланса | E4, E5 | С | В | IP allowlist жёсткий; HMAC на тело (E4); idempotency-key |
|
||||
| 🟡 P2 | Энумерация email на login (не только forgot) | E1 | В | С | Unified-ответ на login тоже |
|
||||
| 🟡 P2 | Флуд регистраций без email-верификации | E1 | С | С | Email verification или captcha |
|
||||
| 🟡 P2 | Signed URL отчёта 24 ч без аутентификации | E17 | Н | С | Сократить TTL; добавить revocation при logout |
|
||||
| 🟡 P2 | Нет нотификации тенанту при impersonation | E21 | Н | С | Email/in-app уведомление при входе admin |
|
||||
| 🟢 P3 | Тайминг-атака на TOTP | E2 | Н | С | Проверить constant-time compare в TwoFactorController |
|
||||
| 🟢 P3 | Тайминг-атака на email в forgot | E3 | Н | Н | Unified-ответ + jitter sleep |
|
||||
|
||||
---
|
||||
|
||||
## Что уже защищает портал (baseline)
|
||||
|
||||
- **RLS PostgreSQL** — 39 политик; кросс-tenant утечка через SQL закрыта.
|
||||
- **Sanctum SPA auth** — все бизнес-эндпоинты под `auth:sanctum + tenant`.
|
||||
- **Per-token rate-limit** — на входящих webhook'ах тенанта (E5).
|
||||
- **IP allowlist** — на webhook поставщика (E4).
|
||||
- **HMAC X-Webhook-Signature** — на E5 в prod (не в dev).
|
||||
- **`auth_log`** — фиксирует login/logout события.
|
||||
- **`saas_admin_audit_log`** — фиксирует admin-действия.
|
||||
- **Bcrypt** — хеш пароля; коды восстановления 2FA — hashed.
|
||||
- **`saas-admin` middleware** — fail-closed 503 в prod (если `SAAS_ADMIN_TEST_BYPASS=false`).
|
||||
- **Signed URL** — для скачивания отчётов (E17).
|
||||
- **gitleaks** — pre-commit/pre-push; секреты не должны попасть в репозиторий.
|
||||
@@ -1,5 +0,0 @@
|
||||
# Normalize line endings for Node ESM tooling files.
|
||||
# Keep LF in the working tree regardless of core.autocrlf — CRLF .mjs files
|
||||
# break vitest module loading (SyntaxError: Invalid or unexpected token,
|
||||
# no file:line). See memory quirk #100 (2026-05-19).
|
||||
*.mjs text eol=lf
|
||||
@@ -1,85 +0,0 @@
|
||||
name: Accessibility (Pa11y live)
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
a11y:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup PHP 8.3
|
||||
uses: shivammathur/setup-php@v2
|
||||
with:
|
||||
php-version: '8.3'
|
||||
extensions: pdo, pdo_pgsql, redis, mbstring, intl, bcmath
|
||||
coverage: none
|
||||
|
||||
- name: Setup Node 20
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install root JS deps
|
||||
run: npm ci --no-audit --no-fund
|
||||
|
||||
- name: Install app composer deps
|
||||
working-directory: app
|
||||
run: composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
|
||||
|
||||
- name: Install app JS deps
|
||||
working-directory: app
|
||||
run: npm ci --no-audit --no-fund
|
||||
|
||||
- name: Bootstrap .env + key
|
||||
working-directory: app
|
||||
run: |
|
||||
cp .env.example .env
|
||||
php artisan key:generate --force
|
||||
|
||||
- name: Prepare SQLite for CI (avoid pg-on-CI fixture cost)
|
||||
working-directory: app
|
||||
run: |
|
||||
touch database/database.sqlite
|
||||
sed -i 's/DB_CONNECTION=.*/DB_CONNECTION=sqlite/' .env
|
||||
sed -i 's|DB_DATABASE=.*|DB_DATABASE=/home/runner/work/${{ github.event.repository.name }}/${{ github.event.repository.name }}/app/database/database.sqlite|' .env
|
||||
|
||||
- name: Build frontend assets
|
||||
working-directory: app
|
||||
run: npm run build
|
||||
|
||||
- name: Start Laravel dev-server
|
||||
working-directory: app
|
||||
run: nohup php artisan serve --host=127.0.0.1 --port=8000 > /tmp/laravel-serve.log 2>&1 &
|
||||
|
||||
- name: Wait for dev-server ready
|
||||
run: |
|
||||
for i in {1..30}; do
|
||||
if curl -s -o /dev/null http://127.0.0.1:8000/login; then
|
||||
echo "Dev-server up after ${i}s"
|
||||
exit 0
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
echo "Dev-server did not start within 30s"
|
||||
tail -50 /tmp/laravel-serve.log
|
||||
exit 1
|
||||
|
||||
- name: Run Pa11y (live Vue)
|
||||
run: npm run a11y
|
||||
|
||||
- name: Upload Pa11y screenshots
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: a11y-screenshots
|
||||
path: bin/a11y-screenshots/
|
||||
if-no-files-found: warn
|
||||
retention-days: 14
|
||||
@@ -1,31 +0,0 @@
|
||||
name: brain-l1-watcher (weekly)
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 6 * * 1'
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
drift:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
- name: run l1-watcher
|
||||
id: l1
|
||||
run: node tools/l1-watcher.mjs
|
||||
continue-on-error: true
|
||||
- name: open issue on drift
|
||||
if: steps.l1.outcome == 'failure'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
github.rest.issues.create({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
title: `[l1-watcher] drift detected (weekly cron ${new Date().toISOString().slice(0,10)})`,
|
||||
body: `Run failed. Check workflow logs and run /claude-md-management:claude-md-improver.`,
|
||||
labels: ['brain', 'drift']
|
||||
});
|
||||
-49
@@ -139,52 +139,3 @@ app/infection-summary.log
|
||||
|
||||
# Plan 3 Task 5 — Playwright Node subprocess (~200MB chromium downloads on prod)
|
||||
app/playwright/node_modules/
|
||||
|
||||
# Superpowers using-git-worktrees — локальные worktrees вне репо
|
||||
.claude/worktrees/
|
||||
|
||||
# Vitest coverage output (app/coverage/) — генерируется npm run test:coverage
|
||||
/app/coverage/
|
||||
|
||||
# ── Ruflo big-bang integration (2026-05-15) ──────────────────────────────────
|
||||
# ruflo runtime scaffolding и local-only routing config
|
||||
.claude-flow/
|
||||
CLAUDE.local.md
|
||||
# ruflo runtime state (created on activation 2026-05-15: memory DB + RuVector bridge)
|
||||
.swarm/
|
||||
ruvector.db
|
||||
# CLAUDE.md / .claude/ backups перед npx ruflo init --force (плановые artifacts Task 2.1)
|
||||
CLAUDE.md.pre-ruflo.bak
|
||||
.claude.pre-ruflo.bak/
|
||||
# ruflo install/dry-run logs (transient)
|
||||
ruflo-init.log
|
||||
ruflo-init-dryrun.log
|
||||
ruflo-mcp-stdout.log
|
||||
ruflo-mcp-stderr.log
|
||||
# ruflo init --force regen'ит 23 subdirs из upstream IPFS-registry — auto-regenerable, не tracking
|
||||
.claude/agents/analysis/
|
||||
.claude/agents/architecture/
|
||||
.claude/agents/browser/
|
||||
.claude/agents/consensus/
|
||||
.claude/agents/core/
|
||||
.claude/agents/custom/
|
||||
.claude/agents/data/
|
||||
.claude/agents/development/
|
||||
.claude/agents/devops/
|
||||
.claude/agents/documentation/
|
||||
.claude/agents/flow-nexus/
|
||||
.claude/agents/github/
|
||||
.claude/agents/goal/
|
||||
.claude/agents/optimization/
|
||||
.claude/agents/payments/
|
||||
.claude/agents/sona/
|
||||
.claude/agents/sparc/
|
||||
.claude/agents/specialized/
|
||||
.claude/agents/sublinear/
|
||||
.claude/agents/swarm/
|
||||
.claude/agents/templates/
|
||||
.claude/agents/testing/
|
||||
.claude/agents/v3/
|
||||
.claude/commands/*
|
||||
!.claude/commands/security-review.md
|
||||
.claude/helpers/
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user