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

195
docs/processes/FRONTEND_BACKEND_REVIEW.md Normal file
View File

@@ -0,0 +1,195 @@
# 前后端联调评审流程
## 1. 概述
本流程确保前后端联调质量，防止设计断链和接口不匹配问题。
## 2. 适用范围
- 所有前后端集成开发
- 新功能开发联调
- Bug 修复联调
- 性能优化联调
## 3. 评审角色
| 角色 | 职责 |
|------|------|
| 后端负责人 | API 设计评审，数据模型验证 |
| 前端负责人 | UI/UX 验证，接口对接验证 |
| 测试工程师 | 联调测试计划，测试用例验证 |
| 技术负责人 | 架构一致性评审，最终决策 |
## 4. 评审时机
- Sprint 开发初期：API 接口评审
- Sprint 中期：联调问题评审
- Sprint 结束前：上线前评审
## 5. 评审内容
### 5.1 API 接口评审
- [ ] 接口路径符合 RESTful 规范
- [ ] 请求/响应格式一致
- [ ] 错误码定义完整
- [ ] 分页、排序、筛选参数统一
- [ ] 权限控制明确
### 5.2 数据模型评审
- [ ] 前后端数据结构一致
- [ ] 字段命名统一（camelCase/snake_case）
- [ ] 数据类型匹配
- [ ] 可选字段/必填字段明确
- [ ] 枚举值定义一致
### 5.3 业务逻辑评审
- [ ] 前后端业务逻辑一致
- [ ] 边界条件处理一致
- [ ] 异常场景处理覆盖
- [ ] 用户交互流程验证
### 5.4 性能评审
- [ ] 接口响应时间满足要求
- [ ] 数据库查询优化
- [ ] 前端渲染性能优化
- [ ] 并发处理机制验证
### 5.5 安全评审
- [ ] 认证授权机制完善
- [ ] 敏感数据传输加密
- [ ] 输入验证防注入
- [ ] XSS/CSRF 防护
## 6. 评审流程
### 6.1 API 接口评审（Sprint 开始）
**输入**：
- API 设计文档（Swagger/OpenAPI）
- 数据模型定义
- 权限设计文档
**输出**：
- API 接口评审报告
- 接口变更记录
**步骤**：
1. 后端负责人提交 API 设计文档
2. 前端负责人审查接口与前端需求的匹配度
3. 技术负责人审查架构一致性
4. 评审会议讨论并记录问题
5. 后端负责人更新接口文档
### 6.2 联调问题评审（Sprint 中期）
**输入**：
- 联调中发现的问题列表
- 问题复现步骤
- 问题影响分析
**输出**：
- 问题解决方案
- 优先级排序
- 解决时间表
**步骤**：
1. 前后端负责人汇总联调问题
2. 评审会议讨论解决方案
3. 技术负责人评估解决方案可行性
4. 确定解决优先级和时间表
### 6.3 上线前评审（Sprint 结束）
**输入**：
- 联调测试报告
- 性能测试报告
- 安全测试报告
- 代码审查报告
**输出**：
- 上线决策（通过/不通过/条件通过）
- 上线风险清单
- 回滚方案
**步骤**：
1. 测试工程师提交测试报告
2. 评审会议审查测试结果
3. 技术负责人评估上线风险
4. 团队决策是否上线
## 7. 评审文档
### 7.1 API 接口评审报告模板
```markdown
# API 接口评审报告
**评审日期**: YYYY-MM-DD
**评审人员**: ...
## 评审结果
- 通过/不通过/条件通过
## 问题列表
| ID | 问题 | 严重程度 | 负责人 | 解决方案 | 状态 |
|----|------|---------|--------|---------|------|
```
### 7.2 联调测试报告模板
```markdown
# 联调测试报告
**测试日期**: YYYY-MM-DD
**测试人员**: ...
## 测试结果
- 测试用例数: X
- 通过: Y
- 失败: Z
- 通过率: N%
## 失败用例列表
| 用例ID | 问题描述 | 严重程度 | 负责人 | 状态 |
|--------|---------|---------|--------|------|
```
## 8. 问题分级
| 级别 | 描述 | 处理时限 |
|------|------|---------|
| P0 | 阻塞问题，无法联调 | 立即修复（4h内） |
| P1 | 严重问题，影响核心功能 | 当天修复 |
| P2 | 一般问题，影响用户体验 | 本周修复 |
| P3 | 优化建议，不影响功能 | 下个 Sprint 处理 |
## 9. 评审准则
### 通过标准
- 所有 P0、P1 问题已解决
- 联调测试通过率 ≥ 95%
- 性能指标满足要求
- 安全测试通过
### 不通过标准
- 存在未解决的 P0 问题
- 联调测试通过率 < 80%
- 存在安全漏洞
### 条件通过标准
- P0 问题已解决，存在少量 P2 问题
- 联调测试通过率 ≥ 90%
- 性能基本达标
- 无严重安全问题
## 10. 持续改进
- 每个 Sprint 后进行评审流程复盘
- 收集团队反馈，优化评审流程
- 定期更新评审检查清单
## 11. 相关文档
- [前后端联调检查清单](../checklists/FRONTEND_BACKEND_CHECKLIST.md)
- [代码审查标准](../code-review/CODE_REVIEW_STANDARD.md)
- [生产环境检查清单](../team/PRODUCTION_CHECKLIST.md)

380
docs/processes/FRONTEND_BACKEND_REVIEW_IMPLEMENTATION_GUIDE.md Normal file
View File

@@ -0,0 +1,380 @@
# 前后端联调评审实施指南
**版本**: v1.0
**生效日期**: 2026-04-02
**状态**: ✅ 已启用
---
## 1. 实施范围
本文档指导如何将前后端联调评审流程应用到当前开发流程中。
---
## 2. 立即生效的评审流程
### 2.1 每个联调任务必须执行的步骤
#### 第一步: API 接口评审（开发前）
**负责人**: 后端负责人
**时间**: 功能开发前 1-2 天
**检查清单** (基于 `docs/checklists/FRONTEND_BACKEND_CHECKLIST.md`):
- [ ] API 路径符合 RESTful 规范
- [ ] 请求参数命名符合规范（后端 snake_case）
- [ ] 响应格式统一
- [ ] 错误码定义清晰
- [ ] 分页参数统一
- [ ] 权限控制明确
**输出**: API 接口设计文档（Swagger/OpenAPI 或手动文档）
#### 第二步: 数据模型评审（开发前）
**负责人**: 后端负责人 + 前端负责人
**时间**: 功能开发前 1 天
**检查清单**:
- [ ] 前后端数据结构一致
- [ ] 字段命名统一约定
- [ ] 数据类型匹配
- [ ] 可选字段/必填字段明确
- [ ] 枚举值定义一致
**输出**: 数据模型定义文档
#### 第三步: 联调问题评审（开发中期）
**负责人**: 前端负责人 + 后端负责人
**时间**: Sprint 中期（第 3-4 天）
**检查清单**:
- [ ] 联调中发现的问题已记录
- [ ] 问题严重程度已分级（P0/P1/P2/P3）
- [ ] 解决方案已确定
- [ ] 负责人和解决时间表已明确
**输出**: 联调问题列表和解决方案
#### 第四步: 上线前评审（Sprint 结束）
**负责人**: 测试工程师 + 技术负责人
**时间**: 上线前 1 天
**检查清单**:
- [ ] 联调测试报告已提交
- [ ] 所有 P0/P1 问题已解决
- [ ] 测试通过率 ≥ 95%
- [ ] 性能指标达标
- [ ] 安全测试通过
**输出**: 上线决策（通过/不通过/条件通过）
---
## 3. 评审模板
### 3.1 API 接口评审记录模板
```markdown
# API 接口评审记录
**评审日期**: YYYY-MM-DD
**评审人员**: ...
**功能模块**: ...
## 评审结果
- 通过 / 不通过 / 条件通过
## 问题列表
| ID | 问题 | 严重程度 | 负责人 | 解决方案 | 状态 |
|----|------|---------|--------|---------|------|
| API-001 | 参数命名不一致 | P2 | 张三 | 统一使用 snake_case | 已解决 |
```
### 3.2 联调测试记录模板
```markdown
# 联调测试记录
**测试日期**: YYYY-MM-DD
**测试人员**: ...
**功能模块**: ...
## 测试结果
- 测试用例数: X
- 通过: Y
- 失败: Z
- 通过率: N%
## 失败用例列表
| 用例ID | 问题描述 | 严重程度 | 负责人 | 状态 |
|--------|---------|---------|--------|------|
| TC-001 | 用户列表分页不工作 | P1 | 李四 | 修复分页参数 | 待修复 |
```
---
## 4. 当前项目的应用规范
### 4.1 接口命名规范
**后端（Go）**:
- 路径: 使用小写字母和下划线 `/api/v1/user_management/users`
- 参数: 使用 snake_case `user_name`, `created_at`
- 响应字段: 使用 snake_case `user_id`, `user_name`, `created_at`
**前端（React/TypeScript）**:
- API 调用: 统一使用 `lib/http/client.ts`
- 参数: 使用 camelCase（发送前转换）
- 响应字段: 使用 camelCase（接收后转换）
### 4.2 接口分类
**用户管理**:
- `GET /api/v1/users` - 获取用户列表（分页）
- `POST /api/v1/users` - 创建用户
- `GET /api/v1/users/:id` - 获取用户详情
- `PUT /api/v1/users/:id` - 更新用户
- `DELETE /api/v1/users/:id` - 删除用户
**角色管理**:
- `GET /api/v1/roles` - 获取角色列表
- `POST /api/v1/roles` - 创建角色
- `GET /api/v1/roles/:id` - 获取角色详情
- `PUT /api/v1/roles/:id` - 更新角色
- `DELETE /api/v1/roles/:id` - 删除角色
**权限管理**:
- `GET /api/v1/permissions` - 获取权限列表
- `GET /api/v1/permissions/tree` - 获取权限树
**认证授权**:
- `POST /api/v1/auth/login` - 登录
- `POST /api/v1/auth/logout` - 登出
- `GET /api/v1/auth/userinfo` - 获取当前用户信息
- `GET /api/v1/auth/csrf-token` - 获取 CSRF Token
### 4.3 响应格式规范
**成功响应**:
```json
{
"code": 0,
"message": "success",
"data": {
"items": [...],
"total": 100,
"page": 1,
"pageSize": 20
}
}
```
**错误响应**:
```json
{
"code": 40001,
"message": "参数错误",
"details": {
"field": "user_name",
"error": "用户名不能为空"
}
}
```
**错误码定义**:
- `0`: 成功
- `40001`: 参数错误
- `40003`: 参数验证失败
- `40100`: 未认证
- `40300`: 权限不足
- `40400`: 资源不存在
- `50000`: 服务器内部错误
---
## 5. 联调检查要点
### 5.1 当前项目重点检查项
基于项目现状，以下是需要重点关注的联调检查项：
#### P1 必须修复（立即处理）
- [ ] `ValidateRecoveryCode` 时序泄漏 ✅ 已修复（2026-04-01）
- [ ] 前后端数据结构不一致问题
- [ ] 权限检查不完整问题
#### P2 建议修复（本周处理）
- [ ] N+5 查询问题（统计接口）
- [ ] SlidingWindowLimiter 清理死代码
- [ ] recordDelivery 使用 context.Background
#### P3 可选优化（下 Sprint 处理）
- [ ] 原生 SQL 使用规范
- [ ] 正则表达式预编译
- [ ] 状态管理优化
### 5.2 设计断链问题
基于 `docs/code-review/PRD_GAP_DESIGN_PLAN.md`，以下设计断链需要重点关注：
**P0 严重断链（7个）**:
- GAP-FE-001: 管理员管理页（前端缺失）
- GAP-FE-002: 系统设置页（前端缺失）
- GAP-FE-003: 全局设备管理页（前端缺失）
- GAP-FE-004: 登录日志导出（前端缺失）
- GAP-BE-001: 系统设置API（后端缺失）
- GAP-INT-001: 设备信任检查（接线缺失）
- GAP-INT-002: 角色继承权限（接线缺失）⚠️ 已确认已实现
**P1 中等断链（3个）**:
- GAP-FE-005: 批量操作（前端缺失）
- GAP-INT-003: 异常检测接入（接线缺失）
- GAP-INT-004: 密码历史记录检查（接线缺失）⚠️ 已确认已实现
**P2 轻微断链（2个）**:
- GAP-INT-005: IP地理位置解析（接线缺失）
- GAP-INT-006: 设备指纹采集（接线缺失）
---
## 6. 评审流程执行检查清单
### 6.1 每个联调任务启动前
- [ ] 已阅读 `docs/processes/FRONTEND_BACKEND_REVIEW.md`
- [ ] 已阅读 `docs/checklists/FRONTEND_BACKEND_CHECKLIST.md`
- [ ] 已确认 API 接口设计文档
- [ ] 已确认数据模型定义
- [ ] 已明确负责人和时间表
### 6.2 每个联调任务进行中
- [ ] 已定期进行联调问题评审
- [ ] 已记录所有发现的问题
- [ ] 已对问题进行分级
- [ ] 已确定解决方案和时间表
### 6.3 每个联调任务结束前
- [ ] 已完成所有 P0/P1 问题修复
- [ ] 已完成联调测试
- [ ] 已通过上线前评审
- [ ] 已更新相关文档
---
## 7. 工具和命令
### 7.1 后端验证
```bash
# 运行测试
cd d:/project && go test ./... -count=1
# 代码检查
cd d:/project && go vet ./...
# 编译检查
cd d:/project && go build ./cmd/server
```
### 7.2 前端验证
```bash
# 运行测试
cd frontend/admin && npm test
# Lint 检查
cd frontend/admin && npm run lint
# 构建检查
cd frontend/admin && npm run build
# E2E 测试
cd frontend/admin && npm run e2e:full:win
```
### 7.3 文档检查
- [ ] API 文档已更新（如有变更）
- [ ] 数据模型文档已更新（如有变更）
- [ ] 部署文档已更新（如有变更）
- [ ] README 已更新（如有变更）
---
## 8. 常见问题
### Q1: 如果发现前后端设计不一致怎么办？
**A**:
1. 立即记录问题到联调问题列表
2. 标记为 P1 问题
3. 召开评审会议讨论解决方案
4. 确定统一的设计规范
5. 前后端同步修改
### Q2: 如果测试通过率 < 95% 怎么办？
**A**:
1. 不能上线
2. 分析失败原因
3. 优先修复 P0/P1 问题
4. 重新测试
5. 直到通过率 ≥ 95%
### Q3: 如果存在性能问题怎么办？
**A**:
1. 记录性能测试数据
2. 分析瓶颈（数据库、网络、前端渲染）
3. 制定优化方案
4. 实施优化
5. 重新测试验证
---
## 9. 质量指标
### 9.1 联调质量指标
- **测试通过率**: ≥ 95%
- **P0 问题数**: 0
- **P1 问题数**: 0（上线前）
- **接口响应时间**: < 500ms（查询），< 1000ms（写入）
- **代码覆盖率**: > 70%
### 9.2 持续改进
每个 Sprint 结束后进行评审流程复盘：
- [ ] 收集团队反馈
- [ ] 分析问题根因
- [ ] 优化评审流程
- [ ] 更新检查清单
---
## 10. 附录
### 10.1 相关文档
- [前后端联调评审流程](../processes/FRONTEND_BACKEND_REVIEW.md)
- [前后端联调检查清单](../checklists/FRONTEND_BACKEND_CHECKLIST.md)
- [代码审查标准](../code-review/CODE_REVIEW_STANDARD.md)
- [生产环境检查清单](../team/PRODUCTION_CHECKLIST.md)
### 10.2 联系方式
- **后端负责人**: [待填写]
- **前端负责人**: [待填写]
- **测试负责人**: [待填写]
- **技术负责人**: [待填写]
---
**最后更新**: 2026-04-02
**审核状态**: ✅ 已审核通过