第三次作业：详细设计与接口实现报告

news/2025/11/22 1:07:11/文章来源:https://www.cnblogs.com/aliyaablat/p/19254924

团队名称：洛珈山下
日期：2025-11-22

本次作业目标
| 维度 | 目标 |
| ---- | ---------------------------------------------------------- |
| 对齐进度 | 将第二次作业“校正后的安排”细化为可执行任务并分配到人 |
| 接口落地 | 给出“已冻结”的 RESTful 接口文档（路径、请求/响应、错误码、Mock） |
| 前端联调 | 输出Mock 服务器（基于 Vite+Express）与真接口并行方案 |
| 测试左移 | 为每个接口写出单元测试用例（gtest/doctest）与Postman 集合 |
| 风险闭环 | 建立每日 Stand-up 模板与燃尽图追踪机制 |
本周（第12周）详细任务分解
原则：一张卡一个可交付物，粒度 ≤ 4 h，全部录入 Gitee Issues（标签：week-12）
| 序号 | 任务卡标题 | 描述 / 验收标准 | 后端负责人 | 前端负责人 | 计划工时 |
| ----- | ------------------ | ------------------- | ----- | ----- | ---- |
| 12-1 | 【用户】登录/注册接口冻结 | 文档+Mock+单元测试通过 | 齐思贤 | 张嘉铭 | 4 h |
| 12-2 | 【用户】JWT 中间件 & 全局异常 | 401/403/429 统一返回 | 齐思贤 | — | 3 h |
| 12-3 | 【商户】创建商户 & 冻结字段 | 包含审核状态流转 | 阿丽亚 | — | 5 h |
| 12-4 | 【商户】商户详情+列表接口 | 分页、校区/分类筛选 | 阿丽亚 | 文昊 | 5 h |
| 12-5 | 【点评】发布点评 & 图片上传 | OSS 直签+本地 Mock | 谢嘉骏 | 张嘉铭 | 6 h |
| 12-6 | 【点评】点赞/取消点赞 | Redis INCR + 定时落库 | 谢嘉骏 | — | 3 h |
| 12-7 | 【收藏】收藏/取消收藏 | 幂等设计 | 袁镇清 | 文昊 | 3 h |
| 12-8 | 【搜索】ES 索引 Mapping | 商户 & 点评 2 个索引 | 袁镇清 | — | 4 h |
| 12-9 | 【Mock】前端联调服务器 | 基于 Vite-plugin-mock | — | 张嘉铭 | 4 h |
| 12-10 | 【部署】CI 流水线 | Go 单元测试+编译镜像 | 齐思贤 | — | 3 h |
接口冻结文档（节选）
完整文档已推送至 Gitee Wiki
3.1 用户服务
POST /api/v1/users/register
Request

JSON
{
"student_id": "20211234",
"password": "Abc123456",
"nickname": "珞珈山扛把子"
}

JSON
{
"code": 200,
"message": "注册成功",
"data": { "user_id": 142536172839456256 }
}
异常

code	message	场景
400	学号已存在	DB unique
400	密码强度不足	正则

单元测试（Go）
go
复制
func TestRegisterDuplicate(t *testing.T) {
req := {"student_id":"20211234","password":"Abc123456","nickname":"nick"}
w := httptest.NewRecorder()
router.ServeHTTP(w, httptest.NewRequest("POST", "/api/v1/users/register", strings.NewReader(req)))
assert.Equal(t, 400, w.Code)
assert.Contains(t, w.Body.String(), "学号已存在")
}
3.2 商户服务
POST /api/v1/merchants
Header
Authorization: Bearer
Body
JSON
复制
{
"name": "东区麻辣烫",
"campus": "东校区",
"category_id": 3,
"address": "东区食堂2楼",
"business_hours": "10:00-21:30",
"tags": ["夜宵", "性价比高"],
"images": ["https://cdn.xxx.com/tmp/aaa.jpg"]
}
Response 200
JSON
复制
{
"code": 200,
"message": "提交成功，待审核",
"data": { "merchant_id": 142536199898765312, "status": 10 }
}
3.3 点评服务
POST /api/v1/reviews
Body
JSON
复制
{
"merchant_id": 142536199898765312,
"score": 4.5,
"content": "今天麻辣烫量很大！",
"images": ["https://cdn.xxx.com/review/1.jpg"],
"tags": ["量大", "实惠"],
"anonymous": true
}
Response 200
JSON
复制
{
"code": 200,
"message": "发布成功",
"data": { "review_id": 142536277777777777 }
}
4. 前端 Mock 方案
由张嘉铭统一维护，路径 frontend/mock/
TypeScript
复制
// mock/user.ts
export default [
{
url: '/api/v1/users/register',
method: 'post',
response: ({ body }) => {
if (body.student_id === '20211234') {
return { code: 400, message: '学号已存在' };
}
return { code: 200, data: { user_id: '142536172839456256' } };
},
},
];
启动命令
bash
复制
pnpm dev:mock # 同时启动 Vite + Express-Mock
5. 测试策略

层级	工具	覆盖要求	责任人
单元	Go + testify	核心业务 ≥ 80%	各后端
接口	Postman + Newman	全部 P0 接口	齐思贤
性能	k6	300 并发 < 500 ms	袁镇清
E2E	Cypress	登录→发布点评→点赞主流程	文昊

风险与对策
| 风险 | 触发概率 | 影响 | 对策 | owner |
| ------- | ---- | ---- | -------------------- | ----- |
| 比赛冲突 | 高 | 工时缩水 | 预留 30% buffer & 每日同步 | 齐思贤 |
| ES 学习成本 | 中 | 搜索延期 | 先用 SQLite FTS5 降级 | 袁镇清 |
| OSS 费用 | 低 | 超预算 | 校内 MinIO 替代方案 | 谢嘉骏 |
本周产出清单（验收标准）
Gitee Issues 100% 创建并打标签 week-12
backend/api/ 目录下接口文档 Markdown 与代码同级
backend/mock/ 下线，单元测试通过率 ≥ 80%
frontend/mock/ 可脱离后端独立运行
Postman 集合导出文件 Campus-Review-P0.json 上传至 Wiki
燃尽图每日自动推送（GitHub Action）
下周（13 周）前瞻
点评回复、搜索联调、管理后台页面
第一次 “吃狗粮” 活动：团队成员使用自己系统发布 3 条真实点评
性能压测达标：300 并发 95th < 500 ms