简介《软件技术预研方案模板》以 Word 文档形式提供一套可直接套用的技术预研方案框架面向软件项目经理、技术负责人与研发团队成员用于在项目启动前理清技术路线、评估可行性。文档共设八大部分引言部分涵盖编写目的、范围界定、术语定义与参考资料随后依次给出可验证的技术预研目标、人员与软硬件经费等工作条件、含评分等级的技术选型标准、应递交的工作成果清单、基于 Microsoft Project 或表格的进度表、困难与风险应对措施并在附录中预留计划审批意见栏形成从立项到审批的完整闭环。压缩包内仅 1 个 docx 文件约 46KB轻量易取用可按企业项目实际情况改写。目前已有 423 人学习下载适合需要快速搭建规范化预研文档、补齐技术选型与风险管理思路的开发与管理人员参考。1. 技术预研方案不是走过场一份 docx 模板要填出技术判断力互联网项目节奏快没人愿意花两周写文档但真正让人返工的往往不是代码是选型。有个团队在立项会上拍板用了某个流式框架两周后压测发现单节点吞吐只有目标的四成改回原方案又要动三个上游服务代价整整一个迭代。软件技术预研方案就是卡在这个节点上的东西在正式排期之前把「这项技术到底行不行」变成能被验证、能被否决的结论。这份《软件技术预研方案模板.docx》来自一套企业软件项目管理系列模板八个部分——引言、技术预研目标、工作条件、技术选型标准、应递交的工作成果、进度表、可能存在的困难与风险、附录每节下面都留了一行「提示」说明该写什么。它的价值不在排版而在结构目标可验证、选型有依据、成果能验收、风险有归属。适合三类人第一次独立扛预研任务的开发评审别人方案的技术负责人把预研当交付物管的项目经理。模板只给了字段名字段里填什么取决于你愿不愿意把判断过程写清楚。2. 模板骨架拆解八个章节的输入输出与数据源收敛大多数预研方案写得难看不是因为文笔是因为同一件事在文档里出现了三次三次还写得不一样。负责人名字在首页、在修改记录、在附录审批意见里各一份范围在 1.2 写一遍在 2 目标里又写一遍到第 5 章成果清单里变成第三版。等评审会上有人问「你说的兼容性到底包含哪些表」三个人翻三个地方答案对不上。解决办法是先理清章节之间的依赖关系再把重复出现的事实收敛到一个数据源里文档只做渲染。2.1 章节依赖链先有范围才有目标和成果模板的章节顺序不是随便排的。1.2 范围界定的是「研究什么、不研究什么」2 技术预研目标是从范围里挑出可度量的那几条4 技术选型标准决定了 5 的成果形态5 又反过来决定 6 进度表里要有哪些里程碑7 的风险条目则应该来自前面每一章里没把握的地方。章节核心字段上游依赖被谁引用常见返工点文档信息版本号、修改记录审批流程全文页眉与附录改了版本号没改修改记录1.1 编写目的预期读者立项文件附录审批意见写成「为了研究新技术」1.2 范围技术边界、明确不做的部分需求规格第 2、5 章只写做什么不写不做什么1.3 术语定义缩写、外文全称参考资料全文用词一致性定义了却在正文里换词4 技术选型标准维度、权重、等级锚点预研目标选型结论1/2/3 级没有判定依据5 应递交的成果名称、形式、验收人选型结论进度表里程碑成果写成「一份报告」6 进度表起止时间、里程碑、缓冲工作条件风险应对措施排满无缓冲无依赖关系7 困难与风险触发信号、应对措施、责任人前六章附录审批只列风险不给措施这张表的用法很简单写完任何一章回头看看它有没有上游输入。如果 1.2 范围写不出来说明需求规格还没读懂后面全是空转。注意5「应递交的工作成果」是全篇最容易被糊弄的一节。写「技术预研报告一份」等于没写评审时无法验收进度表上也排不出里程碑。2.2 用 YAML 做单一数据源避免同一事实写三遍我一般会在项目仓库里建一个prestudy/目录把方案里所有结构化事实放进plan.yamldocx 只负责渲染。这样评审意见改的是 YAML重新导出即可不会出现「文档里写 5000 TPS、附录里写 3000 TPS」的情况。# prestudy/plan.yaml —— 技术预研方案的机器可读单一数据源 project: name: 订单中心实时对账能力预研 owner: 张工 # 负责人对应模板文档信息页 author: 李工 # 编写人 reviewer: 王工 # 审核人 approver: 赵工 # 批准人 version: v0.3 # 必须与 changelog 最后一条一致 scope: in: # 1.2 范围做什么 - 流式对账引擎选型 - 峰值 5000 TPS 压测 - 与现有分库的兼容性验证 out: # 1.2 范围明确不做什么 - 对账规则的可视化配置 - 历史数据迁移方案 goals: # 第 2 章每条都要可验证 - id: G1 desc: 单节点吞吐不低于 5000 TPS1KB 报文 verify: bench/tps_test.py --tps 5000 # 可直接执行的验证命令 timeout: 1800 - id: G2 desc: 与现有分库表结构兼容零 DDL 变更 verify: sql/schema_diff.sql changelog: - { version: v0.2, date: 2024-05-08, note: 补充兼容性验证项 } - { version: v0.3, date: 2024-05-15, note: 权重调整见第 4 章 }写完之后加一个校验脚本把「可验证」这三个字落到实处。这个脚本我通常放在 CI 里提交 YAML 就自动跑。import yaml, pathlib, sys root pathlib.Path(__file__).parent plan yaml.safe_load((root / plan.yaml).read_text(encodingutf-8)) errors [] # 1) 每条预研目标必须指向一个真实存在的验证脚本否则「可验证」是空话 for g in plan[goals]: cmd g[verify].split()[0] if not (root.parent / cmd).exists(): errors.append(f{g[id]} 的验证脚本不存在: {cmd}) # 2) in / out 不能交叉交叉说明范围没想清楚 cross set(plan[scope][in]) set(plan[scope][out]) for dup in cross: errors.append(f范围冲突同一项既在做也不在做: {dup}) # 3) 文档信息页的版本号必须等于修改记录的最后一条 if plan[project][version] ! plan[changelog][-1][version]: errors.append(文档信息页版本号与修改记录不一致) if errors: print(\n.join(errors)) sys.exit(1) print(f校验通过共 {len(plan[goals])} 条可验证目标)逻辑说明三条校验分别对应模板里最容易出错的三处——第 2 章目标写空、第 1.2 章范围自相矛盾、文档信息页与修改记录脱节。脚本以退出码作为判定非零即失败方便挂进流水线。参数说明g[verify]取第一个空格前的字符串当路径所以验证命令必须是相对仓库根目录的可执行文件不能是「人工检查」这类描述sys.exit(1)让 CI 直接标红如果某条目标确实只能人工判定就在 YAML 里把它移到单独的manual_goals列表并在第 5 章成果里写明验收人不要留在goals里凑数。2.3 术语表与参考资料的引用一致性检查1.3 术语定义这一节写的时候很认真用的时候全忘。常见结果是术语表里写了TPS正文里一会儿写 TPS 一会儿写「每秒事务数」。用两行 shell 就能查出来。# 从术语表抽出以大写字母开头的缩写检查正文里是否至少被引用两次 # 一次是定义本身一次是实际使用 grep -oP ^\|\s*\K[A-Z][A-Za-z0-9] docs/terms.md | while read -r term; do count$(grep -c -- $term docs/plan.md) if [ $count -lt 2 ]; then echo 术语 $term 在正文中未被实际使用 fi donegrep -oP里的\K用于丢弃匹配前缀只保留缩写本身-c统计出现行数而非次数够用且快。这条命令的输出建议直接贴进评审邮件的「待确认项」比在会上口头问有效。3. 技术选型标准量化从 1/2/3 等级到加权评分矩阵第 4 章「技术选型标准」是整份方案里最容易变成摆设的一节。模板给的提示是「1-不能满足要求2-基本满足要求3-完全满足要求」很多人照着抄一遍就完事最后评出来的分数谁都不服。问题出在等级没有锚点什么叫「基本满足」性能维度上是 3000 TPS 还是 5000 TPS没有锚点评分就是投票。3.1 维度、权重与等级锚点先定维度再定权重最后给每个维度的三个等级写死判定条件。判定条件要能被引用最好直接指向第 2 章的目标编号或验证脚本。维度权重1-不能满足2-基本满足3-完全满足数据来源性能0.25压测低于目标 60%达到目标 60%~100%达到 G1 且 P99 ≤ 50msbench/tps_test.py兼容性0.20需改 3 张以上表结构需改 1~2 张表schema_diff.sql 结果为空sql/schema_diff.sql技术成熟度0.15无生产案例有同规模案例但版本较新两个以上同规模生产案例内部案例库可维护性0.15团队无人读过源码有人做过 POC有成员参与过社区贡献团队技能盘点掌握成本0.15需外部培训 ≥5 人日2~5 人日≤2 人日跑通主链路POC 工时记录许可与合规0.10许可证与商用冲突需法务确认已在白名单许可证清单提示权重之和必须为 1这是后面评分脚本的硬约束。如果某个维度的权重调不动说明它其实不是独立维度考虑合并。3.2 加权评分与权重敏感性分析有了锚点评分就变成一个矩阵乘法。但只算加权得分还不够——如果权重动一动排名就翻盘那这个选型结论根本站不住。所以我会同时跑一遍敏感性分析。import numpy as np # 候选技术与各维度得分1/2/3顺序与 weights 严格对齐 # 维度顺序性能 / 兼容性 / 成熟度 / 可维护性 / 掌握成本 / 许可 candidates { Kafka Streams: [3, 2, 3, 3, 3, 2], Flink: [3, 3, 3, 2, 2, 1], 自研轮询对账: [1, 3, 1, 1, 3, 3], } weights np.array([0.25, 0.20, 0.15, 0.15, 0.15, 0.10]) assert abs(weights.sum() - 1) 1e-9, 权重之和必须为 1 scores np.array(list(candidates.values()), dtypefloat) base scores weights best list(candidates)[int(base.argmax())] # 敏感性分析逐个维度权重上下浮动 20%看第一名会不会被翻盘 flip [] for i in range(len(weights)): for delta in (0.2, -0.2): w weights.copy() w[i] * (1 delta) w w / w.sum() # 重新归一化否则和不等于 1 top list(candidates)[int((scores w).argmax())] if top ! best: flip.append((i, delta, top)) for name, s in sorted(zip(candidates, base), keylambda x: -x[1]): print(f{name:16s} 加权得分 {s:.3f}) print(权重敏感导致的排名变化:, flip or 无)逻辑说明scores weights一次算出所有候选的加权总分避免手算错行。敏感性分析对每个维度的权重各扰动 ±20%重新归一化后重算排名只要出现翻盘就记录下来。参数说明delta取 0.2 是经验值——如果 ±20% 权重就翻盘说明两名候选的差距在噪声范围内此时应当补充验证项比如把 G1 的压测从单节点扩到三节点而不是硬选。输出里flip为空才说明结论稳健不为空时必须在第 7 章风险里写明「选型结论对 X 维度权重敏感若该维度评估有误需重评」。3.3 评分结果回填到 docx 表格分数算完还要回到 docx 里。用 python-docx 直接操作模板注意是基于模板对象打开再保存不要新建。from docx import Document # 基于原模板打开页眉页脚、样式、修改记录都会保留 doc Document(模板/软件技术预研方案模板.docx) tbl doc.add_table(rows1, cols4) tbl.style Table Grid # 用模板自带样式名别自造 for cell, title in zip(tbl.rows[0].cells, [候选技术, 加权得分, 等级结论, 关键短板]): cell.text title for p in cell.paragraphs: # 表头加粗要落到 run 上 for r in p.runs: r.bold True for name, s in sorted(zip(candidates, base), keylambda x: -x[1]): row tbl.add_row().cells row[0].text name row[1].text f{s:.3f} row[2].text 3-完全满足 if s 2.5 else 2-基本满足 row[3].text — # 短板从敏感性分析结果里回填 doc.save(输出/软件技术预研方案_订单中心_v0.3.docx)逻辑说明Document(路径)打开已有模板会保留原有样式表、页眉页脚和正文Document()空构造则会丢掉这些很多人栽在这一步。表格样式名必须与模板中已有的样式一致否则 Word 打开会提示样式缺失。参数说明s 2.5这个阈值对应「加权平均达到基本满足与完全满足之间」可以根据维度数量调整如果候选数超过 5 个建议把表格拆成两页并在第 5 章成果里说明评分明细表作为附件单独交付。4. 预研目标可验证化验收断言、压测与兼容性校验模板第 2 章写着一句「必须是可以验证的」这六个字是整份方案的技术含量所在。可验证的意思是换一个人来读能得出同一个结论而且这个结论有脚本或数据支撑。4.1 把模糊目标翻译成可执行断言模糊写法可验证写法验证手段提升对账性能单节点 1KB 报文 ≥5000 TPSP99 ≤50msbench/tps_test.py --tps 5000兼容现有库分库表结构零 DDL 变更字段类型映射覆盖 100%sql/schema_diff.sql技术上手上快2 人 5 人日内跑通 POC 主链路POC 提交记录 工时表社区活跃近 6 个月发版 ≥3 次提交者 ≥5 人仓库元数据快照右列才是关键——验证手段必须是可执行的命令或可归档的数据快照。写「组织评审」不算验证手段因为它没有判定标准。4.2 验证运行器把所有目标逐条跑一遍一条条手动跑验证脚本容易漏写个运行器统一执行输出一份 JSON 记录直接作为第 5 章「应递交的工作成果」的附件。import subprocess, yaml, json, time, pathlib plan yaml.safe_load(pathlib.Path(prestudy/plan.yaml).read_text(encodingutf-8)) report [] for g in plan[goals]: t0 time.time() # verify 是一条可直接执行的命令例如 bench/tps_test.py --tps 5000 p subprocess.run( g[verify].split(), capture_outputTrue, textTrue, timeoutg.get(timeout, 1800), # 默认 30 分钟防止脚本卡死 ) report.append({ id: g[id], desc: g[desc], pass: p.returncode 0, # 退出码是唯一判定标准 seconds: round(time.time() - t0, 1), tail: p.stdout.strip().splitlines()[-3:], # 只留尾部三行贴进报告 }) pathlib.Path(输出/预研验证记录.json).write_text( json.dumps(report, ensure_asciiFalse, indent2), encodingutf-8) print(未通过目标:, [r[id] for r in report if not r[pass]] or 无)逻辑说明以子进程退出码作为唯一判定标准脚本内部怎么断言由验证脚本自己决定运行器不掺和业务逻辑。截取 stdout 尾部三行是为了让记录文件保持精简避免把整段压测日志塞进方案正文。参数说明timeout从 YAML 逐条读取默认 1800 秒压测类目标建议单独放宽到 3600。pass为 false 的目标必须在附录审批意见之前处理掉要么补验证要么在风险章节登记为已知偏差——两条路都行但空着不行。4.3 兼容性验证的 SQL让差异结果集为零涉及数据层的预研兼容性目标最容易含糊。直接查information_schema对比两套库的表结构结果集为空就是达标。-- 对比预研库与生产库的表结构差异输出所有需要变更的列 SELECT c.TABLE_NAME, c.COLUMN_NAME, c.COLUMN_TYPE AS prestudy_type, p.COLUMN_TYPE AS prod_type, CASE WHEN p.COLUMN_NAME IS NULL THEN 新增列 ELSE 类型不一致 END AS diff_kind FROM information_schema.COLUMNS c LEFT JOIN information_schema.COLUMNS p ON p.TABLE_SCHEMA prod_db AND p.TABLE_NAME c.TABLE_NAME AND p.COLUMN_NAME c.COLUMN_NAME WHERE c.TABLE_SCHEMA prestudy_db AND (p.COLUMN_NAME IS NULL OR p.COLUMN_TYPE c.COLUMN_TYPE) ORDER BY diff_kind, c.TABLE_NAME, c.COLUMN_NAME;逻辑说明以预研库为主表左连生产库只保留「生产库没有这一列」或「两边类型不同」的行因此空结果集直接等价于兼容性目标达成。参数说明TABLE_SCHEMA换成实际库名如果两边字符集定义不同但类型一致需要额外加一条COLLATION_NAME的比较条件。这个查询有个前提——预研库是从生产库的结构快照建的如果预研库本身已经改过结果就失去意义。4.4 成果清单与进度表对齐第 5 章列的每一项成果都必须在第 6 章进度表里对应一个里程碑否则排期里没人认领这件事。成果名称形式验收人对应里程碑判定方式选型评分明细表附件表格技术负责人M2 选型评审权重敏感性分析无翻盘压测记录JSON 图表架构组M3 性能验证验证运行器全部 pass兼容性对比结果SQL 结果集DBAM3 性能验证结果集为空预研报告正文docx项目经理M4 方案评审附录审批意见签字提示验收人和里程碑必须落在具体人头上。写「项目组」等于没人负责进度表里也画不出依赖箭头。5. 风险登记与文档流水线5.1 风险字段与触发信号第 7 章的模板提示只有一句话实际写的时候至少要拆成六列。触发信号这一列最值钱它把「风险」从形容词变成了可以监控的条件。风险ID描述概率影响触发信号应对措施责任人R1压测达不到 5000 TPS中高连续两次压测低于 4000 TPS降级为集群方案工期 5 人日李工R2某组件许可证与商用冲突低高法务回复「需确认」切换候选二见 3.2 评分表王工R3预研人力被业务需求抽调高中双周迭代内投入低于 0.5 人冻结范围 out 列表保 M3 里程碑张工R1 的触发信号直接来自压测脚本的输出可以做到自动化告警把验证运行器接进定时任务连续两次 fail 就发消息给责任人。5.2 用 docxtpl 把 YAML 渲染成合规 docx最后一招是把整个流程闭环。先把模板复制一份另存为方案模板_tpl.docx把正文里所有「提示」整段替换成 Jinja2 占位符原件保持不动作为基线。# pip install docxtpl from docxtpl import DocxTemplate import yaml, pathlib plan yaml.safe_load(pathlib.Path(prestudy/plan.yaml).read_text(encodingutf-8)) tpl DocxTemplate(模板/方案模板_tpl.docx) tpl.render({ project: plan[project], # 首页文档信息 页眉 scope_in: plan[scope][in], # 1.2 范围渲染为列表项 scope_out: plan[scope][out], goals: plan[goals], # 第 2 章目标表 changelog: plan[changelog], # 修改记录表 }) tpl.save(f输出/软件技术预研方案_{plan[project][version]}.docx)渲染时把changelog一起带进去修改记录就不会和版本号脱节。用 git 管plan.yaml每次评审前打一个 tag附录里的审批意见就能对上版本号——评审查的是 v0.3导出的就是 v0.3不会出现「文档改过但没人知道改了什么」。评审前一天跑一遍第 2 章的校验脚本和第 4 章的验证运行器把输出/预研验证记录.json里 fail 的条目清空比在会上解释为什么没做完省事得多。本文还有配套的精品资源点击获取 软件技术预研方案模板：YAML数据源与可验证选型评分
简介《软件技术预研方案模板》以 Word 文档形式提供一套可直接套用的技术预研方案框架面向软件项目经理、技术负责人与研发团队成员用于在项目启动前理清技术路线、评估可行性。文档共设八大部分引言部分涵盖编写目的、范围界定、术语定义与参考资料随后依次给出可验证的技术预研目标、人员与软硬件经费等工作条件、含评分等级的技术选型标准、应递交的工作成果清单、基于 Microsoft Project 或表格的进度表、困难与风险应对措施并在附录中预留计划审批意见栏形成从立项到审批的完整闭环。压缩包内仅 1 个 docx 文件约 46KB轻量易取用可按企业项目实际情况改写。目前已有 423 人学习下载适合需要快速搭建规范化预研文档、补齐技术选型与风险管理思路的开发与管理人员参考。1. 技术预研方案不是走过场一份 docx 模板要填出技术判断力互联网项目节奏快没人愿意花两周写文档但真正让人返工的往往不是代码是选型。有个团队在立项会上拍板用了某个流式框架两周后压测发现单节点吞吐只有目标的四成改回原方案又要动三个上游服务代价整整一个迭代。软件技术预研方案就是卡在这个节点上的东西在正式排期之前把「这项技术到底行不行」变成能被验证、能被否决的结论。这份《软件技术预研方案模板.docx》来自一套企业软件项目管理系列模板八个部分——引言、技术预研目标、工作条件、技术选型标准、应递交的工作成果、进度表、可能存在的困难与风险、附录每节下面都留了一行「提示」说明该写什么。它的价值不在排版而在结构目标可验证、选型有依据、成果能验收、风险有归属。适合三类人第一次独立扛预研任务的开发评审别人方案的技术负责人把预研当交付物管的项目经理。模板只给了字段名字段里填什么取决于你愿不愿意把判断过程写清楚。2. 模板骨架拆解八个章节的输入输出与数据源收敛大多数预研方案写得难看不是因为文笔是因为同一件事在文档里出现了三次三次还写得不一样。负责人名字在首页、在修改记录、在附录审批意见里各一份范围在 1.2 写一遍在 2 目标里又写一遍到第 5 章成果清单里变成第三版。等评审会上有人问「你说的兼容性到底包含哪些表」三个人翻三个地方答案对不上。解决办法是先理清章节之间的依赖关系再把重复出现的事实收敛到一个数据源里文档只做渲染。2.1 章节依赖链先有范围才有目标和成果模板的章节顺序不是随便排的。1.2 范围界定的是「研究什么、不研究什么」2 技术预研目标是从范围里挑出可度量的那几条4 技术选型标准决定了 5 的成果形态5 又反过来决定 6 进度表里要有哪些里程碑7 的风险条目则应该来自前面每一章里没把握的地方。章节核心字段上游依赖被谁引用常见返工点文档信息版本号、修改记录审批流程全文页眉与附录改了版本号没改修改记录1.1 编写目的预期读者立项文件附录审批意见写成「为了研究新技术」1.2 范围技术边界、明确不做的部分需求规格第 2、5 章只写做什么不写不做什么1.3 术语定义缩写、外文全称参考资料全文用词一致性定义了却在正文里换词4 技术选型标准维度、权重、等级锚点预研目标选型结论1/2/3 级没有判定依据5 应递交的成果名称、形式、验收人选型结论进度表里程碑成果写成「一份报告」6 进度表起止时间、里程碑、缓冲工作条件风险应对措施排满无缓冲无依赖关系7 困难与风险触发信号、应对措施、责任人前六章附录审批只列风险不给措施这张表的用法很简单写完任何一章回头看看它有没有上游输入。如果 1.2 范围写不出来说明需求规格还没读懂后面全是空转。注意5「应递交的工作成果」是全篇最容易被糊弄的一节。写「技术预研报告一份」等于没写评审时无法验收进度表上也排不出里程碑。2.2 用 YAML 做单一数据源避免同一事实写三遍我一般会在项目仓库里建一个prestudy/目录把方案里所有结构化事实放进plan.yamldocx 只负责渲染。这样评审意见改的是 YAML重新导出即可不会出现「文档里写 5000 TPS、附录里写 3000 TPS」的情况。# prestudy/plan.yaml —— 技术预研方案的机器可读单一数据源 project: name: 订单中心实时对账能力预研 owner: 张工 # 负责人对应模板文档信息页 author: 李工 # 编写人 reviewer: 王工 # 审核人 approver: 赵工 # 批准人 version: v0.3 # 必须与 changelog 最后一条一致 scope: in: # 1.2 范围做什么 - 流式对账引擎选型 - 峰值 5000 TPS 压测 - 与现有分库的兼容性验证 out: # 1.2 范围明确不做什么 - 对账规则的可视化配置 - 历史数据迁移方案 goals: # 第 2 章每条都要可验证 - id: G1 desc: 单节点吞吐不低于 5000 TPS1KB 报文 verify: bench/tps_test.py --tps 5000 # 可直接执行的验证命令 timeout: 1800 - id: G2 desc: 与现有分库表结构兼容零 DDL 变更 verify: sql/schema_diff.sql changelog: - { version: v0.2, date: 2024-05-08, note: 补充兼容性验证项 } - { version: v0.3, date: 2024-05-15, note: 权重调整见第 4 章 }写完之后加一个校验脚本把「可验证」这三个字落到实处。这个脚本我通常放在 CI 里提交 YAML 就自动跑。import yaml, pathlib, sys root pathlib.Path(__file__).parent plan yaml.safe_load((root / plan.yaml).read_text(encodingutf-8)) errors [] # 1) 每条预研目标必须指向一个真实存在的验证脚本否则「可验证」是空话 for g in plan[goals]: cmd g[verify].split()[0] if not (root.parent / cmd).exists(): errors.append(f{g[id]} 的验证脚本不存在: {cmd}) # 2) in / out 不能交叉交叉说明范围没想清楚 cross set(plan[scope][in]) set(plan[scope][out]) for dup in cross: errors.append(f范围冲突同一项既在做也不在做: {dup}) # 3) 文档信息页的版本号必须等于修改记录的最后一条 if plan[project][version] ! plan[changelog][-1][version]: errors.append(文档信息页版本号与修改记录不一致) if errors: print(\n.join(errors)) sys.exit(1) print(f校验通过共 {len(plan[goals])} 条可验证目标)逻辑说明三条校验分别对应模板里最容易出错的三处——第 2 章目标写空、第 1.2 章范围自相矛盾、文档信息页与修改记录脱节。脚本以退出码作为判定非零即失败方便挂进流水线。参数说明g[verify]取第一个空格前的字符串当路径所以验证命令必须是相对仓库根目录的可执行文件不能是「人工检查」这类描述sys.exit(1)让 CI 直接标红如果某条目标确实只能人工判定就在 YAML 里把它移到单独的manual_goals列表并在第 5 章成果里写明验收人不要留在goals里凑数。2.3 术语表与参考资料的引用一致性检查1.3 术语定义这一节写的时候很认真用的时候全忘。常见结果是术语表里写了TPS正文里一会儿写 TPS 一会儿写「每秒事务数」。用两行 shell 就能查出来。# 从术语表抽出以大写字母开头的缩写检查正文里是否至少被引用两次 # 一次是定义本身一次是实际使用 grep -oP ^\|\s*\K[A-Z][A-Za-z0-9] docs/terms.md | while read -r term; do count$(grep -c -- $term docs/plan.md) if [ $count -lt 2 ]; then echo 术语 $term 在正文中未被实际使用 fi donegrep -oP里的\K用于丢弃匹配前缀只保留缩写本身-c统计出现行数而非次数够用且快。这条命令的输出建议直接贴进评审邮件的「待确认项」比在会上口头问有效。3. 技术选型标准量化从 1/2/3 等级到加权评分矩阵第 4 章「技术选型标准」是整份方案里最容易变成摆设的一节。模板给的提示是「1-不能满足要求2-基本满足要求3-完全满足要求」很多人照着抄一遍就完事最后评出来的分数谁都不服。问题出在等级没有锚点什么叫「基本满足」性能维度上是 3000 TPS 还是 5000 TPS没有锚点评分就是投票。3.1 维度、权重与等级锚点先定维度再定权重最后给每个维度的三个等级写死判定条件。判定条件要能被引用最好直接指向第 2 章的目标编号或验证脚本。维度权重1-不能满足2-基本满足3-完全满足数据来源性能0.25压测低于目标 60%达到目标 60%~100%达到 G1 且 P99 ≤ 50msbench/tps_test.py兼容性0.20需改 3 张以上表结构需改 1~2 张表schema_diff.sql 结果为空sql/schema_diff.sql技术成熟度0.15无生产案例有同规模案例但版本较新两个以上同规模生产案例内部案例库可维护性0.15团队无人读过源码有人做过 POC有成员参与过社区贡献团队技能盘点掌握成本0.15需外部培训 ≥5 人日2~5 人日≤2 人日跑通主链路POC 工时记录许可与合规0.10许可证与商用冲突需法务确认已在白名单许可证清单提示权重之和必须为 1这是后面评分脚本的硬约束。如果某个维度的权重调不动说明它其实不是独立维度考虑合并。3.2 加权评分与权重敏感性分析有了锚点评分就变成一个矩阵乘法。但只算加权得分还不够——如果权重动一动排名就翻盘那这个选型结论根本站不住。所以我会同时跑一遍敏感性分析。import numpy as np # 候选技术与各维度得分1/2/3顺序与 weights 严格对齐 # 维度顺序性能 / 兼容性 / 成熟度 / 可维护性 / 掌握成本 / 许可 candidates { Kafka Streams: [3, 2, 3, 3, 3, 2], Flink: [3, 3, 3, 2, 2, 1], 自研轮询对账: [1, 3, 1, 1, 3, 3], } weights np.array([0.25, 0.20, 0.15, 0.15, 0.15, 0.10]) assert abs(weights.sum() - 1) 1e-9, 权重之和必须为 1 scores np.array(list(candidates.values()), dtypefloat) base scores weights best list(candidates)[int(base.argmax())] # 敏感性分析逐个维度权重上下浮动 20%看第一名会不会被翻盘 flip [] for i in range(len(weights)): for delta in (0.2, -0.2): w weights.copy() w[i] * (1 delta) w w / w.sum() # 重新归一化否则和不等于 1 top list(candidates)[int((scores w).argmax())] if top ! best: flip.append((i, delta, top)) for name, s in sorted(zip(candidates, base), keylambda x: -x[1]): print(f{name:16s} 加权得分 {s:.3f}) print(权重敏感导致的排名变化:, flip or 无)逻辑说明scores weights一次算出所有候选的加权总分避免手算错行。敏感性分析对每个维度的权重各扰动 ±20%重新归一化后重算排名只要出现翻盘就记录下来。参数说明delta取 0.2 是经验值——如果 ±20% 权重就翻盘说明两名候选的差距在噪声范围内此时应当补充验证项比如把 G1 的压测从单节点扩到三节点而不是硬选。输出里flip为空才说明结论稳健不为空时必须在第 7 章风险里写明「选型结论对 X 维度权重敏感若该维度评估有误需重评」。3.3 评分结果回填到 docx 表格分数算完还要回到 docx 里。用 python-docx 直接操作模板注意是基于模板对象打开再保存不要新建。from docx import Document # 基于原模板打开页眉页脚、样式、修改记录都会保留 doc Document(模板/软件技术预研方案模板.docx) tbl doc.add_table(rows1, cols4) tbl.style Table Grid # 用模板自带样式名别自造 for cell, title in zip(tbl.rows[0].cells, [候选技术, 加权得分, 等级结论, 关键短板]): cell.text title for p in cell.paragraphs: # 表头加粗要落到 run 上 for r in p.runs: r.bold True for name, s in sorted(zip(candidates, base), keylambda x: -x[1]): row tbl.add_row().cells row[0].text name row[1].text f{s:.3f} row[2].text 3-完全满足 if s 2.5 else 2-基本满足 row[3].text — # 短板从敏感性分析结果里回填 doc.save(输出/软件技术预研方案_订单中心_v0.3.docx)逻辑说明Document(路径)打开已有模板会保留原有样式表、页眉页脚和正文Document()空构造则会丢掉这些很多人栽在这一步。表格样式名必须与模板中已有的样式一致否则 Word 打开会提示样式缺失。参数说明s 2.5这个阈值对应「加权平均达到基本满足与完全满足之间」可以根据维度数量调整如果候选数超过 5 个建议把表格拆成两页并在第 5 章成果里说明评分明细表作为附件单独交付。4. 预研目标可验证化验收断言、压测与兼容性校验模板第 2 章写着一句「必须是可以验证的」这六个字是整份方案的技术含量所在。可验证的意思是换一个人来读能得出同一个结论而且这个结论有脚本或数据支撑。4.1 把模糊目标翻译成可执行断言模糊写法可验证写法验证手段提升对账性能单节点 1KB 报文 ≥5000 TPSP99 ≤50msbench/tps_test.py --tps 5000兼容现有库分库表结构零 DDL 变更字段类型映射覆盖 100%sql/schema_diff.sql技术上手上快2 人 5 人日内跑通 POC 主链路POC 提交记录 工时表社区活跃近 6 个月发版 ≥3 次提交者 ≥5 人仓库元数据快照右列才是关键——验证手段必须是可执行的命令或可归档的数据快照。写「组织评审」不算验证手段因为它没有判定标准。4.2 验证运行器把所有目标逐条跑一遍一条条手动跑验证脚本容易漏写个运行器统一执行输出一份 JSON 记录直接作为第 5 章「应递交的工作成果」的附件。import subprocess, yaml, json, time, pathlib plan yaml.safe_load(pathlib.Path(prestudy/plan.yaml).read_text(encodingutf-8)) report [] for g in plan[goals]: t0 time.time() # verify 是一条可直接执行的命令例如 bench/tps_test.py --tps 5000 p subprocess.run( g[verify].split(), capture_outputTrue, textTrue, timeoutg.get(timeout, 1800), # 默认 30 分钟防止脚本卡死 ) report.append({ id: g[id], desc: g[desc], pass: p.returncode 0, # 退出码是唯一判定标准 seconds: round(time.time() - t0, 1), tail: p.stdout.strip().splitlines()[-3:], # 只留尾部三行贴进报告 }) pathlib.Path(输出/预研验证记录.json).write_text( json.dumps(report, ensure_asciiFalse, indent2), encodingutf-8) print(未通过目标:, [r[id] for r in report if not r[pass]] or 无)逻辑说明以子进程退出码作为唯一判定标准脚本内部怎么断言由验证脚本自己决定运行器不掺和业务逻辑。截取 stdout 尾部三行是为了让记录文件保持精简避免把整段压测日志塞进方案正文。参数说明timeout从 YAML 逐条读取默认 1800 秒压测类目标建议单独放宽到 3600。pass为 false 的目标必须在附录审批意见之前处理掉要么补验证要么在风险章节登记为已知偏差——两条路都行但空着不行。4.3 兼容性验证的 SQL让差异结果集为零涉及数据层的预研兼容性目标最容易含糊。直接查information_schema对比两套库的表结构结果集为空就是达标。-- 对比预研库与生产库的表结构差异输出所有需要变更的列 SELECT c.TABLE_NAME, c.COLUMN_NAME, c.COLUMN_TYPE AS prestudy_type, p.COLUMN_TYPE AS prod_type, CASE WHEN p.COLUMN_NAME IS NULL THEN 新增列 ELSE 类型不一致 END AS diff_kind FROM information_schema.COLUMNS c LEFT JOIN information_schema.COLUMNS p ON p.TABLE_SCHEMA prod_db AND p.TABLE_NAME c.TABLE_NAME AND p.COLUMN_NAME c.COLUMN_NAME WHERE c.TABLE_SCHEMA prestudy_db AND (p.COLUMN_NAME IS NULL OR p.COLUMN_TYPE c.COLUMN_TYPE) ORDER BY diff_kind, c.TABLE_NAME, c.COLUMN_NAME;逻辑说明以预研库为主表左连生产库只保留「生产库没有这一列」或「两边类型不同」的行因此空结果集直接等价于兼容性目标达成。参数说明TABLE_SCHEMA换成实际库名如果两边字符集定义不同但类型一致需要额外加一条COLLATION_NAME的比较条件。这个查询有个前提——预研库是从生产库的结构快照建的如果预研库本身已经改过结果就失去意义。4.4 成果清单与进度表对齐第 5 章列的每一项成果都必须在第 6 章进度表里对应一个里程碑否则排期里没人认领这件事。成果名称形式验收人对应里程碑判定方式选型评分明细表附件表格技术负责人M2 选型评审权重敏感性分析无翻盘压测记录JSON 图表架构组M3 性能验证验证运行器全部 pass兼容性对比结果SQL 结果集DBAM3 性能验证结果集为空预研报告正文docx项目经理M4 方案评审附录审批意见签字提示验收人和里程碑必须落在具体人头上。写「项目组」等于没人负责进度表里也画不出依赖箭头。5. 风险登记与文档流水线5.1 风险字段与触发信号第 7 章的模板提示只有一句话实际写的时候至少要拆成六列。触发信号这一列最值钱它把「风险」从形容词变成了可以监控的条件。风险ID描述概率影响触发信号应对措施责任人R1压测达不到 5000 TPS中高连续两次压测低于 4000 TPS降级为集群方案工期 5 人日李工R2某组件许可证与商用冲突低高法务回复「需确认」切换候选二见 3.2 评分表王工R3预研人力被业务需求抽调高中双周迭代内投入低于 0.5 人冻结范围 out 列表保 M3 里程碑张工R1 的触发信号直接来自压测脚本的输出可以做到自动化告警把验证运行器接进定时任务连续两次 fail 就发消息给责任人。5.2 用 docxtpl 把 YAML 渲染成合规 docx最后一招是把整个流程闭环。先把模板复制一份另存为方案模板_tpl.docx把正文里所有「提示」整段替换成 Jinja2 占位符原件保持不动作为基线。# pip install docxtpl from docxtpl import DocxTemplate import yaml, pathlib plan yaml.safe_load(pathlib.Path(prestudy/plan.yaml).read_text(encodingutf-8)) tpl DocxTemplate(模板/方案模板_tpl.docx) tpl.render({ project: plan[project], # 首页文档信息 页眉 scope_in: plan[scope][in], # 1.2 范围渲染为列表项 scope_out: plan[scope][out], goals: plan[goals], # 第 2 章目标表 changelog: plan[changelog], # 修改记录表 }) tpl.save(f输出/软件技术预研方案_{plan[project][version]}.docx)渲染时把changelog一起带进去修改记录就不会和版本号脱节。用 git 管plan.yaml每次评审前打一个 tag附录里的审批意见就能对上版本号——评审查的是 v0.3导出的就是 v0.3不会出现「文档改过但没人知道改了什么」。评审前一天跑一遍第 2 章的校验脚本和第 4 章的验证运行器把输出/预研验证记录.json里 fail 的条目清空比在会上解释为什么没做完省事得多。本文还有配套的精品资源点击获取