51信用卡管家App PRD怎么写？Markdown转docx与后端模板渲染实战

简介一份从真实体验逆向推导而成的51信用卡管家APP产品需求文档PRD面向产品经理、交互设计师及互联网产品初学者。文档按产品概述、名词与功能点、产品结构图、全局说明、部分功能原型交互展示五大章节组织完整覆盖账单导入更新、还款提醒、借款、理财、会员等级与成长值等模块并详细描述了登录注册、账单详情、财富、借钱、发现、我的、公积金查询等页面的交互逻辑与异常处理规则。全局说明中对网络异常、Toast/Dialog/浮窗、键盘呼出、生物识别、空状态等场景均有具体规范可帮助读者理解金融类APP从业务流转到前端交互的完整PRD框架也可作为撰写类似金融产品需求文档的参考模板。资源为单个docx文件压缩包约2.95MB已有202人浏览学习适合产品新人拆解学习金融类APP的产品流程与文档撰写思路。1. 一份 51 信用卡管家 App 的 PRD为什么值得用 docx 认真归档拿到51信用卡管家app产品需求文档.docx这个文件名很多团队第一反应是双击 Word 开始排版。真正要解决的不是 Word 技巧而是这份文档能不能让开发照着做、测试对着查、后端批量生成时不翻车。一个 docx 文件既是产品经理的交付物也是后端模板渲染的输入更是 Windows 文件系统里能被搜索到正文的文本载体。这篇笔记不讲产品科普直接讲落地针对 51 信用卡管家这类信用卡管理 App 的需求文档怎么写、怎么用 Markdown 转成带样式的 docx、后端模板生成怎么做、以及我在 Windows 上遇到的 docx 搜索和渲染坑。适合三类人要写需求文档的产品、要接文档生成接口的后端、以及在共享目录里翻不到评审稿的测试。2. 先拆需求用页面流程、状态机和埋点表锁住 App 行为写产品需求文档最忌讳一上来就打开 Word 画原型。我会先把它当成一套可评审的逻辑链这个版本要解决什么、哪些页面参与、状态怎么流转、数据从哪里来。对于 51 信用卡管家这类信用卡管理 App核心链路是账单、还款、提醒需求只要偏离这条链评审会必然翻车。下面是我写 PRD 时固定先做的三件事。2.1 从信用卡管理的核心闭环里圈出文档边界先把功能拓扑列出来而不是急着写页面。以“还款提醒优化”这个版本为例我会在文档开头放一张范围表让开发一眼就能判断“这个需求我到底要不要动”。功能域本次范围关键页面备注账单管理只读账单列表账单详情页不做账单导入还款提醒新增状态机与推送策略提醒设置页、还款详情页核心改动卡片管理不变卡片列表页仅保证入口可达优惠权益不涉及无下个版本再审用户中心不变无不改登录与实名这张表不是为了凑页数。我见过不少 PRD 顺手把“卡片管理”重写一遍结果版本周期拖了两周最后发现用户要的只是提醒时间改到下午。PRD 的边界写清楚后端工作量估算才能准测试用例的优先级也不会被无关功能带偏。边界圈定之后再画主流程。对信用卡管理 App用户高频动作是“查看账单 → 选择还款方式 → 还款 → 查结果”提醒是拉动回访的钩子。流程图上不需要画出每一个页面跳转但一定要画出和状态变化相关的关键节点否则后面的状态机没有落脚点。2.2 用状态机表把还款提醒的每个分支写死还款提醒不是简单“发一条 push”就结束了。提醒、点击、支付、逾期之间存在多次状态迁移文档里不定义清楚后端建表时就会漏字段。我习惯在 PRD 里直接放一张状态机表字段包括当前状态、触发动作、目标状态、页面表现和外部通知。当前状态触发动作目标状态页面表现外部通知pending_remind到达还款日前 3 天reminded首页卡片显示“待还款”推送一条还款提醒reminded用户点击提醒reminded进入账单详情无reminded支付成功回调paid账单页显示已还款不发逾期通知pending_remind / reminded超过还款日未支付overdue首页红色逾期标签次日 10:00 推逾期提醒overdue用户还清paid状态恢复已还款推送还款成功通知这张表写完后我还会补一段异常分支说明用户点击提醒的动作可能发生在 push 到达之前也可能发生在到达之后两种进入路径都要在文档里写明还有断网时支付回调失败状态要允许补偿重试这属于后端状态机设计但必须在 PRD 里定义否则开发默认按成功处理。这些细节是评审里最容易被挑战的地方提前写死能少吵三次会。状态机表不只是给后端看的。测试拿到表以后可以直接把每一行“触发动作 目标状态”转成一条测试用例比如“在 reminded 状态下重复点击提醒按钮状态不发生迁移”。PRD 里有了这张表测试就不用再靠猜来设计场景。2.3 埋点字段与接口定义同步进文档埋点和接口不能等开发阶段再补。我一般在每个功能域下直接放一张埋点表和一张接口表字段命名在立项会上先对齐。埋点表的好处是让前端知道上报什么、让数据分析知道怎么取数。事件名触发时机参数备注remind_push_click用户点击还款提醒 pushcard_id, remind_plan_id, status, click_sourceclick_source 区分列表或通知栏remind_setting_change保存提醒时间remind_time, days_before, push_switch上报新值remind_overdue_view查看逾期账单card_id, overdue_days逾期天数由后端计算接口表可以沿用同一份数据模型。PRD 里的接口定义不需要写完整代码但入参、出参、错误码必须有否则开发和测试会在“这个字段到底叫 plan_id 还是 remind_id”上反复拉扯。接口入参出参错误码POST /v1/remind/plancard_id, remind_time, push_switchplan_id, status40001 参数错误 / 40002 重复设置POST /v1/remind/plan/updateplan_id, remind_timeplan_id40003 计划不存在GET /v1/remind/plancard_idplan 详情40004 无还款计划这些表会让文档变长但换来的是后端不用反复问“埋点上报什么字段、状态从哪来”测试可以直接照着表里的错误码写断言。内容结构定清楚后才轮到 docx 排版直接打开 Word 从零写通常会在评审前夜发现十几处逻辑对不上然后一边改一边调样式。3. 从 Markdown 到 docx一条命令生成带样式的 PRD内容结构定好之后才轮到 docx 本身。直接 Word 手工排版的问题是版本 diff 难做改一版就存一个“最终版v3_再也不改.docx”。我推荐的工作流是Markdown 写源稿git 管版本pandoc 转 docx。这样标题、目录、样式都由模板统一控制生成速度快还能接后端批量出稿。3.1 先把 PRD 拆成可复用的 Markdown 文档块不建议一个 Markdown 文件写整个 PRD。文件太长后评审时不同人改同一段文件冲突不断。我一般按文档层级拆成多个 md 文件合并时再按顺序拼起来。prd/ ├── 00_version.md ├── 01_background.md ├── 02_scope.md ├── 03_flow.md ├── 04_state.md └── 05_tracking.md每个文件只负责一块内容。比如00_version.md里放版本信息和评审状态# 版本说明 - 产品51 信用卡管家 App - 版本v1.2.0 - 需求负责人产品-李四 - 评审状态待评审这种组织方式有两点好处一是 markdown 源稿可以被 git 追踪每次评审意见对应一次 commit责任人一目了然二是这些文件可以作为后端数据模型的来源字段名和文档内容保持一致生成 docx 时不容易出现版本错位。3.2 用 pandoc 合成主文档并生成目录命令与参数当所有源稿就绪后用一条命令合并输出。我的常用命令是pandoc prd/00_version.md prd/01_background.md prd/02_scope.md \ prd/03_flow.md prd/04_state.md prd/05_tracking.md \ -o build/51信用卡管家app产品需求文档.docx \ --reference-docprd-reference.docx \ --toc --toc-depth3 --number-sections逻辑说明pandoc 会把多个输入文件按顺序拼成一个文档每个 md 文件的一级标题映射为 Word 的 Heading 1二级标题映射为 Heading 2具体样式由--reference-doc决定。--toc生成目录--toc-depth3控制目录显示到三级标题--number-sections为标题自动编号省去手工维护“2.1、2.2”的麻烦。参数说明里有两处要特别注意-o指定的文件名建议带 build 前缀避免源稿目录混入生成物--reference-doc后面跟的是模板文件路径如果不传pandoc 会用内置默认样式出来的 docx 往往是 Calibri 字体中文观感很差。注意pandoc 生成的目录是 Word 域文件打开后页码不会自动更新。评审前按CtrlA再按F9目录页码才会刷新。看到目录不准先更新域别怀疑内容漏了。3.3 自定义 reference docx字体、页边距和标题样式一次管够pandoc 转换出的 docx 布局是否专业取决于 reference docx 模板。先导出一份 pandoc 默认参考文件pandoc -o prd-reference.docx --print-default-data-file reference.docx逻辑说明这条命令会生成一个 docx 文件里面没有正文只有命名样式和页面设置。之后用 Word 打开这个文件进入样式面板逐个修改正文行距改为 1.5 倍中文字体设置为“微软雅黑”或“宋体”Heading 1 固定字号和颜色页边距按公司模板调整。这里有个容易翻车的细节不要用“全选改字体”的方式改模板。pandoc 是按样式名来匹配内容的只有修改样式定义本身转换出来的标题和正文才会统一继承。我见过有人全选改成黑体结果 Heading 样式还是默认字体目录里的标题和正文字号对不上交付前又要返工。模板调好后可以用 unzip 直接检查生成结果unzip -p build/51信用卡管家app产品需求文档.docx word/document.xml | head -c 1500逻辑说明docx 本质上是一个 zip 包正文存在word/document.xml里。执行这条命令能把正文 XML 打印出来。看到“还款提醒”这些关键词以明文方式出现在 XML 里说明内容真的写入文档结构了。这一步同时也是后面 Windows 搜索能否命中 docx 正文的前提。4. 后端 docx 模板生成把 PRD 从手写件变成批量交付物人工用 pandoc 适合产品侧自己出稿一旦要批量生成多个版本的 PRD或者把文档生成嵌进后端流水线就需要模板渲染方案。核心思路是把一份 docx 当作模板后端用数据填充占位符输出新文档。下面是我的选型和最小可运行写法。4.1 选模板引擎为什么我推荐 poi-tl 而不是直接操作 XML先弄清 docx 底层的原理一个 docx 文件就是 zip 包正文在word/document.xml里段落由w:p表示文字放在w:rw:t节点内。所以“生成 docx”最直接的办法是拼 XML但这种方式对中文转义、样式继承、分页符都不友好只适合最后兜底。方案模板友好度循环表格图片维护成本选型建议直接 Apache POI XWPF低代码操作段落麻烦麻烦高只做局部替换docx4j中偏底层中中高需要完整解析文档时poi-tl高{{占位符}}简单简单低批量模板生成首选Freemarker 拼 XML低容易坏结构不可控极高不推荐我选 poi-tl 的理由是模板是真实的 docx 文件产品经理和测试可以直接在 Word 里调整占位符位置不用动代码循环块和图片都有现成约定遇到问题去社区搜踩坑记录也比别的方案多。对于 PRD 这种带表格、带截图、格式要求较高的文档这个特性最省事。4.2 最小可运行的后端渲染示例注释与参数说明后端渲染前先在 pom 里引入依赖。版本号建议由公司私服或 BOM 统一锁定不要每个项目手写一个版本避免 CI 环境换机器后构建失败。dependency groupIdcom.deepoove/groupId artifactIdpoi-tl/artifactId version${poi-tl.version}/version /dependency然后是最小渲染代码。模板里提前写好{{prdName}}、{{author}}这类占位符代码只负责往 Map 里塞数据。package prd.render; import com.deepoove.poi.XWPFTemplate; import java.io.FileOutputStream; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.HashMap; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; public class PrdDocxRenderer { public static void main(String[] args) throws Exception { MapString, Object data new HashMap(); data.put(prdName, 51信用卡管家App-还款提醒优化); data.put(author, 产品组); data.put(version, v1.2.0); data.put(submitDate, LocalDateTime.now().format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm))); ListMapString, Object features new ArrayList(); MapString, Object f1 new LinkedHashMap(); f1.put(featureName, 还款提醒状态机); f1.put(owner, 后端-张工); f1.put(priority, P0); features.add(f1); MapString, Object f2 new LinkedHashMap(); f2.put(featureName, 逾期提醒推送); f2.put(owner, 后端-王工); f2.put(priority, P1); features.add(f2); data.put(features, features); XWPFTemplate template XWPFTemplate.compile(templates/prd-template.docx) .render(data); template.writeAndClose(new FileOutputStream(build/51信用卡管家app产品需求文档_v1.2.0.docx)); } }逻辑说明compile加载 docx 模板路径render把 Map 里的 key 替换到模板对应占位符writeAndClose输出文件并释放资源。features对应模板里的循环区域写法是{{?features}}开头、{{/features}}结尾poi-tl 会按 List 长度复制这段区域里的行适合功能清单这种行数不固定的表格。参数说明占位符必须是{{key}}双大括号形式key 严格区分大小写所有时间、金额、枚举字段在放进去之前先格式化成展示字符串不要在模板里做逻辑输出文件名带上版本号不要用裸文件名否则多人并发调用接口时文件会互相覆盖。4.3 表格、图片和目录占位符的处理边界模板里动态表格有两种做法。行数不固定、结构简单的用循环块最方便但如果整个表格结构都变化就要用{{table}}语法并传入TableRenderData。我在 PRD 场景里一般只用循环块把表格标题和首行固定写在模板里只让数据行循环这样格式最稳定。图片是另一个常见边界。模板里写{{screenshot}}占位符代码里用Pictures对象传入字节数组和尺寸byte[] screenshotBytes loadFromFile(screenshot.png); data.put(screenshot, Pictures.of(screenshotBytes).size(480, 320).create());参数说明size的单位是磅不是像素。App 截图原始宽度如果是 750 像素显示宽度 480 磅比较合适不设尺寸图片会按原图分辨率塞进文档一张手机截图就能让 docx 膨胀到几十兆。目录这块是模板渲染方案最坑的环节。docx 里的 TOC 目录域在渲染后不会自动计算页码因为页码要等 Word 打开时才生成。常见做法是模板里保留 TOC 域渲染完成后用 Word 打开一次并更新域如果交付流程要求全自动就在 Windows 上调用 Word COM 接口刷新目录。没有自动化条件时明确告诉验收人“目录打开后按 CtrlA、F9 更新”不要承诺生成后的目录能直接打印。5. docx 避坑Windows 搜不到正文、模板乱码与并发覆盖这一章写我在交付和渲染过程中踩过的五个具体问题每一条都按“现象 → 原因 → 解决”来记录。这些问题如果不提前处理文档生成后往往要花更多时间排查。5.1 docx 在 Windows 搜索里搜不到正文现象、原因与解决现象测试在共享目录里搜索“还款提醒”旁边一个 txt 文件一搜就中这个 docx 文件明明就在目录里却搜不到。原因Windows 搜索能索引 docx 正文依赖本机安装的 Office 提供 iFilter 过滤器。文件放在网络共享盘、U 盘或没有加入索引的位置时索引服务默认不会解析这些内容另外docx 正文如果被放进了文本框或内容控件里iFilter 也可能读不到。很多由模板引擎生成的 docx正文确实存在word/document.xml里但搜索命不中原因几乎都在索引范围。解决先把文件拷到本机“文档”目录看能否搜到再到“索引选项”里把共享目录添加为索引位置。也可以用前面 3.3 节的办法先验证正文是否真实存在unzip -p build/51信用卡管家app产品需求文档.docx word/document.xml | grep -n 还款提醒如果这条命令能 grep 到关键词但 Windows 搜不到就确认是索引问题。如果 grep 不到问题出在生成侧优先检查模板引擎是否把内容写进了非标准节点。注意共享目录里的文件即使加了索引也可能延迟几分钟才能搜索。刚上传完文件就去搜搜不到不一定是文档坏了先等索引生效再下结论。5.2 模板引擎把日期渲染成一串数字现象、原因与解决现象后端渲染完成后打开 docx日期位置显示的是2024-10-11T09:30:00甚至是一串纯数字时间戳完全不是预期格式。原因poi-tl 等模板引擎在把 Java 对象转文本时对LocalDateTime和Date默认调用toString()而不是自动格式化。这不算 bug但确实容易在联调时才暴露。解决不要在数据模型里放日期对象进入模板前先格式化成指定字符串。data.put(submitDate, DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm).format(LocalDateTime.now()));逻辑说明格式化责任放在后端模板里的{{submitDate}}只负责展示。这条原则同样适用于金额和枚举值所有展示层的格式统一在后端完成模板里不要出现任何转换逻辑否则项目换人维护时很难查。5.3 图片一多文件就膨胀到几百兆现象、原因与解决现象PRD 里贴了几张 App 截图docx 从正常的 3 兆变成 180 兆打开要半分钟后端渲染时甚至直接内存溢出。原因从手机或截图工具直接粘贴的 PNG 常常是 2x 或 3x 分辨率单张原图可能 10 兆后端渲染时如果直接写入原始字节文档体积完全不可控。解决渲染前统一压缩宽边限制在 1440 像素、质量取 85%单张压缩后控制在 400KB 以内。再用Pictures.of限制显示尺寸。byte[] compressed ImageCompressor.compress(originalBytes, 1440, 0.85f); data.put(screenshot, Pictures.of(compressed).size(480, 320).create());参数说明压缩参数不是越高越好。PRD 里的截图主要是给人看文字和按钮位置1440 宽度、85 质量在普通电脑上已经足够清晰再往上只会增加体积。5.4 多人同时调后端渲染输出文件互相覆盖现象、原因与解决现象测试环境三个分支同时执行“生成产品需求文档”的任务拿到的目标 docx 一会是 A 版本一会是 B 版本后生成的把先生成的覆盖了。原因输出路径写死成了51信用卡管家app产品需求文档.docx进程并发写同一个文件没有加锁也没有版本隔离。解决输出文件名按“产品名_版本_日期_时间戳”规则生成并把“写文件”和“上传对象存储”拆成两步文件名在任务创建时就确定。建议命名51信用卡管家app产品需求文档_v1.2.0_20240512_163001.docx这个规则同样适用于手工出稿。产品经理手动存文档时如果按这个格式命名测试在 Windows 搜索里直接搜版本号就能定位文件比搜中文名更可靠。5.5 评审修订留痕被模板渲染清空现象、原因与解决现象评审时用 Word 修订模式在 docx 里改了一轮后端把文档重新渲染一次所有修订和批注全消失了。原因docx 的修订和批注存放在 XML 的w:ins、w:comment等结构化节点里。模板引擎渲染时只关心占位符不会承诺保留未绑定区域里的复杂元素重新保存后修订记录就丢了。解决把“评审稿”和“模板稿”分开。模板只用于生成干净的待评审版本一旦进入评审阶段后续修改直接在 Word 里做修订不再回后端重新渲染。如果确实需要自动化就改 Markdown 源稿后生成一个新版本并单独归档评审副本。不要指望模板引擎帮你保留批注这个能力目前不在它的设计目标里。6. 用一次批量渲染验证整套流程docx 也能做回归最后分享一个我常用的验证技巧把 docx 生成变成 CI 里的一道检查命令每次用同一份测试数据跑一遍渲染再提取正文文本做断言。这样目录和搜索问题在交付前就能暴露不用靠人肉打开 Word 检查。6.1 用 pandoc 把生成的 docx 转成纯文本后 grep渲染完成后先用 pandoc 把 docx 转成纯文本pandoc build/51信用卡管家app产品需求文档_v1.2.0.docx \ -t plain --wrapnone | grep -E 还款提醒|状态机|已还款逻辑说明-t plain输出纯文本--wrapnone禁止换行grep 用来检查关键需求点是否真的在正文里。如果这条命令一个关键词都命中不了说明占位符没渲染、章节丢了或者数据错位不需要打开 Word 就能定位。再进一步可以写一个 shell 循环对三份模拟输入分别渲染每一份 grep 不同关键词作为回归基线。6.2 目录可更新、文件可搜索是交付前的最后一道关除了内容断言我还会做三个固定验证用 unzip 确认正文 XML 里有关键词用 pandoc 确认文档能被读取为纯文本再把文件放到 Windows 搜索目录里搜版本号确认能命中。这三步全过才认为这份 docx 可以进入评审。我以前有个坏习惯打开 Word 看一眼样式觉得没问题就发出去后来在共享目录里搜不到评审稿被测试同事直接怼到工位上。从那以后“能搜索”就被我写进了交付验收清单。docx 是最普通的办公格式但正因为普通它的可搜索性、可更新目录、可批量渲染才是真正值得较真的地方。希望这些方法能帮你少走几步弯路。本文还有配套的精品资源点击获取