diff --git a/FinalHomework/hzh_doc/思维导图.md b/FinalHomework/hzh_doc/思维导图.md new file mode 100644 index 0000000..17bc51f --- /dev/null +++ b/FinalHomework/hzh_doc/思维导图.md @@ -0,0 +1,323 @@ +--- +tags: [全栈开发, 大作业, gRPC, Gin, OSS, Eino] +create time: 2026-05-09 13:25 +--- + +# 大作业·思维导图 — 双端 gRPC HR 系统 + +## 概述 + +本文档以思维导图和架构图表的形式，梳理全栈大作业的核心知识点与任务拆解。涵盖**技术架构、前后端功能、数据流转、关键考点**四大模块，帮助你快速建立全局认知并定位开发重点。 + +> [!tip] 如何使用本笔记 +> 建议先看「整体知识体系」建立全局观，再逐层深入每个分支的细节图表。遇到流程图时，思考：如果我是请求发起方，每一步数据会经历什么？ + +## 整体知识体系 + +```mermaid +mindmap + root((HR招聘系统
全栈大作业)) + 技术架构 + 两层服务 + Web网关(Gin) + Logic业务(gRPC) + 通信协议:gRPC/Protobuf + 前端双端 + HR管理端 + 候选人用户端 + 数据存储 + MySQL:结构化数据 + 私有OSS:简历文件 + AI能力 + Eino框架 + Chat对话组件 + 上下文持久化 + 核心功能 + HR管理端 + JWT登录鉴权 + 岗位CRUD(本人范围) + 投递候选人查看 + AI智能对话 + 自然语言转数据查询 + 历史记录留存 + 候选人用户端 + 游客免登录浏览 + 注册登录(强校验) + 结构化档案编辑 + PDF/DOC/DOCX简历上传 + 签名URL直传OSS + 关键考点 + gRPC分层调用 + 禁止同工程直连 + 只允许跨服务调用 + OSS签名URL + 不落地缓存 + 严格格式白名单 + Eino基础对接 + 不能裸写HTTP + 数据到上下文到模型到回答 + 权限隔离 + JWT统一签发 + 角色精准管控 + 提交要求 + 源码仓库 + final_homework根目录 + api/db/README文档齐全 + 演示视频 + 全链路实操录制 + 口述两大核心技术点 + 禁止剪辑拼接 + 拓展方案 + answer.md设计思路 + OpenClaw/Hermes集成 +``` + +> [!note] 图表阅读提示 +> 这是整份作业的"导航图"——所有分支都来自项目要求文档。每个主分支下的二级节点对应一个开发阶段，三级节点是具体实现细节。 + +## 一、技术架构详解 + +### 1.1 两层微服务架构 + +> [!question] 为什么不用传统单体架构？ +> 如果所有逻辑写在一个 Gin 工程里，代码耦合严重、难以扩展。拆分成 Web + Logic 两层，职责清晰，也贴合真实生产环境的微服务实践。 + +```mermaid +flowchart LR + subgraph Frontend ["前端层"] + HR["HR管理端，独立路由页面"] + User["候选人用户端，独立路由页面"] + end + + subgraph WebLayer ["Web网关层，Gin服务 web-gin-service"] + Route["路由分发"] + CORS["全局跨域处理"] + Auth["JWT统一鉴权"] + Validate["参数合法性校验"] + end + + subgraph LogicLayer ["Logic业务层，gRPC服务 logic-grpc-service"] + UserMgmt["用户权限管控"] + JobBiz["岗位业务处理"] + OSSSign["OSS签名调度"] + DataRW["MySQL数据读写"] + EinoAI["Eino AI对话封装"] + end + + subgraph Storage ["存储层"] + MySQL[(MySQL数据库)] + OSS[(私有OSS Bucket)] + end + + HR -->|"HTTP REST"| WebLayer + User -->|"HTTP REST"| WebLayer + WebLayer -.->|"gRPC远程调用"| LogicLayer + LogicLayer --> MySQL + LogicLayer --> OSS + EinoAI -->|"查询MySQL，推送大模型，返回回答"| LogicLayer + + style Frontend fill:#e1f5fe + style WebLayer fill:#fff3e0 + style LogicLayer fill:#e8f5e9 + style Storage fill:#fce4ec +``` + +### 1.2 请求处理全流程 + +> [!example] 思考题 +> 从候选人点击"投递简历"到文件安全存到 OSS，整个链路经过哪些组件？每个环节做了什么校验？尝试在脑中走一遍流程，这就是考试时需要口述的内容。 + +```mermaid +sequenceDiagram + participant U as U_CandidateFrontend + participant W as W_WebService + participant L as L_LogicService + participant M as M_MySQL + participant O as O_OSS + + U->>W: "POST /api/profile，提交结构化档案" + W->>W: JWT校验加参数合法性校验 + W->>L: gRPC UpdateProfile request + L->>M: UPDATE user_profile SET ... + M-->>L: 操作结果 + L-->>W: RPC response + W-->>U: code 200 msg success + + Note over W,O: 简历上传流程 + + U->>W: "POST /api/resume/upload，PDF DOC或DOCX" + W->>W: JWT校验加后缀加文件头白名单 + W->>L: gRPC GenOssSign key ext + L-->>W: UploadURL DownloadURL Expiry + W-->>U: 签名URL信息 + + U->>O: PUT直接上传到OSS，不走服务端 + O-->>U: 上传完成，本地零缓存 +``` + +### 1.3 AI 对话链路 + +> [!warning] 底线要求 +> 必须使用 Eino 框架，禁止裸写 HTTP 接口直连大模型。Eino 只是轻量级封装，主要做两件事：**拼接业务上下文** 和 **调用大模型**。 + +```mermaid +flowchart TD + A["HR在AI窗口输入自然语言提问"] --> B{后端解析意图} + B --> C["提取查询条件，如岗位ID或筛选标签"] + C --> D["查询MySQL获取真实数据"] + D --> E["拼接标准模板"] + E --> F["Prompt = 业务上下文 + 原始问题"] + F --> G["Eino Chat推送大模型"] + G --> H{大模型返回} + H --> I["规范化自然语言回答"] + I --> J["存入对话历史表，绑定HR账号ID"] + J --> K["返回给前端展示"] + + style A fill:#e1f5fe + style D fill:#fff3e0 + style G fill:#e8f5e9 + style I fill:#ce93d8 + style J fill:#ffcdd2 +``` + +## 二、前后端功能矩阵 + +### 2.1 HR 管理端 + +```mermaid +stateDiagram-v2 + [*] --> Login: 游客状态 + Login --> Dashboard: JWT校验通过 + Dashboard --> JobCreate: 新建岗位 + Dashboard --> JobEdit: 编辑下架个人岗位 + Dashboard --> CandidateList: 查看岗位下候选人 + CandidateList --> ProfileView: 查看结构化档案 + ProfileView --> ResumeView: 查看OSS简历链接 + Dashboard --> AIChat: 打开AI对话窗口 + AIChat --> AIQuery: 自然语言提问 + AIQuery --> AIResult: 返回统计回答 + AIResult --> AIChat: 写入历史 + state 权限边界 { + Dashboard: 只能操作自己发布的岗位 + JobCreate: 发布时关联当前HR ID + JobEdit: 校验岗位创建者等于当前用户 + } +``` + +### 2.2 候选人用户端 + +```mermaid +stateDiagram-v2 + [*] --> BrowseJobs: 游客免登录浏览 + BrowseJobs --> Register: 看到投递按钮才需登录 + Register --> Login: 完成注册 + Login --> ProfileSetup: 首次登录引导完善档案 + ProfileSetup --> ResumeUpload: 上传合规简历 + ResumeUpload --> ApplyJob: 满足条件才能投递 + state 投递校验 { + ProfileSetup: 必填 姓名电话学历院校经历技能 + ResumeUpload: 仅PDF DOC DOCX三种格式 + ApplyJob: 未完善资料或无简历 拦截弹窗 + } + ApplyJob --> [*]: 投递成功 + BrowseJobs --> ApplyJob: 未登录直接投递 跳转登录 +``` + +## 三、数据结构概览 + +### 3.1 核心实体关系 + +```mermaid +erDiagram + USER ||--o{ JOB : "发布" + JOB ||--o{ APPLICATION : "收到" + USER ||--o{ PROFILE : "拥有" + USER ||--o{ CHAT_RECORD : "发起" + PROFILE ||--|| RESUME : "包含" + + USER { + uint64 id "PK" + string username "UK" + string password_hash + string role "hr / candidate" + datetime created_at + } + + JOB { + uint64 id "PK" + uint64 creator_id "FK" + string title + string description + string status "on / off" + datetime created_at + } + + APPLICATION { + uint64 id "PK" + uint64 job_id "FK" + uint64 candidate_id "FK" + datetime applied_at + } + + PROFILE { + uint64 id "PK" + uint64 user_id "UK" + string name + string phone + string education + string school + text experience + string skills + } + + CHAT_RECORD { + uint64 id "PK" + uint64 hr_id "FK" + text question + text ai_reply + datetime created_at + } +``` + +### 3.2 技术选型清单 + +| 层级 | 技术 | 用途 | +|------|------|------| +| 前端 × 2 | 任意（Vue/React均可） | HR管理端 + 候选人用户端 | +| Web 服务 | Go + Gin | HTTP 网关：路由、鉴权、校验 | +| 通信协议 | Protocol Buffers + gRPC | Web ↔ Logic 唯一通信方式 | +| Logic 服务 | Go + gRPC server | 业务逻辑：权限、岗位、OSS、AI、MySQL | +| 数据库 | MySQL | 用户、岗位、投递、档案、对话历史 | +| 对象存储 | 私有 OSS Bucket | 简历文件签名 URL 直传 | +| AI 框架 | Eino（基础 Chat） | 自然语言问答 + 上下文持久化 | +| 认证 | JWT | 双角色统一令牌签发与校验 | + +## 四、关键考点速查 + +> [!danger] 验收红线（必考） +> 以下条目是评分的关键依据，遗漏任何一项可能导致扣分： + +1. **gRPC 分层**：Web 与 Logic 之间必须是 `gRPC` 远程调用，同工程函数直连 = 不符合架构要求 +2. **OSS 签名 URL**：文件不落地本地，客户端直传 OSS；严格后缀 + 文件头校验 +3. **Eino 框架调用**：不可裸写 HTTP 请求连接大模型，必须通过 Eino 封装 +4. **权限隔离**：JWT 统一签发，HR 只能管理自己发布的岗位，候选人未完善资料不可投递 +5. **AI 对话持久化**：每条问答对入 MySQL，刷新页面自动加载历史上下文 + +## 五、提交 Checklist + +> [!example] 自查清单 +> 在提交前逐项勾选，确保没有遗漏： + +- [ ] 源码位于 `final_homework/` 目录下 +- [ ] 四个子目录完整：`hr-frontend`、`user-frontend`、`web-gin-service`、`logic-grpc-service` +- [ ] `api.md` — 接口说明文档 +- [ ] `db.md` — 数据库设计文档 +- [ ] `README.md` — 启动部署指南 + 项目亮点 +- [ ] 演示视频：原生实操 + 口述两大核心技术点 +- [ ] 视频命名：`姓名_学号_全栈大作业.mp4` +- [ ] `answer.md` — 拓展设计方案（OpenClaw/Hermes 集成思路） +- [ ] `.env` / config 文件中 key 等敏感信息已忽略提交 + +## 关联笔记 + +- [[大作业项目要求]] — 作业完整需求文档 diff --git a/FinalHomework/大作业项目要求.md b/FinalHomework/大作业项目要求.md new file mode 100644 index 0000000..6f88ec3 --- /dev/null +++ b/FinalHomework/大作业项目要求.md @@ -0,0 +1,86 @@ +>[Warning] 此文件为只读，**禁止** AI 工具修改此文件 +## 一、作业考核核心目标 + +1. 掌握 gRPC 两层服务架构调用，只拆分 Web 服务、Logic 业务服务，架构轻量化易上手。 +2. 熟练使用 Gin 开发标准接口，~~实现 JWT 双角色登录~~、权限精准隔离管控。 +3. 完成私有 OSS 全流程对接，使用签名 URL 安全完成简历上传、下载，保障文件访问安全。 +4. 基于 Eino 框架实现前端 AI 对话，联动查询 MySQL 真实业务数据，全程不做向量、不做 RAG、不做简历智能匹配。 +5. 本次不考察docker，前端技术栈随意。 +6. key相关不提交（真实业务中是不需要提交的），提交了也不扣分，做好保护即可。 + +## 二、前后端开发硬性要求 + +### 1. 两套独立前端页面工程 + +1. HR 管理端前端：专属独立路由，包含岗位全量管理、候选人台账查看、AI 智能对话问答窗口。注意：有多个HR账号，随意注册HR或者候选人。一个用户只有一种角色。 +2. 候选人用户端前端：专属独立路由，包含岗位浏览、账号注册登录、个人资料编辑、简历OSS上传、岗位一键投递。 +3. 前端仅负责页面渲染、交互操作、接口请求，所有权限校验、文件处理、AI 逻辑、业务数据读写全部封装在后端，前端禁止写核心业务逻辑。 + +### 2. HR 管理端核心功能细节 + +1. 独立账号密码登录，后端统一签发、校验 JWT 令牌，无令牌禁止访问后台功能。 +2. 自主新增、编辑、下架个人发布的招聘岗位，仅能管理本人创建岗位，无权操作他人岗位。 +3. 分页查看所有岗位对应的投递候选人、结构化个人档案、OSS 云端简历记录。 +4. 前端内置常驻 AI 对话窗口，支持自然语言问答，可查询投递总人数、单岗位投递统计、符合条件候选人筛选、岗位热度数据等MySQL后台真实数据。 +5. AI 对话自动留存聊天记录入库，页面刷新后自动加载历史对话上下文，不丢失交互记录。 + +### 3. 候选人用户端功能 + +1. 游客免登录权限：无需注册、无需登录，即可直接浏览全平台公开岗位列表，无任何权限门槛。 +2. 投递强制校验规则：仅注册并成功登录后，才会展示岗位投递按钮；未完善结构化个人资料、未上传合规简历，直接拦截投递请求，弹窗提示补齐资料。 +3. 结构化个人档案：必填填写姓名、联系电话、最高学历、毕业院校、工作/项目经历、核心技能标签，所有信息实时存入MySQL，支持用户随时前端编辑、后端同步更新。可选功能：简历解析自动填充相关字段。 +4. 简历文件格式强限制：仅支持 PDF、DOC、DOCX 三种标准办公格式，后端严格校验文件后缀与文件头，拦截图片、压缩包、TXT 等非法格式。简历此次只考察OSS上传，不与AI交互。 +5. 合规简历直传私有OSS，生成签名访问链路，本地不缓存、不留存任何简历源文件。 + +## 三、技术架构硬性要求 + +1. Web 服务（Gin 网关层）：仅负责接收前端 HTTP 请求、全局跨域处理、JWT 统一鉴权、请求参数合法性校验，不编写任何核心业务代码，所有能力全部通过 gRPC 远程调用 Logic 服务。 +2. Logic 核心业务服务：集中承载全量后端逻辑，包含用户权限管控、岗位业务处理、私有OSS签名调度、MySQL全量数据读写、Eino AI对话封装，独立部署运行。 +3. 通信强制规范：Web 服务与 Logic 服务之间，只允许 gRPC 远程跨服务调用，禁止同工程本地函数直连调用，守住微服务分层考点。 +4. 数据存储：采用MySQL数据库、岗位数据、候选人结构化档案、岗位投递关联数据、AI对话历史记录。 +5. 文件存储：所有合规简历文件仅归档至私有OSS Bucket，严禁本地文件夹临时存储兜底。 + +## 四、私有 OSS 硬性落地规范 + +1. 学生自主完成OSS平台注册，手动创建专属私有Bucket，彻底关闭匿名访问、公开读权限，保障简历隐私安全。 +2. OSS密钥、访问域名、Bucket名称等敏感配置，统一写入独立配置文件，禁止硬编码写入业务代码提交仓库。 + +## 五、Eino 框架使用规范+AI对话增强细节 + +1. 轻量化使用：仅调用Eino基础Chat对话组件。 +2. AI业务问答固定流程：HR输入自然语言提问 → 后端解析意图查询MySQL真实业务数据 → 拼接标准业务上下文+用户问题 → 调用Eino推送大模型 → 返回规范自然语言统计回答。 +3. 对话持久化增强：每一条HR提问、AI回复自动成对存入MySQL对话历史表，绑定HR管理员账号ID。 +4. 前端会话联动：HR重新进入AI对话页面，自动从MySQL加载过往全部聊天上下文，延续历史问答交互。 +5. 底线要求：必须完整引用Eino框架依赖编程，禁止裸写HTTP接口直连大模型完成AI功能糊弄验收。 + +## 六、标准化目录结构 + +所有代码放到：git根目录/final_homework/ （注意没有homework这一层） + +1. 📁 hr-frontend 文件夹：存放完整HR管理端前端全部源码 +2. 📁 user-frontend 文件夹：存放候选人用户端前端全部源码 +3. 📁 web-gin-service 文件夹：完整Gin Web网关服务工程代码 +4. 📁 logic-grpc-service 文件夹：完整Logic核心业务gRPC服务代码 +5. 📄 api.md：项目接口说明文档，统一规范所有前后端对接接口 +6. 📄 db.md：数据库设计文档，包含所有数据表结构、字段说明、关联关系 +7. 📄 README.md：项目完整启动部署文档，写明环境配置、服务启动顺序、OSS密钥配置方式，项目亮点等 + +## 六、作业提交与视频录制规范要求 + +### 1. 视频硬性录制要求 + +1. 视频：禁止额外剪辑拼接、后期特效包装，保证原生实操画面真实有效。 +2. 视频必录核心内容：完整演示系统全链路核心实操功能；口述讲解本次作业两大核心技术点：两层gRPC服务调用逻辑、私有OSS签名URL安全上传下载；可自愿补充Eino基础对话实操要点、个人开发优化思路，无额外无关冗余内容。 +3. 全程实操配合：后台服务启动、前端页面操作、接口联调等全流程，同步搭配实时语音讲解，禁止无声黑屏静默录制。 + +### 2. 统一提交格式与提交入口 + +1. 视频文件命名强制规范：严格按照格式命名，姓名_学号_全栈大作业.mp4，禁止私自修改命名格式、随意缩写信息。 +2. 固定提交地址：统一线上填报提交，提交入口：[https://f.kdocs.cn/g/Qvi7GT0p/](https://f.kdocs.cn/g/Qvi7GT0p/)，进入【2027届全栈开发实战：大作业提交】WPS表单，按页面提示逐项填写信息、上传视频与配套源码材料。 +3. 表单填报必填项：如实填写本人姓名、对应技术方向、所属学校、完整学号，规范上传合规演示视频，据实填写本次作业收获与开发难点，无特殊疑问正常提交即可。 + +## 七、拓展设计方案思考题（必答，无需编码实现） + +1. 额外新建文件：**answer.md**，专门用来写本题答案。 +2. 设计题目：未来所有的系统都应该可以和AI Agent进行交互和对话。如果需要对接集成到 OpenClaw或者Hermes等三方AI Agent 平台中，请你详细写出完整接入实施方案，只写设计思路与流程，不需要写任何代码实现。 +3. 答题要求：逻辑清晰、步骤完整，所有细节都有考虑到。 \ No newline at end of file