diff --git a/.gitignore b/.gitignore index 002bfbe..04869f6 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,8 @@ .dumi/tmp-production .DS_Store /mint-0.0.875.tar.gz + +.bmad-core +/.claude/commands/BMad +/.claude/commands/openspec +/docs diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0669699 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,18 @@ + +# OpenSpec Instructions + +These instructions are for AI assistants working in this project. + +Always open `@/openspec/AGENTS.md` when the request: +- Mentions planning or proposals (words like proposal, spec, change, plan) +- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work +- Sounds ambiguous and you need the authoritative spec before coding + +Use `@/openspec/AGENTS.md` to learn: +- How to create and apply change proposals +- Spec format and conventions +- Project structure and guidelines + +Keep this managed block so 'openspec update' can refresh the instructions. + + \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0669699 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,18 @@ + +# OpenSpec Instructions + +These instructions are for AI assistants working in this project. + +Always open `@/openspec/AGENTS.md` when the request: +- Mentions planning or proposals (words like proposal, spec, change, plan) +- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work +- Sounds ambiguous and you need the authoritative spec before coding + +Use `@/openspec/AGENTS.md` to learn: +- How to create and apply change proposals +- Spec format and conventions +- Project structure and guidelines + +Keep this managed block so 'openspec update' can refresh the instructions. + + \ No newline at end of file diff --git a/openspec/AGENTS.md b/openspec/AGENTS.md new file mode 100644 index 0000000..96ab0bb --- /dev/null +++ b/openspec/AGENTS.md @@ -0,0 +1,456 @@ +# OpenSpec Instructions + +Instructions for AI coding assistants using OpenSpec for spec-driven development. + +## TL;DR Quick Checklist + +- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search) +- Decide scope: new capability vs modify existing capability +- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`) +- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability +- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement +- Validate: `openspec validate [change-id] --strict` and fix issues +- Request approval: Do not start implementation until proposal is approved + +## Three-Stage Workflow + +### Stage 1: Creating Changes +Create proposal when you need to: +- Add features or functionality +- Make breaking changes (API, schema) +- Change architecture or patterns +- Optimize performance (changes behavior) +- Update security patterns + +Triggers (examples): +- "Help me create a change proposal" +- "Help me plan a change" +- "Help me create a proposal" +- "I want to create a spec proposal" +- "I want to create a spec" + +Loose matching guidance: +- Contains one of: `proposal`, `change`, `spec` +- With one of: `create`, `plan`, `make`, `start`, `help` + +Skip proposal for: +- Bug fixes (restore intended behavior) +- Typos, formatting, comments +- Dependency updates (non-breaking) +- Configuration changes +- Tests for existing behavior + +**Workflow** +1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context. +2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes//`. +3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement. +4. Run `openspec validate --strict` and resolve any issues before sharing the proposal. + +### Stage 2: Implementing Changes +Track these steps as TODOs and complete them one by one. +1. **Read proposal.md** - Understand what's being built +2. **Read design.md** (if exists) - Review technical decisions +3. **Read tasks.md** - Get implementation checklist +4. **Implement tasks sequentially** - Complete in order +5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses +6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality +7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved + +### Stage 3: Archiving Changes +After deployment, create separate PR to: +- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/` +- Update `specs/` if capabilities changed +- Use `openspec archive --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly) +- Run `openspec validate --strict` to confirm the archived change passes checks + +## Before Any Task + +**Context Checklist:** +- [ ] Read relevant specs in `specs/[capability]/spec.md` +- [ ] Check pending changes in `changes/` for conflicts +- [ ] Read `openspec/project.md` for conventions +- [ ] Run `openspec list` to see active changes +- [ ] Run `openspec list --specs` to see existing capabilities + +**Before Creating Specs:** +- Always check if capability already exists +- Prefer modifying existing specs over creating duplicates +- Use `openspec show [spec]` to review current state +- If request is ambiguous, ask 1–2 clarifying questions before scaffolding + +### Search Guidance +- Enumerate specs: `openspec spec list --long` (or `--json` for scripts) +- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available) +- Show details: + - Spec: `openspec show --type spec` (use `--json` for filters) + - Change: `openspec show --json --deltas-only` +- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs` + +## Quick Start + +### CLI Commands + +```bash +# Essential commands +openspec list # List active changes +openspec list --specs # List specifications +openspec show [item] # Display change or spec +openspec validate [item] # Validate changes or specs +openspec archive [--yes|-y] # Archive after deployment (add --yes for non-interactive runs) + +# Project management +openspec init [path] # Initialize OpenSpec +openspec update [path] # Update instruction files + +# Interactive mode +openspec show # Prompts for selection +openspec validate # Bulk validation mode + +# Debugging +openspec show [change] --json --deltas-only +openspec validate [change] --strict +``` + +### Command Flags + +- `--json` - Machine-readable output +- `--type change|spec` - Disambiguate items +- `--strict` - Comprehensive validation +- `--no-interactive` - Disable prompts +- `--skip-specs` - Archive without spec updates +- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive) + +## Directory Structure + +``` +openspec/ +├── project.md # Project conventions +├── specs/ # Current truth - what IS built +│ └── [capability]/ # Single focused capability +│ ├── spec.md # Requirements and scenarios +│ └── design.md # Technical patterns +├── changes/ # Proposals - what SHOULD change +│ ├── [change-name]/ +│ │ ├── proposal.md # Why, what, impact +│ │ ├── tasks.md # Implementation checklist +│ │ ├── design.md # Technical decisions (optional; see criteria) +│ │ └── specs/ # Delta changes +│ │ └── [capability]/ +│ │ └── spec.md # ADDED/MODIFIED/REMOVED +│ └── archive/ # Completed changes +``` + +## Creating Change Proposals + +### Decision Tree + +``` +New request? +├─ Bug fix restoring spec behavior? → Fix directly +├─ Typo/format/comment? → Fix directly +├─ New feature/capability? → Create proposal +├─ Breaking change? → Create proposal +├─ Architecture change? → Create proposal +└─ Unclear? → Create proposal (safer) +``` + +### Proposal Structure + +1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique) + +2. **Write proposal.md:** +```markdown +# Change: [Brief description of change] + +## Why +[1-2 sentences on problem/opportunity] + +## What Changes +- [Bullet list of changes] +- [Mark breaking changes with **BREAKING**] + +## Impact +- Affected specs: [list capabilities] +- Affected code: [key files/systems] +``` + +3. **Create spec deltas:** `specs/[capability]/spec.md` +```markdown +## ADDED Requirements +### Requirement: New Feature +The system SHALL provide... + +#### Scenario: Success case +- **WHEN** user performs action +- **THEN** expected result + +## MODIFIED Requirements +### Requirement: Existing Feature +[Complete modified requirement] + +## REMOVED Requirements +### Requirement: Old Feature +**Reason**: [Why removing] +**Migration**: [How to handle] +``` +If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs//spec.md`—one per capability. + +4. **Create tasks.md:** +```markdown +## 1. Implementation +- [ ] 1.1 Create database schema +- [ ] 1.2 Implement API endpoint +- [ ] 1.3 Add frontend component +- [ ] 1.4 Write tests +``` + +5. **Create design.md when needed:** +Create `design.md` if any of the following apply; otherwise omit it: +- Cross-cutting change (multiple services/modules) or a new architectural pattern +- New external dependency or significant data model changes +- Security, performance, or migration complexity +- Ambiguity that benefits from technical decisions before coding + +Minimal `design.md` skeleton: +```markdown +## Context +[Background, constraints, stakeholders] + +## Goals / Non-Goals +- Goals: [...] +- Non-Goals: [...] + +## Decisions +- Decision: [What and why] +- Alternatives considered: [Options + rationale] + +## Risks / Trade-offs +- [Risk] → Mitigation + +## Migration Plan +[Steps, rollback] + +## Open Questions +- [...] +``` + +## Spec File Format + +### Critical: Scenario Formatting + +**CORRECT** (use #### headers): +```markdown +#### Scenario: User login success +- **WHEN** valid credentials provided +- **THEN** return JWT token +``` + +**WRONG** (don't use bullets or bold): +```markdown +- **Scenario: User login** ❌ +**Scenario**: User login ❌ +### Scenario: User login ❌ +``` + +Every requirement MUST have at least one scenario. + +### Requirement Wording +- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative) + +### Delta Operations + +- `## ADDED Requirements` - New capabilities +- `## MODIFIED Requirements` - Changed behavior +- `## REMOVED Requirements` - Deprecated features +- `## RENAMED Requirements` - Name changes + +Headers matched with `trim(header)` - whitespace ignored. + +#### When to use ADDED vs MODIFIED +- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement. +- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details. +- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name. + +Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead. + +Authoring a MODIFIED requirement correctly: +1) Locate the existing requirement in `openspec/specs//spec.md`. +2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios). +3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior. +4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`. + +Example for RENAMED: +```markdown +## RENAMED Requirements +- FROM: `### Requirement: Login` +- TO: `### Requirement: User Authentication` +``` + +## Troubleshooting + +### Common Errors + +**"Change must have at least one delta"** +- Check `changes/[name]/specs/` exists with .md files +- Verify files have operation prefixes (## ADDED Requirements) + +**"Requirement must have at least one scenario"** +- Check scenarios use `#### Scenario:` format (4 hashtags) +- Don't use bullet points or bold for scenario headers + +**Silent scenario parsing failures** +- Exact format required: `#### Scenario: Name` +- Debug with: `openspec show [change] --json --deltas-only` + +### Validation Tips + +```bash +# Always use strict mode for comprehensive checks +openspec validate [change] --strict + +# Debug delta parsing +openspec show [change] --json | jq '.deltas' + +# Check specific requirement +openspec show [spec] --json -r 1 +``` + +## Happy Path Script + +```bash +# 1) Explore current state +openspec spec list --long +openspec list +# Optional full-text search: +# rg -n "Requirement:|Scenario:" openspec/specs +# rg -n "^#|Requirement:" openspec/changes + +# 2) Choose change id and scaffold +CHANGE=add-two-factor-auth +mkdir -p openspec/changes/$CHANGE/{specs/auth} +printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md +printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md + +# 3) Add deltas (example) +cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF' +## ADDED Requirements +### Requirement: Two-Factor Authentication +Users MUST provide a second factor during login. + +#### Scenario: OTP required +- **WHEN** valid credentials are provided +- **THEN** an OTP challenge is required +EOF + +# 4) Validate +openspec validate $CHANGE --strict +``` + +## Multi-Capability Example + +``` +openspec/changes/add-2fa-notify/ +├── proposal.md +├── tasks.md +└── specs/ + ├── auth/ + │ └── spec.md # ADDED: Two-Factor Authentication + └── notifications/ + └── spec.md # ADDED: OTP email notification +``` + +auth/spec.md +```markdown +## ADDED Requirements +### Requirement: Two-Factor Authentication +... +``` + +notifications/spec.md +```markdown +## ADDED Requirements +### Requirement: OTP Email Notification +... +``` + +## Best Practices + +### Simplicity First +- Default to <100 lines of new code +- Single-file implementations until proven insufficient +- Avoid frameworks without clear justification +- Choose boring, proven patterns + +### Complexity Triggers +Only add complexity with: +- Performance data showing current solution too slow +- Concrete scale requirements (>1000 users, >100MB data) +- Multiple proven use cases requiring abstraction + +### Clear References +- Use `file.ts:42` format for code locations +- Reference specs as `specs/auth/spec.md` +- Link related changes and PRs + +### Capability Naming +- Use verb-noun: `user-auth`, `payment-capture` +- Single purpose per capability +- 10-minute understandability rule +- Split if description needs "AND" + +### Change ID Naming +- Use kebab-case, short and descriptive: `add-two-factor-auth` +- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-` +- Ensure uniqueness; if taken, append `-2`, `-3`, etc. + +## Tool Selection Guide + +| Task | Tool | Why | +|------|------|-----| +| Find files by pattern | Glob | Fast pattern matching | +| Search code content | Grep | Optimized regex search | +| Read specific files | Read | Direct file access | +| Explore unknown scope | Task | Multi-step investigation | + +## Error Recovery + +### Change Conflicts +1. Run `openspec list` to see active changes +2. Check for overlapping specs +3. Coordinate with change owners +4. Consider combining proposals + +### Validation Failures +1. Run with `--strict` flag +2. Check JSON output for details +3. Verify spec file format +4. Ensure scenarios properly formatted + +### Missing Context +1. Read project.md first +2. Check related specs +3. Review recent archives +4. Ask for clarification + +## Quick Reference + +### Stage Indicators +- `changes/` - Proposed, not yet built +- `specs/` - Built and deployed +- `archive/` - Completed changes + +### File Purposes +- `proposal.md` - Why and what +- `tasks.md` - Implementation steps +- `design.md` - Technical decisions +- `spec.md` - Requirements and behavior + +### CLI Essentials +```bash +openspec list # What's in progress? +openspec show [item] # View details +openspec validate --strict # Is it correct? +openspec archive [--yes|-y] # Mark complete (add --yes for automation) +``` + +Remember: Specs are truth. Changes are proposals. Keep them in sync. diff --git a/openspec/project.md b/openspec/project.md new file mode 100644 index 0000000..2777c51 --- /dev/null +++ b/openspec/project.md @@ -0,0 +1,175 @@ +# Project Context + +## Purpose +ERPTurbo_Admin 是寻鸿科技的企业资源规划(ERP)管理系统,为企业提供全面的生产管理、库存管理、经销商管理、订单处理等核心业务功能。系统旨在提高企业运营效率,实现业务流程数字化和智能化管理。 + +## Tech Stack + +### 前端框架 +- **React 18** - 主要UI框架,使用TypeScript开发 +- **UmiJS Max 4.4.9** - 企业级React应用框架,提供路由、构建、部署等一体化解决方案 +- **Ant Design 5.25.2** - 企业级UI设计语言和组件库 +- **Ant Design Pro Components 2.8.6** - 高级业务组件 +- **NutUI React 3.0.18** - 移动端UI组件库(用于移动端适配) + +### 状态管理 +- **Valtio** - 现代化状态管理库 +- **DVA** - 数据流方案(兼容性考虑) +- **React Query** - 服务端状态管理和数据获取 + +### 表单处理 +- **Formily 2.3.2** - 企业级表单解决方案 +- **@formily/antd-v5** - Formily与Ant Design v5的集成 + +### 样式和主题 +- **TailwindCSS 3.4.17** - 原子化CSS框架 +- **antd-style 3.7.1** - Ant Design样式增强方案 +- **Styled Components 6.1.17** - CSS-in-JS样式库 + +### 工具库 +- **Lodash 4.17.21** - 实用工具函数库 +- **Day.js 1.11.13** - 轻量级日期处理库 +- **Axios 1.7.4** - HTTP客户端 +- **UUID 10.0.0** - 唯一标识符生成 +- **CryptoJS 4.2.0** - 加密解密功能 + +### 编辑器和文档 +- **@wangeditor-next/editor** - 富文本编辑器 +- **Markdown-it 14.1.0** - Markdown解析器 +- **XLSX 0.18.5** - Excel文件处理 + +### 地图服务 +- **腾讯地图API** - 地图功能集成 + +### 开发工具 +- **TypeScript 5.6.3** - 类型安全的JavaScript超集 +- **PNPM** - 包管理器,支持工作空间 +- **Prettier 3.3.3** - 代码格式化 +- **ESLint** - 代码质量检查 +- **Husky 9.1.6** - Git钩子管理 +- **Lint-staged 15.2.10** - 暂存文件检查 + +## Project Conventions + +### 代码风格 +- **缩进**: 使用Tab缩进,大小为4个空格宽度 +- **行长度**: 最大80字符 +- **文件编码**: UTF-8 +- **换行符**: LF (Unix风格) +- **尾随空格**: 删除所有尾随空格 +- **文件结尾**: 所有文件以换行符结尾 + +### 命名约定 +- **组件文件**: PascalCase (例: `UserList.tsx`) +- **函数/变量**: camelCase (例: `getUserList`) +- **常量**: SCREAMING_SNAKE_CASE (例: `API_BASE_URL`) +- **文件/目录**: kebab-case (例: `user-management/`) +- **接口/类型**: PascalCase,以I或T开头可选 (例: `UserVO`, `APIResponse`) + +### 目录结构 +``` +packages/app-operation/src/ +├── components/ # 通用组件 +├── pages/ # 页面组件 +├── services/ # API服务 +├── models/ # 数据模型 +├── utils/ # 工具函数 +├── constants/ # 常量定义 +├── layout/ # 布局组件 +├── locales/ # 国际化文件 +├── assets/ # 静态资源 +└── wrappers/ # 高阶组件包装器 +``` + +### 架构模式 +- **微前端架构**: 使用PNPM工作空间管理多个应用 +- **分层架构**: + - 表现层 (Presentation): React组件和页面 + - 业务层 (Business): 业务逻辑和状态管理 + - 数据层 (Data): API调用和数据持久化 +- **模块化设计**: 按业务领域划分模块 (dealer, product, operation等) +- **组件化开发**: 优先使用可复用组件 + +### 测试策略 +- **当前状态**: 项目暂无专门的测试配置 +- **推荐策略**: + - 单元测试:使用Jest + Testing Library + - 集成测试:使用Cypress或Playwright + - 代码覆盖率:目标 > 80% + - 测试文件命名: `*.test.tsx` 或 `*.spec.tsx` + +### Git工作流 +- **分支策略**: + - `master`: 主分支,生产环境代码 + - `feature/*`: 功能开发分支 + - `hotfix/*`: 紧急修复分支 +- **提交规范**: 使用Conventional Commits + - `feat:` 新功能 + - `fix:` 修复bug + - `refactor:` 重构代码 + - `docs:` 文档更新 + - `style:` 代码格式调整 + - `test:` 测试相关 + - `chore:` 构建过程或辅助工具变动 +- **代码质量**: 使用Husky + Lint-staged进行预提交检查 + +### API设计规范 +- **RESTful API**: 遵循REST设计原则 +- **OpenAPI**: 使用Swagger进行API文档化 +- **数据格式**: 统一使用JSON +- **错误处理**: 标准化错误响应格式 +- **分页**: 统一分页参数和响应格式 + +## Domain Context + +### 业务模块 +- **经销商管理 (Dealer)**: 经销商信息、返点计算、配置管理 +- **产品管理 (Product)**: 产品数据、规格管理 +- **订单管理 (Order)**: 订单处理、发货管理 +- **基础数据 (Basic Data)**: 生产预付、工人预付、固定费用 +- **纸箱管理 (Box)**: 纸箱规格管理 +- **系统设置 (Setting)**: 智能识别配置、系统参数 + +### 核心概念 +- **用户角色**: 普通用户、管理员、经销商 +- **权限管理**: 基于角色的访问控制 (RBAC) +- **多租户**: 支持多平台/渠道隔离 +- **国际化**: 默认中文,支持多语言扩展 + +## Important Constraints + +### 技术约束 +- **浏览器支持**: 现代浏览器 (Chrome 80+, Firefox 75+, Safari 13+) +- **响应式设计**: 支持桌面端和移动端 +- **性能要求**: 页面加载时间 < 3秒 +- **安全要求**: + - XSS防护 + - CSRF防护 + - 敏感数据加密 + - API鉴权 + +### 业务约束 +- **数据一致性**: 关键业务数据必须保持一致性 +- **审计日志**: 重要操作需要记录审计日志 +- **数据备份**: 定期备份关键业务数据 +- **合规要求**: 符合企业数据管理规范 + +## External Dependencies + +### 云服务 +- **阿里云OSS**: 文件存储服务 +- **腾讯地图API**: 地图功能服务 + +### API服务 +- **业务API**: 自建后端API服务 +- **认证服务**: SSO单点登录服务 + +### 第三方集成 +- **支付接口**: 支付宝、微信支付(预留) +- **短信服务**: 短信通知服务(预留) +- **邮件服务**: 邮件通知服务(预留) + +### 开发环境 +- **Node.js**: >= 16.0.0 +- **PNPM**: >= 8.0.0 +- **Git**: >= 2.30.0