long-agent/user-system
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: project docs, scripts, deployment configs, and evidence

Browse Source
This commit is contained in:
long-agent
2026-04-02 11:22:17 +08:00
parent 4718980ab5
commit bbeeb63dfa
396 changed files with 165018 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
docs/archive/plans/NEXT_STEPS.md Normal file
View File

@@ -0,0 +1,254 @@
# 项目下一步操作指南
## ✅ 项目迁移完成
**源位置**: `c:\Users\Admin\WorkBuddy\20260310215221\`
**目标位置**: `D:\project\`
**迁移状态**: ✅ 成功
## 📊 当前状态
### 已完成的工作
1. ✅ **项目完整迁移到D盘**
- 117个文件已复制
- 41个目录已复制
- 总大小: 851.6 KB
2. ✅ **编译错误修复**
- Task 1: 添加了roleHandler/permissionHandler/deviceHandler
- Task 2: 添加了socialRepo初始化
- Task 4-7: 验证了OAuth和验证码系统已完整实现
- Task 16: 删除了重复的Auth方法
3. ✅ **代码审查完成**
- 识别了虚假测试问题
- 创建了真实任务清单
- 项目真实完成度: 35% (7/20任务)
## 🔧 环境配置
### 1. 安装Go环境
Go当前未安装。需要先安装Go 1.23+：
#### 下载Go
访问: https://golang.org/dl/
选择Windows版本：
- **推荐**: `go1.23.x.windows-amd64.msi`
#### 安装步骤
1. 下载MSI安装包
2. 双击运行安装程序
3. 按照提示完成安装（默认安装到 `C:\Go`）
4. 重启命令行窗口
#### 验证安装
```powershell
go version
```
应该输出: `go version go1.23.x windows/amd64`
### 2. 配置Go环境变量
Go安装程序通常会自动配置以下环境变量：
- `GOROOT`: Go安装目录（如 `C:\Go`）
- `GOPATH`: Go工作目录（默认 `%USERPROFILE%\go`）
- `PATH`: 添加 `%GOROOT%\bin` 和 `%GOPATH%\bin`
**如果自动配置失败，手动添加**：
1. 右键"此电脑" → 属性 → 高级系统设置
2. 环境变量 → 系统变量 → 新建
3. 添加：
- 变量名: `GOROOT`
- 变量值: `C:\Go`
4. 编辑 `PATH`，添加：
- `%GOROOT%\bin`
- `%GOPATH%\bin`
### 3. 验证环境
打开新的PowerShell窗口：
```powershell
# 检查Go版本
go version
# 检查环境变量
go env
# 检查GOPATH
$env:GOPATH
```
## 🚀 项目操作步骤
### 步骤1: 进入项目目录
```powershell
cd D:\project
```
### 步骤2: 验证Go模块
```powershell
go mod verify
```
这会验证所有依赖的完整性。
### 步骤3: 下载依赖
```powershell
go mod download
```
### 步骤4: 尝试编译
```powershell
go build ./cmd/server
```
如果成功，会生成 `server.exe` 文件。
### 步骤5: 运行项目
**开发模式**:
```powershell
go run cmd/server/main.go
```
**生产模式**:
```powershell
.\server.exe
```
### 步骤6: 测试API
项目启动后，可以访问：
- 健康检查: `http://localhost:8080/health`
- Prometheus指标: `http://localhost:8080/metrics`
使用curl或Postman测试：
```powershell
# 注册用户
Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/register" `
-Method POST `
-ContentType "application/json" `
-Body '{"username":"testuser","password":"Test123456","email":"test@example.com"}'
# 登录
Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/login" `
-Method POST `
-ContentType "application/json" `
-Body '{"account":"admin","password":"<initialized-password>"}'
```
## 🐳 Docker部署（可选）
如果已安装Docker，可以直接部署：
```powershell
cd D:\project
docker-compose up -d
```
查看日志：
```powershell
docker-compose logs -f
```
停止服务：
```powershell
docker-compose down
```
## 📝 项目文件说明
### 关键目录
| 目录 | 说明 |
|------|------|
| `cmd/` | 命令行工具入口 |
| `internal/` | 内部代码（API、Service、Repository等） |
| `configs/` | 配置文件 |
| `docs/` | 项目文档 |
| `deployment/` | 部署配置 |
| `migrations/` | 数据库迁移 |
### 关键文件
| 文件 | 说明 |
|------|------|
| `go.mod` | Go模块定义 |
| `docker-compose.yml` | Docker配置 |
| `Makefile` | 构建脚本 |
| `configs/config.yaml` | 应用配置 |
## 🎯 后续任务
根据真实任务清单，接下来需要完成：
### P0 - 编译验证（当前）
- [ ] 安装Go环境
- [ ] 验证项目编译
### P1 - 核心功能
- [ ] Task 3: 验证代码编译
- [ ] Task 8: 实现真实E2E测试（替换Mock）
- [ ] Task 15: 真实集成测试
### P2 - 次要功能
- [ ] Task 9: 实现2FA多因素认证
- [ ] Task 10: 实现Admin管理后台
- [ ] Task 11: 实现Webhook事件通知
- [ ] Task 12: 实现批量导入导出
- [ ] Task 13: 实现SDK支持
- [ ] Task 14: 实现IP黑白名单和异常检测
## 🧹 清理C盘空间
**确认D盘项目工作正常后**，可以删除C盘旧文件：
```powershell
Remove-Item -Path "c:\Users\Admin\WorkBuddy\20260310215221" -Recurse -Force
```
**预计释放空间**: 约 50-100 MB
## 📚 参考文档
- Go官方文档: https://golang.org/doc/
- Gin框架文档: https://gin-gonic.com/docs/
- GORM文档: https://gorm.io/docs/
## 💡 常见问题
### Q: go命令找不到？
A: 确保Go已安装并配置了环境变量，重启命令行窗口。
### Q: 编译失败？
A: 检查Go版本是否 >= 1.23，运行 `go mod tidy` 整理依赖。
### Q: 端口被占用？
A: 修改 `configs/config.yaml` 中的 `server.port` 配置。
### Q: 数据库错误？
A: 确保SQLite驱动已安装，检查 `configs/config.yaml` 中的数据库配置。
---
**当前状态**: ⏳ 等待Go环境配置
**下一步**: 安装Go 1.23+，然后验证编译

168
docs/archive/plans/REAL_TASK_LIST.md Normal file
View File

@@ -0,0 +1,168 @@
# 真实任务清单 - 基于实际代码状态
> 生成时间: 2026-03-12
> 基于code-explorer深入代码分析的真实情况
---
## 📋 编译修复任务（P0 - 必须完成）
### Task 1: 修复main.go编译错误 - 缺少Handler定义
**问题**: `cmd/server/main.go:86` 调用了未定义的变量
```go
// 当前代码（第86行）
r := router.NewRouter(authHandler, userHandler, roleHandler, permissionHandler, deviceHandler, authMiddleware, rateLimitMiddleware)
// ^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
// 未定义 未定义 未定义
```
**需要修复**:
- ✅ 定义 `roleHandler = handler.NewRoleHandler(roleService)`
- ✅ 定义 `permissionHandler = handler.NewPermissionHandler(permissionService)`
- ✅ 定义 `deviceHandler = handler.NewDeviceHandler(deviceService)`
- ✅ 初始化对应的Service
**文件**: `cmd/server/main.go`
---
### Task 2: 修复main.go编译错误 - AuthService参数不匹配
**问题**: `service.NewAuthService()` 调用参数数量不匹配
```go
// 当前代码（第63-70行）
authService := service.NewAuthService(
userRepo,
jwtManager,
cacheManager,
cfg.Security.PasswordMinLength,
cfg.Security.LoginMaxAttempts,
cfg.Security.LoginLockDuration,
)
// 但实际AuthService构造函数签名
func NewAuthService(
userRepo *repository.UserRepository,
socialRepo *repository.SocialAccountRepository, // 缺少这个参数
jwt *auth.JWT,
cache *cache.CacheManager,
passwordMin int,
maxAttempts int,
lockTime time.Duration,
) *AuthService
```
**需要修复**:
- ✅ 初始化 `socialRepo = repository.NewSocialAccountRepository(db.DB)`
- ✅ 添加 `socialRepo` 到 `NewAuthService()` 调用
**文件**: `cmd/server/main.go`
---
### Task 3: 验证代码能否成功编译
**前提**: 完成Task 1和Task 2后
**验证步骤**:
```bash
cd c:/Users/Admin/WorkBuddy/20260310215221
go build -o server.exe ./cmd/server
```
**期望结果**: 编译成功，生成 `server.exe`
---
## 🚀 功能实现任务（P1 - 核心功能）
### Task 4: 实现验证码系统
**现状**: Handler中调用了 `GenerateState()` 和 `ValidateState()` 但函数不存在
**需要实现**:
- ✅ `GenerateState()` - 生成随机state
- ✅ `ValidateState(state)` - 验证state有效性
- ✅ State存储和过期机制
---
### Task 5: 实现OAuth真实集成到AuthService
**现状**: Handler调用了OAuth方法但AuthService中没有实现
**需要实现**:
- ✅ `OAuthLogin(ctx context.Context, provider string, state string) (string, error)`
- ✅ `OAuthCallback(ctx context.Context, provider string, code string) (*LoginResponse, error)`
- ✅ `BindSocialAccount(ctx context.Context, userID int64, provider, openID string) error`
- ✅ `UnbindSocialAccount(ctx context.Context, userID int64, provider string) error`
- ✅ `GetSocialAccounts(ctx context.Context, userID int64) ([]*domain.SocialAccount, error)`
- ✅ `GetEnabledOAuthProviders() []auth.OAuthProviderInfo`
---
### Task 6: 实现OAuth工具函数
**需要实现**:
- ✅ HTTP请求封装（带超时、重试）
- ✅ 错误处理（OAuth API错误解析）
- ✅ JSON响应解析
- ✅ State生成和验证
---
### Task 7: 实现GetEnabledOAuthProviders方法
**需要实现**:
- ✅ 从OAuth配置读取已启用的提供商
- ✅ 返回提供商列表和配置信息
---
## 🧪 测试任务（P1 - 真实测试）
### Task 8: 实现真实的E2E测试
**现状**: E2E测试使用Mock Handler，完全没测试真实服务
**需要实现**:
- ✅ 启动真实HTTP服务器
- ✅ 使用真实的Handler和Service
- ✅ 使用真实数据库
- ✅ 测试完整的HTTP请求/响应
---
## 🎯 新功能任务（P2 - 次要功能）
### Task 9-14: PRD要求的其他功能
详见完整文档...
---
## 📊 任务优先级总结
### P0 - 阻塞上线（必须完成）- 预计1-2小时
- [ ] Task 1: 修复main.go Handler定义
- [ ] Task 2: 修复main.go AuthService参数
- [ ] Task 3: 验证代码编译
### P1 - 核心功能（必须完成）- 预计5-7天
- [ ] Task 4: 实现验证码系统
- [ ] Task 5: 实现OAuth集成
- [ ] Task 6: 实现OAuth工具函数
- [ ] Task 7: 实现GetEnabledOAuthProviders
- [ ] Task 8: 实现真实E2E测试
- [ ] Task 15: 真实集成测试
### P2 - 次要功能 - 预计15-20天
- [ ] Task 9: 实现2FA认证
- [ ] Task 10: 实现Admin后台
- [ ] Task 11: 实现Webhook
- [ ] Task 12: 实现批量导入导出
- [ ] Task 13: 实现SDK
- [ ] Task 14: 实现安全功能