【山竹记账-全栈】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. 系统详细设计文档
# 文档 作用 本课是否要写
1 需求文档 用文字概括所有功能,无歧义、层次分明 ✅ 要写
2 系统概要设计 描述系统大致轮廓(架构、模块划分) ✅ 要写
3 系统详细设计 对每个模块逐项细化,细到可直接照做 ✅ 要写
4 测试文档 列出所有测试用例(输入、输出、环境) ❌ 不写(由测试人员负责)
5 接口文档 支撑不同模块(前后端)互相调用 ❌ 不写(应由代码自动生成)

进度管理(如甘特图、分工排期等)

  • 不属于这五份文档的范畴,是在有了这些文档之后再去做的。
  • 属于项目管理者自己的进度管理,用来实时调整工时与分工

简要结论

  • 回答”几天做完项目”的前提是对项目有完整把握,而这依赖于撰写完整的文档
  • 五份文档各有分工、分层递进:需求文档理清功能、概要设计定架构、详细设计定实现、测试文档保质量、接口文档保协作
    • 需求 → 概要设计 → 详细设计 → 测试 → 接口,前者给方向,后者给细节
  • 接口文档应自动生成而非手写,避免文档与代码不同步
  • 本项目前三份文档:
    • 需求文档(用例图)
    • 系统概要设计(架构图 + 模块划分)
    • 系统详细设计(逐项细化 + 多种图)
  • 本项目从需求文档开始写起;使用成熟的库生成接口文档,并部署到网站
  • 测试文档交给专职测试;接口文档交给自动化生成,别手写

可执行清单(项目任务)


2. 需求文档怎么写 ⇧

需求文档的载体很多:Word(最常见)、Excel、Axure(做原型的软件),甚至用笔在纸上画原型图给程序员看

2.1 核心要点 ⇧

  • 本项目采用用例图:软件工程中专门用来描述需求的图,非常简单、一学就会。
  • 需求文档的内容因项目而异,但有几个必须写的基本要素:
    • 项目背景、用户定位、需求划分、功能列表、范围、可行性;
    • 不写的要素要能口头说清楚。

2.2 重要细节 ⇧

2.2.1. 项目背景 ⇧

  • 写清楚为什么做这个项目,真实原因会引发后面一系列不同的对策。
  • 本项目的两个真实原因:
    • 「解决记账需求」是个伪需求:大部分账已在信用卡、微信里对账
    • 实际并不需要记账,是为做项目而设想的需求。
    • 希望简历里有一个比较好看的项目。

2.2.2. 用户定位 ⇧

  • 明确希望服务什么样的用户;定位不确定,后面就没法做。
  • 示例(做电商):定位为「知道如何使用网络支付的中国用户」,两个条件都很重要:
    • 不会网络支付 → 要考虑电话订购、汇款等,整个服务流程不一样。
    • 不是中国用户(如美国用户)→ 支付与整个金融体系完全不同。
  • 本项目定位:自己用,自己开心、能用上就行。

2.2.3. 需求划分 ⇧

  • 把大需求拆成小需求:大需求是记账;小需求如记账时能查看历史、查看支出和收入的占比。
  • 纯文字罗列会很长(上百行)、难看懂,建议把原型图画出来。
  • 三个主要界面即可代表主要需求:
    1. 查看所有账的界面
    2. 查看所有收入支出占比的界面
    3. 登录界面

2.2.4. 功能列表 ⇧

  • 划分完大需求后,把每个功能详细、严谨地列出来;这是产品经理最讨厌写的部分,因为全部用文字描述非常麻烦。
  • 示例(登录/验证码流程):
    • 用户先输入邮箱
    • 若直接输入随便的验证码,要提示”验证码错误”
    • 点发送后应马上提示倒计时 60秒(测试暂定为「六秒」),用于防止重复发送。
    • 可能需要人机验证,防机器人。
    • 之后弹出对话框让用户输入验证码。
  • 注意事项:如果产品经理说的需求非常模糊,直接问清楚到底想实现什么,拆解到程序员能听懂为止。
  • 程序员的实用做法:直接问产品经理”你想抄谁”,拿到链接或 App 照着做,比口述清楚得多。
  • 描述手段不限:文字、图片、流程图、用例图都可以,只要能让程序员听懂。

2.2.5. 范围(优先级) ⇧

  • 最终目的是达成需求,而不是做功能;要区分哪些功能是达成需求必需做的
  • 示例:登录必需做;导入导出可以放到后面做。
  • 要分清哪些第一个版本做、哪些第二个版本做,一定要提前分好。

2.2.6. 可行性 ⇧

  • 最好从经济、技术、法律三方面证明项目可以做:
维度 说明 原文示例
经济 投入产出是否算得过账 项目要做约三个月,但公司可能一个月后就倒闭,就不用做了;或能否提前拿到融资
技术 所有需求和功能能否通过技术实现 「换手机壳、网页背景色跟着变」:带芯片的手机壳可让手机知道壳的颜色(举例某品牌锤子手机);现有手机可切换白色/暗色主题;做不到就改需求
法律 是否存在法律风险 在国内做在线小学生数学教育 APP,可能被行政命令关停,就不能做
  • 可行性的门槛很低:只要不是不可能达成即可,50% 的可能性也能接受、就开始做。

简要结论 ⇧

  • 需求文档的价值在于把”想做什么”讲到没有歧义、层次分明,让人一眼看懂主要界面与功能
  • 需求文档六要素:项目背景、用户定位、需求划分、功能列表、范围、可行性。
    • 六个要素缺一不可:背景交代动机,定位圈定用户,划分理清结构,功能列表讲清细节,范围定下取舍,可行性证明能做
  • 功能列表最繁琐,需逐一严谨描述;范围要提前划分必做与可延后;可行性从经济、技术、法律论证,「不是不可能」即可。
  • 一开始就把必做与选做分开,是后续排期和砍需求的前提
  • 本课程用用例图写需求文档。

本课撰写安排(待办) ⇧


3. 使用用例图描述功能 ⇧

核心要点 ⇧

  • 本讲用用例图逐个描述功能列表:画一个用户,列出他能做的操作(用例)
  • 用例图非常高效:简单的图约 10 秒画完,一张图就能覆盖多个界面;复杂的图(如新增记账)有十几个框。
  • 同一张图前后端各取所需,反推页面模块工作量与接口数量:
    • 前端看要做哪些按钮、表单等界面元素;
    • 后端看要做哪些接口,据此估算工作量。
  • 范围:最后三个功能(导出、导入、记账提醒)为选做,其余功能都在 v1 实现;项目可行。

功能用例 ⇧

1. 特性介绍(欢迎页)

1.特性介绍

  • 这是公司的需求而非用户需求:公司希望产品显得高档,在用户进来时展示功能或广告
  • 用户操作:
    • 查看新特性,点击下一页继续查看
    • 点击跳过 → 跳过广告页到记账首页
    • 点击开启记账 → 直接进入记账应用
  • 四个界面用一张用例图即可全部描述,用户只能点击下页、跳过、开启应用

2. 登录与登出 ⇧

2.登录与退出

  1. 输入邮箱地址,点击发送验证码 → 请求发送验证码
  2. 输入验证码
  3. 点击登录
  4. 两种结果:登录成功 / 登录失败,提示不同
  5. 成功后进入首页(即查看记账页面),首页可点击退出登录
  • 后端必做两个接口:提交登录、发送验证码;其余都是前端工作
  • 结论:前端工作量很大,基本上是后端的三倍

3. 新增记账 ⇧

3.新增记账

  • 记账相关功能:
    1. 点击「开始记账」,跳转到记账页面
    2. 输入记账信息:标签、时间、金额——用例图写得笼统即可,字段不需要写清楚
    3. 点击提交,两种结果:失败 → 展示错误(统一处理,图中不画);成功 → 提示记账成功
  • 标签相关功能:
    • 记账时可点击添加标签 → 输入标签信息 → 同样分成功/失败
    • 长按标签可修改标签;修改界面里还有删除标签
  • 看完图就知道有哪几条流程,按箭头走即可
  • 前后端分工:
    • 表单、按钮等属于前端工作
    • 前端:要做一个日期控件
    • 可切换时间范围,切换后继续查看;往下滑加载更多,加载后继续查看。
    • 后端:至少要提供分页;
    • 两次提交(记账提交、标签提交)→ 后端需提供两个接口
    • 两处验证(校验)→ 后端需处理
  • 接口推导示例:两次提交(记账提交、标签提交)→ 至少两个接口;删除标签与删除记账 → 至少一个删标签接口,删记账时加个参数

4. 查看记账 ⇧

4.查看记账

  • 操作流程:
    1. 切换时间范围
    2. 查看记账列表
    3. 向下滑动加载更多
  • 后端:需要提供查看接口要做分页(加载更多),和时间范围筛选接口
  • 前端看:复用时间范围切换控件。

5. 统计图表 ⇧

5.统计图表

  • 操作流程:
    1. 切换时间范围,与查看记账类似:可切换时间、切换类型
    2. 查看图表
    3. 向下滑动加载更多
  • 后端:需要提供查看接口和时间范围筛选接口

选做 ⇧

  • 导出,展示生活费花销比例
  • 导入
  • 记账提醒

功能汇总 ⇧

功能 类型 后端接口数
特性介绍(广告页) 必做 —
新增记账 必做 约 2 个
查看记账 必做 约 2 个
统计图表 必做 约 1 个
登录与登出 必做 2 个
导出 选做 —
导入 选做 —
记账提醒 选做 —

简要结论 ⇧

  • 用例图是需求文档功能列表的载体,能高效、清晰地描述所有功能需求:
    • 把每个功能的用户操作流程画成图
    • 直接复制到需求文档中即可指导开发
    • 程序员看不懂就按图讨论
  • 一张用例图同时服务前后端:前端推导界面元素,后端推导接口数量与工作量(前端工作量约为后端三倍)。
  • 必做功能 5 个(特性介绍、新增记账、查看记账、统计图表、登录登出),选做功能 3 个(导出、导入、记账提醒)
  • 提需求要克制:每个新增词语背后都可能是一个大系统。
  • 需求文档不体现技术语言:用什么语言实现不会在需求文档中体现,需求文档只描述功能
  • 用例图可直接复制到文档:程序员看不懂文字描述时,根据用例图即可开始开发

4. 概要设计 ⇧

核心要点 ⇧

系统概要设计主要回答四个问题:

  1. 分哪些模块,模块之间怎么交互
  2. 用哪些数据,数据之间有什么关系
  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 只做转发,速度非常快
  • 两大好处:
    1. 分担压力:每台机器工作量变少,性能变好
    2. 零停机更新:更新时先挂掉一台,Nginx 自动把流量转发到另一台;更新完成后再恢复,用户无感知
  • 灰度发布:配合负载均衡,可以只更新一部分机器(如奇数 ID 用新版,偶数 ID 用旧版),让一部分用户先体验新版
  • Nginx 支持自定义规则、自定义插件,这是灰度发布的实现方法

中间件 ⇧

  • 在架构中多加一层或一个环节
  • 常见中间件:鉴权、登录验证、安全过滤等
  • 数据请求经过必要的中间件后再到达应用层业务代码
  • 在成熟团队中经常使用

注意事项 ⇧

  • 画架构图时,商业公司场景适合正规方格风格
  • 一张能说清「模块、交互、数据、风险」的轮廓图
  • 架构图画出来后,系统设计的能力就基本心中有数了
  • 本项目架构图已在 MVC 架构基础上画好

简要结论 ⇧

  • 概要设计四要素:模块划分、数据设计、技术风险、架构选择
  • 后端模块按用例图中的名词划分,前端按页面划分
  • 常见架构:三层架构(最经典)、MVC(三层细化)、微服务(完整模块独立部署)
  • 常用技术:前后端分离、负载均衡(分担压力 + 零停机更新 + 灰度发布)、中间件

5. 详细设计之后端接口列表 ⇧


6. 详细设计之数据库设计 ⇧


7. 详细设计之前端工作量统计 ⇧


8. 总结 ⇧


9. 补充:使用 AI 估算代码工程量

使用 AI 估算代码工程量(开发工时、故事点或资源成本),核心在于让 AI 充当任务拆解引擎与历史数据参照器,而不是直接拍脑袋给出天数

  • 结合现代研发管理实践,最可靠的落地方法是将 AI 融入结构化的估算工作流中
  1. 标准估算工作流(四步法)
  • 结构化任务拆解 (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 快速迭代功能带来的长期维护风险,可能节省剩下的工程时间,需要比以往人力更多的算力去验证
  1. 可直接复用的估算提示词 (Prompt) 模板

复制以下模板,填入具体需求让 AI 输出评估表:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
你是一位资深技术总监与敏捷研发专家。请根据以下需求文档与团队背景,进行精细化的代码工程量评估。

【团队背景】
- 技术栈:<例如:React + TypeScript / Go + PostgesSQL>
- 团队水平:<例如:中级工程师为主,已全员使用 AI 编程助手>
- 历史参考:<例如:上个月开发一个带权限控制的导出报表功能,前后端共耗时 4 人天>

【需求内容】
<在此粘贴你的 PRD 文本、接口设计或 User Story>

【输出要求】
1. **WBS 任务拆解**:按功能模块拆分为具体的开发子任务(单个任务不超过 2 人天),明确涉及的技术端(前端/后端/测试/运维)。
2. **三点工时估算**:为每个子任务给出乐观(O)、最可能(M)、悲观(P)工时(单位:小时),并计算出 PERT 期望工时。
3. **隐性工作量补充**:单独列出需求评审会议、前后端联调、Code Review、前后端单元测试、e2e测试、回归测试、部署上线及缓冲时间(建议预留 15%-30%)。
4. **风险与盲区提示**:指出需求中描述不清、容易导致返工的技术难点或边界条件。
请以 Markdown 表格形式输出最终汇总。
  1. 避坑指南与局限性
  • 代码行数 (LOC) 不等于工程量。
    • 切忌让 AI 预估代码行数来折算工时
    • 复杂的并发问题或老旧代码重构可能只改 10 行代码,但排查与测试需要 3 天或更多;需要长期维护的项目,需要有经验的研发人员重构
  • 必须结合现有代码库上下文。
    • 在全新项目(从 0 到 1)中估算较准
    • 若在庞大的遗留系统(屎山代码)上做二次开发,建议直接在 Cursor、Windsurf 等具备仓库级上下文(Repo-level Context)的 AI IDE 中提问,让 AI 检索现有依赖后再评估影响面
  • 人工终审不可替代
    • AI 擅长发现常规漏项,但对团队内部的审批流程、跨部门沟通成本、第三方接口联调阻力缺乏感知
    • 技术负责人必须对悲观时间(P)进行人工修正

9. 补充:其他流程管理工具

  • Jira 项目管理
  • 禅道-可自部署,需要注意备份数据

·未完待续·

参考文章

  • 无

相关文章


  • 作者: Joel
  • 文章链接:
  • 版权声明
  • 非自由转载-非商用-非衍生-保持署名