【山竹记账-全栈】4.文档撰写与排期
大纲链接 §
[toc]
1. 老板问:几天做完项目? ⇧
核心要点
- 当领导问”这个项目几天做完”时,很多程序员不知如何回答,因为对每个功能需要多少天没有概念
- 软件工程这门学科的核心就是在研究”到底能几天把项目做完”
- 要回答这个问题,需要对整个项目有总体把握,而前提是撰写以下文档。
五份核心文档 ⇧
1. 需求文档 PRD
- 目的:用文字描述清楚所有的功能
- 要求:用无歧义、层次分明的语言把需求描述出来
- 工具推荐:用例图(
Use Case Diagram)——描述需求最好用的图,几秒钟就能把需求理清楚,比直接画 UI 省事得多 - 备选方式:直接画 UI 也可以,但成本高、麻烦,变更频繁时,需要记录保存不同版本
- 示例:做记账项目,需要明确”记账包括哪些功能”,不能笼统说”记账就是记账”,要拆解到具体功能
2. 系统概要设计文档:只描述廓
- 目的:描述系统大致的样子和技术架构
- 内容:例如三层架构、MVC、微微服务架构等,给出一个架构图,概要设计基本就完成了。
- 特点:非常概要的描述,不需要太细,概要设计基本就完成了。
- 依据架构图中的模块做分工(如数据库模块、渲染模块)
- 附:根据同名模块划分,主要是方便分工,一般需要经验丰富的程序员来撰写
3. 系统详细设计文档:把模块说透,不留例外
- 目的:对每个模块进行详细说明,逐一列出要做的所有内容,要做什么必须一条条全部写出来,没有例外。
- 细化对象:数据库设计、流程图、类图等。
- 与概要设计的区别,对比示例——登录功能:
- 概要设计:只说”用什么”(如”我们用什么登录”),只写:登录用 Session 实现、使用 Cookie。
- 详细设计:给出具体流程(如”用户输入账号密码 → 点提交 → 返回错误信息或成功”等完整流程)
- 使用的图:设计图、流程图、时序图等,种类较多
- 核心价值:另一个程序员拿到你的详细设计文档就能直接写代码,不用思考
- 国内外差异:
- 国外:成熟的分工模式——专门的架构师/需求分析师写文档,初级程序员照文档实现,职责分明
- 国外敏捷是完整流程:每日站会(会议内容、时长、参会人都规定清楚),会后用看板把所有任务列出来。
- 国内:自己设计、自己实现、自己想、自己写(所谓的”敏捷开发”实际上往往是缺少流程的随意开发)
4. 测试文档:客观的输入/输出清单
- 目的:描述所有测试用例,包括输入、输出及所在环境(测试环境/生产环境等)
- 判定标准很客观:实现不满足测试文档的输入输出,就是 bug。
- 测试分类(按技术含量从高到低):
| 类型 | 说明 |
|---|---|
| 单元测试 | 测一个函数,如验证数据校验函数的正确性 |
| 集成测试 | 前后端联调,验证两部分的接口对接是否成功 |
| 系统测试 | 找测试人员模拟用户真实使用环境,手动点击操作应用 |
| 端到端测试 | 使用现代并成熟的技术框架,模拟用户操作真实使用环境,使用代码操作应用,验证反馈结果 |
| 冒烟测试 | 上线前的快速验证——新功能是否影响了旧功能(借自硬件测试概念:通电看是否冒烟) |
| 回归测试 | 加了新功能后,回头测旧功能有没有被影响 |
- 分工:
- 程序员一般只参与单元测试和集成测试
- 系统测试、冒烟测试等由专职测试人员负责
5. 接口文档:不该由人写,必须自动生成
- 重要性:在前后端分离开发中非常重要
- 核心原则:接口文档必须由代码自动生成,不能人为手写
- 手写的接口文档存在不实时的问题——改了代码但忘了改文档,导致文档过时(即”文档是旧的”)
- 逻辑推导:接口文档一旦过时,参数或返回值必然对不上,代码一定会出 bug。
- 正确做法:代码提交/代码部署/编译通过后,自动生成接口文档,并自动发布到可访问的网站地址
- 保证与代码同步;一版代码,一版文档;编译不通过则不生成
- 常用工具:
- Knife4j:开源,功能完善成熟
- Swagger:国际流行,功能强大
- Postman:用的人多,可直接下载试用
- Apifox:集成了 Swagger 等工具并提供 Mock,比较好用(但依赖商业公司长期存续,不作强依赖)
- 其他国产上线工具(免费可用)
- 建议:保证一定的自动化流程,未来可自写脚本,上线代码时自动生成文档
- 搭自动化流程(后续会写脚本,做到上传代码即自动生成文档)
本课程要写的文档
本课程需要撰写的文档为前三份:
- 需求文档
- 系统概要设计文档
- 系统详细设计文档
| # | 文档 | 作用 | 本课是否要写 |
|---|---|---|---|
| 1 | 需求文档 | 用文字概括所有功能,无歧义、层次分明 | ✅ 要写 |
| 2 | 系统概要设计 | 描述系统大致轮廓(架构、模块划分) | ✅ 要写 |
| 3 | 系统详细设计 | 对每个模块逐项细化,细到可直接照做 | ✅ 要写 |
| 4 | 测试文档 | 列出所有测试用例(输入、输出、环境) | ❌ 不写(由测试人员负责) |
| 5 | 接口文档 | 支撑不同模块(前后端)互相调用 | ❌ 不写(应由代码自动生成) |
进度管理(如甘特图、分工排期等)
- 不属于这五份文档的范畴,是在有了这些文档之后再去做的。
- 属于项目管理者自己的进度管理,用来实时调整工时与分工
简要结论
- 回答”几天做完项目”的前提是对项目有完整把握,而这依赖于撰写完整的文档
- 五份文档各有分工、分层递进:需求文档理清功能、概要设计定架构、详细设计定实现、测试文档保质量、接口文档保协作
- 需求 → 概要设计 → 详细设计 → 测试 → 接口,前者给方向,后者给细节
- 接口文档应自动生成而非手写,避免文档与代码不同步
- 本项目前三份文档:
- 需求文档(用例图)
- 系统概要设计(架构图 + 模块划分)
- 系统详细设计(逐项细化 + 多种图)
- 本项目从需求文档开始写起;使用成熟的库生成接口文档,并部署到网站
- 测试文档交给专职测试;接口文档交给自动化生成,别手写
可执行清单(项目任务)
2. 需求文档怎么写 ⇧
需求文档的载体很多:Word(最常见)、Excel、Axure(做原型的软件),甚至用笔在纸上画原型图给程序员看
2.1 核心要点 ⇧
- 本项目采用用例图:软件工程中专门用来描述需求的图,非常简单、一学就会。
- 需求文档的内容因项目而异,但有几个必须写的基本要素:
- 项目背景、用户定位、需求划分、功能列表、范围、可行性;
- 不写的要素要能口头说清楚。
2.2 重要细节 ⇧
2.2.1. 项目背景 ⇧
- 写清楚为什么做这个项目,真实原因会引发后面一系列不同的对策。
- 本项目的两个真实原因:
- 「解决记账需求」是个伪需求:大部分账已在信用卡、微信里对账
- 实际并不需要记账,是为做项目而设想的需求。
- 希望简历里有一个比较好看的项目。
2.2.2. 用户定位 ⇧
- 明确希望服务什么样的用户;定位不确定,后面就没法做。
- 示例(做电商):定位为「知道如何使用网络支付的中国用户」,两个条件都很重要:
- 不会网络支付 → 要考虑电话订购、汇款等,整个服务流程不一样。
- 不是中国用户(如美国用户)→ 支付与整个金融体系完全不同。
- 本项目定位:自己用,自己开心、能用上就行。
2.2.3. 需求划分 ⇧
- 把大需求拆成小需求:大需求是记账;小需求如记账时能查看历史、查看支出和收入的占比。
- 纯文字罗列会很长(上百行)、难看懂,建议把原型图画出来。
- 三个主要界面即可代表主要需求:
- 查看所有账的界面
- 查看所有收入支出占比的界面
- 登录界面
2.2.4. 功能列表 ⇧
- 划分完大需求后,把每个功能详细、严谨地列出来;这是产品经理最讨厌写的部分,因为全部用文字描述非常麻烦。
- 示例(登录/验证码流程):
- 用户先输入邮箱
- 若直接输入随便的验证码,要提示”验证码错误”
- 点发送后应马上提示倒计时 60秒(测试暂定为「六秒」),用于防止重复发送。
- 可能需要人机验证,防机器人。
- 之后弹出对话框让用户输入验证码。
- 注意事项:如果产品经理说的需求非常模糊,直接问清楚到底想实现什么,拆解到程序员能听懂为止。
- 程序员的实用做法:直接问产品经理”你想抄谁”,拿到链接或 App 照着做,比口述清楚得多。
- 描述手段不限:文字、图片、流程图、用例图都可以,只要能让程序员听懂。
2.2.5. 范围(优先级) ⇧
- 最终目的是达成需求,而不是做功能;要区分哪些功能是达成需求必需做的
- 示例:登录必需做;导入导出可以放到后面做。
- 要分清哪些第一个版本做、哪些第二个版本做,一定要提前分好。
2.2.6. 可行性 ⇧
- 最好从经济、技术、法律三方面证明项目可以做:
| 维度 | 说明 | 原文示例 |
|---|---|---|
| 经济 | 投入产出是否算得过账 | 项目要做约三个月,但公司可能一个月后就倒闭,就不用做了;或能否提前拿到融资 |
| 技术 | 所有需求和功能能否通过技术实现 | 「换手机壳、网页背景色跟着变」:带芯片的手机壳可让手机知道壳的颜色(举例某品牌锤子手机);现有手机可切换白色/暗色主题;做不到就改需求 |
| 法律 | 是否存在法律风险 | 在国内做在线小学生数学教育 APP,可能被行政命令关停,就不能做 |
- 可行性的门槛很低:只要不是不可能达成即可,50% 的可能性也能接受、就开始做。
简要结论 ⇧
- 需求文档的价值在于把”想做什么”讲到没有歧义、层次分明,让人一眼看懂主要界面与功能
- 需求文档六要素:项目背景、用户定位、需求划分、功能列表、范围、可行性。
- 六个要素缺一不可:背景交代动机,定位圈定用户,划分理清结构,功能列表讲清细节,范围定下取舍,可行性证明能做
- 功能列表最繁琐,需逐一严谨描述;范围要提前划分必做与可延后;可行性从经济、技术、法律论证,「不是不可能」即可。
- 一开始就把必做与选做分开,是后续排期和砍需求的前提
- 本课程用用例图写需求文档。
本课撰写安排(待办) ⇧
3. 使用用例图描述功能 ⇧
核心要点 ⇧
- 本讲用用例图逐个描述功能列表:画一个用户,列出他能做的操作(用例)
- 用例图非常高效:简单的图约 10 秒画完,一张图就能覆盖多个界面;复杂的图(如新增记账)有十几个框。
- 同一张图前后端各取所需,反推页面模块工作量与接口数量:
- 前端看要做哪些按钮、表单等界面元素;
- 后端看要做哪些接口,据此估算工作量。
- 范围:最后三个功能(导出、导入、记账提醒)为选做,其余功能都在 v1 实现;项目可行。
功能用例 ⇧
1. 特性介绍(欢迎页)
- 这是公司的需求而非用户需求:公司希望产品显得高档,在用户进来时展示功能或广告
- 用户操作:
- 查看新特性,点击下一页继续查看
- 点击跳过 → 跳过广告页到记账首页
- 点击开启记账 → 直接进入记账应用
- 四个界面用一张用例图即可全部描述,用户只能点击下页、跳过、开启应用
2. 登录与登出 ⇧
- 输入邮箱地址,点击发送验证码 → 请求发送验证码
- 输入验证码
- 点击登录
- 两种结果:登录成功 / 登录失败,提示不同
- 成功后进入首页(即查看记账页面),首页可点击退出登录
- 后端必做两个接口:提交登录、发送验证码;其余都是前端工作
- 结论:前端工作量很大,基本上是后端的三倍
3. 新增记账 ⇧
- 记账相关功能:
- 点击「开始记账」,跳转到记账页面
- 输入记账信息:标签、时间、金额——用例图写得笼统即可,字段不需要写清楚
- 点击提交,两种结果:失败 → 展示错误(统一处理,图中不画);成功 → 提示记账成功
- 标签相关功能:
- 记账时可点击添加标签 → 输入标签信息 → 同样分成功/失败
- 长按标签可修改标签;修改界面里还有删除标签
- 看完图就知道有哪几条流程,按箭头走即可
- 前后端分工:
- 表单、按钮等属于前端工作
- 前端:要做一个日期控件
- 可切换时间范围,切换后继续查看;往下滑加载更多,加载后继续查看。
- 后端:至少要提供分页;
- 两次提交(记账提交、标签提交)→ 后端需提供两个接口
- 两处验证(校验)→ 后端需处理
- 接口推导示例:两次提交(记账提交、标签提交)→ 至少两个接口;删除标签与删除记账 → 至少一个删标签接口,删记账时加个参数
4. 查看记账 ⇧
- 操作流程:
- 切换时间范围
- 查看记账列表
- 向下滑动加载更多
- 后端:需要提供查看接口要做分页(加载更多),和时间范围筛选接口
- 前端看:复用时间范围切换控件。
5. 统计图表 ⇧
- 操作流程:
- 切换时间范围,与查看记账类似:可切换时间、切换类型
- 查看图表
- 向下滑动加载更多
- 后端:需要提供查看接口和时间范围筛选接口
选做 ⇧
- 导出,展示生活费花销比例
- 导入
- 记账提醒
功能汇总 ⇧
| 功能 | 类型 | 后端接口数 |
|---|---|---|
| 特性介绍(广告页) | 必做 | — |
| 新增记账 | 必做 | 约 2 个 |
| 查看记账 | 必做 | 约 2 个 |
| 统计图表 | 必做 | 约 1 个 |
| 登录与登出 | 必做 | 2 个 |
| 导出 | 选做 | — |
| 导入 | 选做 | — |
| 记账提醒 | 选做 | — |
简要结论 ⇧
- 用例图是需求文档功能列表的载体,能高效、清晰地描述所有功能需求:
- 把每个功能的用户操作流程画成图
- 直接复制到需求文档中即可指导开发
- 程序员看不懂就按图讨论
- 一张用例图同时服务前后端:前端推导界面元素,后端推导接口数量与工作量(前端工作量约为后端三倍)。
- 必做功能 5 个(特性介绍、新增记账、查看记账、统计图表、登录登出),选做功能 3 个(导出、导入、记账提醒)
- 提需求要克制:每个新增词语背后都可能是一个大系统。
- 需求文档不体现技术语言:用什么语言实现不会在需求文档中体现,需求文档只描述功能
- 用例图可直接复制到文档:程序员看不懂文字描述时,根据用例图即可开始开发
4. 概要设计 ⇧
核心要点 ⇧
系统概要设计主要回答四个问题:
- 分哪些模块,模块之间怎么交互
- 用哪些数据,数据之间有什么关系
- 技术风险在哪里
- 采用什么架构
一、模块划分与交互 ⇧
前端模块划分 ⇧
- 一个页面就是一个模块,差不多够用,页面的组织方式与代码几乎一对一
- 页面内的小组件不需要单独设计,直接封装即可
- 模块间交互使用前端状态管理工具(如 Pinia / Zustand 等),用于拆分的组件之间通信
后端模块划分 ⇧
- 后端必须按功能(名词)划分
- 根据用例图中的名词来划分模块(与页面无关)
- 示例:
- 增删改查 哪些表 → 增删改查 模块
- 登录 → 登录模块
- 用户 → 用户模块
- 记账 → 记账模块
- 统计 → 统计模块
- 导入 → 导入模块
- 提醒 → 提醒模块
二、数据设计 ⇧
- 根据用例图推导需要哪些数据表
- 需要说明:
- 需要哪些数据表(可用简化方式描述,但表制要列清楚)
- 每张表有哪些字段
- 表与表之间的关联关系(用数据库 ER 图表示)
三、技术风险 ⇧
- 评估是否有技术上无法实现的部分
- 本项目整体简单,目前无明显技术风险
- 潜在风险点(导入功能):
- 需要解析银行账单邮件,邮件附件可能有
CSV/PDF等格式 - 不同银行的账单格式不统一,能否完全支持每家银行是风险点
- 如果要实现导入,能否成功需打问号
- 需要解析银行账单邮件,邮件附件可能有
四、常见架构 ⇧
三层架构(最经典) ⇧
- 表现层:处理视图(类似 MVC 的 View)
- 应用层:处理业务逻辑(类似 MVC 的 Controller)
- 数据层:处理数据(类似 MVC 的 Model)
- 与 MVC 的区别:三层架构的粒度比 MVC 更粗一些
- 典型画法:
- 底层一条线写 DB;
- 上面一层框写所用框架(如 Java Spring);
- 再有一层专门封装 DB reader/setter 负责读数据;
- 应用层按业务模块分成 A、B、C 模块,各自调用不同数据表;
- 如果中间分两层,其中一层是专门负责数据读取的抽象层;
- 最上层渲染成不同模块或界面(管理后台、用户端页面、浏览器)
- 识别方法:看到图画了一条线分两层、DB +
Model/Controller/View,基本就是三层架构
| 层 | 职责 |
|---|---|
| 数据层 | 处理数据(MySQL / PostgreSQL / NoSQL 均可,无所谓) |
| 应用层 | 处理业务逻辑 |
| 表现层 | 处理视图 |
MVC 架构 ⇧
- 是三层架构的细化版本
- 同样分为 Model(数据)、Controller(应用)、View(视图)
- 划分粒度更细,每个模块更小
- user 模块分为 UserModel、UserController、UserView;
- x 模块也分为 XModel、XController、XView。
微服务架构 ⇧
- 每个微服务是一个完整的模块(如做权限的、做支付的)
- 每个接口只执行一个函数
- 语言对微服务不重要,不同微服务可以用不同语言,(服务之间可通过 RPC 或 HTTP 交流)
- 难点:
- 每个微服务都要独立部署
- 服务间如何调用、如何治理
- 配置管理复杂
- 目前
Serverless主打轻量小型功能,可作为微服务替代方案- 每个接口只执行一个函数;微服务至少是一个完整模块(专门做登录、鉴权、支付)
五、其他常用技术 ⇧
前后端分离 ⇧
- 前端代码与后端代码分开,不混在一起
- 早期 ASP / JSP / PHP 喜欢把 CSS 和 JS 混到 HTML 里,前端很难维护
- 前后端分离后,通过接口(API)交流
- 人员也可分离:大公司会让前端和后端由不同人担任
- 好处:增加人员可替代性,降低成本(一个后端一万多 + 一个前端一万多 < 一个全栈两万多)
- 对公司有利,但对全栈个人不利(可替代性增加)
负载均衡 ⇧
- 用多台同样的机器提供服务,分担压力
- 示例:用 Nginx 做转发,分发到两台后端服务器
- 每台机器只服务 50% 用户,压力减半
- Nginx 只做转发,速度非常快
- 两大好处:
- 分担压力:每台机器工作量变少,性能变好
- 零停机更新:更新时先挂掉一台,Nginx 自动把流量转发到另一台;更新完成后再恢复,用户无感知
- 灰度发布:配合负载均衡,可以只更新一部分机器(如奇数 ID 用新版,偶数 ID 用旧版),让一部分用户先体验新版
- Nginx 支持自定义规则、自定义插件,这是灰度发布的实现方法
中间件 ⇧
- 在架构中多加一层或一个环节
- 常见中间件:鉴权、登录验证、安全过滤等
- 数据请求经过必要的中间件后再到达应用层业务代码
- 在成熟团队中经常使用
注意事项 ⇧
- 画架构图时,商业公司场景适合正规方格风格
- 一张能说清「模块、交互、数据、风险」的轮廓图
- 架构图画出来后,系统设计的能力就基本心中有数了
- 本项目架构图已在 MVC 架构基础上画好
简要结论 ⇧
- 概要设计四要素:模块划分、数据设计、技术风险、架构选择
- 后端模块按用例图中的名词划分,前端按页面划分
- 常见架构:三层架构(最经典)、MVC(三层细化)、微服务(完整模块独立部署)
- 常用技术:前后端分离、负载均衡(分担压力 + 零停机更新 + 灰度发布)、中间件
5. 详细设计之后端接口列表 ⇧
6. 详细设计之数据库设计 ⇧
7. 详细设计之前端工作量统计 ⇧
8. 总结 ⇧
9. 补充:使用 AI 估算代码工程量
使用 AI 估算代码工程量(开发工时、故事点或资源成本),核心在于让 AI 充当任务拆解引擎与历史数据参照器,而不是直接拍脑袋给出天数
- 结合现代研发管理实践,最可靠的落地方法是将 AI 融入结构化的估算工作流中
- 标准估算工作流(四步法)
- 结构化任务拆解 (
WBS)。- 将模糊的 PRD(产品需求文档)或需求描述输入给 AI,要求其按“前端/后端/数据库/联调/测试”拆解出具体的子任务(颗粒度尽量控制在 0.5 到 2 天)
- AI 对单一明确小任务的估算准确度远高于对庞大模块的估算
- 引入历史基准 (
Few-Shot校准)。- 估算不能脱离团队实际水平。
- 在提示词中附带团队过往 3~5 个类似功能的实际耗时与复杂度,让 AI 校准基准线
- 结合三点估算法 (
PERT)。- 要求 AI 为每个子任务输出三个值:乐观时间 (O)、最可能时间 (M) 和 悲观时间 (P),
- 最终采用期望工时公式计算:E = (O + 4M + P) / 6,有效缓冲技术风险。
- 评估 AI 辅助提效折扣。
- 如果团队已普及 AI 编程助手(如 Copilot、Cursor 等),纯编码环节通常可带来 10%~30% 的效率提升
- 但需注意需求沟通、代码审查(Code Review)与集成测试的耗时并未等比例缩减,切勿盲目对总工期打对折
- 需要注意的是 AI 快速迭代功能带来的长期维护风险,可能节省剩下的工程时间,需要比以往人力更多的算力去验证
- 可直接复用的估算提示词 (Prompt) 模板
复制以下模板,填入具体需求让 AI 输出评估表:
|
|
- 避坑指南与局限性
- 代码行数 (LOC) 不等于工程量。
- 切忌让 AI 预估代码行数来折算工时
- 复杂的并发问题或老旧代码重构可能只改 10 行代码,但排查与测试需要 3 天或更多;需要长期维护的项目,需要有经验的研发人员重构
- 必须结合现有代码库上下文。
- 在全新项目(从 0 到 1)中估算较准
- 若在庞大的遗留系统(屎山代码)上做二次开发,建议直接在 Cursor、Windsurf 等具备仓库级上下文(Repo-level Context)的 AI IDE 中提问,让 AI 检索现有依赖后再评估影响面
- 人工终审不可替代
- AI 擅长发现常规漏项,但对团队内部的审批流程、跨部门沟通成本、第三方接口联调阻力缺乏感知
- 技术负责人必须对悲观时间(P)进行人工修正
9. 补充:其他流程管理工具
Jira项目管理- 禅道-可自部署,需要注意备份数据
·未完待续·
参考文章
- 无
相关文章
- 作者: Joel
- 文章链接:
- 版权声明
- 非自由转载-非商用-非衍生-保持署名