feat: Phase 1 完成 — 基础设施 + 用户认证 + 管理端 + 端到端验证

Phase 1 (基础设施与用户认证) 全部 11 个 Task 开发完成：后端 (Go)： - Auth 模块: 注册/登录/JWT(有状态)/Profile/密码修改 - Admin 模块: 用户列表/详情/禁用/启用/角色分配/创建用户 - 中间件: JWT认证 + RBAC角色权限 + 请求日志 + CORS + Panic恢复 - Dockerfile 多阶段构建 + Docker Compose 全栈部署前台 (uni-app)： - 登录/注册页面 + 自定义 TabBar + 个人中心 - 请求封装 + 状态管理 (Pinia) 管理端 (Vue 3 + Element Plus)： - 登录/仪表盘/用户列表/用户详情 - Axios 封装 + 路由守卫 + Pinia 状态管理验证： - 全流程 API 端到端测试通过 - Playwright 页面自动化验证通过 - code-reviewer 代码审查通过 Made-with: Cursor
2026-03-02 11:31:24 +08:00
parent e9bd4dd204
commit 4d03215fe4
63 changed files with 15908 additions and 102 deletions
--- a/docs/api/admin/user.md
+++ b/docs/api/admin/user.md
@@ -26,13 +26,41 @@

 **查询参数：**

-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| keyword | string | 无 | 搜索关键词（匹配用户名/邮箱/昵称） |
-| status | int | 无 | 按状态筛选：1=正常，2=禁用，3=注销 |
-| role | string | 无 | 按角色筛选：user / admin / super_admin |
-| page | int | 1 | 页码 |
-| page_size | int | 20 | 每页数量 |
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| page | int | 是 | - | 页码（从 1 开始） |
+| page_size | int | 是 | - | 每页数量（1-100） |
+| keyword | string | 否 | 无 | 搜索关键词（模糊匹配用户名或邮箱） |
+| status | int | 否 | 无 | 按状态筛选：1=正常，2=禁用，3=注销 |
+
+**成功响应：**
+```json
+{
+    "code": 0,
+    "message": "success",
+    "data": {
+        "total": 100,
+        "list": [
+            {
+                "id": 1,
+                "username": "zhangsan",
+                "email": "zhangsan@example.com",
+                "nickname": "张三",
+                "avatar": "",
+                "gender": 1,
+                "phone": "13800138000",
+                "status": 1,
+                "status_text": "正常",
+                "roles": ["user"],
+                "last_login_at": "2026-02-27 10:00:00",
+                "last_login_ip": "192.168.1.100",
+                "created_at": "2026-02-20 08:00:00",
+                "updated_at": "2026-02-27 10:00:00"
+            }
+        ]
+    }
+}
+```

 ---

@@ -46,20 +74,22 @@
 ```json
 {
    "code": 0,
-    "message": "ok",
+    "message": "success",
    "data": {
        "id": 1,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "nickname": "张三",
-        "avatar": "https://...",
+        "avatar": "",
        "gender": 1,
        "phone": "13800138000",
        "status": 1,
+        "status_text": "正常",
        "roles": ["user"],
        "last_login_at": "2026-02-27 10:00:00",
        "last_login_ip": "192.168.1.100",
-        "created_at": "2026-02-20 08:00:00"
+        "created_at": "2026-02-20 08:00:00",
+        "updated_at": "2026-02-27 10:00:00"
    }
 }
 ```
@@ -86,7 +116,7 @@

 `PUT /api/v1/admin/users/:id/role`

-**权限：** super_admin
+**权限：** admin / super_admin

 **请求参数：**

@@ -102,10 +132,14 @@

 **权限：** admin

-**请求参数：** 同前台用户注册接口，额外支持：
+**请求参数：**

 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
+| username | string | 是 | 用户名，3-50 字符 |
+| email | string | 是 | 邮箱地址 |
+| password | string | 是 | 初始密码，6-50 字符 |
+| nickname | string | 否 | 昵称（默认使用用户名） |
 | role_code | string | 否 | 指定角色，默认为 user |

 ---
--- a/docs/architecture/system-architecture.md
+++ b/docs/architecture/system-architecture.md
@@ -283,10 +283,39 @@ services:
 | **mediasoup** | 最高性能的开源 SFU，C++ 实现 |
 | **PostgreSQL 17** | 强一致性、JSONB 支持、性能优异 |
 | **Redis 7** | 实时状态存储、发布订阅、高速缓存 |
-| **uniapp (Vue 3)** | 一套代码多端运行（H5/App/小程序） |
-| **Element Plus** | Vue 3 生态最成熟的 PC 端组件库 |
+| **uniapp (Vue 3.4)** | 一套代码多端运行（H5/App/小程序），Vue 版本由 uni-app 框架锁定 |
+| **Element Plus** | Vue 3 生态最成熟的 PC 端组件库，管理端使用 |
 | **Docker Compose** | 轻量级容器编排，适合初期和开发环境 |

+### 7.1 前端技术栈版本策略
+
+系统包含两个独立前端项目，因框架约束，版本策略有所区别：
+
+| 前端项目 | 目录 | 框架 | Vue 版本 | 状态管理 | 原因 |
+|----------|------|------|---------|---------|------|
+| 前台用户端 | `frontend/` | uni-app 3.0 | 3.4.21（框架锁定） | Pinia 2.x | uni-app 尚未适配 Vue 3.5，Pinia 3.x 需要 Vue >= 3.5.11 |
+| 后台管理端 | `admin/` | Vue 3 + Element Plus | 3.5+（不受限） | Pinia 3.x | 独立 Vue 3 项目，可使用最新版本 |
+
+**npm 兼容性说明：** uni-app 的 peer dependency 链与 npm 7+ 的严格依赖解析存在冲突，`frontend/` 项目需在 `.npmrc` 中设置 `legacy-peer-deps=true`，这是 uni-app 社区的标准做法。
+
+**版本升级策略：** 当 uni-app 正式适配 Vue 3.5+ 后，可统一将前台的 Pinia 升级至 3.x，API 层面几乎无需改动（Pinia 2.x 与 3.x 的 `defineStore` API 完全兼容）。
+
+### 7.2 两端开发规范差异
+
+前台用户端和后台管理端是**完全独立**的前端项目，开发规范、依赖版本、构建方式不需要强制统一：
+
+| 维度 | 前台用户端 (`frontend/`) | 后台管理端 (`admin/`) |
+|------|------------------------|---------------------|
+| 框架 | uni-app 3.0（Vue 3.4.21） | Vue 3.5+ + Vite |
+| 状态管理 | Pinia 2.x（`pinia-plugin-persistedstate@3`） | Pinia 3.x（最新版） |
+| HTTP 客户端 | `uni.request` 封装 | Axios |
+| 路由 | `pages.json` + `uni.navigateTo/switchTab` | Vue Router 4 |
+| UI 组件 | 原生 uni-app 组件（`<view>`/`<text>`/`<input>`） | Element Plus |
+| 模块系统 | ES Module（Vite 要求） | ES Module（Vite 标准） |
+| npm 配置 | 需要 `.npmrc` 设置 `legacy-peer-deps=true` | 标准 npm 配置 |
+| 适配能力 | H5 / 小程序 / App / 桌面端 | 仅 PC 浏览器 |
+| 设计系统 | ui-ux-pro-max 生成的设计系统 | ui-ux-pro-max + Element Plus 主题 |
+
 ---

 ## 八、日志系统与链路追踪设计
--- a/docs/plans/2026-02-27-phase1-foundation-and-auth.md
+++ b/docs/plans/2026-02-27-phase1-foundation-and-auth.md
@@ -6,7 +6,7 @@

 **架构：** Go 单体模块化服务 + uniapp 前台 + Vue3 管理端 + PostgreSQL + Redis，Docker Compose 编排。

-**技术栈：** Go 1.23+ (Gin + GORM + Wire + zap) / Vue 3.4+ / uniapp 3.0 / Element Plus / PostgreSQL 17 / Redis 7 / Docker Compose
+**技术栈：** Go 1.23+ (Gin + GORM + Wire + zap) / uniapp 3.0 (Vue 3.4 + Pinia 2.x) / Vue 3.5+ 管理端 (Pinia 3.x + Element Plus) / PostgreSQL 17 / Redis 7 / Docker Compose

 **设计文档：** `docs/plans/2026-02-27-echochat-system-design.md`

@@ -30,11 +30,52 @@
 7. **中间件**：说明中间件的作用、执行顺序依赖和副作用

 **前端注释规范（Vue/uniapp）：**
-1. **组件注释**：每个 `.vue` 文件顶部说明组件用途和依赖
-2. **API 函数**：每个 API 调用函数说明对应后端接口
+1. **组件注释**：每个 `.vue` 文件顶部 `<!-- -->` 说明组件用途、功能清单、对应 API 和文档引用
+2. **API 函数**：每个 API 调用函数说明对应后端接口路径和参数
 3. **Store**：state 字段、action 方法需要注释说明
 4. **工具函数**：参数和返回值类型、用途说明
 5. **复杂模板逻辑**：`v-if`/`v-for` 等复杂条件需要注释说明
+6. **CSS 注释**：`<style>` 顶部声明设计系统来源和色板引用
+
+### 前端目录结构与编码规范
+
+**目录结构（uni-app 前台）：**
+
+```
+frontend/src/
+├── api/              # API 接口模块，每个后端模块一个文件
+│   └── auth.js       # 对应 /api/v1/auth/*
+├── pages/            # 页面组件（uni-app 页面路由）
+│   ├── auth/         # 认证页面（login/register）
+│   ├── index/        # 启动页（登录状态判断 + 路由重定向）
+│   ├── chat/         # 消息列表（TabBar 页）
+│   ├── contact/      # 联系人（TabBar 页）
+│   ├── meeting/      # 会议（TabBar 页）
+│   └── profile/      # 个人中心（TabBar 页）
+├── store/            # Pinia 状态管理
+│   └── user.js       # 用户认证状态
+├── utils/            # 工具函数
+│   ├── request.js    # HTTP 请求封装（基于 uni.request）
+│   └── storage.js    # 本地存储封装
+├── services/         # 业务服务（WebSocket 等）
+│   └── websocket.js  # WebSocket 管理（占位）
+├── static/           # 静态资源（图片、图标）
+├── main.js           # 应用入口（Pinia 初始化）
+├── App.vue           # 根组件
+├── pages.json        # 页面路由 + TabBar 配置
+└── manifest.json     # 应用配置
+```
+
+**编码规范：**
+1. **模块化导入**：使用 `@/` 别名引用 `src/` 下的模块（如 `@/api/auth`、`@/store/user`）
+2. **命名规范**：文件名使用 kebab-case 或小写，Vue 组件 name 使用 PascalCase
+3. **导出方式**：统一使用 ES Module（`export` / `export default`）。禁止使用 CommonJS `module.exports`/`require`，Vite 构建环境不兼容 CJS
+4. **状态管理**：所有全局状态通过 Pinia Store 管理，组件内部状态使用 `data()`
+5. **API 调用**：页面组件不直接调用 `request.js`，必须通过 `api/` 层或 Store action
+6. **表单校验**：使用 label + error feedback 模式（禁止 placeholder-only），参照 ui-ux-pro-max UX 规则
+7. **设计系统**：所有页面 UI 必须基于 `design-system/echochat/MASTER.md` 设计规范实现
+8. **响应式单位**：使用 `rpx` 替代 `px`（750rpx = 屏幕宽度），确保多端适配
+9. **npm 配置**：`frontend/.npmrc` 设置 `legacy-peer-deps=true`（uni-app 生态需要）

 ### 日志规范

@@ -633,7 +674,17 @@ git commit -m "feat(auth): 用户注册/登录 API（Controller + 路由注册

 **Step 1: 安装前端依赖**

-Run: `cd frontend && npm install pinia @pinia/persist`
+> **版本策略：** uni-app 锁定 Vue 3.4.21，Pinia 3.x 需要 Vue >= 3.5.11，因此前台用户端必须使用 Pinia 2.x。后台管理端（Task 9）为独立 Vue 3 项目，不受此限制，可使用 Pinia 3.x。
+> 
+> **npm 兼容性：** uni-app 的 peer dependency 链与 npm 7+ 的严格解析存在冲突，需在 `frontend/.npmrc` 中设置 `legacy-peer-deps=true`。
+
+```bash
+# 创建 .npmrc 固化 npm 解析策略
+echo "legacy-peer-deps=true" > frontend/.npmrc
+
+# 安装 Pinia 及持久化插件
+cd frontend && npm install pinia@2.1.7 pinia-plugin-persistedstate@3
+```

 uniapp 内置了请求 API（uni.request），不需要额外安装 axios。

@@ -796,6 +847,8 @@ Run: `cd /path/to/EchoChat && npm create vite@latest admin -- --template vue`

 **Step 2: 安装核心依赖**

+> **版本策略：** 管理端为独立 Vue 3 项目（非 uni-app），可使用最新的 Vue 3.5+ 和 Pinia 3.x，不受 uni-app 版本限制。
+
 Run: `cd admin && npm install element-plus vue-router@4 pinia axios @element-plus/icons-vue`

 **Step 3: 创建布局框架**
--- a/docs/progress/CURRENT_STATUS.md
+++ b/docs/progress/CURRENT_STATUS.md
@@ -0,0 +1,140 @@
+# EchoChat 项目开发进度
+
+> **最后更新**：2026-03-02（Phase 1 全部完成 — Task 11 完成后更新）
+> **当前阶段**：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 存储在 Redis（`echo:auth:token:{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/            # 系统架构文档
+    ├── 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` 技能，在声称完成前必须运行验证命令并确认输出结果
+
+---
+
+## 五、已知问题与注意事项
+
+1. ~~前端工具模块使用了 CommonJS，已修复为 ESM~~（已解决）
+2. uni-app 的 `tabBar.custom: true` 配合自定义 TabBar 组件使用
+3. 管理端和前台的 localStorage key 通过前缀隔离（`admin_` vs `echo_`）
+4. Go 依赖版本需匹配 Go 1.23.12，不要随意升级 Go 工具链
+
+---
+
+## 六、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 长连接 + 消息系统
+- 联系人/好友管理
+- 消息通知