简介软件详细设计说明书文档编号SD002V1.0是一份面向软件开发团队的核心设计文档用于将需求分析转化为可操作的模块级设计方案为编码实现提供依据。文档密级为机密并包含完整的修订历史便于项目追溯与维护。资源为单个doc文档2.26MB章节涵盖引言、总体设计、模块设计、代码规范、测试方案与安全策略。其中模块设计重点拆解了门诊导医、门诊就诊等子模块每个子模块均含描述、功能、参数说明、流程逻辑与文献清单可作为医疗类或相似业务系统详细设计的编写模板。全文结构规范从编写目的、背景、术语定义到运营环境、软件架构逐层展开并细化到命名规则、注释规范等代码级要求。已有83人学习查看适合软件设计师、开发工程师、测试人员及项目经理参考帮助提升设计文档完整性与可读性降低开发阶段因设计不明确导致的返工风险。1. 门诊系统的详细设计说明书为什么是“开发中途接手”时的救命稻草接手一个没写过详细设计的旧项目和拿着一份模块级设计说明书进场完全是两种体验。这份软件详细设计说明书文档编号SD002、版本V1.0把门诊导医、门诊就诊、门诊收费、药品发药、电子病历模板管理等18个模块拆到了参数说明级别。它不只告诉你系统有哪些页面还告诉你每个功能点有哪些参数、流程怎么走、权限怎么控。适合正在做门诊类信息系统开发、或准备写详细设计文档的人拿来当参考模板也适合测试工程师按模块设计用例。它的价值在于把需求和代码之间的鸿沟补上了。大部分开发翻车不是编码能力问题是设计意图在传递中丢了。而这份文档恰好把“为什么这么做、参数怎么配、流程怎么走”压实了后面每一章我都会按读文档、拆模块、落代码的顺序拆解。说句实话设计文档这种东西写得粗了会被开发嫌弃写得细了又容易没人维护。这份SD002用的是最稳妥的模板每个模块都按“描述、功能、参数说明、流程逻辑、文献清单”五段式展开。只要照着这个结构读半小时内就能判断出整个系统的设计成熟度。2. 从引言到总体设计读SD002的三层骨架与版本追踪机制2.1 引言四件套编写目的、背景、定义、参考资料怎么读新接手项目的人第一反应往往是跳过引言直接看模块这是最赔本的习惯。SD002把引言拆成编写目的、背景、定义、参考资料每一条都有实际的阅读意义。编写目的决定文档的“用户画像”。SD002的编写目的明确指向编码实现阶段也就是说这份文档是开发人员的施工依据。如果你拿它去跟业务人员对需求会发现颗粒度对不上那不是文档的问题是读者拿错了视角。我一般会先在这一页画一条边界这份文档只回答了“怎么做”不回答“为什么有这个业务”。背景段解决“系统从哪里来”的问题。比如门诊导医模块如果背景只写“帮助患者分流”设计时就不会考虑到号源分配、过号重排、医生停诊改约这些边界背景写得越细开发时踩的坑越少。我习惯在背景部分用荧光笔标出“业务目标”和“约束条件”两类句子前者决定功能要不要做后者决定功能怎么做。定义段是一次正式的“术语对齐”。在门诊系统里“退费”和“退货”容易混。按SD002的模块结构看退费走的是收费处的收入冲正逻辑退货走的是药房库存的供应商退货逻辑两条链路完全不同。文档里如果没有这段定义开发阶段就会冒出“退费退药到底谁先谁后”这种争执。参考资料段则列出编写依据。这里有个实用技巧需求冲突时先去查参考资料里的规范和高层文档以更上游的文档为准而不是在模块内部打补丁。很多项目后期改需求改出数据不一致根源就是忽略了参考资料的优先级。2.2 总体设计三元素运营环境、功能描述、软件结构总体设计章节回答三个问题系统跑在哪、系统干什么、系统长什么样。SD002将这三者分别定义为运营环境、软件功能描述、软件结构这个顺序很合理因为运营环境的约束会直接影响后面架构选型。运营环境描述硬件、操作系统、数据库和网络条件。门诊系统的特点是终端分散挂号窗口、收费窗口、药房、诊室分布在多层楼和不同网段。如果设计时没考虑这些终端与中心数据库之间的连接稳定性后续就会出现窗口卡顿、小票打印超时、药房确认滞后一类的线上事故。所以我在看运营环境时会特地把网络拓扑和数据库连接方式圈出来作为性能设计的输入。软件功能描述部分SD002列出了18个功能模块从门诊导医到卫生材料目录维护。这些模块并不处在同一层导医、就诊、收费、发药是流程主链药品目录维护、收费项目子项目管理是基础数据链门诊量记录、销售汇总是统计链。读懂这条分层关系后面做接口设计时才知道哪个模块是上游、哪个是下游。软件结构描述系统架构和模块划分。常见做法是三层结构加模块间通信约定。比如门诊就诊模块它在功能上是收费和发药的上游但在数据上要读取电子病历模板和收费项目。因此在软件结构这一节里要重点看模块依赖图——如果依赖画成环就要警惕循环调用。2.3 版本记录和文档编号可追溯性是设计文档的自我防御SD002的文档头值得单独说一下。文档编号SD002、版本号V1.0、密级机密加上一张修订记录表。这些字段看起来是行政要求实际是工程上的“后悔药”。修订记录逐行说明了日期、版本号、修订说明、修订人、审核人、批准人。本质上这是一张变更日志表。2023.10.15创建2023.11.12修订说明里写着“增长门诊就诊模块”——按上下文应该是“新增”的笔误但这也暴露了一个细节门诊就诊模块是后补进V1.0版本的也就是说设计边界在开发过程中发生过一次重要扩展。这个现象在真实项目里很常见。所以拿到任何设计文档我做的第一件事是读修订历史。如果发现某个模块是后期新增的就要重点检查它与旧模块的衔接处比如门诊就诊与门诊收费之间是否存在重复计价的边界。这里给个字段对照表方便你把文档头的管理信息与工程实践对应起来文档字段工程含义落地用途文档编号系统的唯一索引代码注释里引用设计决策版本号设计基线版本决定当前代码对应哪个基线密级信息开放范围控制文档是否能进外部协作平台修订说明变更摘要快速定位本次变更覆盖的模块审核人/批准人责任链出问题时追溯评审环节密级“机密”不只是一个标签。在真实项目中它决定了代码仓库、文档库、外包团队的访问范围。我见过有人把标着机密的详细设计直接传进公共网盘这是管理事故不是小事。拿到文档第一件事就是确认它在内部系统的权限边界。3. 核心模块拆解门诊导医与门诊就诊的参数与流程逻辑3.1 门诊导医模块五段式结构里的字段级信息门诊导医是患者进入门诊系统后接触的第一个模块它的设计质量直接决定了后续就诊流程能不能跑顺。SD002对每个模块统一用“描述-功能-参数说明-流程逻辑-文献清单”五段式展示这里描述交代目的功能列出功能点参数说明则落到具体的字段。在实际项目里“描述功能”两段决定需求“参数说明”决定接口文档“流程逻辑”决定状态机。开发拿到门诊导医模块后应该先画一条纵向线索从挂号取号、排队叫号、过号重排到医生接诊。每个环节在参数层都会对应若干个字段。以叫号和过号处理为例常见的参数设计如下参数名类型取值范围默认值设计意图排队队列IDString科室编码日期无区分不同科室当日队列叫号未响应时长Integer30~120分钟60超时触发过号逻辑过号重排次数Integer0~52超过后转人工分诊过号时间窗口Integer0~240分钟120窗口内允许重排窗口外转缺诊这些参数不是我从原文抄出来的而是根据门诊导医的常规业务补全的“合格设计”。原文的参数说明在文档里是逐条列出的拿到手上之后我的建议是先补一列“取值范围”因为原文很可能只写了类型和业务含义没写边界。3.2 门诊就诊模块一次“后补模块”的边界设计样本门诊就诊模块最值得看的不是功能列表而是它的入场方式。修订记录显示这个模块是在V1.0期间新增的说明初始设计并未把就诊过程纳入系统边界。后补模块首先要解决的和旧模块的关系问题。从SD002的模块清单看门诊就诊处在导医之后、收费和发药之前。它必须复用导医产生的排队信息调用电子病历模板管理模块生成病历再向收费模块传递计价信息。我在拆这种后续新增模块时会做三件事一是找出上下游依赖二是列出状态流转三是抽公共参数。状态流转可以提炼为待就诊→就诊中→已完成加上两个异常状态过号缺席和提前离开。这里要特别注意状态值的唯一性否则收费模块会收到重复的就诊状态导致重复计价或漏计价。所谓的“状态值唯一性”就是同一语义只允许一个枚举值。比如“已完成”和“结束就诊”不能同时存在否则两个开发各写各的联调时就要互相迁就。3.3 从流程逻辑到代码一个过号重排的可运行示例把流程逻辑翻译成代码是详细设计说明书真正发挥价值的地方。下面拿“过号重排”写一段可以直接改用的伪代码思路来自门诊导医模块的流程逻辑# consultation_queue.py # 过号处理逻辑超时未响应 - 状态置为 OVERDUE - 按规则重排 def handle_no_show(patient_id, queue_id, config): patient queue_service.get_patient(patient_id) if patient.status ! CALLED: return # 第一次过号状态从“呼叫中”改为“过号” patient.status OVERDUE patient.overdue_count 1 # 判断是否还有资格重排 now datetime.now() within_window now patient.valid_until retry_left patient.overdue_count config.max_retry_count if within_window and retry_left: # 重排到队尾并通知患者 queue_service.enqueue(queue_id, patient.id, positiontail) front_count queue_service.pending_count(queue_id) notify(patient, f您已重新排队前方还有 {front_count} 人) else: # 超过重试次数或过号时间窗口转为缺诊 patient.status MISSED queue_service.mark_missed(patient.id) # config 参数示例 # max_retry_count 2 # valid_until 由“过号时间窗口”参数在首次叫号时算出这段代码的核心是把“过号重排”这种口语化的业务规则变成三个可验证的条件状态必须是CALLED、当前时间必须还在窗口内、重试次数未超限。参数说明一旦细化到这个程度开发基本不会跑偏。参数方面要注意两个点valid_until是首次叫号时根据“过号时间窗口”计算出的绝对时间不要每次在handle_no_show里重新计算overdue_count要写入持久化不能只放内存否则程序重启后患者能无限次重排。这两个细节都是我在真实项目里踩过的。再从代码反推文档你会发现SD002的“流程逻辑”这一节本质上就是在描述状态机。文档里写“叫号后超时未响应进入过号状态”对应代码里就是CALLED到OVERDUE的迁移。读文档时状态迁移找全写代码时分支就能一次写对。4. 药品与收费的闭环设计从进销台账到预警阈值4.1 药品进销台账账实相符的基本功门诊系统里最容易出问题的不是收费而是药品库存。收费减库存、发药减库存、退货加库存、退药加库存多个模块同时操作同一个药品编码如果没有一本统一的进销台账账面很快就会对不上。SD002里专门设置了药品进销台账模块作用就是把所有库存变化都记成流水。实际项目里台账表通常长这样CREATE TABLE drug_stock_ledger ( id BIGINT PRIMARY KEY AUTO_INCREMENT, drug_code VARCHAR(20) NOT NULL COMMENT 药品编码, batch_no VARCHAR(30) NOT NULL COMMENT 批次号, in_qty INT DEFAULT 0 COMMENT 入库数量, out_qty INT DEFAULT 0 COMMENT 出库数量, return_qty INT DEFAULT 0 COMMENT 退货数量, stock_balance INT NOT NULL COMMENT 结存数量, biz_type VARCHAR(10) NOT NULL COMMENT 业务类型: IN/OUT/RETURN/RETURN_DRUG, occurrence_time DATETIME NOT NULL COMMENT 发生时间, created_by VARCHAR(30) NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_drug_batch (drug_code, batch_no) ) ENGINEInnoDB COMMENT 药品进销台账表;这里的核心设计是“不更新、只追加”。每一条入库、发药、退货都生成一行流水stock_balance在写入时由程序计算而不是在旧记录上改动。这样做的好处是任何时候都能回放台账排查数据对不上的问题。参数说明里要注意三个字段。biz_type建议用业务类型而不是操作类型比如退药和退货虽然都是库存增加但前者是患者侧后者是供应商侧必须区分。batch_no一定要保留药品效期管理依赖批次。occurrence_time建议用数据库时间或应用服务器时间并统一时区避免各窗口客户端时间不一致。4.2 收费与退费发药与退药反向流程要有对称性有了台账再来看收费和退费。门诊收费模块处理正常收费门诊退费模块处理收入冲正。SD002把门诊退费单独列成模块而不是收费模块下的一个按钮这在设计上是有讲究的退费涉及权限、审批和状态回写逻辑复杂度和正向收费完全不在一个量级。编写退费逻辑时我一般会先把三个校验条件写死# refund_service.py def check_refund(charge_no, refund_items): charge get_charge_record(charge_no) # 条件1退费总额不得超过已收总额 if charge.amount sum(item.amount for item in refund_items): raise BizError(退费金额超过原收费金额请核对) # 条件2已发药项目必须先完成退药才能退款 for item in refund_items: if get_dispense_status(charge_no, item.drug_code) DISPENSED: raise BizError(f药品[{item.drug_code}]已发药请先执行退药流程) # 条件3跨日退费需要走审批当日退费直接冲正 if not is_same_day(charge.paid_time): return submit_approval(charge, refund_items) return refund(charge, refund_items)三个条件对应的是SD002门诊退费模块的流程逻辑里最容易被忽略的三个分支。实际编码时的教训是先做退药再做退费如果先退了钱再走退药药房会把退回的药品重新放入货架但账上已经无法冲平。从设计文档的角度看正向和反向流程应当成对出现。SD002把门诊收费和门诊退费、药品发药和药品退药、药品入库和药品退货分别并列为模块就是为了让开发者可以对照着看。读文档时我建议把每一对正反向流程的字段列成对照表确保同名字段语义一致。4.3 药品预警与库存量查询阈值参数的设计药品预警模块是台账的下游它的功能是发现库存异常而不是修正异常。SD002里设置了药品库存量查询和药品预警两个模块前者解决“现在有多少”后者解决“快没了要补货”。预警的核心是阈值参数阈值设置得好不好直接决定这个模块是真的在管库存还是一直在误报。我见过两种极端阈值设得太低每天半夜跑批都跑出几千条预警没人看预警模块变成摆设阈值设得太高药房断货了系统还没响。合理做法是把阈值拆成两个级别存量预警和断货预警。参数说明建议初始值预警阈值低于该数量时提醒补货按近7天日均消耗量×3天计算预警检查周期跑批频率DAILY断货阈值低于该数量时告警并停售0预警通知对象接收人/角色药房管理员这个表里的具体数值只是示例真实取值要结合门诊量和药房库存周转周期。但有一个设计要点是通用的预警模块只做“发现和通知”不要直接改库存所有状态变化仍要落到台账模块。否则预警逻辑和台账逻辑耦合在一起排查问题时非常痛苦。5. 详细设计说明书落地避坑三个真实翻车点与补救方案5.1 坑一参数说明里有类型没有取值范围现象代码写完后测试提交一条负库存记录库存出现“-1盒”的数据查询模块也跟着报错。原因详细设计文档的参数说明只写了字段类型是Integer没有写取值范围。开发默认负数合法数据库也没加约束。解决编码开始前把每个模块的参数说明扩成一张“值域检查表”补全最小值、最大值、默认值、空值策略四列。像库存数量这种字段直接约束为非负整数并在接口层做参数校验。测试用例也按边界值生成比如0、1、最大值、null。这一步非常值得做因为它能把设计阶段遗留的模糊地带一次性清干净。5.2 坑二流程逻辑只画了正向路径异常分支全靠猜现象文档里流程图看起来顺畅排队叫号、就诊、收费、发药一环扣一环。结果联调时过号重试、退药未完成、手工修改库存这些分支各有一套实现。原因详细设计的流程逻辑只覆盖正常路径没有展开异常分支。开发各自脑补模块间对异常的处理方式不一致。解决正反向流程配对检查。每个模块的正向流程列出后强制补三种异常路径超时、取消、中断。拿门诊就诊来说不但要有“待就诊→就诊中→已完成”还要有“叫号未响应→过号重排→转缺诊”这条异常路径。把这些状态做成枚举表状态机里不允许出现未定义的取值。这个习惯能让异常分支从“靠猜”变成“有据可查”。5.3 坑三把模块参数说明当成数据库建表脚本直接抄现象开发照着参数说明建库结果一个“患者姓名”字段在导医表、就诊表、发药表里各建一遍患者转科时数据改不齐还出现同一患者多条记录互相矛盾。原因参数说明描述的是功能上的输入输出字段不是最终数据模型。不同功能里出现“患者ID”是同一实体的外键引用不应当复制成三份物理字段。解决做一次“参数→数据表”映射把18个模块的参数项按实体归并。患者、就诊、处方、收费单、药品是核心实体先建实体表再建关系表和流水表。映射表建议按“功能名-参数名-实体名”三列维护评审时直接就这张表过。这样建出来的库冗余少改起来也快。6. 把SD002转成开发任务清单颗粒度、验收条件与追溯习惯详细设计说明书本身不是交付物真正交付的是代码。所以我拿到SD002这种资源后的第一件事是把每个模块改写成一组可验收的开发任务。一个模块不是一个任务一个模块拆出来的功能点和数据表组合才是任务。比如门诊退费模块可以拆成退费金额校验、退费审批流数据、退费状态回写三个任务。我给每个任务定三条验收条件是否能在接口层拦截非法参数、状态流转是否覆盖异常路径、台账是否记录完整流水。对应到SD002的参数说明和流程逻辑只要这两段写清楚了这三条验收条件就都能落地。拿门诊退费举一个任务示例开发任务依赖表验收条件退费金额校验charge_record, refund_record退费总额原收费总额时返回错误码退费审批流refund_approval, operator_role跨日退费必须生成审批单退费状态回写charge_record.status退费成功后原收费单状态变为REFUNDED这样把文档拆成任务清单后每个任务都不超过两天工作量进度好控测试也好写。更重要的是每一个任务都能回溯到SD002的某个模块和某段流程逻辑出了问题时能沿链条找到责任人。从那以后我每次拆详细设计说明书都会强制走一遍三道工序先读修订记录判断边界再按“参数→数据表”做一次映射最后把模块拆成可验收任务。这三步做完编码阶段很少因为设计理解不一致而返工。希望这份SD002的拆解方式也能帮到你——下次拿到一份详细设计说明书别急着抄先把它拆薄。本文还有配套的精品资源点击获取
