[T.6] 团队项目：技术规格说明书

项目	内容
这个作业属于哪个课程	软件工程
这个作业的要求在哪里	[T.6]技术规格说明书
我在这个课程的目标是	掌握软件工程的核心理论，协作完成软件项目开发
这个作业在哪个具体方面帮助我实现目标	明确技术规格说明书，团队成员完成更高效

一、技术栈

项目整体基于 Web 端实现，适配移动端及平板等大屏设备，项目统一部署至阿里云ECS

• Ubuntu 24.04，2 核 4G，40GB ESSD 云盘，5Mbps 带宽

• 前端：采用Vue 3 (Composition API) + TypeScript作为核心框架，搭配Vite构建工具提升开发与运行效率，Tailwind CSS实现轻量化界面设计，Pinia进行状态管理，确保页面加载流畅、交互便捷，契合用户碎片化使用场景。

• 后端：选用Python + Flask + SQLAlchemy + PostgreSQL技术栈，可快速对接AI接口生成个性化运势、答案内容，同时PostgreSQL数据库能稳定存储用户心情、历史记录、收藏内容等数据，为各页面的留存设计提供数据支撑。

二、软件架构

子系统与模块说明

子系统	模块	功能任务
客户端	UI组件库	实现运势看板、答案之书、个人中心等页面
	状态管理(Pinia)	管理用户登录态、主题、本地缓存的运势数据
	PWA Service Worker	实现静态资源缓存，提供离线回退页面
	工具库	封装网络请求、摇一摇、分享到社交平台、本地存储等能力
服务端	API网关	所有请求的入口，负责路由、限流、跨域处理
	认证鉴权	处理用户登录、Session管理
	运势/答案生成	1. 接收用户请求 2. 构造Prompt 3. 调用LLM API 4. 调用内容审核 5. 结构化返回数据
	内容审核	在AI生成内容和用户分享内容落库前，调用第三方API进行过滤。
	用户与日记	处理用户个人信息、情绪日记、历史记录的增删改查
	分享广场	管理用户公开分享的卡片，提供热门/最新列表查询接口
数据层	PostgreSQL	存储用户表、心情日记表、分享内容表等结构化数据
	对象存储	存储生成的分享卡片图片、前端静态资源
外部服务	LLM API	提供文本生成能力
	内容审核API	提供文本违规检测能力

三、系统开发

3.1 代码设计

数据模型抽象

在数据模型层面，我们将用户抽象为访客用户和注册用户两类。访客用户通过设备ID识别，可以无门槛体验核心功能，而注册用户则能够跨设备同步历史记录与个人偏好。这种设计既降低了新用户的使用门槛，又为后续留存和深度互动打下了基础。

我们将“运势解读”和“答案之书回复”统一抽象为“内容单元”，这样一来，无论是今日运势文案、随机答案，都可以用同一套存储、审核和缓存机制来管理，避免了为每种内容类型重复开发相似的功能模块。

内聚/耦合/模块化

整体架构采用了前后端分离的方式，前端专注于界面交互和用户体验，后端负责业务逻辑、数据存储和外部服务调用，二者通过清晰定义的API接口进行通信。这种分离不仅让前后端团队可以并行开发、独立部署，也使得系统的整体耦合度大大降低。

在模块划分上，我们将系统拆分为运势看板、答案之书、情绪日记、社交广场和用户中心等核心模块，每个模块内部高度内聚。例如，运势看板模块集中了所有与运势计算相关的规则；答案之书模块则独立负责问题接收、随机答案抽取、历史回溯等功能。模块之间的依赖关系被严格限制：它们只传递必要的信息，绝不直接访问彼此的内部状态或数据库连接。

信息隐藏和封装

在后端设计中，我们只向前端暴露一组 API 接口，所有数据库操作、SQL语句以及数据表结构都被隐藏在服务层内部。这种封装使得后端可以在不改变API契约的前提下，随时更换AI供应商、优化查询逻辑或调整缓存策略，也最大程度地避免了信息的泄露。

3.2 代码编写

前端

• 项目初始化：Vue3 + Vite + TS 环境配置、PWA（manifest、Service Worker）
• 路由与页面：TabBar 导航、四大页面（看板、答案之书、广场、我的）骨架
• 状态管理：Pinia 存储用户信息、运势、答案历史
• UI 组件：
  • 运势看板：今日运势卡片、宜/忌列表、历史运势流、ECharts 运势轨迹图
  • 答案之书：提问输入框、CSS 3D 书籍动效、答案弹窗、历史答案列表、答案收藏
  • 分享广场：瀑布流布局、分类筛选、卡片展示
  • 我的页面：情绪日记表单、心情时间轴
• 分享功能：Canvas/html2canvas 生成分享图片、本地下载
• 认证交互：手机号登录页、验证码倒计时、Token 持久化

后端

• 数据库设计：Schema 设计（users, fortune_records, answer_records, user_profiles 等）、建表 SQL
• Flask 框架：项目结构、环境变量、SQLAlchemy 集成
• 用户认证：注册/登录接口、密码哈希、JWT 生成与验证中间件
• 用户画像：画像表结构、注册时自动创建、行为更新画像函数
• 运势看板接口：AI 调用框架、内容审核、today_fortune 接口
• 答案之书接口：AI 生成答案、更新画像、审核、answer 接口
• 历史记录接口：get_fortune_history、get_answer_history
• 分享社交接口：post_share、get_shares、like
• 单元测试：覆盖认证、运势、答案、历史等接口的测试用例

3.3 文档编写

• API 文档：使用 Swagger/OpenAPI 规范，说明每个接口的 URL、Method、请求参数、响应示例、错误码。
• 数据库设计文档：提供 E-R 图，说明每张表的字段、类型、索引、外键约束。
• 部署维护手册：包含环境配置、启动命令、备份脚本、日志清理等操作说明

3.4 测试

我们采用分层测试策略来设计本系统的测试，分为单元测试、集成测试和压力测试等

• 前端我们拟采用Vue Test Utils进行测试，需要完成以下单元测试：
  • 组件逻辑测试：测试四大核心页面（运势看板、答案之书、分享社交、我的）组件的渲染、用户交互（如点击抽签按钮）和事件响应等；
  • 状态管理测试：需要测试 Pinia​ Store的行为，包括对用户信息、运势数据）等状态的初始化、修改，以及actions的逻辑是否正确触发和更新状态；
  • HTTP请求测试：需要测试调用后端API（如获取今日运势）的行为，包括使用axios发送异步请求、成功响应处理和网络错误/超时等异常情况的处理；
  • 表单与用户输入测试：需要测试用户输入行为，包括“答案之书”问题输入的验证、心情标签的选择与提交、以及分享卡片时的表单交互逻辑；
• 后端我们拟采用pytest进行测试，需要完成以下单元测试：
  • 数据模型测试：测试User、MoodRecord、FortuneHistory等核心模型的字段定义、关联关系和CRUD操作，以及各种约束；
  • API端点测试：使用pytest-flask等工具模拟HTTP请求，测试所有API接口是否正常工作；
  • 安全测试：在接收用户输入的接口测试中，尝试注入恶意参数，验证ORM是否有效防护，测试接口对非法参数（如超长文本、异常类型）的校验和错误返回；
• 我们拟使用k6进行压力测试，验证系统在模拟的早高峰、节假日等突发流量下的稳定性，我们将对于运势获取、答案之书等重要接口进行压力测试。具体压力指标：
  • 并发用户数：从100逐渐增长到300；
  • 吞吐量：在300并发用户下，核心接口的整体吞吐率应不低于 20 req/s；
  • 响应时间：重要接口平均响应时间应小于3秒；
• 需要完成以下真实测试：
  • 端到端测试：使用Playwright测试PWA应用启动与安装以及用户主要使用流程（获取、查看运势、答案等）；
  • 安全测试：AI生成内容审核测试（判断系统能否调用第三方内容审核API并拦截违规、敏感或极端文本，返回预设的安全文案）；用户输入安全测试（SQL注入、XSS攻击测试）；

四、软件发布

4.1 出口条件

1. 代码完整性
   • 所有计划内的核心功能（运势看板、答案之书、情绪日记、分享卡片）代码已合并至 main 分支。
   • 前端构建（npm run build）无报错，后端服务（Flask）可正常启动。
2. 测试通过
   • 后端单元测试（pytest）通过率 100%，覆盖认证、运势生成、答案抽取、日记 CRUD 等核心接口。
   • 核心流程端到端测试：获取运势、摇答案、写日记、生成分享卡片，全部通过。
   • 无 P0 级（应用崩溃、核心功能完全不可用）和 P1 级（主要流程严重受阻）Bug
3. 性能达标
   • 通过 100 并发压力测试，核心接口（今日运势、随机答案）错误率< 1%，95% 响应时间< 3 秒
4. 安全与合规
   • AI 生成内容及用户分享内容均经过过滤，违规内容被拦截并替换为安全默认文案。
   • 隐私政策页面在应用内可访问，明示数据采集范围。

4.2 技术风险识别与评估

风险点	可能性	影响	应对策略
LLM 生成内容违规或被屏蔽	中	高	1. 强制集成内容审核 API（阿里云/腾讯云）作为前置过滤 2. 维护高质量的预设文案库作为兜底 3. Prompt 中明确禁止敏感话题
LLM API 费用超预算	中	中	1. 每位用户每日免费调用额度（运势 3 次，答案 10 次） 2. 前端限流 + 后端 Redis 计数
PWA 兼容性问题	低	中	1. 在 iOS（Safari）和 Android（Chrome）真机上测试添加到主屏幕及离线缓存 2. 不支持的浏览器降级为普通Web应用
用户隐私数据泄露	低	高	1. 全站 HTTPS，数据库连接加密 2. 用户标识字段哈希存储 3. 定期执行 npm audit 和 pip-audit 修复漏洞
数据库备份缺失导致数据丢失	低	高	1. 编写自动备份脚本 2. 备份文件同步至阿里云OSS并保留30天

4.3 软件部署与维护

部署流程

1. 开发者推送代码到 main 分支
2. 执行 npm run build 和 pytest 等测试命令
3. 测试通过，将前端构建产物部署到对象存储，将后端代码部署到云函数
4. 发送部署结果通知到团队群

维护策略

• 监控与告警
  • 磁盘使用率 > 85% → 告警 + 自动触发日志清理脚本
  • LLM API 调用失败率 > 10% → 告警，并降级至预设文案库
• 数据备份
• 版本回滚
  • 保留最近 3 个版本的前端构建包。
  • 后端代码通过 Git 标签回滚
  • 若发布后 30 分钟内出现 P0 错误，手动执行回滚脚本。