From 18d6d2922771cf5f37c4ec7ba14dc92e62c7fe08 Mon Sep 17 00:00:00 2001 From: zichun Date: Tue, 21 Apr 2026 10:32:33 +0800 Subject: [PATCH] init --- .claude-plugin/plugin.json | 6 ++++++ README.md | 227 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_CLAUDE.md | 364 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_commands/erp-session-start.md | 5 +++++ _pl_staging/pl_hooks/deny-no-verify.sh | 18 ++++++++++++++++++ _pl_staging/pl_hooks/guard-confirmed-flip.sh | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_hooks/log-cross-module.sh | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_hooks/log-ddl.sh | 43 +++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_hooks/session-start-dispatch.sh | 6 ++++++ _pl_staging/pl_settings.json | 39 +++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_settings.local.json | 21 +++++++++++++++++++++ _pl_staging/pl_skills/erp-confirmed-update/SKILL.md | 35 +++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-confirmed-update/templates/confirmed-flip-commit-template.md | 1 + _pl_staging/pl_skills/erp-confirmed-update/templates/docs-08-flip-diff-template.md | 12 ++++++++++++ _pl_staging/pl_skills/erp-cross-module-log/SKILL.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-row-template.md | 1 + _pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-template.md | 6 ++++++ _pl_staging/pl_skills/erp-downstream-gen/SKILL.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-02-template.md | 19 +++++++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-endpoint-template.md | 24 ++++++++++++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-header-template.md | 30 ++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-06-module-pagelist-template.md | 9 +++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-header-template.md | 9 +++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-module-row-template.md | 6 ++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-header-template.md | 14 ++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-module-template.md | 18 ++++++++++++++++++ _pl_staging/pl_skills/erp-downstream-gen/templates/seed-data-sql-template.sql | 15 +++++++++++++++ _pl_staging/pl_skills/erp-feature-brainstorm/SKILL.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-brainstorm/templates/feature-spec-template.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-plan/SKILL.md | 26 ++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-plan/templates/feature-plan-template.md | 25 +++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-review/SKILL.md | 22 ++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-review/templates/feature-review-template.md | 24 ++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-tdd/SKILL.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-tdd/templates/commit-message-template.md | 1 + _pl_staging/pl_skills/erp-feature-verify/SKILL.md | 32 ++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-feature-verify/templates/feature-verify-evidence-template.md | 16 ++++++++++++++++ _pl_staging/pl_skills/erp-local-test-gate/SKILL.md | 37 +++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-local-test-gate/templates/test-gate-result-template.md | 22 ++++++++++++++++++++++ _pl_staging/pl_skills/erp-module-report/SKILL.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-module-report/templates/module-report-template.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-module-start/SKILL.md | 31 +++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-module-start/templates/cross-module-log-template.md | 6 ++++++ _pl_staging/pl_skills/erp-module-start/templates/module-start-banner-template.md | 10 ++++++++++ _pl_staging/pl_skills/erp-module-start/templates/schema-scratch-log-template.md | 6 ++++++ _pl_staging/pl_skills/erp-mr-create/SKILL.md | 34 ++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-mr-create/templates/mr-description-template.md | 20 ++++++++++++++++++++ _pl_staging/pl_skills/erp-mr-create/templates/mr-title-template.md | 1 + _pl_staging/pl_skills/erp-mysql-mcp-setup/SKILL.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-mysql-mcp-setup/templates/mcp-json-template.json | 15 +++++++++++++++ _pl_staging/pl_skills/erp-placeholder-scan/SKILL.md | 40 ++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-placeholder-scan/templates/placeholder-scan-result-template.md | 13 +++++++++++++ _pl_staging/pl_skills/erp-red-flag-check/SKILL.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-red-flag-check/templates/red-flag-block-template.md | 8 ++++++++ _pl_staging/pl_skills/erp-requirements-gen/SKILL.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-requirements-gen/templates/docs-01-module-template.md | 11 +++++++++++ _pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-header-template.md | 14 ++++++++++++++ _pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-table-template.md | 22 ++++++++++++++++++++++ _pl_staging/pl_skills/erp-requirements-gen/templates/req-card-template.md | 10 ++++++++++ _pl_staging/pl_skills/erp-schema-baseline-check/SKILL.md | 34 ++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-schema-baseline-check/templates/schema-baseline-diff-template.md | 16 ++++++++++++++++ _pl_staging/pl_skills/erp-schema-scratch-log/SKILL.md | 33 +++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-row-template.md | 1 + _pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-template.md | 6 ++++++ _pl_staging/pl_skills/erp-session-start/SKILL.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/SKILL.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-04-skeleton-template.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-06-static-template.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-07-env-template.md | 37 +++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-09-structure-template.md | 25 +++++++++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/env-local-example-template | 6 ++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/githooks-pre-push-template.sh | 9 +++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh | 19 +++++++++++++++++++ _pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-test-sh-template.sh | 26 ++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-tech-stack-lock/SKILL.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-tech-stack-lock/templates/claude-md-header-template.md | 16 ++++++++++++++++ _pl_staging/pl_skills/erp-understanding-report/SKILL.md | 36 ++++++++++++++++++++++++++++++++++++ _pl_staging/pl_skills/erp-understanding-report/templates/understanding-report-template.md | 25 +++++++++++++++++++++++++ _pl_staging/pl_指南.md | 617 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ hooks/hooks.json | 20 ++++++++++++++++++++ hooks/scripts/deny-no-verify.sh | 18 ++++++++++++++++++ hooks/scripts/log-cross-module.sh | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-brainstorm/SKILL.md | 39 +++++++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-brainstorm/templates/feature-spec-template.md | 31 +++++++++++++++++++++++++++++++ skills/coding/erp-feature-plan/SKILL.md | 34 ++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-plan/templates/feature-plan-template.md | 28 ++++++++++++++++++++++++++++ skills/coding/erp-feature-review/SKILL.md | 41 +++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-review/templates/feature-review-template.md | 24 ++++++++++++++++++++++++ skills/coding/erp-feature-tdd/SKILL.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-tdd/templates/commit-message-template.md | 1 + skills/coding/erp-feature-verify/SKILL.md | 40 ++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-feature-verify/templates/feature-verify-evidence-template.md | 16 ++++++++++++++++ skills/coding/erp-local-test-gate/SKILL.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-local-test-gate/templates/test-gate-result-template.md | 16 ++++++++++++++++ skills/coding/erp-module-report/SKILL.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-module-report/templates/module-report-template.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-module-start/SKILL.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-module-start/templates/cross-module-log-template.md | 8 ++++++++ skills/coding/erp-module-start/templates/module-start-banner-template.md | 11 +++++++++++ skills/coding/erp-mr-create/SKILL.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/coding/erp-mr-create/templates/mr-description-template.md | 18 ++++++++++++++++++ skills/coding/erp-mr-create/templates/mr-title-template.md | 1 + skills/crosscut/erp-coding-start/SKILL.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/crosscut/erp-cross-module-log/SKILL.md | 37 +++++++++++++++++++++++++++++++++++++ skills/crosscut/erp-cross-module-log/templates/cross-module-log-row-template.md | 1 + skills/crosscut/erp-cross-module-log/templates/cross-module-log-template.md | 8 ++++++++ skills/crosscut/erp-plan-start/SKILL.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/crosscut/erp-red-flag-check/SKILL.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md | 8 ++++++++ skills/plan/erp-db-design-gen/SKILL.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-db-design-gen/templates/docs-03-header-template.md | 14 ++++++++++++++ skills/plan/erp-db-design-gen/templates/docs-03-table-template.md | 22 ++++++++++++++++++++++ skills/plan/erp-db-init/SKILL.md | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-downstream-gen/SKILL.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-downstream-gen/templates/docs-02-template.md | 24 ++++++++++++++++++++++++ skills/plan/erp-downstream-gen/templates/docs-05-endpoint-template.md | 24 ++++++++++++++++++++++++ skills/plan/erp-downstream-gen/templates/docs-05-header-template.md | 30 ++++++++++++++++++++++++++++++ skills/plan/erp-downstream-gen/templates/docs-06-module-pagelist-template.md | 9 +++++++++ skills/plan/erp-downstream-gen/templates/docs-08-module-row-template.md | 4 ++++ skills/plan/erp-downstream-gen/templates/docs-10-header-template.md | 14 ++++++++++++++ skills/plan/erp-downstream-gen/templates/docs-10-module-template.md | 18 ++++++++++++++++++ skills/plan/erp-project-init/SKILL.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-project-init/templates/CLAUDE-template.md | 336 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-project-init/templates/docs-01-readme-template.md | 16 ++++++++++++++++ skills/plan/erp-project-init/templates/docs-08-initial-template.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-scope-lock/SKILL.md | 234 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-scope-lock/templates/docs-01-module-template.md | 11 +++++++++++ skills/plan/erp-scope-lock/templates/req-card-template.md | 10 ++++++++++ skills/plan/erp-skeleton-gen/SKILL.md | 304 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/scripts/merge-gitignore.sh | 39 +++++++++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/docs-04-skeleton-template.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/docs-06-static-template.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/docs-07-env-template.md | 26 ++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/docs-09-structure-template.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/env-local-template | 6 ++++++ skills/plan/erp-skeleton-gen/templates/githooks-pre-push-template.sh | 9 +++++++++ skills/plan/erp-skeleton-gen/templates/gitignore-append-template | 32 ++++++++++++++++++++++++++++++++ skills/plan/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh | 20 ++++++++++++++++++++ 138 files changed, 6277 insertions(+), 0 deletions(-) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 _pl_staging/pl_CLAUDE.md create mode 100644 _pl_staging/pl_commands/erp-session-start.md create mode 100755 _pl_staging/pl_hooks/deny-no-verify.sh create mode 100755 _pl_staging/pl_hooks/guard-confirmed-flip.sh create mode 100755 _pl_staging/pl_hooks/log-cross-module.sh create mode 100755 _pl_staging/pl_hooks/log-ddl.sh create mode 100755 _pl_staging/pl_hooks/session-start-dispatch.sh create mode 100644 _pl_staging/pl_settings.json create mode 100644 _pl_staging/pl_settings.local.json create mode 100644 _pl_staging/pl_skills/erp-confirmed-update/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-confirmed-update/templates/confirmed-flip-commit-template.md create mode 100644 _pl_staging/pl_skills/erp-confirmed-update/templates/docs-08-flip-diff-template.md create mode 100644 _pl_staging/pl_skills/erp-cross-module-log/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-row-template.md create mode 100644 _pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-02-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-endpoint-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-header-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-06-module-pagelist-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-header-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-module-row-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-header-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-module-template.md create mode 100644 _pl_staging/pl_skills/erp-downstream-gen/templates/seed-data-sql-template.sql create mode 100644 _pl_staging/pl_skills/erp-feature-brainstorm/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-feature-brainstorm/templates/feature-spec-template.md create mode 100644 _pl_staging/pl_skills/erp-feature-plan/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-feature-plan/templates/feature-plan-template.md create mode 100644 _pl_staging/pl_skills/erp-feature-review/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-feature-review/templates/feature-review-template.md create mode 100644 _pl_staging/pl_skills/erp-feature-tdd/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-feature-tdd/templates/commit-message-template.md create mode 100644 _pl_staging/pl_skills/erp-feature-verify/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-feature-verify/templates/feature-verify-evidence-template.md create mode 100644 _pl_staging/pl_skills/erp-local-test-gate/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-local-test-gate/templates/test-gate-result-template.md create mode 100644 _pl_staging/pl_skills/erp-module-report/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-module-report/templates/module-report-template.md create mode 100644 _pl_staging/pl_skills/erp-module-start/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-module-start/templates/cross-module-log-template.md create mode 100644 _pl_staging/pl_skills/erp-module-start/templates/module-start-banner-template.md create mode 100644 _pl_staging/pl_skills/erp-module-start/templates/schema-scratch-log-template.md create mode 100644 _pl_staging/pl_skills/erp-mr-create/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-mr-create/templates/mr-description-template.md create mode 100644 _pl_staging/pl_skills/erp-mr-create/templates/mr-title-template.md create mode 100644 _pl_staging/pl_skills/erp-mysql-mcp-setup/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-mysql-mcp-setup/templates/mcp-json-template.json create mode 100644 _pl_staging/pl_skills/erp-placeholder-scan/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-placeholder-scan/templates/placeholder-scan-result-template.md create mode 100644 _pl_staging/pl_skills/erp-red-flag-check/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-red-flag-check/templates/red-flag-block-template.md create mode 100644 _pl_staging/pl_skills/erp-requirements-gen/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-requirements-gen/templates/docs-01-module-template.md create mode 100644 _pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-header-template.md create mode 100644 _pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-table-template.md create mode 100644 _pl_staging/pl_skills/erp-requirements-gen/templates/req-card-template.md create mode 100644 _pl_staging/pl_skills/erp-schema-baseline-check/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-schema-baseline-check/templates/schema-baseline-diff-template.md create mode 100644 _pl_staging/pl_skills/erp-schema-scratch-log/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-row-template.md create mode 100644 _pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-template.md create mode 100644 _pl_staging/pl_skills/erp-session-start/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-04-skeleton-template.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-06-static-template.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-07-env-template.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/docs-09-structure-template.md create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/env-local-example-template create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/githooks-pre-push-template.sh create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh create mode 100644 _pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-test-sh-template.sh create mode 100644 _pl_staging/pl_skills/erp-tech-stack-lock/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-tech-stack-lock/templates/claude-md-header-template.md create mode 100644 _pl_staging/pl_skills/erp-understanding-report/SKILL.md create mode 100644 _pl_staging/pl_skills/erp-understanding-report/templates/understanding-report-template.md create mode 100644 _pl_staging/pl_指南.md create mode 100644 hooks/hooks.json create mode 100755 hooks/scripts/deny-no-verify.sh create mode 100755 hooks/scripts/log-cross-module.sh create mode 100644 skills/coding/erp-feature-brainstorm/SKILL.md create mode 100644 skills/coding/erp-feature-brainstorm/templates/feature-spec-template.md create mode 100644 skills/coding/erp-feature-plan/SKILL.md create mode 100644 skills/coding/erp-feature-plan/templates/feature-plan-template.md create mode 100644 skills/coding/erp-feature-review/SKILL.md create mode 100644 skills/coding/erp-feature-review/templates/feature-review-template.md create mode 100644 skills/coding/erp-feature-tdd/SKILL.md create mode 100644 skills/coding/erp-feature-tdd/templates/commit-message-template.md create mode 100644 skills/coding/erp-feature-verify/SKILL.md create mode 100644 skills/coding/erp-feature-verify/templates/feature-verify-evidence-template.md create mode 100644 skills/coding/erp-local-test-gate/SKILL.md create mode 100644 skills/coding/erp-local-test-gate/templates/test-gate-result-template.md create mode 100644 skills/coding/erp-module-report/SKILL.md create mode 100644 skills/coding/erp-module-report/templates/module-report-template.md create mode 100644 skills/coding/erp-module-start/SKILL.md create mode 100644 skills/coding/erp-module-start/templates/cross-module-log-template.md create mode 100644 skills/coding/erp-module-start/templates/module-start-banner-template.md create mode 100644 skills/coding/erp-mr-create/SKILL.md create mode 100644 skills/coding/erp-mr-create/templates/mr-description-template.md create mode 100644 skills/coding/erp-mr-create/templates/mr-title-template.md create mode 100644 skills/crosscut/erp-coding-start/SKILL.md create mode 100644 skills/crosscut/erp-cross-module-log/SKILL.md create mode 100644 skills/crosscut/erp-cross-module-log/templates/cross-module-log-row-template.md create mode 100644 skills/crosscut/erp-cross-module-log/templates/cross-module-log-template.md create mode 100644 skills/crosscut/erp-plan-start/SKILL.md create mode 100644 skills/crosscut/erp-red-flag-check/SKILL.md create mode 100644 skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md create mode 100644 skills/plan/erp-db-design-gen/SKILL.md create mode 100644 skills/plan/erp-db-design-gen/templates/docs-03-header-template.md create mode 100644 skills/plan/erp-db-design-gen/templates/docs-03-table-template.md create mode 100644 skills/plan/erp-db-init/SKILL.md create mode 100644 skills/plan/erp-downstream-gen/SKILL.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-02-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-05-endpoint-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-05-header-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-06-module-pagelist-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-08-module-row-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-10-header-template.md create mode 100644 skills/plan/erp-downstream-gen/templates/docs-10-module-template.md create mode 100644 skills/plan/erp-project-init/SKILL.md create mode 100644 skills/plan/erp-project-init/templates/CLAUDE-template.md create mode 100644 skills/plan/erp-project-init/templates/docs-01-readme-template.md create mode 100644 skills/plan/erp-project-init/templates/docs-08-initial-template.md create mode 100644 skills/plan/erp-scope-lock/SKILL.md create mode 100644 skills/plan/erp-scope-lock/templates/docs-01-module-template.md create mode 100644 skills/plan/erp-scope-lock/templates/req-card-template.md create mode 100644 skills/plan/erp-skeleton-gen/SKILL.md create mode 100755 skills/plan/erp-skeleton-gen/scripts/merge-gitignore.sh create mode 100644 skills/plan/erp-skeleton-gen/templates/docs-04-skeleton-template.md create mode 100644 skills/plan/erp-skeleton-gen/templates/docs-06-static-template.md create mode 100644 skills/plan/erp-skeleton-gen/templates/docs-07-env-template.md create mode 100644 skills/plan/erp-skeleton-gen/templates/docs-09-structure-template.md create mode 100644 skills/plan/erp-skeleton-gen/templates/env-local-template create mode 100644 skills/plan/erp-skeleton-gen/templates/githooks-pre-push-template.sh create mode 100644 skills/plan/erp-skeleton-gen/templates/gitignore-append-template create mode 100644 skills/plan/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..cf92522 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "erp-workflow", + "description": "ERP 项目全流程框架：阶段 A 计划（一次性） + 阶段 B 编码（模块循环 + 功能循环），含完整 skill 流水线 + 守门 hook + 软规则留痕。专为后端 Spring Boot + 前端 React + MySQL 8 的 ERP/管理类系统设计。", + "version": "0.1.0", + "skills": ["./skills/plan", "./skills/coding", "./skills/crosscut"] +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..c46c1b8 --- /dev/null +++ b/README.md @@ -0,0 +1,227 @@ +# erp-workflow + +Claude Code 插件：ERP / 后端管理系统全流程开发框架。 + +把"从零到 N 个模块上线"的整个流程固化成 **19 个 skill + 2 个 hook + 38 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、人工审核可控的前提下推进编码。 + +## 这个插件做什么 + +``` +📋 阶段 A：规划（一次性，入口 /erp-workflow:erp-plan-start） + 初始化项目 → 锁范围（REQ 卡片生成） + ↓ + ⏸ 审阅 REQ 卡片 → 重跑 /erp-plan-start 继续 + ↓ + 生骨架 → 初始化 DB（V1 migration + seed）→ 生 DB 设计 → 生下游文档 + ↓ + 用户显式 /erp-workflow:erp-coding-start + +🔁 阶段 B：编码（按模块循环，入口 /erp-workflow:erp-coding-start） + 功能循环：Brainstorm → Plan → TDD → Verify → Review + 模块循环：本地测试闸门 → 写模块报告 → 建 GitLab MR → ⏸ 用户 Approve+Merge → 下次 coding-start 自动扫 MR merged → 下一模块 + +⚙️ 后台守门：占位符未填 / 红旗触发 / 跨模块改动未记录 +``` + +## 安装 + +### 方式 1：本地测试（开发期） + +```bash +claude --plugin-dir /path/to/erp-workflow-plugin +``` + +### 方式 2：从 marketplace 安装（发布后） + +``` +/plugin install erp-workflow@ +``` + +详见官方文档 [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins)。 + +## 首次使用 + +1. **进入空项目目录并启动 Claude Code**： + ```bash + mkdir my-erp && cd my-erp + claude --plugin-dir /path/to/erp-workflow-plugin + ``` + +2. **Plan 阶段入口**（一次性规划）： + ``` + /erp-workflow:erp-plan-start + ``` + Plan 阶段**两段式**执行，中间有一个 REQ 审阅断点： + + - **第一段（首次运行）**：跑 **A0 → A1**（创建骨架 / 锁技术栈 / 填需求 / 生成 REQ 卡片）后**停下**，等你审阅 `docs/01-需求清单/*.md` 里的 REQ 卡片（这是 Plan 阶段最关键的人工关口） + - **第二段（审阅完重跑同一命令）**：继续 **A2 → A5**（生骨架 / 初始化 DB / 生设计 / 生下游文档），Plan 完成后再次**停下** + + 每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次跑同样的命令就能恢复。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:erp-coding-start`。 + +3. **Coding 阶段入口**（模块循环）： + ``` + /erp-workflow:erp-coding-start + ``` + Plan 全部完成后由你显式触发。**按 `docs/02 § 二` REQ 开发顺序清单**扫描决定当前模块： + 对每个 REQ 所属模块查 `docs/08` 的 `MR:` 字段 + `glab mr view state`： + - `state == merged` → 模块已完成，跳过 + - `MR: —` / opened / closed / 查不到 → 该模块是当前模块 + + 之后 `git checkout main` + `git pull --ff-only` 同步远程 main（保证下次 module 分支切出时 base 新鲜），再派发到 `erp-module-start`。 + + **`docs/08 § 二` 每模块是 bullet（`- module_id ...`，无 checkbox）**——完成信号由 MR merged state 判定。原来的"翻勾 `[x]`"动作已从结构上消除，彻底消灭 Codex adversarial review Finding 1 的"用户抢跑 coding-start 跳过未合并模块"的 ordering bug。 + +4. **中途恢复**：任何时候跑对应入口命令——根据 Plan § 一 checkbox 和 § 二 各模块 MR state 跳到当前该做的事。 + +## 目录结构 + +``` +erp-workflow-plugin/ +├── .claude-plugin/ +│ └── plugin.json # 插件清单，声明 skills 三个子目录 +├── README.md # 本文档 +├── hooks/ +│ ├── hooks.json # hook 注册表（2 个 hook） +│ └── scripts/*.sh # 2 个 hook 脚本 +└── skills/ + ├── plan/ # 阶段 A：6 个一次性规划 skill + ├── coding/ # 阶段 B：9 个模块/功能循环 skill + └── crosscut/ # 横切：2 个入口 + 1 红旗 + 1 留痕 skill +``` + +插件加载时按 `plugin.json` 的 `skills: ["./skills/plan", "./skills/coding", "./skills/crosscut"]` 扫描。skill 名称不含子目录前缀（如 `/erp-workflow:erp-scope-lock`）。 + +## Hook 清单（2 个，全部在 hooks/hooks.json 注册） + +| Hook | 脚本 | 事件 | 触发条件 | 作用 | +|---|---|---|---|---| +| 拒绝 no-verify | `deny-no-verify.sh` | PreToolUse / Bash | CC 尝试 `git push --no-verify` | 硬拦截，强制 `.githooks/pre-push` 生效 | +| 跨模块改动留痕 | `log-cross-module.sh` | PostToolUse / Edit \| Write | 当前处于 `module-*` 分支 且 编辑目标路径落在 `docs/08 § 二` 中**非当前模块**的 path 范围内（无论目标模块 MR 是否已 merged） | 把改动追加为 `TBD(CC 补)` 存根到 `-cross-module.md`；通过 `additionalContext` 软提示 CC 调 `erp-cross-module-log` skill **自主推断**补「原因 / 影响评估」两列。即时性由 CC 自己决定；**最迟在 `erp-module-report` § ⑦ 硬闸门处**（TBD 未清空会阻断模块完成报告），保证模块完成前所有 TBD 必被 CC 填实 | + +**流程使用情况**：2 个 hook 全部在 hooks.json 注册、被 CC 自动触发。 + +## Skill 清单（19 个） + +### Plan 阶段（6 个，`skills/plan/`） + +| # | Skill | 作用 | 流程中谁调用 | +|---|---|---|---| +| A0 | `erp-project-init` | • 依赖检查（`mysql` / `mysqldump` 在 PATH，缺失则尝试自动安装）
• 空目录初始化：`cp` 模板创建 CLAUDE.md / docs/01/README.md / docs/08
• `git init` | `erp-plan-start` | +| A1 | `erp-scope-lock` | • 引导填项目概述 / 技术栈 / 需求索引
• 生成 REQ 卡片（`schema_refs=TBD(A4 自动补)`、`api_refs=TBD(A5 自动补)`）
• **停下**等人工审阅 REQ 卡片，审阅完毕用 `/erp-plan-start` 恢复续进 A2 | A0 | +| A2 | `erp-skeleton-gen` | • 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09
• 生成工具脚本：scripts/*.sh、.githooks/pre-push、.env.local
• 创建 `sql/migrations/` 空目录（Flyway 准备）
• 合并 .gitignore（逐行判重） | `erp-plan-start` | +| A3 | `erp-db-init` | • 验证 MySQL 连接
• 导出 schema 为 `sql/migrations/V1__initial_schema.sql`（DDL only）
• 导出数据为 `sql/seed-data.sql`（INSERT only） | A2 | +| A4 | `erp-db-design-gen` | • 生成 `docs/03-数据库设计文档.md`
• 回填 REQ 卡片依赖表（`TBD(A4 自动补)` → 实际表名）
• schema 一致性检查 | A3 | +| A5 | `erp-downstream-gen` | • 一次性生成 docs/02 / docs/05 / docs/06 § 五 / docs/10
• 回填 REQ 卡片依赖接口（`TBD(A5 自动补)` → 实际 endpoint）
• 追加模块清单到 docs/08 § 二
• 最终占位符扫描（TBD 自动补 + `【人工填写：】` QA 循环）
• 打印 Plan 完成横幅并**停下**（不自动进 B） | A4 | + +### Coding 阶段（9 个，`skills/coding/`） + +**触发与顺序**（`erp-coding-start` 是唯一由用户手动触发的入口，下面所有 skill 都由 skill 链自动调用）： + +``` +/erp-workflow:erp-coding-start ← 用户每次手动触发 + │ + │ 扫 docs/02 REQ 序 + docs/08 MR 字段 + glab mr view state 判当前模块： + │ - 所有模块都 merged → 打印"所有模块已完成" + │ - 找到第一个非 merged 模块 → 派发 + │ 派发前 git checkout main + git pull --ff-only（同步远程 base） + │ + └─→ erp-module-start（幂等可重入，切 module- 分支） + │ + │ 对每个未完成 REQ，按序串链： + │ erp-feature-brainstorm → -plan → -tdd → -verify → -review + │ + │ review approve → 回 erp-module-start（推进下一 REQ） + │ review request-changes (<5) → fix commit → 回 erp-feature-verify 重跑 + │ review request-changes (=5) → 停下（升级给人） + │ + │ 模块全部 REQ approve → + │ erp-local-test-gate（commit test-gate.md） + │ → erp-module-report（commit 模块报告 + cross-module log） + │ → erp-mr-create（worktree clean 校验 → push 代码+evidence → 建 MR + │ → 追 MR URL 到报告 + commit → 写 MR iid 到 docs/08 + commit + │ → 再 push；docs/08 无 checkbox） + │ + └─ ⏸ 停下等人工 Approve + Merge + （人工合并后再跑 coding-start，扫到 state=merged 自动跳过 + → pull main → 推进下一模块） +``` + +| Skill | 做什么 | 谁触发它 | +|---|---|---| +| `erp-module-start` | 定位当前模块（docs/02 REQ 序）+ 切/建 `module-` 分支 + 扫 `docs/superpowers/reviews/*.md` 的 `verdict=approve` 算已完成 REQ + 推进第一个未完成 REQ 的功能循环。全部完成 → `erp-local-test-gate`。**幂等可重入**（中途断开再跑自动跳过已 approve 的 REQ） | `erp-coding-start` 派发；`erp-feature-review` approve 后回调 | +| `erp-feature-brainstorm` | 功能循环步骤 1：交互 brainstorm → 生成 `docs/superpowers/specs/*.md` | `erp-module-start` 推进 REQ 时调用 | +| `erp-feature-plan` | 功能循环步骤 2：spec → 任务级 plan（含文件路径 + 完整代码），输出 `docs/superpowers/plans/*.md` | `erp-feature-brainstorm` 链式调用 | +| `erp-feature-tdd` | 功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 `module-` 分支） | `erp-feature-plan` 链式调用 | +| `erp-feature-verify` | 功能循环步骤 4：全测试套件派子会话跑一次，用模板渲染 evidence | `erp-feature-tdd` 链式调用；`erp-feature-review` 在 request-changes 修复后重跑 | +| `erp-feature-review` | 功能循环步骤 5：AI 自审，写 `docs/superpowers/reviews/*.md`。approve → 回 `erp-module-start`；request-changes → 逐项 Edit + fix commit → 回 `erp-feature-verify` 重跑（最多 5 轮，第 5 轮仍 request-changes 则停下） | `erp-feature-verify` 链式调用 | +| `erp-local-test-gate` | MR 前硬闸门：子会话跑 `scripts/test.sh`（脚本内部 drop+create 空库、Flyway apply `sql/migrations/V*.sql`、再跑测试）；通过 → 写 `-test-gate.md` 并 `git add + commit`（evidence 进 module 分支）；失败停下 | `erp-module-start` 在本模块所有 REQ approve 后调用 | +| `erp-module-report` | 红旗检查 → 生成 12 节模块完成报告 `docs/superpowers/module-reports/-.md` → `git add + commit`（报告 + cross-module log 进 module 分支，erp-mr-create 的 worktree clean 前置条件依赖此步） | `erp-local-test-gate` 链式调用 | +| `erp-mr-create` | 红旗检查 → 验证当前分支 = `module-` + `git status --porcelain` worktree 干净 → `git push` 推代码和所有 evidence → `glab mr create`（模块报告嵌入 MR 描述）→ 追 MR URL 到报告 + commit → 回写 `MR: —` → `MR: !` 到 docs/08 + commit → 再次 push；**停下等人工 Approve+Merge**。docs/08 § 二是模块元数据 bullet（无 checkbox），完成由 MR state 判定 | `erp-module-report` 链式调用 | + +### Crosscut（4 个，`skills/crosscut/`） + +| Skill | 作用 | 流程中谁调用 | +|---|---|---| +| `erp-plan-start` | **A 阶段入口**。读 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:erp-plan-start` | +| `erp-coding-start` | **B 阶段入口**。先验证 Plan 已完成；**按 `docs/02 § 二` REQ 序扫**，对每个 REQ 所属模块查 `MR: 字段 + glab mr view state`：`merged` 跳过；`—`/opened/closed/查不到 选为当前模块。派发前 `git checkout main + git pull --ff-only` 同步远程 base，然后调 `erp-module-start` | **用户手动**运行 `/erp-workflow:erp-coding-start` | +| `erp-red-flag-check` | 检查 CLAUDE.md 的 6 项红旗清单；命中则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 | +| `erp-cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根补「原因 / 影响评估」 | 用户看到 hook 提示后调用；`erp-module-start` 初始化日志文件时也会用其模板 | + +## Templates 清单（38 份） + +| 所属 Skill | 模板文件 | 用途 | +|---|---|---| +| erp-project-init | `CLAUDE-template.md` | 项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定） | +| erp-project-init | `docs-01-readme-template.md` | 需求清单索引骨架，等用户填模块表 | +| erp-project-init | `docs-08-initial-template.md` | 工作流进度文件骨架（Plan A0~A5 checkbox） | +| erp-scope-lock | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片字段结构 | +| erp-scope-lock | `docs-01-module-template.md` | 单模块 `-.md` 外壳 | +| erp-skeleton-gen | `docs-04-skeleton-template.md` | docs/04 § 一+ 编码规范大纲（HTML 注释引导 LLM） | +| erp-skeleton-gen | `docs-06-static-template.md` | docs/06 § 一~四 UI 模式大纲 | +| erp-skeleton-gen | `docs-07-env-template.md` | docs/07 环境配置大纲 | +| erp-skeleton-gen | `docs-09-structure-template.md` | docs/09 目录结构大纲 | +| erp-skeleton-gen | `scripts-setup-test-db-template.sh` | 运行时 drop + create 空库脚本（0 槽位）；schema apply 交给 Flyway | +| erp-skeleton-gen | `githooks-pre-push-template.sh` | pre-push → 调 scripts/test.sh（0 槽位） | +| erp-skeleton-gen | `env-local-template` | 6 字段凭据模板（DB_* + JWT_SECRET） | +| erp-skeleton-gen | `gitignore-append-template` | 插件推荐忽略项（`.env.local`、`.tmp/`、构建产物等） | +| erp-db-init | `migration-v1-header-template.sql` | V1 initial migration 文件头部注释 | +| erp-db-init | `seed-data-sql-template.sql` | seed-data.sql 文件头部注释 | +| erp-db-design-gen | `docs-03-header-template.md` | docs/03 数据库设计头部 | +| erp-db-design-gen | `docs-03-table-template.md` | docs/03 单表小节模板 | +| erp-downstream-gen | `docs-02-template.md` | docs/02 开发计划 | +| erp-downstream-gen | `docs-05-header-template.md` | docs/05 API 契约头部 | +| erp-downstream-gen | `docs-05-endpoint-template.md` | docs/05 单接口小节 | +| erp-downstream-gen | `docs-06-module-pagelist-template.md` | docs/06 § 五 单模块页面清单 | +| erp-downstream-gen | `docs-08-module-row-template.md` | docs/08 § 二 单模块 bullet 行 | +| erp-downstream-gen | `docs-10-header-template.md` | docs/10 验收清单头部 | +| erp-downstream-gen | `docs-10-module-template.md` | docs/10 单模块验收项 | +| erp-module-start | `module-start-banner-template.md` | 模块启动横幅 | +| erp-module-start | `cross-module-log-template.md` | cross-module 日志头（副本） | +| erp-feature-brainstorm | `feature-spec-template.md` | 功能 spec 结构 | +| erp-feature-plan | `feature-plan-template.md` | 功能 plan 结构 | +| erp-feature-tdd | `commit-message-template.md` | TDD 每步 commit 信息 | +| erp-feature-verify | `feature-verify-evidence-template.md` | 验证证据渲染模板 | +| erp-feature-review | `feature-review-template.md` | 自审报告结构 | +| erp-local-test-gate | `test-gate-result-template.md` | 闸门结果渲染 | +| erp-module-report | `module-report-template.md` | 12 节模块报告 | +| erp-mr-create | `mr-title-template.md` | MR 标题模板 | +| erp-mr-create | `mr-description-template.md` | MR 描述模板（嵌入模块报告） | +| erp-red-flag-check | `red-flag-block-template.md` | Blocker 节追加模板 | +| erp-cross-module-log | `cross-module-log-template.md` | cross-module 日志头（主本） | +| erp-cross-module-log | `cross-module-log-row-template.md` | 单条改动行模板 | + +**流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。 + +## 前置依赖 + +- **MySQL 8.x** 实例已建好（CC 不跑 DDL；schema 由人工初始化） +- **`mysql` / `mysqldump` 命令行**：`erp-db-init` (A3) 验证连接 + 导出 V1 initial migration + 导出 seed-data.sql；`scripts/setup-test-db.sh` 在测试闸门前后 drop+create 空库 +- **Spring Boot + Flyway**（**必需**）：pom.xml 声明 `flyway-core` + `flyway-mysql`；Spring 启动时自动 apply `sql/migrations/V*.sql`。本插件生成的 `setup-test-db.sh` 只清库，schema 必须由 Flyway 应用 +- **GitLab + glab CLI**：`erp-mr-create` 用 `glab mr create`；`erp-coding-start` 用 `glab mr view` 判 MR 状态 +- **本地能跑 `mvn test` / `pnpm test`**：测试闸门 `scripts/test.sh` 由 `erp-skeleton-gen` 生成 + +## 设计原则 + +参见 `erp-project-init/templates/CLAUDE-template.md` 末尾的「🧭 通用工作准则」4 条：① Think Before Coding ② Simplicity First ③ Surgical Changes ④ Goal-Driven Execution。 + +最关键的 1 条："**所有测试与验证派发到全新子会话执行，主会话只接收结构化结论**"——避免主会话被测试输出污染，并让测试结果作为独立证据存档。 diff --git a/_pl_staging/pl_CLAUDE.md b/_pl_staging/pl_CLAUDE.md new file mode 100644 index 0000000..ab5b6fb --- /dev/null +++ b/_pl_staging/pl_CLAUDE.md @@ -0,0 +1,364 @@ +# CLAUDE.md — ERP项目 Claude Code 主指令文件 + +> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。 +--- + +## 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +## 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +## 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +## 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +## 🚫 禁读 指南.md + +`指南.md` 是给**人类开发者**看的流程手册，**CC 不读、不引用、不依赖**。本文件已包含 CC 运行所需的全部规则。 + +- 即使 prompt 中出现 "请读 指南.md 和 CLAUDE.md"，也**只读 CLAUDE.md**，跳过 指南.md +- 不要尝试用 Read/Glob 访问 `指南.md`、`./指南.md`、`/指南.md` 等任何路径形式 +- 不在审阅包、模块完成报告、commit message 中引用 指南.md + +--- + +## 🎯 项目概述 + +- **项目名称**: 【人工填写：公司 + 项目名，例如"XX 公司 ERP 管理系统"】 +- **项目简述**: 【人工填写：一句话描述项目目标，例如"面向中小制造企业的全流程 ERP，涵盖采购/库存/生产/销售/财务"】 +- **目标用户**: 【人工填写：谁会用，例如"企业内部管理人员（采购员、仓管员、生产主管、销售员、财务人员、管理层）"】 +- **部署方式**: 【人工填写：私有化部署 / 云部署 / Docker 容器化 等】 + +--- + +## 🏗️ 技术栈（不可更改） + +| 层级 | 技术 | 版本要求 | +| ------ | -------------------- | ----- | +| 前端框架 | React | 18.x | +| 前端UI库 | Ant Design | 5.x | +| 前端状态管理 | Redux Toolkit | 最新稳定版 | +| 前端路由 | React Router | v6 | +| 前端构建 | Vite | 最新稳定版 | +| 前端HTTP | Axios | 最新稳定版 | +| 后端框架 | Spring Boot | 3.x | +| 后端ORM | MyBatis-Plus | 最新稳定版 | +| 数据库 | MySQL | 8.x | +| 认证方案 | JWT (JSON Web Token) | — | +| API风格 | RESTful | — | + + + +> 本表只做**大版本锁定**（例如 `18.x` / `3.x`）。具体小版本号、依赖清单、配置模板请查 [docs/07-环境配置.md](docs/07-环境配置.md)，不要在本表重复小版本，避免两处漂移。 + +--- + +## 📋 开发前必读文档 + +`docs/01 ~ 10` 是项目知识库。**具体阅读顺序和产出的《理解确认报告》由 `erp-understanding-report` skill 统一处理**（模板见 `.claude/skills/erp-understanding-report/templates/understanding-report-template.md`）。CC 会话入口请调 `/erp-session-start`。 + +--- + +## ✅ 模块完成确认标记规则 + +`confirmed` 是**模块完成确认清单**：追踪哪些模块已由人工审核通过、可视为已完成，从而决定 CC 该在哪个模块上继续工作。 + +### 规则定义 + +每个模块在 `docs/08-模块任务管理.md` 中有一个 `confirmed` 字段： + +```yaml +module_N: + confirmed: false # 默认值 +``` + +### confirmed 语义 + +| confirmed 值 | 含义 | 你（Claude Code）的行为 | +|--------------|------|------------------------| +| `false`（默认） | 模块**待完成**（开发中 / 待 review / 有问题被打回） | ✅ 在本模块开展工作：写代码、跑测试、建 MR | +| `true` | 模块**已完成**（MR 已 Approve + Merge） | 🟢 进入下一个 `false` 模块；本模块只在后续开发中读取引用 | +| `true` → 被改回 `false` | 模块**被重新开启**（人工或你发现问题） | ✅ 回头继续推进这个模块 | + +### 工作流规则 + +- 你总是在 `docs/08-模块任务管理.md` 中**第一个 `confirmed: false` 的模块**上工作 +- 对 `confirmed: true` 的模块：**默认不改**（不是禁止，是已交付无需改） +- 如果在当前模块开发中发现某个 `confirmed: true` 模块有 bug： + 1. 停止当前工作 + 2. 报告：说明哪个模块的哪个文件有什么问题，以及建议的修复范围 + 3. 你可以主动把该模块的 `confirmed` 改回 `false` 重新开启，并切换到该模块修复；修复完成走正常的 MR 流程 + +### 模块完成流程 + +``` +1. 你完成一个模块的所有功能 +2. 你输出"模块完成报告" + 自动 git push + glab mr create +3. 人工 review MR → Approve + Merge（人工动作，唯一人工介入点） +4. 人工告诉你"MR 已 approve + merge"（或你通过 glab mr view 自行确认已 merged） +5. 你自行把当前模块的 confirmed 改为 true +6. 你开始下一个模块 +``` + +### confirmed 修改授权 + +- `confirmed: true` **由你（CC）写入**，不是人工手动改 +- **前置条件**：必须确认 MR 已 Approved + Merged（通过人工告知或 `glab mr view ` 验证） +- 未确认 MR 状态前**严禁**把 `confirmed` 改为 `true`；一旦改错，等于跳过了人工审核 + +### 模块完成报告 + +由 `erp-module-report` skill 产出，模板位于 `.claude/skills/erp-module-report/templates/module-report-template.md`（12 节标准化，含跨模块改动、schema 临时改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告，仅填模板。 + +--- + +## 🏷️ 占位符统一约定（`【人工填写：...】`） + +所有"只有人工能决定"的位置（密钥 / 账密 / 包名 / 命名约定 / 小版本号 等）一律使用以下纯文本标记： + +``` +【人工填写：<简短说明>】 +``` + +### CC 行为规则 + +- **生成文档 / 模板时**：凡是项目专属值、敏感值、技术栈小版本号一律用此标记，不要自行编造 +- **不要用 HTML 注释**（``），因为后者在 Obsidian 渲染视图被隐藏，开发者会漏填 +- **必须带简短说明**：例如 `【人工填写：JWT 签名密钥，256+ bit 随机串】`，而不是空 `【人工填写】` +- **每插入一处新标记**，同步登记到所在文件顶部的「零、人工占位速查表」（若文件无零节，先建一个） +- **项目专属标识**（Java 根包名 / C# 命名空间 / Python 顶层模块等）只在 `docs/07-环境配置.md` 引入一次占位，其他文件**复用**已登记的占位，不再重复创建 + +### 残余占位扫描（任一启动 B 类文档生成时强制执行） + +匹配以下任一字符串视为有未填占位，停下输出残留位置清单等人补完： + +- `【人工填写：` —— 首选特征字符串 +- `your_password` / `your-secret-key` —— 兜底通用裸占位 +- 形如 `N.x` / `N.N.x` 的版本号占位（未锁到具体小版本） + +--- + +## 🔄 开发流程（模块循环 + 功能循环） + +两层嵌套循环的详细步骤**全部固化到 skills**，CLAUDE.md 不再展开。入口调 `/erp-session-start`，自动分发： + +- **模块循环（外层，Layer 2）** → `erp-module-start` → `erp-local-test-gate` → `erp-module-report` → `erp-mr-create` → 人工 Approve+Merge → `erp-confirmed-update` +- **功能循环（内层，Layer 3，每个 REQ-XXX-NNN 走一遍）** → `erp-feature-brainstorm` → `erp-feature-plan` → `erp-feature-tdd` → `erp-feature-verify` → `erp-feature-review` + +**本地测试闸门**: `scripts/test.sh` 是 push 与 merge 前的唯一硬闸门。调用由 `erp-local-test-gate` 派发到全新子会话执行（见设计原则：测试/验证隔离）；`.githooks/pre-push` 也会触发。`git push --no-verify` 被 hook `deny-no-verify.sh` 硬拦截。本项目不配置 GitLab CI/CD。 + +--- + +## 📐 编码行为约束 + +### 你必须做的 ✅ + +1. **严格遵循** `docs/04-技术规范.md` 中的命名和编码规范 +2. **严格遵循** `docs/09-项目目录结构.md` 中的目录规范，文件放对位置 +3. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 中定义，再编码实现 +4. **每个功能** 必须可追溯到 `docs/01-需求清单.md` 中的需求编号 +5. **代码注释** 必须包含对应的需求编号，如 `// REQ-001: 用户登录` +6. **数据库操作** 默认只使用已有表结构；如需临时 DDL 调试，按软规则 S1 执行（留痕 + 模块结束前回撤到基线） +7. **提交代码前** 确保无编译错误、无明显运行时错误 +8. **每个Controller方法** 必须有统一的响应格式包装 +9. **异常处理** 使用全局异常处理器，不在业务代码中catch后吞掉异常 +10. **分页查询** 统一使用 MyBatis-Plus 的 Page 对象 + +### 你禁止做的 🚫 + +1. **默认禁止** 修改 `confirmed: true` 模块的代码；确为实现当前模块所必需时，按软规则 S2 执行（留痕 + 模块报告单列说明） +2. **禁止** 引入技术栈表以外的框架或中间件（如需要必须先报告） +3. **禁止** 硬编码配置（数据库连接、端口号等必须放在配置文件中） +4. **禁止** 在前端直接写SQL或直接操作数据库 +5. **禁止** 跳过模块开发（必须按顺序） +6. **禁止** 删除或覆盖他人代码（如有冲突必须报告） +7. **禁止** 使用 `SELECT *`，必须显式列出需要的字段 +8. **禁止** 在循环中执行数据库查询（N+1问题） +9. **禁止** 前端存储敏感信息到 localStorage +10. **禁止** 返回后端异常堆栈给前端 + +--- + +## 🔄 统一响应格式 + +所有后端接口必须返回以下格式： + +```json +{ + "code": 200, + "message": "操作成功", + "data": {}, + "timestamp": 1700000000000 +} +``` + +错误响应： + +```json +{ + "code": 40001, + "message": "用户名或密码错误", + "data": null, + "timestamp": 1700000000000 +} +``` + +错误码规范： + +| 错误码范围 | 含义 | +|-----------|------| +| 200 | 成功 | +| 400xx | 客户端参数错误 | +| 401xx | 认证/授权错误 | +| 403xx | 权限不足 | +| 404xx | 资源不存在 | +| 500xx | 服务端内部错误 | + +--- + +## 🗂️ Git 提交规范 + +每次提交必须遵循以下格式： + +``` +(): + +type: feat|fix|refactor|docs|style|test|chore +scope: 模块名，如 user, inventory, order +subject: 简短描述，中文可 + +示例： +feat(user): 实现用户登录接口 REQ-001 +fix(order): 修复订单金额计算精度问题 +refactor(common): 统一响应格式包装 +``` + +--- + +## 🧪 自测要求 + +- 所有测试与验证（`scripts/test.sh` / `mvn test` / `pnpm test` / schema 基线 diff 等）**一律派发到全新子会话 via `Agent` 执行**，主会话只接收结构化结论（命令 / 退出码 / 通过数 / 失败项 / 关键 stdout ≤30 行）。不在主会话直跑测试。 +- 由 `erp-feature-verify`（功能级）+ `erp-local-test-gate`（模块级）两道 skill 统一承接。前者每个 REQ 跑一次，后者模块闸门跑一次。 +- 声称"完成"前必须贴出子会话返回的 evidence（模板：`.claude/skills/erp-feature-verify/templates/feature-verify-evidence-template.md`）。 + +--- + +## 🚩 静默执行红旗清单（中断机制） + +功能循环（每个功能 REQ-XXX 的 Brainstorm → Plan → TDD → Verify → AI 自审）默认 **静默跑不打扰人**，但命中以下任何一条必须**立刻停下、记录原因、等人决策**，不得自行绕过： + +| # | 红旗 | 例子 | +| - | --- | --- | +| 1 | **需求与 schema 冲突** | 某功能（REQ-XXX）提到的字段在 MySQL MCP 查到的现有表里不存在 | +| 2 | **需求本身歧义** | spec 中某规则有两种合理解读，CC 无法判断 | +| 3 | **超技术栈边界** | 需要引入 `CLAUDE.md` 技术栈表外的框架 / 中间件 | +| 4 | **测试反复失败** | 同一测试同一功能内连续 **5 次**修复失败 | +| 5 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 | +| 6 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题 | + +**命中红旗时的固定动作：** + +1. 在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`，描述红旗编号、现象、初步判断 +2. 停止后续所有功能的静默执行 +3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复 + +**报告格式：** + +```markdown +## ⚠️ 需要人工决策 + +**红旗编号**: [1–6 中的某一条] +**问题描述**: [详细描述] +**影响范围**: [影响哪些模块 / 功能] +**我的建议**: [初步判断，可选] +**等待决策**: [需要人工做什么决定] +``` + +--- + +## 🟡 软规则（允许继续，但有强制后续动作） + +以下情况 **不触发中断**，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。漏留痕 = 红旗。 + +| # | 软规则 | 允许动作 | 强制后续 | +| - | ----- | ------- | ------- | +| S1 | **临时 schema 改动** | 调试期间可执行 `CREATE / ALTER / DROP TABLE / INDEX / VIEW` | ① 每次 DDL 立即追加到 `docs/superpowers/module-reports/-schema-scratch.md`（含 SQL、时间戳、原因）② 模块**本地 test.sh 闸门前**必须回撤到基线（`mysqldiff` 或 schema dump 比对为空）③ 未回撤 → 升级为红旗，停下 | +| S2 | **跨模块改动**（动到 `confirmed: true` 模块的代码） | 允许修改，但范围受限：仅为当前模块实现所必需 | ① 当次修改立即追加到 `docs/superpowers/module-reports/-cross-module.md`（含文件路径、改动原因、对原模块功能/API 的影响评估）② 《模块完成报告》必须单列「跨模块改动」节完整贴入 ③ 漏留痕或未评估影响 → 升级为红旗 | + +--- + +## ⚡ Skill & 模板入口索引 + +CC 会话启动请直接调 **`/erp-session-start`** —— 顶层编排器会自动探测当前阶段（计划 / 模块循环 / 功能循环 / blocker）并分发到下一个 skill。不要读 `指南.md`。 + +### Skills（22 个，详细动作见各 `SKILL.md` 正文） + +| Layer | Skill | +|---|---| +| **0 入口** | `erp-session-start` | +| **1 计划阶段** | `erp-tech-stack-lock` / `erp-skeleton-gen` / `erp-mysql-mcp-setup` / `erp-requirements-gen` / `erp-downstream-gen` / `erp-understanding-report` | +| **2 模块循环（外）** | `erp-module-start` / `erp-local-test-gate` / `erp-module-report` / `erp-mr-create` / `erp-confirmed-update` | +| **3 功能循环（内）** | `erp-feature-brainstorm` / `erp-feature-plan` / `erp-feature-tdd` / `erp-feature-verify` / `erp-feature-review` | +| **4 横切守门** | `erp-red-flag-check` / `erp-placeholder-scan` / `erp-schema-baseline-check` / `erp-schema-scratch-log`（软规则 S1）/ `erp-cross-module-log`（软规则 S2） | + +### Hooks（5 个，`.claude/settings.json` + `.claude/hooks/*.sh`） + +- `deny-no-verify.sh` — 拒 `git push --no-verify` +- `guard-confirmed-flip.sh` — 翻 `confirmed: false→true` 前校验 MR merged 证据 +- `log-ddl.sh` — DDL 自动留痕（S1） +- `log-cross-module.sh` — 跨模块改动自动留痕（S2） +- `session-start-dispatch.sh` — 会话启动提示运行 `/erp-session-start` + +### 模板（44 份，分散在各 skill 的 `.claude/skills/erp-*/templates/*`） + +每个生成文件都对应一个模板（设计原则 #5）。模板保持纯净（原则 #6），帮助文本由 skill 通过 `AskUserQuestion` 交互引导。模板按"谁用谁拥有"原则分散到各自的 skill 目录下，便于打包成 plugin。两份共享模板（`schema-scratch-log-template.md` / `cross-module-log-template.md`）在 `erp-module-start` 与 `erp-schema-scratch-log` / `erp-cross-module-log` 中各有一份副本。 + diff --git a/_pl_staging/pl_commands/erp-session-start.md b/_pl_staging/pl_commands/erp-session-start.md new file mode 100644 index 0000000..9cbfcd0 --- /dev/null +++ b/_pl_staging/pl_commands/erp-session-start.md @@ -0,0 +1,5 @@ +--- +description: ERP 项目会话入口 — 自动探测当前阶段并分发到下一步 skill +--- + +Invoke the `erp-session-start` skill via the Skill tool to detect the current ERP-project phase and dispatch to the next skill. Do not read `指南.md`. Follow CLAUDE.md. diff --git a/_pl_staging/pl_hooks/deny-no-verify.sh b/_pl_staging/pl_hooks/deny-no-verify.sh new file mode 100755 index 0000000..786736d --- /dev/null +++ b/_pl_staging/pl_hooks/deny-no-verify.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# PreToolUse hook: block any `git push --no-verify` — the local test.sh gate is the only hard gate. + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +[ "$tool_name" = "Bash" ] || exit 0 + +cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')" +[ -n "$cmd" ] || exit 0 + +if printf '%s' "$cmd" | grep -qE '\bgit[[:space:]]+push\b.*--no-verify\b'; then + echo "BLOCKED: --no-verify bypasses the local test.sh gate (唯一硬闸门). If test.sh is failing, fix the root cause; do not skip the gate. Use /erp-local-test-gate to run the gate properly." >&2 + exit 2 +fi + +exit 0 diff --git a/_pl_staging/pl_hooks/guard-confirmed-flip.sh b/_pl_staging/pl_hooks/guard-confirmed-flip.sh new file mode 100755 index 0000000..370715f --- /dev/null +++ b/_pl_staging/pl_hooks/guard-confirmed-flip.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +# PreToolUse hook: on any Edit/Write to docs/08 that flips `confirmed: false` → `true`, +# require recent `glab mr view ... merged` evidence in conversation transcript. + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +case "$tool_name" in Edit|Write) ;; *) exit 0 ;; esac + +file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')" +case "$file_path" in *"/docs/08-模块任务管理.md") ;; *) exit 0 ;; esac + +# For Edit: check old_string/new_string; for Write: check content. +old_str="$(printf '%s' "$input" | jq -r '.tool_input.old_string // empty')" +new_str="$(printf '%s' "$input" | jq -r '.tool_input.new_string // empty')" +content="$(printf '%s' "$input" | jq -r '.tool_input.content // empty')" + +flipping=0 +if [ -n "$old_str" ] && [ -n "$new_str" ]; then + if printf '%s' "$old_str" | grep -q 'confirmed:[[:space:]]*false' && \ + printf '%s' "$new_str" | grep -q 'confirmed:[[:space:]]*true'; then + flipping=1 + fi +fi +if [ -n "$content" ] && [ "$flipping" = 0 ]; then + # Full overwrite: compare against current file's `false` entries to detect a flip. + if [ -f "$file_path" ]; then + cur_false_count="$(grep -c 'confirmed:[[:space:]]*false' "$file_path" || true)" + new_false_count="$(printf '%s' "$content" | grep -c 'confirmed:[[:space:]]*false' || true)" + [ "$new_false_count" -lt "$cur_false_count" ] && flipping=1 + fi +fi + +[ "$flipping" = 1 ] || exit 0 + +transcript_path="$(printf '%s' "$input" | jq -r '.transcript_path // empty')" +evidence=0 +if [ -n "$transcript_path" ] && [ -f "$transcript_path" ]; then + if grep -E '"state"[[:space:]]*:[[:space:]]*"merged"|state:[[:space:]]*merged|MERGED' "$transcript_path" >/dev/null 2>&1; then + evidence=1 + fi +fi + +if [ "$evidence" = 0 ]; then + echo "BLOCKED: flipping confirmed:false → true requires prior evidence that the MR is merged. Run \`glab mr view -F json\` first (via erp-confirmed-update skill) and confirm state=merged. 若 MR 未合并即改 confirmed，等于跳过人工审核。" >&2 + exit 2 +fi + +exit 0 diff --git a/_pl_staging/pl_hooks/log-cross-module.sh b/_pl_staging/pl_hooks/log-cross-module.sh new file mode 100755 index 0000000..92b0583 --- /dev/null +++ b/_pl_staging/pl_hooks/log-cross-module.sh @@ -0,0 +1,75 @@ +#!/usr/bin/env bash +# PostToolUse hook: detect Edit/Write to a file inside a confirmed:true module and stub-log to cross-module file. +# Triggers soft rule S2. + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +case "$tool_name" in Edit|Write) ;; *) exit 0 ;; esac + +file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')" +[ -n "$file_path" ] || exit 0 + +project_dir="${CLAUDE_PROJECT_DIR:-$(pwd)}" +docs08="$project_dir/docs/08-模块任务管理.md" +[ -f "$docs08" ] || exit 0 + +# Skip changes to docs/08 itself (handled by guard-confirmed-flip). +case "$file_path" in *"/docs/08-模块任务管理.md") exit 0 ;; esac + +# Determine current (first confirmed:false) module. +current_module="$(awk '/confirmed:[[:space:]]*false/ {print prev; exit} {prev=$0}' "$docs08" | sed -nE 's/^[[:space:]]*([A-Za-z0-9_-]+):.*/\1/p')" +[ -n "$current_module" ] || exit 0 + +# Collect confirmed:true modules and their path scopes. +# Expected YAML shape in docs/08 per module: +# module_N: +# name: ... +# paths: [src/foo/**, frontend/bar/**] +# confirmed: true +confirmed_true_modules="$(awk ' + /^[[:space:]]*[A-Za-z0-9_-]+:[[:space:]]*$/ { name=$1; sub(":","",name) } + /confirmed:[[:space:]]*true/ { print name } +' "$docs08")" + +[ -n "$confirmed_true_modules" ] || exit 0 + +hit_module="" +for m in $confirmed_true_modules; do + [ "$m" = "$current_module" ] && continue + # Read paths list for this module (best-effort — match lines under this module before next module). + scopes="$(awk -v mod="$m" ' + $0 ~ "^[[:space:]]*"mod":[[:space:]]*$" {in_mod=1; next} + in_mod && /^[A-Za-z0-9_-]+:[[:space:]]*$/ {in_mod=0} + in_mod && /paths:/ {gsub(/.*paths:[[:space:]]*\[/,""); gsub(/\].*/,""); gsub(/["'"'"' ]/,""); print; exit} + ' "$docs08")" + [ -n "$scopes" ] || continue + IFS=',' read -ra scope_arr <<< "$scopes" + for s in "${scope_arr[@]}"; do + [ -z "$s" ] && continue + pattern="${s%/\*\*}" + case "$file_path" in *"$pattern"*) hit_module="$m"; break 2;; esac + done +done + +[ -n "$hit_module" ] || exit 0 + +log_dir="$project_dir/docs/superpowers/module-reports" +mkdir -p "$log_dir" +log_file="$log_dir/${current_module}-cross-module.md" +if [ ! -f "$log_file" ]; then + { + echo "# 跨模块改动日志 — ${current_module}" + echo "" + echo "| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 |" + echo "|---|---|---|---|---|---|" + } > "$log_file" +fi + +ts="$(date -u +%FT%TZ)" +rel_path="${file_path#$project_dir/}" +echo "| ${ts} | ${hit_module} | ${rel_path} | ${tool_name} | TBD(待填) | TBD(待填) |" >> "$log_file" + +jq -n --arg m "$hit_module" --arg f "$log_file" --arg p "$rel_path" \ + '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:("Cross-module edit detected: \($p) belongs to confirmed:true module [\($m)]. Stub logged to \($f). Invoke erp-cross-module-log skill to fill 原因 and 影响评估. (软规则 S2)")}}' diff --git a/_pl_staging/pl_hooks/log-ddl.sh b/_pl_staging/pl_hooks/log-ddl.sh new file mode 100755 index 0000000..d294ec3 --- /dev/null +++ b/_pl_staging/pl_hooks/log-ddl.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash +# PostToolUse hook: detect DDL in MCP mysql_query and stub-log to current module's schema-scratch file. +# Triggers soft rule S1 — DDL is allowed during debug, but must be rolled back by module gate. + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +[ "$tool_name" = "mcp__mcp_server_mysql__mysql_query" ] || exit 0 + +sql="$(printf '%s' "$input" | jq -r '.tool_input.sql // .tool_input.query // empty')" +[ -n "$sql" ] || exit 0 + +if ! printf '%s' "$sql" | grep -iqE '\b(CREATE|ALTER|DROP|TRUNCATE)[[:space:]]+(TABLE|INDEX|VIEW|DATABASE|SCHEMA)\b'; then + exit 0 +fi + +project_dir="${CLAUDE_PROJECT_DIR:-$(pwd)}" +docs08="$project_dir/docs/08-模块任务管理.md" +module_name="unknown-module" +if [ -f "$docs08" ]; then + module_name="$(awk '/confirmed:[[:space:]]*false/ {print prev; exit} {prev=$0}' "$docs08" | sed -nE 's/^[[:space:]]*([A-Za-z0-9_-]+):.*/\1/p')" + [ -n "$module_name" ] || module_name="unknown-module" +fi + +log_dir="$project_dir/docs/superpowers/module-reports" +mkdir -p "$log_dir" +log_file="$log_dir/${module_name}-schema-scratch.md" + +if [ ! -f "$log_file" ]; then + { + echo "# Schema 临时改动日志 — ${module_name}" + echo "" + echo "| 时间戳 | SQL | 原因 | 预计回撤时机 |" + echo "|---|---|---|---|" + } > "$log_file" +fi + +ts="$(date -u +%FT%TZ)" +sql_one_line="$(printf '%s' "$sql" | tr '\n' ' ' | sed 's/|/\\|/g' | cut -c1-200)" +echo "| ${ts} | \`${sql_one_line}\` | TBD(待填) | TBD(待填) |" >> "$log_file" + +jq -n --arg msg "DDL detected on schema. Stub logged to ${log_file}. Invoke erp-schema-scratch-log skill to fill 原因 and 回撤时机. Remember: 软规则 S1 — schema must be rolled back to baseline before module gate, else 升级为红旗。" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}' diff --git a/_pl_staging/pl_hooks/session-start-dispatch.sh b/_pl_staging/pl_hooks/session-start-dispatch.sh new file mode 100755 index 0000000..0ddf0aa --- /dev/null +++ b/_pl_staging/pl_hooks/session-start-dispatch.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +# SessionStart hook: remind CC to run erp-session-start for phase detection & dispatch. + +cat <<'EOF' +[ERP skills] Session started. Run /erp-session-start to auto-detect the current phase (Layer 1 planning / Layer 2 module loop / blocker) and dispatch to the next skill. See CLAUDE.md for the 6-flag + 2-soft-rule shortlist. +EOF diff --git a/_pl_staging/pl_settings.json b/_pl_staging/pl_settings.json new file mode 100644 index 0000000..5ca87ad --- /dev/null +++ b/_pl_staging/pl_settings.json @@ -0,0 +1,39 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/deny-no-verify.sh" } + ] + }, + { + "matcher": "Edit|Write", + "hooks": [ + { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-confirmed-flip.sh" } + ] + } + ], + "PostToolUse": [ + { + "matcher": "mcp__mcp_server_mysql__mysql_query", + "hooks": [ + { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-ddl.sh" } + ] + }, + { + "matcher": "Edit|Write", + "hooks": [ + { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-cross-module.sh" } + ] + } + ], + "SessionStart": [ + { + "hooks": [ + { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start-dispatch.sh" } + ] + } + ] + } +} diff --git a/_pl_staging/pl_settings.local.json b/_pl_staging/pl_settings.local.json new file mode 100644 index 0000000..b504407 --- /dev/null +++ b/_pl_staging/pl_settings.local.json @@ -0,0 +1,21 @@ +{ + "permissions": { + "allow": [ + "mcp__mcp_server_mysql__mysql_query", + "Bash(ls docs/)", + "Bash(ls scripts/ .githooks/)", + "Bash(ls .mcp.json docs/superpowers/schema-baseline.sql)", + "Bash(ls docs/01-需求清单/)", + "Bash(sed -i.bak -e 's|@references/|templates/|g' __TRACKED_VAR__/SKILL.md)", + "Bash(rm __TRACKED_VAR__/SKILL.md.bak)", + "Bash(mkdir -p erp-workflow-plugin/.claude-plugin erp-workflow-plugin/hooks/scripts)", + "Bash(cp -r .claude/skills erp-workflow-plugin/skills)", + "Bash(cp -r .claude/commands erp-workflow-plugin/commands)", + "Bash(cp .claude/hooks/*.sh erp-workflow-plugin/hooks/scripts/)", + "Bash(cp CLAUDE.md erp-workflow-plugin/CLAUDE.md.template)", + "Bash(sed -i.bak -e 's|`\\\\.claude/skills/erp-understanding-report/templates/understanding-report-template\\\\.md`|由 erp-understanding-report skill 持有，安装插件后 skill 自动读取|g' -e 's|`\\\\.claude/skills/erp-module-report/templates/module-report-template\\\\.md`|由 erp-module-report skill 持有|g' -e 's|`\\\\.claude/skills/erp-feature-verify/templates/feature-verify-evidence-template\\\\.md`|由 erp-feature-verify skill 持有|g' -e 's|`\\\\.claude/skills/erp-\\\\*/templates/\\\\*`|插件 `skills/erp-*/templates/*`|g' erp-workflow-plugin/CLAUDE.md.template)", + "Bash(rm erp-workflow-plugin/CLAUDE.md.template.bak)" + ], + "deny": [] + } +} diff --git a/_pl_staging/pl_skills/erp-confirmed-update/SKILL.md b/_pl_staging/pl_skills/erp-confirmed-update/SKILL.md new file mode 100644 index 0000000..2a53886 --- /dev/null +++ b/_pl_staging/pl_skills/erp-confirmed-update/SKILL.md @@ -0,0 +1,35 @@ +--- +name: erp-confirmed-update +description: After the human merges the module's MR, verify merged state via glab mr view, flip docs/08 confirmed:false→true, commit the flip, and hand back to erp-session-start for the next module. +--- + +# erp-confirmed-update + +## Pre-conditions + +- User said "MR 已合" OR auto-trigger from `erp-session-start` ladder step 8. +- `docs/08` current module's MR IID known (from § ⑫ of module report). + +## Procedure + +1. Run `glab mr view -F json` (direct Bash; no subagent needed — it's a read). +2. Parse JSON; verify `.state == "merged"` (and `.merge_status == "merged"` if present). +3. On not-merged → print state, stop (do NOT flip). +4. On merged: + a. Edit `docs/08-模块任务管理.md`: for the current module, change `confirmed: false` → `confirmed: true`. Change exactly one line. + - **`guard-confirmed-flip.sh` hook will verify merged evidence is in the transcript** — since we just ran `glab mr view` above, that check will see it. + b. Stage `docs/08-模块任务管理.md`. + c. Read `templates/confirmed-flip-commit-template.md`; fill `module_id`, `mr_iid`; commit with that message. +5. Print `confirmed-update: → true (MR !)`. +6. Invoke `erp-session-start` to dispatch to the next module. + +## Invariants + +- Never flip `confirmed: true → false` in this skill (that's a red-flag-reopen flow, handled manually). +- Never flip for a module other than the current (first `confirmed: false`). + +## References + +- `templates/confirmed-flip-commit-template.md` +- `templates/docs-08-flip-diff-template.md` +- Hook interlock: `guard-confirmed-flip.sh` diff --git a/_pl_staging/pl_skills/erp-confirmed-update/templates/confirmed-flip-commit-template.md b/_pl_staging/pl_skills/erp-confirmed-update/templates/confirmed-flip-commit-template.md new file mode 100644 index 0000000..4d33c20 --- /dev/null +++ b/_pl_staging/pl_skills/erp-confirmed-update/templates/confirmed-flip-commit-template.md @@ -0,0 +1 @@ +chore({{module_id}}): mark confirmed (MR !{{mr_iid}} merged) diff --git a/_pl_staging/pl_skills/erp-confirmed-update/templates/docs-08-flip-diff-template.md b/_pl_staging/pl_skills/erp-confirmed-update/templates/docs-08-flip-diff-template.md new file mode 100644 index 0000000..d71e024 --- /dev/null +++ b/_pl_staging/pl_skills/erp-confirmed-update/templates/docs-08-flip-diff-template.md @@ -0,0 +1,12 @@ +Expected unified-diff shape for a legitimate confirmed flip: + +``` +@@ + {{module_id}}: + name: ... + ... +- confirmed: false ++ confirmed: true +``` + +Exactly one block changed from `false` to `true`. Any other shape is suspicious — `guard-confirmed-flip.sh` will block unless merged-state evidence is present. diff --git a/_pl_staging/pl_skills/erp-cross-module-log/SKILL.md b/_pl_staging/pl_skills/erp-cross-module-log/SKILL.md new file mode 100644 index 0000000..a9e06db --- /dev/null +++ b/_pl_staging/pl_skills/erp-cross-module-log/SKILL.md @@ -0,0 +1,31 @@ +--- +name: erp-cross-module-log +description: Fill in 原因 and 影响评估 for cross-module edit stubs that the `log-cross-module.sh` hook auto-appended to `docs/superpowers/module-reports/-cross-module.md`. Covers edits to files inside `confirmed: true` modules. +--- + +# erp-cross-module-log + +## What + +Soft-rule S2 enforcement: every edit to a confirmed-merged module must be logged with reason + impact assessment. + +## Procedure + +1. Identify the current module (first `confirmed: false` in `docs/08-模块任务管理.md`). +2. Open `docs/superpowers/module-reports/-cross-module.md` (init from `templates/cross-module-log-template.md` if absent). +3. Find rows with `TBD(待填)` in 原因 or 影响评估 columns. +4. For each TBD row: + - **原因**: why was the target module's code modified? What requirement in the current module forced it? + - **影响评估**: which APIs / behaviors / callers in the target module may be affected? Are its existing tests still valid? Are new tests needed? (1-3 sentences) +5. Edit the row; keep 时间戳 / 目标模块 / 文件 / 改动摘要 immutable. +6. Print a one-line confirmation: `cross-module-log: N rows updated`. + +## Downstream + +The filled log is embedded verbatim into `module-report-template.md` § ⑦ by `erp-module-report`. + +## References + +- `templates/cross-module-log-template.md` +- `templates/cross-module-log-row-template.md` +- `CLAUDE.md` § 🟡 软规则 S2 diff --git a/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-row-template.md b/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-row-template.md new file mode 100644 index 0000000..883cdcd --- /dev/null +++ b/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-row-template.md @@ -0,0 +1 @@ +| {{timestamp}} | {{target_module}} | {{file_path}} | {{change_summary}} | {{reason}} | {{impact}} | diff --git a/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-template.md b/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-template.md new file mode 100644 index 0000000..8c8ef54 --- /dev/null +++ b/_pl_staging/pl_skills/erp-cross-module-log/templates/cross-module-log-template.md @@ -0,0 +1,6 @@ +# 跨模块改动日志 — {{module_name}} + +软规则 S2：本模块开发期间对其他 `confirmed: true` 模块代码的改动记录在此；模块完成报告必须单列「跨模块改动」节完整贴入。漏留痕或未评估影响 → 升级为红旗。 + +| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 | +|---|---|---|---|---|---| diff --git a/_pl_staging/pl_skills/erp-downstream-gen/SKILL.md b/_pl_staging/pl_skills/erp-downstream-gen/SKILL.md new file mode 100644 index 0000000..7828503 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/SKILL.md @@ -0,0 +1,62 @@ +--- +name: erp-downstream-gen +description: Plan-phase step A5. Generate docs/02 + docs/05 + docs/06 五节 + docs/08 + docs/10 + sql/seed-data.sql in one pass, derived from docs/01 and docs/03. +--- + +# erp-downstream-gen + +## Pre-conditions + +- `docs/01-需求清单/*.md` full REQ cards present. +- `docs/03-数据库设计文档.md` present. +- Human has reviewed 01 and 03 (ask user to confirm before proceeding). + +## Procedure + +### A. docs/02 — 开发计划 +1. Build module dependency DAG from: + - FKs in docs/03 (table A → table B ⇒ A's module depends on B's module) + - Explicit `depends_on` hints in docs/01 READMEs +2. Topological sort → `order[]`. +3. Read `templates/docs-02-template.md`; fill `modules[]`, `order[]`, `notes`. +4. Write `docs/02-开发计划.md`. + +### B. docs/05 — API 接口契约 +1. Read `templates/docs-05-header-template.md`; write header to `docs/05-API接口契约.md`. +2. For each REQ across all modules: read `templates/docs-05-endpoint-template.md`; infer method / path / auth / permission / request & response schemas (ask user for non-obvious ones); append to `docs/05`. + +### C. docs/06 — 页面清单 +1. For each module with frontend pages: read `templates/docs-06-module-pagelist-template.md`; fill `pages[]` (page_name, route, page_type, req_ids, menu_path, interactions). +2. Append each rendered block to `docs/06-UI交互规范.md` § 五. + +### D. docs/08 — 模块任务管理 +1. Read `templates/docs-08-header-template.md`; write header to `docs/08-模块任务管理.md`. +2. For each module in topological order: read `templates/docs-08-module-row-template.md`; fill `module_id`, `module_name`, `depends_on`, `req_ids`, `path_scopes` (from docs/09 + module code prefix), `confirmed: false`; append. + +### E. docs/10 — 验收清单 +1. Read `templates/docs-10-header-template.md`; write header to `docs/10-验收检查清单.md`. +2. For each module: read `templates/docs-10-module-template.md`; fill `reqs[]`, `data_checks[]`, `ui_checks[]`; append. + +### F. sql/seed-data.sql +1. Read `templates/seed-data-sql-template.sql`. +2. For each module, ask user or infer minimal seed rows (enough for acceptance tests to pass). Fill `module_blocks[]`. +3. Write `sql/seed-data.sql`. + +### G. Validate +- Every REQ in docs/01 appears in docs/05 (as an endpoint if applicable), docs/08 (under its module), docs/10 (as an acceptance item). +- Every module in docs/02 order has a row in docs/08 with `confirmed: false`. +- Run `erp-placeholder-scan` over the 5 files — log residuals. + +Print: `downstream-gen: wrote 5 files + seed. Awaiting human review.` + +## References + +- `templates/docs-02-template.md` +- `templates/docs-05-header-template.md` +- `templates/docs-05-endpoint-template.md` +- `templates/docs-06-module-pagelist-template.md` +- `templates/docs-08-header-template.md` +- `templates/docs-08-module-row-template.md` +- `templates/docs-10-header-template.md` +- `templates/docs-10-module-template.md` +- `templates/seed-data-sql-template.sql` diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-02-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-02-template.md new file mode 100644 index 0000000..4c70da6 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-02-template.md @@ -0,0 +1,19 @@ +# 02-开发计划 + +模块按**技术依赖**排序，非业务优先级。 + +## 模块依赖表 + +| 模块 ID | 模块名 | 依赖模块 | 依赖表 | 估算天数 | +|---|---|---|---|---| +{{#each modules}} +| {{id}} | {{name}} | {{deps}} | {{tables}} | {{days}} | +{{/each}} + +## 开发顺序（拓扑序） +{{#each order}} +{{index}}. {{module_id}} — {{module_name}} +{{/each}} + +## 关键说明 +{{notes}} diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-endpoint-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-endpoint-template.md new file mode 100644 index 0000000..1583d4e --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-endpoint-template.md @@ -0,0 +1,24 @@ +### {{req_id}} {{title}} + +- **Method**: {{method}} +- **Path**: `{{path}}` +- **Auth**: {{auth}} +- **Permission**: {{permission}} + +#### 请求参数 +{{request_params}} + +#### 请求体 +```json +{{request_body_schema}} +``` + +#### 响应体 +```json +{{response_body_schema}} +``` + +#### 错误码 +{{#each errors}} +- `{{code}}` — {{message}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-header-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-header-template.md new file mode 100644 index 0000000..6bcd293 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-05-header-template.md @@ -0,0 +1,30 @@ +# 05-API接口契约 + +BasePath: `{{base_path}}` +端口: `【人工填写：后端端口，默认 8080】` + +## 全局约定 + +### 响应格式 +```json +{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000} +``` + +### 错误码 +| 范围 | 含义 | +|---|---| +| 200 | 成功 | +| 400xx | 客户端参数错误 | +| 401xx | 认证/授权错误 | +| 403xx | 权限不足 | +| 404xx | 资源不存在 | +| 500xx | 服务端内部错误 | + +### 鉴权 +{{auth_note}} + +### 分页参数 +{{pagination_note}} + +## 接口清单 +（各模块接口段落见下方，由 `erp-downstream-gen` 按 REQ 填入） diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-06-module-pagelist-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-06-module-pagelist-template.md new file mode 100644 index 0000000..36f18a5 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-06-module-pagelist-template.md @@ -0,0 +1,9 @@ +### {{module_id}} {{module_name}} + +{{#each pages}} +- **{{page_name}}** (`{{route}}`) + - 类型: {{page_type}} （列表页 / 表单页 / 详情页 / 树形管理页） + - 对应 REQ: {{req_ids}} + - 入口菜单: {{menu_path}} + - 主要交互: {{interactions}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-header-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-header-template.md new file mode 100644 index 0000000..c5ac562 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-header-template.md @@ -0,0 +1,9 @@ +# 08-模块任务管理 + +`confirmed` 语义（权威定义在 `CLAUDE.md`）： +- `false` → 模块待完成或被重开，CC 在此模块工作 +- `true` → 已 MR Approve + Merge，CC 进入下一 `false` 模块 + +CC 修改 `false → true` 需 MR 已 merged 证据（hook `guard-confirmed-flip.sh` 强制）。 + +## 模块列表 diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-module-row-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-module-row-template.md new file mode 100644 index 0000000..e07fc29 --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-08-module-row-template.md @@ -0,0 +1,6 @@ +{{module_id}}: + name: {{module_name}} + depends_on: {{depends_on}} + reqs: {{req_ids}} + paths: [{{path_scopes}}] + confirmed: false diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-header-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-header-template.md new file mode 100644 index 0000000..ea9a09c --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-header-template.md @@ -0,0 +1,14 @@ +# 10-验收检查清单 + +通用验收项（全项目适用）: + +- [ ] `scripts/test.sh` 本地全绿 +- [ ] schema 与 `docs/superpowers/schema-baseline.sql` 一致（无未回撤 DDL） +- [ ] 所有新接口在 `docs/05` 中有契约定义 +- [ ] 所有新功能代码注释含 REQ-XXX-NNN +- [ ] 统一响应格式 `{code, message, data, timestamp}` +- [ ] 异常走全局处理器，不暴露堆栈到前端 +- [ ] 前端不存敏感信息到 localStorage + +## 模块专项 +（各模块验收段落见下方，由 `erp-downstream-gen` 按模块填入） diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-module-template.md b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-module-template.md new file mode 100644 index 0000000..9342e2e --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/docs-10-module-template.md @@ -0,0 +1,18 @@ +### {{module_id}} {{module_name}} + +#### 功能级验收（每个 REQ 对应可执行用例） +{{#each reqs}} +- [ ] {{req_id}} {{title}} + - 自动化用例: `{{test_file}}::{{test_name}}` + - 手动验收: {{manual_check}} +{{/each}} + +#### 数据级验收 +{{#each data_checks}} +- [ ] {{check}} +{{/each}} + +#### UI 级验收（若含前端） +{{#each ui_checks}} +- [ ] {{check}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-downstream-gen/templates/seed-data-sql-template.sql b/_pl_staging/pl_skills/erp-downstream-gen/templates/seed-data-sql-template.sql new file mode 100644 index 0000000..eb0576a --- /dev/null +++ b/_pl_staging/pl_skills/erp-downstream-gen/templates/seed-data-sql-template.sql @@ -0,0 +1,15 @@ +-- seed-data.sql — 本地测试数据 +-- Reloaded on every scripts/setup-test-db.sh run. +-- Never mutate schema here; data only. + +SET FOREIGN_KEY_CHECKS = 0; + +{{#each module_blocks}} +-- ========================================================== +-- {{module_id}} {{module_name}} +-- ========================================================== +{{sql_block}} + +{{/each}} + +SET FOREIGN_KEY_CHECKS = 1; diff --git a/_pl_staging/pl_skills/erp-feature-brainstorm/SKILL.md b/_pl_staging/pl_skills/erp-feature-brainstorm/SKILL.md new file mode 100644 index 0000000..b876e1c --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-brainstorm/SKILL.md @@ -0,0 +1,31 @@ +--- +name: erp-feature-brainstorm +description: Feature-loop step 1. Thin wrapper over superpowers:brainstorming for a single REQ-XXX-NNN. Produces a spec file at docs/superpowers/specs/YYYY-MM-DD-.md using the feature-spec-template, after interactive brainstorming with the user. +--- + +# erp-feature-brainstorm + +## What + +Produce a ≤1-page spec for one REQ-XXX-NNN by delegating to `superpowers:brainstorming`, then pack the output into the standard spec template. + +## Procedure + +1. **Red-flag gate**: invoke `erp-red-flag-check`. If it halts → stop. +2. Resolve inputs: + - Current REQ-XXX-NNN (from conversation, or the next unfulfilled REQ in `docs/08` current module). + - REQ card: `docs/01-需求清单/.md` § REQ-XXX-NNN. + - Relevant schema tables (from `docs/03` or live MCP query). +3. Delegate to `superpowers:brainstorming` with the REQ card + schema refs as context. +4. Derive path: `docs/superpowers/specs/$(date +%F)-.md`. If already exists, overwrite with user confirmation. +5. Read `templates/feature-spec-template.md`; fill slots from brainstorm output: + - `goal`, `input`, `output`, `rules`, `constraints`, `schema_refs`, `api_refs`, `acceptance` +6. Write the filled spec to the derived path. +7. **Validate**: every top-level section in the template must be non-empty. If any slot is TBD, loop back to brainstorming for that slot. +8. Print `feature-brainstorm: → ` to session. + +## References + +- `templates/feature-spec-template.md` +- Delegates: `superpowers:brainstorming` +- Guard: `erp-red-flag-check` diff --git a/_pl_staging/pl_skills/erp-feature-brainstorm/templates/feature-spec-template.md b/_pl_staging/pl_skills/erp-feature-brainstorm/templates/feature-spec-template.md new file mode 100644 index 0000000..09715ab --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-brainstorm/templates/feature-spec-template.md @@ -0,0 +1,31 @@ +--- +req_id: {{req_id}} +date: {{date}} +module: {{module}} +--- + +# Spec: {{req_id}} — {{title}} + +## 目标 +{{goal}} + +## 输入 / 触发 +{{input}} + +## 输出 / 结果 +{{output}} + +## 业务规则 +{{rules}} + +## 边界与约束 +{{constraints}} + +## 依赖的 schema 表 / 字段 +{{schema_refs}} + +## 依赖的接口 +{{api_refs}} + +## 验收标准 +{{acceptance}} diff --git a/_pl_staging/pl_skills/erp-feature-plan/SKILL.md b/_pl_staging/pl_skills/erp-feature-plan/SKILL.md new file mode 100644 index 0000000..11fd820 --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-plan/SKILL.md @@ -0,0 +1,26 @@ +--- +name: erp-feature-plan +description: Feature-loop step 2. Thin wrapper over superpowers:writing-plans. Turns a spec into a task-level plan (2–5 min per task, with file paths and full code) at docs/superpowers/plans/YYYY-MM-DD-.md. +--- + +# erp-feature-plan + +## Procedure + +1. **Red-flag gate**: `erp-red-flag-check`. +2. Resolve inputs: + - Current REQ-XXX-NNN and the spec at `docs/superpowers/specs/YYYY-MM-DD-.md` (fail if spec missing). + - Relevant code pointers (existing files to touch, discoverable via Grep). + - `docs/04-技术规范.md` and `docs/09-项目目录结构.md` (编码规范 + 目录规范). +3. Delegate to `superpowers:writing-plans` with spec + code pointers + conventions. +4. Derive path: `docs/superpowers/plans/$(date +%F)-.md`. +5. Read `templates/feature-plan-template.md`; fill `files[]`, `tasks[]`, `commits[]`. +6. Enforce: each task must be 2–5 min, have a failing test identifier, an impl path, and a done_when criterion. +7. Write the plan. +8. Print `feature-plan: → ` to session. + +## References + +- `templates/feature-plan-template.md` +- Delegates: `superpowers:writing-plans` +- Guard: `erp-red-flag-check` diff --git a/_pl_staging/pl_skills/erp-feature-plan/templates/feature-plan-template.md b/_pl_staging/pl_skills/erp-feature-plan/templates/feature-plan-template.md new file mode 100644 index 0000000..bcdfbc2 --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-plan/templates/feature-plan-template.md @@ -0,0 +1,25 @@ +--- +req_id: {{req_id}} +date: {{date}} +spec_ref: docs/superpowers/specs/{{date}}-{{req_id}}.md +--- + +# Plan: {{req_id}} + +## 文件变更清单 +{{#each files}} +- `{{path}}` — {{action}}（{{rationale}}） +{{/each}} + +## 任务步骤（每步 2–5 分钟） +{{#each tasks}} +### Task {{index}}: {{title}} +- 失败测试: `{{test_file}}::{{test_name}}` — {{test_intent}} +- 实现路径: `{{impl_file}}` +- 完成判据: {{done_when}} +{{/each}} + +## 提交计划 +{{#each commits}} +- `{{message}}`（覆盖 Task {{task_index}}） +{{/each}} diff --git a/_pl_staging/pl_skills/erp-feature-review/SKILL.md b/_pl_staging/pl_skills/erp-feature-review/SKILL.md new file mode 100644 index 0000000..09966de --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-review/SKILL.md @@ -0,0 +1,22 @@ +--- +name: erp-feature-review +description: Feature-loop step 5. Thin wrapper over superpowers:code-reviewer. Writes review report at docs/superpowers/reviews/YYYY-MM-DD-.md. Self-fix loop capped at 3 rounds. +--- + +# erp-feature-review + +## Procedure + +1. Delegate to `superpowers:code-reviewer` with the REQ's diff (`git diff ..HEAD`) and the spec. +2. Derive path: `docs/superpowers/reviews/$(date +%F)-.md`. +3. Read `templates/feature-review-template.md`; fill `round`, `verdict`, `must_fix[]`, `nice_to_have[]`, `gaps`. +4. Write the report. +5. Dispatch logic: + - `verdict = approve` → print `feature-review: APPROVED` and exit. + - `verdict = request-changes` → fix Must-fix items, re-run `erp-feature-verify`, then re-review as round N+1. +6. Cap: **3 rounds**. If still `request-changes` after round 3 → stop and print a summary; escalate to user. (Red flag #9 was removed from the strict halt list — use judgement, but don't loop forever.) + +## References + +- `templates/feature-review-template.md` +- Delegates: `superpowers:code-reviewer` diff --git a/_pl_staging/pl_skills/erp-feature-review/templates/feature-review-template.md b/_pl_staging/pl_skills/erp-feature-review/templates/feature-review-template.md new file mode 100644 index 0000000..a9b6216 --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-review/templates/feature-review-template.md @@ -0,0 +1,24 @@ +--- +req_id: {{req_id}} +date: {{date}} +round: {{round}} +reviewer: superpowers:code-reviewer +--- + +# Review: {{req_id}} — round {{round}} + +## 结论 +{{verdict}} （approve / request-changes） + +## Must-fix +{{#each must_fix}} +- [{{severity}}] {{file}}:{{line}} — {{issue}}（建议：{{suggestion}}） +{{/each}} + +## Nice-to-have +{{#each nice_to_have}} +- {{file}}:{{line}} — {{suggestion}} +{{/each}} + +## 反例 / 测试覆盖缺口 +{{gaps}} diff --git a/_pl_staging/pl_skills/erp-feature-tdd/SKILL.md b/_pl_staging/pl_skills/erp-feature-tdd/SKILL.md new file mode 100644 index 0000000..f476edc --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-tdd/SKILL.md @@ -0,0 +1,31 @@ +--- +name: erp-feature-tdd +description: Feature-loop step 3. Thin wrapper over superpowers:test-driven-development. Executes tasks from the plan one by one, each commit follows the commit-message-template. CRITICAL: every red→green test run is dispatched to a fresh subagent per design principle #7. +--- + +# erp-feature-tdd + +## Procedure + +1. **Red-flag gate**: `erp-red-flag-check`. +2. Load the plan at `docs/superpowers/plans/YYYY-MM-DD-.md`. +3. For each task in order: + a. Write the failing test(s) at `test_file::test_name`. + b. **Dispatch a fresh subagent via `Agent` (general-purpose) to run the test and confirm it fails**; the subagent returns `{command, exit_code, failing_assertion}` only. Main session does NOT run the test directly. + c. Implement the minimum code at `impl_file` to satisfy the test. + d. **Dispatch another fresh subagent to run the test and confirm it passes**. + e. On persistent failure (>5 attempts on the same test) → invoke `erp-red-flag-check` with flag #4. + f. Stage changes and commit using `templates/commit-message-template.md`; `scope` matches the task's module, `subject` short (≤50 chars), `req_id` mandatory. +4. After all tasks done → hand off to `erp-feature-verify`. + +## Guardrails + +- Never run `mvn test` / `pnpm test` / `scripts/test.sh` directly in the main session. Always via subagent. +- Every commit must include the REQ-XXX-NNN tag. +- Never batch unrelated changes into one commit. + +## References + +- `templates/commit-message-template.md` +- Delegates: `superpowers:test-driven-development` +- Guard: `erp-red-flag-check` diff --git a/_pl_staging/pl_skills/erp-feature-tdd/templates/commit-message-template.md b/_pl_staging/pl_skills/erp-feature-tdd/templates/commit-message-template.md new file mode 100644 index 0000000..ecf5222 --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-tdd/templates/commit-message-template.md @@ -0,0 +1 @@ +{{type}}({{scope}}): {{subject}} {{req_id}} diff --git a/_pl_staging/pl_skills/erp-feature-verify/SKILL.md b/_pl_staging/pl_skills/erp-feature-verify/SKILL.md new file mode 100644 index 0000000..d9ab289 --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-verify/SKILL.md @@ -0,0 +1,32 @@ +--- +name: erp-feature-verify +description: Feature-loop step 4. Thin wrapper over superpowers:verification-before-completion. Dispatches the REQ's test suite to a fresh subagent and renders the result through feature-verify-evidence-template. No "done" claim is allowed without this evidence. +--- + +# erp-feature-verify + +## Procedure + +1. Determine the feature's test target (Maven profile / pnpm script / pytest path) from the plan or the project's standard commands. +2. **Dispatch a fresh subagent via `Agent` (general-purpose)** with a prompt like: + + ``` + Task: run the feature's test target and report back. Do NOT modify code. Steps: + 1. Run: (e.g., mvn -pl user-module test -Dtest=REQ* ) + 2. Report ONLY structured JSON: {"command":"","exit_code":,"passed":,"failed":,"failed_list":["", ...],"stdout_excerpt":""} + No prose. + ``` + +3. Parse the JSON; read `templates/feature-verify-evidence-template.md`; fill slots including `subagent_id` and `conclusion`. +4. If `exit_code != 0` or `failed > 0` → print the filled evidence to session and **stop**. Do not proceed to review. +5. On pass → print the evidence; hand off to `erp-feature-review`. + +## Guardrails + +- Never paste raw test stdout into main session beyond the 30-line `stdout_excerpt`. +- Evidence must be rendered from the template, never freely written. + +## References + +- `templates/feature-verify-evidence-template.md` +- Delegates: `superpowers:verification-before-completion` diff --git a/_pl_staging/pl_skills/erp-feature-verify/templates/feature-verify-evidence-template.md b/_pl_staging/pl_skills/erp-feature-verify/templates/feature-verify-evidence-template.md new file mode 100644 index 0000000..efaa70b --- /dev/null +++ b/_pl_staging/pl_skills/erp-feature-verify/templates/feature-verify-evidence-template.md @@ -0,0 +1,16 @@ +## Verify evidence — {{req_id}} + +- 命令: `{{command}}` +- 子会话: {{subagent_id}} +- 退出码: {{exit_code}} +- 通过用例数: {{passed}} +- 失败用例数: {{failed}} +- 失败列表: {{failed_list}} + +关键 stdout 片段 (≤30 行): + +``` +{{stdout_excerpt}} +``` + +结论: {{conclusion}} （pass / fail） diff --git a/_pl_staging/pl_skills/erp-local-test-gate/SKILL.md b/_pl_staging/pl_skills/erp-local-test-gate/SKILL.md new file mode 100644 index 0000000..9c763d6 --- /dev/null +++ b/_pl_staging/pl_skills/erp-local-test-gate/SKILL.md @@ -0,0 +1,37 @@ +--- +name: erp-local-test-gate +description: The only hard gate before MR creation. Runs schema-baseline-check + placeholder-scan + scripts/test.sh. scripts/test.sh is dispatched to a fresh subagent (design principle #7). Non-zero on any check = stop. +--- + +# erp-local-test-gate + +## Procedure + +1. Invoke `erp-schema-baseline-check`. + - Dirty → flag #1 raised by the skill, stop. +2. Invoke `erp-placeholder-scan` over `docs/**`, `.env*`, `scripts/**`, `CLAUDE.md`. + - Non-empty hits → stop. +3. **Dispatch a fresh subagent (general-purpose)** to run `./scripts/test.sh`: + + ``` + Task: run the project's local test gate. Do NOT modify any code or data. Steps: + 1. cd to the repo root. + 2. Run: ./scripts/test.sh + 3. Report ONLY JSON: {"command":"./scripts/test.sh","exit_code":,"passed":,"failed":,"stdout_excerpt":""} + No prose. + ``` + +4. Read `templates/test-gate-result-template.md`; fill ① ② ③ slots with the three check results. +5. Write the rendered result to `docs/superpowers/module-reports/-test-gate.md`. +6. If `exit_code = 0` and both prior checks green → hand off to `erp-module-report` (print `local-test-gate: GREEN`). +7. Otherwise print `local-test-gate: RED ()` and stop. + +## Guardrails + +- **Never** invoke `./scripts/test.sh` directly from the main session. +- **Never** bypass via `git push --no-verify` (hook `deny-no-verify.sh` enforces). + +## References + +- `templates/test-gate-result-template.md` +- Upstream guards: `erp-schema-baseline-check`, `erp-placeholder-scan` diff --git a/_pl_staging/pl_skills/erp-local-test-gate/templates/test-gate-result-template.md b/_pl_staging/pl_skills/erp-local-test-gate/templates/test-gate-result-template.md new file mode 100644 index 0000000..0f012ef --- /dev/null +++ b/_pl_staging/pl_skills/erp-local-test-gate/templates/test-gate-result-template.md @@ -0,0 +1,22 @@ +## Local test gate — {{module_id}} + +执行时间: {{timestamp}} + +### ① Schema 基线比对 +{{schema_baseline_result}} + +### ② 占位扫描 +{{placeholder_scan_result}} + +### ③ scripts/test.sh (subagent) +- 子会话: {{subagent_id}} +- 命令: {{command}} +- 退出码: {{exit_code}} +- 通过: {{passed}} / 失败: {{failed}} +- 关键 stdout (≤30 行): + +``` +{{stdout_excerpt}} +``` + +结论: {{conclusion}} （green / red） diff --git a/_pl_staging/pl_skills/erp-module-report/SKILL.md b/_pl_staging/pl_skills/erp-module-report/SKILL.md new file mode 100644 index 0000000..c85300c --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-report/SKILL.md @@ -0,0 +1,31 @@ +--- +name: erp-module-report +description: After the local test gate is green, produce the standardized 12-section module completion report at docs/superpowers/module-reports/YYYY-MM-DD-.md. Embeds schema-scratch and cross-module logs verbatim. +--- + +# erp-module-report + +## Procedure + +1. Verify upstream: `erp-local-test-gate` returned GREEN. Otherwise stop. +2. Collect inputs (by globs + git): + - `git diff ..HEAD` → file changes (§ ③) + - `docs/superpowers/specs|plans|reviews/-.md` → § ②, § ⑨ + - `docs/superpowers/module-reports/-schema-scratch.md` → § ⑥ + - `docs/superpowers/module-reports/-cross-module.md` → § ⑦ + - `docs/superpowers/module-reports/-test-gate.md` → § ⑤ + - `docs/03` + actual code (grep) → § ④ (tables read/written) +3. Read `templates/module-report-template.md`; fill all 12 sections. +4. **Validation (hard)**: + - § ⑥: if schema-scratch has any row with TBD → stop, ask user (via erp-schema-scratch-log) to fill. + - § ⑦: if cross-module has any row with TBD → stop (erp-cross-module-log). + - § ⑦: if non-empty but no 影响评估 per row → stop. + - § ⑧ must enumerate every deviation from spec; if empty, explicitly write "无偏离". +5. Write `docs/superpowers/module-reports/$(date +%F)-.md`. +6. Hand off to `erp-mr-create`. + +## References + +- `templates/module-report-template.md` (12 sections) +- Upstream: `erp-local-test-gate` +- Downstream: `erp-mr-create` diff --git a/_pl_staging/pl_skills/erp-module-report/templates/module-report-template.md b/_pl_staging/pl_skills/erp-module-report/templates/module-report-template.md new file mode 100644 index 0000000..f743552 --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-report/templates/module-report-template.md @@ -0,0 +1,66 @@ +--- +module_id: {{module_id}} +date: {{date}} +git_range: {{git_range}} +--- + +# 模块完成报告 — {{module_id}} {{module_name}} + +## ① 模块信息 +- 模块 ID: {{module_id}} +- 模块名: {{module_name}} +- 开发区间: {{git_range}} +- 开发天数: {{duration_days}} + +## ② REQ 完成清单 +{{#each reqs}} +- [{{status}}] {{req_id}} — {{title}} + - spec: docs/superpowers/specs/{{date}}-{{req_id}}.md + - plan: docs/superpowers/plans/{{date}}-{{req_id}}.md + - review: docs/superpowers/reviews/{{date}}-{{req_id}}.md +{{/each}} + +## ③ 文件变更表 +| 文件 | 操作 | 说明 | +|---|---|---| +{{#each file_changes}} +| {{path}} | {{action}} | {{note}} | +{{/each}} + +## ④ 数据库使用表 +- 读: {{tables_read}} +- 写: {{tables_written}} + +## ⑤ 测试结果 +- `scripts/test.sh` 最终：{{test_conclusion}} +- 通过: {{passed}} / 失败: {{failed}} / 跳过: {{skipped}} +- 覆盖率: {{coverage}} + +## ⑥ Schema 临时改动清单（软规则 S1） + +{{schema_scratch_contents}} + +回撤验证: {{rollback_verified}} （见 erp-schema-baseline-check 结果） + +## ⑦ 跨模块改动清单（软规则 S2） + +{{cross_module_contents}} + +## ⑧ 偏离 spec 清单 +{{#each deviations}} +- {{req_id}}: {{deviation}} （原因: {{reason}}） +{{/each}} + +## ⑨ AI reviewer 报告汇总 +{{#each reviews}} +- {{req_id}}: round {{round}} — {{verdict}}（link: docs/superpowers/reviews/{{date}}-{{req_id}}.md） +{{/each}} + +## ⑩ 已知问题 +{{known_issues}} + +## ⑪ 下一模块预览 +{{next_module}} + +## ⑫ MR 链接 +{{mr_url}} diff --git a/_pl_staging/pl_skills/erp-module-start/SKILL.md b/_pl_staging/pl_skills/erp-module-start/SKILL.md new file mode 100644 index 0000000..2967566 --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-start/SKILL.md @@ -0,0 +1,31 @@ +--- +name: erp-module-start +description: Start the module loop. Locate the first `confirmed: false` module in docs/08, initialize schema-scratch & cross-module log files, print a module banner, and drive the feature loop over each REQ in order. +--- + +# erp-module-start + +## Procedure + +1. Read `docs/08-模块任务管理.md`. Locate the first `confirmed: false` module; extract `module_id`, `module_name`, REQ list, dependencies. +2. If no such module → all modules done; print a completion summary and stop. +3. Initialize logs (idempotent): + - `docs/superpowers/module-reports/-schema-scratch.md` — if missing, write from `templates/schema-scratch-log-template.md` with `module_name` slot. + - `docs/superpowers/module-reports/-cross-module.md` — if missing, write from `templates/cross-module-log-template.md`. +4. Read `templates/module-start-banner-template.md`; fill slots and print to session. +5. For each REQ in order: + a. `erp-red-flag-check` → stop if hit. + b. `erp-feature-brainstorm` + c. `erp-feature-plan` + d. `erp-feature-tdd` + e. `erp-feature-verify` + f. `erp-feature-review` + g. Any halt → stop the module; do not skip to the next REQ silently. +6. After all REQs done → invoke `erp-local-test-gate`. + +## References + +- `templates/module-start-banner-template.md` +- `templates/schema-scratch-log-template.md` +- `templates/cross-module-log-template.md` +- Downstream: `erp-feature-*`, `erp-local-test-gate` diff --git a/_pl_staging/pl_skills/erp-module-start/templates/cross-module-log-template.md b/_pl_staging/pl_skills/erp-module-start/templates/cross-module-log-template.md new file mode 100644 index 0000000..8c8ef54 --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-start/templates/cross-module-log-template.md @@ -0,0 +1,6 @@ +# 跨模块改动日志 — {{module_name}} + +软规则 S2：本模块开发期间对其他 `confirmed: true` 模块代码的改动记录在此；模块完成报告必须单列「跨模块改动」节完整贴入。漏留痕或未评估影响 → 升级为红旗。 + +| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 | +|---|---|---|---|---|---| diff --git a/_pl_staging/pl_skills/erp-module-start/templates/module-start-banner-template.md b/_pl_staging/pl_skills/erp-module-start/templates/module-start-banner-template.md new file mode 100644 index 0000000..e1b35eb --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-start/templates/module-start-banner-template.md @@ -0,0 +1,10 @@ +## Module start — {{module_id}} ({{module_name}}) + +- 模块依赖: {{depends_on}} +- 对应需求文件: docs/01-需求清单/{{req_file}} +- 功能清单: +{{#each reqs}} + - [ ] {{req_id}} — {{title}} +{{/each}} + +开始功能循环（Layer 3）依次跑每个 REQ。命中红旗 → 停；完成所有 REQ → 进入模块闸门。 diff --git a/_pl_staging/pl_skills/erp-module-start/templates/schema-scratch-log-template.md b/_pl_staging/pl_skills/erp-module-start/templates/schema-scratch-log-template.md new file mode 100644 index 0000000..86b7ff2 --- /dev/null +++ b/_pl_staging/pl_skills/erp-module-start/templates/schema-scratch-log-template.md @@ -0,0 +1,6 @@ +# Schema 临时改动日志 — {{module_name}} + +软规则 S1：本模块开发期间对 schema 的所有临时 DDL 都应记录在此；模块闸门前必须全部回撤到基线（`docs/superpowers/schema-baseline.sql`）。未回撤 → 升级为红旗。 + +| 时间戳 | SQL | 原因 | 预计回撤时机 | +|---|---|---|---| diff --git a/_pl_staging/pl_skills/erp-mr-create/SKILL.md b/_pl_staging/pl_skills/erp-mr-create/SKILL.md new file mode 100644 index 0000000..1c338a4 --- /dev/null +++ b/_pl_staging/pl_skills/erp-mr-create/SKILL.md @@ -0,0 +1,34 @@ +--- +name: erp-mr-create +description: After the module completion report is written, git push and create a GitLab MR with the module report embedded in the description. The only action that touches the remote. Stops to wait for human review. +--- + +# erp-mr-create + +## Pre-conditions + +- `erp-module-report` produced the report file. +- `erp-local-test-gate` returned GREEN (re-check just before push; fail if file mtime older than latest commit). + +## Procedure + +1. Ensure current branch is a feature branch (not main/master). If needed: `git checkout -b module-`. +2. `git push -u origin ` — do NOT use `--no-verify` (hook `deny-no-verify.sh` would block anyway). +3. Read `templates/mr-title-template.md`; fill `module_id`, `module_name`. +4. Read `templates/mr-description-template.md`; fill slots: + - `module_report_contents` = full text of `docs/superpowers/module-reports/-.md` + - `test_gate_conclusion`, `test_subagent_id`, `schema_rollback_conclusion`, `placeholder_conclusion` +5. Create the MR: + + ```bash + glab mr create --title "$(, "tables_count": <int>, "error": "<if any>"} +``` + +If `connected: false` → stop, surface error to user. + +### C. Freeze baseline (subagent) +**Dispatch a fresh subagent** to run: +``` +mysqldump --no-data --skip-comments -h<host> -P<port> -u<user> -p<password> <schema> +``` +and return the full dump body (as a text block). + +The subagent must NOT modify the DB. Only mysqldump. + +### D. Write baseline file +1. Read `templates/schema-baseline-header-template.sql`. +2. Fill slots: `project_name`, `timestamp`, `schema_name`, `dump_body` (from subagent). +3. Write `docs/superpowers/schema-baseline.sql`. + +### E. Validate +Read back `docs/superpowers/schema-baseline.sql` — must contain `CREATE TABLE` statements for the tables listed in step B. + +Print: `mysql-mcp-setup: DONE (schema=<name>, tables=<n>, baseline=docs/superpowers/schema-baseline.sql)`. + +## Invariants + +- CC never runs DDL during setup. +- Subagent prompts must explicitly forbid mutations. + +## References + +- `templates/mcp-json-template.json` +- `templates/schema-baseline-header-template.sql` diff --git a/_pl_staging/pl_skills/erp-mysql-mcp-setup/templates/mcp-json-template.json b/_pl_staging/pl_skills/erp-mysql-mcp-setup/templates/mcp-json-template.json new file mode 100644 index 0000000..6482afc --- /dev/null +++ b/_pl_staging/pl_skills/erp-mysql-mcp-setup/templates/mcp-json-template.json @@ -0,0 +1,15 @@ +{ + "mcpServers": { + "mysql": { + "command": "npx", + "args": ["-y", "@benborla29/mcp-server-mysql"], + "env": { + "MYSQL_HOST": "{{db_host}}", + "MYSQL_PORT": "{{db_port}}", + "MYSQL_USER": "{{db_user}}", + "MYSQL_PASS": "{{db_password}}", + "MYSQL_DB": "{{db_schema}}" + } + } + } +} diff --git a/_pl_staging/pl_skills/erp-placeholder-scan/SKILL.md b/_pl_staging/pl_skills/erp-placeholder-scan/SKILL.md new file mode 100644 index 0000000..c2ee8fe --- /dev/null +++ b/_pl_staging/pl_skills/erp-placeholder-scan/SKILL.md @@ -0,0 +1,40 @@ +--- +name: erp-placeholder-scan +description: Scan for 占位符 residuals (`【人工填写：...】`, `your_password`, `your-secret-key`, `N.x` 版本号) in docs/, .env files, scripts/. Invoke after any Write to these locations and always before the module local-test-gate. Produces a scan result following a fixed template. +--- + +# erp-placeholder-scan + +## What + +Detect unfilled placeholders. Any hit in a release-blocking scope (module gate) → stop and list residuals for user to fill. + +## Patterns (all case-sensitive unless noted) + +- `【人工填写：` — primary placeholder marker +- `your_password`, `your-secret-key` — generic naked placeholders +- `^\d+\.x$` or `^\d+\.\d+\.x$` — unlocked tech-stack minor versions + +## Scope + +- `docs/**` +- `.env*` (not `.env.local` if the user has intentionally committed secrets? no — still scan; user decides) +- `scripts/**` +- `CLAUDE.md` (header section only) + +## Procedure + +1. Run ripgrep (via Grep tool) for each pattern across scope. +2. Aggregate hits into a list of `(file, line, match)`. +3. Read `templates/placeholder-scan-result-template.md`; fill slots. +4. If hits found in module-gate context: stop the caller, print the filled template to session. +5. If no hits: print `placeholder-scan: PASS` to session only. + +## When called by `erp-local-test-gate` + +A non-empty result fails the gate — caller must stop. + +## References + +- `templates/placeholder-scan-result-template.md` +- `CLAUDE.md` § 🏷️ 占位符统一约定 diff --git a/_pl_staging/pl_skills/erp-placeholder-scan/templates/placeholder-scan-result-template.md b/_pl_staging/pl_skills/erp-placeholder-scan/templates/placeholder-scan-result-template.md new file mode 100644 index 0000000..51711b7 --- /dev/null +++ b/_pl_staging/pl_skills/erp-placeholder-scan/templates/placeholder-scan-result-template.md @@ -0,0 +1,13 @@ +## 占位符扫描结果 + +扫描时间: {{timestamp}} +扫描范围: {{scan_globs}} +命中总数: {{hit_count}} + +| 文件 | 行号 | 命中串 | +|---|---|---| +{{#each hits}} +| {{file}} | {{line}} | `{{match}}` | +{{/each}} + +结论: {{conclusion}} （pass=无残留 / fail=需人工补齐） diff --git a/_pl_staging/pl_skills/erp-red-flag-check/SKILL.md b/_pl_staging/pl_skills/erp-red-flag-check/SKILL.md new file mode 100644 index 0000000..63a1dfb --- /dev/null +++ b/_pl_staging/pl_skills/erp-red-flag-check/SKILL.md @@ -0,0 +1,46 @@ +--- +name: erp-red-flag-check +description: Use before each feature-loop step (Brainstorm/Plan/TDD/Verify/Review) and before generating any major artifact. Runs the 6-item red-flag checklist from CLAUDE.md; on any hit, appends a Blocker block to the current plan file and stops silent execution. +--- + +# erp-red-flag-check + +## What + +Verify none of the 6 red flags from `CLAUDE.md` § 🚩 静默执行红旗清单 are active. Halt on any hit. + +## When to invoke + +- Before starting any feature-loop step (3.1-3.5) +- Before generating a module-level artifact (module report, MR description) +- Any time the user's request implies a schema conflict, tech-stack boundary, or external dependency + +## Checklist (6 items — source of truth: CLAUDE.md) + +1. **需求与 schema 冲突** — needed fields/tables missing in live schema +2. **需求本身歧义** — two or more reasonable interpretations +3. **超技术栈边界** — requires framework/middleware outside CLAUDE.md 技术栈表 +4. **测试反复失败** — same test failing after 5 consecutive fix attempts in the current feature +5. **要改密钥 / 账密 / 包名** — touching placeholders in `docs/07-环境配置.md` +6. **外部接口不可达** — third-party API / cert / network issue + +## Procedure + +1. Read the current feature's spec/plan path (from conversation or `docs/08`). +2. For each of the 6 flags, check explicitly. If none hit → print `red-flag-check: PASS` to session, exit. +3. On hit: + - Read `templates/red-flag-block-template.md` + - Fill slots (flag_number, flag_name, description, affected_scope, recommendation, decision_needed) + - Append the rendered block to the current plan file: `docs/superpowers/plans/YYYY-MM-DD-<REQ-id>.md` + - Print a 1-sentence session summary pointing to the plan file + - **Stop** — do not invoke any further skill until the user decides + +## Output + +Either `red-flag-check: PASS` (session only), or a `## 🚩 Blocker` block appended to the feature plan file. + +## References + +- `templates/red-flag-block-template.md` +- `CLAUDE.md` § 🚩 静默执行红旗清单（权威 6 条） +- `CLAUDE.md` § 🟡 软规则（S1/S2，不触发红旗但需留痕） diff --git a/_pl_staging/pl_skills/erp-red-flag-check/templates/red-flag-block-template.md b/_pl_staging/pl_skills/erp-red-flag-check/templates/red-flag-block-template.md new file mode 100644 index 0000000..8d1278e --- /dev/null +++ b/_pl_staging/pl_skills/erp-red-flag-check/templates/red-flag-block-template.md @@ -0,0 +1,8 @@ +## 🚩 Blocker + +**红旗编号**: {{flag_number}} (1-6，对应 CLAUDE.md 🚩 静默执行红旗清单) +**红旗名称**: {{flag_name}} +**问题描述**: {{description}} +**影响范围**: {{affected_scope}} +**我的建议**: {{recommendation}} +**等待决策**: {{decision_needed}} diff --git a/_pl_staging/pl_skills/erp-requirements-gen/SKILL.md b/_pl_staging/pl_skills/erp-requirements-gen/SKILL.md new file mode 100644 index 0000000..77b3f39 --- /dev/null +++ b/_pl_staging/pl_skills/erp-requirements-gen/SKILL.md @@ -0,0 +1,48 @@ +--- +name: erp-requirements-gen +description: From the human-authored requirement outline in docs/01-需求清单/README.md and the live MySQL schema, generate full REQ-XXX-NNN cards under docs/01 and the DB design doc docs/03. +--- + +# erp-requirements-gen + +## Pre-conditions + +- `docs/01-需求清单/README.md` exists with per-module bullet outlines (author: human). +- MCP + baseline ready (`erp-mysql-mcp-setup` done). + +## Procedure + +### A. Parse README outline +For each module bullet, extract: `module_code` (SYS / PUR / INV / ...), `module_name`, function bullets. + +Ask user via `AskUserQuestion` to clarify any ambiguous mapping. + +### B. Generate REQ cards +For each function bullet: +1. Assign `REQ-<MOD>-<NNN>` (increment per module). +2. Interactively fill the card via `AskUserQuestion` + inference from context: + - 目标 / 输入 / 输出 / 业务规则 / 边界 / 依赖表（验证存在）/ 依赖接口（先占位）/ 验收 +3. Read `templates/req-card-template.md`; render. + +### C. Assemble per-module files +For each module, read `templates/docs-01-module-template.md`, fill with `reqs[]`, write `docs/01-需求清单/<module_code>-<module_name>.md`. + +### D. Generate docs/03 +1. **Dispatch subagent** to query the live schema via MCP and return a structured list: tables + columns + indexes + FKs + types. +2. Read `templates/docs-03-header-template.md`; fill `schema_name`, `er_overview`, `tables[]`. +3. For each table, read `templates/docs-03-table-template.md`; fill and append. +4. Business meaning of each column: infer from REQ cards or ask user. +5. Write `docs/03-数据库设计文档.md`. + +### E. Sanity checks +- Every REQ must reference at least one table that exists in docs/03. +- Every table in docs/03 must appear in at least one REQ (else print a warning; may be an unused table or a missing requirement). + +Print: `requirements-gen: <M> modules, <N> REQs, <T> tables. Awaiting human review of 01/03.` + +## References + +- `templates/req-card-template.md` +- `templates/docs-01-module-template.md` +- `templates/docs-03-header-template.md` +- `templates/docs-03-table-template.md` diff --git a/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-01-module-template.md b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-01-module-template.md new file mode 100644 index 0000000..4534a7d --- /dev/null +++ b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-01-module-template.md @@ -0,0 +1,11 @@ +# {{module_code}}-{{module_name}} + +模块简述: {{module_brief}} +依赖模块: {{depends_on}} +涉及表: {{tables}} + +## 功能清单 + +{{#each reqs}} +{{req_card}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-header-template.md b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-header-template.md new file mode 100644 index 0000000..55ef00f --- /dev/null +++ b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-header-template.md @@ -0,0 +1,14 @@ +# 03-数据库设计文档 + +Schema: `{{schema_name}}` +基线快照: `docs/superpowers/schema-baseline.sql` +生成方式: 通过 MCP (`mcp__mcp_server_mysql__mysql_query`) 从 live schema 反查生成。 + +## ER 关系概览 + +{{er_overview}} + +## 表清单 +{{#each tables}} +- `{{table_name}}` — {{purpose}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-table-template.md b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-table-template.md new file mode 100644 index 0000000..dfdc35a --- /dev/null +++ b/_pl_staging/pl_skills/erp-requirements-gen/templates/docs-03-table-template.md @@ -0,0 +1,22 @@ +## `{{table_name}}` — {{purpose}} + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +{{#each columns}} +| {{name}} | {{type}} | {{nullable}} | {{default}} | {{business_meaning}} | +{{/each}} + +### 索引 +{{#each indexes}} +- `{{name}}` ({{type}}): {{columns}} +{{/each}} + +### 外键 +{{#each foreign_keys}} +- `{{name}}`: {{from_col}} → {{to_table}}.{{to_col}} ({{on_delete}}) +{{/each}} + +### 业务注记 +{{notes}} diff --git a/_pl_staging/pl_skills/erp-requirements-gen/templates/req-card-template.md b/_pl_staging/pl_skills/erp-requirements-gen/templates/req-card-template.md new file mode 100644 index 0000000..a616c59 --- /dev/null +++ b/_pl_staging/pl_skills/erp-requirements-gen/templates/req-card-template.md @@ -0,0 +1,10 @@ +### {{req_id}} {{title}} + +- **目标**: {{goal}} +- **输入**: {{input}} +- **输出**: {{output}} +- **业务规则**: {{rules}} +- **边界**: {{constraints}} +- **依赖表**: {{schema_refs}} +- **依赖接口**: {{api_refs}} +- **验收**: {{acceptance}} diff --git a/_pl_staging/pl_skills/erp-schema-baseline-check/SKILL.md b/_pl_staging/pl_skills/erp-schema-baseline-check/SKILL.md new file mode 100644 index 0000000..70417e3 --- /dev/null +++ b/_pl_staging/pl_skills/erp-schema-baseline-check/SKILL.md @@ -0,0 +1,34 @@ +--- +name: erp-schema-baseline-check +description: Verify the live MySQL schema matches the frozen baseline (`docs/superpowers/schema-baseline.sql`). Invoke before the module local-test-gate and before any `confirmed` flip. Any diff = 软规则 S1 未回撤 → 升级为红旗 #1. Execution is delegated to a fresh subagent per design principle #7. +--- + +# erp-schema-baseline-check + +## What + +Confirm schema has been rolled back to baseline before declaring a module done. + +## Procedure + +1. Locate baseline file: `docs/superpowers/schema-baseline.sql`. If missing → stop with error "baseline not initialized; run erp-mysql-mcp-setup first". +2. Read env: `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_SCHEMA` from `.env.local` (or prompt user). +3. **Dispatch a fresh subagent via `Agent` tool (subagent_type: general-purpose)** with this prompt: + + ``` + Task: verify MySQL schema matches a frozen baseline. Do NOT make any changes. Steps: + 1. Run: mysqldump --no-data --skip-comments -h<host> -P<port> -u<user> -p<password> <schema> > /tmp/current-schema.sql + 2. Diff against: <absolute path to baseline> + 3. Report back ONLY a structured JSON object (no prose): {"diff_lines": <int>, "deviations": [{"type": "added_table|dropped_column|...", "object": "<name>", "change": "<one-line>"}], "conclusion": "clean|dirty"} + Limit: if the diff exceeds 200 lines, truncate deviations to the first 20 and note "truncated". + ``` + +4. Read the subagent's JSON result. +5. Read `templates/schema-baseline-diff-template.md`; fill slots including `subagent_id` = the agent description/ID. +6. If `conclusion = dirty` → invoke `erp-red-flag-check` with flag #1 and stop the caller. +7. If `conclusion = clean` → print `schema-baseline-check: PASS` to session. + +## References + +- `templates/schema-baseline-diff-template.md` +- `CLAUDE.md` § 🟡 软规则 S1 diff --git a/_pl_staging/pl_skills/erp-schema-baseline-check/templates/schema-baseline-diff-template.md b/_pl_staging/pl_skills/erp-schema-baseline-check/templates/schema-baseline-diff-template.md new file mode 100644 index 0000000..7a908e1 --- /dev/null +++ b/_pl_staging/pl_skills/erp-schema-baseline-check/templates/schema-baseline-diff-template.md @@ -0,0 +1,16 @@ +## Schema 基线比对结果 + +比对时间: {{timestamp}} +基线文件: docs/superpowers/schema-baseline.sql +当前 schema: {{schema_name}} @ {{db_host}} +执行方式: subagent ({{subagent_id}}) + +diff 行数: {{diff_lines}} + +### 偏离清单 + +{{#each deviations}} +- {{type}}: {{object}} — {{change}} +{{/each}} + +结论: {{conclusion}} （clean=已回撤 / dirty=未回撤，升级红旗 #1） diff --git a/_pl_staging/pl_skills/erp-schema-scratch-log/SKILL.md b/_pl_staging/pl_skills/erp-schema-scratch-log/SKILL.md new file mode 100644 index 0000000..3ff2c4e --- /dev/null +++ b/_pl_staging/pl_skills/erp-schema-scratch-log/SKILL.md @@ -0,0 +1,33 @@ +--- +name: erp-schema-scratch-log +description: Fill in 原因 and 预计回撤时机 for DDL stub rows that the `log-ddl.sh` hook auto-appended to `docs/superpowers/module-reports/<current>-schema-scratch.md`. Triggered by the hook's PostToolUse notification or invoked directly before running DDL. +--- + +# erp-schema-scratch-log + +## What + +Soft-rule S1 enforcement: every DDL during debug must be logged with reason + rollback plan. + +## Procedure + +1. Identify the current module (first `confirmed: false` entry in `docs/08-模块任务管理.md`). +2. Open `docs/superpowers/module-reports/<current>-schema-scratch.md`. +3. If file does not exist → initialize it by reading `templates/schema-scratch-log-template.md` and writing with `module_name` slot filled. +4. Find rows with `TBD(待填)` in 原因 or 预计回撤时机 columns. +5. For each TBD row, ask the user (AskUserQuestion) or infer from recent conversation context: + - **原因**: what was the debug goal? + - **预计回撤时机**: 本功能结束前 / 本模块 gate 前 / 其他 +6. Edit the row (keep the same timestamp + SQL columns). +7. Print a one-line confirmation: `schema-scratch-log: N rows updated`. + +## Invariants + +- Never mutate the 时间戳 or SQL columns of existing rows. +- Never remove rows; rollback is tracked by `erp-schema-baseline-check`, not by deletion here. + +## References + +- `templates/schema-scratch-log-template.md` (file header) +- `templates/schema-scratch-log-row-template.md` (single row) +- `CLAUDE.md` § 🟡 软规则 S1 diff --git a/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-row-template.md b/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-row-template.md new file mode 100644 index 0000000..bc63449 --- /dev/null +++ b/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-row-template.md @@ -0,0 +1 @@ +| {{timestamp}} | `{{sql}}` | {{reason}} | {{rollback_plan}} | diff --git a/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-template.md b/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-template.md new file mode 100644 index 0000000..86b7ff2 --- /dev/null +++ b/_pl_staging/pl_skills/erp-schema-scratch-log/templates/schema-scratch-log-template.md @@ -0,0 +1,6 @@ +# Schema 临时改动日志 — {{module_name}} + +软规则 S1：本模块开发期间对 schema 的所有临时 DDL 都应记录在此；模块闸门前必须全部回撤到基线（`docs/superpowers/schema-baseline.sql`）。未回撤 → 升级为红旗。 + +| 时间戳 | SQL | 原因 | 预计回撤时机 | +|---|---|---|---| diff --git a/_pl_staging/pl_skills/erp-session-start/SKILL.md b/_pl_staging/pl_skills/erp-session-start/SKILL.md new file mode 100644 index 0000000..01c6ce7 --- /dev/null +++ b/_pl_staging/pl_skills/erp-session-start/SKILL.md @@ -0,0 +1,104 @@ +--- +name: erp-session-start +description: Top-level orchestrator. Run at the start of any ERP-project session (or manually via /erp-session-start). Detects the current project phase and dispatches to the next skill. Never generates files directly. +--- + +# erp-session-start + +## 整体流程（给用户看） + +本项目分两大阶段：**先规划，再编码**。CC 自动探测当前位置、打印阶段横幅、分发到下一步。你只在 ⏸ 卡点处介入。 + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ 锁技术栈 → 生项目骨架 → 接数据库 → 生需求/DB文档 │ +│ ↓ │ +│ 输出「理解确认报告」 │ +│ ↓ │ +│ ⏸ 等你回复「理解正确」 才进入阶段 B │ +└──────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────┐ +│ 🔁 阶段 B：编码（按模块循环，每模块包含多个功能） │ +│ │ +│ 一个模块 = 多个功能（REQ-XXX-NNN）： │ +│ │ +│ ┌─ 功能循环（每个 REQ 跑一遍）────────────────┐ │ +│ │ Brainstorm → Plan → TDD → Verify → Review │ │ +│ └────────────────────────────────────────────┘ │ +│ ↓ 本模块全部功能完成 │ +│ 本地测试闸门 → 写模块报告 → 建 GitLab MR │ +│ ↓ │ +│ ⏸ 等你 Approve + Merge MR │ +│ ↓ │ +│ 标记模块完成 → 自动进入下一个模块 │ +└──────────────────────────────────────────────────────┘ + +⚙️ 后台守门（任意阶段命中即停下问你，不会静默继续）： + • 文档/配置里有未填的【人工填写：】占位符 + • 命中红旗清单（schema 冲突 / 需求歧义 / 超技术栈 等 6 项） + • 数据库 schema 偏离已冻结的基线 + • 调试期间临时 DDL 未在模块结束前回撤 + • 改了已完成模块的代码但没记录原因和影响 +``` + +## 分发梯（按优先级，首条命中即停） + +**A 阶段 · 计划（一次性）** + +1. **A1 技术栈未锁定** — `CLAUDE.md` 顶部 4 meta slots（项目名称/简述/目标用户/部署方式）或技术栈表含 `【人工填写：` + → `erp-tech-stack-lock` +2. **A2 骨架文件缺失** — `docs/04-技术规范.md` / `docs/07-环境配置.md` / `docs/09-项目目录结构.md` / `scripts/test.sh` / `scripts/setup-test-db.sh` / `.githooks/pre-push` / `.env.local.example` 任一缺失 + → `erp-skeleton-gen` +3. **A3 MCP + schema 基线未建立** — `.mcp.json` 或 `docs/superpowers/schema-baseline.sql` 缺失 + → `erp-mysql-mcp-setup` +4. **A4 需求 & DB 文档缺失** — `docs/01-需求清单/` 只有 README 或 `docs/03-数据库设计文档.md` 没有生成的表 + → `erp-requirements-gen` +5. **A5 下游文档缺失** — `docs/02-开发计划.md` / `docs/05-API接口契约.md` / `docs/08-模块任务管理.md` / `docs/10-验收检查清单.md` / `sql/seed-data.sql` 任一缺失 + → `erp-downstream-gen` +6. **A6 未输出过理解确认报告**（且人工未回复「理解正确」） + → `erp-understanding-report` + +**横切守门** + +7. **X1 占位残留** — 内联跑 `erp-placeholder-scan`，结果非空 + → 停下打印清单，等人填 + +**B 阶段 · 编码（按模块循环）** + +8. **B5 待翻 confirmed** — `docs/08` 当前 `confirmed:false` 模块对应的 MR 已 Merged（`glab mr view` 或用户告知） + → `erp-confirmed-update` +9. **B1 默认** — 进入或继续模块循环 + → `erp-module-start` + +## 执行步骤 + +1. **收集状态** + - 读 `CLAUDE.md` 头部 + - Glob `docs/**`、`scripts/**`、`.githooks/**`、`.mcp.json`、`docs/superpowers/schema-baseline.sql` + - 读 `docs/08-模块任务管理.md` + - `git log -1`；若 `glab` 可用则 `glab mr list --state=opened` + +2. **打印阶段横幅（必须输出给用户看）** + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-session-start] + 阶段：<A 计划 | B 编码 | 横切守门> + 命中：<编号> <label> （例：A1 技术栈未锁定） + 当前模块：<module_id 或 —> （B 阶段才填） + 下一步：invoke <skill> + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + +3. **红旗联动** — 分发目标属于 B 阶段（`erp-module-*` / `erp-feature-*`）时，先调 `erp-red-flag-check`；命中红旗则停在此不分发。 + +4. **分发** — 通过 `Skill` 工具调用选中的下游 skill。本 skill 不直接产出任何制品。 + +## References + +- `CLAUDE.md`（项目指令） +- `docs/08-模块任务管理.md`（confirmed 状态） +- `.claude/skills/erp-*`（下游 skills） diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/SKILL.md b/_pl_staging/pl_skills/erp-skeleton-gen/SKILL.md new file mode 100644 index 0000000..4911a25 --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/SKILL.md @@ -0,0 +1,58 @@ +--- +name: erp-skeleton-gen +description: Generate the technical skeleton files (docs/04, docs/06 一~四节, docs/07, docs/09) and scripts/ + .githooks/ + .env.local.example. Reads the locked tech stack from CLAUDE.md; emits files from dedicated templates. All sensitive values left as `【人工填写：...】`. +--- + +# erp-skeleton-gen + +## Pre-conditions + +- CLAUDE.md header is locked (`erp-tech-stack-lock` has run; no `【人工填写：` in the 4 meta slots). + +## Procedure + +### A. Read tech stack +From CLAUDE.md § 🏗️ 技术栈, parse rows into memory. + +### B. Emit docs/ +For each target below, read the named template, fill stack-derived slots, Write to target path. Files that already exist → stop and ask (`overwrite? skip?`); do not silently clobber. + +| Target | Template | +|---|---| +| `docs/04-技术规范.md` | `templates/docs-04-skeleton-template.md` | +| `docs/06-UI交互规范.md` | `templates/docs-06-static-template.md` | +| `docs/07-环境配置.md` | `templates/docs-07-env-template.md` | +| `docs/09-项目目录结构.md` | `templates/docs-09-structure-template.md` | + +Slot examples: `backend_layering`, `backend_package_convention`, `backend_class_convention`, `frontend_layout`, `controller_rule`, etc. + +- Where a value is project-specific (root package name / namespace), keep the placeholder `【人工填写：<说明>】` and register it in the `zero-section placeholder table` of `docs/07`. + +### C. Emit scripts/ and .githooks/ and .env example + +| Target | Template | +|---|---| +| `scripts/test.sh` | `templates/scripts-test-sh-template.sh` | +| `scripts/setup-test-db.sh` | `templates/scripts-setup-test-db-template.sh` | +| `.githooks/pre-push` | `templates/githooks-pre-push-template.sh` | +| `.env.local.example` | `templates/env-local-example-template` | + +After writing, `chmod +x scripts/*.sh .githooks/pre-push`. + +Run: `git config core.hooksPath .githooks` (ask user confirmation before changing git config — this touches shared state). + +### D. Validate + +- `erp-placeholder-scan` over newly written files: hits are expected (we want them registered in § 零, speed-table). +- Print summary: `skeleton-gen: wrote N files. Placeholders to fill: M (see docs/07 § 零、人工占位速查表).` + +## References + +- `templates/docs-04-skeleton-template.md` +- `templates/docs-06-static-template.md` +- `templates/docs-07-env-template.md` +- `templates/docs-09-structure-template.md` +- `templates/scripts-test-sh-template.sh` +- `templates/scripts-setup-test-db-template.sh` +- `templates/githooks-pre-push-template.sh` +- `templates/env-local-example-template` diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-04-skeleton-template.md b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-04-skeleton-template.md new file mode 100644 index 0000000..7fcfc3f --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-04-skeleton-template.md @@ -0,0 +1,50 @@ +# 04-技术规范 + +## 一、后端规范 + +### 1.1 分层结构 +{{backend_layering}} + +### 1.2 命名约定 +- 包名: {{backend_package_convention}} +- 类名: {{backend_class_convention}} +- 方法名: {{backend_method_convention}} + +### 1.3 统一响应格式 +```json +{"code": 200, "message": "", "data": {}, "timestamp": 0} +``` + +### 1.4 异常处理 +{{backend_exception_strategy}} + +### 1.5 事务 +{{backend_tx_strategy}} + +### 1.6 JWT 认证 +{{backend_jwt}} + +## 二、前端规范 + +### 2.1 目录约定 +{{frontend_layout}} + +### 2.2 状态管理 +{{frontend_state}} + +### 2.3 请求封装 +{{frontend_http}} + +### 2.4 错误处理 +{{frontend_error}} + +## 三、共同约定 + +### 3.1 Git 提交 +`<type>(<scope>): <subject> REQ-XXX-NNN` + +### 3.2 分页查询 +{{pagination_rule}} + +### 3.3 日期与金额 +{{datetime_money_rule}} diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-06-static-template.md b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-06-static-template.md new file mode 100644 index 0000000..3931e69 --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-06-static-template.md @@ -0,0 +1,45 @@ +# 06-UI交互规范 + +## 一、整体布局 + +### 1.1 页面框架 +{{layout_frame}} + +### 1.2 布局参数 +| 参数 | 值 | 说明 | +|---|---|---| +| Header高度 | 64px | 固定定位 | +| Sidebar宽度 | 220px（展开）/ 64px（折叠） | 可手动切换 | +| 内容区内边距 | 24px | 四周 | +| 最小支持宽度 | 1280px | 不做移动端适配 | + +## 二、标准页面类型 + +### 2.1 列表页 +{{list_page}} + +### 2.2 表单页 +{{form_page}} + +### 2.3 详情页 +{{detail_page}} + +### 2.4 树形管理页 +{{tree_page}} + +## 三、通用交互规则 + +### 3.1 操作反馈 +{{feedback_rules}} + +### 3.2 数据展示 +{{display_rules}} + +### 3.3 权限控制（前端） +{{permission_rules}} + +## 四、主题与颜色 +{{theme_rules}} + +## 五、页面清单（CC 生成） +（由 `erp-downstream-gen` 按模块追加段落） diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-07-env-template.md b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-07-env-template.md new file mode 100644 index 0000000..2a87f9b --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-07-env-template.md @@ -0,0 +1,37 @@ +# 07-环境配置 + +## 零、人工占位速查表 + +| 占位符 | 位置 | 说明 | +|---|---|---| +{{#each placeholders}} +| {{marker}} | {{location}} | {{note}} | +{{/each}} + +## 一、依赖清单 +{{#each deps}} +- {{name}} {{version}} — {{purpose}} +{{/each}} + +## 二、端口约定 +| 服务 | 端口 | +|---|---| +{{#each ports}} +| {{service}} | {{port}} | +{{/each}} + +## 三、环境变量（.env.local.example） +见 `.env.local.example`。敏感值 `【人工填写：...】` 由人工替换。 + +## 四、数据库连接 +- Host: `【人工填写：MySQL host】` +- Port: `【人工填写：MySQL port，默认 3306】` +- Schema: `【人工填写：schema 名】` +- 字符集: `【人工填写，例如 utf8mb4】` +- 账号: `【人工填写：只读/读写账号】` +- 密码: `【人工填写：对应密码】` + +## 五、常用命令 +{{#each commands}} +- `{{command}}` — {{description}} +{{/each}} diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-09-structure-template.md b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-09-structure-template.md new file mode 100644 index 0000000..ec554ca --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/docs-09-structure-template.md @@ -0,0 +1,25 @@ +# 09-项目目录结构 + +## 一、仓库顶层 +``` +{{repo_root_tree}} +``` + +## 二、后端目录 +``` +{{backend_tree}} +``` + +## 三、前端目录 +``` +{{frontend_tree}} +``` + +## 四、命名与放置约定 +- 根包: `【人工填写：Java 根包名 / C# 命名空间 / Python 顶层模块】` +- Controller: {{controller_rule}} +- Service: {{service_rule}} +- Mapper/Repository: {{mapper_rule}} +- DTO/VO: {{dto_rule}} +- 前端组件: {{component_rule}} +- 前端页面: {{page_rule}} diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/env-local-example-template b/_pl_staging/pl_skills/erp-skeleton-gen/templates/env-local-example-template new file mode 100644 index 0000000..ebe16fb --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/env-local-example-template @@ -0,0 +1,6 @@ +DB_HOST=【人工填写：MySQL host，例如 localhost】 +DB_PORT=【人工填写：MySQL port，默认 3306】 +DB_USER=【人工填写：开发账号名】 +DB_PASSWORD=【人工填写：对应密码】 +DB_SCHEMA=【人工填写：schema 名，例如 erp_dev】 +JWT_SECRET=【人工填写：JWT 签名密钥，256+ bit 随机串】 diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/githooks-pre-push-template.sh b/_pl_staging/pl_skills/erp-skeleton-gen/templates/githooks-pre-push-template.sh new file mode 100644 index 0000000..8289050 --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/githooks-pre-push-template.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +# .githooks/pre-push — run scripts/test.sh before every push. +# No --no-verify: the claude-code hook deny-no-verify.sh also blocks it. + +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +./scripts/test.sh diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh b/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh new file mode 100644 index 0000000..fd227af --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +# scripts/setup-test-db.sh — truncate + reseed only. NEVER runs DDL. +# Schema is human-owned; this script only clears data and reloads seed-data.sql. + +set -euo pipefail + +source "$(dirname "$0")/../.env.local" + +echo "[setup-test-db] truncate tables in ${DB_SCHEMA}" +mysql -h"${DB_HOST}" -P"${DB_PORT}" -u"${DB_USER}" -p"${DB_PASSWORD}" "${DB_SCHEMA}" <<'SQL' +SET FOREIGN_KEY_CHECKS = 0; +{{truncate_block}} +SET FOREIGN_KEY_CHECKS = 1; +SQL + +echo "[setup-test-db] reseed" +mysql -h"${DB_HOST}" -P"${DB_PORT}" -u"${DB_USER}" -p"${DB_PASSWORD}" "${DB_SCHEMA}" < sql/seed-data.sql + +echo "[setup-test-db] done" diff --git a/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-test-sh-template.sh b/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-test-sh-template.sh new file mode 100644 index 0000000..8986507 --- /dev/null +++ b/_pl_staging/pl_skills/erp-skeleton-gen/templates/scripts-test-sh-template.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash +# scripts/test.sh — the only hard gate before merging to main. +# Runs build + lint + unit + integration + E2E. +# Called by .githooks/pre-push and by the erp-local-test-gate skill (via subagent). + +set -euo pipefail + +PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$PROJECT_ROOT" + +echo "[test.sh] 1/5 setup test db" +./scripts/setup-test-db.sh + +echo "[test.sh] 2/5 build" +{{build_command}} + +echo "[test.sh] 3/5 lint" +{{lint_command}} + +echo "[test.sh] 4/5 unit + integration" +{{unit_integration_command}} + +echo "[test.sh] 5/5 E2E" +{{e2e_command}} + +echo "[test.sh] GREEN" diff --git a/_pl_staging/pl_skills/erp-tech-stack-lock/SKILL.md b/_pl_staging/pl_skills/erp-tech-stack-lock/SKILL.md new file mode 100644 index 0000000..f87a1da --- /dev/null +++ b/_pl_staging/pl_skills/erp-tech-stack-lock/SKILL.md @@ -0,0 +1,67 @@ +--- +name: erp-tech-stack-lock +description: Interactively collect project metadata (name / brief / target users / deployment) and confirm-or-edit the tech stack table, then write into CLAUDE.md header via claude-md-header-template. Invoke at project start or whenever CLAUDE.md header slots are still `【人工填写：...】`. +--- + +# erp-tech-stack-lock + +## Procedure + +### A. Collect 4 metadata slots + +Ask the user via `AskUserQuestion` (one question per slot; use multiSelect=false; provide reasonable options where possible): + +1. **项目名称** — open-ended (no options; use "Other") +2. **项目简述** — open-ended, one sentence +3. **目标用户** — open-ended (examples: 企业内部管理人员 / 面向 C 端客户 / ...) +4. **部署方式** — options: `私有化部署` / `云部署` / `Docker 容器化` / `混合` + +### B. Tech-stack table + +Default table (11 rows): + +| 层级 | 技术 | 版本要求 | +|---|---|---| +| 前端框架 | React | 18.x | +| 前端UI库 | Ant Design | 5.x | +| 前端状态管理 | Redux Toolkit | 最新稳定版 | +| 前端路由 | React Router | v6 | +| 前端构建 | Vite | 最新稳定版 | +| 前端HTTP | Axios | 最新稳定版 | +| 后端框架 | Spring Boot | 3.x | +| 后端ORM | MyBatis-Plus | 最新稳定版 | +| 数据库 | MySQL | 8.x | +| 认证方案 | JWT | — | +| API风格 | RESTful | — | + +**Ask one question per row, in order.** For each row, use `AskUserQuestion` with: +- **header**: the 层级 name (e.g. "前端框架") +- **question**: `<层级>：沿用 <默认技术 默认版本>，还是替换？` +- **options** (exactly 3): + 1. `沿用 <默认技术> <默认版本>` — keep default + 2. `替换为其它技术` — user picks "Other" and types the replacement (format: `技术名 版本`, e.g. `Vue 3.x`) + 3. `当前技术栈不需要` — drop this row entirely (e.g. 纯后端项目可移除前端各行) +- **multiSelect**: false + +One row = one `question` entry. Batch as many rows as possible into each `AskUserQuestion` call (the tool's own `maxItems` caps how many fit per call; don't add artificial limits beyond that). Do NOT collapse multiple rows into one question with rows-as-options. + +**After all 11 rows are collected**, ask a final question: +- **question**: `以上 11 项已确认。是否需要新增技术栈条目？（例如消息队列/缓存/搜索引擎）` +- **options** (exactly 2): + 1. `不新增` + 2. `新增条目` — if picked, follow up: ask the user to list additions in free text, format: `层级 | 技术 | 版本` per line +- **multiSelect**: false + +Collect the final stack_rows list (11 base rows, each either kept or replaced, plus any additions). + +### C. Render and write + +1. Read `templates/claude-md-header-template.md`. +2. Fill slots: `project_name`, `project_brief`, `target_users`, `deployment`, `stack_rows[]`. +3. Locate the target block in `CLAUDE.md` (§ 🎯 项目概述 + § 🏗️ 技术栈) and replace with the rendered content. Preserve all other CLAUDE.md sections verbatim. +4. Verify with `erp-placeholder-scan` over `CLAUDE.md` header — must have no `【人工填写：` residuals in the 4 collected slots. +5. Print `tech-stack-lock: DONE (<project_name>)`. + +## References + +- `templates/claude-md-header-template.md` diff --git a/_pl_staging/pl_skills/erp-tech-stack-lock/templates/claude-md-header-template.md b/_pl_staging/pl_skills/erp-tech-stack-lock/templates/claude-md-header-template.md new file mode 100644 index 0000000..9d6fc94 --- /dev/null +++ b/_pl_staging/pl_skills/erp-tech-stack-lock/templates/claude-md-header-template.md @@ -0,0 +1,16 @@ +## 🎯 项目概述 + +- **项目名称**: {{project_name}} +- **项目简述**: {{project_brief}} +- **目标用户**: {{target_users}} +- **部署方式**: {{deployment}} + +--- + +## 🏗️ 技术栈（不可更改） + +| 层级 | 技术 | 版本要求 | +|---|---|---| +{{#each stack_rows}} +| {{layer}} | {{tech}} | {{version}} | +{{/each}} diff --git a/_pl_staging/pl_skills/erp-understanding-report/SKILL.md b/_pl_staging/pl_skills/erp-understanding-report/SKILL.md new file mode 100644 index 0000000..9d89eed --- /dev/null +++ b/_pl_staging/pl_skills/erp-understanding-report/SKILL.md @@ -0,0 +1,36 @@ +--- +name: erp-understanding-report +description: Output the 6-section understanding confirmation report and stop to wait for the user's "理解正确" before any coding starts. +--- + +# erp-understanding-report + +## Pre-conditions + +All planning docs present: `docs/01-需求清单/**`, `docs/02` through `docs/10`, `sql/seed-data.sql`. + +## Procedure + +1. Read (one-time, comprehensive): + - CLAUDE.md + - docs/01-需求清单/README.md and all module files + - docs/02 through 10 + - docs/superpowers/schema-baseline.sql header (not body) +2. Read `templates/understanding-report-template.md`. +3. Fill slots: + - `project_goal` — derived from CLAUDE.md 项目概述 + - `modules[]` — from docs/08 in topological order + - `data_model` — key entity relations summarized from docs/03 (3–5 sentences) + - `tech_approach` — key architectural choices from docs/04 + - `questions` — any ambiguity / conflict / gap you spotted; explicit list, not "no questions" + - `next_module` — first `confirmed: false` in docs/08 +4. Print the rendered report **to the main session** (do NOT write a file — this is a conversation artifact). +5. Stop. Do not invoke any downstream skill. Wait for the user to reply "理解正确" or equivalent. + +## After user confirms + +- Hand off to `erp-session-start` (which will detect state and dispatch to `erp-module-start`). + +## References + +- `templates/understanding-report-template.md` diff --git a/_pl_staging/pl_skills/erp-understanding-report/templates/understanding-report-template.md b/_pl_staging/pl_skills/erp-understanding-report/templates/understanding-report-template.md new file mode 100644 index 0000000..ae2ad08 --- /dev/null +++ b/_pl_staging/pl_skills/erp-understanding-report/templates/understanding-report-template.md @@ -0,0 +1,25 @@ +## 📝 理解确认报告 + +### 1. 项目目标理解 +{{project_goal}} + +### 2. 模块拆解理解 +{{#each modules}} +- **{{module_id}} {{module_name}}** — {{core_functions}} +{{/each}} + +### 3. 数据模型理解 +{{data_model}} + +### 4. 技术方案理解 +{{tech_approach}} + +### 5. 存在的疑问 +{{questions}} + +### 6. 开发计划确认 +按 `docs/02-开发计划.md` 拓扑序开发，首个待推进模块: **{{next_module}}**。 + +--- + +⚠️ 等待人工回复"理解正确"后才开始编码。 diff --git a/_pl_staging/pl_指南.md b/_pl_staging/pl_指南.md new file mode 100644 index 0000000..3f0e3b7 --- /dev/null +++ b/_pl_staging/pl_指南.md @@ -0,0 +1,617 @@ +# ERP项目 — 文档总览与使用指南 + +> 本文件是整个文档体系的入口。先读这里，再按流程操作。 +> 核心思路：**人工只填"机器不可能知道的东西"，其余交给 Claude Code 生成后人工审阅。** +> +> **阅读顺序**：建议先通读一到四节（文档目录 / 分工 / 配套机制 / 关键原则），建立整体认知；然后按第五节"完整使用流程"逐步上手。 + +--- + +## 一、文档目录 + +``` +项目根目录/ +├── CLAUDE.md ← ★ Claude Code 的主指令文件（顶部需人工填项目概述） +├── 指南.md ← 本文件 +├── docs/ ← 所有项目文档 +│ ├── 01-需求清单/ ← 功能需求全集（按模块分文件，模块可自由增删） +│ │ ├── README.md ← 纲要 + 模块索引（人工写） +│ │ ├── SYS-系统管理.md ← REQ-SYS-* 用户/角色/权限/部门/字典 +│ │ └── <其他模块>.md ← 如 PUR-采购 / SAL-销售 / HR-人事 等，按业务增删，详见 README +│ ├── 02-开发计划.md ← 分模块开发路线图（CC 基于需求**按技术依赖重排**） +│ ├── 03-数据库设计文档.md ← 表结构业务含义（CC 通过 MySQL MCP 查询 live DB 生成） +│ ├── 04-技术规范.md ← 通用规范 + 技术栈衍生编码规范（骨架由 CC 按技术栈生成） +│ ├── 05-API接口契约.md ← 前后端接口契约（CC 基于需求+表结构生成） +│ ├── 06-UI交互规范.md ← 页面布局与交互规则（模板已完整） +│ ├── 07-环境配置.md ← 骨架由 CC 按技术栈生成；人工填账密/密钥/包名等占位 +│ ├── 08-模块任务管理.md ← ★ 人机协作控制中枢（CC 与 02 对齐） +│ ├── 09-项目目录结构.md ← 骨架由 CC 按技术栈生成（前后端目录名与层级） +│ └── 10-验收检查清单.md ← 每个模块的质量门（CC 基于需求生成） +├── scripts/ +│ ├── setup-test-db.sh ← truncate 当前 schema + reseed（CC 按技术栈生成；3.3） +│ └── test.sh ← 一键全量测试脚本（CC 按技术栈生成；3.3） +├── .githooks/ +│ └── pre-push ← Git hook：push 前自动跑 test.sh（3.3） +├── .env.local ← 每人独立的数据库连接（schema 名），不入 git +└── <代码目录> ← 由 Step 1 技术栈决定，CC 在 Step 10 开发时生成 + 具体目录名与层级参见 docs/09-项目目录结构.md +``` + +--- + +## 二、文档分工：谁来填？ + +| 类别 | 文档 | 负责人 | 说明 | +| ---------- | --------------------------------- | ----------- | ----------------------------------------------------------------------- | +| **A 必填** | `CLAUDE.md` 顶部项目概述（4 处） | 👤 人工 | 项目名、简述、目标用户、部署方式 | +| **A 必填** | `docs/01-需求清单/README.md` **纲要** | 👤 人工 | 模块列表 + 每模块核心功能点 + 关键业务数字 | +| **A 必填** | `docs/07-环境配置.md` 敏感/专属占位 | 👤 人工 | 数据库账密、JWT secret、包名、上传路径、小版本号等 | +| **A 必填** | MySQL schema + 表 DDL + MCP 连接 | 👤 人工 | 在现有 MySQL 中新建项目专用 schema 并建齐所有表；在仓库 `.mcp.json` 配置 MCP 指向该 schema | +| **B 生成+审** | `docs/01-需求清单/<模块>.md` 完整版 | 🤖 CC → 人工审 | 逐模块一个文件，基于纲要扩展成 REQ-XXX-NNN 标准卡片 | +| **B 生成+审** | `docs/02-开发计划.md` | 🤖 CC → 人工审 | 基于 01 需求按技术依赖拆分模块 0～N | +| **B 生成+审** | `docs/03-数据库设计文档.md` | 🤖 CC → 人工审 | 通过 MySQL MCP 查 live DB 自动填字段业务说明、ER 关系 | +| **B 生成+审** | `docs/04-技术规范.md` 骨架 | 🤖 CC → 人工审 | 按 `CLAUDE.md` 技术栈表推导后端 / 前端编码规范与认证实现（通用规范章节保留不变） | +| **B 生成+审** | `docs/05-API接口契约.md` | 🤖 CC → 人工审 | 基于 01+03 生成 RESTful 契约 | +| **B 生成+审** | `docs/07-环境配置.md` 骨架 & 依赖 | 🤖 CC → 人工审 | 按 `CLAUDE.md` 技术栈表推导主配置文件 / 依赖清单 / 端口规划 | +| **B 生成+审** | `docs/08-模块任务管理.md` | 🤖 CC → 人工审 | 与 02 对齐生成任务表格 | +| **B 生成+审** | `docs/09-项目目录结构.md` | 🤖 CC → 人工审 | 按 `CLAUDE.md` 技术栈表推导前后端目录名与层级 | +| **B 生成+审** | `docs/10-验收检查清单.md` | 🤖 CC → 人工审 | 基于 01+08 生成验收项 | +| **B 生成+审** | `sql/seed-data.sql` | 🤖 CC → 人工审 | 基于 MCP 查到的 schema 扩充业务测试数据 | +| **C 模板齐全** | `docs/06-UI交互规范.md` | — | 通用规范，无需填写 | + +**判断标准**：只有你知道 / 涉及密钥 / 体现业务意图 → A 类必填；能从需求或 schema 推导 → B 类交给 CC。 + +### 占位符统一约定 + +所有"需要人工填"的位置，全部用下面这种**可见、可搜索** 的标记： + +``` +【人工填写：<简短说明>】 +``` + +示例： + +```markdown +- **项目名称**: 【人工填写：公司+项目名，例如：无锡五彩印务 ERP】 +- **数据库密码**: 【人工填写：生产库密码，走环境变量不要入库】 +- **销售（SAL）**: 【人工填写：客户管理、报价单、销售订单、出库 等核心功能点】 +``` + +**规则：** + +- **填写时把整个 `【人工填写：...】` 连带中文方括号一起替换为实际值**，不要保留方括号 + （示例：`【人工填写：数据库密码】` → `Abc@123`，不是 `【Abc@123】`） +- Step 6 启动时 CC 扫描 `【人工填写：` 作为残留占位的首选特征字符串；兜底还扫通用的裸占位值：`your_password` / `your-secret-key`（技术栈特有的占位值不纳入，统一靠 `【人工填写：`） + +--- + +## 三、配套机制（跨步骤生效，非顺序步骤） + +五节的 9 步是"从零到开发"的顺序动作；本节三条**不是步骤**，而是始终在后台生效的规则 / 闸门 / 工具。 + +### 3.1 confirmed 完成确认标记（模块完成清单） + +`confirmed` 是**模块完成清单**：标记哪些模块已通过人工审核、可视为已交付，从而让 CC 知道该在哪个模块上继续工作。定义在 `docs/08-模块任务管理.md`。 + +```yaml +module_1: + confirmed: false # false = 待完成（CC 在此模块上开发） + # true = 已完成（MR 已合入，CC 进入下一模块） +``` + +| 操作 | 触发方 | 触发条件 | +| -- | -- | -- | +| 默认 `confirmed: false` | — | 新模块生成时 | +| `false` → `true` | **CC** | MR 已 Approved + Merged（人工告知 或 `glab mr view` 验证 merged 状态） | +| `true` → `false`（重新开启） | **人工 或 CC** | 发现已确认模块有 bug / 需打回重做 | + +**授权边界：** + +- CC 可以改 `false` → `true`，**但前置条件是 MR 已合入**（人工 review 是唯一审核点；CC 只是把"MR 合入"这个事实同步到清单里） +- CC **不得**在 MR 未 merged 时改 `true`（等于跳过人工审核） +- CC **可以**把 `true` 改回 `false`（发现已确认模块有 bug 时，把该模块重新开启） + +### 3.2 红旗中断机制（CC 行为规则） + +功能循环默认静默执行，只有命中"红旗"才打断等人决策。**具体的 10 条红旗清单 + CC 命中后的固定动作都定义在 `CLAUDE.md` 的「🚩 静默执行红旗清单」一节**——CC 启动时已自动加载，开发者无需在此重复学习。 + +本节在指南中保留只是为了让阅读流程的开发者知道这个机制存在；**运行态的权威来源是 CLAUDE.md**。 + +### 3.3 本地测试闸门（本项目唯一的硬闸门） + +> **设计**：本项目**不使用 GitLab CI/CD**，所有测试集中在本地完整跑（单元 + 集成 + E2E + lint + 构建）；闸门由一键脚本 + `pre-push` Git hook + CC 自动创建 MR + 人工审核合入**协同**实现。 + +#### 数据库架构 + +- **单 MySQL 实例 + 单 schema**（复用现有 MySQL 服务器，不用 Docker） +- schema 命名由人工定（例如 `erp_dev`），由人工在 Step 4 建好所有表 +- **CC 的 MCP 连接**指向该 schema，作为 live 真实源供文档生成与字段核对 +- 本项目**单开发者场景**，`test.sh` 跑时 truncate + reseed 同一 schema，不存在并发问题 + +#### 仓库里放三个产物（CC 在 Step 2 按技术栈生成） + +``` +<项目根>/ +├── scripts/ +│ ├── setup-test-db.sh ← truncate 当前 schema 所有表 + 导入 seed-data.sql +│ └── test.sh ← 一键全量测试：单元 + 集成 + E2E + lint + 构建 +└── .githooks/ + └── pre-push ← Git hook：push 前自动跑 test.sh，失败则拒绝 push +``` + +> **不使用 Docker**、不使用 `docker-compose.test.yml`；复用现有 MySQL。 + +**各文件职责：** + +- **`scripts/setup-test-db.sh`**：读 `.env.local` 取 DB 连接 → 连 MySQL → 对当前 schema 内所有表 `TRUNCATE`（禁用 FK 检查）→ `mysql < sql/seed-data.sql`。**不建表不删表**（DDL 归人工） +- **`scripts/test.sh`**：按技术栈串起来——先调 `setup-test-db.sh` 重置数据 → 后端单元 / 集成测试、前端单元测试、E2E（Playwright / Cypress）、lint、构建验证。退出码非 0 即失败 +- **`.githooks/pre-push`**：bash 脚本，`git push` 前自动触发 `scripts/test.sh`；非 0 退出码会让 `git push` 被拒绝 + +#### 一次性 Dev Setup（每个开发者克隆后跑一次） + +```bash +# 1. 启用仓库自带 hooks（不在 .git/hooks 里，在 .githooks/ 方便入版本控制） +git config core.hooksPath .githooks + +# 2. 复制 .env.local.example → .env.local，填入 MySQL 连接 +cp .env.local.example .env.local +# 编辑：DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA（项目专用 schema 名） + +# 3. 试跑一遍（会对当前 schema 做 truncate + reseed） +./scripts/setup-test-db.sh +./scripts/test.sh + +# 4. 配置 glab CLI（CC 自动创建 MR 用） +glab auth login # 按提示填自建 GitLab 实例 URL + PAT +``` + +> **前提**：MySQL 中已建好项目专用 schema 并用 DDL 建齐所有表（见 Step 4）。 +> +> **CC 需要**：`glab` CLI + GitLab PAT（scope: `api` / `write_repository`）；token 存 `~/.config/glab-cli/config.yml`，不入版本控制。MySQL MCP 连接在 `.mcp.json` 配置（指向项目 schema）。 + +**约定写在 `docs/07-环境配置.md` 的七节"启动 / 构建命令"**，由 CC 在 Step 2 生成时同步登记。 + +#### MR 创建与合并流程（合并前置仅 2 项） + +1. **本地 `scripts/test.sh` 全绿** —— `.githooks/pre-push` 自动触发，失败则 push 被拒；**禁止** `--no-verify` 绕过 +2. **CC 自动 `git push` + `glab mr create`** —— 将《模块完成报告》审阅包贴入 MR 描述（含通过用例数、耗时、`test.sh` 输出结尾作为跑过测试的书面证据）；CC 输出 MR 链接后**停下**等人工 +3. **模块末人工审核（唯一人工介入点）** —— 你 review 通过后： + - 点 MR "Approve" + Merge + - 对 CC 说"MR 已 approve + merge"（或 "继续"） +4. **CC 自行同步 confirmed 并进入下一模块**： + - CC 用 `glab mr view <mr-iid>` 验证 MR 确实已 merged + - 验证通过后，在 `docs/08-模块任务管理.md` 把当前模块 `confirmed` 改为 `true` + - 进入下一个 `false` 模块开始工作 + +> 人工只做"审 + Approve + Merge + 告知 CC"四件事；`confirmed` 字段的实际写入由 CC 完成，但**必须以 MR merged 为前提**——CC 若在未 merged 状态下写 `true`，等于跳过人工审核，属于严重违规。 + +#### GitLab 仓库设置（Ops 一次性配置） + +- Project → Settings → Repository → Protected Branches + - `main`：Allowed to push = **No one**（强制走 MR） + - Allowed to merge = Developers + Maintainers +- Project → Settings → Merge Requests + - ☑ All threads must be resolved + - Approvals → 至少 1 人 + +> 本项目**不启用** "Pipelines must succeed"，也不配置 CI/CD Runner；本地 `scripts/test.sh` + `pre-push` hook 是唯一硬闸门。 + +--- + +## 四、关键原则 + +1. **schema 是只读权威（MySQL MCP live 查询）** — 项目专用 schema 是唯一权威来源，CC 通过 MCP 只读查询；需求围绕既有表结构展开；CC 禁止 `CREATE TABLE / ALTER TABLE / DROP TABLE`（DDL 归人工，在 MySQL 中直接执行） +2. **需求与 schema 冲突必须停下来** — 若某需求在表里找不到落脚点，CC 须报告由你决策：改需求 or 人工改库 +3. **人工只填机器不可能知道的东西** — 意图、密钥、密码等 +4. **文档越精确，AI 输出越准确** — A 类纲要写得越详细，B 类生成越准 +5. **先确认理解，再动手编码** — CC 必须先输出《理解确认报告》 +6. **每份文档生成后立即审阅** — 不要积压到最后一起审 +7. **按模块推进，每个模块可控** — 不跳模块，不并行，逐个确认完成 +8. **静默执行，命中红旗才停** — 功能循环默认不打扰人；CC 仅在 `CLAUDE.md` 🚩 红旗清单 10 条之一成立时才打断主会话等人决策 +9. **技术栈分工：版本号单一来源** — `CLAUDE.md` 的技术栈表只做大版本锁定（`18.x` / `3.x`），作为"禁止更换技术"的约束；所有小版本号、依赖清单、具体配置模板（application.yml / pom.xml / vite.config.ts / package.json）只写在 `docs/07-环境配置.md`。两处不要重复小版本，避免漂移。 +10. **Spec 是 source of truth** — 所有代码必须能回溯到某份 spec（01 需求卡 / superpowers spec）；代码跑偏 spec 时，以 spec 为准，先改 spec 再改码。 +11. **验收必须可执行** — `docs/10-验收检查清单.md` 不是人工 checklist，而是**可自动运行的测试用例清单**（JUnit + Playwright / Vitest）。`confirmed: true` 的前提是所有用例本地 `./scripts/test.sh` 全绿。 +12. **AI 产物必须逐行 review，但人工只在模块末做一次** — 每个功能强制跑 `superpowers:code-reviewer` 子代理审查并修复；人工 review 在模块末统一进行，依据《模块完成报告》的审阅包。 +13. **本地测试脚本是唯一硬闸门** — `scripts/test.sh` 跑完整测试（单元 + 集成 + E2E + lint + 构建）；`pre-push` hook 失败即拒 push；测试绿后 CC 自动 `git push + glab mr create`；**本项目不配置 CI/CD**；禁止 `--no-verify` 绕过。 +14. **业务顺序 ≠ 执行顺序** — `01-需求清单/` 按业务模块分组，顺序无所谓；`02-开发计划.md` 才是执行顺序，由 CC 按技术依赖（基础设施 → 认证 → 系统管理 → 基础资料 → 业务主流程）重排。人工不要试图在 01 里排开发顺序。 +15. **计划阶段 vs 开发阶段** — Step 1–9 是**计划阶段**，**不写业务代码**，通过人机反复对话把所有不确定性消解在文档里（需求卡、表结构、API 契约、任务清单、验收用例等都越厚越好）。Step 10 是**开发阶段**，CC 在充分的文档基础上**尽可能自主推进**（功能循环默认静默），人工只在模块末 review MR。**文档越厚，开发越能自主；开发越自主，文档越要在计划阶段打磨**——宁可在前者多花时间，也不让后者被追问打断。 + +--- + +## 五、完整使用流程 + +本流程分为两个阶段，**严格单向推进，不回头**： + +| 阶段 | 步骤 | 核心原则 | 交互密度 | +|------|------|--------|--------| +| 🗂️ **计划阶段** | Step 1–9 | **不写业务代码**，通过人机反复对话沉淀尽量丰富的文档 | 高（每步都有人工审核 / 输入） | +| 🏗️ **开发阶段** | Step 10 | **文档驱动自主开发**，功能循环默认静默，人工只在模块末 review MR | 低（每个模块唯一一次人工介入点） | + +> **设计意图**：把所有模糊、歧义、决策压力都挪到计划阶段解决；进入开发阶段后 CC 能一气呵成地推进功能循环，不被反复打断。**文档质量 = 开发自主度的上限。** + +> **总原则**：通用开发项目都应遵循"**锁定技术栈 → 生成环境配置 → 填占位 → 提供业务输入 → 生成需求文档 → 分模块开发**"的单向依赖链。 +> ⚠️ 本项目额外约束：数据库是**现有的**，schema 是既定事实不可变，所以业务需求必须后于 schema。 +> +> **动手前**先读完一到四节，建立整体认知；本节是具体操作步骤。 + +--- + +## 🗂️ 计划阶段（Step 1–9）：文档厚过天 + +> 本阶段**不写任何业务代码**（Step 2 生成的 scripts / 配置骨架属于开发工装，不是产品代码）。 +> 每一步产出都要**立刻人工审阅**，宁可在这里多对话几轮。 +> 计划阶段走完后，`docs/` 应该能回答 CC 在开发中可能遇到的 95% 以上问题。 + +### Step 1 — 确定技术栈（人工） + +1. **填 `CLAUDE.md` 顶部 4 处**：项目名 / 简述 / 目标用户 / 部署方式。 +2. **确认或调整 `CLAUDE.md` 的「🏗️ 技术栈」表**。默认是 `Spring Boot 3.x + MyBatis-Plus + React 18 + Vite + Ant Design + JWT + MySQL 8`，保留或替换为你的技术选型。**此表只写大版本**，小版本号留到 Step 3（配置运行环境）填。 + +> 这一步决定了 Step 2 能生成什么；变动技术栈必须回到这一步重走。 + +### Step 2 — 生成技术骨架（CC） + +基于 `CLAUDE.md` 技术栈表，由 CC 一次性生成 **04 / 07 / 09** 的**骨架部分**（凡是技术栈变动就需要重生成的内容）。 + +**对 CC 说（复制粘贴即可）：** + +``` +请读 CLAUDE.md（不需要读 指南.md），基于 CLAUDE.md 的「🏗️ 技术栈」表，一次性生成下列骨架。 +前三份是 docs/ 下的纯模板文件；第四项是**本地测试闸门**的四件套（仓库根与 scripts/ / .githooks/ 下）。 +你的任务是把每一节 / 每个文件填成技术栈对应的实际内容。 + +1. docs/07-环境配置.md —— 保留文件头与节标题不变，按技术栈填入各节内容： + - 一、基础环境：列出运行时 / 包管理器 / 构建工具的大版本要求 + - 二、后端运行配置：给出主配置文件（如 application.yml / appsettings.json / settings.py / …）的完整结构 + - 三、前端构建配置：给出构建与路径配置（如 vite.config.* / next.config.* / tsconfig.json 等） + - 四、后端依赖清单：按包管理器格式（pom.xml / build.gradle / requirements.txt / *.csproj / go.mod / package.json …）列核心依赖 + - 五、前端依赖清单：按包管理器格式列依赖 + - 六、端口规划：填表 + - 七、启动 / 构建命令：填表 + +2. docs/09-项目目录结构.md —— 保留文件头与节标题不变，按技术栈填入： + - 一、顶层结构（固定项 CLAUDE.md / 指南.md / docs / sql + 技术栈相关代码目录） + - 二、后端目录结构（分层结构树） + - 三、前端目录结构 + - 四、命名约定（表格） + +3. docs/04-技术规范.md —— 保留文件头与节标题不变，**三节（通用规范）不要改**；只填： + - 一、后端编码规范（1.1 命名约定表 / 1.2 包 / 模块结构树 / 1.3 分层职责 / 1.4 代码模板） + - 二、前端编码规范（2.1 命名约定表 / 2.2 目录结构 / 2.3 组件编写规范 / 2.4 API 调用规范） + - 四节只填 4.6 认证实现（其余 4.1–4.5 是跨栈策略，不要改） + +4. 本地测试闸门三件套 + 一个环境文件（项目**不配置 CI/CD**；闸门完全在本地；**不使用 Docker**；单开发者复用现有 MySQL 中的单 schema）： + - `scripts/setup-test-db.sh` —— 读 `.env.local` 取 DB 连接 → 连 MySQL → 对当前 schema 内所有表 TRUNCATE（SET FOREIGN_KEY_CHECKS=0）→ `mysql < sql/seed-data.sql`；**不做 DDL**（建表归人工） + - `scripts/test.sh` —— 先调 `setup-test-db.sh` 重置数据 → 后端单元+集成测试 + 前端单元测试 + **E2E**（Playwright / Cypress，按栈选）+ lint + 前后端构建；任一失败即退出非 0 + - `.githooks/pre-push` —— `#!/usr/bin/env bash` + `set -e` + 调用 `./scripts/test.sh` + - 根目录 `.env.local.example` —— 占位模板，列 `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_SCHEMA`，值用 `【人工填写：...】`；真实 `.env.local` 入 `.gitignore` + - `docs/07-环境配置.md` 需额外登记：MySQL 连接信息（host / port / 账密 / schema 名占位）+ MCP 配置说明；`glab` CLI 工具要求 + GitLab PAT 占位；E2E 测试依赖（Playwright browser install 等） + - **不生成** `docker-compose.test.yml`（本项目不用 Docker） + +【强制规则】 +- 所有敏感值 / 项目专属值 / 小版本号一律用 【人工填写：<简短说明>】 标记，不要填实际值 +- 凡是"只有人工能决定"的地方（密钥、账密、命名约定等）一律用这个标记，不要自行编值 +- 占位标记必须用纯文本 `【人工填写：…】`，**不要用 HTML 注释**（`<!-- ... -->`），因为后者在 Obsidian 渲染视图会被隐藏，开发者会漏填 +- 每个【人工填写：...】 必须带**简短说明**，让填写的人立刻知道这里要写什么（例如"【人工填写：JWT 签名密钥，256+ bit 随机串】"，不是"【人工填写】"） +- 项目专属标识（Java 根包名 / C# 命名空间 / Python 顶层模块等）**不要在本次引入新的 【人工填写】**， + 统一引用 docs/07-环境配置.md 中已登记的占位（如在 07 里叫 `type-aliases-package`，本次生成 04 时也用该值引用） +- 每插入一处 新的 【人工填写：...】 标记，同步把它的位置登记到所在文件的「零、人工占位速查表」 + （04 没有零节，如果确需引入新占位，同步在 04 顶部新建一个与 07 同结构的零节；能复用 07 占位就不要新建） +- 三份文件的文件头说明、节标题不要改，只填充表格行 / 章节内容 + +四份可以连续生成，不用中间停下来确认。全部完成后统一输出： + - 四份文件的绝对路径 + - 四份各自引入的 【人工填写：...】 标记总数 + - 07 / 09 占位速查表的最终行数（04 和测试闸门四件套若无新增占位则报"无"） + - 生成过程中遇到的任何疑点 + +然后停下等我一次性人工审核，之后进入 Step 3（配置运行环境）。不要触碰其他文件。 +``` + +**CC 会生成的内容参考：** + +- **2a. `docs/07-环境配置.md` 骨架** —— 七节：基础环境 / 后端运行配置 / 前端构建配置 / 后端依赖 / 前端依赖 / 端口规划 / 启动命令 +- **2b. `docs/09-项目目录结构.md` 骨架** —— 四节：顶层结构 / 后端目录 / 前端目录 / 命名约定 +- **2c. `docs/04-技术规范.md` 骨架** —— 技术栈相关部分（一、后端规范 / 二、前端规范 / 4.6 认证实现），三节通用规范和 4.1–4.5 策略不动 +- **2d. 本地测试闸门三件套 + `.env.local.example`** —— `scripts/setup-test-db.sh` + `scripts/test.sh` + `.githooks/pre-push` + `.env.local.example`；**不生成** `docker-compose.test.yml`（本项目不用 Docker）；详见 3.3 + +**CC 不填任何敏感值**，一律用 `【人工填写：...】` 标记（详见第二节「占位符统一约定」）。 + +### Step 3 — 配置运行环境（人工） + +分别打开 `docs/07-环境配置.md` 和 `docs/09-项目目录结构.md` 顶部的「零、人工占位速查表」，按速查表逐行定位到正文里的 `【人工填写：...】` 标记，连同方括号一起替换为实际值。 + +> 速查表的每一行由 Step 2 生成时自动登记，内容随所选技术栈而异（Java 栈里会有 Java 包名、JWT secret；.NET 栈里则可能是命名空间、appsettings.json 密钥等）。**以你这份项目的速查表为准**，不要参考其他项目的清单。 +> +> 是否填完由 Step 6 启动时 CC 自动搜索 `【人工填写：` 来核对。 +> 小版本号**只写在此处**；`CLAUDE.md` 技术栈表只锁大版本。两处重复必然漂移。 + +### Step 4 — 建 schema 建表 + 配置 MCP（人工） + +本项目**不使用 `sql/schema.sql` 文件**；MySQL live DB 本身就是 schema 的唯一权威来源，CC 通过 MySQL MCP 查询获取。 + +**操作步骤：** + +1. **在现有 MySQL 中建项目专用 schema**（如 `erp_dev`，名字由你定；大版本需与 `CLAUDE.md` 技术栈表一致） +2. **在该 schema 内建齐所有表**： + - 若是全新项目：人工手写 DDL 一次性建好 + - 若有参考库：`mysqldump --no-data <source> | mysql <erp_dev>` +3. **配置 CC 的 MCP 连接**：在仓库根 `.mcp.json` 里填 `mcp_server_mysql` 的 host / port / user / password / database（指向项目 schema），账密用 `【人工填写：...】` 占位 + 实际值走环境变量 +4. **配置 `.env.local`**：`cp .env.local.example .env.local` 填入 DB 连接与 schema 名 +5. **验证**：跑 `./scripts/setup-test-db.sh` 能正常 truncate + reseed；CC 启动时能通过 MCP `SHOW TABLES` 查到所有表 + +> ⚠️ **CC 禁止 `CREATE / ALTER / DROP TABLE`**（见 CLAUDE.md 红旗 #1 + #6）。schema 改动永远由人工在 MySQL 中直接执行。 +> +> ⚠️ DDL 文件请版本化管理（可另存库外，如团队知识库），但**不要放 `sql/schema.sql`**——那会被误当作 CC 的输入源。 + +### Step 5 — 确定需求纲要（人工） + +在 `docs/01-需求清单/README.md` 中填写"模块 + 核心功能点"的 bullet 纲要。 + +> ⚠️ 写之前先通过 MySQL MCP `SHOW TABLES` 看一遍库里有哪些表，确保每条需求在表里有落脚点。 +> ⚠️ 模块顺序**不代表开发顺序**——开发顺序由 CC 生成 `02` 时按技术依赖重排。 + +示例： +- 系统管理（SYS）：用户登录、用户 CRUD、角色权限、部门管理 +- 销售（SAL）：客户管理、报价单、销售订单、出库 +- 采购（PUR）：供应商管理、采购申请、采购订单、入库 +- ……（按业务实际增删模块） + +### Step 6 — 生成需求与数据库文档（CC） + +本步只生成 **需求卡（01）+ 数据库设计文档（03）**。完成后**停下等人工审核**（可能需要修改），审核通过后再进入 Step 7 生成依赖它们的下游文档。 + +**对 CC 说（复制粘贴即可）：** + +``` +请先读 CLAUDE.md（不需要读 指南.md）。 + +【第 0 步：占位核对】在生成任何 B 类文档前，先扫描 docs/07-环境配置.md、 +docs/09-项目目录结构.md 以及其他所有 A 类文档，匹配以下任一特征字符串视为未填： + - "【人工填写：" （统一标记，详见 CLAUDE.md「🏷️ 占位符统一约定」） + - "your_password" / "your-secret-key" （兜底：通用配置裸占位值） + - 版本号仍为大版本占位（匹配形如 "N.x" 或 "N.N.x" 的正则，未锁定到具体小版本） + +如发现残留占位：停下来输出残留位置清单，等我补完 07 再重新触发本 prompt，不要进入下一步。 +如全部已替换：继续下面的生成流程。 + +【生成流程：一次性生成两份文档，不用逐份停下等我确认，默认静默执行】 + +1. 基于 docs/01-需求清单/README.md 的纲要，按模块逐个生成 + docs/01-需求清单/<模块缩写>-<模块名>.md（SYS / SAL / PUR / INV / …）， + 每个模块一个文件 + +2. 通过 MySQL MCP 查 live DB（`SHOW TABLES` / `SHOW CREATE TABLE` / `INFORMATION_SCHEMA.COLUMNS`）填 docs/03-数据库设计文档.md 表结构业务说明 + +全部生成完毕后【统一输出一份汇总】： + - 每份文件的绝对路径 + - 每份的关键体量指标（01 每模块多少个功能 / 03 多少张表多少字段） + - 生成过程中遇到的任何疑点（与 schema 对不上、纲要不够等） + +然后停下来等我做【一次性人工审核】。中途不要提问、不要等"下一份"； +仅当出现以下阻塞时才中断并报告： + - 需求纲要里提到的字段在 schema 中找不到 + - 需求本身出现无法自行消解的歧义 + - MySQL MCP 连接不可达（host 不通 / 账密错 / schema 为空表 0 张） + +**严禁**生成 02 / 05 / 08 / 10 / seed-data.sql——那是 Step 7 的范围，必须在 01 / 03 审核通过后才能动。 +``` + +**人工审核要点**： +- 01 需求卡是否覆盖纲要每一条 bullet？字段引用在 schema 里能否找到？ +- 03 表结构业务含义是否准确？ER 关系是否漏写？ +- 发现问题直接改文档，或让 CC 针对性重生成某模块 / 某表。审核通过后进入 Step 7。 + +--- + +### Step 7 — 生成下游文档（CC） + +**前置**：Step 6 的 01 + 03 已通过人工审核。本步基于它们生成所有依赖文档。 + +**对 CC 说（复制粘贴即可）：** + +``` +Step 6 的 01 + 03 已通过人工审核。请基于它们【一次性】生成下游文档，默认静默执行： + +1. 基于 01 + 03 生成 docs/02-开发计划.md + —— 必须按技术依赖重排（先基础设施 / 认证 / 系统管理，再业务模块按依赖顺序）， + 不要沿用 01 的业务分组顺序 + +2. 基于 01 + 03 生成 docs/05-API接口契约.md + +3. 与 02 对齐生成 docs/08-模块任务管理.md + +4. 基于 01 + 08 生成 docs/10-验收检查清单.md + +5. 基于 MCP 查到的 schema 扩充 sql/seed-data.sql + +全部生成完毕后【统一输出一份汇总】： + - 每份文件的绝对路径 + - 每份的关键体量指标（02 多少模块 / 05 多少个 Endpoint / 08 多少 Task / + 10 多少验收用例 / seed 多少行） + - 生成过程中遇到的任何疑点 + +然后停下来等我做【一次性人工审核】。中途不要提问。 +仅当出现以下阻塞时才中断并报告： + - 01 / 03 中的需求/表在生成 02/05/08/10 时出现无法消解的歧义 + - MySQL MCP 连接不可达 +``` + +### Step 8 — 确认 CC 理解（CC） + +全部文档就绪后，CC 需输出 6 节式确认报告。你回复"理解正确"后才能进入 Step 9。 + +**对 CC 说（复制粘贴即可）：** + +``` +所有文档已生成完毕。请按依赖顺序完整读一遍（**不要读 指南.md**）： + CLAUDE.md → + docs/01-需求清单/README.md → docs/01-需求清单/<各模块>.md → + docs/02 → docs/03 → docs/04 → docs/05 → docs/06 → + docs/07 → docs/08 → docs/09 → docs/10 + +然后输出《理解确认报告》，严格 6 节： + +### 1. 项目目标理解（≤ 3 句话复述项目目标） +### 2. 模块拆解理解（列出所有业务模块及其核心功能） +### 3. 数据模型理解（核心实体之间的关系） +### 4. 模块规划理解（模块 1 / 2 / …，每个模块做什么、依赖什么） +### 5. 技术栈与约束理解（CLAUDE.md 技术栈表 + 认证 + 只读 schema 等约束） +### 6. 风险与歧义清单（读文档过程中发现的矛盾、歧义、待确认项） + +报告输完停下，等我回复"理解正确"再做任何后续动作。 +``` + +### Step 9 — 固化文档为 CC 参考（CC 一次性清理） + +Step 8 通过后，`docs/` 进入**"事实只读"状态**：人工不再手动改 docs，所有 docs 作为 CC 写代码时的纯参考。此步由 CC 一次性扫描并删除面向人工的流程 / 指引性内容，让文档只剩业务 / 技术事实。 + +**对 CC 说（复制粘贴即可）：** + +``` +《理解确认报告》已通过我批准。现在进行一次性"文档固化"清理：把 docs/ 下所有文档 +转为"纯 CC 参考"状态。 + +【不要动的文件】 + - docs/08-模块任务管理.md（人机协作控制中枢，CC 在每个模块末 MR 合入后改 confirmed） + - 根目录 指南.md（流程文档，本身就面向人） + - 根目录 CLAUDE.md（保留顶部「项目概述」4 条即可，其他已是规范型内容可留） + +【其他所有 docs/*.md、docs/01-需求清单/*.md 执行删除规则】 + +删除以下内容： + 1. 文件头部"本文档由 Claude Code 在 Step X 自动生成…" / "初始状态：空模板…" 等 + 生命周期说明（CC 读过指南知道来源，无需每份文档重复） + 2. 所有明确面向人工的操作指引 blockquote，例如： + - "新增模块只需两步…" + - "改名规则" + - "填写方式" / "核对由 Step 6 CC 自动执行" + - "⚠️ 写之前先…" / "⚠️ 顺序不代表开发顺序…" + 3. 章节标题里的"（人工填写）" / "（CC 自动填）" / "（CC 参考）" 等人机角色标记， + 只保留章节主标题 + 4. 「零、人工占位速查表」整节（此时占位已全部填完，索引表已失去用途） + 5. 各节开头 "由 CC 在 Step X 基于 XX 生成" 一类节内生命周期引导 blockquote + （章节内容已填妥，引导文字已完成使命） + 6. "示例见 SYS-系统管理.md" / "示例见下" 等面向人的阅读引导 + +【保留】 + - 所有实际业务 / 技术事实：功能卡片（REQ-XXX）、表结构、字段说明、ER 关系、API 契约、 + 模块规划、任务表、代码规范、依赖清单、目录结构、验收用例、seed 数据、配置值 + - 章节主标题（去掉括号里的角色标记） + - 文档头 H1 标题 + +【执行方式】 + - 先给我一份「清理前 vs 清理后」的预览 diff（每份文件列出将删除的段落摘要 + 行数变化） + - 我确认"执行"后你再真正下手 + - 执行后再次输出每份文件的前后行数对比 + 分类删除统计 + +执行完之后，docs/ 进入 Step 10（分模块开发）的只读参考态。 +``` + +--- + +## 🏗️ 开发阶段（Step 10）：文档即 spec，CC 自主推进 + +> 进入本阶段时，`docs/` 已固化为只读参考态（Step 9 已清理），所有业务 / 技术事实都在文档里。 +> 功能循环（Brainstorm → Plan → TDD → Verify → AI 自审）**默认静默**，CC 遇到不确定性只在命中 🚩 红旗清单时才打断人工。 +> 人工在本阶段的**唯一介入点**是模块末 review MR（一个模块一次）。 +> 如果此阶段 CC 频繁打断问问题，说明计划阶段文档打磨得不够，应回头补文档（必要时 Step 6/7 重生成 + 人工审核）而不是让开发"边开发边定义"。 + +### Step 10 — 分模块开发（模块循环 + 功能循环） + +> **术语提示** +> - **模块** = 一组紧密相关、能整体交付的功能集合，对应 `docs/02-开发计划.md` 里的一个模块。**模块循环**就是开发一个模块。 +> - **功能** = 一条具体的功能需求，编号格式 `REQ-<模块缩写>-<三位序号>`（如 `REQ-SYS-001` 用户登录）。**功能循环**就是开发一个功能。 +> - **confirmed** = 模块完成确认标记，详见 3.1。 + +**启动新模块时对 CC 说（复制粘贴即可）：** + +``` +请按 CLAUDE.md「🔄 模块循环 + 功能循环」开发下一个模块。 + +1. 打开 docs/08-模块任务管理.md，找到第一个 confirmed: false 的模块 +2. 对该模块内每个功能（REQ-XXX）依次跑功能循环 5 步： + Brainstorm → Plan → TDD → Verify → AI 自审 + 所有产物归档到 docs/superpowers/{specs,plans,reviews}/YYYY-MM-DD-<REQ-id>.md +3. 命中 CLAUDE.md「🚩 静默执行红旗清单」任一条 → 立即停下、写 🚩 Blocker 节、一句话告警 +4. 该模块全部功能完成后产出《模块完成报告》审阅包： + - 每个功能的 spec + plan + diff + - 每个功能的 AI reviewer 报告 + - 测试总数 / 通过率 / 覆盖率 / `scripts/test.sh` 最后一次输出结尾 + - schema 改动清单（应为 0） + - 偏离 spec 清单 +5. `scripts/test.sh` 本地全绿后，自动 `git push` + `glab mr create`，把审阅包贴入 MR 描述，输出 MR 链接后**停下**等人工审核。 + **此时严禁改 `confirmed`**——必须等人工 Approve + Merge 后才能改（见步骤 6）。 + +默认静默执行。除红旗场景外，不要向我提问或确认。 +``` + +**模块末人工 review 通过后对 CC 说（复制粘贴即可）：** + +``` +MR 已 Approve + Merge。请： +1. 用 glab mr view <mr-iid> 验证 MR 状态为 merged +2. 验证通过后，把 docs/08-模块任务管理.md 里当前模块的 confirmed 改为 true（commit 消息格式：chore(module): confirm module_N as completed） +3. 基于指南开始下一个模块（重复上面的启动 prompt） + +若 glab mr view 显示未 merged（opened / closed），立即停下告警，不要改 confirmed。 +``` + +--- + +**流程详解：** + +每个模块走一次**模块循环**，模块内每个**功能**（REQ-XXX）走一次**功能循环**。 + +**模块循环：** + +``` +找 docs/08 中第一个 confirmed: false 的模块 + ↓ +对模块内每个功能（REQ-XXX）依次跑功能循环（CC 静默执行，不打扰人） + ↓ +CC 输出《模块完成报告》，打包附件（见下方"审阅包"） + ↓ +自动化闸门：本地 `./scripts/test.sh` 全绿（见 3.3） + ↓ +CC 自动 `git push` + `glab mr create`（审阅包贴入 MR 描述） + ↓ +**人工审核 MR**（一个模块唯一一次人工介入点） + ↓ +全部通过 → 你点 Approve + Merge + ↓ +你对 CC 说"MR 已合入" → CC 验证 merged 状态 → CC 把 `confirmed` 改为 true → 进入下一个模块 +``` + +**《模块完成报告》审阅包必须包含：** + +- 本模块所有功能的 spec、plan、diff（`git diff <module-start>..HEAD`） +- 每个功能的 AI reviewer 报告（`docs/superpowers/reviews/`） +- 测试结果：总用例数、通过率、覆盖率、`scripts/test.sh` 最后一次运行输出结尾（证据） +- schema 改动清单（应为 0，若非 0 必须额外解释） +- 偏离 spec 清单（实现中与 spec 不一致的地方，一处都不能漏报） + +**功能循环（单个功能 REQ-XXX 级）— 静默执行，无人工打断：** + +``` +1. Brainstorm （可调用 superpowers:brainstorming） + 产出：≤ 1 页 spec，写入 docs/superpowers/specs/YYYY-MM-DD-<REQ-id>.md + 内容：目标 / 接口 / 数据流 / 边界条件 / 测试标准 + +2. Plan （可调用 superpowers:writing-plans） + 产出：Task 级步骤，每步 2–5 分钟，含文件路径与完整代码 + 写入 docs/superpowers/plans/YYYY-MM-DD-<REQ-id>.md + +3. TDD 执行 （可调用 superpowers:test-driven-development） + 写失败测试 → 跑 → 实现最小代码 → 测试通过 → 提交 + 频繁小提交，每个 task 一个 commit + +4. Verify （可调用 superpowers:verification-before-completion） + 声称"完成"前，必须贴出 mvn test / pnpm test 的实际输出 + +5. AI 自审 （superpowers:code-reviewer 子代理，强制） + 产出：审查报告写入 docs/superpowers/reviews/YYYY-MM-DD-<REQ-id>.md + CC 自行修复 reviewer 发现的问题，直到 reviewer 通过 +``` + +> **人工 review 不在此发生**，移到模块末统一进行（模块循环倒数第 2 步）。 diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..d3d7db1 --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,20 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/scripts/deny-no-verify.sh" } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit|Write", + "hooks": [ + { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/hooks/scripts/log-cross-module.sh" } + ] + } + ] + } +} diff --git a/hooks/scripts/deny-no-verify.sh b/hooks/scripts/deny-no-verify.sh new file mode 100755 index 0000000..786736d --- /dev/null +++ b/hooks/scripts/deny-no-verify.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +# PreToolUse hook: block any `git push --no-verify` — the local test.sh gate is the only hard gate. + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +[ "$tool_name" = "Bash" ] || exit 0 + +cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')" +[ -n "$cmd" ] || exit 0 + +if printf '%s' "$cmd" | grep -qE '\bgit[[:space:]]+push\b.*--no-verify\b'; then + echo "BLOCKED: --no-verify bypasses the local test.sh gate (唯一硬闸门). If test.sh is failing, fix the root cause; do not skip the gate. Use /erp-local-test-gate to run the gate properly." >&2 + exit 2 +fi + +exit 0 diff --git a/hooks/scripts/log-cross-module.sh b/hooks/scripts/log-cross-module.sh new file mode 100755 index 0000000..1fe0aa7 --- /dev/null +++ b/hooks/scripts/log-cross-module.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash +# PostToolUse hook: 检测 Edit/Write 是否触及"当前模块以外"的模块路径，若是则在当前模块的跨模块日志中留痕（软规则 S2）。 +# 注：原设计基于"已勾 [x] 模块"触发，但 docs/08 § 二 的 checkbox 永远保持 `- [ ]`（完成由 MR merged state 判定）； +# 新判定按"非当前模块"触发——CC 在当前模块开发期间改动其他模块（无论是否已 merged）都应留痕。 + +set -euo pipefail + +input="$(cat)" +tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')" +case "$tool_name" in Edit|Write) ;; *) exit 0 ;; esac + +file_path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')" +[ -n "$file_path" ] || exit 0 + +project_dir="${CLAUDE_PROJECT_DIR:-$(pwd)}" +docs08="$project_dir/docs/08-模块任务管理.md" +[ -f "$docs08" ] || exit 0 + +# 跳过 docs/08 自身的改动（元数据文件编辑不是代码跨模块改动，不触发 S2） +case "$file_path" in *"/docs/08-模块任务管理.md") exit 0 ;; esac + +# 当前模块 = 当前 git 分支名去掉 `module-` 前缀。 +# erp-module-start 步骤 3 保证模块循环期间处于 module-<id> 分支； +# 非 module-* 分支（如 main、feature/*、docs/*）不在模块循环内，不触发 S2 留痕。 +current_branch="$(cd "$project_dir" 2>/dev/null && git branch --show-current 2>/dev/null || echo '')" +case "$current_branch" in + module-*) current_module="${current_branch#module-}" ;; + *) exit 0 ;; +esac +[ -n "$current_module" ] || exit 0 + +# 遍历所有 `- module_X` 行（docs/08 § 二 的所有模块，纯 bullet 无 checkbox）， +# 提取 module_id 和其下的"路径:"行。 +# docs/08 § 二 的模块块结构： +# - module_0 <name> +# - 依赖: ... +# - 路径: backend/module/xxx/, frontend/pages/xxx/ +# - MR: !N 或 — +hit_module="" +# 用 awk 逐模块解析：每碰到 `- module_` 记录 module_id（$2），然后在其下找第一个 `- 路径:` 行 +# current_module 已在上文计算，在外层循环被排除 → 只会命中"非当前模块"的路径 +while IFS=$'\t' read -r mod paths; do + [ "$mod" = "$current_module" ] && continue + IFS=',' read -ra scope_arr <<< "$paths" + for s in "${scope_arr[@]}"; do + s="$(echo "$s" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//; s:/$::')" + [ -z "$s" ] && continue + case "$file_path" in *"$s"*) hit_module="$mod"; break 2;; esac + done +done < <(awk ' + /^- module_/ { + # `- module_xxx <name>` awk 默认分词：$1=-、$2=module_xxx、$3=<name> + mod=$2 + next + } + mod && /^[[:space:]]*- 路径:/ { + sub(/^[[:space:]]*- 路径:[[:space:]]*/,"") + print mod "\t" $0 + mod="" + } + /^- module_/ && mod { mod="" } +' "$docs08") + +[ -n "$hit_module" ] || exit 0 + +log_dir="$project_dir/docs/superpowers/module-reports" +mkdir -p "$log_dir" +log_file="$log_dir/${current_module}-cross-module.md" +if [ ! -f "$log_file" ]; then + { + echo "# 跨模块改动日志 — ${current_module}" + echo "" + echo "| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 |" + echo "|---|---|---|---|---|---|" + } > "$log_file" +fi + +ts="$(date -u +%FT%TZ)" +rel_path="${file_path#$project_dir/}" +echo "| ${ts} | ${hit_module} | ${rel_path} | ${tool_name} | TBD(CC 补) | TBD(CC 补) |" >> "$log_file" + +jq -n --arg m "$hit_module" --arg f "$log_file" --arg p "$rel_path" \ + '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:("跨模块改动检测：\($p) 属于模块 [\($m)]（非当前模块）。存根已写入 \($f)，含 TBD(CC 补) 占位。请由 CC 调用 erp-cross-module-log skill 自主推断并补填原因与影响评估（软规则 S2，CC 自主维护，非人工填写）。")}}' diff --git a/skills/coding/erp-feature-brainstorm/SKILL.md b/skills/coding/erp-feature-brainstorm/SKILL.md new file mode 100644 index 0000000..8298d5e --- /dev/null +++ b/skills/coding/erp-feature-brainstorm/SKILL.md @@ -0,0 +1,39 @@ +--- +name: erp-feature-brainstorm +description: 功能循环第 1 步。针对单个 REQ-XXX-NNN 进行交互式头脑风暴，产出功能规格文件到 docs/superpowers/specs/。 +user-invocable: false +allowed-tools: Read Write Skill Bash(mysql *) +--- + +**所有输出必须使用中文。** + +# erp-feature-brainstorm + +## 说明 + +针对一个 REQ-XXX-NNN，委托 `superpowers:brainstorming` 进行头脑风暴，然后将输出打包到标准规格模板中，产出 ≤1 页的功能规格。 + +## 执行步骤 + +1. **红旗检查**：调用 `erp-red-flag-check`。如果命中 → 停止。 +2. 确定输入： + - 当前 REQ-XXX-NNN（从对话中获取，或 `docs/08` 当前模块下一个未完成的 REQ）。 + - REQ 卡片：`docs/01-需求清单/<module>.md` 中对应的 REQ-XXX-NNN 节。 + - 相关数据表（从 `docs/03` 或实时 mysql 命令行查询）。 +3. 委托 `superpowers:brainstorming`，以 REQ 卡片 + schema 引用作为上下文。 +4. 推导路径：`docs/superpowers/specs/$(date +%F)-<REQ-id>.md`。如已存在，征求用户确认后覆盖。 +5. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md`，从头脑风暴输出填充槽位： + - `goal`、`input`、`output`、`rules`、`constraints`、`schema_refs`、`api_refs`、`acceptance` +6. 将填充后的规格写入推导路径。 +7. **验证**：模板中每个顶级节必须非空。如有槽位为 TBD，回到头脑风暴补充该槽位。 +8. 输出 `feature-brainstorm: <REQ> → <path>`。 + +## 衔接 + +立即调用 `Skill(erp-feature-plan)` 进入下一步。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/feature-spec-template.md` +- 委托：`superpowers:brainstorming` +- 守门：`erp-red-flag-check` diff --git a/skills/coding/erp-feature-brainstorm/templates/feature-spec-template.md b/skills/coding/erp-feature-brainstorm/templates/feature-spec-template.md new file mode 100644 index 0000000..09715ab --- /dev/null +++ b/skills/coding/erp-feature-brainstorm/templates/feature-spec-template.md @@ -0,0 +1,31 @@ +--- +req_id: {{req_id}} +date: {{date}} +module: {{module}} +--- + +# Spec: {{req_id}} — {{title}} + +## 目标 +{{goal}} + +## 输入 / 触发 +{{input}} + +## 输出 / 结果 +{{output}} + +## 业务规则 +{{rules}} + +## 边界与约束 +{{constraints}} + +## 依赖的 schema 表 / 字段 +{{schema_refs}} + +## 依赖的接口 +{{api_refs}} + +## 验收标准 +{{acceptance}} diff --git a/skills/coding/erp-feature-plan/SKILL.md b/skills/coding/erp-feature-plan/SKILL.md new file mode 100644 index 0000000..4afd9a3 --- /dev/null +++ b/skills/coding/erp-feature-plan/SKILL.md @@ -0,0 +1,34 @@ +--- +name: erp-feature-plan +description: 功能循环第 2 步。将规格转化为任务级计划（每任务 2-5 分钟，含文件路径和完整代码），输出到 docs/superpowers/plans/。 +user-invocable: false +allowed-tools: Read Write Grep Skill +--- + +**所有输出必须使用中文。** + +# erp-feature-plan + +## 执行步骤 + +1. **红旗检查**：调用 `erp-red-flag-check`。 +2. 确定输入： + - 当前 REQ-XXX-NNN 及其规格文件 `docs/superpowers/specs/YYYY-MM-DD-<REQ>.md`（规格不存在则报错）。 + - 相关代码指针（已有的待修改文件，通过 Grep 发现）。 + - `docs/04-技术规范.md` 和 `docs/09-项目目录结构.md`（编码规范 + 目录规范）。 +3. 委托 `superpowers:writing-plans`，以规格 + 代码指针 + 规范作为上下文。 +4. 推导路径：`docs/superpowers/plans/$(date +%F)-<REQ-id>.md`。 +5. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md`，填充 `files[]`、`tasks[]`、`commits[]`。 +6. 强制要求：每个任务有失败测试标识、实现路径和完成标准。 +7. 写入计划文件。 +8. 输出 `feature-plan: <REQ> → <path>`。 + +## 衔接 + +立即调用 `Skill(erp-feature-tdd)` 进入下一步。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/feature-plan-template.md` +- 委托：`superpowers:writing-plans` +- 守门：`erp-red-flag-check` diff --git a/skills/coding/erp-feature-plan/templates/feature-plan-template.md b/skills/coding/erp-feature-plan/templates/feature-plan-template.md new file mode 100644 index 0000000..00d36f6 --- /dev/null +++ b/skills/coding/erp-feature-plan/templates/feature-plan-template.md @@ -0,0 +1,28 @@ +--- +req_id: {{req_id}} +date: {{date}} +spec_ref: docs/superpowers/specs/{{date}}-{{req_id}}.md +--- + +# Plan: {{req_id}} + +## Schema 改动 +{{schema_change_decision}} <!-- "无" 或 "需要 migration：V<n>__<snake_case>.sql，作用：<一行描述>" --> + +## 文件变更清单 +{{#each files}} +- `{{path}}` — {{action}}（{{rationale}}） +{{/each}} + +## 任务步骤 +{{#each tasks}} +### Task {{index}}: {{title}} +- 失败测试: `{{test_file}}::{{test_name}}` — {{test_intent}} +- 实现路径: `{{impl_file}}` +- 完成判据: {{done_when}} +{{/each}} + +## 提交计划 +{{#each commits}} +- `{{message}}`（覆盖 Task {{task_index}}） +{{/each}} diff --git a/skills/coding/erp-feature-review/SKILL.md b/skills/coding/erp-feature-review/SKILL.md new file mode 100644 index 0000000..9be880e --- /dev/null +++ b/skills/coding/erp-feature-review/SKILL.md @@ -0,0 +1,41 @@ +--- +name: erp-feature-review +description: 功能循环第 5 步。AI 自审，输出审阅报告到 docs/superpowers/reviews/。approve 回调 erp-module-start；request-changes 则编辑代码并 fix commit，重跑 verify。自修复循环上限 5 轮。 +user-invocable: false +allowed-tools: Read Write Edit Skill Agent Bash(git add *) Bash(git commit *) +--- + +**所有输出必须使用中文。** + +# erp-feature-review + +## 执行步骤 + +1. 委托 `superpowers:code-reviewer`，以该 REQ 的 diff（`git diff <feature-start>..HEAD`）和规格作为输入。 +2. 推导路径：`docs/superpowers/reviews/$(date +%F)-<REQ-id>.md`。 +3. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md`，填充 `round`、`verdict`、`must_fix[]`、`nice_to_have[]`、`gaps`。verdict 必须是 `approve` 或 `request-changes`。 +4. 写入报告。 + +5. 分发： + - **`verdict = approve`** → 输出 `feature-review: <REQ> round <N> 通过`，然后调用 `Skill(erp-module-start)` 回模块主循环（module-start 会自动把本 REQ 识别为 done 并推进下一个 REQ）。 + - **`verdict = request-changes`** → 执行"自修复子流程"： + - 逐项处理 `must_fix[]`：对每个条目用 `Edit` 修改其指向的代码文件。 + - 所有 Must-fix 修复后，拼 commit 消息（格式与 `erp-feature-tdd` 一致，单行）：`fix(<module_id>): 修复 review round <N> must-fix <REQ-id>`。 + - `Bash`: `git add <修改的代码文件>` + `git commit -m "<上一步拼出的消息>"`。 + - 调用 `Skill(erp-feature-verify)` 重跑验证；verify 通过后会再次链到本 skill，作为 round `<N+1>` 重审。 + +6. 上限：**5 轮**。第 5 轮仍为 `request-changes` → 停止并打印摘要（升级给用户手工介入），不再自动修复，不回调 module-start。 + +## 衔接 + +- `approve` → `Skill(erp-module-start)` 回主循环。 +- `request-changes`（round < 5）→ `Skill(erp-feature-verify)` 重跑。 +- `request-changes`（round == 5）→ 停止。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/feature-review-template.md` +- Fix commit 格式与 `erp-feature-tdd` 的 `commit-message-template.md` 对齐（`fix(<scope>): <subject> <req_id>`） +- 委托：`superpowers:code-reviewer` +- 上游：`erp-feature-verify` +- 下游：`erp-module-start`（approve）或 `erp-feature-verify`（request-changes） diff --git a/skills/coding/erp-feature-review/templates/feature-review-template.md b/skills/coding/erp-feature-review/templates/feature-review-template.md new file mode 100644 index 0000000..a9b6216 --- /dev/null +++ b/skills/coding/erp-feature-review/templates/feature-review-template.md @@ -0,0 +1,24 @@ +--- +req_id: {{req_id}} +date: {{date}} +round: {{round}} +reviewer: superpowers:code-reviewer +--- + +# Review: {{req_id}} — round {{round}} + +## 结论 +{{verdict}} （approve / request-changes） + +## Must-fix +{{#each must_fix}} +- [{{severity}}] {{file}}:{{line}} — {{issue}}（建议：{{suggestion}}） +{{/each}} + +## Nice-to-have +{{#each nice_to_have}} +- {{file}}:{{line}} — {{suggestion}} +{{/each}} + +## 反例 / 测试覆盖缺口 +{{gaps}} diff --git a/skills/coding/erp-feature-tdd/SKILL.md b/skills/coding/erp-feature-tdd/SKILL.md new file mode 100644 index 0000000..ffca2a9 --- /dev/null +++ b/skills/coding/erp-feature-tdd/SKILL.md @@ -0,0 +1,45 @@ +--- +name: erp-feature-tdd +description: 功能循环第 3 步。逐任务执行计划：写失败测试 → 实现代码 → 测试通过 → 提交。所有测试运行均派发到子会话执行。 +user-invocable: false +allowed-tools: Read Write Edit Agent Skill Bash(git add *) Bash(git commit *) +--- + +**所有输出必须使用中文。** + +# erp-feature-tdd + +## 执行步骤 + +1. **红旗检查**：调用 `erp-red-flag-check`。 +2. 加载计划文件 `docs/superpowers/plans/YYYY-MM-DD-<REQ>.md`。 +3. **Schema 改动优先（如果计划声明了需要）**：若 plan 标注 "本 REQ 需要 schema 改动"，**第一个任务必须是写 migration 文件**： + - `ls sql/migrations/V*.sql` 得最大版本号 n_max，新文件版本号 = n_max + 1 + - 文件名格式 `V<n>__<snake_case_desc>.sql`，例 `V5__add_user_email.sql` + - `Write` 该文件（只含 DDL：`ALTER TABLE ... ADD COLUMN ...` / `CREATE TABLE ...` 等），commit + - 之后的代码任务（entity / DAO / service / 测试）在此之后做；测试跑时 Spring Boot 启动会让 Flyway 自动 apply 这个新 migration（`scripts/setup-test-db.sh` 只负责清空库） +4. 按顺序处理每个（代码类）任务： + a. 在 `test_file::test_name` 处编写失败测试。 + b. **派发子会话**（通过 `Agent`，general-purpose）运行测试并确认失败；子会话只返回 `{command, exit_code, failing_assertion}`。主会话**不直接**运行测试。 + c. 在 `impl_file` 处实现最小代码使测试通过。 + d. **再次派发子会话**运行测试并确认通过。 + e. 持续失败（同一测试 >10 次修复尝试）→ 调用 `erp-red-flag-check`（红旗 #4）。 + f. 暂存变更并使用 `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` 提交；`scope` 匹配任务的模块，`subject` ≤50 字符，`req_id` 必填。 +5. 所有任务完成后 → 交接给 `erp-feature-verify`。 + +## 护栏 + +- **绝不**在主会话直接运行 `mvn test` / `pnpm test` / `scripts/test.sh`，必须通过子会话。 +- 每次提交必须包含 REQ-XXX-NNN 标签。 +- 不要将不相关的变更合并到一次提交中。 +- **禁止**在主会话直接 `mysql -e "ALTER ..."` 跑业务 DDL；所有业务 schema 变更必须走 `sql/migrations/V_n__<desc>.sql` 文件（只读查询 / 临时调试探索除外）。 + +## 衔接 + +立即调用 `Skill(erp-feature-verify)` 进入下一步。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/commit-message-template.md` +- 委托：`superpowers:test-driven-development` +- 守门：`erp-red-flag-check` diff --git a/skills/coding/erp-feature-tdd/templates/commit-message-template.md b/skills/coding/erp-feature-tdd/templates/commit-message-template.md new file mode 100644 index 0000000..ecf5222 --- /dev/null +++ b/skills/coding/erp-feature-tdd/templates/commit-message-template.md @@ -0,0 +1 @@ +{{type}}({{scope}}): {{subject}} {{req_id}} diff --git a/skills/coding/erp-feature-verify/SKILL.md b/skills/coding/erp-feature-verify/SKILL.md new file mode 100644 index 0000000..c77442e --- /dev/null +++ b/skills/coding/erp-feature-verify/SKILL.md @@ -0,0 +1,40 @@ +--- +name: erp-feature-verify +description: 功能循环第 4 步。将功能的测试套件派发到子会话执行，用模板渲染验证证据。无证据不得声称完成。 +user-invocable: false +allowed-tools: Skill Read Write Agent +--- + +**所有输出必须使用中文。** + +# erp-feature-verify + +## 执行步骤 + +1. 从计划文件或项目标准命令中确定功能的测试目标（Maven profile / pnpm script / pytest path）。 +2. **派发子会话**（通过 `Agent`，general-purpose），prompt 类似： + + ``` + 任务：运行功能测试目标并报告结果。不要修改任何代码。步骤： + 1. 执行：<command>（例如 mvn -pl user-module test -Dtest=REQ*） + 2. 仅返回结构化 JSON：{"command":"<cmd>","exit_code":<int>,"passed":<int>,"failed":<int>,"failed_list":["<test>", ...],"stdout_excerpt":"<最后 30 行或最相关的失败摘录>"} + 不要输出任何描述性文字。 + ``` + +3. 解析 JSON；用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/feature-verify-evidence-template.md`，填充槽位（包括 `subagent_id` 和 `conclusion`）。 +4. 如果 `exit_code != 0` 或 `failed > 0` → 打印填充后的证据到会话并**停止**，不进入审阅。 +5. 通过 → 打印证据，交接给 `erp-feature-review`。 + +## 护栏 + +- 不要将原始测试 stdout 粘贴到主会话（超过 30 行的 `stdout_excerpt`）。 +- 证据必须从模板渲染，不能自由编写。 + +## 衔接 + +立即调用 `Skill(erp-feature-review)` 进入下一步。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/feature-verify-evidence-template.md` +- 委托：`superpowers:verification-before-completion` diff --git a/skills/coding/erp-feature-verify/templates/feature-verify-evidence-template.md b/skills/coding/erp-feature-verify/templates/feature-verify-evidence-template.md new file mode 100644 index 0000000..efaa70b --- /dev/null +++ b/skills/coding/erp-feature-verify/templates/feature-verify-evidence-template.md @@ -0,0 +1,16 @@ +## Verify evidence — {{req_id}} + +- 命令: `{{command}}` +- 子会话: {{subagent_id}} +- 退出码: {{exit_code}} +- 通过用例数: {{passed}} +- 失败用例数: {{failed}} +- 失败列表: {{failed_list}} + +关键 stdout 片段 (≤30 行): + +``` +{{stdout_excerpt}} +``` + +结论: {{conclusion}} （pass / fail） diff --git a/skills/coding/erp-local-test-gate/SKILL.md b/skills/coding/erp-local-test-gate/SKILL.md new file mode 100644 index 0000000..b0f7a10 --- /dev/null +++ b/skills/coding/erp-local-test-gate/SKILL.md @@ -0,0 +1,79 @@ +--- +name: erp-local-test-gate +description: MR 创建前的唯一硬闸门。子会话跑 scripts/test.sh（setup-test-db.sh 清库后，Spring Boot 启动让 Flyway apply 当前 sql/migrations/V*.sql），任一失败则停止。 +user-invocable: false +allowed-tools: Read Write Skill Agent Bash(git add *) Bash(git commit *) +--- + +**所有输出必须使用中文。** + +# erp-local-test-gate + +## 执行步骤 + +1. **派发子会话**（`Agent`，general-purpose）运行 `./scripts/test.sh`： + + ``` + 任务：运行项目本地测试闸门。不要修改任何代码或数据。步骤： + 1. cd 到仓库根目录。 + 2. 执行：./scripts/test.sh + 3. 仅返回 JSON：{"command":"./scripts/test.sh","exit_code":<int>,"passed":<int>,"failed":<int>,"stdout_excerpt":"<最后 30 行，包含 FAIL 摘要>"} + 不要输出任何描述性文字。 + ``` + +2. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/test-gate-result-template.md`，用结果填充槽位。 + +3. 写入 `docs/superpowers/module-reports/<module_id>-test-gate.md`。 + +3b. **commit evidence 到 module 分支**（确保 test-gate.md 随 MR 合并进 main，审计可追溯）： + + ```bash + git add docs/superpowers/module-reports/<module_id>-test-gate.md + git commit -m "chore(<module_id>): add local test-gate evidence" + ``` + +4. 如果 `exit_code = 0` → 交接给 `erp-module-report`（输出 `local-test-gate: 通过`）。 + +5. 否则打印以下横幅并**停下**（不自动重试、不自动修复——失败分类需人工判断）： + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-local-test-gate] ⚠️ 未通过 + + 失败清单: <失败测试清单（来自子会话 JSON）> + stdout 摘录: <最后 30 行 / FAIL 摘要> + 详细证据: docs/superpowers/module-reports/<module_id>-test-gate.md + + 请根据失败类型选择下一步： + + ① 测试脆弱（flakey，偶发） + → 再跑 /erp-workflow:erp-coding-start + （module-start 幂等：reviews 已全 approve 会跳过功能循环，直接重跑本闸门） + + ② 真有回归（某个 REQ 破坏了其他 REQ/已合并模块） + → 定位到具体 REQ，删除其 review 记录： + rm docs/superpowers/reviews/*-<REQ-id>.md + → 再跑 /erp-workflow:erp-coding-start + （module-start 把该 REQ 视为未完成，重走 brainstorm→...→review 循环修复） + + ③ 环境/依赖问题（DB 连不上、外部 API 失败、证书失效） + → 命中红旗 #6（外部接口不可达） + → 调用 Skill(erp-red-flag-check) 追加 Blocker 到本模块任一 plan 文件 + → 修好环境后再跑 /erp-workflow:erp-coding-start + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + + 然后**停止**，不调用下游 skill（module-report / mr-create）。 + +## 护栏 + +- **绝不**在主会话直接执行 `./scripts/test.sh`。 +- **绝不**通过 `git push --no-verify` 绕过（hook `deny-no-verify.sh` 会拦截）。 + +## 衔接 + +立即调用 `Skill(erp-module-report)` 生成模块报告。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/test-gate-result-template.md` diff --git a/skills/coding/erp-local-test-gate/templates/test-gate-result-template.md b/skills/coding/erp-local-test-gate/templates/test-gate-result-template.md new file mode 100644 index 0000000..1382801 --- /dev/null +++ b/skills/coding/erp-local-test-gate/templates/test-gate-result-template.md @@ -0,0 +1,16 @@ +## Local test gate — {{module_id}} + +执行时间: {{timestamp}} + +### scripts/test.sh (subagent) +- 子会话: {{subagent_id}} +- 命令: {{command}} +- 退出码: {{exit_code}} +- 通过: {{passed}} / 失败: {{failed}} +- 关键 stdout (≤30 行): + +``` +{{stdout_excerpt}} +``` + +结论: {{conclusion}} （green / red） diff --git a/skills/coding/erp-module-report/SKILL.md b/skills/coding/erp-module-report/SKILL.md new file mode 100644 index 0000000..4295c58 --- /dev/null +++ b/skills/coding/erp-module-report/SKILL.md @@ -0,0 +1,54 @@ +--- +name: erp-module-report +description: 本地测试闸门通过后，生成标准化 12 节模块完成报告，嵌入本模块新增的 migration 清单和跨模块改动日志。 +user-invocable: false +allowed-tools: Read Write Glob Grep Skill Bash(git diff *) Bash(git log *) Bash(git add *) Bash(git commit *) +--- + +**所有输出必须使用中文。** + +# erp-module-report + +## 执行步骤 + +0. **红旗检查**：调用 `Skill(erp-red-flag-check)` → 命中则停止（与 `erp-red-flag-check` SKILL 描述"生成模块级制品前"对齐）。 + +1. 验证上游：`erp-local-test-gate` 返回了绿色。否则停止。 +2. 收集输入（优先 shell 摘要，避免把 diff 正文读进上下文）： + - **文件变更 § ③** — 只用摘要，**不**读 diff 正文： + - `git diff --stat <module-start-commit>..HEAD` → 每文件增减行数 + - `git diff --name-status <module-start-commit>..HEAD` → A/M/D 状态 + - `git log --oneline <module-start-commit>..HEAD` → commit 列表 + - `docs/superpowers/specs|plans|reviews/<date>-<本模块的 REQ>.md` → § ②、§ ⑨（正常 Read，一般不大） + - **§ ⑥ 本模块新增 migration**：用 `git diff --name-only --diff-filter=A <module-start-commit>..HEAD -- 'sql/migrations/V*.sql'` 列出本模块提交的新 migration 文件；每个文件 Read 第一行（V_n 描述）作为说明 + - `docs/superpowers/module-reports/<module_id>-cross-module.md` → § ⑦ + - `docs/superpowers/module-reports/<module_id>-test-gate.md` → § ⑤ + - § ④（读写的表）：**用 `grep -rlE "(SELECT|INSERT|UPDATE|DELETE).*FROM|INTO"` 定位涉及 SQL 的文件，再按需 Read 片段**。不要全量读 docs/03。 +3. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/module-report-template.md`，填充全部 12 节。 +4. **硬性验证**： + - § ⑦：如果 cross-module 有任何行含 `TBD(CC 补)` → **停止**，调用 `Skill(erp-cross-module-log)` 让 CC **自主推断**补齐，补完再回本步骤重验。 + - § ⑦：如果非空但某行缺少影响评估（被填成空/敷衍）→ 同样调 `erp-cross-module-log` 重补。 + - § ⑧ 必须列举所有偏离规格之处；如果没有，明确写"无偏离"。 +5. 写入 `docs/superpowers/module-reports/$(date +%F)-<module_id>.md`。 + +5b. **commit 模块报告 + cross-module 日志到 module 分支**（确保审计证据随 MR 合并进 main；erp-mr-create 的 worktree clean 前置条件依赖此步）： + + ```bash + git add docs/superpowers/module-reports/$(date +%F)-<module_id>.md + # cross-module log 若存在且有改动（erp-cross-module-log 补齐过 TBD）也一并提交 + [ -f "docs/superpowers/module-reports/<module_id>-cross-module.md" ] && \ + git add docs/superpowers/module-reports/<module_id>-cross-module.md + git commit -m "docs(<module_id>): add module completion report + cross-module log" + ``` + +6. 交接给 `erp-mr-create`。 + +## 衔接 + +立即调用 `Skill(erp-mr-create)` 推送并创建 MR。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/module-report-template.md`（12 节） +- 上游：`erp-local-test-gate` +- 下游：`erp-mr-create` diff --git a/skills/coding/erp-module-report/templates/module-report-template.md b/skills/coding/erp-module-report/templates/module-report-template.md new file mode 100644 index 0000000..30c8281 --- /dev/null +++ b/skills/coding/erp-module-report/templates/module-report-template.md @@ -0,0 +1,67 @@ +--- +module_id: {{module_id}} +date: {{date}} +git_range: {{git_range}} +--- + +# 模块完成报告 — {{module_id}} {{module_name}} + +## ① 模块信息 +- 模块 ID: {{module_id}} +- 模块名: {{module_name}} +- 开发区间: {{git_range}} + +## ② REQ 完成清单 +{{#each reqs}} +- [{{status}}] {{req_id}} — {{title}} + - spec: docs/superpowers/specs/{{date}}-{{req_id}}.md + - plan: docs/superpowers/plans/{{date}}-{{req_id}}.md + - review: docs/superpowers/reviews/{{date}}-{{req_id}}.md +{{/each}} + +## ③ 文件变更表 +| 文件 | 操作 | 说明 | +|---|---|---| +{{#each file_changes}} +| {{path}} | {{action}} | {{note}} | +{{/each}} + +## ④ 数据库使用表 +- 读: {{tables_read}} +- 写: {{tables_written}} + +## ⑤ 测试结果 +- `scripts/test.sh` 最终：{{test_conclusion}} +- 通过: {{passed}} / 失败: {{failed}} / 跳过: {{skipped}} +- 覆盖率: {{coverage}} + +## ⑥ 本模块新增 Migration + +{{#each migrations}} +- `sql/migrations/{{filename}}` — {{desc}} +{{/each}} + +（若本模块无 schema 改动，写 "—"） + +## ⑦ 跨模块改动清单（软规则 S2） + +{{cross_module_contents}} + +## ⑧ 偏离 spec 清单 +{{#each deviations}} +- {{req_id}}: {{deviation}} （原因: {{reason}}） +{{/each}} + +## ⑨ AI reviewer 报告汇总 +{{#each reviews}} +- {{req_id}}: round {{round}} — {{verdict}}（link: docs/superpowers/reviews/{{date}}-{{req_id}}.md） +{{/each}} + +## ⑩ 已知问题 +{{known_issues}} + +## ⑪ 下一模块预览 +{{next_module}} + +## ⑫ MR 链接 +{{mr_url}} diff --git a/skills/coding/erp-module-start/SKILL.md b/skills/coding/erp-module-start/SKILL.md new file mode 100644 index 0000000..595f2e4 --- /dev/null +++ b/skills/coding/erp-module-start/SKILL.md @@ -0,0 +1,73 @@ +--- +name: erp-module-start +description: 启动/恢复模块循环。按 docs/02 § 二 REQ 清单定位当前模块及其 REQ 序列，确保处于模块分支，扫 docs/superpowers/reviews/ 计算已完成 REQ，驱动第一个未完成 REQ 的功能循环；全部完成则调 erp-local-test-gate。幂等可重入。 +user-invocable: false +allowed-tools: Read Write Skill Glob Grep Bash(git branch *) Bash(git checkout *) Bash(git rev-parse *) Bash(glab mr *) +--- + +**所有输出必须使用中文。** + +# erp-module-start + +## 执行步骤 + +### 步骤 1：按 `docs/02 § 二` REQ 序 + MR state 定位当前模块 + 本模块 REQ 列表 + +与 `erp-coding-start` 步骤 3 同构（完成判定权威是 `MR:` 字段 + `glab mr view state`，不看 checkbox）： + +- 用 `Read` 读取 `docs/02-开发计划.md`，用 `Grep`（pattern `^\|\s*[0-9]+\s*\|\s*\*\*(REQ-[A-Z0-9]+-[0-9]+)\*\*\s*\|\s*(module_\w+)`）抽取 § 二 表格数据行，按行号升序得 `req_order[]`。 +- 若 `req_order` 为空 → 打印"⚠️ docs/02 § 二 REQ 开发顺序清单为空或无法解析，请检查"并停止。 +- 初始化 `module_merged[module_id → bool]` 空缓存。按序遍历 `req_order[]`： + - `module_merged[module_id]` 已缓存为 `true` → 跳过本 REQ。 + - `module_merged[module_id]` 已缓存为 `false` → `current_module = module_id`，结束遍历。 + - 未缓存 → 读 docs/08 § 二 该模块条目的 ` - MR:` 字段： + - `MR: —` → `module_merged[module_id] = false`，`current_module = module_id`，结束遍历。 + - `MR: !<iid>` → `Bash`: `glab mr view <iid> -F json 2>/dev/null`，取 `.state`： + - `merged` → 缓存 `true`，跳过本 REQ。 + - 其他 → 缓存 `false`，`current_module = module_id`，结束遍历。 +- **抽取本模块 REQ 序列 `req_list[]`**：从 `req_order[]` 取出所有 `module_id == current_module` 的项，按原序组成（同模块 REQ 必须连续，见 A5 约束）。 +- 用 `Read` 读取 docs/08 § 二 该模块行 + 后续缩进行，提取 `module_name` / `depends_on`（REQ 列表以 docs/02 为权威，不再读 docs/08）。 + +### 步骤 2：所有模块已完成短路 + +如果 `req_order[]` 全部遍历完 `current_module` 仍未赋值（即所有模块都 merged）→ 打印"所有模块已完成"摘要并停止。 + +### 步骤 3：确保处于模块分支 + +- `target_branch = module-<module_id>`（例 `module-module_sys`）。 +- 用 `Bash` 执行 `git branch --show-current` 得 `current_branch`。 +- `current_branch == target_branch` → 继续步骤 4。 +- 否则用 `Bash` 执行 `git rev-parse --verify <target_branch> 2>/dev/null`： + - 存在 → `git checkout <target_branch>` + - 不存在 → `git checkout -b <target_branch>` +- 若当前工作区有未提交改动且 checkout 失败 → 打印错误并停止（请用户手工处理 dirty state）。 + +### 步骤 4：初始化跨模块日志（幂等） + +`docs/superpowers/module-reports/<module_id>-cross-module.md` — 不存在则从 `${CLAUDE_SKILL_DIR}/templates/cross-module-log-template.md` 创建。 + +### 步骤 5：计算已完成 REQ 集合 `done_reqs[]`（幂等断点恢复关键） + +- 对 `req_list[]` 每个 `req_id`，用 `Glob` 查 `docs/superpowers/reviews/*-<req_id>.md`。 +- 命中后用 `Grep`（pattern `^verdict:\s*approve`，`-i` 不敏感）检查首部 verdict。 +- 两者都命中 → 加入 `done_reqs[]`。 + +### 步骤 6：渲染并打印模块横幅 + +`Read ${CLAUDE_SKILL_DIR}/templates/module-start-banner-template.md`，填充槽位；`reqs[]` 每项的 `status` 字段根据 `done_reqs[]` 填 `x`（已完成）或空格（未完成）。 + +### 步骤 7：推进主循环 + +- 从 `req_list[]` 取第一个不在 `done_reqs[]` 中的 REQ 作为 `next_req`。 +- **没有 `next_req`**（全部完成）→ 调用 `Skill(erp-local-test-gate)` 进入模块闸门。 +- **有 `next_req`** → 调用 `Skill(erp-feature-brainstorm)` 启动该 REQ 的功能循环。功能循环链（brainstorm → plan → tdd → verify → review）完成后，`erp-feature-review` 在 `verdict=approve` 分支会回调 `Skill(erp-module-start)` —— 再次进入本 skill 时，步骤 5 会把刚通过的 REQ 加入 `done_reqs[]`，步骤 7 自动取下一 REQ，形成可重入推进。 +- 任何中断（红旗 / 测试持续失败 / review 5 轮仍 request-changes）→ 停止本模块，不要静默跳下一 REQ。 + +## 参考 + +- `docs/02-开发计划.md § 二 开发顺序清单`（分发权威） +- `docs/08-模块任务管理.md § 二`（模块元数据 + `MR:` 字段；每模块行是 `- module_id ...` bullet，无 checkbox；完成判定权威是 MR state） +- `docs/superpowers/reviews/*.md`（REQ 级进度事实——verdict=approve 即完成） +- `${CLAUDE_SKILL_DIR}/templates/module-start-banner-template.md` +- `${CLAUDE_SKILL_DIR}/templates/cross-module-log-template.md` +- 下游：`erp-feature-*`、`erp-local-test-gate` diff --git a/skills/coding/erp-module-start/templates/cross-module-log-template.md b/skills/coding/erp-module-start/templates/cross-module-log-template.md new file mode 100644 index 0000000..3a653ed --- /dev/null +++ b/skills/coding/erp-module-start/templates/cross-module-log-template.md @@ -0,0 +1,8 @@ +# 跨模块改动日志 — {{module_name}} + +软规则 S2：本模块开发期间对**非当前模块**代码的改动（无论目标模块是否已 MR merged）记录在此；模块完成报告必须单列「跨模块改动」节完整贴入。漏留痕或未评估影响 → 升级为红旗。 + +**本日志由 CC 自主维护**——hook `log-cross-module.sh` 自动落存根（含 `TBD(CC 补)` 占位），CC 调 `erp-cross-module-log` skill 自主推断补「原因 / 影响评估」两列。**不需要人工填写**。 + +| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 | +|---|---|---|---|---|---| diff --git a/skills/coding/erp-module-start/templates/module-start-banner-template.md b/skills/coding/erp-module-start/templates/module-start-banner-template.md new file mode 100644 index 0000000..81ae4e2 --- /dev/null +++ b/skills/coding/erp-module-start/templates/module-start-banner-template.md @@ -0,0 +1,11 @@ +## Module start — {{module_id}} ({{module_name}}) + +- 模块依赖: {{depends_on}} +- 对应需求文件: docs/01-需求清单/{{req_file}} +- 分支: module-{{module_id}} +- 功能清单（`x` = 已完成 review approve）: +{{#each reqs}} + - [{{status}}] {{req_id}} — {{title}} +{{/each}} + +开始/恢复功能循环（Layer 3），本次处理清单中第一个未完成 REQ。命中红旗 → 停；所有 REQ 完成 → 进入模块闸门。 diff --git a/skills/coding/erp-mr-create/SKILL.md b/skills/coding/erp-mr-create/SKILL.md new file mode 100644 index 0000000..8f6cfdd --- /dev/null +++ b/skills/coding/erp-mr-create/SKILL.md @@ -0,0 +1,128 @@ +--- +name: erp-mr-create +description: 模块报告完成后，验证当前分支为 module-<id> + worktree 干净，push 推代码和所有 evidence，创建 GitLab MR（报告嵌入描述），把 MR URL 追加到模块报告 § ⑫ 并 commit，把 MR iid 回写到 docs/08 该模块 `MR:` 字段并 commit，再次 push 同步。完成信号由 MR merged state 判定（docs/08 无 checkbox）。停下等待人工审核。 +user-invocable: false +allowed-tools: Read Write Edit Skill Bash(git *) Bash(glab *) Bash(sed *) Bash(awk *) Bash(cat *) Bash(echo *) Bash(mkdir -p .tmp) Bash(mv .tmp/*) Bash(rm -f .tmp/*) +--- + +**所有输出必须使用中文。** + +# erp-mr-create + +## 前置条件 + +- `erp-module-report` 已生成报告文件并 commit 到 module 分支。 +- `erp-local-test-gate` 返回了绿色，test-gate.md 已 commit 到 module 分支。 +- 当前分支 = `module-<module_id>`（由 `erp-module-start` 步骤 3 负责切入）。 + +## 执行步骤 + +### 步骤 0：红旗检查 + +调用 `Skill(erp-red-flag-check)` → 命中则停止。 + +### 步骤 1：验证当前分支 + +- `Bash`: `git branch --show-current` → `current_branch`。 +- `current_branch` 必须匹配 `module-*`；否则打印错误并**停止**（不自动建分支——分支职责在 `erp-module-start` 步骤 3）。 +- 从 `current_branch` 取 `module_id = current_branch` 去掉 `"module-"` 前缀。 + +### 步骤 2：验证 worktree 干净（防止 evidence 文件漏 commit） + +- `Bash`: `git status --porcelain` +- 输出非空 → 打印 dirty 文件清单并**停止**： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-mr-create] ⚠️ worktree 不干净，无法 push + + 以下文件有未提交改动： + <git status 输出> + + push 前所有 evidence 必须已 commit 到 module 分支。检查点： + - erp-local-test-gate 步骤 3b 是否已 commit test-gate.md？ + - erp-module-report 步骤 5b 是否已 commit 模块报告 + cross-module log？ + - 本 skill 前没人跑过额外的 Edit/Write？ + + 修复方式：`git add <files> && git commit -m "..."`，然后重跑 /erp-workflow:erp-coding-start。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + +### 步骤 3：push 推送全部已 commit 内容 + +`git push -u origin <current_branch>` — **不要**使用 `--no-verify`（hook `deny-no-verify.sh` 会拦截）。 + +此 push 包含：代码 commit（erp-feature-tdd 产出）+ 模块 review fix commit（erp-feature-review 产出）+ test-gate evidence commit（erp-local-test-gate 产出）+ 模块完成报告 commit（erp-module-report 产出）。 + +### 步骤 4：读取 MR 标题模板 + +用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/mr-title-template.md`，填充 `module_id`、`module_name`，得到 MR 标题字符串（一行，较短，进上下文 OK）。 + +### 步骤 5：生成 MR 描述文件（纯 shell，不读模块报告内容进上下文） + +```bash +mkdir -p .tmp +DESC_FILE=.tmp/mr-desc.md +REPORT="docs/superpowers/module-reports/<date>-<module_id>.md" + +# 先用 sed 替换 description 模板的简单槽位 +sed -e "s|{{test_gate_conclusion}}|<值>|g" \ + -e "s|{{test_subagent_id}}|<值>|g" \ + -e "s|{{module_id}}|<值>|g" \ + -e "s|{{date}}|<值>|g" \ + "${CLAUDE_SKILL_DIR}/templates/mr-description-template.md" > "$DESC_FILE" + +# 把模块报告完整内容直接管道注入，替换 {{module_report_contents}} 所在行 +awk -v report="$REPORT" ' + /\{\{module_report_contents\}\}/ { while ((getline line < report) > 0) print line; close(report); next } + { print } +' "$DESC_FILE" > .tmp/mr-desc.final +mv .tmp/mr-desc.final "$DESC_FILE" +``` + +关键：**模块报告内容只经 awk 管道流过**，从不进入 LLM 上下文。 + +### 步骤 6：创建 MR + +```bash +TITLE_FILE=.tmp/mr-title.txt +echo "<步骤 4 得到的标题>" > "$TITLE_FILE" +glab mr create --title "$(cat "$TITLE_FILE")" --description "$(cat "$DESC_FILE")" +rm -f .tmp/mr-title.txt .tmp/mr-desc.md +``` + +### 步骤 7：追加 MR URL 到模块报告 § ⑫ 并 commit + +- 解析返回的 MR URL 和 IID（`<iid>`）。 +- `Edit docs/superpowers/module-reports/<date>-<module_id>.md` 的 § ⑫：把 `{{mr_url}}` 占位替换为实际 URL（若已替换过，追加一行）。 +- `Bash`: `git add docs/superpowers/module-reports/<date>-<module_id>.md && git commit -m "docs(<module_id>): record MR !<iid> link in module report"`。 + +### 步骤 8：回写 docs/08 的 MR 字段并 commit + +- `Edit docs/08-模块任务管理.md`：把当前模块条目的 ` - MR: —` 改为 ` - MR: !<iid>`（只改一行）。docs/08 § 二每模块是 bullet（`- module_id ...`，无 checkbox），`MR:` 字段是唯一动态字段。 +- `Bash`: `git add docs/08-模块任务管理.md && git commit -m "chore(<module_id>): record MR !<iid> in docs/08"`。 + +### 步骤 9：再次 push + +步骤 3 的 push 之后，步骤 7 和 8 又产生了两个新 commit（MR link + docs/08 MR iid）。必须再次 push 让 MR 自动更新 commit 列表 + diff： + +`Bash`: `git push origin <current_branch>` + +### 步骤 10：向会话打印 MR URL + +### 步骤 11：停止 — 等待人工 Approve + Merge + +用户合并后再跑 `/erp-workflow:erp-coding-start`，入口会自动检测 MR merged → `git checkout main` + `git pull --ff-only` 同步远程 + 派发下一模块。 + +## 设计要点 + +- **main 是 protected branch**，只能通过 MR 修改。MR diff 包含：代码 + 模块报告 + test-gate evidence + cross-module log + docs/08 的 `MR: !<iid>` 字段。 +- **完成信号由 MR state 判定**——docs/08 § 二每模块是 bullet（无 checkbox），没有可翻勾的地方。从结构上消除"用户抢跑 coding-start 跳过未合并模块"的 ordering bug。仅 `MR:` 字段在 `—` / `!<iid>` 之间变化。 +- **worktree 干净前置**（步骤 2）：保证 test-gate.md、module-report.md、cross-module log.md 都已进 repo，审计证据完整；防止下次 coding-start `git checkout main` 遇到 dirty state。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/mr-title-template.md` +- `${CLAUDE_SKILL_DIR}/templates/mr-description-template.md` +- 上游：`erp-module-report` +- 守门：`erp-red-flag-check` +- 下游闸门：用户手工 MR Approve + Merge diff --git a/skills/coding/erp-mr-create/templates/mr-description-template.md b/skills/coding/erp-mr-create/templates/mr-description-template.md new file mode 100644 index 0000000..0a71f94 --- /dev/null +++ b/skills/coding/erp-mr-create/templates/mr-description-template.md @@ -0,0 +1,18 @@ +## 模块完成报告 + +见 `docs/superpowers/module-reports/{{date}}-{{module_id}}.md`（本 MR 仓库内完整贴入下方）。 + +--- + +{{module_report_contents}} + +--- + +## 本地闸门证据 + +- test.sh: {{test_gate_conclusion}}（subagent: {{test_subagent_id}}） + +## 审核入口 + +- 本 MR = 模块 `{{module_id}}` 的唯一人工介入点 +- Approve + Merge 后，下次用户跑 `/erp-workflow:erp-coding-start` 时入口会自动扫到 `glab mr view state=merged`，`git pull --ff-only` 同步 main 并推进下一模块。docs/08 § 二每模块是 bullet（无 checkbox），完成由 MR state 判定 diff --git a/skills/coding/erp-mr-create/templates/mr-title-template.md b/skills/coding/erp-mr-create/templates/mr-title-template.md new file mode 100644 index 0000000..2cf9c1a --- /dev/null +++ b/skills/coding/erp-mr-create/templates/mr-title-template.md @@ -0,0 +1 @@ +feat({{module_id}}): {{module_name}} diff --git a/skills/crosscut/erp-coding-start/SKILL.md b/skills/crosscut/erp-coding-start/SKILL.md new file mode 100644 index 0000000..f57519a --- /dev/null +++ b/skills/crosscut/erp-coding-start/SKILL.md @@ -0,0 +1,123 @@ +--- +name: erp-coding-start +description: B 阶段（Coding）入口。先验证 Plan 已完成；按 docs/02 § 二 REQ 开发顺序清单扫，对每个 REQ 所属模块用 docs/08 的 `MR:` 字段 + `glab mr view state` 判完成——merged 跳过，`—` 或 opened/closed 选为当前模块并派发到 erp-module-start。派发前先 git checkout main + pull --ff-only 保持 base 最新。docs/08 § 二 每模块是 bullet（无 checkbox），完成由 MR state 判定。 +user-invocable: true +allowed-tools: Skill Read Glob Grep Bash(glab mr *) Bash(git branch *) Bash(git checkout *) Bash(git pull *) Bash(git status *) +--- + +**所有输出必须使用中文。** + +B 阶段（Coding）的入口分发器。职责：**验证 Plan 已完成 → 按 docs/02 § 二 REQ 序 + MR state 找当前模块 → 切回 main 同步 remote → 派发 erp-module-start**。不直接生成任何文件。开发顺序权威是 `docs/02 § 二`；完成判定权威是 `docs/08 条目的 MR: 字段 + glab mr view state`（docs/08 § 二每模块是 bullet，无 checkbox）。 + +## 执行步骤 + +### 步骤 1：确认 docs/08 存在 + +用 `Glob` 检查 `docs/08-模块任务管理.md`。 +- 不存在 → 打印"⚠️ 项目尚未初始化，请先运行 `/erp-workflow:erp-plan-start`"并停下。 + +### 步骤 2：Plan 完成性检查 + +用 `Grep` 在 `docs/08-模块任务管理.md` 搜 `^- \[ \] A[0-5]`（pattern 可以直接匹配父项未勾的情况；也可以更宽地搜 `^[[:space:]]*- \[ \].*A[0-5]` 涵盖子项）。 + +- **命中任一 A 未勾** → 打印： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-coding-start] ⚠️ Plan 尚未完成 + + docs/08 § 一 还有未勾选项，请先运行： + /erp-workflow:erp-plan-start + + 继续 Plan 阶段直到 A5 下游文档生成完成，再回来运行 coding-start。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + **停下**。 + +- 无命中 → Plan 已完成，进入步骤 3。 + +### 步骤 3：按 docs/02 REQ 序 + MR state 找当前模块 + +1. 用 `Read` 读取 `docs/02-开发计划.md` 的 § 二；用 `Grep`（pattern `^\|\s*[0-9]+\s*\|\s*\*\*(REQ-[A-Z0-9]+-[0-9]+)\*\*\s*\|\s*(module_\w+)`，`-n`）抽取所有表格数据行，按行号升序得 `req_order[]`，每项含 `req_id` + `module_id`。 +2. 若 `req_order` 为空 → 打印错误并**停下**（与原逻辑相同，略）。 +3. **初始化模块完成缓存 `module_merged[module_id → bool]`**（空）。 +4. 按序遍历 `req_order[]`： + - 若 `module_merged[module_id]` 已有缓存： + - `true` → 跳过本 REQ，继续下一个 + - `false` → `current_module = module_id`，结束遍历，进入步骤 4 + - 未缓存 → 读 docs/08 § 二 该模块条目的 ` - MR:` 字段： + - `MR: —` → `module_merged[module_id] = false`；`current_module = module_id`，结束遍历 + - `MR: !<iid>` → `Bash`: `glab mr view <iid> -F json 2>/dev/null`，解析 `.state`： + - `merged` → `module_merged[module_id] = true`，跳过本 REQ + - 其他（`opened` / `closed` / 查不到）→ `module_merged[module_id] = false`；`current_module = module_id`，结束遍历 +5. 全遍历完仍无命中（所有模块都 merged） → 打印： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-coding-start] ✅ 所有模块已完成 + + docs/02 § 二 清单中每个 REQ 所属模块的 MR 都已 merged。项目结束。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + 并**停下**。 +6. 命中后：记录 `current_module` 的 `MR:` 字段值（`—` / `!<iid>-opened` / `!<iid>-closed` / `!<iid>-查不到`，用于步骤 5 横幅展示）。 + +### 步骤 4：切回 main + 同步远程（准备 module-start 切新分支的干净 base） + +- `Bash`: `git branch --show-current` → `current_branch`。 +- 若 `current_branch != main`： + - `Bash`: `git status --porcelain`；非空 → 打印： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-coding-start] ⚠️ 当前分支 <current_branch> 有未提交改动，无法切换到 main + + <git status 输出> + + 请手工处理后重跑 /erp-workflow:erp-coding-start。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + 并**停下**。 + - `Bash`: `git checkout main`。 +- `Bash`: `git pull --ff-only origin main`。 + - 失败（非 fast-forward / 网络 / 冲突）→ 打印错误横幅： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-coding-start] ⚠️ 同步 main 失败 + + 本地 main 无法 fast-forward 到 remote。请手工处理： + git status + git log main..origin/main # 远程领先的 commit + git log origin/main..main # 本地未推的 commit + 修复后重跑 /erp-workflow:erp-coding-start。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + 并**停下**。 + +### 步骤 5：打印横幅并分发 + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-coding-start] + 阶段：B 编码 + 当前模块：<current_module> + MR 状态：<未建 | opened | closed | 查不到> + 下一步：invoke erp-module-start +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +然后立即用 `Skill` 工具调用 `erp-module-start`。 + +> 分发前先调 `erp-red-flag-check`；命中红旗则停在此不分发。 + +## 设计要点 + +- **完成判定直接读 `MR:` 字段 + `glab mr view state`**：docs/08 § 二 每模块是 bullet（无 checkbox），没有可翻勾的地方。这从结构上消除了 Codex adversarial review Finding 1 描述的"用户抢跑 coding-start 跳过未合并模块"的 ordering bug： + - MR 未 merge 前本地 docs/08 没有任何"已完成"标记 + - 即使用户抢跑 coding-start，步骤 3 扫到 MR opened 仍会选中当前模块（不是跳到下一模块） + - module-start 会 `git checkout module-<id>` 回到原分支，用户看到"继续在当前模块"而非"开始下一模块" +- **pull main 时机**：原设计里 pull main 是 merged 分支特有动作；新设计里每次派发前都 pull main（代码同步 + module-start 切新分支时 base 新鲜）。 + +## 参考 + +- `docs/02-开发计划.md § 二 开发顺序清单`（分发权威） +- `docs/08-模块任务管理.md § 二`（模块元数据 + `MR:` 字段；每模块行是 `- module_id ...` bullet，无 checkbox） +- `CLAUDE.md`（项目指令） +- `erp-plan-start`（姊妹入口，A 阶段） diff --git a/skills/crosscut/erp-cross-module-log/SKILL.md b/skills/crosscut/erp-cross-module-log/SKILL.md new file mode 100644 index 0000000..c9e7d04 --- /dev/null +++ b/skills/crosscut/erp-cross-module-log/SKILL.md @@ -0,0 +1,37 @@ +--- +name: erp-cross-module-log +description: 为 log-cross-module.sh hook 自动追加到跨模块改动日志中的条目补填「原因」和「影响评估」。覆盖对"非当前模块"文件的编辑（无论目标模块是否已 MR merged）。 +user-invocable: false +allowed-tools: Read Write Edit Bash(git branch *) +--- + +**所有输出必须使用中文。** + +# erp-cross-module-log + +## 说明 + +软规则 S2 执行：对**非当前模块**文件的每次编辑（无论目标模块是否已 MR merged）必须记录原因 + 影响评估。 + +**本日志由 CC 自主维护**——hook 自动落存根、CC 自主推断补齐两列，**不需要人工填写**。人工只在最终看 MR 描述时复核。 + +## 执行步骤 + +1. 确定当前模块（从当前 git 分支名推导：`git branch --show-current` → `module-<module_id>` → 取 `module_id`。`erp-module-start` 步骤 3 保证本 skill 执行时一定处于 `module-*` 分支）。 +2. 打开 `docs/superpowers/module-reports/<current>-cross-module.md`（不存在则从 `${CLAUDE_SKILL_DIR}/templates/cross-module-log-template.md` 初始化）。 +3. 找到「原因」或「影响评估」列中含 `TBD(CC 补)` 的行。 +4. 对每个 TBD 行，CC **自主推断**填写以下两列（基于当前 session 的改动上下文 + REQ 卡片 + 目标模块的代码）： + - **原因**：为什么要修改目标模块的代码？当前模块的哪个需求迫使这样做？ + - **影响评估**：目标模块的哪些 API / 行为 / 调用方可能受影响？其现有测试是否仍然有效？是否需要新测试？（1-3 句话） +5. 编辑该行；保持时间戳 / 目标模块 / 文件 / 改动摘要列不变。 +6. 输出确认：`cross-module-log: 更新了 N 行`。 + +## 下游 + +填充后的日志会被 `erp-module-report` 原文嵌入到 `module-report-template.md` § ⑦。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/cross-module-log-template.md` +- `${CLAUDE_SKILL_DIR}/templates/cross-module-log-row-template.md` +- `CLAUDE.md` § 🟡 软规则 S2 diff --git a/skills/crosscut/erp-cross-module-log/templates/cross-module-log-row-template.md b/skills/crosscut/erp-cross-module-log/templates/cross-module-log-row-template.md new file mode 100644 index 0000000..883cdcd --- /dev/null +++ b/skills/crosscut/erp-cross-module-log/templates/cross-module-log-row-template.md @@ -0,0 +1 @@ +| {{timestamp}} | {{target_module}} | {{file_path}} | {{change_summary}} | {{reason}} | {{impact}} | diff --git a/skills/crosscut/erp-cross-module-log/templates/cross-module-log-template.md b/skills/crosscut/erp-cross-module-log/templates/cross-module-log-template.md new file mode 100644 index 0000000..3a653ed --- /dev/null +++ b/skills/crosscut/erp-cross-module-log/templates/cross-module-log-template.md @@ -0,0 +1,8 @@ +# 跨模块改动日志 — {{module_name}} + +软规则 S2：本模块开发期间对**非当前模块**代码的改动（无论目标模块是否已 MR merged）记录在此；模块完成报告必须单列「跨模块改动」节完整贴入。漏留痕或未评估影响 → 升级为红旗。 + +**本日志由 CC 自主维护**——hook `log-cross-module.sh` 自动落存根（含 `TBD(CC 补)` 占位），CC 调 `erp-cross-module-log` skill 自主推断补「原因 / 影响评估」两列。**不需要人工填写**。 + +| 时间戳 | 目标模块 | 文件 | 改动摘要 | 原因 | 影响评估 | +|---|---|---|---|---|---| diff --git a/skills/crosscut/erp-plan-start/SKILL.md b/skills/crosscut/erp-plan-start/SKILL.md new file mode 100644 index 0000000..4b1c561 --- /dev/null +++ b/skills/crosscut/erp-plan-start/SKILL.md @@ -0,0 +1,87 @@ +--- +name: erp-plan-start +description: A 阶段（Plan）入口与分发器。根据 docs/08 § 一 的 checkbox 状态派发到 A0~A5 对应 skill（§ 二是 B 阶段模块元数据，本 skill 不读）。Plan 全部完成（A5 已勾）时打印提示让用户运行 /erp-workflow:erp-coding-start 进入 B 阶段。 +allowed-tools: Skill Read Glob Grep +--- + +**所有输出必须使用中文。** 用户是中文用户，所有对话、横幅、提示、报告一律用中文。 + +你是 ERP 项目**规划阶段的编排器**。你**只派发 A 阶段（A0~A5）的 skill**；docs/08 § 一 全部勾选后即停下，提示用户显式运行 `/erp-workflow:erp-coding-start` 进入 B 阶段，**不直接派发任何 B 阶段 skill**。你不直接生成任何文件。 + +## 第一步：读取 docs/08 + 决定分发目标 + `mark_line` + +docs/08 § 一 是**Plan 阶段进度权威**（A0~A5 的 checkbox）。不做其他文件存在性检查——文件在不等于做完，只有 checkbox 是做完的证据。§ 二的模块元数据由 erp-coding-start 消费，本 skill 不读。 + +### 分发判定 + +1. **docs/08 是否存在** + 用 `Glob` 检查 `docs/08-模块任务管理.md`。 + - 不存在 → `target=erp-project-init`、`mark_line=A0`、`unchecked_line=""`（流程开始）。 + +2. **找 § 一 第一个未勾的 A 子项** + 用 `Grep`（pattern `^[[:space:]]*- \[ \].*A[0-5]`，`-n`）在 `docs/08-模块任务管理.md` 的 § 一 Plan 段搜索，取**最小行号**那一行作为 `unchecked_line`。 + 注：§ 二 的模块行是纯 bullet（`- module_id ...`，无 checkbox），不会被此 pattern 匹配。 + +3. **把 `unchecked_line` 映射到 `target_skill` + `mark_line`**： + +| `unchecked_line` 特征 | `target_skill` | `mark_line` | +|---|---|---| +| 无 docs/08 | `erp-project-init` | `A0` | +| 含 `A0` / A0 子项 | `erp-project-init` | `A0` | +| 含 `A1` / A1 子项 | `erp-scope-lock` | `A1` | +| 含 `A2` / A2 子项 | `erp-skeleton-gen` | `A2` | +| 含 `A3` / A3 子项 | `erp-db-init` | `A3` | +| 含 `A4` / A4 子项 | `erp-db-design-gen` | `A4` | +| 含 `A5` / A5 子项 | `erp-downstream-gen` | `A5` | +| 无命中（A 全勾，Plan 阶段结束） | **无分发** | `plan-done` | + +项目完成状态（B 阶段所有模块 MR merged）由 `erp-coding-start` 扫 MR state 判定并打印，本 skill 不处理。 + +## 第二步：分发通知 + 调用目标 skill + +本入口**不画完整流程图**——目标 A skill 会在自己的步骤 0 打印带 `▶` 当前位置的流程图。本步骤只做分发决策与通知。 + +### 2.1 Plan 已完成（`mark_line=plan-done`） + +A 阶段所有 checkbox 均 `[x]`。因无下游 A skill 接手，本步骤**自己打印流程图**（`▶` 标在"规划阶段到此结束"）+ 提示，**停下**；项目整体完成状态由 `erp-coding-start` 扫 MR state 判定，本 skill 不负责： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → A3 初始化 DB → A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ ▶ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ + +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-plan-start] ✅ Plan 阶段全部完成 + + 请运行 /erp-workflow:erp-coding-start 进入 B 阶段模块循环。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +不调任何下游 skill。 + +### 2.2 正常派发（`target_skill` 非空） + +打印简短分发通知： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-plan-start] → 派发到 <target_skill> + 未勾项：<docs/08 中第一个 - [ ] 行内容> +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +立即用 `Skill` 工具调用 `target_skill`。 + +## 参考 + +- `docs/08-模块任务管理.md`（唯一进度权威） +- `CLAUDE.md`（项目指令） +- 下游 skills（通过 `Skill` 工具按名称调用） diff --git a/skills/crosscut/erp-red-flag-check/SKILL.md b/skills/crosscut/erp-red-flag-check/SKILL.md new file mode 100644 index 0000000..a6e20e4 --- /dev/null +++ b/skills/crosscut/erp-red-flag-check/SKILL.md @@ -0,0 +1,50 @@ +--- +name: erp-red-flag-check +description: 在每个功能循环步骤和生成重要制品前运行。检查 CLAUDE.md 中的 6 项红旗清单，命中任一项则追加 Blocker 到计划文件并停止。 +user-invocable: false +allowed-tools: Read Write Bash(mysql *) +--- + +**所有输出必须使用中文。** + +# erp-red-flag-check + +## 说明 + +验证 CLAUDE.md § 🚩 静默执行红旗清单中的 6 项均未触发。命中任一项则中断。 + +## 调用时机 + +- 每个功能循环步骤开始前（3.1-3.5） +- 生成模块级制品前（模块报告、MR 描述） +- 用户请求涉及 schema 冲突、技术栈边界或外部依赖时 + +## 检查清单（6 项 — 权威来源：CLAUDE.md） + +1. **需求与 schema 冲突** — 所需字段/表在实时 schema 中不存在 +2. **需求本身歧义** — 存在两种或以上合理解读 +3. **超技术栈边界** — 需要 CLAUDE.md 技术栈表以外的框架/中间件 +4. **测试反复失败** — 同一功能中同一测试连续 10 次修复失败 +5. **要改密钥/账密/包名** — 涉及 `docs/07-环境配置.md` 中的人工填写字段 +6. **外部接口不可达** — 第三方 API / 证书 / 网络问题 + +## 执行步骤 + +1. 读取当前功能的规格/计划文件路径（从对话或 `docs/08` 获取）。 +2. 逐项检查 6 个红旗。如果全部未命中 → 输出 `red-flag-check: 通过`，退出。 +3. 命中时： + - 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/red-flag-block-template.md` + - 填充槽位（flag_number、flag_name、description、affected_scope、recommendation、decision_needed） + - 将渲染后的块追加到当前计划文件：`docs/superpowers/plans/YYYY-MM-DD-<REQ-id>.md` + - 向会话打印一句话摘要 + 指向计划文件的路径 + - **停止** — 在用户决策前不调用任何后续 skill + +## 输出 + +`red-flag-check: 通过`（仅会话），或一个 `## 🚩 Blocker` 块追加到功能计划文件。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/red-flag-block-template.md` +- `CLAUDE.md` § 🚩 静默执行红旗清单（权威 6 条） +- `CLAUDE.md` § 🟡 软规则（S2 跨模块改动，不触发红旗但需留痕） diff --git a/skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md b/skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md new file mode 100644 index 0000000..8d1278e --- /dev/null +++ b/skills/crosscut/erp-red-flag-check/templates/red-flag-block-template.md @@ -0,0 +1,8 @@ +## 🚩 Blocker + +**红旗编号**: {{flag_number}} (1-6，对应 CLAUDE.md 🚩 静默执行红旗清单) +**红旗名称**: {{flag_name}} +**问题描述**: {{description}} +**影响范围**: {{affected_scope}} +**我的建议**: {{recommendation}} +**等待决策**: {{decision_needed}} diff --git a/skills/plan/erp-db-design-gen/SKILL.md b/skills/plan/erp-db-design-gen/SKILL.md new file mode 100644 index 0000000..330331a --- /dev/null +++ b/skills/plan/erp-db-design-gen/SKILL.md @@ -0,0 +1,110 @@ +--- +name: erp-db-design-gen +description: A4 DB 设计生成 + REQ 回填——用 mysql CLI 反查 schema 生成 docs/03-数据库设计文档.md；然后用 Grep 在 docs/01-需求清单/*.md 定位 TBD(A4 自动补) 替换为实际表/字段引用。 +user-invocable: false +allowed-tools: Read Write Edit Grep Glob Skill Bash(mysql *) Bash(source *) +--- + +**所有输出必须使用中文。** + +# erp-db-design-gen + +## 前置条件 + +- `erp-db-init` 已完成：`.env.local` 凭据已填，`sql/migrations/V1__initial_schema.sql` 和 `sql/seed-data.sql` 都已生成。 +- `erp-scope-lock` 已完成：`docs/01-需求清单/<module>-*.md` REQ 卡片存在，含 `TBD(A4 自动补)` 占位。 + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A4）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → A3 初始化 DB → ▶ A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. 查询实时 schema + +用 `Bash` source `.env.local` 后查询： + +```bash +source .env.local +MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD} -N -B" + +# 表列表 + 注释 +$MYSQL_CMD -e "SELECT table_name, table_comment FROM information_schema.tables WHERE table_schema='${DB_SCHEMA}' AND table_type='BASE TABLE' ORDER BY table_name;" + +# 字段详情 +$MYSQL_CMD -e "SELECT table_name, column_name, column_type, is_nullable, column_default, column_comment FROM information_schema.columns WHERE table_schema='${DB_SCHEMA}' ORDER BY table_name, ordinal_position;" + +# 外键 +$MYSQL_CMD -e "SELECT table_name, column_name, referenced_table_name, referenced_column_name FROM information_schema.key_column_usage WHERE table_schema='${DB_SCHEMA}' AND referenced_table_name IS NOT NULL;" + +# 索引 +$MYSQL_CMD -e "SELECT table_name, index_name, GROUP_CONCAT(column_name ORDER BY seq_in_index) AS cols, non_unique FROM information_schema.statistics WHERE table_schema='${DB_SCHEMA}' GROUP BY table_name, index_name, non_unique;" +``` + +将结果解析为结构化列表（内存中）。**不把查询结果完整写入会话上下文**——只保留表名 + 字段名 + 关键元信息。 + +### B. 生成 docs/03 + +1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`、`er_overview`、`tables[]`。 +2. 对每张表，用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`，填充并追加。 +3. 每个字段的业务含义： + - 如果 `column_comment` 非空，直接用 + - 否则从 A1 生成的 REQ 卡片上下文推断 +4. 用 `Write` 写入 `docs/03-数据库设计文档.md`。 + +### C. 回填 REQ 卡片的 TBD 字段 + +1. 用 `Glob` 列出 `docs/01-需求清单/*.md`（排除 `README.md`）。 +2. 用 `Grep` 在这些文件中搜索 `TBD(A4 自动补)` 的**行号**（不读全文）。 +3. 对每个命中的 REQ： + - 用 `Read` 仅读取该 REQ 卡片所在的片段（REQ 标题行前后 20 行） + - 根据 `goal` / `input` / `output` 推断引用的表 + - 用 `Edit`：`依赖表: TBD(A4 自动补)` → `依赖表: <table1>, <table2>`（具体表名） + - **不动** `依赖接口: TBD(A5 自动补)`——那行由 A5 `erp-downstream-gen` 生成 docs/05 后回填 +4. 打印回填统计：`A4 回填 N 处 schema_refs`。 + +### D. 一致性检查 + +1. 用 `Grep` 在 `docs/01-需求清单/*.md` 搜索 `依赖表:`，抽取所有表名。 +2. 用 `Grep` 在 `docs/03-数据库设计文档.md` 搜索表标题（每张表一行 `### table_name`）。 +3. 比对： + - REQ 提到但 docs/03 没有的表 → 报错停下（schema 与需求不一致；请确认是 REQ 理解错误还是需要新增 migration） + - docs/03 有但没 REQ 引用 → 警告但不停下（可能是未使用表） +4. 用 `Grep` 搜 `TBD(A4 自动补)` 在 `docs/01-需求清单/*.md`：应 0 命中（A4 已把所有 schema_refs 回填完）；若仍有，打印残留 REQ 清单并停下。 + +### E. 勾选 docs/08 进度 + 进入 A5 + +用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 4 个 checkbox（A4 的 3 个子项 + A4 父项）： +- ` - [ ] docs/03 数据库设计已生成` → `[x]` +- ` - [ ] REQ 卡片依赖表已回填` → `[x]` +- ` - [ ] schema 一致性检查通过` → `[x]` +- `- [ ] A4 DB 设计 + REQ 回填 — erp-db-design-gen` → `[x]` + +输出 `db-design-gen: 完成（<T> 张表, <R> 个 REQ 已回填依赖表；依赖接口留给 A5）`。 + +立即调用 `Skill(erp-downstream-gen)` 进入 A5，不等用户手动输入。 + +## 不变量 + +- REQ 卡片的 `依赖接口` 字段不在此处填充，留给 A5 erp-downstream-gen（它会先生成 docs/05 API 契约，再按 `TBD(A5 自动补)` 回填）。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md` +- `.env.local`（DB 凭据） +- `docs/01-需求清单/*.md`（回填目标） diff --git a/skills/plan/erp-db-design-gen/templates/docs-03-header-template.md b/skills/plan/erp-db-design-gen/templates/docs-03-header-template.md new file mode 100644 index 0000000..ff9bd9e --- /dev/null +++ b/skills/plan/erp-db-design-gen/templates/docs-03-header-template.md @@ -0,0 +1,14 @@ +# 03-数据库设计文档 + +Schema: `{{schema_name}}` +Migration 清单: `sql/migrations/V*.sql`（由 Flyway 顺序 apply） +生成方式: 通过 `mysql` 命令行从 live schema 反查生成。 + +## ER 关系概览 + +{{er_overview}} + +## 表清单 +{{#each tables}} +- `{{table_name}}` — {{purpose}} +{{/each}} diff --git a/skills/plan/erp-db-design-gen/templates/docs-03-table-template.md b/skills/plan/erp-db-design-gen/templates/docs-03-table-template.md new file mode 100644 index 0000000..dfdc35a --- /dev/null +++ b/skills/plan/erp-db-design-gen/templates/docs-03-table-template.md @@ -0,0 +1,22 @@ +## `{{table_name}}` — {{purpose}} + +### 字段 + +| 字段 | 类型 | Nullable | 默认 | 业务含义 | +|---|---|---|---|---| +{{#each columns}} +| {{name}} | {{type}} | {{nullable}} | {{default}} | {{business_meaning}} | +{{/each}} + +### 索引 +{{#each indexes}} +- `{{name}}` ({{type}}): {{columns}} +{{/each}} + +### 外键 +{{#each foreign_keys}} +- `{{name}}`: {{from_col}} → {{to_table}}.{{to_col}} ({{on_delete}}) +{{/each}} + +### 业务注记 +{{notes}} diff --git a/skills/plan/erp-db-init/SKILL.md b/skills/plan/erp-db-init/SKILL.md new file mode 100644 index 0000000..b9a9cf7 --- /dev/null +++ b/skills/plan/erp-db-init/SKILL.md @@ -0,0 +1,157 @@ +--- +name: erp-db-init +description: A3 验证 MySQL 连接 + 导出当前 schema 为 `sql/migrations/V1__initial_schema.sql`（Flyway 初始 migration，DDL only）+ 导出当前数据为 `sql/seed-data.sql`（INSERT only）。不执行任何 DDL。 +user-invocable: false +allowed-tools: Read Write Edit Glob Skill Bash(mkdir *) Bash(mysql *) Bash(mysqldump *) Bash(source *) Bash(sed *) Bash(cat *) Bash(rm sql/migrations/*.raw) Bash(rm sql/*.raw) Bash(grep *) +--- + +**所有输出必须使用中文。** + +# erp-db-init + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A3）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → ▶ A3 初始化 DB → A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. 防御性检查 .env.local + +用 `Glob` 检查 `.env.local` 是否存在。 + +- **存在** → 进入步骤 B。 +- **不存在** → 向用户输出： + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-db-init] ⚠️ .env.local 缺失 + + 可能是被误删。请先重新运行 erp-skeleton-gen 重建， + 或手动从 .env.local.example 复制并填写 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA。 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + +### B. 验证 MySQL 连接 + +用 `Bash` 执行（先 `source .env.local` 加载变量）： + +```bash +source .env.local && mysql -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" -e "USE \`$DB_SCHEMA\`; SHOW TABLES;" +``` + +- **成功** → 记录表列表，继续步骤 C。 +- **失败** → 向用户输出具体错误（认证失败 / schema 不存在 / 主机不可达等），提示检查 `.env.local`，**停下**。 + +### C. 导出当前 schema 为 V1 initial migration + +用 `Bash` 执行 mysqldump（**仅 DDL，不含数据**）： + +```bash +mkdir -p sql/migrations && source .env.local && mysqldump --no-data --skip-comments -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" > sql/migrations/V1__initial_schema.sql.raw +``` + +如果 `mysqldump` 命令不存在，向用户输出具体错误（提示安装 `mysql-client` / `brew install mysql-client` 等）并**停下**（mysql 和 mysqldump 是 A0 `erp-project-init` 的前置依赖，正常情况下应已就绪）。 + +### D. 加头部写入 V1 最终 migration 文件 + +**严禁**用 `Read` 读取 `.sql.raw`（dump 可能有几千行，会撑爆上下文）。用纯 shell 拼接： + +```bash +PROJECT="<从 CLAUDE.md 读到的项目名称>" +TS="$(date -u +%FT%TZ)" +source .env.local +{ + sed -e "s|{{project_name}}|$PROJECT|g" \ + -e "s|{{timestamp}}|$TS|g" \ + -e "s|{{schema_name}}|$DB_SCHEMA|g" \ + "${CLAUDE_SKILL_DIR}/templates/migration-v1-header-template.sql" + cat sql/migrations/V1__initial_schema.sql.raw +} > sql/migrations/V1__initial_schema.sql +rm sql/migrations/V1__initial_schema.sql.raw +``` + +说明： +- `sed` 替换 header 模板里的 3 个槽位 +- `cat` 追加 dump 内容 +- 全程不经过 LLM 上下文 + +### E. 导出当前数据为 seed-data.sql + +用 `Bash` 执行 mysqldump（**仅数据，INSERT only**）： + +```bash +source .env.local && mysqldump --no-create-info --complete-insert --skip-comments --skip-extended-insert \ + -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" > sql/seed-data.sql.raw +``` + +拼接 header 模板 + raw： + +```bash +PROJECT="<从 CLAUDE.md 读到的项目名称>" +TS="$(date -u +%FT%TZ)" +source .env.local +{ + sed -e "s|{{project_name}}|$PROJECT|g" \ + -e "s|{{timestamp}}|$TS|g" \ + -e "s|{{schema_name}}|$DB_SCHEMA|g" \ + "${CLAUDE_SKILL_DIR}/templates/seed-data-sql-template.sql" + echo "" + echo "SET FOREIGN_KEY_CHECKS = 0;" + echo "" + cat sql/seed-data.sql.raw + echo "" + echo "SET FOREIGN_KEY_CHECKS = 1;" +} > sql/seed-data.sql +rm sql/seed-data.sql.raw +``` + +说明： +- 本地 MySQL 里已有的数据就是测试数据集，直接 dump 下来 +- `--complete-insert` 让 INSERT 含列名，schema 演化后仍可读 +- `--skip-extended-insert` 让每行一条 INSERT，diff 友好 +- 全程不经过 LLM 上下文 + +### F. 验证 + 勾选 docs/08 进度 + 进入 A4 + +1. 用 `Bash` 执行 `grep -c "CREATE TABLE" sql/migrations/V1__initial_schema.sql` 统计表数量，与步骤 B 记录的表数对比。不一致 → 报错停下。 + +2. 用 `Bash` 执行 `grep -c "INSERT INTO" sql/seed-data.sql` 统计数据行数： + - > 0：正常 + - = 0：提示"本地 DB 无数据，seed-data.sql 为空（只有 header 注释）；如需测试数据，请在本地 MySQL 插入后重跑 A3"，允许继续 + +3. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 5 个 checkbox（A3 的 4 个子项 + A3 父项）： + - ` - [ ] .env.local 凭据验证通过` → `[x]` + - ` - [ ] MySQL 连接验证通过` → `[x]` + - ` - [ ] V1 initial migration 已生成（sql/migrations/V1__initial_schema.sql，DDL only）` → `[x]` + - ` - [ ] sql/seed-data.sql 已导出（本地数据快照，INSERT only）` → `[x]` + - `- [ ] A3 DB 初始化 — erp-db-init` → `[x]` + +4. 输出 `db-init: 完成（schema=<名称>, tables=<T>, V1 migration ✓, seed rows=<R>）`。 + +5. 立即调用 `Skill(erp-db-design-gen)` 进入 A4，不等用户手动输入。 + +## 不变量 + +- 密码通过 `.env.local` 经 `source` 注入，不硬编码在命令里。 +- 本 skill **只** 产生 V1 initial migration 和 seed-data.sql 快照；后续 V2/V3 及业务数据变化由 B 阶段 `erp-feature-tdd` 在 REQ 实现时写入。 + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/migration-v1-header-template.sql` +- `${CLAUDE_SKILL_DIR}/templates/seed-data-sql-template.sql` +- 产物 1：`sql/migrations/V1__initial_schema.sql`（由 Flyway 在 Spring Boot 启动时自动 apply） +- 产物 2：`sql/seed-data.sql`（由开发者选一种方式装载：@Sql / R__seed / data.sql） diff --git a/skills/plan/erp-downstream-gen/SKILL.md b/skills/plan/erp-downstream-gen/SKILL.md new file mode 100644 index 0000000..fd7a133 --- /dev/null +++ b/skills/plan/erp-downstream-gen/SKILL.md @@ -0,0 +1,170 @@ +--- +name: erp-downstream-gen +description: A5 下游文档生成——基于 docs/01 和 docs/03 推导，一次性生成 docs/02 + docs/05 + docs/06 § 五 + docs/10，回填 REQ 卡片依赖接口，把模块清单追加到 docs/08 § 二。 +user-invocable: false +allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(cat *) +--- + +**所有输出必须使用中文。** + +# erp-downstream-gen + +## 前置条件 + +- `docs/01-需求清单/*.md` 完整 REQ 卡片已就绪（A1 生成 + 人工审阅过）。 +- `docs/03-数据库设计文档.md` 已就绪（A4 生成）。 +- `docs/05` / `docs/06` / `docs/10` / `sql/seed-data.sql` 等下游文件尚不存在（本 skill 创建）。 + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A5）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → A3 初始化 DB → A4 生 DB 设计 → ▶ A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. docs/02 — 开发计划（含 REQ 级开发顺序清单，CC 分发权威） + +**清单粒度**：每行一个 REQ（功能），不是模块。同一模块的 REQ 必须**连续排列**。 + +1. 构建**模块依赖 DAG**： + - docs/03 中的外键（表 A → 表 B ⇒ A 的模块依赖 B 的模块） + - docs/01 README 中的显式 `depends_on` 提示 +2. 对模块 DAG 做拓扑排序得 `module_topo_order[]`。 +3. 对**每个模块内部**构建 REQ 间依赖（从 REQ 卡片 `goal` / `rules` / `依赖表` 推断 REQ-A 是 REQ-B 的前置），得到模块内 REQ 顺序。 +4. 合成 `req_order[]`：按 `module_topo_order[]` 依次铺开每个模块内的 REQ 序列（**同模块 REQ 连续**）。 +5. **环依赖打破**： + - **模块级**：若模块 DAG 存在环（module_A ↔ module_B），按启发式（字母序 / 被依赖次数多者先）破环排出 `module_topo_order`，并在**参与环的模块里第一个 REQ** 的 `note` 字段填入原因（如 "A↔B 互依赖：先做 A 的骨架"）。 + - **REQ 级（同模块内）**：若模块内 REQ 互依赖，同样破环，`note` 填原因。 + - 非环 REQ `note` 留 `—`。 +6. 为 `req_order[]` 每项生成字段： + - `index`：行号（从 1 开始） + - `req_id`：如 `REQ-SYS-001` + - `module_id`：该 REQ 所属模块，如 `module_sys` + - `rationale`（一行**选中理由**）：依赖驱动的简短描述，如 `所属模块无依赖，基础模块` / `依赖 REQ-SYS-001 已在前` / `所属模块依赖 module_sys 已在前` + - `note`（一行**备注**）：默认 `—`；仅环依赖打破场景填原因 +7. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md`，填充 `modules[]`（含 `id` / `name` / `deps` / `tables`）/ `req_order[]`（每项含 `index` / `req_id` / `module_id` / `rationale` / `note`）/ `notes`。 +8. 写入 `docs/02-开发计划.md`。 + +### B. docs/05 — API 接口契约 + +1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md`，写入 `docs/05-API接口契约.md` 头部。 +2. 对所有模块的每个 REQ：用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md`，推断 method / path / auth / permission / 请求和响应 schema（不明确的询问用户），追加到 docs/05。 + +### B2. 回填 REQ 卡片 依赖接口 + +1. 用 `Glob` 列出 `docs/01-需求清单/*.md`（排除 `README.md`）。 +2. 用 `Grep` 在这些文件中搜索 `TBD(A5 自动补)` 的行号（不读全文）。 +3. 对每个命中的 REQ： + - 用 `Read` 仅读取该 REQ 卡片所在的片段（REQ 标题行前后 20 行），提取 `req_id`。 + - 在步骤 B 刚生成的 `docs/05-API接口契约.md` 里 Grep 属于该 REQ 的 endpoint（通过 REQ 标签或 req_id 关联）。 + - 用 `Edit`：`依赖接口: TBD(A5 自动补)` → `依赖接口: POST /api/xxx, GET /api/yyy`（具体 method + path 列表，多个用 `,` 分隔）。 +4. 打印回填统计：`A5 回填 N 处 api_refs`。 + +### C. docs/06 — 页面清单 + +1. 对每个有前端页面的模块：用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md`，填充 `pages[]`（page_name、route、page_type、req_ids、menu_path、interactions）。 +2. 将每个渲染块追加到 `docs/06-UI交互规范.md` § 五。 + +### D. docs/08 § 二 — 追加模块清单 + +docs/08 已由 A0 erp-project-init 创建（含 Plan 进度骨架）。本步骤只往 § 二 追加模块行，**不重写整个文件**。 + +1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`（单模块 bullet 行模板）。 +2. **按 `module_id` 字母序**对每个模块：渲染一行 bullet（`- ` 开头，无 checkbox），填充 `module_id` / `module_name` / `depends_on` / `path_scopes`（不含 REQ 列表——REQ 级顺序由 docs/02 § 二 权威维护；模块完成信号由 `MR:` 字段 + `glab mr view state` 判定）。 + + > 注意：docs/08 § 二 的行序**不决定分发顺序**——分发权威在 docs/02 § 二 REQ 开发顺序清单。本步骤按字母序排只是便于人类肉眼查找。 +3. 所有模块行拼成一段文本，用 `Edit` 在 `docs/08-模块任务管理.md` 的 `## 二、Coding 阶段（按模块循环）` 标题后插入（定位用下一行注释"（A5 填入后..."作为锚，把模块清单插到该注释之前）。 + +### E. docs/10 — 验收清单 + +1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md`，写入 `docs/10-验收检查清单.md` 头部。 +2. 对每个模块：用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-10-module-template.md`，填充 `reqs[]`、`data_checks[]`、`ui_checks[]`，追加。 + +### F. 验证 + 勾选 docs/08 进度 + 终止 Plan 阶段 + +1. 一致性检查： + - docs/01 的每个 REQ 都出现在 docs/05（作为接口，如适用）、docs/10（作为验收项）。 + - `docs/02 § 二` 开发顺序清单的 `module_id` 集合 = `docs/08 § 二` 的 `module_id` 集合（数量、ID 全等）；不相等 → 报错停下，列出差集。 + +2. **最终占位符扫描**（覆盖 Plan 阶段全部产出：`docs/01-需求清单/*.md` + `docs/02` / `docs/05` / `docs/06` / `docs/10` + `sql/seed-data.sql`）： + + a. **`TBD` → CC 自动补齐**：`Grep` 搜 `TBD(A4 自动补)` 和 `TBD(A5 自动补)`。有命中则按 A4 / B2 同样逻辑就地补填（A4 查 docs/03 填 `依赖表:`；A5 查 docs/05 按 REQ-ID 填 `依赖接口:`），再 Grep 确认 0 命中；仍残留报错停下。 + + b. **`【人工填写：...】` → QA 循环等用户补**（与 A2 erp-skeleton-gen 步骤 E 同风格）： + + 循环执行直到两个条件**同时满足**：(1) 扫描 0 命中；(2) 用户选「继续」 + + - **b.1 扫描**：用 `Grep` 在上述所有文件中搜 `【人工填写：`，得命中数 N 和残留位置清单（`<文件:行号> — <行内容摘要>`） + - **b.2 打印汇总横幅**： + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-downstream-gen] 最终占位符审阅 + + <N=0 时打印：✅ 全部填完> + <N>0 时打印：⚠️ 还有 N 处待填： + <文件:行号> — <行内容摘要> + ...> + + 需要调整 → 直接编辑对应文件 + 填完后 → 回来选「继续」放行完成 Plan + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + - **b.3 弹 QA**：用 `AskUserQuestion` 询问： + - **question**: `最终占位符补填完毕？` + - **options** (每项为对象)： + - `{"label": "继续", "description": "放行完成 Plan 阶段"}` + - `{"label": "有疑问想先沟通", "description": "需要讨论或修改"}` + - **b.4 路由**： + - 选「有疑问想先沟通」→ 回答用户问题后**回 b.1 重扫** + - 选「继续」→ **回 b.1 重扫验证**： + - 新 N = 0 → 进步骤 3 + - 新 N > 0 → 用户以为填完其实还有残留，回 b.2 打印新横幅 + 再弹 QA + + 关键：**每次弹 QA 前都重扫一次**，用户看到的 N 始终是最新的；只有 N = 0 且选「继续」才放行。 + +3. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 7 个 checkbox（A5 的 6 个子项 + A5 父项）： + - ` - [ ] docs/02 开发计划已生成` → `[x]` + - ` - [ ] docs/05 API 契约已生成` → `[x]` + - ` - [ ] docs/06 § 五 页面清单已填入` → `[x]` + - ` - [ ] docs/10 验收清单已生成` → `[x]` + - ` - [ ] 下方模块列表已填入` → `[x]` + - ` - [ ] REQ 卡片依赖接口已回填` → `[x]` + - `- [ ] A5 下游文档生成 — erp-downstream-gen` → `[x]` + +4. 输出：`downstream-gen: 写入 4 个文件 + <N> 个模块 + <M> 处 REQ 依赖接口回填。` + +5. 打印 Plan 阶段终止横幅并**停下**（不自动进入 B 阶段）： + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-downstream-gen] ✅ Plan 阶段（A0~A5）全部完成 + + 所有规划文档已就绪，docs/08 § 一 全部勾选。 + + 下一步由你显式触发： + 运行 /erp-workflow:erp-coding-start 进入 B 阶段模块循环 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + +## 参考 + +- `${CLAUDE_SKILL_DIR}/templates/docs-02-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-05-header-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-05-endpoint-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-06-module-pagelist-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-08-module-row-template.md`（模块 bullet 行模板） +- `${CLAUDE_SKILL_DIR}/templates/docs-10-header-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-10-module-template.md` diff --git a/skills/plan/erp-downstream-gen/templates/docs-02-template.md b/skills/plan/erp-downstream-gen/templates/docs-02-template.md new file mode 100644 index 0000000..4f66854 --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-02-template.md @@ -0,0 +1,24 @@ +# 02-开发计划 + +## 一、模块依赖表 + +| 模块 ID | 模块名 | 依赖模块 | 依赖表 | +|---|---|---|---| +{{#each modules}} +| {{id}} | {{name}} | {{deps}} | {{tables}} | +{{/each}} + +## 二、开发顺序清单（CC 分发权威） + +> 本清单由 A5 `erp-downstream-gen` 一次性生成。**每行是一个 REQ（功能）**，不是模块。CC 按表格行序从上到下扫描，对每个 REQ 所属模块查 `docs/08 § 二` 的 `MR:` 字段 + `glab mr view state`：`merged` 跳过，其他（`—` / opened / closed / 查不到）选为当前模块（`erp-module-start` 会一次性把该模块在本清单里所有 REQ 做完）。`docs/08 § 二` 每模块是 bullet（无 checkbox），完成由 MR state 判定。 +> +> **约束**：同一模块的所有 REQ 必须**连续排列**。允许打破依赖拓扑（如环依赖、业务必须先做），但必须在「备注」列写明原因。 + +| # | REQ | 所属模块 | 选中理由 | 备注 | +|---|-----|---------|---------|------| +{{#each req_order}} +| {{index}} | **{{req_id}}** | {{module_id}} | {{rationale}} | {{note}} | +{{/each}} + +## 三、关键说明 +{{notes}} diff --git a/skills/plan/erp-downstream-gen/templates/docs-05-endpoint-template.md b/skills/plan/erp-downstream-gen/templates/docs-05-endpoint-template.md new file mode 100644 index 0000000..1583d4e --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-05-endpoint-template.md @@ -0,0 +1,24 @@ +### {{req_id}} {{title}} + +- **Method**: {{method}} +- **Path**: `{{path}}` +- **Auth**: {{auth}} +- **Permission**: {{permission}} + +#### 请求参数 +{{request_params}} + +#### 请求体 +```json +{{request_body_schema}} +``` + +#### 响应体 +```json +{{response_body_schema}} +``` + +#### 错误码 +{{#each errors}} +- `{{code}}` — {{message}} +{{/each}} diff --git a/skills/plan/erp-downstream-gen/templates/docs-05-header-template.md b/skills/plan/erp-downstream-gen/templates/docs-05-header-template.md new file mode 100644 index 0000000..6bcd293 --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-05-header-template.md @@ -0,0 +1,30 @@ +# 05-API接口契约 + +BasePath: `{{base_path}}` +端口: `【人工填写：后端端口，默认 8080】` + +## 全局约定 + +### 响应格式 +```json +{"code": 200, "message": "操作成功", "data": {}, "timestamp": 1700000000000} +``` + +### 错误码 +| 范围 | 含义 | +|---|---| +| 200 | 成功 | +| 400xx | 客户端参数错误 | +| 401xx | 认证/授权错误 | +| 403xx | 权限不足 | +| 404xx | 资源不存在 | +| 500xx | 服务端内部错误 | + +### 鉴权 +{{auth_note}} + +### 分页参数 +{{pagination_note}} + +## 接口清单 +（各模块接口段落见下方，由 `erp-downstream-gen` 按 REQ 填入） diff --git a/skills/plan/erp-downstream-gen/templates/docs-06-module-pagelist-template.md b/skills/plan/erp-downstream-gen/templates/docs-06-module-pagelist-template.md new file mode 100644 index 0000000..36f18a5 --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-06-module-pagelist-template.md @@ -0,0 +1,9 @@ +### {{module_id}} {{module_name}} + +{{#each pages}} +- **{{page_name}}** (`{{route}}`) + - 类型: {{page_type}} （列表页 / 表单页 / 详情页 / 树形管理页） + - 对应 REQ: {{req_ids}} + - 入口菜单: {{menu_path}} + - 主要交互: {{interactions}} +{{/each}} diff --git a/skills/plan/erp-downstream-gen/templates/docs-08-module-row-template.md b/skills/plan/erp-downstream-gen/templates/docs-08-module-row-template.md new file mode 100644 index 0000000..76cf552 --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-08-module-row-template.md @@ -0,0 +1,4 @@ +- {{module_id}} {{module_name}} + - 依赖: {{depends_on}} + - 路径: {{path_scopes}} + - MR: — diff --git a/skills/plan/erp-downstream-gen/templates/docs-10-header-template.md b/skills/plan/erp-downstream-gen/templates/docs-10-header-template.md new file mode 100644 index 0000000..0587a54 --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-10-header-template.md @@ -0,0 +1,14 @@ +# 10-验收检查清单 + +通用验收项（全项目适用）: + +- [ ] `scripts/test.sh` 本地全绿 +- [ ] 所有 schema 改动都有对应 `sql/migrations/V_n__<desc>.sql` +- [ ] 所有新接口在 `docs/05` 中有契约定义 +- [ ] 所有新功能代码注释含 REQ-XXX-NNN +- [ ] 统一响应格式 `{code, message, data, timestamp}` +- [ ] 异常走全局处理器，不暴露堆栈到前端 +- [ ] 前端不存敏感信息到 localStorage + +## 模块专项 +（各模块验收段落见下方，由 `erp-downstream-gen` 按模块填入） diff --git a/skills/plan/erp-downstream-gen/templates/docs-10-module-template.md b/skills/plan/erp-downstream-gen/templates/docs-10-module-template.md new file mode 100644 index 0000000..9342e2e --- /dev/null +++ b/skills/plan/erp-downstream-gen/templates/docs-10-module-template.md @@ -0,0 +1,18 @@ +### {{module_id}} {{module_name}} + +#### 功能级验收（每个 REQ 对应可执行用例） +{{#each reqs}} +- [ ] {{req_id}} {{title}} + - 自动化用例: `{{test_file}}::{{test_name}}` + - 手动验收: {{manual_check}} +{{/each}} + +#### 数据级验收 +{{#each data_checks}} +- [ ] {{check}} +{{/each}} + +#### UI 级验收（若含前端） +{{#each ui_checks}} +- [ ] {{check}} +{{/each}} diff --git a/skills/plan/erp-project-init/SKILL.md b/skills/plan/erp-project-init/SKILL.md new file mode 100644 index 0000000..8dfd4fb --- /dev/null +++ b/skills/plan/erp-project-init/SKILL.md @@ -0,0 +1,94 @@ +--- +name: erp-project-init +description: A0 项目初始化——从插件模板幂等地复制 CLAUDE.md / docs/01-需求清单/README.md / docs/08-模块任务管理.md（已存在则跳过），并初始化 Git（如未初始化）。session-start 在 docs/08 缺失时派发本 skill。 +user-invocable: false +allowed-tools: Glob Edit Skill Bash(mkdir *) Bash(cp -n *) Bash(git init) Bash(command -v *) Bash(uname *) Bash(brew *) Bash(export PATH=*) Bash(echo *) +--- + +**所有输出必须使用中文。** + +你负责在空/半空项目目录中创建初始文件结构。**本 skill 幂等**——已存在的文件不覆盖。 + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A0）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ ▶ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → A3 初始化 DB → A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. 依赖检查 + 自动安装（命令行工具） + +用 `Bash` 检查 `mysql` / `mysqldump` 是否在 PATH 中： + +```bash +for cmd in mysql mysqldump; do + command -v "$cmd" >/dev/null 2>&1 || echo "MISSING: $cmd" +done +``` + +**全部在 PATH** → 进入 B。 + +**有缺失** → 尝试自动安装： +1. 用 `Bash` 探测环境（`uname -s`、是否有 `brew` / `apt` / `yum` / `apk` 等） +2. 根据当前系统选最合适的包管理器安装 mysql 客户端；若需要 sudo 但 CC 没有权限，打印手动安装命令让用户执行 +3. 装完后，把必要的 bin 路径加入本次会话 PATH（如 macOS 的 keg-only 路径） +4. 向用户提示如何把路径永久写入 shell 启动脚本 +5. 重新跑开头的 `command -v` 循环验证；仍缺失 → 打印错误并停下，等用户手动解决后重跑入口 + +### B. 幂等复制模板文件 + +用 `Bash` 一次性完成。`cp -n` 表示"不覆盖已存在的文件"： + +```bash +mkdir -p docs/01-需求清单 +cp -n "${CLAUDE_SKILL_DIR}/templates/CLAUDE-template.md" CLAUDE.md +cp -n "${CLAUDE_SKILL_DIR}/templates/docs-01-readme-template.md" docs/01-需求清单/README.md +cp -n "${CLAUDE_SKILL_DIR}/templates/docs-08-initial-template.md" docs/08-模块任务管理.md +``` + +故障恢复场景：如果用户之前 init 跑一半中断（CLAUDE.md 已存在但 docs/08 缺失），`cp -n` 会保留 CLAUDE.md 原样，只补齐 docs/08。 + +### C. 初始化 Git（如尚未初始化） + +用 `Glob` 检查 `.git/` 目录是否存在。 +- 不存在 → 用 `Bash` 执行 `git init`。 +- 已存在 → 跳过。 + +### D. 勾选 docs/08 的 A0 进度 + +用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选这两行： +- ` - [ ] 项目文件骨架已创建（CLAUDE.md + docs/01-需求清单/README.md）` → ` - [x] 项目文件骨架已创建（CLAUDE.md + docs/01-需求清单/README.md）` +- `- [ ] A0 项目初始化 — erp-project-init` → `- [x] A0 项目初始化 — erp-project-init` + +### E. 打印完成横幅并进入 A1 + +向用户输出： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-project-init] 项目初始化完成 + + 已创建： + ✓ CLAUDE.md（从插件模板复制） + ✓ docs/01-需求清单/README.md（待人工填写模块索引） + ✓ docs/08-模块任务管理.md（全流程进度跟踪） + 已勾选：A0 项目初始化 + + 下一步：A1 erp-scope-lock（填写项目概述 + 技术栈 + 需求索引 + REQ 卡片） +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +立即调用 `Skill(erp-scope-lock)` 进入 A1，不等用户手动输入。 diff --git a/skills/plan/erp-project-init/templates/CLAUDE-template.md b/skills/plan/erp-project-init/templates/CLAUDE-template.md new file mode 100644 index 0000000..7be104a --- /dev/null +++ b/skills/plan/erp-project-init/templates/CLAUDE-template.md @@ -0,0 +1,336 @@ +# CLAUDE.md — ERP项目 Claude Code 主指令文件 + +> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。 + +--- + +## 🎯 项目概述 + +- **项目名称**: 【人工填写：公司 + 项目名，例如"XX 公司 ERP 管理系统"】 +- **项目简述**: 【人工填写：一句话描述项目目标，例如"面向中小制造企业的全流程 ERP，涵盖采购/库存/生产/销售/财务"】 +- **目标用户**: 【人工填写：谁会用，例如"企业内部管理人员（采购员、仓管员、生产主管、销售员、财务人员、管理层）"】 +- **部署方式**: 【人工填写：私有化部署 / 云部署 / Docker 容器化 等】 + +--- + +## ✅ 模块完成判定规则 + +`docs/08-模块任务管理.md § 二` 是**模块元数据表**——每个模块一行 bullet（无 checkbox），记录依赖 / 路径 / MR iid。**模块完成由 `MR:` 字段 + `glab mr view state=merged` 判定**，不用 checkbox 表达进度。 + +### 规则定义 + +每个模块在 docs/08 § 二 中长这样： + +```markdown +- module_0 系统管理 + - 依赖: — + - 路径: backend/module/sys/, frontend/pages/sys/ + - MR: — +``` + +`MR:` 字段由 `erp-mr-create` 在创建 MR 时从 `—` 改为 `!<iid>`。 + +### 模块状态语义 + +| `MR:` 字段 | `glab mr view state` | 含义 | 你（Claude Code）的行为 | +|---|---|---|---| +| `—` | — | 模块未开始（未建 MR） | ✅ 开始本模块开发 | +| `!<iid>` | `opened` / `closed` | 模块开发中 / 打回 | ✅ 继续推进该模块 | +| `!<iid>` | `merged` | 模块**已完成** | 🟢 进入下一未完成模块 | + +### 工作流规则 + +- **开发顺序权威在 `docs/02-开发计划.md § 二 开发顺序清单`**，不是 `docs/08 § 二` 的物理行序 +- **下一个要做的模块** = `docs/02 § 二` 清单中**第一个所属模块 MR 状态非 merged 的 REQ** 的 `module_id`（由 `erp-coding-start` 步骤 3 扫 `docs/08` 的 `MR:` 字段 + `glab mr view` 判定） +- `docs/02 § 二` 清单由 A5 `erp-downstream-gen` 生成阶段一次性确定（会交互询问业务偏好），之后通常不改；若开发中途需要调整顺序，重新触发 A5 生成阶段而非直接编辑文件 +- **已完成模块**（`MR: !<iid>` + `glab mr view state=merged`）：**默认不改**（不是禁止，是已交付无需改） +- 如果在当前模块开发中发现某个**已完成模块**（MR merged）有 bug： + - **不停下当前工作**，按软规则 S2 直接修复该模块代码；hook `log-cross-module.sh` 会自动留痕，调用 `erp-cross-module-log` 补「原因 / 影响评估」 + - 修复随当前模块 MR 一起合并——不需要改 `docs/08`（模块已是 merged 状态，本插件不会标记重开；修复是以"当前模块依赖他的代码"的方式进入） + - 在当前模块的《模块完成报告》第 ⑦ 节「跨模块改动」明确记录：哪个模块、哪个文件、什么问题、修复范围、影响评估 + +### 模块完成流程 + +``` +1. 对每个 REQ 跑完整功能循环： + brainstorm → plan → TDD（红绿循环，每步 commit）→ verify（子会话跑 REQ 级测试）→ 自审 +2. 所有 REQ 完成后，erp-local-test-gate 派子会话按顺序跑： + a. schema 一致性检查（erp-local-test-gate 步骤 1 内联，schema 未漂移）+ 占位符扫描 + b. scripts/test.sh 全套：build → lint → **unit + integration（全量重跑当前模块所有 + REQ 的功能测试 + 所有已勾模块的回归测试）** → e2e + 任一失败停下修复再来 +3. 测试全绿 → erp-module-report 输出《模块完成报告》 +4. 自动 git push（.githooks/pre-push 会再跑一遍 scripts/test.sh 作为硬闸门） + + glab mr create，报告嵌入 MR 描述 +5. 人工 review MR → Approve + Merge（人工动作，唯一人工介入点） +6. 下次用户跑 `/erp-workflow:erp-coding-start` 时，入口自动检测到本模块 `glab mr view state=merged` → `git checkout main && git pull --ff-only` 同步远程 → 扫下一模块派发 +7. 你**不需要**手工 Edit docs/08（模块元数据不变；下次 coding-start 自动扫 MR state 判完成） +``` + +> 两道测试闸门：功能级（`erp-feature-tdd` + `erp-feature-verify`，每 REQ 一遍）+ 模块级（`erp-local-test-gate` + pre-push hook，每模块一遍）。所有测试/验证都派到子会话跑，主会话只收结构化结论。 + +### 模块完成报告 + +由 `erp-module-report` skill 产出，模板位于 由 erp-module-report skill 持有（12 节标准化，含跨模块改动等 CLAUDE.md 软规则映射节）。CC 不手写模块报告，仅填模板。 + +--- + +## 🏷️ 占位符统一约定（`【人工填写：...】`） + +所有"只有人工能决定"的位置（密钥 / 账密 / 包名 / 命名约定 / 小版本号 等）一律使用以下纯文本标记： + +``` +【人工填写：<简短说明>】 +``` + +### CC 行为规则 + +- **生成文档 / 模板时**：凡是项目专属值、敏感值、技术栈小版本号一律用此标记，不要自行编造 +- **不要用 HTML 注释**（`<!-- ... -->`），因为后者在 Obsidian 渲染视图被隐藏，开发者会漏填 +- **必须带简短说明**：例如 `【人工填写：JWT 签名密钥，256+ bit 随机串】`，而不是空 `【人工填写】` +- **项目专属标识**（Java 根包名 / C# 命名空间 / Python 顶层模块等）只在 `docs/07-环境配置.md` 引入一次占位，其他文件**复用**已有的占位，不重复创建 + +--- + +## 🔄 开发流程（模块循环 + 功能循环） + +两层嵌套循环的详细步骤**全部固化到 skills**，CLAUDE.md 不展开。入口调 `/erp-workflow:erp-coding-start`，自动分发： + +- **模块循环（外层，Layer 2）** → `erp-module-start` → `erp-local-test-gate`（commit test-gate.md）→ `erp-module-report`（commit 模块报告 + cross-module log）→ `erp-mr-create`（worktree clean 校验 → push → 建 MR → 追 MR URL 到报告 + commit → 写 `MR: !<iid>` 到 docs/08 + commit → 再 push）→ 人工 Approve+Merge → 下次 `/erp-workflow:erp-coding-start` 扫到本模块 `glab mr view merged` → `git pull --ff-only main` → 推进下一模块 +- **功能循环（内层，Layer 3，每个 REQ-XXX-NNN 走一遍）** → `erp-feature-brainstorm` → `erp-feature-plan` → `erp-feature-tdd` → `erp-feature-verify` → `erp-feature-review` + +**本地测试闸门**: `erp-local-test-gate` 是 MR 前的唯一硬闸门，子会话跑 `scripts/test.sh`：脚本先让 `setup-test-db.sh` 清空库 → build / lint → 跑测试（Spring Boot 启动时 Flyway 自动 apply `sql/migrations/V*.sql`）→ e2e → 再次清库。详见 § 🧪 自测要求。`.githooks/pre-push` 在 push 时会再跑一次 `scripts/test.sh` 作为兜底；`git push --no-verify` 被 hook `deny-no-verify.sh` 硬拦截。本项目不配置 GitLab CI/CD。 + +> 占位符扫描 / schema 一致性校验都不在此闸门：前者在 A 阶段 skill 生成期完成；schema 演化通过 Flyway migration 保证一致（每次测试启动，Spring Boot 的 Flyway 从空库按序 apply V1~Vn，不存在"漂移"概念）。hook 产生的 `TBD(CC 补)` 存根由 CC 自主调 `erp-cross-module-log` 补齐，并在 `erp-module-report` § ⑦ 硬验收（非人工填写）。 + +--- + +## 📐 编码行为约束 + +### 你必须做的 ✅ + +1. **严格遵循** `docs/04-技术规范.md` 中的命名和编码规范 +2. **严格遵循** `docs/09-项目目录结构.md` 中的目录规范，文件放对位置 +3. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 中定义，再编码实现 +4. **每个功能** 必须可追溯到 `docs/01-需求清单.md` 中的需求编号 +5. **代码注释** 必须包含对应的需求编号，如 `// REQ-001: 用户登录` +6. **数据库 schema 走 migration**：所有业务 schema 改动（CREATE/ALTER/DROP TABLE/INDEX/VIEW）必须写成 `sql/migrations/V_n__<snake_case_desc>.sql` 文件，由 Flyway 顺序 apply；**禁止**在主会话直接 `mysql -e` 跑业务 DDL（只读查询 / 临时本地调试探索除外）。详见 § Schema 演化规约 +7. **提交代码前** 确保无编译错误、无明显运行时错误 +8. **每个Controller方法** 必须有统一的响应格式包装 +9. **异常处理** 使用全局异常处理器，不在业务代码中catch后吞掉异常 +10. **分页查询** 统一使用 MyBatis-Plus 的 Page 对象 + +### 你禁止做的 🚫 + +1. **默认禁止** 修改"非当前模块"（其他 REQ 所属模块）的代码；确为实现当前模块所必需时，按软规则 S2 执行（留痕 + 模块报告单列说明） +2. **禁止** 引入`docs/04-技术规范.md` 技术栈表以外的框架或中间件（如需要必须先报告） +3. **禁止** 硬编码配置（数据库连接、端口号等必须放在配置文件中） +4. **禁止** 在前端直接写SQL或直接操作数据库 +5. **禁止** 跳过模块开发（必须按顺序） +6. **禁止** 删除或覆盖他人代码（如有冲突必须报告） +7. **禁止** 使用 `SELECT *`，必须显式列出需要的字段 +8. **禁止** 在循环中执行数据库查询（N+1问题） +9. **禁止** 前端存储敏感信息到 localStorage +10. **禁止** 返回后端异常堆栈给前端 + +### Schema 演化规约（Flyway migration） + +1. **文件命名**：`sql/migrations/V<n>__<snake_case_desc>.sql`，例：`V5__add_user_email_unique_index.sql` +2. **版本号分配**：建文件前 `ls sql/migrations/V*.sql` 查当前最大 n，新文件 `n_max + 1` +3. **Apply 方式**：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖）。`scripts/setup-test-db.sh` 只负责清空库，不做 apply +4. **已合并的 migration 永不修改**：发现错了写一个补救 migration（如 `V7__fix_V5_index_name.sql`），绝不编辑 git 历史里的旧 `V_n.sql` +5. **临时调试 DDL ≠ 业务 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.sh` 会 drop+create 清掉 +6. **A3 生成的 V1**：`V1__initial_schema.sql` 是 A 阶段由 `erp-db-init` 从人工初始化的 schema 导出的初始版本；后续 V2/V3/... 由 B 阶段每个 REQ 按需写入 + +--- + +## 🔄 统一响应格式 + +所有后端接口必须返回以下格式： + +```json +{ + "code": 200, + "message": "操作成功", + "data": {}, + "timestamp": 1700000000000 +} +``` + +错误响应： + +```json +{ + "code": 40001, + "message": "用户名或密码错误", + "data": null, + "timestamp": 1700000000000 +} +``` + +错误码规范： + +| 错误码范围 | 含义 | +|-----------|------| +| 200 | 成功 | +| 400xx | 客户端参数错误 | +| 401xx | 认证/授权错误 | +| 403xx | 权限不足 | +| 404xx | 资源不存在 | +| 500xx | 服务端内部错误 | + +--- + +## 🗂️ Git 提交规范 + +每次提交必须遵循以下格式： + +``` +<type>(<scope>): <subject> + +type: feat|fix|refactor|docs|style|test|chore +scope: 模块名，如 user, inventory, order +subject: 简短描述，中文可 + +示例： +feat(user): 实现用户登录接口 REQ-001 +fix(order): 修复订单金额计算精度问题 +refactor(common): 统一响应格式包装 +``` + +--- + +## 🧪 自测要求 + +- 所有测试与验证（`scripts/test.sh` / `mvn test` / `pnpm test` / DB 测试集 diff 等）**一律派发到全新子会话 via `Agent` 执行**，主会话只接收结构化结论（命令 / 退出码 / 通过数 / 失败项 / 关键 stdout ≤30 行）。不在主会话直跑测试。 +- 由 `erp-feature-verify`（功能级）+ `erp-local-test-gate`（模块级）两道 skill 统一承接。前者每个 REQ 跑一次，后者模块闸门跑一次。 +- 声称"完成"前必须贴出子会话返回的 evidence（模板：由 erp-feature-verify skill 持有）。 + +--- + +## 🚩 静默执行红旗清单（中断机制） + +功能循环（每个功能 REQ-XXX 的 Brainstorm → Plan → TDD → Verify → AI 自审）默认 **静默跑不打扰人**，但命中以下任何一条必须**立刻停下、记录原因、等人决策**，不得自行绕过： + +| # | 红旗 | 例子 | +| - | --- | --- | +| 1 | **需求与 schema 不一致** | REQ 提到的字段/表在现有 schema 里不存在 → 先向用户确认「加一个 migration 新增 / 修正 REQ 理解」；得到答复后继续，**不走下方 Blocker 文件流程** | +| 2 | **需求本身歧义** | spec 中某规则有两种合理解读，CC 无法判断 | +| 3 | **超技术栈边界** | 需要引入 `docs/tech-stack.md` 以外的框架 / 中间件 | +| 4 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 | +| 5 | **要改密钥 / 账密 / 包名** | `docs/07-环境配置.md` 里由人工标注必须填的字段 | +| 6 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题 | + +**命中红旗时的固定动作：** + +1. 在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`，描述红旗编号、现象、初步判断 +2. 停止后续所有功能的静默执行 +3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复 + +**报告格式：** + +```markdown +## ⚠️ 需要人工决策 + +**红旗编号**: [1–6 中的某一条] +**问题描述**: [详细描述] +**影响范围**: [影响哪些模块 / 功能] +**我的建议**: [初步判断，可选] +**等待决策**: [需要人工做什么决定] +``` + +--- + +## 🟡 软规则（允许继续，但有强制后续动作） + +以下情况 **不触发中断**，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。漏留痕 = 红旗。 + +| # | 软规则 | 允许动作 | 强制后续 | +| - | ----- | ------- | ------- | +| S2 | **跨模块改动**（动到非当前模块的代码——无论该模块是否已 MR merged） | 允许修改，但范围受限：仅为当前模块实现所必需 | ① 当次修改立即追加到 `docs/superpowers/module-reports/<current>-cross-module.md`（含文件路径、改动原因、对目标模块功能/API 的影响评估）② 《模块完成报告》必须单列「跨模块改动」节完整贴入 ③ 漏留痕或未评估影响 → 升级为红旗 | + +--- + +## 🧭 通用工作准则（General Principles） + +### 1. Think Before Coding + +**Don't assume. Don't hide confusion. Surface tradeoffs.** + +Before implementing: +- State your assumptions explicitly. If uncertain, ask. +- If multiple interpretations exist, present them - don't pick silently. +- If a simpler approach exists, say so. Push back when warranted. +- If something is unclear, stop. Name what's confusing. Ask. + +### 2. Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- No features beyond what was asked. +- No abstractions for single-use code. +- No "flexibility" or "configurability" that wasn't requested. +- No error handling for impossible scenarios. +- If you write 200 lines and it could be 50, rewrite it. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +### 3. Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +When editing existing code: +- Don't "improve" adjacent code, comments, or formatting. +- Don't refactor things that aren't broken. +- Match existing style, even if you'd do it differently. +- If you notice unrelated dead code, mention it - don't delete it. + +When your changes create orphans: +- Remove imports/variables/functions that YOUR changes made unused. +- Don't remove pre-existing dead code unless asked. + +The test: Every changed line should trace directly to the user's request. + +### 4. Goal-Driven Execution + +**Define success criteria. Loop until verified.** + +Transform tasks into verifiable goals: +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +For multi-step tasks, state a brief plan: +``` +1. [Step] → verify: [check] +2. [Step] → verify: [check] +3. [Step] → verify: [check] +``` + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +--- + +## ⚡ Skill & 模板入口索引 + +CC 会话启动请直接调 **`/erp-plan-start`** —— 顶层编排器会自动探测当前阶段（计划 / 模块循环 / 功能循环 / blocker）并分发到下一个 skill。 + +### Skills（20 个，详细动作见各 `SKILL.md` 正文） + +| Layer | Skill | +|---|---| +| **0 入口** | `erp-plan-start` / `erp-project-init` | +| **1 计划阶段** | `erp-scope-lock` / `erp-skeleton-gen` / `erp-db-init` / `erp-db-design-gen` / `erp-downstream-gen` | +| **2 模块循环（外）** | `erp-module-start` / `erp-local-test-gate` / `erp-module-report` / `erp-mr-create` | +| **3 功能循环（内）** | `erp-feature-brainstorm` / `erp-feature-plan` / `erp-feature-tdd` / `erp-feature-verify` / `erp-feature-review` | +| **4 横切守门** | `erp-red-flag-check` / `erp-cross-module-log`（软规则 S2） | + +### Hooks（3 个，由插件 `hooks/hooks.json` + `hooks/scripts/*.sh` 提供） + +- `deny-no-verify.sh` — 拒 `git push --no-verify` +- `log-cross-module.sh` — 跨模块改动自动留痕（S2） + +### 模板（分散在各 skill 的 插件 `skills/erp-*/templates/*`） + +每个生成文件都对应一个模板（设计原则 #5）。模板保持纯净（原则 #6），帮助文本由 skill 通过 `AskUserQuestion` 交互引导。模板按"谁用谁拥有"原则分散到各自的 skill 目录下，便于打包成 plugin。一份共享模板（`cross-module-log-template.md`）在 `erp-module-start` 与 `erp-cross-module-log` 中各有一份副本。 + diff --git a/skills/plan/erp-project-init/templates/docs-01-readme-template.md b/skills/plan/erp-project-init/templates/docs-01-readme-template.md new file mode 100644 index 0000000..ed09a21 --- /dev/null +++ b/skills/plan/erp-project-init/templates/docs-01-readme-template.md @@ -0,0 +1,16 @@ +# 需求清单 + +> 本目录按模块组织所有功能需求。每个模块一个文件，由 CC 基于下方纲要扩展成 REQ-XXX-NNN 标准卡片。 + +## 模块索引 + +| 模块代码 | 模块名称 | 核心功能点（简要） | +|----------|----------|--------------------| +| SYS | 系统管理 | 【人工填写：用户/角色/权限/部门/字典 等】 | +| 【人工填写：模块代码】 | 【人工填写：模块名称】 | 【人工填写：核心功能点】 | + +## 填写说明 + +1. 每个模块占一行，`模块代码` 用大写英文缩写（如 SYS / PUR / INV / SAL / FIN / HR） +2. `核心功能点` 只需列关键词，CC 会基于此扩展成完整 REQ 卡片 +3. 填完后运行 `/erp-workflow:erp-plan-start`，CC 会自动检测并进入需求生成阶段 diff --git a/skills/plan/erp-project-init/templates/docs-08-initial-template.md b/skills/plan/erp-project-init/templates/docs-08-initial-template.md new file mode 100644 index 0000000..3b9a069 --- /dev/null +++ b/skills/plan/erp-project-init/templates/docs-08-initial-template.md @@ -0,0 +1,51 @@ +# 08-工作流进度 + +> 全流程进度跟踪。CC 每完成一项产出就勾选一项。 +> - **§ 一 Plan（A0~A5）**：`erp-plan-start` 找第一个未勾 A 子项分发到对应 skill +> - **§ 二 Coding（模块）**：分发权威在 `docs/02-开发计划.md § 二 开发顺序清单`；`erp-coding-start` 按 docs/02 顺序扫，对每个 REQ 所属模块查本 § 二的 `MR:` 字段 + `glab mr view state`，找第一个非 merged 模块分发。本 § 二每模块是纯 bullet（无 checkbox），§ 二行序无语义 + +## 一、Plan 阶段（一次性） + +- [ ] A0 项目初始化 — erp-project-init + - [ ] 项目文件骨架已创建（CLAUDE.md + docs/01-需求清单/README.md） + +- [ ] A1 范围锁定 — erp-scope-lock + - [ ] 项目概述已填写（CLAUDE.md § 🎯 项目概述） + - [ ] 技术栈已确认（docs/04 § 零） + - [ ] 需求清单索引已填写（docs/01-需求清单/README.md） + - [ ] REQ 卡片已生成（docs/01-需求清单/*.md，schema/api 字段标记为 TBD） + +- [ ] A2 骨架生成 — erp-skeleton-gen + - [ ] 架构文档已生成（docs/04 § 一+、docs/06、docs/07、docs/09） + - [ ] 工具脚本已生成（scripts/*.sh、.githooks/pre-push、.env.local） + - [ ] .gitignore 已配置 + +- [ ] A3 DB 初始化 — erp-db-init + - [ ] .env.local 凭据验证通过 + - [ ] MySQL 连接验证通过 + - [ ] V1 initial migration 已生成（sql/migrations/V1__initial_schema.sql，DDL only） + - [ ] sql/seed-data.sql 已导出（本地数据快照，INSERT only） + +- [ ] A4 DB 设计 + REQ 回填 — erp-db-design-gen + - [ ] docs/03 数据库设计已生成 + - [ ] REQ 卡片依赖表已回填 + - [ ] schema 一致性检查通过 + +- [ ] A5 下游文档生成 — erp-downstream-gen + - [ ] docs/02 开发计划已生成 + - [ ] docs/05 API 契约已生成 + - [ ] docs/06 § 五 页面清单已填入 + - [ ] docs/10 验收清单已生成 + - [ ] 下方模块列表已填入 + - [ ] REQ 卡片依赖接口已回填 + +## 二、Coding 阶段（按模块循环） + +（A5 填入后，每个模块一行 bullet（`- ` 开头，无 checkbox）。每个模块的 `MR:` 字段在 `—` 和 `!<iid>` 之间变化，完成由 `glab mr view state=merged` 判定。`erp-coding-start` 每次跑时按 docs/02 REQ 序扫描每模块的 MR state 决定派发。） + +<!-- 模块格式示例（由 A5 erp-downstream-gen 追加）： +- module_0 系统管理 + - 依赖: — + - 路径: backend/module/sys/, frontend/pages/sys/ + - MR: — +--> diff --git a/skills/plan/erp-scope-lock/SKILL.md b/skills/plan/erp-scope-lock/SKILL.md new file mode 100644 index 0000000..3913cf4 --- /dev/null +++ b/skills/plan/erp-scope-lock/SKILL.md @@ -0,0 +1,234 @@ +--- +name: erp-scope-lock +description: A1 计划范围锁定——引导用户填写项目概述 + 技术栈 + 需求索引，并自动扩展 REQ 卡片待人工评审。`schema_refs` 填 `TBD(A4 自动补)`（A4 回填依赖表），`api_refs` 填 `TBD(A5 自动补)`（A5 回填依赖接口）。 +user-invocable: false +allowed-tools: Read Write Edit Grep Skill AskUserQuestion +--- + +**所有输出必须使用中文。** + +# erp-scope-lock + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A1）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → ▶ A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ A2 生骨架 → A3 初始化 DB → A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. 提示用户填写项目概述并等待 + +向用户输出： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-scope-lock] 请填写项目概述 + + 📄 文件位置: ./CLAUDE.md + 📌 编辑位置: § 🎯 项目概述 + + 请将以下占位符替换为实际值： + - 项目名称 + - 项目简述 + - 目标用户 + - 部署方式 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问： +- **question**: `项目概述填写完毕了吗？` +- **options** (每项为对象)： + - `{"label": "继续", "description": "已完成检查"}` + - `{"label": "有疑问想先沟通", "description": "需要讨论或修改"}` + +- 用户选择「有疑问想先沟通」→ 回答用户问题后，再次弹出同样的 QA。 +- 用户选择「继续」→ 进入步骤 B。 + +### B. 保存默认技术栈到 docs/04 + +用 `Write` 将以下默认技术栈表写入 `docs/04-技术规范.md`： + +```markdown +# 04-技术规范 + +## 零、技术栈总览 + +| 分层模块 | 技术 | 版本要求 | 说明 | +|---|---|---|---| +| 前端基础框架 | React | 18.x | 构建前端应用 | +| 前端 UI 组件 | Ant Design | 5.x | 页面组件与交互控件 | +| 前端状态管理 | Redux Toolkit | 最新稳定版 | 管理全局状态 | +| 前端路由管理 | React Router | v6 | 页面路由与导航 | +| 前端工程化构建 | Vite | 最新稳定版 | 前端开发与打包构建 | +| 前端接口通信 | Axios | 最新稳定版 | 调用后端 API | +| 后端基础框架 | Spring Boot | 3.x | 构建后端服务 | +| 后端数据访问 | MyBatis-Plus | 最新稳定版 | 数据库访问与 ORM 增强 | +| 工作流引擎 | Activiti | 6.x | 审批流、流程流转 | +| 缓存服务 | Redis | 最新稳定版 | 缓存、会话、分布式能力 | +| 报表打印 | JXLS | 2.8.1 | 基于 Excel 模板生成报表 | +| Excel 导入导出 | EasyExcel | 4.0.3 | Excel 数据导入导出 | +| 关系型数据库 | MySQL | 8.x | 核心业务数据存储 | +| 数据库 schema 迁移 | Flyway (`flyway-core` + `flyway-mysql`) | 10.x / 最新稳定版 | `sql/migrations/V_n__*.sql` 顺序 apply；Spring Boot 启动时自动应用 | +| 接口风格 | RESTful API | 统一规范 | 前后端接口设计规范 | +| 权限认证 | Spring Security / JWT | 最新稳定版 | 登录认证、权限控制 | +| API 文档 | OpenAPI / Swagger | 最新稳定版 | 接口文档与调试 | +| 项目构建管理 | Maven | 3.9.x | Java 项目依赖与构建 | +| JDK 运行环境 | Java | 17 / 21 | Spring Boot 3 推荐版本 | +| 部署容器 | Docker | 最新稳定版 | 容器化部署 | +| Web 服务器 / 反向代理 | Nginx | 最新稳定版 | 前端托管、反向代理、负载分发 | +| 日志管理 | Logback | 默认集成 / 最新稳定版 | 应用日志输出 | +| 对象映射工具 | MapStruct | 最新稳定版 | DTO / VO / Entity 转换 | +| 工具类库 | Hutool / Apache Commons | 最新稳定版 | 常用工具方法支持 | + +> 本表由 erp-scope-lock 锁定。后续所有规范基于此表推导。 +``` + +### C. 提示用户检查并等待 + +向用户输出： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-scope-lock] 技术栈已保存 + + 📄 文件位置: ./docs/04-技术规范.md + 📌 编辑位置: § 零、技术栈总览 + + 请检查技术栈表： + - 不需要的行直接删除（如纯后端项目删前端行） + - 需要替换的技术直接改 + - 需要新增的条目直接加行 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问： +- **question**: `技术栈检查完毕了吗？` +- **options** (每项为对象)： + - `{"label": "继续", "description": "已完成检查"}` + - `{"label": "有疑问想先沟通", "description": "需要讨论或修改"}` + +- 用户选择「有疑问想先沟通」→ 回答用户问题后，再次弹出同样的 QA。 +- 用户选择「继续」→ 进入步骤 D。 + +### D. 提示用户填写需求清单并等待 + +`docs/01-需求清单/README.md` 已由 `erp-project-init` 写入占位符模板，这里让用户补齐模块清单。 + +向用户输出： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-scope-lock] 请填写需求清单模块索引 + + 📄 文件位置: ./docs/01-需求清单/README.md + 📌 编辑位置: § 模块索引（表格） + + 请按业务列出所有模块： + - 每行一个模块（如 SYS 系统管理 / PUR 采购 / SAL 销售） + - 「核心功能点」只需关键词，CC 会扩展为完整 REQ 卡片 + 改完后回来选择「继续」。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +用 `AskUserQuestion` 询问： +- **question**: `需求清单模块索引填写完毕了吗？` +- **options** (每项为对象)： + - `{"label": "继续", "description": "已完成检查"}` + - `{"label": "有疑问想先沟通", "description": "需要讨论或修改"}` + +- 用户选择「有疑问想先沟通」→ 回答用户问题后，再次弹出同样的 QA。 +- 用户选择「继续」→ 进入步骤 E。 + +### E. 生成 REQ 卡片并等用户审阅 + +先用 `Grep` 在 `docs/01-需求清单/README.md` 搜索 `【人工填写：`，命中 → 提示残留行，回到步骤 D。通过后： + +1. 用 `Read` 读取 `docs/01-需求清单/README.md`，解析模块索引表（每行：模块代码 / 模块名 / 核心功能点）。 +2. 用 `Read` 读取两份模板： + - `${CLAUDE_SKILL_DIR}/templates/req-card-template.md` + - `${CLAUDE_SKILL_DIR}/templates/docs-01-module-template.md` +3. 对每个模块： + - 基于「核心功能点」关键词，LLM 扩展为若干 REQ-XXX-NNN 卡片（编号按模块递增） + - 每张卡片填充字段： + - `goal` / `input` / `output` / `rules` / `constraints` / `acceptance` —— LLM 基于功能点推断 + - `schema_refs` —— 填 `TBD(A4 自动补)`（A4 `erp-db-design-gen` 回填依赖表） + - `api_refs` —— 填 `TBD(A5 自动补)`（A5 `erp-downstream-gen` 回填依赖接口） + - 用 module 模板包装卡片列表 + - 用 `Write` 写入 `docs/01-需求清单/<module_code>-<module_name>.md` +4. 向用户输出（只打印，**不弹 QA**，不等待）： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-scope-lock] REQ 卡片已生成 + + 📄 文件位置: ./docs/01-需求清单/<module>-*.md + ⚠️ 依赖表 = TBD(A4 自动补)（A4 阶段回填） / 依赖接口 = TBD(A5 自动补)（A5 阶段回填） + + 请人工审阅每张 REQ 卡片的功能字段： + - 目标 / 输入 / 输出 + - 业务规则 / 边界 + - 验收标准 + + 审阅是 Plan 阶段的关键人工关口，请认真逐张过一遍。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +5. 立即进入步骤 F（不等待用户任何输入）。 + +### F. 勾选 docs/08 进度 + 停下等人工审阅 + +1. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 5 个 checkbox（A1 的 4 个子项 + A1 父项）： + - ` - [ ] 项目概述已填写（CLAUDE.md § 🎯 项目概述）` → `[x]` + - ` - [ ] 技术栈已确认（docs/04 § 零）` → `[x]` + - ` - [ ] 需求清单索引已填写（docs/01-需求清单/README.md）` → `[x]` + - ` - [ ] REQ 卡片已生成（docs/01-需求清单/*.md，schema/api 字段标记为 TBD）` → `[x]` + - `- [ ] A1 范围锁定 — erp-scope-lock` → `[x]` + +2. 输出 `scope-lock: 完成（4 项产出已勾选）`。 + +3. 打印停下横幅并**停下**（**不调** `Skill(erp-skeleton-gen)`，A2 由用户手动恢复）： + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-scope-lock] ✅ A1 范围锁定完成 + + 产出： + ✓ CLAUDE.md § 🎯 项目概述 + ✓ docs/04 § 零 技术栈 + ✓ docs/01-需求清单/README.md 模块索引 + ✓ docs/01-需求清单/<module>-*.md REQ 卡片 + + ⏸ 现在请你审阅 REQ 卡片（路径：`docs/01-需求清单/<module_code>-<module_name>.md`）。 + + 审阅完成后，运行以下命令继续进入 A2： + /erp-workflow:erp-plan-start + + （入口会读 docs/08 进度，自动派发到 A2 erp-skeleton-gen） + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + + **停止**，不调用任何下游 skill。 + +## 参考 + +- `CLAUDE.md` § 🎯 项目概述（写入目标） +- `docs/04-技术规范.md`（技术栈输出，供 erp-skeleton-gen 读取使用） +- `docs/01-需求清单/README.md`（模块索引输入） +- `docs/01-需求清单/<module>-*.md`（REQ 卡片输出，A4 erp-db-design-gen 会回填 TBD 字段） +- `${CLAUDE_SKILL_DIR}/templates/req-card-template.md` +- `${CLAUDE_SKILL_DIR}/templates/docs-01-module-template.md` diff --git a/skills/plan/erp-scope-lock/templates/docs-01-module-template.md b/skills/plan/erp-scope-lock/templates/docs-01-module-template.md new file mode 100644 index 0000000..4534a7d --- /dev/null +++ b/skills/plan/erp-scope-lock/templates/docs-01-module-template.md @@ -0,0 +1,11 @@ +# {{module_code}}-{{module_name}} + +模块简述: {{module_brief}} +依赖模块: {{depends_on}} +涉及表: {{tables}} + +## 功能清单 + +{{#each reqs}} +{{req_card}} +{{/each}} diff --git a/skills/plan/erp-scope-lock/templates/req-card-template.md b/skills/plan/erp-scope-lock/templates/req-card-template.md new file mode 100644 index 0000000..a616c59 --- /dev/null +++ b/skills/plan/erp-scope-lock/templates/req-card-template.md @@ -0,0 +1,10 @@ +### {{req_id}} {{title}} + +- **目标**: {{goal}} +- **输入**: {{input}} +- **输出**: {{output}} +- **业务规则**: {{rules}} +- **边界**: {{constraints}} +- **依赖表**: {{schema_refs}} +- **依赖接口**: {{api_refs}} +- **验收**: {{acceptance}} diff --git a/skills/plan/erp-skeleton-gen/SKILL.md b/skills/plan/erp-skeleton-gen/SKILL.md new file mode 100644 index 0000000..005a8bb --- /dev/null +++ b/skills/plan/erp-skeleton-gen/SKILL.md @@ -0,0 +1,304 @@ +--- +name: erp-skeleton-gen +description: A2 骨架生成——基于 docs/04 § 零 技术栈 + docs/01-需求清单/README.md 模块索引，生成项目专属的架构文档（docs/04 § 一+、docs/06、docs/07、docs/09）和工具脚本。固定工具文件走 cp，架构文档由 LLM 按大纲生成。 +user-invocable: false +allowed-tools: Read Write Edit Skill Grep Glob AskUserQuestion Bash(mkdir *) Bash(cp *) Bash(touch *) Bash(chmod *) Bash(git config *) Bash(cat *) Bash(bash *) +--- + +**所有输出必须使用中文。** + +# erp-skeleton-gen + +## 前置条件 + +本 skill 从 docs/08 进度推进而来。 + +**输入文件**： +- `docs/04-技术规范.md § 零`：erp-scope-lock 写入的技术栈表。本 skill 基于它推导 § 一+ 编码规范、docs/07 依赖清单、docs/09 目录结构、scripts/test.sh 的构建/测试命令。 +- `docs/01-需求清单/`：A1 已产出 README.md（模块索引表）+ 每模块一份 REQ 卡片（`<code>-<name>.md`，用户已审阅确认）。A2 只用其中的**模块 ID 列表**生成 docs/09 的后端/前端模块目录树（`module/user/` / `module/order/` 等），REQ 卡片详情不在本 skill 使用（留给 A4 回填 schema、A5 生成 API/验收清单）。 +- `docs/08-模块任务管理.md`：末尾 Edit 勾选 A2 checkbox。 + +**产出覆盖提醒**： +- 本 skill 会 `Write` 覆盖以下文件：docs/04（拼接 § 零 + § 一+）、docs/06、docs/07、docs/09、scripts/test.sh、scripts/setup-test-db.sh、.githooks/pre-push、.env.local。 +- 如果之前运行过本 skill 且用户手动改过这些文件，**重跑会覆盖修改**。 + +## 执行步骤 + +### 步骤 0：打印当前位置流程图 + +向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A2）： + +``` +┌──────────────────────────────────────────────────────┐ +│ 📋 阶段 A：规划（一次性） │ +│ │ +│ A0 初始化项目 → A1 锁范围（REQ 卡片） │ +│ ↓ │ +│ ⏸ 等你审阅 REQ，重跑 /erp-plan-start 续 │ +│ ↓ │ +│ ▶ A2 生骨架 → A3 初始化 DB → A4 生 DB 设计 → A5 生下游文档│ +│ ↓ │ +│ 规划阶段到此结束 │ +└──────────────────────────────────────────────────────┘ +``` + +### A. 读取锁定的输入 + +用 `Read` 读取： +- `docs/04-技术规范.md` § 零 技术栈表 +- `docs/01-需求清单/README.md` 模块索引 + +这两份是本次生成的**唯一权威输入**，后续所有内容都基于它们推导。 + +### B.1 生成 3 个全新架构文档（docs/06 / 07 / 09） + +对下表每个目标文件： +1. 用 `Read` 读取对应的大纲模板（只含 section 标题 + HTML 注释形式的填写提示） +2. 基于步骤 A 的输入，按大纲生成项目专属内容 +3. **剥掉所有 `<!-- -->` 注释**（注释是给 LLM 的提示，不应出现在最终文档里） +4. 用 `Write` 写入目标路径 + +| 目标文件 | 大纲模板 | +|---|---| +| `docs/06-UI交互规范.md`（写 § 一 ~ 四，§ 五 占位） | `${CLAUDE_SKILL_DIR}/templates/docs-06-static-template.md` | +| `docs/07-环境配置.md` | `${CLAUDE_SKILL_DIR}/templates/docs-07-env-template.md` | +| `docs/09-项目目录结构.md` | `${CLAUDE_SKILL_DIR}/templates/docs-09-structure-template.md` | + +项目专属标识（根包名 / 命名空间）保留 `【人工填写：<说明>】` 占位，等人工在 docs/09 顶部补填一次后，其他文件复用。 + +### B.2 追加 docs/04 § 一+（保留 § 零 不覆盖） + +docs/04 已由 erp-scope-lock 写入 § 零。本步骤追加 § 一 ~ 三。 + +1. 用 `Read` 读取 `docs/04-技术规范.md`（拿现有 § 零 完整内容）。 +2. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`（§ 一+ 大纲）。 +3. 基于步骤 A 技术栈，按大纲生成 § 一 ~ 三 的项目专属内容，剥掉 HTML 注释。 +4. 拼接 `<§ 零 原文>\n\n<新生成的 § 一+>` → 用 `Write` 写回 `docs/04-技术规范.md`。 + +### C. 生成工具脚本 + +#### C.1 零槽位文件：纯 `cp` + +```bash +mkdir -p scripts .githooks sql/migrations +touch sql/migrations/.gitkeep +cp "${CLAUDE_SKILL_DIR}/templates/env-local-template" .env.local +cp "${CLAUDE_SKILL_DIR}/templates/githooks-pre-push-template.sh" .githooks/pre-push +cp "${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh" scripts/setup-test-db.sh +``` + +说明： +- `sql/migrations/` 是 Flyway migration 目录。A3 `erp-db-init` 会在此生成 `V1__initial_schema.sql`，后续 B 阶段每个 REQ 的业务 DDL 也写在这（`V2__xxx.sql` / `V3__xxx.sql` ...） +- `setup-test-db.sh` 只做 **drop + create 空库**；schema apply 由 **Flyway 在 Spring Boot 启动时自动处理** +- **硬依赖**：项目 `pom.xml` 必须包含 `flyway-core` + `flyway-mysql` 依赖（已列入 docs/04 § 零 技术栈）；否则 Spring 启动不会 apply migration，测试会因表不存在而失败 +- seed 数据（`sql/seed-data.sql`）由 A3 `erp-db-init` 从本地 MySQL 导出，开发者选一种装载方式（Spring `@Sql` / Flyway `R__seed.sql` / `data.sql`）；setup-test-db.sh 只负责清空库 + +#### C.2 `scripts/test.sh` —— 直接 Write + +基于步骤 A 的技术栈推断 4 条命令（build / lint / unit+integration / e2e），直接 `Write` 完整 `scripts/test.sh`。 + +骨架如下（CC 把 4 个 `<推断的 ... 命令>` 替换成实际值后 Write）： + +```bash +#!/usr/bin/env bash +# scripts/test.sh —— 合并到 main 前的唯一硬闸门。 +# 顺序：setup-db → build → lint → unit+integration → e2e → reset-db +# 由 .githooks/pre-push 和 erp-local-test-gate skill（通过子会话）调用。 + +set -euo pipefail + +PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$PROJECT_ROOT" + +echo "[test.sh] 1/6 setup test db" +./scripts/setup-test-db.sh + +echo "[test.sh] 2/6 build" +<推断的 build 命令，如：(cd backend && mvn -DskipTests clean package) && (cd frontend && pnpm build)> + +echo "[test.sh] 3/6 lint" +<推断的 lint 命令> + +echo "[test.sh] 4/6 unit + integration" +<推断的 unit+integration 命令> + +echo "[test.sh] 5/6 E2E" +<推断的 e2e 命令> + +echo "[test.sh] 6/6 reset test db" +./scripts/setup-test-db.sh + +echo "[test.sh] GREEN" +``` + +#### C.3 赋权 + 配置 git hooks + +```bash +chmod +x scripts/*.sh .githooks/pre-push +git config core.hooksPath .githooks +``` + +### D. 追加 .gitignore 忽略项 + +调用脚本完成合并： + +```bash +bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh" "${CLAUDE_SKILL_DIR}/templates/gitignore-append-template" +``` + +脚本行为： +- 若项目根无 `.gitignore` → 直接 `cp` 整份模板 +- 若已有 → 读模板每一行，跳过注释/空行，用 `grep -xF` 整行精确匹配判重（避免 `.env` 误匹配 `.env.local`、通配符 `*.iml` 被当正则），只追加缺失的规则 + +### E. 占位符智能填充 + `.env.local` 独立提示 + QA 循环验证 + +目标：减少用户重复编辑。同一"逻辑占位"（如根包名出现多处）只问用户一次，CC 批量填；派生占位（如 Java 路径从根包名派生）由 CC 自己推断。敏感占位（`.env.local` 凭据 / 密钥）不进会话上下文，让用户自己去文件里填。 + +循环执行直到**两个条件同时满足**： +(a) 所有占位符已填（重扫命中数 N = 0） +(b) 用户选「继续」 + +#### E.1 扫描 + 分组 + +用 `Grep` 扫 `【人工填写：` 于以下 8 个路径，记录每处命中（文件 + 行号 + 说明文字）： +- `docs/04-技术规范.md` +- `docs/06-UI交互规范.md` +- `docs/07-环境配置.md` +- `docs/09-项目目录结构.md` +- `scripts/*.sh` +- `.githooks/pre-push` +- `.gitignore` +- `.env.local` + +对每个命中提取 `【人工填写：<说明>】` 的 `<说明>`，**分两组**： + +- **敏感组**：`.env.local` 路径下的全部命中（密码 / 密钥 / 账号等）。**不**通过 `AskUserQuestion` 问——留给 E.4 提示用户手动编辑。 +- **非敏感组**：其他文件的命中。按语义聚合成"逻辑占位"： + - **说明文字完全相同** → 同一个根占位（多处共用同一值），如"根包名"出现 3 次 + - **说明表达派生关系** → 派生占位，派生自某根占位（如"后端 java 根包路径"派生自"根包名"） + - **无法归类** → 视作独立根占位单独问 + +若总 N=0（无任何占位）→ 直接跳 E.5 验证。 + +#### E.2 向用户询问非敏感"根占位" + +对每个非派生根占位用 `AskUserQuestion` 询问： + +- **question**: `请输入 <说明>（将填充到 <N> 处）` +- **options**（给**默认值候选 + 自由输入**，供用户快速选择；"Other" 由 CC 运行时自动提供，无需显式列）： + - `{"label": "<合理默认值>", "description": "示例默认值"}` + - （可选）`{"label": "<第二个常见默认>", "description": "..."}` + +示例（根包名）： +``` +question: "请输入 Java 根包名（将填充到 3 处）" +options: + - {"label": "com.example.erp", "description": "示例默认"} +``` + +- 用户选默认值 → 取该值 +- 用户选 Other → 用户输入的字符串为该值 + +**派生占位不问用户**——由 CC 在 E.3 自行推断。 + +#### E.3 CC 批量 Edit 填充 + +1. 对每个根占位：遍历所有命中位置，用 `Edit` 把 `【人工填写：<说明>】` 替换为 E.2 用户输入的值。 + +2. 对每个派生占位：CC 基于说明文字 + 根占位值**自行推断**派生值，用 `Edit` 填入。例如： + - 根 `根包名 = com.xly.erp` → 派生 `后端 java 根包路径 = backend/src/main/java/com/xly/erp/` + - 根 `根包名 = com.xly.erp` → 派生 `测试 java 根包路径 = backend/src/test/java/com/xly/erp/` + +3. 若 CC 对某派生占位无法可靠推断（说明不清 / 上下文不足），**回退**：把该占位当作独立根占位，弹 `AskUserQuestion` 问用户。 + +#### E.4 `.env.local` 敏感占位提示（不弹 QA） + +若敏感组非空，打印提示横幅（只打印，不问）： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-skeleton-gen] ⚠️ 敏感占位需你亲自填 + + 📄 文件: ./.env.local + 待填字段（<N> 个）： + <列出实际命中的字段名，如 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA / JWT_SECRET> + + 这些是凭据 / 密钥，CC 不通过会话询问（避免写入聊天记录）。 + 请直接编辑 .env.local 填入实际值。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +#### E.5 验证 + QA 循环 + +1. 用 `Grep` **重新扫** `【人工填写：` 于所有 8 个路径，得新命中数 N 和残留清单。 + +2. 打印汇总横幅： + + ``` + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [erp-skeleton-gen] 骨架生成完成，请审阅 + + 📄 架构文档: + ✓ docs/04-技术规范.md (§ 一 ~ 三) + ✓ docs/06-UI交互规范.md (§ 一 ~ 四) + ✓ docs/07-环境配置.md + ✓ docs/09-项目目录结构.md + + 📄 工具文件: + ✓ scripts/test.sh + ✓ scripts/setup-test-db.sh + ✓ .githooks/pre-push + ✓ .env.local + ✓ .gitignore（新建 / 追加 / 跳过） + ✓ sql/migrations/.gitkeep + + 占位符状态: + <N=0 时打印：✅ 全部填完> + <N>0 时打印：⚠️ 还有 N 处待填： + <文件:行号> — <行内容摘要> + ...> + + 需要调整 → 直接编辑对应文件（尤其 .env.local 敏感字段） + 填完后 → 选「继续」放行 A3 + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + ``` + +3. 用 `AskUserQuestion` 询问： + - **question**: `架构文档审阅 & 占位符补填完毕？` + - **options**： + - `{"label": "继续", "description": "进入 A3 数据库配置"}` + - `{"label": "有疑问想先沟通", "description": "需要讨论或修改"}` + +4. 路由： + - 选「有疑问想先沟通」→ 回答用户问题后**回 E.5.1 重扫** + - 选「继续」→ **回 E.5.1 重扫验证**： + - 新 N = 0 → 进入步骤 F（放行 A3） + - 新 N > 0 → 用户以为填完其实还有残留，回 E.5.2 打印新横幅 + 再弹 QA + +关键点：**每次弹 QA 前都重扫一次**，用户看到的 N 始终是最新的；只有 N = 0 且选「继续」才放行。 + +### F. 勾选 docs/08 进度 + 进入 A3 + +1. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 4 个 checkbox（A2 的 3 个子项 + A2 父项）： + - ` - [ ] 架构文档已生成（docs/04 § 一+、docs/06、docs/07、docs/09）` → `[x]` + - ` - [ ] 工具脚本已生成（scripts/*.sh、.githooks/pre-push、.env.local）` → `[x]` + - ` - [ ] .gitignore 已配置` → `[x]` + - `- [ ] A2 骨架生成 — erp-skeleton-gen` → `[x]` + +2. 输出 `skeleton-gen: 完成（docs/04 § 一+ / docs/06 / docs/07 / docs/09 + scripts/*.sh + .githooks/pre-push + .env.local + .gitignore）`。 + +3. 立即调用 `Skill(erp-db-init)` 进入 A3，不等用户手动输入。 + +## 参考 + +- `docs/04-技术规范.md` § 零（技术栈输入） +- `docs/01-需求清单/README.md`（模块索引输入） +- `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`（大纲） +- `${CLAUDE_SKILL_DIR}/templates/docs-06-static-template.md`（大纲） +- `${CLAUDE_SKILL_DIR}/templates/docs-07-env-template.md`（大纲） +- `${CLAUDE_SKILL_DIR}/templates/docs-09-structure-template.md`（大纲） +- `${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh`（0 槽位） +- `${CLAUDE_SKILL_DIR}/templates/githooks-pre-push-template.sh`（0 槽位） +- `${CLAUDE_SKILL_DIR}/templates/env-local-template`（0 槽位） +- `${CLAUDE_SKILL_DIR}/templates/gitignore-append-template`（0 槽位） +- `${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh`（.gitignore 逐行判重合并脚本） diff --git a/skills/plan/erp-skeleton-gen/scripts/merge-gitignore.sh b/skills/plan/erp-skeleton-gen/scripts/merge-gitignore.sh new file mode 100755 index 0000000..02fd0da --- /dev/null +++ b/skills/plan/erp-skeleton-gen/scripts/merge-gitignore.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# merge-gitignore.sh +# 把模板里的忽略规则合并到项目根的 .gitignore： +# - 若 .gitignore 不存在 → 直接 cp 模板（含注释头和结构） +# - 若已存在 → 逐行判重，只追加模板里缺失的规则行（跳过注释/空行） +# +# 用法：merge-gitignore.sh <template_path> [<target_gitignore_path>] +# template_path 模板文件绝对路径（由 erp-skeleton-gen skill 传入） +# target_gitignore_path 目标 .gitignore 路径，默认为当前工作目录下的 .gitignore +# +# 判重：grep -xF 整行精确匹配 + 字面字符串（非正则），避免 .env 误匹配 .env.local， +# 也避免 *.class / *.iml 等通配符被当作 regex。 + +set -euo pipefail + +template="${1:?usage: merge-gitignore.sh <template_path> [<target_gitignore_path>]}" +target="${2:-.gitignore}" + +if [ ! -f "$template" ]; then + echo "[merge-gitignore] ERROR: template not found: $template" >&2 + exit 1 +fi + +if [ ! -f "$target" ]; then + cp "$template" "$target" + echo "[merge-gitignore] created $target from template" + exit 0 +fi + +added=0 +while IFS= read -r line; do + case "$line" in ""|"#"*) continue ;; esac + if ! grep -qxF "$line" "$target"; then + echo "$line" >> "$target" + added=$((added + 1)) + fi +done < "$template" + +echo "[merge-gitignore] $target updated (+$added rules)" diff --git a/skills/plan/erp-skeleton-gen/templates/docs-04-skeleton-template.md b/skills/plan/erp-skeleton-gen/templates/docs-04-skeleton-template.md new file mode 100644 index 0000000..24bd1fb --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/docs-04-skeleton-template.md @@ -0,0 +1,50 @@ +<!-- +本文件是 docs/04-技术规范.md 的 § 一+ 大纲。 +skeleton-gen 读取 docs/04 § 零（技术栈表）和 docs/01-需求清单/README.md（模块索引）， +按下述大纲生成本项目专属的规范内容。LLM 不要原样拷贝提示文字，只保留 section 标题。 +--> + +## 一、后端规范 + +### 1.1 分层结构 +<!-- 按 § 零 的后端框架定层次：controller/service/mapper 等；每层职责一句话。 --> + +### 1.2 命名约定 +<!-- 包名（根包用【人工填写：根包名】占位）/ 类名 / 方法名 / 常量的大小写规则，含 2 个示例。 --> + +### 1.3 统一响应格式 +<!-- 成功/失败的 JSON 结构，错误码段位划分。 --> + +### 1.4 异常处理 +<!-- 全局异常处理器的使用方式；哪些异常要 catch，哪些禁止。 --> + +### 1.5 事务 +<!-- 事务边界（通常 service 层）；跨服务调用的禁止/替代方案。 --> + +### 1.6 认证 +<!-- 基于 § 零 认证方案推导：token 生命周期、刷新机制、密钥管理。 --> + +## 二、前端规范 + +### 2.1 目录约定 +<!-- 基于 § 零 前端框架推导：api/components/pages/store/hooks/utils 的职责。 --> + +### 2.2 状态管理 +<!-- 基于 § 零 状态管理技术推导：全局 vs 局部、服务端数据的存放。 --> + +### 2.3 请求封装 +<!-- HTTP 客户端的拦截器、超时、错误重试、鉴权注入。 --> + +### 2.4 错误处理 +<!-- 网络错误 / 业务错误 / 页面级错误的分层处理。 --> + +## 三、共同约定 + +### 3.1 Git 提交 +`<type>(<scope>): <subject> REQ-XXX-NNN` + +### 3.2 分页查询 +<!-- 后端分页对象 + 前端分页组件，入参出参约定。 --> + +### 3.3 日期与金额 +<!-- 后端类型（如 LocalDateTime / BigDecimal）+ 前端展示工具；金额精度约定。 --> diff --git a/skills/plan/erp-skeleton-gen/templates/docs-06-static-template.md b/skills/plan/erp-skeleton-gen/templates/docs-06-static-template.md new file mode 100644 index 0000000..6896010 --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/docs-06-static-template.md @@ -0,0 +1,47 @@ +<!-- +本文件是 docs/06-UI交互规范.md 的 § 一~四 大纲（§ 五由 erp-downstream-gen 追加）。 +skeleton-gen 读取 docs/04 § 零 和 docs/01 README，按下述大纲生成项目专属内容。 +UI 细节（布局参数、颜色、组件选型）来自 § 零 前端 UI 组件库。 +--> + +# 06-UI交互规范 + +## 一、整体布局 + +### 1.1 页面框架 +<!-- 基于 § 零 UI 组件库（如 Ant Design Layout）描述整体骨架：Header / Sider / Content。 --> + +### 1.2 布局参数 +<!-- 表格形式：Header 高度 / Sidebar 宽度 / 内边距 / 最小分辨率，给出默认值。 --> + +## 二、标准页面类型 +<!-- 根据 docs/01 README 的模块索引推断业务可能出现的页面类型（通常列表/表单/详情/树形 4 类，根据项目裁剪）。 --> + +### 2.1 列表页 +<!-- 顶部操作区 + 搜索栏 + 表格 + 分页，关键组件选型。 --> + +### 2.2 表单页 +<!-- Drawer 还是独立页；校验时机；提交按钮位置。 --> + +### 2.3 详情页 +<!-- Descriptions + Tabs 的组合方式。 --> + +### 2.4 树形管理页 +<!-- 如项目有组织架构/权限树/分类树才生成此节，否则删除。 --> + +## 三、通用交互规则 + +### 3.1 操作反馈 +<!-- 成功/失败消息；危险操作二次确认；长耗时按钮 loading 态。 --> + +### 3.2 数据展示 +<!-- 空状态 / 加载 / 异常 的统一组件与文案。 --> + +### 3.3 权限控制（前端） +<!-- 菜单级 / 按钮级 / 路由级的控制方式，关联后端 RBAC。 --> + +## 四、主题与颜色 +<!-- 基于 § 零 UI 库的主题 token；主色 / 成功 / 警告 / 错误 色值。 --> + +## 五、页面清单（CC 生成） +（由 `erp-downstream-gen` 按模块追加段落） diff --git a/skills/plan/erp-skeleton-gen/templates/docs-07-env-template.md b/skills/plan/erp-skeleton-gen/templates/docs-07-env-template.md new file mode 100644 index 0000000..f5bfadc --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/docs-07-env-template.md @@ -0,0 +1,26 @@ +<!-- +本文件是 docs/07-环境配置.md 的大纲。 +skeleton-gen 基于 docs/04 § 零 技术栈表推导各节内容： + § 一 依赖清单 → 从技术栈的每一行技术推导运行时和构建依赖 + § 二 端口约定 → 从后端/前端/数据库/缓存/反向代理 各取默认端口 + § 四 常用命令 → 基于构建工具、包管理器、MR 工具给出开发者最常用命令 +--> + +# 07-环境配置 + +## 一、依赖清单 + +<!-- 表格：| 层 | 依赖 | 版本 | 说明 |；覆盖 运行时 / 构建 / 容器 / CLI 工具。 --> + +## 二、端口约定 + +<!-- 表格：| 服务 | 端口 | 说明 |；至少列 后端 HTTP / 前端 dev / 数据库 / 缓存 / 反代。 --> + +## 三、环境变量 + +运行时凭据（数据库连接、JWT 密钥等）全部放在仓库根的 `.env.local`，不入 git。 +字段清单与占位符见该文件，真实值由开发者本地填写。 + +## 四、常用命令 + +<!-- 表格：| 命令 | 说明 |；包含 启动后端 / 启动前端 / 打包 / 跑测试 / 重置测试数据 / 创建 MR。 --> diff --git a/skills/plan/erp-skeleton-gen/templates/docs-09-structure-template.md b/skills/plan/erp-skeleton-gen/templates/docs-09-structure-template.md new file mode 100644 index 0000000..cc0e921 --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/docs-09-structure-template.md @@ -0,0 +1,45 @@ +<!-- +本文件是 docs/09-项目目录结构.md 的大纲。 +skeleton-gen 基于 docs/04 § 零 技术栈推导目录树： + § 二 后端目录 → 按后端框架的惯例（如 Spring Boot 的 src/main/java） + § 三 前端目录 → 按前端框架的惯例（如 Vite + React 的 src/） + § 四 docs 目录 → 沿用插件标准 + § 五 命名约定 → 按后端语言的包/命名空间习惯 + +模块划分参考 docs/01-需求清单/README.md 的模块索引，将业务模块落到代码目录。 +--> + +# 09-项目目录结构 + +## 一、仓库顶层 + +<!-- 用代码块画出顶层目录树，含 CLAUDE.md / README.md / .env.local / .githooks / scripts / docs / sql / backend / frontend 等。 --> + +## 二、后端目录 + +<!-- 基于后端框架的目录树；按 docs/01 README 的模块代码把业务模块列出（module/user/、module/order/ 等）。 --> + +## 三、前端目录 + +<!-- 基于前端框架的目录树；pages/ 下按业务模块建子目录。 --> + +## 四、docs/ 结构 + +``` +docs/ +├── 01-需求清单/ # REQ 卡片按模块分文件 +├── 02-开发计划.md +├── 03-数据库设计文档.md +├── 04-技术规范.md +├── 05-API接口契约.md +├── 06-UI交互规范.md +├── 07-环境配置.md +├── 08-模块任务管理.md +├── 09-项目目录结构.md +├── 10-验收检查清单.md +└── superpowers/ # CC 运行时产物 +``` + +## 五、命名与放置约定 + +<!-- 根包 / 命名空间用【人工填写：】占位；Controller / Service / Mapper / DTO / VO / 前端组件 / 前端页面 的放置规则。 --> diff --git a/skills/plan/erp-skeleton-gen/templates/env-local-template b/skills/plan/erp-skeleton-gen/templates/env-local-template new file mode 100644 index 0000000..ebe16fb --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/env-local-template @@ -0,0 +1,6 @@ +DB_HOST=【人工填写：MySQL host，例如 localhost】 +DB_PORT=【人工填写：MySQL port，默认 3306】 +DB_USER=【人工填写：开发账号名】 +DB_PASSWORD=【人工填写：对应密码】 +DB_SCHEMA=【人工填写：schema 名，例如 erp_dev】 +JWT_SECRET=【人工填写：JWT 签名密钥，256+ bit 随机串】 diff --git a/skills/plan/erp-skeleton-gen/templates/githooks-pre-push-template.sh b/skills/plan/erp-skeleton-gen/templates/githooks-pre-push-template.sh new file mode 100644 index 0000000..8289050 --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/githooks-pre-push-template.sh @@ -0,0 +1,9 @@ +#!/usr/bin/env bash +# .githooks/pre-push — run scripts/test.sh before every push. +# No --no-verify: the claude-code hook deny-no-verify.sh also blocks it. + +set -euo pipefail + +cd "$(git rev-parse --show-toplevel)" + +./scripts/test.sh diff --git a/skills/plan/erp-skeleton-gen/templates/gitignore-append-template b/skills/plan/erp-skeleton-gen/templates/gitignore-append-template new file mode 100644 index 0000000..70540c4 --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/gitignore-append-template @@ -0,0 +1,32 @@ +# ==== ERP 插件推荐忽略项（erp-skeleton-gen 追加） ==== +# 本地运行时配置（含真实凭据，严禁入库） +.env.local +.env.*.local + +# Java / Maven +target/ +*.class + +# Node / 前端构建产物 +node_modules/ +dist/ +build/ +coverage/ + +# IDE +.idea/ +.vscode/ +*.iml + +# OS +.DS_Store +Thumbs.db + +# 日志 +*.log +logs/ + +# 插件运行时临时文件 +.tmp/ +*.raw +# ==== 结束 ==== diff --git a/skills/plan/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh b/skills/plan/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh new file mode 100644 index 0000000..23c02a9 --- /dev/null +++ b/skills/plan/erp-skeleton-gen/templates/scripts-setup-test-db-template.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# scripts/setup-test-db.sh — 数据库重置脚本：drop + create 空库。 +# schema apply 由 Flyway 在 Spring Boot 启动时自动处理（见 docs/04 技术栈 + sql/migrations/V*.sql）。 +# seed 数据由测试框架负责（Spring @Sql / Flyway R__seed.sql / data.sql）。 +# +# 使用场景： +# - scripts/test.sh 开头：清空库，让 Spring 启动时 Flyway 从 V1 开始重放所有 migration +# - scripts/test.sh 结尾：清空库，避免测试遗留污染下次运行 +# - 手动调试时：reset 到零状态 + +set -euo pipefail + +source "$(dirname "$0")/../.env.local" + +MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD}" + +echo "[setup-test-db] drop + create database ${DB_SCHEMA}" +$MYSQL_CMD -e "DROP DATABASE IF EXISTS \`${DB_SCHEMA}\`; CREATE DATABASE \`${DB_SCHEMA}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" + +echo "[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts" -- libgit2 0.22.2