108 lines
5.5 KiB
Markdown
108 lines
5.5 KiB
Markdown
|
# PRD-REQ-通用-006-预生产测试通道
|
|||
|
|
|
|||
|
|
> **版本**: v1.0 | **日期**: 2026-08-11 | **状态**: [待评审]
|
|||
|
|
> **作者**: 宋献（产品） | **审核**: —
|
|||
|
|
> **需求编号**: REQ-通用-006
|
|||
|
|
> **需求类型**: 新增
|
|||
|
|
> **关联模块**: 通用（跨端基础设施）
|
|||
|
|
> **关联文档**:
|
|||
|
|
> - 技术方案: `../../02-技术文档/技术方案-REQ-通用-006-预生产测试通道-v1.0.md`
|
|||
|
|
> - 任务说明书: `../../07-项目管理/任务说明书/任务说明书-REQ-通用-006-预生产测试通道.md`
|
|||
|
|
> - 测试用例: `../../03-测试文档/03-功能测试用例/TC-REQ-通用-006-预生产测试通道.md`
|
|||
|
|
> - 部署方案: `../../04-运维文档/部署运维/DEPLOY-REQ-通用-006-预生产测试通道.md`
|
|||
|
|
> - 关联规范: `00-产品开发流程与文档管理规范.md`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 背景与问题
|
|||
|
|
|
|||
|
|
### 1.1 业务背景
|
|||
|
|
|
|||
|
|
IT 智能服务台三端（用户端 H5、坐席端、管理后台）的登录已统一为**企微 OAuth 扫码认证**（见 `PRD-REQ-认证-统一认证与登录-v1.1.md`），系统无账号密码入口。这带来一个工程问题：
|
|||
|
|
|
|||
|
|
> **自动化测试无法完整执行**——三端登录均需企微扫码/OAuth 交互，脚本无法模拟，导致端到端（E2E）测试链路被阻断。
|
|||
|
|
|
|||
|
|
### 1.2 环境定位决策（2026-08-11 已确认）
|
|||
|
|
|
|||
|
|
| 决策项 | 结论 |
|
|||
|
|
|--------|------|
|
|||
|
|
| 10.90.5.110（itsupport.servyou.com.cn） | 定位为**预生产环境** |
|
|||
|
|
| 未来正式生产 | 单独申请**分布式服务资源**（容器平台/K8s），预生产就绪后域名迁移 |
|
|||
|
|
| 公网暴露面 | **暂不收敛**，待新生产就绪后一次性迁移（过渡期保持现状） |
|
|||
|
|
| 自动化测试落点 | **预生产开启测试通道**（本需求） |
|
|||
|
|
| 生产形态 | 容器平台/K8s（本需求不涉及，另立评估） |
|
|||
|
|
|
|||
|
|
### 1.3 核心矛盾
|
|||
|
|
|
|||
|
|
「预生产仍公网可达」+「预生产开测试通道」两者叠加，若直接启用 `DEV_MODE=true`，**公网任何人可调用 `/api/dev/login` 获取任意角色（含 admin）的有效 token**——比当前登录页暴露严重一个数量级。因此测试通道必须带**访问控制闸门**，不得裸开。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. 需求描述
|
|||
|
|
|
|||
|
|
### 2.1 目标
|
|||
|
|
|
|||
|
|
在预生产环境提供**仅内网可用的免企微登录通道**，支撑自动化测试（后端 API + 前端 E2E）完整执行，同时保证公网无法触达测试后门。
|
|||
|
|
|
|||
|
|
### 2.2 范围（In Scope）
|
|||
|
|
|
|||
|
|
1. 预生产后端启用 `DEV_MODE=true`，挂载既有 `/api/dev/*` 测试端点（login / users / health）
|
|||
|
|
2. nginx 新增 `/api/dev/` 内网 IP 白名单闸门（公网 403）
|
|||
|
|
3. 三端（坐席/管理/H5）登录页新增「测试账号登录」入口（仅内网可见），调 `/api/dev/login` 获取 token 并注入本地会话
|
|||
|
|
|
|||
|
|
### 2.3 非目标（Non-goals）
|
|||
|
|
|
|||
|
|
- ❌ 不新增生产环境的账号密码登录（安全红线，明确排除）
|
|||
|
|
- ❌ 不改动公网域名/WAF 映射（过渡期维持现状）
|
|||
|
|
- ❌ 不改造现有企微 OAuth 主登录流程（仅新增旁路测试通道）
|
|||
|
|
- ❌ 不涉及新生产环境（K8s）的架构改造（另立 REQ 评估）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. 用户故事
|
|||
|
|
|
|||
|
|
- **作为**测试工程师，**我希望**在内网访问预生产时能用测试账号一键登录三端，**以便**完整执行自动化测试而无需企微扫码。
|
|||
|
|
- **作为**安全管理员，**我希望**公网无法访问任何测试后门接口，**以便**测试通道不成为攻击面。
|
|||
|
|
- **作为**运维人员，**我希望**测试通道可一键开关（环境变量/nginx 配置），**以便**新生产上线时可干净撤离。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. 验收标准
|
|||
|
|
|
|||
|
|
| # | 验收项 | 判定 |
|
|||
|
|
|---|--------|------|
|
|||
|
|
| AC-1 | 内网调用 `GET /api/dev/login?userid=dev-agent-001&role=agent` | 返回有效 token（Redis 可校验），HTTP 200 |
|
|||
|
|
| AC-2 | 公网调用 `/api/dev/*` | HTTP 403（nginx 闸门拦截），且非 `/api/dev/` 前缀业务接口不受影响 |
|
|||
|
|
| AC-3 | 前端测试登录入口（坐席/管理/H5） | 内网可一键登录并进入业务页；登录后业务 API 携带 token 正常响应 |
|
|||
|
|
| AC-4 | 既有企微扫码登录 | 不受影响，回归通过 |
|
|||
|
|
| AC-5 | 预生产环境配置可追溯 | `DEV_MODE` 注入方式、nginx 闸门配置均落文档，可回滚 |
|
|||
|
|
| AC-6 | 生产环境安全隔离 | 新生产环境默认 `DEV_MODE=false`，不包含测试通道配置 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. 技术约束与依赖
|
|||
|
|
|
|||
|
|
- 后端 `/api/dev/login` 已存在（`app/api/dev_auth.py`），**零后端开发**，仅配置启用；接口内部有 `_dev_mode_enabled()` 二次校验
|
|||
|
|
- 前端 token 存储：坐席 `localStorage.TOKEN_KEY`、H5 `localStorage.h5_token`、管理后台同构——测试登录需复用同一存储键
|
|||
|
|
- nginx 闸门依赖内网网段规划（10/8、172.16/12、192.168/16）
|
|||
|
|
- 依赖 `jumpserver-V2` 工具链完成预生产配置变更与验证
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. 风险
|
|||
|
|
|
|||
|
|
| 风险 | 等级 | 缓解 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| DEV_MODE 误入生产 | 高 | compose 显式注入 + `.dockerignore` 排除 `.env`（已有）+ 上线 checklist 检查 |
|
|||
|
|
| 闸门配置错误导致公网可访问 dev 接口 | 高 | 部署后必须公网/内网双向 curl 验证（AC-2） |
|
|||
|
|
| 前端测试入口内网判定失效（如内网 IP 变化） | 中 | 判定逻辑与 nginx 闸门同源（内网网段常量），配置化 |
|
|||
|
|
| 测试数据污染预生产 | 中 | 测试账号使用独立 userid 前缀（dev-*），与真实账号隔离 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. 变更记录
|
|||
|
|
|
|||
|
|
| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|
|||
|
|
|------|------|----------|--------|----------|
|
|||
|
|
| 2026-08-11 | v1.0 | 初版 | 宋献 | 预生产测试通道需求确认 |
|