docs(openspec): 添加OpenSpec指令和项目上下文文档
- 创建AGENTS.md，定义AI助手的OpenSpec使用规范 - 添加project.md，描述ERPTurbo_Admin项目的技术栈和约定 - 建立完整的OpenSpec目录结构和工作流指引 - 包含代码风格、命名约定和架构模式等项目规范 - 提供API设计、测试策略和Git工作流指导原则
This commit is contained in:
shenyifei
parent
35fd2e8138
commit
1ee0bf173c
5
.gitignore
vendored
5
.gitignore
vendored
@ -17,3 +17,8 @@
|
||||
.dumi/tmp-production
|
||||
.DS_Store
|
||||
/mint-0.0.875.tar.gz
|
||||
|
||||
.bmad-core
|
||||
/.claude/commands/BMad
|
||||
/.claude/commands/openspec
|
||||
/docs
|
||||
|
||||
18
AGENTS.md
Normal file
18
AGENTS.md
Normal file
@ -0,0 +1,18 @@
|
||||
<!-- OPENSPEC:START -->
|
||||
# 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.
|
||||
|
||||
<!-- OPENSPEC:END -->
|
||||
18
CLAUDE.md
Normal file
18
CLAUDE.md
Normal file
@ -0,0 +1,18 @@
|
||||
<!-- OPENSPEC:START -->
|
||||
# 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.
|
||||
|
||||
<!-- OPENSPEC:END -->
|
||||
456
openspec/AGENTS.md
Normal file
456
openspec/AGENTS.md
Normal file
@ -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/<id>/`.
|
||||
3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
|
||||
4. Run `openspec validate <id> --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 <change-id> --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 <spec-id> --type spec` (use `--json` for filters)
|
||||
- Change: `openspec show <change-id> --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 <change-id> [--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/<capability>/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/<capability>/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 <change-id> [--yes|-y] # Mark complete (add --yes for automation)
|
||||
```
|
||||
|
||||
Remember: Specs are truth. Changes are proposals. Keep them in sync.
|
||||
175
openspec/project.md
Normal file
175
openspec/project.md
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user