fix
Some checks failed
部署后端服务 / 🧪 测试后端 (push) Failing after 5m8s
部署后端服务 / 🚀 构建并部署 (push) Has been skipped
部署后端服务 / 🔄 回滚部署 (push) Has been skipped

This commit is contained in:
xujiang
2025-07-10 18:09:11 +08:00
parent 35004f224e
commit 010fe2a8c7
96 changed files with 23709 additions and 19 deletions

View File

@ -0,0 +1,262 @@
---
description: Code style and naming conventions
---
# 代码风格和约定规则
## 📝 通用代码风格
### 文件命名
- **Go文件**: `camelCase.go` (例: `uploadPhotoHandler.go`)
- **TypeScript**: `kebab-case.tsx` 或 `PascalCase.tsx` (组件)
- **API文件**: `kebab-case.api` (例: `photo.api`)
- **配置文件**: `kebab-case.yaml/.json`
### 注释规范
```go
// ✅ Go - 函数注释
// UploadPhoto 上传照片到服务器
// 支持JPEG、PNG、GIF、WebP格式最大10MB
func (l *UploadPhotoLogic) UploadPhoto(req *types.UploadPhotoRequest) (*types.UploadPhotoResponse, error) {
// 实现逻辑
}
```
```typescript
// ✅ TypeScript - 接口注释
/**
* 照片数据接口
* @interface Photo
*/
interface Photo {
/** 照片唯一标识符 */
id: string
/** 照片标题 */
title: string
/** 文件名 */
filename: string
}
```
## 🎯 命名约定
### 变量命名
```go
// ✅ Go - 驼峰命名
var photoID string
var userList []User
var maxFileSize int64 = 10 * 1024 * 1024 // 10MB
// ❌ 避免
var photo_id string
var PhotoId string
```
```typescript
// ✅ TypeScript - 驼峰命名
const photoList: Photo[] = []
const isLoading = false
const handlePhotoUpload = () => {}
// ✅ 常量 - 大写下划线
const MAX_FILE_SIZE = 10 * 1024 * 1024
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL
```
### 函数命名
- **动词开头**: `getPhotoList`, `uploadPhoto`, `deleteCategory`
- **布尔值**: `isVisible`, `hasPermission`, `canEdit`
- **事件处理**: `handleClick`, `onPhotoSelect`, `onUploadSuccess`
## 🛡️ 错误处理
### Go 错误处理
```go
// ✅ 标准错误处理
func (l *UploadPhotoLogic) UploadPhoto(req *types.UploadPhotoRequest) (*types.UploadPhotoResponse, error) {
if !file.IsImageFile(req.File) {
return nil, errorx.NewDefaultError("不支持的文件类型")
}
photoID, err := l.savePhoto(req)
if err != nil {
logx.Errorf("保存照片失败: %v", err)
return nil, errorx.NewDefaultError("照片保存失败")
}
return &types.UploadPhotoResponse{
Id: photoID,
// ...
}, nil
}
```
### TypeScript 错误处理
```typescript
// ✅ 异步操作错误处理
try {
const response = await api.post<UploadResponse>('/photos', formData)
return response.data
} catch (error) {
if (axios.isAxiosError(error)) {
const message = error.response?.data?.msg || '上传失败'
throw new Error(message)
}
throw error
}
```
## 📦 导入组织
### Go 导入顺序
```go
import (
// 标准库
"context"
"fmt"
"net/http"
// 第三方库
"github.com/zeromicro/go-zero/rest/httpx"
"github.com/zeromicro/go-zero/core/logx"
// 本地包
"photography/internal/logic/photo"
"photography/internal/svc"
"photography/internal/types"
)
```
### TypeScript 导入顺序
```typescript
// React 相关
import React, { useState, useEffect } from 'react'
import { useRouter } from 'next/router'
// 第三方库
import axios from 'axios'
import { useQuery } from '@tanstack/react-query'
// UI 组件
import { Button } from '@/components/ui/button'
import { Card } from '@/components/ui/card'
// 本地模块
import { api } from '@/lib/api'
import { Photo } from '@/types/api'
import { useAuthStore } from '@/stores/authStore'
```
## 🎨 CSS/样式约定
### Tailwind CSS 类名顺序
```tsx
// ✅ 推荐顺序:布局 → 尺寸 → 间距 → 颜色 → 其他
<div className="flex flex-col w-full h-full p-4 bg-white border rounded-lg shadow-md">
<img
className="w-full h-48 object-cover rounded-md"
src={photo.thumbnail}
alt={photo.title}
/>
</div>
```
### 响应式设计
```tsx
// ✅ 移动优先响应式
<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
{photos.map(photo => (
<PhotoCard key={photo.id} photo={photo} />
))}
</div>
```
## 🔧 类型定义
### TypeScript 接口规范
```typescript
// ✅ 明确的接口定义
interface PhotoCardProps {
photo: Photo
onEdit?: (id: string) => void
onDelete?: (id: string) => void
className?: string
}
// ✅ API 响应类型
interface ApiResponse<T> {
code: number
msg: string
data: T
}
type PhotoListResponse = ApiResponse<{
photos: Photo[]
total: number
page: number
limit: number
}>
```
### Go 结构体规范
```go
// ✅ 结构体标签完整
type Photo struct {
ID string `json:"id" db:"id"`
Title string `json:"title" db:"title"`
Description string `json:"description" db:"description"`
Filename string `json:"filename" db:"filename"`
Thumbnail string `json:"thumbnail" db:"thumbnail"`
CategoryID string `json:"category_id" db:"category_id"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
}
```
## 📊 性能约定
### 避免性能陷阱
```typescript
// ✅ 使用 useMemo 避免重复计算
const expensiveValue = useMemo(() => {
return photos.filter(photo => photo.category_id === selectedCategory)
}, [photos, selectedCategory])
// ✅ 使用 useCallback 避免重复渲染
const handlePhotoSelect = useCallback((id: string) => {
setSelectedPhoto(photos.find(p => p.id === id))
}, [photos])
```
## 🔒 安全约定
### 输入验证
```go
// ✅ 后端输入验证
if req.Title == "" {
return nil, errorx.NewDefaultError("照片标题不能为空")
}
if len(req.Title) > 100 {
return nil, errorx.NewDefaultError("照片标题不能超过100个字符")
}
```
```typescript
// ✅ 前端输入验证
const validatePhoto = (data: PhotoFormData): string[] => {
const errors: string[] = []
if (!data.title.trim()) {
errors.push('标题不能为空')
}
if (data.title.length > 100) {
errors.push('标题不能超过100个字符')
}
return errors
}
```
遵循这些约定可以保持代码的一致性和可维护性。

View File

@ -0,0 +1,151 @@
---
description: General development workflow and best practices
---
# 开发工作流规则
## 🎯 当前优先级任务
基于 [TASK_PROGRESS.md](mdc:TASK_PROGRESS.md),当前高优先级任务:
### 🔥 立即处理
1. **完善照片更新和删除业务逻辑** - 后端CRUD完整性
2. **完善分类更新和删除业务逻辑** - 后端CRUD完整性
3. **前端与后端API集成测试** - 端到端功能验证
### 📋 本周目标
- 实现完整的照片和分类CRUD操作
- 前后端API集成调试
- 用户认证流程实现
## 🔄 开发流程规范
### Git 工作流
```bash
# 功能开发
git checkout -b feature/photo-update-api
git add .
git commit -m "feat: 实现照片更新API"
git push origin feature/photo-update-api
# 代码审查后合并
git checkout main
git merge feature/photo-update-api
```
### 提交信息规范
```bash
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式
refactor: 重构
test: 测试
chore: 构建/工具
```
## 🧪 测试策略
### 后端测试
```bash
# API 测试
curl -X GET http://localhost:8888/api/v1/health
curl -X POST http://localhost:8888/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"123456"}'
# 功能测试
make test
```
### 前端测试
```bash
# 启动开发服务器
cd admin && bun run dev # 管理后台:5173
cd frontend && pnpm dev # 用户界面:3000
cd ui && pnpm dev # 组件库:6006
```
## 🚀 部署流程
### 开发环境
```bash
# 后端
cd backend
make run # 端口:8888
# 前端项目并行启动
cd admin && bun run dev &
cd frontend && pnpm dev &
```
### 生产环境准备
1. 配置PostgreSQL数据库
2. 更新CI/CD流程
3. 配置反向代理
4. 设置监控和日志
## 📁 文件组织原则
### 后端文件
- 新Handler: `internal/handler/{module}/{action}Handler.go`
- 新Logic: `internal/logic/{module}/{action}Logic.go`
- 新API: `api/desc/{module}.api`
### 前端文件
- 新页面: `src/pages/{PageName}.tsx`
- 新组件: `src/components/{ComponentName}.tsx`
- 新服务: `src/services/{serviceName}.ts`
## 🔧 开发工具配置
### VS Code 推荐插件
- Go语言`golang.go`
- React`ES7+ React/Redux/React-Native snippets`
- Tailwind`Tailwind CSS IntelliSense`
- API测试`REST Client`
### 本地环境变量
```bash
# backend/.env
DATABASE_URL="sqlite:photography.db"
JWT_SECRET="your-secret-key"
UPLOAD_PATH="./uploads"
# frontend/.env.local
NEXT_PUBLIC_API_URL="http://localhost:8888/api/v1"
```
## 🛠️ 故障排除
### 常见问题
1. **端口冲突**: 检查8888(后端)、3000(前端)、5173(管理后台)
2. **依赖问题**: 删除node_modules重新安装
3. **Go模块**: 运行`go mod tidy`清理依赖
4. **API调用失败**: 检查CORS设置和认证token
### 调试命令
```bash
# 检查服务状态
lsof -i :8888
netstat -tlnp | grep 8888
# 查看日志
tail -f backend/logs/photography.log
```
## 📊 进度跟踪
### 完成标准
- ✅ 代码通过测试
- ✅ API接口可正常调用
- ✅ 前端界面功能正常
- ✅ 更新TASK_PROGRESS.md状态
### 每日更新
在 [TASK_PROGRESS.md](mdc:TASK_PROGRESS.md) 记录:
- 完成的任务
- 遇到的问题
- 明日计划
保持项目进度透明化和可追踪性。

View File

@ -0,0 +1,248 @@
# Git 工作流规则
## 🌿 分支管理
### 分支命名规范
```bash
# 功能分支
feature/photo-upload-api
feature/admin-dashboard
feature/responsive-design
# 修复分支
fix/photo-delete-bug
fix/login-redirect-issue
# 优化分支
refactor/api-structure
refactor/component-organization
# 文档分支
docs/api-documentation
docs/deployment-guide
```
### 分支工作流
```bash
# 1. 从主分支创建功能分支
git checkout main
git pull origin main
git checkout -b feature/photo-update-api
# 2. 开发和提交
git add .
git commit -m "feat: 实现照片更新API"
# 3. 推送分支
git push origin feature/photo-update-api
# 4. 创建Pull Request
# 在GitHub/GitLab上创建PR
# 5. 代码审查后合并
git checkout main
git pull origin main
git branch -d feature/photo-update-api
```
## 📝 提交信息规范
### 提交类型
```bash
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式化(不影响代码逻辑)
refactor: 重构既不是新增功能也不是修复bug
perf: 性能优化
test: 添加测试
chore: 构建过程或辅助工具的变动
ci: CI/CD配置文件和脚本的变动
```
### 提交信息格式
```bash
<type>(<scope>): <subject>
<body>
<footer>
```
### 提交示例
```bash
# 简单提交
git commit -m "feat: 添加照片上传功能"
git commit -m "fix: 修复登录页面重定向问题"
# 详细提交
git commit -m "feat(api): 实现照片批量删除功能
- 添加批量删除API接口
- 支持选择多张照片删除
- 添加删除确认对话框
- 更新照片列表组件
Closes #123"
```
## 🔄 工作流最佳实践
### 代码同步
```bash
# 每日开始工作前
git checkout main
git pull origin main
# 功能开发中定期同步
git checkout main
git pull origin main
git checkout feature/your-branch
git rebase main # 或者 git merge main
```
### 提交频率
- **小而频繁的提交**:每个逻辑单元完成后提交
- **有意义的提交**:每次提交都应该是可运行的状态
- **原子性提交**:一次提交只做一件事
### 代码审查
```bash
# PR 标题规范
feat: 实现照片分类管理功能
fix: 修复图片上传失败问题
docs: 更新API文档
# PR 描述模板
## 变更说明
- 实现了什么功能
- 修复了什么问题
## 测试说明
- 如何测试这个变更
- 相关的测试用例
## 影响范围
- 影响的模块
- 是否有破坏性变更
```
## 🏷️ 版本管理
### 语义化版本
```bash
# 版本格式MAJOR.MINOR.PATCH
v1.0.0 # 初始版本
v1.0.1 # 补丁版本修复bug
v1.1.0 # 次要版本(新功能,向后兼容)
v2.0.0 # 主要版本(破坏性变更)
```
### 标签管理
```bash
# 创建标签
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
# 查看标签
git tag -l
git show v1.0.0
```
## 🚀 发布流程
### 发布分支
```bash
# 创建发布分支
git checkout -b release/v1.1.0 main
# 在发布分支上修复最后的问题
git commit -m "fix: 修复发布前的小问题"
# 合并回主分支和开发分支
git checkout main
git merge release/v1.1.0
git tag -a v1.1.0 -m "Release v1.1.0"
# 删除发布分支
git branch -d release/v1.1.0
```
## 🔧 Git 配置
### 全局配置
```bash
# 用户信息
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# 编辑器
git config --global core.editor "code --wait"
# 别名
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'
```
### 项目配置
```bash
# .gitignore 示例
# 依赖
node_modules/
vendor/
# 构建产物
dist/
build/
*.exe
# 环境文件
.env
.env.local
.env.production
# IDE
.vscode/
.idea/
*.swp
*.swo
# 日志
logs/
*.log
# 临时文件
.DS_Store
Thumbs.db
```
## 📊 常用命令
### 日常操作
```bash
# 查看状态
git status
git log --oneline -10
# 暂存操作
git stash
git stash pop
git stash list
# 撤销操作
git reset HEAD~1 # 撤销最后一次提交(保留更改)
git reset --hard HEAD~1 # 撤销最后一次提交(丢弃更改)
git revert HEAD # 创建一个撤销提交
# 查看差异
git diff
git diff --staged
git diff main..feature/branch
```
参考 [TASK_PROGRESS.md](mdc:TASK_PROGRESS.md) 进行版本控制和任务跟踪。

View File

@ -0,0 +1,36 @@
---
alwaysApply: true
---
# Photography Portfolio 项目结构指南
## 🏗️ 项目架构概览
这是一个全栈摄影作品集项目,采用微服务架构:
### 后端服务 (`backend/`)
- **框架**: go-zero v1.8.0
- **主要入口**: [cmd/api/main.go](mdc:backend/cmd/api/main.go)
- **配置文件**: [etc/photography-api.yaml](mdc:backend/etc/photography-api.yaml)
- **API 定义**: [api/desc/](mdc:backend/api/desc/) 目录下的 `.api` 文件
### 前端项目
- **管理后台**: [admin/](mdc:admin/) - React + TypeScript + Vite
- **用户界面**: [frontend/](mdc:frontend/) - Next.js + TypeScript
- **UI 组件库**: [ui/](mdc:ui/) - 共享组件
### 核心目录结构
- `backend/internal/handler/` - HTTP 处理器
- `backend/internal/logic/` - 业务逻辑层
- `backend/internal/model/` - 数据模型
- `backend/pkg/` - 共享工具包
- `docs/` - 项目文档
- `scripts/` - 部署和维护脚本
## 📋 开发状态
参考 [TASK_PROGRESS.md](mdc:TASK_PROGRESS.md) 了解当前开发进度和优先级任务。
## 🔧 依赖管理
- 后端Go modules (`go.mod`)
- 前端pnpm (推荐) / bun
- 管理后台bun