第三次团队作业：需求改进&系统设计

第三次团队作业：需求改进&系统设计

团队名称：洛珈山下

日期：2025-11-22

本周工程目标

维度	目标
对齐进度	将第二次作业“校正后的安排”细化为可执行任务并分配到人
接口落地	给出“已冻结”的 RESTful 接口文档（路径、请求/响应、错误码、Mock）
前端联调	输出Mock 服务器（基于 Vite+Express）与真接口并行方案
测试左移	为每个接口写出单元测试用例（gtest/doctest）与Postman 集合
风险闭环	建立每日 Stand-up 模板与燃尽图追踪机制

题目任务

1. 需求&原型改进：（20分）

1.1按照老师的问题进行修改：（5分）

老师没有提出任何问题，这里不用进行修改。

1.2修改完善上周提交的需求规格说明书（10分）

1.2.1：我们把第12周的任务计划详细的写出来了，并放到了前面，并没有直接在原版上修改
1.2.2：我们分好了小组，分割好了任务，每个小组都有自己的工作：
后端任务分割

组别	接口列表（完整路径）	预计工时	备注（可先Mock）
后端A组（用户 + 收藏 + 通知）	- POST /api/v1/users/register - POST /api/v1/users/login - GET /api/v1/users/me - PUT /api/v1/users/me - POST /api/v1/collections - DELETE /api/v1/collections/{merchant_id} - GET /api/v1/users/me/collections - GET /api/v1/notifications - PUT /api/v1/notifications/{id}/read - PUT /api/v1/notifications/read-all	6-8天	最独立，先做完可供前端登录使用
后端B组（商户核心 + 管理员审核）	- POST /api/v1/merchants（创建待审核） - GET /api/v1/merchants（列表，支持?category_id=&campus=） - GET /api/v1/merchants/{id}（详情） - GET /api/v1/admin/merchants/pending - PUT /api/v1/admin/merchants/{id}/approve - PUT /api/v1/admin/merchants/{id}/reject（带reject_reason）	7-9天	商户主流程，核心
后端C组（点评 + 互动）	- POST /api/v1/reviews（发布点评） - GET /api/v1/merchants/{id}/reviews - POST /api/v1/reviews/{id}/like - POST /api/v1/reviews/{review_id}/replies（一级回复） - GET /api/v1/reviews/{review_id}/replies	7-9天	点评互动，依赖商户存在
前端任务分割
组别	负责人	页面列表（路由）	预计工时
-----------------------------------------------------	------	------------------------------------------------------------	--------
前端A组（登录 + 我的 + 通知 + 收藏）	FE1	- /login 登录页 - /register 注册页 - /pages/my/index 个人中心 - /pages/my/collections 我的收藏 - /pages/my/reviews 我的点评（可选） - /pages/notification/list 通知中心	8-10天
前端B组（首页 + 商户 + 点评 + 发布 + 管理员后台）	FE2	- /pages/index/index 首页 - /pages/category/list 分类列表 - /pages/merchant/detail 商户详情（含点评列表） - /pages/review/post 发布点评页 - /pages/review/detail 点评详情页（含回复） - /pages/admin/* 管理员后台全部页面	10-12天

人员分组

小组	人员	任务
后端1组	齐思贤，阿里亚	后端A组
后端2组	袁镇清，谢嘉骏	后端C组
前端组	彭文昊，张嘉铭	前端A，B组
运维与管理人员	林旭坚	管理工程，“救火队长”

1.3参考《构建之法》5节功能的定位和优先级，给出功能分析的四个象限（2分）

象限	类型	描述	示例功能
第一象限	杀手级（高优先、高差异）	核心竞争力，独特卖点	匿名点评、楼中楼回复、实时评分更新、智能商户推荐
第二象限	外围级（低优先、低差异）	基础支持，非核心	管理员操作日志、数据统计导出、系统设置
第三象限	必要级（高优先、低差异）	必须有，但无差异	用户注册/登录、商户信息展示、基础点评发布
第四象限	辅助级（低优先、高差异）	锦上添花，可后期加	点评情感分析、用户行为画像、高级搜索筛选

1.4根据修改后的需求，调整任务分解WBS及相应的项目进度计划（3分）

我们现在任务已经分配下去了，现在已经通知每个团队，先进行自己的高优先任务。（举例：齐思贤先进行登录和注册，袁镇清进行楼中楼服务）

2. 系统设计：（50分）

2.1如何才能最大限度地实现这些需求，这就是架构设计要解决的问题。请给出系统的架构设计

分层说明：

2.1.1：前端层：客户端层（Client Layer）

职责（解决什么问题）：用户交互界面，发起 HTTP/HTTPS 请求。

2.2.2： API 网关层（Gateway Layer）

职责（解决什么问题）：统一入口，路由转发，抵御ddos攻击等。

2.2.3 后台层：微服务层（Microservice Layer）

因为后台有7部分，所以用一张表格加以描述：

服务名称	职责
User Service	用户注册、登录、信息管理
Merchant Service	商户信息管理、审核状态
Review Service	点评发布、点赞、回复
Collection Service	用户收藏管理
Search Service	全文检索（商户、点评）
Notification Service	消息推送、通知管理
Audit Service	商户/点评审核、权限控制

2.2.4 数据层（Data Layer）

职责（解决什么问题）：存储数据，供后台使用。

2.2完成团队项目的数据库设计，并在随笔中提供相应ER图（如果必要）

ER图如下：

这是一个可行的数据库设计：

用户方面：

-- 用户表
CREATE TABLE user (
    id BIGINT PRIMARY KEY COMMENT '主键（可以用雪花算法生成）',
    student_id VARCHAR(20) UNIQUE NOT NULL COMMENT '学号，唯一标识',
    password_hash VARCHAR(255) NOT NULL COMMENT '加密的密码哈希值，这里用BCrypt加密',
    nickname VARCHAR(50) NOT NULL COMMENT '用户昵称',
    avatar_url VARCHAR(500) DEFAULT '' COMMENT '用户头像URL地址',
    role ENUM('user', 'admin') DEFAULT 'user' COMMENT '用户角色：user-普通用户，admin-管理员',
    review_count INT DEFAULT 0 COMMENT '用户发表的点评数量',
    collection_count INT DEFAULT 0 COMMENT '用户收藏的商家数量',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '记录创建时间',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '记录最后更新时间'
);

-- 用户收藏表
CREATE TABLE collection (
    id BIGINT PRIMARY KEY COMMENT '收藏记录ID，主键',
    user_id BIGINT NOT NULL COMMENT '用户ID，外键关联user表',
    merchant_id BIGINT NOT NULL COMMENT '商家ID，外键关联merchant表',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '收藏创建时间',
    UNIQUE KEY uk_user_merchant (user_id, merchant_id) COMMENT '用户与商家唯一索引，防止重复收藏',
    FOREIGN KEY (user_id) REFERENCES user(id),
    FOREIGN KEY (merchant_id) REFERENCES merchant(id)
);

商户方面：

-- 商户分类表
CREATE TABLE merchant_category (
    id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键ID',
    name VARCHAR(50) NOT NULL COMMENT '分类名称：食堂/超市/教学楼/图书馆...',
    description VARCHAR(200) COMMENT '分类描述',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间'
);

-- 商户表
CREATE TABLE merchant (
    id BIGINT PRIMARY KEY COMMENT '主键ID，可以使用雪花算法生成',
    name VARCHAR(100) NOT NULL COMMENT '商户名称',
    campus VARCHAR(50) NOT NULL COMMENT '所属校区：东校区/西校区...',
    category_id BIGINT NOT NULL COMMENT '商户分类ID，关联merchant_category表',
    address VARCHAR(200) COMMENT '商户详细地址',
    business_hours VARCHAR(100) COMMENT '营业时间',
    avg_score DECIMAL(2,1) DEFAULT 0.0 COMMENT '平均评分',
    review_count INT DEFAULT 0 COMMENT '评价数量',
    collection_count INT DEFAULT 0 COMMENT '收藏数量',
    status TINYINT DEFAULT 10 COMMENT '状态：10-待审核,20-已审核,30-已驳回',
    create_user_id BIGINT NOT NULL COMMENT '创建用户ID，关联user表',
    tags JSON COMMENT '标签数组，存储商户标签信息',
    images JSON COMMENT '图片URL数组，存储商户相关图片',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (category_id) REFERENCES merchant_category(id),
    FOREIGN KEY (create_user_id) REFERENCES user(id)
);

点评互动相关方面：

-- 点评表
CREATE TABLE review (
    id BIGINT PRIMARY KEY COMMENT '本身的ID（默认雪花id）',
    merchant_id BIGINT NOT NULL COMMENT '商家ID',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    score DECIMAL(2,1) NOT NULL COMMENT '评分：1.0-5.0',
    content TEXT NOT NULL COMMENT '点评内容',
    images JSON COMMENT '图片URL数组',
    tags JSON COMMENT '标签数组',
    anonymous BOOLEAN DEFAULT FALSE COMMENT '是否匿名',
    like_count INT DEFAULT 0 COMMENT '点赞数',
    reply_count INT DEFAULT 0 COMMENT '回复数',
    status TINYINT DEFAULT 1 COMMENT '1-正常,10-待审核,20-隐藏',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    FOREIGN KEY (merchant_id) REFERENCES merchant(id),
    FOREIGN KEY (user_id) REFERENCES user(id)
) COMMENT = '用户点评表';

-- 点评点赞表
CREATE TABLE review_like (
    id BIGINT PRIMARY KEY COMMENT '本身的ID（默认雪花ID）',
    user_id BIGINT NOT NULL COMMENT '用户ID',
    review_id BIGINT NOT NULL COMMENT '点评ID',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    UNIQUE KEY uk_user_review (user_id, review_id) COMMENT '用户-点评唯一索引',
    FOREIGN KEY (user_id) REFERENCES user(id),
    FOREIGN KEY (review_id) REFERENCES review(id)
) COMMENT = '点评点赞表';

-- 回复表（支持楼中楼）
CREATE TABLE reply (
    id BIGINT PRIMARY KEY COMMENT '本身的ID（默认雪花ID）',
    review_id BIGINT NOT NULL COMMENT '点评ID',
    user_id BIGINT NOT NULL COMMENT '回复用户ID',
    to_reply_id BIGINT COMMENT 'NULL=回复点评,有值=回复用户',
    to_user_id BIGINT COMMENT '被回复的用户ID',
    content TEXT NOT NULL COMMENT '回复内容',
    like_count INT DEFAULT 0 COMMENT '点赞数',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    FOREIGN KEY (review_id) REFERENCES review(id),
    FOREIGN KEY (user_id) REFERENCES user(id),
    FOREIGN KEY (to_reply_id) REFERENCES reply(id),
    FOREIGN KEY (to_user_id) REFERENCES user(id)
) COMMENT = '点评回复表';

3. Alpha任务分配计划

3.1依据项目组能提供的总时间、功能模块的优先级以及模块之间的依赖关系，在Product Backlog中选取待实现的功能项。(5分）

我们团队基于明确的系统设计，我们制定了清晰的任务分配计划，以实现高效并行开发：
前端开发组（张嘉铭、彭文昊）： 负责将确认无误的高保真原型转化为实际代码。具体任务包括：搭建前端项目框架、实现所有静态页面、开发通用UI组件库、并调用后端提供的API接口完成数据渲染与用户交互功能。两人内部可根据功能模块进一步分工，如一人负责用户中心模块，另一人负责业务主流程模块，并定期进行代码审查与整合。
后端开发组（齐思贤、阿丽亚、谢嘉骏、袁镇清）： 负责服务器端业务逻辑、数据库与API的实现。任务包括：搭建后端服务框架、设计并创建数据库表结构、实现核心业务算法、以及编写所有在系统设计中定义的前端所需API接口。
团队将采用“小组功能模块负责制”进行分工，齐思贤和阿丽亚的后端1组负责用户认证与权限管理模块（后端A组）；谢嘉骏和袁镇清的后端2组负责订单或数据处理等核心业务模块（后端C组），确保责任到人。同时，小组需每日进行站会沟通，同步进度并解决协作中的问题。小组之间每两天一次讨论交流，确保相互监督。

3.2对已选择的功能项再做进一步分解，分解为1-10小时左右的任务，构成Sprint Backlog。在PM的协助下，编码的同学对任务进行认领。（5分）

（有的没有认领）

序号	任务卡标题	描述 / 验收标准	后端负责人（团队中的一个人）	前端负责人（团队中的一个人）	计划工时（总工时）
12-1	【用户】登录/注册接口冻结	文档+Mock+单元测试通过	齐思贤	张嘉铭	7 h
12-2	【用户】JWT 中间件 & 全局异常	401/403/429 统一返回	齐思贤	—	6 h
12-3	【商户】创建商户 & 冻结字段	包含审核状态流转	阿丽亚	—	9 h
12-4	【商户】商户详情+列表接口	分页、校区/分类筛选	阿丽亚	彭文昊	5 h
12-5	【点评】发布点评 & 图片上传	OSS 直签+本地 Mock	谢嘉骏	张嘉铭	6 h
12-6	【点评】点赞/取消点赞	Redis INCR + 定时落库	谢嘉骏	—	9 h
12-7	【收藏】收藏/取消收藏	幂等设计	袁镇清	彭文昊	9 h
12-8	【搜索】ES 索引 Mapping	商户 & 点评 2 个索引	袁镇清	—	4 h
12-9	【Mock】前端联调服务器	基于 Vite-plugin-mock	—	张嘉铭	4 h
12-10	【部署】CI 流水线	Go 单元测试+编译镜像	林旭坚	林旭坚	8 h

3.3以甘特图的方式拟定迭代冲刺计划。（10分）

每个后端小组决定自己的冲刺计划，指定自己的甘特图。这里因为沟通耗时，暂时不进行收集。

4. 测试计划（10分）

为保证交付质量，测试工作将贯穿整个Alpha阶段，而非仅在最后进行。

后端测试： 后端开发小组的一位同学在编写代码的同时，另一位同学需要为其负责的模块编写单元测试（如使用JUnit、pytest等），并对核心API进行集成测试，确保接口功能与性能符合预期。这样不技能节约时间，还可以充分发挥结对小组能力。这是开发过程中的首要质量关卡。
前端测试： 前端开发团队将进行充分的界面与交互测试，包括但不限于：跨浏览器兼容性测试、响应式布局测试、用户操作流程测试等。
集成测试： 在前后端功能基本完成后，全体成员将共同参与集成测试。前端与后端紧密配合，按照真实用户场景进行端到端的流程测试，确保系统各个模块能够无缝衔接、稳定运行。所有测试过程中发现的问题将及时记录并快速修复，形成闭环管理。

附件：完整文档已推送至 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