# connectrpc-demo-calculator

**Repository Path**: CourteousBin/connectrpc-demo-calculator

## Basic Information

- **Project Name**: connectrpc-demo-calculator
- **Description**: Modern calculator built with ConnectRPC, Go, and Next.js. Features continuous calculations, TypeScript safety, and full-stack architecture. Perfect for learning gRPC/ConnectRPC integration.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ConnectRPC 计算器

基于 ConnectRPC 和 Next.js 构建的现代计算器应用，演示了前后端通信和 gRPC 协议的实际应用。支持连续计算和完整的计算器功能。

## 🎯 项目概述

这是一个全栈计算器应用，使用 Go 和 ConnectRPC 作为后端，Next.js 15 和 TypeScript 作为前端，支持完整的四则运算和连续计算功能。项目经过全面重构，修复了连续计算的状态管理问题。

### 技术栈

- **后端**: Go + ConnectRPC + Protocol Buffers
- **前端**: Next.js 15.4.6 + TypeScript + React Hooks + Turbopack
- **通信协议**: HTTP/2 + ConnectRPC
- **工具链**: Buf CLI (代码生成)
- **测试**: 前后端单元测试覆盖

## ✨ 功能特性

### 核心计算功能
- ✅ 四种基本运算：加法(+)、减法(−)、乘法(×)、除法(÷)
- ✅ **连续计算支持**: 1+1=2, ×3=6 等链式操作
- ✅ 精确的数字输入和状态管理
- ✅ 除零错误处理和边界情况保护
- ✅ 清除功能 (C 按钮) 和退格功能 (⌫)
- ✅ 正负数切换 (± 按钮)

### 用户体验
- ✅ 现代化 UI 设计，深色主题
- ✅ 计算完成状态指示器 (绿色 ✓)
- ✅ 错误状态显示 (红色 ERR)
- ✅ 响应式布局，完美适配桌面和移动端
- ✅ 流畅的按钮交互和视觉反馈

### 技术特性
- ✅ TypeScript 类型安全
- ✅ React Server Components (RSC) 支持
- ✅ Turbopack 快速构建
- ✅ ConnectRPC 通信协议
- ✅ 前后端分离架构

## 🚀 快速开始

### 环境要求

- Go 1.21+
- Node.js 18+
- npm 或 yarn

### 完整启动 (推荐)

前后端分离架构，需要同时启动两个服务：

1. **启动后端服务**
```bash
# 克隆项目
git clone <repository-url>
cd Calculator/backend

# 安装依赖并启动
go mod download
go run main.go
```

后端服务启动在 `http://localhost:8080`

2. **启动前端服务**
```bash
cd Calculator/frontend

# 安装依赖 (处理版本冲突)
npm install --legacy-peer-deps

# 启动开发服务器 (Turbopack)
npm run dev
```

前端服务启动在 `http://localhost:3000`

### 完整开发环境

如需同时开发前后端或进行修改：

**注意**: 前端已经修复了连续计算问题，支持完整的链式计算功能。

1. **启动后端服务**
```bash
cd backend
go mod download
go build -o calculator-server .
./calculator-server
```

后端服务将启动在 `http://localhost:8080`

2. **启动前端服务**
```bash
cd frontend
npm install
npm run dev
```

前端服务将启动在 `http://localhost:3000`

## 📁 项目结构

```
Calculator/
├── backend/                 # Go 后端服务
│   ├── gen/                # 生成的 protobuf 代码
│   │   └── pts/f/v1/       # ConnectRPC 客户端代码
│   ├── internal/           # 内部业务逻辑
│   │   └── calculator/     # 计算器服务实现和测试
│   ├── main.go            # 应用入口
│   └── go.mod             # Go 模块配置
├── frontend/              # Next.js 前端应用
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx   # 主计算器页面
│   │   │   ├── layout.tsx # 应用布局
│   │   │   └── globals.css # 全局样式 (Tailwind)
│   │   ├── components/    # React 组件
│   │   │   └── ClientCalculator.tsx # 主计算器组件
│   │   ├── gen/           # 生成的 TypeScript 类型
│   │   └── lib/           # 客户端工具类
│   ├── __tests__/         # 前端测试文件
│   ├── package.json       # 项目依赖
│   └── next.config.js     # Next.js 配置 (Turbopack)
├── proto/                 # Protocol Buffers 定义
│   └── pts/f/v1/          # API 定义
├── 测试文件/
│   ├── test-calculator-logic.js      # 前端逻辑测试
│   └── test-fixed-calculator.js      # 修复后的测试
├── 文档/
│   ├── CONTINUOUS_CALCULATION_FIX_REPORT.md  # 修复报告
│   └── CURRENT_FRONTEND_STATUS.md           # 前端状态
├── buf.yaml              # Buf 配置
├── buf.gen.yaml          # 代码生成配置
├── API.md                # API 文档
└── README.md             # 项目文档
```

## 🎨 前端架构

### ClientCalculator 组件特点

经过全面重构，修复了连续计算问题：

- **ConnectRPC 集成**: 与 Go 后端完美通信
- **状态管理修复**: 解决连续计算的状态问题
- **TypeScript 类型安全**: 完整的类型定义
- **完全独立**: 所有计算逻辑在一个组件中

### 核心状态管理

新增了关键状态标志来解决连续计算问题：

1. **`justCalculated`**: 标记是否刚完成计算
2. **`needsNewNumber`**: 标记是否需要开始新数字
3. **`board`**: 当前显示的数值
4. **`op`**: 当前选中的运算符
5. **`opReq`**: 后端请求的状态管理

### 核心功能

1. **数字输入**: 支持 0-9 数字按钮，修复了连续计算时的输入逻辑
2. **运算符**: 加法(+)、减法(−)、乘法(×)、除法(÷)，支持连续运算
3. **连续计算**: 支持链式计算操作，如 1+1=2, ×3=6
4. **清除功能**: C 按钮重置所有状态
5. **退格功能**: ⌫ 按钮删除最后一位数字
6. **正负数切换**: ± 按钮切换正负号
7. **除零保护**: 自动处理除零情况

### 视觉设计

- **深色主题**: 主背景 #f3f4f6，计算器背景白色
- **按钮设计**: 
  - 数字按钮: 深灰色 #d1d5db
  - 运算符按钮: 橙色 #fb923c，选中时 #ea580c
  - 功能按钮: 中灰色 #e5e7eb
- **显示区**: 黑色背景，白色文字，左上角显示 ERR，右上角显示计算完成指示器 ✓
- **响应式布局**: 4×5 网格，0 按钮跨两列
- **圆角设计**: 按钮和容器都采用圆角
- **阴影效果**: 计算器主体带有阴影效果

## 🔧 后端 API 文档

### ConnectRPC 服务端点

#### 计算服务
```
POST /pts.f.v1.CalculatorService/Calculate
Content-Type: application/connect+json
```

请求格式：
```json
{
  "prior": 10,
  "post": 5,
  "op": 0
}
```

响应格式：
```json
{
  "result": 15
}
```

### 支持的操作类型

- `0` - 加法运算
- `1` - 减法运算
- `2` - 乘法运算
- `3` - 除法运算

### 错误处理

服务会返回适当的 ConnectRPC 错误码：

- `INVALID_ARGUMENT` - 无效的操作类型或参数
- `INVALID_ARGUMENT` - 除零错误
- `INTERNAL` - 内部计算错误

## 🛠 开发指南

### 修改 API

1. 编辑 `proto/calculator/v1/calculator.proto`
2. 运行代码生成（如果有 buf CLI）：
```bash
buf generate
```
3. 更新服务实现和前端客户端

### 本地开发

后端支持热重启：
```bash
cd backend
go run main.go
```

前端支持热重载 (Turbopack)：
```bash
cd frontend
npm run dev
```

### 构建生产版本

后端：
```bash
cd backend
go build -o calculator-server .
```

前端：
```bash
cd frontend
npm run build
```

### Docker 部署 (可选)

项目包含 Docker 配置文件：
```bash
# 构建并启动所有服务
docker-compose up --build
```

## 🧪 测试

### 单元测试

#### 前端逻辑测试
```bash
cd frontend
node test-calculator-logic.js      # 原始测试 (发现问题)
node test-fixed-calculator.js      # 修复后测试 (全部通过)
```

**测试结果**: 9/9 通过 ✅

#### 后端单元测试
```bash
cd backend
go test ./internal/calculator/...
```

**测试覆盖**: 基础运算和连续运算全部通过 ✅

### 手动测试

启动开发服务器进行手动测试：
```bash
# 后端
cd backend && go run main.go

# 前端
cd frontend && npm run dev

# 访问 http://localhost:3000
```

### 功能测试清单

#### 基础功能 ✅
- [x] 基本数字输入 (0-9)
- [x] 四则运算 (+, −, ×, ÷)
- [x] 正负数切换 (± 按钮)
- [x] 清除功能 (C 按钮)
- [x] 退格功能 (⌫ 按钮)
- [x] 除零保护

#### 连续计算 ✅ (已修复)
- [x] 两步连续: 1 + 1 = 2, × 3 = 6
- [x] 复杂连续: 2 × 3 = 6, + 4 = 10
- [x] 三步连续: 5 + 5 = 10, × 2 = 20, ÷ 4 = 5

#### UI/UX ✅
- [x] 响应式布局
- [x] 按钮交互效果
- [x] 计算完成指示器 (✓)
- [x] 错误状态显示 (ERR)

## 📝 技术细节

### 连续计算修复

经过全面分析和修复，解决了以下问题：

1. **问题描述**: 连续计算时结果错误，如 1+1=2 再×3 得到 13 而不是 6
2. **根因分析**: 数字输入逻辑错误，运算符后输入数字会拼接而不是重新开始
3. **解决方案**: 添加状态标志 `justCalculated` 和 `needsNewNumber`

### 前端实现

- **React Hooks**: 使用 `useState` 管理计算器状态
- **TypeScript**: 完整类型定义确保类型安全  
- **ConnectRPC 集成**: 与 Go 后端无缝通信
- **状态管理**: 八个核心状态变量管理计算逻辑
  - `board`: 当前显示的数值
  - `op`: 当前运算符
  - `isNegative`: 正负数标志
  - `isErr`: 错误状态标志
  - `justCalculated`: 刚完成计算标志
  - `needsNewNumber`: 需要新数字标志
  - `opReq`: 后端请求状态
  - `mounted`: SSR 水合防护

### 架构优势

1. **问题修复**: 彻底解决连续计算状态管理问题
2. **类型安全**: TypeScript 完整类型支持
3. **高性能**: Turbopack 快速构建，避免不必要的组件重渲染
4. **易于维护**: 清晰的状态管理和逻辑分离
5. **部署简单**: 前后端分离，Docker 支持

### ConnectRPC 优势

后端使用 ConnectRPC 协议，提供以下优势：
- 支持 HTTP/1.1 和 HTTP/2
- 原生支持 JSON 和 Protocol Buffers
- 更好的浏览器兼容性
- 类型安全的 API 定义

### 错误处理策略

- **前端**: 完善的状态管理和边界情况处理
- **后端**: ConnectRPC 标准错误处理
- **用户体验**: 优雅的错误提示和状态恢复
- **类型安全**: TypeScript 预防运行时错误

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 发起 Pull Request

## 📄 许可证

MIT License

## 🎉 致谢

- [ConnectRPC](https://connectrpc.com/) - 现代 RPC 框架
- [Next.js](https://nextjs.org/) - React 框架
- [shadcn/ui](https://ui.shadcn.com/) - UI 组件库
- [Tailwind CSS](https://tailwindcss.com/) - CSS 框架