c3e8600b24
核心变更：
- Redis key 加入 clientType 前缀：echo:auth:token:{frontend|admin}:{user_id}
- JWT Claims 新增 client_type 字段区分前台/管理端
- 新增 constants/client_type.go 定义 ClientTypeFrontend / ClientTypeAdmin
- 全链路传递 clientType：Controller → Service → TokenStore → Redis
- 中间件从 JWT Claims 提取 clientType 做 Redis 校验
- 登出只删除当前端 Token，不影响另一端
前端变更：
- 管理端 login API 改为调用 POST /api/v1/admin/auth/login（之前错误调用了前台接口）
文档更新：
- 系统设计文档、实施计划、API文档、开发规范、项目进度全部同步
Made-with: Cursor
187 lines
8.7 KiB
Markdown
187 lines
8.7 KiB
Markdown
# EchoChat 项目开发进度
|
||
|
||
> **最后更新**：2026-03-02（前后端错误处理规范统一 + 安全加固）
|
||
> **当前阶段**：Phase 1 - 基础设施与用户认证
|
||
> **当前分支**：`feature/phase1-foundation-and-auth`
|
||
> **实施计划**：`docs/plans/2026-02-27-phase1-foundation-and-auth.md`
|
||
|
||
---
|
||
|
||
## 一、Task 完成状态
|
||
|
||
| Task | 描述 | 状态 | 备注 |
|
||
|------|------|------|------|
|
||
| Task 1 | Docker Compose 开发环境搭建 | ✅ 完成 | PostgreSQL 17 + Redis 7 |
|
||
| Task 2 | 数据库初始化脚本 | ✅ 完成 | users + user_roles + roles 表 |
|
||
| Task 3 | Go 后端服务骨架 | ✅ 完成 | Gin + GORM + Wire + Zap |
|
||
| Task 4 | Auth Service 层 | ✅ 完成 | 注册/登录/Token/Profile API |
|
||
| Task 5 | Auth Controller & Router | ✅ 完成 | JWT + Redis 有状态校验 |
|
||
| Task 6 | uniapp 前端骨架 | ✅ 完成 | request/storage/api/store/pages.json |
|
||
| Task 7 | uniapp 登录/注册页面 | ✅ 完成 | 基于 ui-ux-pro-max 设计系统 |
|
||
| Task 8 | 首页框架与 TabBar | ✅ 完成 | 自定义 TabBar + 路由分发 |
|
||
| Task 9 | Vue 3 管理端项目搭建 | ✅ 完成 | Element Plus + Pinia 3.x |
|
||
| Task 10 | 管理端用户管理模块 | ✅ 完成 | 后端 admin 模块 + 前端列表/详情页 |
|
||
| Task 11 | 端到端集成测试与文档 | ✅ 完成 | Dockerfile + Docker Compose + README + 全流程 API 验证 + Playwright 页面验证 + 代码审查 |
|
||
|
||
---
|
||
|
||
## 二、关键技术决策记录
|
||
|
||
### 后端（Go）
|
||
1. **框架组合**：Gin + GORM + Wire + Zap + Viper
|
||
2. **JWT 策略**：有状态 JWT，Token 按 clientType 隔离存储在 Redis（`echo:auth:token:{frontend|admin}:{user_id}`）
|
||
3. **密码加密**：bcrypt
|
||
4. **数据库时间精度**：`TIMESTAMP(0)` 精确到秒
|
||
5. **API 响应格式**：统一 `{ "code": 0, "message": "success", "data": ... }`
|
||
6. **常量命名**：Go camelCase（`UserStatusActive`），非大写下划线
|
||
7. **模块路由**：模块内自注册 + 中央 router 聚合
|
||
|
||
### 前台用户端（frontend/）
|
||
1. **框架**：uni-app 3.0（Vue 3.4.21 框架锁定）
|
||
2. **状态管理**：Pinia 2.1.7 + pinia-plugin-persistedstate@3
|
||
3. **npm 配置**：`.npmrc` 设置 `legacy-peer-deps=true`（uni-app 兼容性）
|
||
4. **模块系统**：ESM（`export` / `import`），禁止 CommonJS
|
||
5. **响应式单位**：`rpx`（750rpx = 屏幕宽度）
|
||
6. **设计系统**：ui-ux-pro-max 生成，持久化在 `design-system/echochat/`
|
||
7. **色板**：Primary `#2563EB` / BG `#F8FAFC` / Text `#1E293B`
|
||
8. **开发端口**：`npm run dev:h5` → localhost:5173+
|
||
|
||
### 后台管理端（admin/）
|
||
1. **框架**：Vue 3.5+ + Vite 7.x（独立项目，不受 uni-app 限制）
|
||
2. **UI 组件**：Element Plus（中文语言包）
|
||
3. **状态管理**：Pinia 3.x（最新版）
|
||
4. **HTTP 客户端**：Axios
|
||
5. **存储隔离**：localStorage key 前缀 `admin_`
|
||
6. **主题色**：CSS 变量覆盖 Element Plus → `--el-color-primary: #2563EB`
|
||
7. **开发端口**：`npm run dev` → localhost:3100（Vite proxy 代理后端）
|
||
|
||
---
|
||
|
||
## 三、目录结构概览
|
||
|
||
```
|
||
EchoChat/
|
||
├── backend/go-service/ # Go 后端服务
|
||
│ ├── app/
|
||
│ │ ├── admin/ # 管理端模块（controller/service/dao/router/provider）
|
||
│ │ ├── auth/ # 认证模块（controller/service/dao/model/router）
|
||
│ │ ├── constants/ # 常量（role_code/user_status）
|
||
│ │ ├── dto/ # 数据传输对象（auth_dto + admin_dto）
|
||
│ │ └── provider/ # Wire 依赖注入
|
||
│ ├── cmd/server/main.go # 入口
|
||
│ ├── config/ # 配置
|
||
│ ├── pkg/ # 公共包（db/logs/middleware/utils）
|
||
│ └── router/router.go # 中央路由聚合
|
||
├── frontend/ # 前台用户端（uni-app）
|
||
│ └── src/
|
||
│ ├── api/auth.js
|
||
│ ├── components/CustomTabBar.vue
|
||
│ ├── pages/{auth,chat,contact,meeting,profile,index}/
|
||
│ ├── store/user.js
|
||
│ └── utils/{request,storage}.js
|
||
├── admin/ # 后台管理端（Vue 3 + Element Plus）
|
||
│ └── src/
|
||
│ ├── api/auth.js
|
||
│ ├── router/index.js
|
||
│ ├── store/user.js
|
||
│ ├── utils/{request,storage}.js
|
||
│ └── views/{layout,login,dashboard,user}/
|
||
├── deploy/
|
||
│ ├── docker-compose.dev.yml
|
||
│ └── docker/postgres/init.sql
|
||
├── design-system/echochat/ # ui-ux-pro-max 生成的设计系统
|
||
│ ├── MASTER.md
|
||
│ └── pages/{login,admin-login}.md
|
||
└── docs/
|
||
├── api/ # API 接口文档
|
||
├── architecture/ # 系统架构文档
|
||
├── conventions/ # 开发规范文档
|
||
│ └── frontend-backend-integration.md # 前后端集成规范
|
||
├── plans/ # 实施计划文档
|
||
└── progress/ # 进度文档（本文件）
|
||
```
|
||
|
||
---
|
||
|
||
## 四、开发流程规范
|
||
|
||
1. **工作流**：使用 superpowers 流程控制开发节奏
|
||
2. **前端设计**：**必须**使用 ui-ux-pro-max 技能包，禁止手动设计
|
||
3. **代码注释**：所有公开函数、组件、Store 必须有详细注释
|
||
4. **文档同步**：代码变更后必须同步更新相关文档
|
||
5. **Git 分支**：`feature/phase1-foundation-and-auth`
|
||
6. **验证方式**：Playwright MCP 进行页面自动化验证
|
||
7. **代码审查**：每个 Task 完成后，使用 `code-reviewer` 子代理进行结构化代码审查，对照实施计划和编码标准检查
|
||
8. **完成验证**：使用 `verification-before-completion` 技能，在声称完成前必须运行验证命令并确认输出结果
|
||
9. **前后端联动规范**：详见 `docs/conventions/frontend-backend-integration.md`，核心要求：前端错误提示必须优先使用后端 message，禁止硬编码覆盖；后端错误处理禁止忽略 error；登录安全统一返回 401
|
||
|
||
---
|
||
|
||
## 五、开发测试指南
|
||
|
||
### 启动命令（开发模式）
|
||
|
||
前提：postgres 和 redis 已通过 Docker Compose 运行。
|
||
|
||
```bash
|
||
# 启动 Go 后端（http://localhost:8085）
|
||
cd backend/go-service && go run cmd/server/main.go
|
||
|
||
# 启动管理端（http://localhost:3100）
|
||
cd admin && npm run dev
|
||
|
||
# 启动前台 H5（http://localhost:5173+）
|
||
cd frontend && npm run dev:h5
|
||
```
|
||
|
||
如需全容器启动（包括 Go 服务）：`cd deploy && docker compose -f docker-compose.dev.yml up -d`
|
||
|
||
### 测试账号
|
||
|
||
| 账号 | 密码 | 角色 | 用途 |
|
||
|------|------|------|------|
|
||
| `admin_test` | `admin123456` | user + admin | **管理端登录推荐** |
|
||
| `testuser1` | `test123456` | user + admin | 前台登录测试 |
|
||
| `testuser` | `test123456` | user | 前台登录测试 |
|
||
| `testuser3` | `test123456` | user | 前台登录测试 |
|
||
| `created_by_admin` | `pass123456` | user | 管理端创建的用户 |
|
||
| `super_admin` | `admin123456` | super_admin | **系统预置唯一超管账号** |
|
||
|
||
> 也可以通过注册接口或管理端"创建用户"功能创建新的测试账号。
|
||
|
||
### 可测试功能
|
||
|
||
- **管理端**：登录 → 仪表盘 → 用户列表 → 搜索/筛选 → 用户详情 → 禁用/启用 → 分配角色 → 创建用户
|
||
- **前台 H5**：注册 → 登录 → 个人中心 → 修改资料 → 退出登录
|
||
- **API**：`GET http://localhost:8085/health`（健康检查）
|
||
|
||
---
|
||
|
||
## 六、已知问题与注意事项
|
||
|
||
1. ~~前端工具模块使用了 CommonJS，已修复为 ESM~~（已解决）
|
||
2. ~~前端登录失败时错误提示不正确（硬编码"登录已过期"覆盖后端消息）~~（已修复，详见 `docs/conventions/frontend-backend-integration.md`）
|
||
3. ~~后端登录时用户不存在返回 404 暴露用户是否注册~~（已修复为统一返回 401）
|
||
4. uni-app 的 `tabBar.custom: true` 配合自定义 TabBar 组件使用
|
||
5. 管理端和前台的 localStorage key 通过前缀隔离（`admin_` vs `echo_`）
|
||
6. Go 依赖版本需匹配 Go 1.23.12，不要随意升级 Go 工具链
|
||
7. `.gitignore` 已配置忽略：`.cursor/`、`.vite/`、`node_modules/`、`dist/`、`*.png`（根目录截图）、`logs/` 等
|
||
|
||
---
|
||
|
||
## 六、Phase 1 完成总结
|
||
|
||
### Phase 1 阶段成果
|
||
- **11 个 Task 全部完成**，端到端验证通过
|
||
- **Go 后端**：15 个 API 端点，JWT 有状态认证，RBAC 角色权限
|
||
- **前台 uni-app**：登录/注册/TabBar/个人中心
|
||
- **管理端 Vue 3**：登录/仪表盘/用户列表/用户详情
|
||
- **基础设施**：Docker Compose 一键启动（PostgreSQL + Redis + Go 服务）
|
||
- **代码审查**：code-reviewer 审查通过，已修复 panic 风险、错误处理等问题
|
||
|
||
### 下一阶段：Phase 2 - 即时通讯
|
||
- 待制定实施计划
|
||
- WebSocket 长连接 + 消息系统
|
||
- 联系人/好友管理
|
||
- 消息通知
|