IT技术研发文档

1、第一部分总纲一、目 的：（1 ）规范公司内部技术研发工作的文档经管；（2） 保持技术研发工作的完整性与连续性；（3） 防止技术流失，减少风险；（4） 使技术文档成为技术研发工作中的重要组成部分。二、适用范围：本公司内部一切与技术研发有关的部门及个人，包括（5） ）总经理；（6） 技术部门经理或负责人；（7） 研发工程师；（8） 测试工程师；（9） 技术支持工程师。三、目 标：通过切实可行的文档经管规范，使得研发工作透明，明确，有章可循，合作无障碍，衔接环节畅通；使得所有的研发产品从开始研发研发进程测试修改阶段性结束产品转化升级维护过程中的所有环节都得以在相应的文档中体现。四、版 本：E2003

2、V0.10 （简称 V0.10）。五、制定原则：（10） ） 实用：鉴于公司目前的状况，通用性的开发模板（如国标）在很大程度上对于本公司并不实用，所以本规范将不会完全照搬此类模板，而是根据公司的具体情况制定公司内部的规范；（ 2） 可行：可行性是该规范的起码要求，没有可行性的规范不能成为真正的“规范”；（ 3） 高效：如果将国标中的所有规范内容都纳入本规范，一定可以达到目的，实现目标。但是，同时必将为相关人员增添大量的工作量，而且很多工作对于本公司来说是冗余，从而造成相关人员的抵触情绪，使规范难于贯彻。所以，本规范应力求在尽量少的模板中体现尽量多的内容；（ 4） 科学：本规范的制定虽然不完全照

3、搬其他通用性的规范，但将大量参照通用规范，特别是国标中的某些部分内容，不是抛弃国标，而是以国标为原则，以保证科学性；（ 5） 建立在广泛意见基础上：本规范并非公司某一个人单方面的意愿，而是从公司利益出发，全体相关人员共同参与，集体的结晶。六、实行过程及生效日期：（ 1 ）V0.10 版的规范为规范草稿，草稿制订完成后，将在相关部门和相关人员中进行传阅和广泛征求意见。经过三次全体相关人员参与讨论和修改，由总经理审批签字后的规范版本为0.40。(2) V0.40为试用版本，在 V0.40的试用过程中，将要求并给予相关人员以合理的时间尽量按照V0.40版的要求规范修改，补充和完善V0.40版以前(包

4、括V0.10以前欠缺的文档)的有价值文档。在此期间，如有新的研发工作开始启动，将要求相关人员按 照V0.40版的规范要求进行文档的相关操作。在此过程中，如果发现规范中需要修改和补充之处，每经过一次大幅度的修改， 版本即升级到 V0.5i (i=1,2,3，n,),每经过一次小的修改或补充，版本将升级为V0.4j (j=1,2,3，,n)。(3 )V1.00为正式版本。此时的版本已经经过讨论，试用，修改，补充和不断完善，并且 V1.00以前欠缺的文档与 V0.40试用过程中的文档都已经按照 V0.40版本的要求整理完毕，此时的 V0.40版已经成熟，可以整体升级到V1.00版。V1.00版本的文

5、档规范将作为公司内部与技术研发工作相关的所有人员在今后相当一段时间内共同遵守的规范，并且将文档的撰写工作作为技术研发的一个重要组成部分正式纳入到技术研发工作中。(4 )V1.00规范将具有强制性和高约束力。(注：Vi.00, i=0,1,2，表示i版本系列；Vi.mn , i, m, n=0, 1, 2,表示i版本系列下的改动或升级)第二部分目录索引一、版本控制规则二、立项1、说明2、模板三、需求分析1、说明2、模板四、可行性分析1、说明2、模板五、功能定义1、说明2. 模板六、概要设计1、硬件部分（1 ）说明（2）模板2、软件部分（1 ）说明（2）模板七、详细设计1、硬件部分（1 ）说明（2

6、）模板2、软件部分（1 ）说明（2）模板八、测试1、测试流程2、测试要求（1 ）硬件部分（2）软件部分3、测试模板（1 ）硬件部分2 软件部分 九、从研发到产品的过渡( 1要求( 2模板十、技术支持(1要求(2模板H一、文档工作的评估与审核(1评估规范(2审核要点第三部分内容、版本控制规则(1) 版本状态：Beta/测试版，Release/E式版，Changing/变更(2) 版本号：版本号以三位数字表示，格式为 i.jk (i=0, 1, 2,，n； jk=01 ,，99)a. Beta 版， i=0b. 第一次正式发布的 Release版，1.00c. 用Changing来表示Beta或R

7、elease版本的修改或升级d. 小的改动或升级i ， j 保持不变，只增加k 值即可，k 的升值幅度为修改或升级处的数目，当k 值达到或增加至9 时， j=j+1 ，k=0e. 比较大的改动如，一次修改或升级处的数目>10，功能性的增加或改变，则i 保持不变，增加j 值。如果是功能性的修改或变动，每有一项j+1 ；如果是>10 的非功能性的修改，每10 处修改，j+1 ，个数部分用k 来表示f. 重大变动，i 值增加g. 累计功能变动超过百次，i+1 ， jk=00二、立项立项经管(Project Initialization Management, PIM)的目的是采纳符合公司

8、最大利益的立项建议，通过立项经管使该建议成为正式 的工程(合法化)。杜绝不符合公司最大利益的立项建议被采纳，避免公司人力资源的，资金，时间的浪费。立项经管是决策行为，目标是“做正确的事情" (do right things)。而立项之后的研发经管活动是保证工程团队“正确地做事情" (do thingsright)。“正确的决策” +“正确地执行”才有可能产生好的产品。1、说明：(1) 立项：任何一次研发工作的启动，包括全新的工程和在以往的工程基础上进行升级或改版的工程，都需要进行立项的工作。(2) 工程分级：为了明晰立项的工作，使之有条理，可操作，所以将工程区分为一级工程和

9、二级工程两个不同的等级a、一级工程：包括全新的工程的启动，原有工程的重大改版和升级b、二级工程：在以往工程的基础上进行的非重大的版本修改和完善(3) 工程审批：a、所有一级工程必须由工程负责人提交工程申请计划书，并就工程的相关情况向总经理和技术总监书面陈述或面对面沟通，得到总经理和技术总监的审批签字后方能启动；b、一级工程必须附加需求分析与可行性分析c、二级工程可以由部门经理指定或由工程负责人申请得到部门经理审批签字后即可执行，不必交由总经理和技术总监审批签字；d、对于二级工程，必须将工程计划申请书(纸介质)交由技术文档负责人归档，总经理及技术总监对二级工程的进展情况具有知情权，而工程负责人具

10、有向总经理和技术总监汇报(主动或被动)工程相关情况的义务；e、工程申请计划书一式两份：纸介质文档与电子文档。纸介质文档作为技术档案由专门负责人员备份归档。电子文档按规范要求 存储在公司指定的文档服务器上。(4) 权利，责任与义务a、总经理，技术总监，部门经理对其所具有审批权限的工程申请计划书具有否决的权利；b、工程申请人有权要求否决人说明被否决的理由，而且否决人必须在被否决的工程申请计划书中陈述否决理由；c、具有审批权限的人对于工程的合理性，需求性，可行性等判断负有全权责任； 2、工程申请计划书工程申请计划书/立项建议书工程编号EPF2003NOX-01级别6级工程二级工程类 另I口指定工程讣

11、请工程版本说明V0.10申请人Su制#日期2003-8-18负责人Su组成员Su,Zhang,Yu工程名称基于GPRS的图像传输产品名称G-BIU ( Hardware , GPRS-Based Image Unit ),G-BIUST(Software , G-BIU Support Toolkit)理由陈述资源配置需求成本简要核算（暂时可不添此项）目标近期（年月日年月日）中 长期（年月日年月日）远期（年月日年月日）问题与解决问题（在此陈述进行该工程可能遇到和需要解决的问题，除了技术层面外，还包括设备， 人员配备等方方向向的主要问题）解决方法针对以上的问题，提出解决建议备注说明审批结果口通过

12、口否决审批日期审批人签字审批意见三、需求分析：如果说立项经管是为了解决do right things 和 do things right 的问题， 那么需求分析就是要解决do what things 的问题。 需求产生目标，目标引领方向。好的需求分析不仅要解决“需要做什么”，同时明确“什么不需要做”。最好的，可能产生最大利益的产品是“恰如其分”的产品。所谓“恰如其分”就是：产品的功能恰好满足那些特定的需求，产品功能不多也不少。一般的情况下，归纳总结出“需好做什么”比区分“什么不需要做”要来的容易，但“什么不需要做”的界定往往会影响到成本投入和利益产出的比例。1、说明：（1 ）需求分析工作的安排

13、：进行一项产品的开发工作的一般流程应该是：市场调查需求分析可行性研究立项审核概要设计（总体设计）详细设计单元测试集成测试修改完善工程评估，审核批量生产投放市场技术支持与售后服务。（2） 需求的种类：需求的本质上都来源于市场，但是在具体表现上又有所不同。有的需求直接由用户提出，目标明确；而有些需求则是我们从市场的零星反馈中归纳总结出来的，带有预见性和自主性。（3） 需求分析的主要目的：从市场的反馈或对市场的观察与预见中归纳总结出市场的需求，并用理性的思维对这些需求进行分析和归纳总结，将需求明确，为后面的工作奠定基础。（4） 需求分析的作用：需求分析是市场与技术的转换点。经过需求分析后，工作的重心

14、即由市场转移到技术，明确的需求分析是真正进行研发工作的起点，是进行产品开发一系列后序工作的基础。（5） 需求在进行研发的过程中如果发生变更，需要填写“需求变更说明书”2、模板1需求分析说明书/报告配置编号EPF2003NOX-02作者提交时间2003-8-18目标用户陈述产品的目标用户需求陈述内容级别1 A BDC2解决方法简单描述针对需求的初步解决意向附加说明讨论意见工程评审委员会结论A需求：紧急，重要B需求：重要，不紧急C需求：非A,B类需求需求/功能变更说明书配置编号EPF2003NOX-02-01历史版本V2.00改后版本V2.17产品名称G-BIU(GPRS-Based Image

15、Unit)负责人时间2003-8-19义更项艾更内容义更属性交更原因是否允许1A DD DM是 否23附加说明变更属性中A代表增加，D代表删除，M代表修改工程评审委员会结论工程评审委员会给出是否进行变更的意见，由评委会主席签字生效四、技术可行性分析可行性分析是进行研发工作的重要环节，详细周到的可行性分析与论证为即将启动的工程把握一道至关重要的关口。技术可行性分析要求从技术层面上分析论证工程的可行性，即能否“做得到，做得快，做得好”。可行性分析报告由工程申请责任人归纳总结，撰写，并提交到工程评审委员会审阅。有工程申请/建议书，需求定义和需求报告仍然不能进行实质性的开发，必须要进行可行性分析，可行

16、性分析包括几个部分（1 ）市场分析：a. 分析归纳总结市场的发展趋势，说明产品处于市场的什么发展阶段，粗略估计产品的生命周期b. 本产品和同类产品的价格比对c. 统计产品当前市场总额，竞争对手所占的份额，分析本产品有哪些比较优势，可能占有多少市场份额d. 为产品定位，即确定产品用户群，分析产品消费群体特征，消费方式及影像市场的因素分析（2） 政策分析a. 分析有无相关政策“支持”或“限制”b. 分析有无地方政府或其他机构的“扶持”或“干扰”（3） 竞争分析a. 分析竞争对手的市场状况，产品的优点与缺点b. 预测可能形成的竞争的特点与周期（4） 技术可行性分析（5） 时间和资源可行性分析a. 按

17、正常的运作，从产品开发到投入市场，时间上是否来得及b. 计划中的人员能否及时到位c. 计划中的软硬件需求能否及时到位d. 成本核算能否负担得起（6） 知识产权分析a. 是否已经存在某些专利将妨碍本产品的开发与推广b. 产品能否得到知识产权的保护技术可行性分析报告配置编号EPF2003NOX-03报告撰写人提交时间2003-8-19可行性论述由工程负责人归纳总结，撰写主要从能否“做得到”，“做得快”，“做得好”的角度分析如果能“做得到”，“做得快”，“做得好”，需要给出通过怎样的方法保证如果不能，需要给出理由讨论意见由技术秘书归纳总结撰写人提交报告后到工程评审委员会后，工程评审委员组织人员对报告

18、的“可行性论述”展开讨论，技术秘书归纳总结各方意见，记述在此栏工程评审委员会意见工程评审委员会给出整体意见，供决策人参考五、功能定义1 .说明：功能定义是对 do what things的明确界定，是针对明确的需求来定义产品功能的过程。是产品设计的实质性阶段，此后 的研发工作将围绕功能定义展开，功能定义说明书是参与研发的人员进行工作的基础文档，是产品测试与评审，用户手册的 编制，市场宣传的主要依据。2 .模版功能定义说明书配置编号EPF2003NOX-04负责人提交时间2003-8-19功能项功能描述123附加说明工程评审委员会意见工程评审委员会给出整体意见，供决策人参考六、概要设计1、硬件部

19、分：为了简化操作流程，使文档既能体现设计原理与设计思路，又具有良好的操作性，所以对于硬件部分的概要设计要求只 要求给出原理图，思路描述，主要器件，主要器件的技术参数。概要设计报告（H）每一种参考资料都有自己的编号如:EPF2003NOX-05-H-R1配置编号EPF2003NOX-05-H负责人时间2003-8-19原理图在此添入原理图配置编号，原理图配置编号由技术文档秘书统一编制，编号编制方法待讨论，（改动：EPF2003NOX-05-H-01 ）设计思路描述基本要求：负责人必须对关键的设计思想进行清楚的描述主要器件及技术参数器件名称用途技术参数参考123主要参考资料资料名称来源编R12按照

20、 重要，关键性器件一 主要器件一 辅助性器件的顺序描述主要器件及技术参数栏。2、软件部分：软件部分的概要设计需要提交的报告有：概要设计报告，界面设计报告，数据库设计报告概要设计报告（S）配置编号EPF2003NOX-05-S-01作者提交时间 2003-8-19当前版本V1.20历史版本V1.00 , V1.07, V1.17术语与缩写解释术语解释G-BIAS即 GPS-Based Integrated Application System设计约束* 系统应当遵循的规范或规范* 软硬件环境（包括运行环境与开发环境）的约束* 接口 /协议的约束* 用户界面的约束*软件质量约束，包括正确性，健壮性

21、，可靠性，效率（性能），易用性，清晰性，安全性，可扩展性，兼容性，可移植性。（如果有约束，逐一填写；如果不存在约束，可不填）设计策略* 扩展策略一为了方便扩展，现在采取的措施* 复用策略一说明本系统在当前以及将来的复用策略* 折衷策略一如果存在两个主要目标难以同时优化时如何折衷系统总体结构描述开发环境配置软件硬件网络主要开发工具及语百运仃环境要求软件包括操作系统，第三方软件平台硬件网络数据库参考资料资料配置编号来源12其他说明*如果系统比较复杂，首先将系统分解成若干子系统，对各个子系统绘制逻辑图，说明子系统的功能 *解释如何以及为什么如此分解系统*说明子系统间如何如何协调工作，以实现元系统的功

22、能*如果子系统N仍然需要分解成模块，则(1) 绘制模块逻辑图(2) 陈述分解理由(3) 说明模块间如何协调工作，从而实现子系统的功能*如果系统相对简单，给出用工具Visio绘制的系统逻辑结构图界面设计报告界面设计报告(S)配置编号EPF2003NOX-05-S-02作者时间2003-8-19当前版本V1.20历史版本V1.00 , v1.07, v1.17界面结构及风格绘制界面视图(1) 主界面：需要给出界面元素的作用与操作(2) 子界面：给出子界面的主要作用第二方界囿兀素控件，组件，函数库及其来源名称来源作用12数据库设计报告主要完成数据库的物理设计，即表的结构设计与对表结构的第三范式处理数

23、据库设计报告（S）配置编号EPF2003NOX-05-S-03作者时间2003-8-19当前版本V1.20历史版本V1.00 , v1.07, v1.17表汇总表名功能描述1A2B3CA列名数据类型（经度范围）约束条件备注12补充说明角色与权限可以访问的表与列访问权限角色A角色B七、详细设计1. 硬件部分，硬件部分的详细设计主要体现在下位机软件的代码上，所以详细设计文档的内容集中在对代码的要求上面，代码要求（ 1 ）所有的代码模块必须用文件的方式组织（ 2） 在每一个文件中的开头以注释的方式写如下内容：Copyright （ c） 2003， * 公司，硬件开发部* All rights re

24、served* 文件名称：* 文件标识：文件标识可以统一规定，也可以自己选择* 摘 要：简要描述该文件的内容* 当前版本：* 作 者：输入作者或修改者的名字* 完成日期：* 取代版本：* 原作者：* 完成日期：（ 3） 如果用 C 语言开发a. 必须将 .H 文件与 .C 文件区分开来，在.H 中定义全局变量，结构，联合，自定义群体等，如链表；函数的声明b. 在定义函数体前，以注释方式写如下内容c. 函数的主要作用d. 输入输出参数的含义（ 4） 全局变量的定义要集中，并说明用途（ 5） 主要变量必须在定义之后说明用途6） 所有函数的定义必须给出函数的作用详细设计报告（H）配置编号EPF200

25、3NOX-06-H作者时间2003-8-20当前版本历史版本所有函数定义列表函数定义主要用途外部接口12流程图外部接口 /库接口/库名主要用途来源12通讯协议、内部通讯协议外部协议1填入内部通讯协议文档配置编号如 SMPP, S7 等2其他说明2.软件部分软件部分的详细设计报告内容相对较多，所以设计报告分成若干部分详细设计报告（SP1）配置编号EPF2003NOX-06-S-01作者时间2003-8-20当前版本历史版本系统架构如果能用图表示，必须用图表示，不好用图表示的部分，可以用文字描述主要控件/组件名称作用来源使用12类/结构类名作用12主要的数据结构数据结构描述12关键算法算法作用实现

26、过程12自定义消息消息名称消息IDInvoke条件12其他说明主要控件一栏包括：第三方控件，如 MapX, Flatstyle等，在使用此类控件中必须给出此控件的作用，来源如购买，Share等；必须简要描述此类控件的使用方法，如果控件本身带有资料描述，必须以附录资料的形式给出资料主要的类/结构：程序中所有用到的类，包括自己独立封装的类，从固有的类中集成下来的类，简要陈述类的作用。如果回使用建模工具，则需要用类图来描述出类的结构，继承关系等。主要的数据结构，如结构（记录），链表，栈，队列，图，树及作用关键算法：关键不是复杂，任何一个程序都有关键算法，这里的“关键”的引申含义为：主要，重要。必须给

27、出算法的作用与实现的思路过程描述详细设计报告（SP2）配置编号EPF2003NOX-06-S-02作者时间2003-8-20当前版本历史版本外部接口接口作用参数描述1Map.Distance()23内部接口（方法/ 函数/过程）接口作用宿主参数描述123其他说明所谓接口，不过是函数在特定概念下的称谓。外部接口，程序中所使用的外部函数。例如，在使用MapX控件时，需要使用Map.Distance（）接口函数来计算距离，那么既需要描述出Map.Distance（）的作用与参数描述内部接口：所谓宿主，即指包括此接口的自定义或从固有类继承而来的类，如果是全局函数，宿主栏填写G详细设计报告（SP3）配置

28、编号EPF2003NOX-06-S-03作者时间2003-8-20当前版本历史版本流程图配置编号1EPF2003NOX-06-S-03-CF-012其他说明流程图主要描述程序的关键流程，对关键的判断依据是：如果没有此流程图描述，则对他人理解此程序存有障碍由于流程图一般占用较大空间，所以将其作为详细设计报告（SP3）的附件八、测试测试是产品研发中相当重要的部分，在IT领域越来越受到人们的普遍重视。高水平的测试不仅可以发现表面存在的bug,还可以发现产品内部设计缺陷，消除潜在隐患，提出修改完善建议等。测试，在产品研发中所占用的时间比例大约是整个研发周期的1/41/3。但是，鉴于公司的实际情况，需要

29、制定有效的，符合公司使用要求，实用的测试规程。产品测试规定为两个部分(1) 内部测试：即指开发人员自己进行的测试工作，基本要求是在一般情况下，产品能够正常启动运行即可(2) 产品测试：当内部测试完成以后，测试人员进行产品测试，测试的依据为工程建议书，概要设计报告，功能定义报告，详细设计报告(3) 集成测试：及产品的各个功能部分一起运作下的测试产品测试在目前看来，最主要的是要测试产品的功能，测试功能的主要依据则是功能定义报告。在产品测试前，开发人员必须提供一套测试样本。产品测试报告(HP1)配置编号EPF2003NOX-07-H-01测试人负责人测试时间2003-8-21产品名称版本历史版本测试环境及工具测试项功能是否通过备注1 YesDNo2遗留问题问题描述问题级别原因分析1R口丫 口。2测试结论测试人签字手写问题级别：(1) R：即Red,红色级别，重大问题，关键问题，如执行某项功能时，导致系统死机(死循环)，崩溃等(2) Y:即Yellow,黄色级别，功能性问题，某项功能无法通过(3) 。:即Orange,橙色级别，功能可以实现，但操作十分不便产品测试报告（HP2）配置编号EPF2003NOX-07-H-0