简介传智健康PRD文档1是一份面向健康管理系统产品设计与开发人员的需求说明书适合产品经理、后端开发及医疗信息化学习者参考用于理解健康管理平台从需求定义到功能落地的完整思路。压缩包内共1个docx文件约890KB内容围绕数据结构管理、用户角色与功能详情展开。文档重点梳理了健康评估指标的数据结构包括序号、指标名称、参考值、单位及针对性别等字段的规范化定义并划分了用户、医护人员、管理员三类角色。产品概述部分覆盖会员管理与预约管理两大模块配有产品结构图、流程图与特性描述功能详情延伸至健康评估与健康干预逐项说明操作流程。已有599人学习下载读者可借此掌握健康类产品的需求文档结构、字段设计规范与业务流程拆解方式为同类项目提供可直接借鉴的PRD模板与设计参考。1. 传智健康PRD文档1一份需求文档为什么值得当成工程资产来拆很多团队做健康管理类系统第一版需求文档写得像功能清单登录、建档、预约、报告查询一条条列完就丢给开发。结果做到一半发现字段对不上、状态流转缺分支、权限模型没定义返工成本比重新写一遍还高。传智健康PRD文档1这个标题核心不是“传智健康”四个字而是“PRD文档”作为可执行资产怎么落地。它解决的是从业务语言到工程语言之间的翻译问题适合产品经理、后端开发和测试三方一起看。我见过太多项目把PRD当一次性交付物最后文档和代码各说各话这份东西如果拆得对能直接变成接口定义、状态机和验收用例的源头。2. 把PRD拆成可执行资产从角色建模到状态机落地2.1 先定角色边界再谈功能列表健康管理类系统的第一层复杂度不在功能多少而在角色交叉。常见角色至少有普通用户、健康管理师、医生、运营管理员、系统管理员。PRD文档1里如果只写“用户可以预约”那开发只能猜预约是用户主动发起还是管理师代约取消预约谁有权限这些不写清楚后面接口鉴权就是一团乱麻。我一般会先做一张角色-资源-操作矩阵把每个角色能碰的数据范围钉死。比如普通用户只能看自己的健康档案健康管理师能看所负责用户的档案但不能改医生诊断医生能写诊断但不能改预约排班。这张矩阵不是PRD的附属品它应该直接映射到后端的权限注解和数据库行级过滤。# 角色-资源-操作矩阵的代码化表达伪代码用于生成权限配置 ROLE_PERMISSIONS { user: { health_record: [read_own], appointment: [create_own, cancel_own, read_own], }, health_manager: { health_record: [read_assigned, update_assigned], appointment: [create_for_assigned, cancel_for_assigned], }, doctor: { health_record: [read_assigned, write_diagnosis], appointment: [read_assigned, confirm], }, admin: { health_record: [read_all], appointment: [read_all, force_cancel], user: [create, disable], }, }这段配置的逻辑是权限判断不写在业务代码的if-else里而是抽成独立矩阵接口层只做一次校验。参数说明上read_own和read_assigned的区别在于数据范围过滤条件不同前者拼user_id current_user后者拼manager_id current_user。这样改权限时只动矩阵不动业务逻辑。2.2 状态机是PRD里最容易漏掉的部分预约单的状态流转PRD文档1如果只写“待确认、已确认、已完成、已取消”那测试用例都写不全。实际至少要考虑用户提交后是待确认管理师确认后是已确认医生接诊后是进行中服务结束后是待评价评价完才是已完成。取消又分用户取消、管理师取消、系统超时取消每种取消后的退款和通知逻辑不一样。我习惯在PRD阶段就画状态迁移表而不是等到开发画流程图。表里至少四列当前状态、触发事件、目标状态、附加动作。附加动作包括发通知、写日志、改库存、触发退款。这张表直接决定后端是写一个状态机引擎还是硬编码switch。# 预约状态机的最小实现基于transitions库风格此处用字典模拟 APPOINTMENT_TRANSITIONS { (pending, manager_confirm): (confirmed, [notify_user, lock_schedule]), (pending, user_cancel): (cancelled, [release_schedule]), (pending, timeout): (cancelled, [release_schedule, notify_user]), (confirmed, doctor_start): (in_progress, [notify_user]), (confirmed, user_cancel): (cancelled, [release_schedule, refund_if_paid]), (in_progress, doctor_finish): (pending_review, [notify_user]), (pending_review, user_review): (completed, [write_review]), (pending_review, timeout): (completed, [auto_review]), } def transition(current_state, event): key (current_state, event) if key not in APPOINTMENT_TRANSITIONS: raise ValueError(f非法流转: {current_state} - {event}) next_state, actions APPOINTMENT_TRANSITIONS[key] for action in actions: execute_action(action) # 执行通知、退款等副作用 return next_state逻辑说明所有状态变更必须走transition函数禁止在业务代码里直接改状态字段。参数说明actions列表里的副作用按顺序执行refund_if_paid需要幂等避免重复退款。这样测试只需要覆盖所有合法key和几个非法key用例数量可控。2.3 字段定义要细到数据库列和校验规则PRD里写“用户填写身高体重”开发建表时可能用varchar(50)测试时输入“一百七十”也能存进去。正确做法是在PRD阶段就给出字段清单字段名、类型、长度、是否必填、取值范围、单位、校验时机。比如身高用decimal(5,2)单位厘米范围50到250提交时校验体重用decimal(5,2)单位千克范围10到300。-- 健康档案核心字段定义MySQL CREATE TABLE health_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL COMMENT 关联用户, height_cm DECIMAL(5,2) DEFAULT NULL COMMENT 身高厘米50-250, weight_kg DECIMAL(5,2) DEFAULT NULL COMMENT 体重千克10-300, blood_pressure VARCHAR(20) DEFAULT NULL COMMENT 血压格式如120/80, fasting_glucose DECIMAL(4,1) DEFAULT NULL COMMENT 空腹血糖mmol/L2.0-30.0, record_date DATE NOT NULL COMMENT 记录日期, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, INDEX idx_user_date (user_id, record_date) ) COMMENT健康档案表;参数说明DECIMAL(5,2)表示总共5位小数2位最大999.99够用且不浪费。blood_pressure用字符串是因为要存“120/80”这种格式拆成两个字段也可以但查询时拼接更麻烦。索引idx_user_date支撑按用户和时间范围查询这是最高频的查询模式。3. 从PRD到接口文档字段映射与错误码设计3.1 接口入参出参必须和PRD字段一一对应很多团队PRD和接口文档是两个人写字段名不一致前端对着PRD写后端对着接口文档写联调时才发现height和height_cm对不上。我的做法是PRD里的字段清单直接作为接口文档的字段来源命名规范统一用下划线单位写在字段名后缀。接口文档只增加三样东西HTTP方法、路径、错误码。// POST /api/v1/health-record 请求体示例 { user_id: 1001, height_cm: 175.50, weight_kg: 70.20, blood_pressure: 120/80, fasting_glucose: 5.6, record_date: 2025-01-15 }逻辑说明请求体字段名和数据库列名保持一致减少映射层。user_id在真实场景中应从登录态获取不放在请求体里这里为了演示保留。参数说明record_date用YYYY-MM-DD格式避免时区歧义数值型字段前端传数字后端做范围校验。3.2 错误码要覆盖PRD里的所有异常分支PRD文档1如果只写正常流程错误码就会在开发时临时拍脑袋。我一般要求PRD里每个业务规则后面标注可能的异常比如“身高范围50-250”对应错误码HEIGHT_OUT_OF_RANGE“预约时间不能早于当前时间”对应APPOINTMENT_TIME_INVALID。错误码表单独维护接口返回统一结构。错误码HTTP状态含义触发场景USER_NOT_FOUND404用户不存在user_id无效HEIGHT_OUT_OF_RANGE400身高超出范围小于50或大于250WEIGHT_OUT_OF_RANGE400体重超出范围小于10或大于300APPOINTMENT_TIME_INVALID400预约时间无效早于当前时间APPOINTMENT_STATE_CONFLICT409预约状态冲突重复确认或取消PERMISSION_DENIED403无权限操作角色矩阵校验失败这张表的价值在于测试可以直接按错误码写用例前端可以按错误码做不同提示后端可以按错误码做统一异常处理。PRD里每加一条业务规则就加一行错误码文档和代码同步演进。3.3 用PRD驱动测试用例而不是事后补测试同学最怕PRD写得模糊只能凭经验猜。如果PRD里已经有状态迁移表和字段校验规则测试用例可以自动生成大半。比如状态迁移表里每个合法key对应一个正向用例每个非法组合对应一个异常用例。字段校验规则里每个范围边界对应边界值用例。# 根据状态迁移表生成测试用例骨架 def generate_state_test_cases(transitions): cases [] for (state, event), (next_state, actions) in transitions.items(): cases.append({ name: f{state} {event} - {next_state}, given: {state: state}, when: {event: event}, then: {state: next_state, actions: actions}, }) # 补充非法流转用例 all_states set(s for s, _ in transitions.keys()) all_events set(e for _, e in transitions.keys()) for state in all_states: for event in all_events: if (state, event) not in transitions: cases.append({ name: f非法: {state} {event}, given: {state: state}, when: {event: event}, then: {error: INVALID_TRANSITION}, }) return cases逻辑说明合法流转生成正向用例非法组合生成异常用例覆盖度由状态和事件的笛卡尔积保证。参数说明actions在测试断言里可以只校验是否被调用不校验具体实现保持测试稳定。4. 避坑PRD落地时最容易翻车的五个地方4.1 字段单位不统一前后端各算各的现象前端传身高1.75后端以为是厘米存成1.75厘米展示时变成“1.75cm”。原因PRD只写“身高”没写单位。解决字段名强制带单位后缀如height_cm、weight_kg接口文档和数据库列名一致代码里禁止裸用height。4.2 状态流转绕过状态机直接改数据库现象运营后台为了“方便”直接UPDATE预约状态为已完成跳过了评价和通知。原因没有强制所有状态变更走统一入口。解决数据库层加触发器或应用层加拦截非状态机调用的状态变更直接拒绝并记录操作日志。4.3 权限矩阵只写角色不写数据范围现象健康管理师A能看到健康管理师B负责的用户档案。原因PRD只写“管理师可查看档案”没写“仅限所负责用户”。解决权限矩阵里每个操作必须标注数据范围代码里用行级过滤或中间件统一注入manager_id条件。4.4 错误码在PRD里缺失开发临时编现象前端收到500不知道是参数错还是服务挂了用户看到“系统繁忙”。原因PRD没定义异常分支和错误码。解决PRD每个业务规则后标注错误码接口文档维护错误码表前端按错误码做差异化提示。4.5 测试用例只覆盖正常流程边界全靠猜现象上线后用户输入身高0或者体重999系统照单全收。原因PRD没写边界值测试没依据。解决字段定义里明确范围和边界测试用边界值分析法生成用例代码里做双重校验前端后端。5. 进阶把PRD变成可执行的契约测试5.1 用契约测试锁住PRD和代码的一致性PRD文档1如果只停留在文档层面代码一改文档就过期。我的习惯是把PRD里的字段定义、状态迁移、错误码抽成一份机器可读的契约文件比如YAML或JSON然后写契约测试每次代码变更后跑一遍校验接口实际行为是否和契约一致。# contract/health_record.yaml endpoint: /api/v1/health-record method: POST request: user_id: {type: integer, required: true} height_cm: {type: number, min: 50, max: 250, required: false} weight_kg: {type: number, min: 10, max: 300, required: false} blood_pressure: {type: string, pattern: ^\\d{2,3}/\\d{2,3}$, required: false} fasting_glucose: {type: number, min: 2.0, max: 30.0, required: false} record_date: {type: string, format: date, required: true} responses: 200: {description: 创建成功} 400: {error_codes: [HEIGHT_OUT_OF_RANGE, WEIGHT_OUT_OF_RANGE, FASTING_GLUCOSE_OUT_OF_RANGE]} 403: {error_codes: [PERMISSION_DENIED]}这份契约文件由PRD负责人维护开发提交代码前跑契约测试。参数说明pattern用正则约束血压格式min/max约束数值范围required标记必填。测试框架读取YAML后自动生成请求用例对比实际响应。5.2 契约测试的落地步骤第一步从PRD里抽出所有接口的字段定义和错误码写成YAML文件放在代码仓库的contract/目录下。第二步选一个契约测试框架比如Pact或Spring Cloud Contract或者自己写一个轻量级的校验脚本。第三步在CI流水线里加一个阶段跑契约测试失败则阻断合并。第四步PRD变更时先改YAML再改代码保证文档和代码同步。# 轻量级契约测试脚本示例Python requests python -m pytest tests/contract/ -v --contract-dircontract/ # 输出示例 # tests/contract/test_health_record.py::test_height_out_of_range PASSED # tests/contract/test_health_record.py::test_permission_denied PASSED逻辑说明测试脚本读取YAML里的字段约束构造边界请求断言响应状态码和错误码。参数说明--contract-dir指定契约文件目录方便多模块管理。这样PRD不再是“写完就忘”的文档而是每次构建都会验证的活契约。5.3 一个具体技巧用PRD字段生成数据库迁移脚本PRD里的字段清单可以直接生成建表语句或迁移脚本减少手写SQL的笔误。我一般写一个简单的解析器读取YAML里的字段定义输出CREATE TABLE或ALTER TABLE语句。这样PRD改字段迁移脚本自动更新DBA审核后执行。# 从YAML字段定义生成MySQL建表语句简化版 def generate_create_table(table_name, fields): columns [] for name, spec in fields.items(): col_type { integer: BIGINT, number: DECIMAL(10,2), string: VARCHAR(255), date: DATE, }[spec[type]] nullable NOT NULL if spec.get(required) else DEFAULT NULL comment spec.get(comment, ) columns.append(f {name} {col_type} {nullable} COMMENT {comment}) return fCREATE TABLE {table_name} (\n ,\n.join(columns) \n);逻辑说明类型映射表把PRD里的抽象类型转成数据库类型required决定NOT NULLcomment保留业务含义。参数说明DECIMAL(10,2)是通用数值类型实际项目按范围调整。这个脚本不追求覆盖所有DDL特性只保证字段名、类型、必填和注释不遗漏。我自己的习惯是PRD评审通过后第一件事不是催开发排期而是把字段清单和状态迁移表抽成契约文件跑通契约测试再开工。这样后面无论谁改代码PRD都不会变成黑匣子。希望帮到你。本文还有配套的精品资源点击获取
