@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/phases/verify/runners/playwright_local.md

@@ -0,0 +1,103 @@
+---
+name: playwright-local-runner
+description: Playwright local execution runner for Web E2E tests
+triggers:
+  - playwright run
+  - run e2e
+  - execute playwright
+  - playwright test
+allowed_tools:
+  - Bash
+  - Read
+phases:
+  - verify
+---
+
+# Playwright Local Runner
+
+## Prerequisites
+
+```bash
+# Install dependencies (usually done during scaffold)
+cd apps/web
+pnpm install
+
+# Install browsers (one-time setup)
+pnpm exec playwright install chromium
+```
+
+## Execution Command
+
+```bash
+# Standard execution
+cd apps/web
+npx playwright test --project=chromium
+
+# With JSON report (for parsing)
+npx playwright test --project=chromium --reporter=json
+
+# Specify test file
+npx playwright test apps/web/tests/e2e/login.spec.ts
+
+# Headless mode (default)
+npx playwright test --project=chromium
+
+# UI mode (for debugging)
+npx playwright test --project=chromium --ui
+
+# With custom base URL
+BASE_URL=http://localhost:3000 npx playwright test --project=chromium
+```
+
+## Report Location
+
+| Type | Location |
+|------|----------|
+| HTML Report | `apps/web/playwright-report/` |
+| JSON Report | stdout (with `--reporter=json`) |
+| Trace | `apps/web/test-results/` |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASE_URL` | `http://localhost:8080` | Override default base URL |
+| `PLAYWRIGHT_BROWSERS_PATH` | `~/.cache/ms-playwright` | Browser installation path |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | All tests passed |
+| 1 | Some tests failed |
+| 2 | Test was interrupted |
+| 3 | Configuration error |
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| `Playwright not installed` | Run `pnpm exec playwright install chromium` |
+| `Browser already in use` | Kill existing browser processes |
+| `Connection refused` | Ensure target app is running on specified port |
+| `Timeout` | Increase timeout in `playwright.config.ts` |
+
+## Example Output
+
+```json
+{
+  "config": {
+    "reporters": ["json"]
+  },
+  "result": {
+    "status": "passed",
+    "stats": {
+      "tests": 5,
+      "passed": 5,
+      "failed": 0,
+      "skipped": 0,
+      "duration": 12345
+    }
+  }
+}
+```

package/ai-dlc-skill/practices/bdd.md

@@ -0,0 +1,119 @@
+# Behavior-Driven Development (BDD)
+
+BDD is the behavior specification and verification methodology used in Understand and Verify phases.
+
+## Role in AI-DLC
+
+| Phase | BDD Usage |
+|-------|-----------|
+| Understand | Feature files with Given/When/Then scenarios |
+| Verify | pytest-bdd scenario verification against implementation |
+| Deliver | BDD e2e tests against preview URL |
+
+## Gherkin Syntax
+
+| Keyword | Purpose |
+|---------|---------|
+| `Feature` | High-level feature description |
+| `Scenario` | Single behavior example |
+| `Given` | Precondition / starting state |
+| `When` | Action performed |
+| `Then` | Expected outcome |
+| `And` / `But` | Additional clause |
+| `Background` | Steps before every scenario |
+| `Scenario Outline` | Template with Examples table |
+| `@tag` | Metadata (FR ID, type) |
+
+## Scenario Coverage Rules
+
+Each FR must have at least 4 scenarios:
+
+| Type | Coverage Dimension | Purpose | Example Tag |
+|------|-------------------|---------|-------------|
+| Positive | 处理逻辑 | Happy path, should work | `@FR-001 @positive` |
+| Negative | 异常处理 | Error handling, should fail | `@FR-001 @negative` |
+| Edge case | 边界情况 | Boundary conditions | `@FR-001 @edge` |
+| Logic | 逻辑一致性 | Idempotency, state consistency | `@FR-001 @logic` |
+
+### @logic 场景说明
+
+`@logic` 场景验证操作的逻辑一致性和理性：
+
+- **幂等性**: 重复执行结果一致
+- **状态一致性**: 操作后状态转换正确
+- **因果合理性**: 操作结果与原因合理对应
+- **数据完整性**: 操作不破坏数据完整性
+
+## Example
+
+```gherkin
+@FR-001
+Feature: User Login
+
+  @FR-001 @positive
+  Scenario: Successful login
+    Given the user is on the login page
+    When the user submits email "user@test.com" and password "correct123"
+    Then the user receives a JWT token
+    And the user is redirected to dashboard
+
+  @FR-001 @negative
+  Scenario: Login with wrong password
+    Given the user is on the login page
+    When the user submits email "user@test.com" and password "wrong"
+    Then the user sees error "Invalid credentials"
+
+  @FR-001 @edge
+  Scenario: Login with empty fields
+    Given the user is on the login page
+    When the user submits email "" and password ""
+    Then the user sees error "Email and password are required"
+
+  @FR-001 @logic
+  Scenario: Login is idempotent
+    Given the user has valid credentials
+    When the user submits the same credentials 3 times
+    Then each login returns the same JWT token
+    And no duplicate sessions are created
+```
+
+## pytest-bdd Integration
+
+```python
+# aidlc/features/steps/test_login_steps.py
+from pytest_bdd import scenarios, given, when, then, parsers
+
+scenarios("../cross-stack/auth/login.feature")
+
+@given("the user is on the login page")
+def login_page():
+    return LoginPage()
+
+@when(parsers.parse("the user submits email {email} and password {password}"))
+def submit(email, password):
+    ...
+```
+
+## Verification
+
+```bash
+# Run all BDD scenarios
+pytest aidlc/features/ --verbose
+
+# Run scenarios for a specific FR
+pytest aidlc/features/ -k "FR-001"
+
+# Generate step definitions
+pytest-bdd generate aidlc/features/cross-stack/auth/login.feature
+
+# BDD scenario coverage
+pytest aidlc/features/ --cov --cov-fail-under=80
+```
+
+## Feature File Locations
+
+| Type | Location |
+|------|----------|
+| Cross-stack contracts | `aidlc/features/cross-stack/` |
+| Web component | `apps/web/features/` |
+| Backend component | `apps/backend/features/` |

package/ai-dlc-skill/practices/sdd.md

@@ -0,0 +1,84 @@
+# Spec-Driven Development (SDD)
+
+SDD is the specification methodology used in Understand and Plan phases.
+
+## Role in AI-DLC
+
+| Phase | SDD Usage |
+|-------|-----------|
+| Understand | Intent capture, spec delta with EARS |
+| Plan | Design doc, task decomposition with DAG |
+| Deliver | Artifact archiving |
+
+## Core Artifacts
+
+### Proposal (Why/What/Impact)
+
+```markdown
+## Change: CHG-001 — User Authentication
+
+**Why:** Users need to securely access their accounts
+**What:** Email + password login with JWT session
+**Impact:** New auth module, changes to user model
+```
+
+### Spec Delta (EARS)
+
+```markdown
+## ADDED Requirements
+
+### FR-001: User Authentication
+
+**Priority:** P0
+
+**Description (Event-Driven):**
+When a user submits valid credentials, the system SHALL authenticate and return a JWT token.
+
+**Acceptance Criteria:**
+- AC1: Valid credentials return JWT with 1-hour expiry
+- AC2: Invalid credentials return 401
+- AC3: Empty fields return validation error
+```
+
+### Design Doc
+
+```markdown
+## Data Model: User
+
+| Field | Type | Constraints |
+|-------|------|-------------|
+| id | UUID | PK |
+| email | string | UNIQUE, NOT NULL |
+
+## API: POST /auth/login
+
+Request: `{email, password}`  Response: `{token, expires_in}`
+```
+
+### Task List with DAG
+
+```yaml
+units:
+  - id: unit-1
+    name: Database schema
+    depends_on: []
+  - id: unit-2
+    name: Login endpoint
+    depends_on: [unit-1]
+```
+
+## EARS Patterns
+
+| Pattern | Syntax | Example |
+|---------|--------|---------|
+| Ubiquitous | `The system SHALL ...` | Always-hash passwords with bcrypt |
+| Event-Driven | `When {event}, SHALL ...` | When user logs in, create session |
+| State-Driven | `While {state}, SHALL ...` | While session active, auto-refresh |
+| Unwanted | `If {condition}, SHALL ...` | If DB fails, return 503 |
+| Optional | `Where {feature}, SHALL ...` | Where SSO enabled, skip password |
+
+## Tools
+
+- Spec format: Markdown with EARS
+- Design: Markdown + Mermaid diagrams
+- Tasks: YAML with DAG structure

package/ai-dlc-skill/practices/tdd.md

@@ -0,0 +1,128 @@
+# Test-Driven Development (TDD)
+
+TDD is the implementation methodology used in the Verify phase.
+
+## Role in AI-DLC
+
+| Phase | TDD Usage |
+|-------|-----------|
+| Plan | Test plan written per scenario |
+| Verify | Red → Green → Refactor per BDD scenario |
+
+## Core Cycle
+
+```
+For each BDD scenario:
+  ┌──────────────────┐
+  │  1. RED          │  Write pytest test → confirm FAILURE
+  │  2. GREEN        │  Write minimum implementation → confirm PASS
+  │  3. REFACTOR     │  Clean up → all tests still PASS
+  └──────────────────┘
+```
+
+## RED Phase
+
+Write a test that asserts the expected behavior. It must fail on first run.
+
+```python
+# tests/unit/test_auth.py
+def test_login_valid_credentials():
+    result = authenticate("user@test.com", "correct123")
+    assert result.token is not None
+    assert result.expires_in == 3600
+```
+
+```bash
+pytest tests/unit/test_auth.py -v
+# FAILED — authenticate not defined  ✓ (RED confirmed)
+```
+
+**Rules:**
+- Test written before implementation code
+- Test must fail (confirms the assertion is valid)
+- Test covers only this scenario's behavior
+
+## GREEN Phase
+
+Write the minimum code to make the test pass.
+
+```python
+# src/auth/login.py
+def authenticate(email, password):
+    if email == "user@test.com" and password == "correct123":
+        return AuthResult(token="jwt_placeholder", expires_in=3600)
+    raise AuthError("Invalid credentials")
+```
+
+```bash
+pytest tests/unit/test_auth.py -v
+# PASSED  ✓ (GREEN)
+```
+
+**Rules:**
+- Minimum code to pass — no extras
+- No premature optimization
+- No new dependencies unless required
+
+## REFACTOR Phase
+
+Improve code quality without changing behavior.
+
+```bash
+pytest --cov --cov-fail-under=80
+# All tests passed, coverage ≥80%  ✓ (REFACTOR)
+```
+
+**Rules:**
+- Keep all tests green
+- No behavior changes
+- Repeat for next scenario
+
+## Naming Convention
+
+| Artifact | Location | Example |
+|----------|----------|---------|
+| Tests | `tests/unit/test_{feature}.py` | `tests/unit/test_auth.py` |
+| Step defs | `aidlc/features/steps/test_{feature}_steps.py` | `aidlc/features/steps/test_login_steps.py` |
+| Source | `src/{module}/{feature}.py` | `src/auth/login.py` |
+
+## Quality Gates
+
+```bash
+pytest --cov --cov-fail-under=80
+pytest aidlc/features/ --verbose
+bandit -r src/ -q
+```
+
+## Test Categories
+
+Each BDD scenario type maps to a test category:
+
+| BDD Tag | Test Category | Focus |
+|---------|---------------|-------|
+| `@positive` | 处理逻辑 | Normal flow, happy path |
+| `@negative` | 异常处理 | Error handling, invalid inputs |
+| `@edge` | 边界情况 | Boundary values, empty/null |
+| `@logic` | 逻辑一致性 | Idempotency, state consistency |
+
+### @logic Test Examples
+
+```python
+def test_login_is_idempotent():
+    """Repeated login returns same token."""
+    result1 = authenticate("user@test.com", "correct123")
+    result2 = authenticate("user@test.com", "correct123")
+    assert result1.token == result2.token
+
+def test_no_duplicate_sessions():
+    """Multiple logins don't create multiple sessions."""
+    authenticate("user@test.com", "correct123")
+    authenticate("user@test.com", "correct123")
+    assert session_count() == 1
+
+def test_state_consistency():
+    """Operation preserves data integrity."""
+    initial = db.count()
+    process()
+    assert db.count() == initial
+```

package/ai-dlc-skill/providers/README.md

@@ -0,0 +1,114 @@
+# Cloud Providers
+
+## Default: TCB (Tencent CloudBase)
+
+TCB is the default cloud development platform. Aliyun is also supported.
+
+The provider layer supports a **monorepo multi-component stack** (native + desktop + web + backend + wxa + mya + tta). Use the `deploy_stack` orchestrator instead of per-component CLI commands for shared environments.
+
+## Provider Comparison
+
+| Capability | TCB | Aliyun |
+|-----------|-----|--------|
+| **Functions** | CloudBase Functions | Function Compute (FC) |
+| **Database** | DocDB + MySQL | TableStore + RDS |
+| **Storage** | COS (Cloud Object Storage) | OSS (Object Storage Service) |
+| **Hosting** | CloudBase Hosting + Preview | Static Website + CDN |
+| **Stack preview URL** | `https://{env-id}.tcb-preview.com` (gateway) | `https://{gateway}.{region}.fc.devs.com` |
+| **Default** | Yes | No |
+
+## Stack Deploy
+
+`deploy_stack` is the unified orchestrator. It deploys `backend` first, captures `BACKEND_URL`, then deploys all client components with `BACKEND_URL` injected. The output is `STACK_URL` (= `BACKEND_URL`) plus per-component URLs.
+
+```bash
+deploy_stack --preview --provider tcb
+# → STACK_URL=https://{env-id}.tcb-preview.com
+# → WEB_URL=https://{env-id}-{project}.tcb-preview.com
+# → NATIVE_DIST_URL=internal distribution URL
+# → DESKTOP_DIST_URL=internal distribution URL
+# → WXA_URL/MYA_URL/TTA_URL=mini-program preview QR
+```
+
+```bash
+deploy_stack --preview --provider aliyun
+# → STACK_URL=https://{gateway}.{region}.fc.devs.com
+# → WEB_URL=https://{bucket}.{region}.oss-website.aliyuncs.com
+# → NATIVE_DIST_URL=internal distribution URL
+# → DESKTOP_DIST_URL=internal distribution URL
+# → WXA_URL/MYA_URL/TTA_URL=mini-program preview QR
+```
+
+## Build Config Injection
+
+All client builds receive `BACKEND_URL` at build time. The orchestrator passes it; components must not hardcode URLs.
+
+```bash
+# web
+pnpm --filter web build --env BACKEND_URL=$BACKEND_URL
+
+# native
+cd apps/native && BACKEND_URL=$BACKEND_URL pnpm build
+
+# desktop
+cd apps/desktop && BACKEND_URL=$BACKEND_URL pnpm build
+
+# mini-programs (wxa, mya, tta)
+cd apps/wxa && BACKEND_URL=$BACKEND_URL pnpm build
+cd apps/mya && BACKEND_URL=$BACKEND_URL pnpm build
+cd apps/tta && BACKEND_URL=$BACKEND_URL pnpm build
+```
+
+## Component URL Resolution
+
+| Component | TCB | Aliyun |
+|-----------|-----|--------|
+| `backend` (gateway) | `https://{env-id}.tcb-preview.com` | `https://{gateway}.{region}.fc.devs.com` |
+| `web` (hosting) | `https://{env-id}-{project}.tcb-preview.com` | `https://{bucket}.{region}.oss-website.aliyuncs.com` |
+| `native` (distribution) | internal distribution URL | internal distribution URL |
+| `desktop` (distribution) | internal distribution URL | internal distribution URL |
+| `wxa` (mini-program) | mini-program preview QR | mini-program preview QR |
+| `mya` (mini-program) | mini-program preview QR | mini-program preview QR |
+| `tta` (mini-program) | mini-program preview QR | mini-program preview QR |
+
+## BDD E2E Targets
+
+| Test | Target |
+|------|--------|
+| `apps/backend/tests/e2e/` | `BACKEND_URL` |
+| `apps/web/tests/e2e/` | `WEB_URL` + `BACKEND_URL` (as API root) |
+| `apps/native/tests/e2e/` | `BACKEND_URL` (built into app) |
+| `apps/desktop/tests/e2e/` | `BACKEND_URL` (built into app) |
+| `apps/wxa/tests/e2e/` | `BACKEND_URL` (built into app) |
+| `apps/mya/tests/e2e/` | `BACKEND_URL` (built into app) |
+| `apps/tta/tests/e2e/` | `BACKEND_URL` (built into app) |
+| `aidlc/tests/cross-stack/` | `STACK_URL` (full flow) |
+
+## Dynamic Preview URL
+
+Preview URLs are resolved at deploy time based on the active provider:
+
+- **TCB:** `deploy_stack --preview --provider tcb` → `STACK_URL=https://{env-id}.tcb-preview.com`
+- **Aliyun:** `deploy_stack --preview --provider aliyun` → `STACK_URL=https://{gateway}.{region}.fc.devs.com`
+
+Set as `STACK_URL` / `BACKEND_URL` / `WEB_URL` / per-component URLs as environment variables for BDD e2e tests:
+
+```bash
+export STACK_URL=$(deploy_stack --preview --output url)
+export BACKEND_URL=$STACK_URL
+export WEB_URL=$(deploy_stack --preview --output web_url)
+export NATIVE_URL=$(deploy_stack --preview --output native_url)
+export DESKTOP_URL=$(deploy_stack --preview --output desktop_url)
+pytest apps/web/tests/e2e/ --base-url $WEB_URL --api-url $BACKEND_URL
+pytest apps/native/tests/e2e/ --backend-url $BACKEND_URL
+pytest apps/desktop/tests/e2e/ --backend-url $BACKEND_URL
+pytest aidlc/tests/cross-stack/ --stack-url $STACK_URL
+```
+
+## Stack Rollback
+
+Rollback is at the **stack** level: backend and all client components revert together to the last stable stack version.
+
+```bash
+deploy_stack --rollback ${LAST_STABLE_STACK_VERSION} --provider tcb
+```