# 职引 — 技术架构文档 v4.0

> **版本**: v4.0
> **日期**: 2026-06-09
> **状态**: Phase 0.5 完成
> **定位**: 应届生/实习生 AI 面试教练

---

## 一、技术栈

### 1.1 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| uni-app | 3.x | 跨端框架（微信小程序 + H5） |
| Vue | 3.4 | 框架 |
| TypeScript | 5.x | 类型安全 |
| Vite | 5.x | 构建工具 |

### 1.2 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Node.js | 18+ | 运行环境 |
| NestJS | 10.x | 框架 |
| MongoDB + Mongoose | 7.x | 数据库 |
| JWT | - | 认证 |
| class-validator | - | 参数校验 |

### 1.3 AI 能力

| 技术 | 用途 | 优先级 |
|------|------|--------|
| opencode-go (deepseek-v4-flash) | 面试模拟、简历诊断、报告 | 主用 |
| NVIDIA (stepfun-ai/step-3.5-flash) | 主用不可用时自动切换 | 备用 |

### 1.4 部署

| 技术 | 用途 |
|------|------|
| 腾讯云轻量应用服务器 | 后端部署（已 ICP 备案） |
| Nginx | 反向代理（HTTPS 终止） + H5 静态文件服务 |
| PM2 | 进程管理 |

**生产域名**：
| 域名 | 用途 | 指向 |
|------|------|------|
| `zhiyinwx.yzrcloud.cn` | 后端 API（小程序服务端 + H5 API） | Nginx → `localhost:3006` |
| `zhiyin.yzrcloud.cn` | H5 网页端 | `/www/wwwroot/zhiyin.yzrcloud.cn` |

---

## 二、项目结构

```
zhiyin/
├── zhiyin-app/                    # 小程序前端
│   └── src/
│       ├── pages/                 # 16 个页面
│       │   ├── index/             # 首页（Tab: 面试）
│       │   ├── interview/         # 面试模拟
│       │   ├── report/            # 面试报告
│       │   ├── history/           # 历史记录（Tab: 面经）
│       │   ├── user/              # 个人中心（Tab: 我的）
│       │   ├── login/             # 登录/注册
│       │   ├── member/            # 会员中心
│       │   ├── progress/          # 进步轨迹雷达图
│       │   ├── contribute/        # 面经贡献
│       │   ├── resume/            # 简历诊断/优化
│       │   ├── result/            # 优化结果
│       │   ├── internship/        # 实习搜索
│       │   ├── admin/             # 管理后台
│       │   ├── about/             # 关于
│       │   ├── agreement/         # 用户协议
│       │   └── privacy/           # 隐私政策
│       ├── services/api.ts        # API 服务封装
│       ├── config.ts              # 全局配置/端点定义
│       ├── pages.json             # 路由表（3 Tab + 13 页面）
│       └── manifest.json          # 小程序配置
│
├── backend/                       # 后端服务 (NestJS)
│   └── src/
│       ├── main.ts                # 入口（端口 3006, 前缀 /api）
│       ├── app.module.ts          # 根模块（导入全部 14 个子模块）
│       ├── common/                # 公共模块
│       │   ├── decorators/        # @CurrentUser, @Public
│       │   ├── guards/            # JwtAuthGuard
│       │   ├── strategies/        # JwtStrategy
│       │   └── filters/           # AllExceptionsFilter
│       └── modules/               # 15 个业务模块
│           ├── user/              # 用户（手机/邮箱/密码/微信登录）
│           ├── interview/         # AI 面试（核心，含进度追踪）
│           ├── ai/                # AI 调用封装（主/备切换）
│           ├── analyze/           # 简历诊断/优化 AI 分析
│           ├── resume/            # 简历 CRUD
│           ├── member/            # 会员套餐/状态
│           ├── payment/           # 微信支付 v3（签名/解密/回调）
│           ├── positions/         # 热门岗位维护
│           ├── upload/            # 文件上传
│           ├── admin/             # 管理后台 API
│           ├── email/             # 邮件发送
│           ├── progress/          # 进步轨迹四维统计
│           ├── contribution/      # 面经贡献 + 公司题库
│           ├── daily-question/    # 每日一题（待完善推送）
│           └── schemas/           # 共享数据模型（5 个 schema）
│
└── docs/                          # 项目文档
    ├── PRODUCT-PLAN.md
    ├── ARCHITECTURE.md
    ├── FEATURE-LIST.md
    ├── ROADMAP.md
    ├── PROJECT-STATUS.md
    ├── DEPLOYMENT.md
    └── WECHAT-CHECKLIST.md
```

---

## 三、数据模型

### 3.1 用户 (User)
```
phone, wxOpenid, email, password, nickname, avatar
plan (free/growth), remaining, vipExpireAt
role (user/admin), isSystemAdmin
interviewCount
```

### 3.2 面试 (Interview)
```
userId, position, status (in_progress/completed)
messages[{role, content, score, feedback, suggestion}]
totalScore, questionCount
summary{dimensionScores{logic,expression,professionalism,stability}, strengths, weaknesses, suggestions}
```

### 3.3 进步轨迹 (Progress)
```
userId, totalInterviews, completedInterviews
avgLogic, avgExpression, avgProfessionalism, avgStability
streak, lastInterviewDate, streakHistory
recentScores[{interviewId, date, position, totalScore, dimensions}]
```

### 3.4 面经贡献 (Contribution)
```
userId, interviewId, company, position, rounds, questions, experience, tags, verified
```

### 3.5 公司题库 (CompanyBank)
```
company, position
questions[{content, type, referenceAnswer, difficulty, frequency, tags}]
contributionCount, viewCount
```

### 3.6 每日一题 (DailyQuestion)
```
position, question, referenceAnswer, category, date, pushed
```

### 3.7 支付订单 (PaymentOrder)
```
outTradeNo, userId, amount, status, channel (native/jsapi)
paidAt, wxTransactionId, refundAmount, refundedAt
```

### 3.8 简历/岗位
```
Resume: userId, title, originalContent, targetPosition
HotPosition: name, salary, company, icon, sort, active
```

---

## 四、API 接口总览

### 4.1 用户 (prefix: `/api/user`)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/send-code` | 发送手机验证码 |
| POST | `/login` | 手机号+验证码登录 |
| POST | `/send-email-code` | 发送邮箱验证码 |
| POST | `/email-login` | 邮箱+验证码登录 |
| POST | `/password-login` | 邮箱+密码登录 |
| POST | `/register` | 邮箱+密码注册 |
| POST | `/wx-login` | 微信静默登录 |
| GET | `/info` | 获取用户信息 |
| PUT | `/update` | 更新用户信息 |
| GET | `/usage` | 获取使用额度 |
| POST | `/set-password` | 设置密码 |

### 4.2 面试 (prefix: `/api/interview`)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/create` | 创建面试 |
| POST | `/:id/answer` | 提交回答 |
| POST | `/:id/complete` | 完成面试生成报告 |
| GET | `/:id` | 获取面试详情 |
| GET | `/list/all` | 面试历史列表 |
| GET | `/stats/mine` | 用户统计 |

### 4.3 简历/AI 分析 (prefix: `/api/analyze`, `/api/resume`)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/analyze/diagnosis` | AI 简历诊断 |
| POST | `/analyze/optimize` | AI 简历优化 |
| POST | `/resume/create` | 创建简历 |
| GET | `/resume/list` | 简历列表 |
| DELETE | `/resume/:id` | 删除简历 |

### 4.4 会员/支付 (prefix: `/api/member`, `/api/payment`)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/member/plans` | 套餐配置 |
| GET | `/member/status` | 会员状态 |
| POST | `/member/pay` | ⚠️ 开发绕过（上线前移除） |
| POST | `/payment/create` | 创建 Native 支付订单 |
| POST | `/payment/jsapi` | 创建 JSAPI 支付 |
| POST | `/payment/notify` | 微信支付回调 |
| POST | `/payment/query` | 查询订单状态 |

### 4.5 Phase 0.5 (prefix: `/api/progress`, `/api/contribution`, `/api/daily-question`)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/progress` | 进步轨迹数据 |
| GET | `/progress/stats` | 进步轨迹统计 |
| POST | `/contribution` | 提交面经贡献 |
| GET | `/contribution/my` | 我的贡献列表 |
| GET | `/contribution/company/:c/position/:p` | 公司题库查询 |
| GET | `/contribution/company/:c` | 公司岗位列表 |
| GET | `/daily-question` | 获取每日一题 |
| GET | `/daily-question/position/:p` | 按岗位获取题目 |

### 4.6 其他
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/positions/hot` | 热门岗位 |
| POST | `/upload` | 文件上传 |
| GET | `/admin/*` | 管理后台接口 |

---

## 五、部署架构

```
微信小程序 (用户端)               H5 浏览器 (用户端)
    ↓ HTTPS                           ↓ HTTPS
zhiyinwx.yzrcloud.cn            zhiyin.yzrcloud.cn
    ↓                                 ↓
Nginx 反向代理 (腾讯云轻量应用服务器)       Nginx 静态文件服务
    ↓                                 ↓
backend (NestJS :3006)              /www/wwwroot/zhiyin.yzrcloud.cn/
    ↓
MongoDB Atlas / 自建 MongoDB
    ↓
AI API (opencode-go → NVIDIA 主备切换)
```

---

## 六、安全与合规

- ✅ ICP 备案已完成
- ✅ AI 深度合成类目已通过
- ✅ JWT 认证全局守卫（白名单接口 @Public 放行）
- ✅ 请求限流 (10次/分钟)
- ⚠️ 生产环境需配置：强 JWT_SECRET、CORS 白名单、HTTPS、移除固定验证码

---

## 变更记录

| 日期 | 变更内容 | 操作人 |
|------|----------|--------|
| 2026-05-14 | 初版 | AI |
| 2026-06-01 | 重新架构：专注校招 | AI |
| 2026-06-09 | 全面重写：匹配真实 15 模块 + 16 页面 + API 清单 | AI |
| 2026-06-09 | 更新部署架构：添加生产域名 zhiyinwx.yzrcloud.cn / zhiyin.yzrcloud.cn | 小之 |