diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000000000000000000000000000000000000..cf410bee0be784ce76fa057ea8eff0b61ae57876 --- /dev/null +++ b/README.en.md @@ -0,0 +1,201 @@ +# SCPIM Project + +SCPIM (SuperClaude Project Integration Management) is a project management integration platform built on the SuperClaude framework, combining business analysis, deep research, and multi-agent collaboration capabilities. + +## Core Architecture + +### SuperClaude Framework Entry Point + +The project uses `.claude/CLAUDE.md` as the entry point for SuperClaude, integrating multiple core components: + +- **Behavior Patterns** - Predefined workflow patterns (e.g., brainstorming, deep research, introspection) +- **MCP Documents** - Model Context Protocol server configuration and integration guidelines +- **Professional Agents** - Various expert roles (architects, security engineers, QA specialists, etc.) + +### Professional Agent System + +| Agent Type | Responsibility | +|------------|----------------| +| Backend Architect | System backend design and architectural decisions | +| Frontend Architect | User interface and interaction design | +| System Architect | Overall system architecture planning | +| Security Engineer | Security assessment and hardening | +| Quality Engineer | Code quality assurance | +| Performance Engineer | Performance analysis and optimization | +| Requirements Analyst | Requirement discovery and analysis | +| Root Cause Analyst | Problem diagnosis and root cause analysis | +| PM Agent | Project management and PDCA cycle | +| Socratic Mentor | Learning guidance and knowledge transfer | + +### Business Panel Expert Group + +Integrates analytical perspectives from multiple business thinkers: + +- **Clayton Christensen** - Disruption Theory Expert +- **Michael Porter** - Competitive Strategy Analyst +- **Peter Drucker** - Management Philosopher +- **Seth Godin** - Marketing and Tribe Builder +- **W. Chan Kim & Renée Mauborgne** - Blue Ocean Strategy Experts +- **Jim Collins** - Organizational Excellence Expert +- **Nassim Nicholas Taleb** - Risk and Uncertainty Expert +- **Donella Meadows** - Systems Thinking Expert +- **Jean-luc Doumont** - Communication Systems Expert + +## SuperClaude Commands + +### Core Commands + +| Command | Function | +|--------|----------| +| `/sc:analyze` | Code analysis and quality assessment | +| `/sc:brainstorm` | Interactive requirement discovery | +| `/sc:build` | Project build and packaging | +| `/sc:business-panel` | Multi-expert business panel analysis | +| `/sc:design` | System and component design | +| `/sc:document` | Focused document generation | +| `/sc:estimate` | Development effort estimation | +| `/sc:explain` | Code and concept explanation | +| `/sc:git` | Enhanced Git operations | +| `/sc:implement` | Feature implementation | +| `/sc:improve` | Code improvement and optimization | +| `/sc:index` | Project documentation indexing | +| `/sc:load` | Project context loading | +| `/sc:pm` | Project manager agent | +| `/sc:research` | Deep research analysis | +| `/sc:task` | Enhanced task management | +| `/sc:test` | Testing and quality assurance | +| `/sc:workflow` | Workflow generation | + +### Analysis Modes + +- **Discussion Mode** - Multi-expert collaborative analysis +- **Debate Mode** - Adversarial analysis verification +- **Socratic Mode** - Question-driven exploration + +## MCP Server Integration + +| Server | Purpose | +|--------|---------| +| Context7 | Official documentation retrieval | +| Magic | UI component generation | +| Morphllm | Pattern matching and batch operations | +| Playwright | Browser automation testing | +| Sequential | Step decomposition and orchestration | +| Serena | Memory management and cross-session persistence | +| Tavily | Deep search research | + +## Installation and Configuration + +### Prerequisites + +- Go 1.21+ +- Protocol Buffers compiler +- Docker (for MySQL, Redis, Consul) + +### Build Steps + +```bash +# Start infrastructure services +docker-compose up -d mysql redis consul + +# Run UC service +make run + +# Build production version +make build +``` + +### Protobuf Compilation + +```bash +# Compile all proto files +make proto + +# Manual compilation (if needed) +protoc --go_out=. --go-grpc_out=. ./path/to/file.proto +``` + +## Development Guidelines + +### Testing Requirements + +```bash +# Run all tests +make test + +# Run tests with coverage display +go test -cover ./... + +# Run tests for a specific package +go test ./package/path + +# Verbose test output +go test -v ./... +``` + +### Code Quality + +```bash +# Format code +go fmt ./... + +# Check formatting +gofmt -l . + +# Static analysis +golangci-lint run +``` + +### File Naming Conventions + +- Test files: `*_test.go` +- Protobuf files: `*_pb.go` +- DAO files: Managed via singleton pattern + +## Key Development Patterns + +### 1. Service Initialization Pattern +System services start and initialize in dependency order. + +### 2. WebSocket Message Handler +Real-time bidirectional communication message handling mechanism. + +### 3. User Context Binding +Critical user state management and tracking. + +### 4. DAO Singleton Pattern +Database access objects managed via singleton pattern. + +### 5. Error Handling Pattern +Unified error codes and logging standards. + +## Protocol and Routing Management + +### Route Code Allocation Rules +Route code ranges are segmented by functional modules to ensure scalability. + +### Error Code Allocation Rules +A unified error code system is adopted for easier issue tracking. + +## Common Pitfalls + +1. **Module Path Resolution** - Ensure correct Go module paths +2. **Actor Model Usage** - Concurrency message passing must follow Actor pattern +3. **Message Broadcasting** - Control broadcast scope and permissions +4. **Authentication Middleware** - All APIs must pass authentication +5. **Database Auto-Migration** - Monitor schema changes +6. **Soft Delete** - Distinguish between logical and physical deletion + +## Service Communication + +### HTTP → WebSocket Login Flow +``` +HTTP Login Authentication → WebSocket Connection Established → Session Maintained +``` + +### gRPC Service Calls +Services communicate efficiently via gRPC. + +## License + +This project is licensed under an open-source license; see the LICENSE file for details. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..243e7547871cef893140b5e3775b02c9b527bf8a --- /dev/null +++ b/README.md @@ -0,0 +1,203 @@ + + +# SCPIM 项目 + +SCPIM(SuperClaude Project Integration Management)是一个基于 SuperClaude 框架的项目管理集成平台,结合了业务分析、深度研究和多智能体协作能力。 + +## 核心架构 + +### SuperClaude 框架入口 + +项目通过 `.claude/CLAUDE.md` 作为 SuperClaude 的入口点,整合了多种核心组件: + +- **行为模式** - 预定义的工作流模式(如头脑风暴、深度研究、内省等) +- **MCP 文档** - Model Context Protocol 服务器配置和集成指南 +- **专业代理** - 各类专家角色(架构师、安全工程师、QA 专家等) + +### 专业代理系统 + +| 代理类型 | 职责 | +|---------|------| +| 后端架构师 | 系统后端设计与架构决策 | +| 前端架构师 | 用户界面与交互设计 | +| 系统架构师 | 整体系统架构规划 | +| 安全工程师 | 安全评估与加固 | +| 质量工程师 | 代码质量保障 | +| 性能工程师 | 性能分析与优化 | +| 需求分析师 | 需求挖掘与分析 | +| 根本原因分析师 | 问题诊断与根因分析 | +| PM Agent | 项目管理与 PDCA 循环 | +| 苏格拉底导师 | 学习引导与知识传递 | + +### 业务面板专家小组 + +集成了多位商业思想家的分析视角: + +- **Clayton Christensen** - 颠覆理论专家 +- **Michael Porter** - 竞争策略分析师 +- **Peter Drucker** - 管理哲学家 +- **Seth Godin** - 营销与部落建设者 +- **W. Chan Kim & Renée Mauborgne** - 蓝海战略家 +- **Jim Collins** - 组织卓越专家 +- **Nassim Nicholas Taleb** - 风险与不确定性专家 +- **Donella Meadows** - 系统思维专家 +- **Jean-luc Doumont** - 通信系统专家 + +## SuperClaude 命令 + +### 核心命令 + +| 命令 | 功能 | +|-----|------| +| `/sc:analyze` | 代码分析和质量评估 | +| `/sc:brainstorm` | 交互式需求发现 | +| `/sc:build` | 项目构建和打包 | +| `/sc:business-panel` | 业务小组多专家分析 | +| `/sc:design` | 系统和组件设计 | +| `/sc:document` | 聚焦文档生成 | +| `/sc:estimate` | 开发工作量估算 | +| `/sc:explain` | 代码和概念解释 | +| `/sc:git` | Git 操作增强 | +| `/sc:implement` | 功能实施 | +| `/sc:improve` | 代码改进优化 | +| `/sc:index` | 项目文档索引 | +| `/sc:load` | 项目上下文加载 | +| `/sc:pm` | 项目经理代理 | +| `/sc:research` | 深度研究分析 | +| `/sc:task` | 增强型任务管理 | +| `/sc:test` | 测试与质量保障 | +| `/sc:workflow` | 工作流生成 | + +### 分析模式 + +- **讨论模式** - 多专家协作分析 +- **辩论模式** - 对抗性分析验证 +- **苏格拉底模式** - 问题驱动探索 + +## MCP 服务器集成 + +| 服务器 | 用途 | +|--------|------| +| Context7 | 官方文档检索 | +| Magic | UI 组件生成 | +| Morphllm | 模式匹配与批量操作 | +| Playwright | 浏览器自动化测试 | +| Sequential | 步骤分解与编排 | +| Serena | 内存管理与跨会话持久化 | +| Tavily | 深度搜索研究 | + +## 安装与配置 + +### 前提条件 + +- Go 1.21+ +- Protocol Buffers 编译器 +- Docker(用于 MySQL、Redis、Consul) + +### 构建步骤 + +```bash +# 启动基础设施服务 +docker-compose up -d mysql redis consul + +# 运行 UC 服务 +make run + +# 编译生产版本 +make build +``` + +### Protobuf 编译 + +```bash +# 编译所有 proto 文件 +make proto + +# 手动编译(如需要) +protoc --go_out=. --go-grpc_out=. ./path/to/file.proto +``` + +## 开发规范 + +### 测试要求 + +```bash +# 运行所有测试 +make test + +# 运行测试并显示覆盖率 +go test -cover ./... + +# 运行指定包测试 +go test ./package/path + +# 详细测试输出 +go test -v ./... +``` + +### 代码质量 + +```bash +# 格式化代码 +go fmt ./... + +# 检查格式 +gofmt -l . + +# 静态分析 +golangci-lint run +``` + +### 文件命名约定 + +- 测试文件:`*_test.go` +- Protobuf 文件:`*_pb.go` +- DAO 文件:单例模式管理 + +## 关键开发模式 + +### 1. 服务初始化模式 +系统服务按依赖顺序启动和初始化。 + +### 2. WebSocket 消息处理器 +支持实时双向通信的消息处理机制。 + +### 3. 用户定位绑定 +关键的用户状态管理和追踪。 + +### 4. DAO 单例模式 +数据库访问对象采用单例管理。 + +### 5. 错误处理模式 +统一的错误码和日志规范。 + +## 协议与路由管理 + +### 路由码分配规则 +按功能模块划分路由码区间,确保可扩展性。 + +### 错误码分配规则 +采用统一的错误码体系,便于问题追踪。 + +## 常见陷阱 + +1. **模块路径解析** - 注意 Go 模块路径的正确性 +2. **Actor 模型使用** - 并发消息传递需遵循 Actor 模式 +3. **消息广播** - 注意广播范围和权限控制 +4. **认证中间件** - 所有 API 需通过认证 +5. **数据库自动迁移** - 关注 schema 变更 +6. **软删除** - 注意逻辑删除与物理删除的区别 + +## 服务通信 + +### HTTP → WebSocket 登录流程 +``` +HTTP 登录验证 → WebSocket 连接建立 → 会话保持 +``` + +### gRPC 服务调用 +服务间通过 gRPC 进行高效通信。 + +## License + +本项目遵循开源协议,详见 LICENSE 文件。 \ No newline at end of file