mi-assessment/.kiro/specs/report-web-pages/requirements.md

需求文档：测评报告网页版（PDF报告生成用）

简介

测评报告网页版是学业邑规划测评系统的服务端渲染模块，由后端（.NET 10 Web API）直接渲染 HTML 输出，用于将测评结果以网页形式渲染为可截图的报告页面。该模块不需要用户登录，通过 URL 参数传入测评记录 ID，服务端直接查询数据库获取测评数据并嵌入 HTML 页面。每个报告板块是一个独立的网页页面，最终由后端截图服务将这些页面截图并与静态图片按配置顺序拼装为 PDF 报告文件。

PDF 报告由"静态图片页"和"网页截图页"两种类型的页面组成，通过报告页面配置表（report_page_configs）定义每一页的类型和顺序。所有页面（包括静态图片和网页截图）统一尺寸为 1309×926px（96dpi），确保拼装 PDF 时页面大小一致。

报告包含 11 个网页板块，对应 8 个报告维度（CategoryType 1-8）的测评结果数据。报告生成时，系统从模板表（report_conclusions）复制结论数据到记录级别的结论表（assessment_record_conclusions），管理员可针对单条测评记录手动调整结论和评分数据。网页渲染时，数据来源于记录级别的 assessment_record_conclusions、assessment_results、report_categories、assessment_records 等数据库表。

术语表

• Report_Renderer（报告渲染模块）：.NET 10 Web API 中的服务端渲染模块，使用 Razor Pages 或直接输出 HTML，用于渲染测评报告的各个页面
• Report_Page（报告页面）：报告中的一个独立网页，对应报告的一个板块，由服务端渲染输出，具有固定的页面尺寸 1309×926px
• Report_Data_Service（报告数据服务）：后端内部服务方法，根据测评记录 ID 从数据库查询报告所需的全部数据，供服务端渲染时调用
• Report_Page_Config（报告页面配置）：report_page_configs 表中的记录，定义 PDF 报告中每一页的类型（静态图片或网页截图）、顺序和关联资源
• Assessment_Record（测评记录）：assessment_records 表中的记录，包含测评人姓名、性别、年龄、学业阶段等基本信息
• Assessment_Result（测评结果）：assessment_results 表中的记录，包含各分类的得分、满分、百分比、排名和星级（1-5），支持管理员手动调整
• Assessment_Record_Conclusion（测评记录结论）：assessment_record_conclusions 表中的记录，存储某条测评记录的结论数据，由报告生成时从 Report_Conclusion 模板复制而来，支持管理员针对单条记录手动调整
• Report_Category（报告分类）：report_categories 表中的记录，CategoryType 字段定义报告维度：1八大智能 2个人特质 3细分能力 4先天学习 5学习能力 6大脑类型 7性格类型 8未来能力
• Report_Conclusion（报告结论模板）：report_conclusions 表中的记录，包含各分类在不同结论类型（1最强/2较强/3较弱/4最弱）下的模板文本内容，作为生成记录级别结论的数据源
• Star_Level（星级）：1-5 星评定，5星为最强，1星为最弱
• Conclusion_Type（结论类型）：1最强 2较强 3较弱 4最弱，由星级映射：5星→1，4星→2，3星→2，2星→3，1星→4
• Page_Container（页面容器）：固定尺寸 1309×926px 的 HTML 容器，与静态图片尺寸一致，用于截图生成图片
• Static_Image_Page（静态图片页）：PDF 报告中直接插入的静态图片页面，如封面图、分隔图等，尺寸为 1309×926px
• Web_Screenshot_Page（网页截图页）：PDF 报告中由服务端渲染的网页截图生成的页面，截图尺寸为 1309×926px
• Radar_Chart（雷达图）：展示八大智能得分百分比的雷达图表
• Bar_Chart（柱状图）：展示八大智能排名的柱状图表
• Screenshot_Service（截图服务）：后端服务，负责访问报告网页并截图生成图片（不在本需求范围内，由其他 spec 负责）
• Conclusion_Data_Chain（结论数据链路）：report_conclusions（模板）→ 生成报告时复制到 assessment_record_conclusions → 管理员可手动调整 → 网页渲染读取 assessment_record_conclusions → 截图生成 PDF

需求

需求 1：测评记录结论独立维护

用户故事： 作为系统管理员，我希望每条测评记录拥有独立的结论数据副本，以便针对单条记录手动调整星级、评语和得分数据，而不影响模板数据和其他测评记录。

验收标准

1. THE Report_Data_Service SHALL 在报告生成时，从 Report_Conclusion（模板结论表）复制结论数据到 Assessment_Record_Conclusion（测评记录结论表），绑定到具体的 Assessment_Record 的 Id
2. THE Assessment_Record_Conclusion SHALL 存储在 Business 库的 assessment_record_conclusions 表中，包含以下字段：Id（主键）、RecordId（测评记录ID）、CategoryId（分类ID）、ConclusionType（结论类型：1最强 2较强 3较弱 4最弱）、Title（结论标题）、Content（结论内容，富文本）、CreateTime、UpdateTime、IsDeleted
3. WHEN 报告生成流程执行时，THE Report_Data_Service SHALL 根据 Assessment_Result 中各分类的 StarLevel 确定 ConclusionType，从 Report_Conclusion 模板表中查询对应的结论记录，复制 Title 和 Content 字段到 Assessment_Record_Conclusion 表中，并关联当前 Assessment_Record 的 Id
4. THE Assessment_Result SHALL 支持管理员在后台针对单条测评记录手动调整以下字段：Score（得分）、Percentage（百分比）、Rank（排名）、StarLevel（星级），调整仅影响当前测评记录，不影响其他测评记录的数据
5. THE Assessment_Record_Conclusion SHALL 支持管理员在后台针对单条测评记录手动调整以下字段：StarLevel（星级，需新增此字段用于记录级别的星级覆盖）、Title（结论标题）、Content（结论文本），调整仅影响当前测评记录，不影响 Report_Conclusion 模板数据和其他测评记录
6. WHEN 管理员点击"重新生成报告"时，THE Report_Data_Service SHALL 删除该测评记录关联的所有 Assessment_Record_Conclusion 记录，重新从 Report_Conclusion 模板表复制生成新的结论数据，覆盖之前的手动调整
7. WHEN 管理员点击"重新生成报告"时，THE Report_Data_Service SHALL 重新计算该测评记录的 Assessment_Result 数据（得分、百分比、排名、星级），覆盖之前的手动调整
8. THE Report_Renderer SHALL 在渲染报告页面时，从 Assessment_Record_Conclusion 表读取结论数据，从 Assessment_Result 表读取得分和星级数据，不直接读取 Report_Conclusion 模板表
9. IF 指定的 Assessment_Record 对应的 Assessment_Record_Conclusion 记录不存在，THEN THE Report_Data_Service SHALL 自动触发结论数据生成流程，从 Report_Conclusion 模板表复制生成结论数据

需求 2：服务端渲染架构与页面路由

用户故事： 作为后端截图服务，我希望通过 URL 访问各个报告页面，页面由服务端直接渲染输出 HTML，以便对每个页面进行截图生成图片。

验收标准

1. THE Report_Renderer SHALL 作为 .NET 10 Web API 项目中的服务端渲染模块实现，使用 Razor Pages 或直接输出 HTML，不依赖独立的前端项目
2. THE Report_Renderer SHALL 在服务端直接查询数据库获取测评数据，将数据嵌入 HTML 页面输出，不需要前端发起 API 请求获取数据
3. THE Report_Renderer SHALL 通过 URL 查询参数 recordId 接收测评记录 ID，所有报告页面共用同一个 recordId 参数
4. THE Report_Renderer SHALL 为每个报告板块提供独立的 URL 路由，路由格式为 /report/{page-name}?recordId={id}
5. THE Report_Renderer SHALL 提供以下页面路由：/report/cover（封面页）、/report/intelligence-overview（八大智能分析）、/report/strongest-intelligence（最强智能详情）、/report/weakest-intelligence（较弱智能详情）、/report/personality-traits（个人特质分析）、/report/sub-abilities（40项细分能力分析）、/report/learning-types（先天学习类型分析）、/report/learning-abilities（学习关键能力分析）、/report/brain-types（科学大脑类型分析）、/report/character-types（性格类型分析）、/report/future-abilities（未来关键发展能力分析）
6. IF URL 中缺少 recordId 参数或 recordId 为空，THEN THE Report_Renderer SHALL 返回包含"缺少测评记录参数"错误提示的 HTML 页面

需求 3：报告数据服务（内部服务方法）

用户故事： 作为报告渲染模块，我希望通过内部服务方法获取报告所需的全部数据，以便在服务端渲染时直接将数据嵌入 HTML 页面。

验收标准

1. THE Report_Data_Service SHALL 提供内部服务方法 GetReportDataAsync(long recordId)，从数据库查询指定测评记录的完整报告数据，供服务端渲染时调用
2. WHEN 测评记录状态为 4（已完成），THE Report_Data_Service SHALL 返回包含以下数据的对象：测评人基本信息（姓名、性别、年龄、学业阶段、省市区）、测评完成时间、所有分类的测评结果（从 Assessment_Result 读取得分、满分、百分比、排名、星级）、所有分类的报告结论文本（从 Assessment_Record_Conclusion 读取）、报告分类的层级结构信息
3. IF 指定的 recordId 对应的 Assessment_Record 不存在或已被软删除，THEN THE Report_Data_Service SHALL 抛出业务异常，包含"测评记录不存在"提示信息
4. IF 指定的 recordId 对应的 Assessment_Record 状态不为 4（已完成），THEN THE Report_Data_Service SHALL 抛出业务异常，包含"报告尚未生成完成"提示信息
5. THE Report_Data_Service SHALL 作为后端内部服务注册到依赖注入容器，不对外暴露为 HTTP API 接口

需求 4：报告页面配置表

用户故事： 作为系统管理员，我希望通过数据库配置表定义 PDF 报告中每一页的类型和顺序，以便灵活调整报告的页面组成和排列顺序。

验收标准

1. THE Report_Page_Config SHALL 存储在 Business 库的 report_page_configs 表中，包含以下字段：Id（主键）、PageType（页面类型：1静态图片 2网页截图）、PageName（页面标识名称）、Title（页面显示标题）、SortOrder（排序序号，从 1 开始）、ImageUrl（静态图片路径，PageType=1 时必填）、RouteUrl（网页路由路径，PageType=2 时必填）、Status（状态：0禁用 1启用）、CreateTime、UpdateTime
2. WHEN PageType 为 1（静态图片），THE Report_Page_Config SHALL 记录静态图片的存储路径，生成 PDF 时直接将该图片插入对应位置
3. WHEN PageType 为 2（网页截图），THE Report_Page_Config SHALL 记录网页的路由路径（如 /report/intelligence-overview），生成 PDF 时先访问该路由截图再插入对应位置
4. THE Screenshot_Service SHALL 按 Report_Page_Config 表中 SortOrder 升序排列的顺序，依次处理每一页并拼装为 PDF 文件
5. THE Report_Page_Config SHALL 支持通过 Status 字段控制某一页是否包含在 PDF 报告中，Status=0 的页面在生成 PDF 时跳过
6. IF Report_Page_Config 表中不存在任何启用状态的配置记录，THEN THE Screenshot_Service SHALL 返回错误提示"报告页面配置为空，无法生成 PDF"

需求 5：页面固定尺寸与截图适配

用户故事： 作为后端截图服务，我希望报告页面具有固定的尺寸，与静态图片保持一致，以便截图生成的图片和静态图片拼装 PDF 时大小统一。

验收标准

1. THE Page_Container SHALL 设置固定尺寸为 1309×926px（宽 1309px，高 926px），与静态图片尺寸保持一致
2. THE Report_Page SHALL 使用 px 作为样式单位，确保在浏览器中渲染尺寸精确为 1309×926px
3. THE Report_Page SHALL 设置白色背景，确保截图无透明区域
4. THE Report_Page SHALL 在服务端渲染完成并输出到浏览器后，当图表等异步内容渲染完毕时，在 document.body 上添加 data-render-complete="true" 属性，以便截图服务判断页面是否渲染完成
5. THE Static_Image_Page SHALL 统一使用 1309×926px（96dpi）尺寸，确保与网页截图页面大小一致

需求 6：封面页

用户故事： 作为测评报告的阅读者，我希望看到一个包含报告标题和测评人信息的封面页，以便了解报告的基本信息。

验收标准

1. THE Report_Page（封面页）SHALL 显示报告标题"多元智能测评报告"
2. THE Report_Page（封面页）SHALL 显示八大智能的拼图图形，每个智能对应一个拼图块，使用不同颜色区分
3. THE Report_Page（封面页）SHALL 显示测评人信息：姓名、性别、年龄、学业阶段、测评日期
4. THE Report_Page（封面页）SHALL 由服务端直接查询 Assessment_Record 表获取测评人信息，测评日期使用 CompleteTime 字段，将数据嵌入 HTML 输出

需求 7：八大智能分析页

用户故事： 作为测评报告的阅读者，我希望通过雷达图和柱状图直观了解八大智能的得分分布，以便快速把握整体智能结构。

验收标准

1. THE Report_Page（八大智能分析页）SHALL 显示包含八大智能百分比得分的 Radar_Chart，八个维度分别为：语言智能、逻辑数学智能、音乐智能、自然探索智能、人际社交智能、自我察觉智能、视觉空间智能、身体动觉智能
2. THE Report_Page（八大智能分析页）SHALL 显示按排名从高到低排列的 Bar_Chart，每个柱状条显示智能名称、百分比得分和星级
3. THE Report_Page（八大智能分析页）SHALL 使用 ECharts 或 Chart.js 等图表库渲染 Radar_Chart 和 Bar_Chart，图表库通过 CDN 引入或内联到服务端渲染的 HTML 中
4. THE Report_Page（八大智能分析页）SHALL 由服务端直接查询 CategoryType=1 的 Assessment_Result 和 Report_Category 数据，将八大智能的得分、百分比、排名和星级嵌入 HTML 输出
5. THE Report_Page（八大智能分析页）SHALL 使用不同颜色区分各智能维度，颜色方案在页面间保持一致

需求 8：最强智能详情页

用户故事： 作为测评报告的阅读者，我希望详细了解自己最强智能的分析内容，以便明确优势方向和发展建议。

验收标准

1. THE Report_Page（最强智能详情页）SHALL 显示星级为 5 星的智能分类名称和五星评级图标
2. THE Report_Page（最强智能详情页）SHALL 显示该智能的结论文本内容，包含：方向、描述、兴趣爱好、天赋培养、学习技巧、擅长职业、综合评估
3. THE Report_Page（最强智能详情页）SHALL 显示推荐学科信息，区分"中小学生优势学科"和"高考志愿/大学生及以上学科专业"
4. THE Report_Page（最强智能详情页）SHALL 由服务端直接查询 CategoryType=1 且 StarLevel=5 的 Assessment_Result，并从 Assessment_Record_Conclusion 中读取对应的结论数据（ConclusionType=1），将结论文本嵌入 HTML 输出
5. WHEN 存在多个 5 星智能时，THE Report_Page（最强智能详情页）SHALL 按排名顺序依次展示所有 5 星智能的详情内容

需求 9：较弱智能详情页

用户故事： 作为测评报告的阅读者，我希望了解自己较弱智能的分析和改进建议，以便有针对性地提升。

验收标准

1. THE Report_Page（较弱智能详情页）SHALL 显示星级为 1 星的智能分类名称和一星评级图标
2. THE Report_Page（较弱智能详情页）SHALL 显示该智能的较弱表现描述和改进建议文本
3. THE Report_Page（较弱智能详情页）SHALL 显示职业发展提醒或学习技巧提升建议
4. THE Report_Page（较弱智能详情页）SHALL 由服务端直接查询 CategoryType=1 且 StarLevel=1 的 Assessment_Result，并从 Assessment_Record_Conclusion 中读取对应的结论数据（ConclusionType=4），将结论文本嵌入 HTML 输出
5. WHEN 存在多个 1 星智能时，THE Report_Page（较弱智能详情页）SHALL 按排名顺序依次展示所有 1 星智能的详情内容

需求 10：个人特质分析页

用户故事： 作为测评报告的阅读者，我希望了解自己的个人学习特质类型，以便选择适合的学习方法。

验收标准

1. THE Report_Page（个人特质分析页）SHALL 显示 CategoryType=2（个人特质）维度中星级最高的分类作为主要特质类型
2. THE Report_Page（个人特质分析页）SHALL 显示该特质的描述、典型特征表现、学习建议和职业培养方向
3. THE Report_Page（个人特质分析页）SHALL 显示所有个人特质分类的星级评分列表，以便展示各特质的相对强弱
4. THE Report_Page（个人特质分析页）SHALL 由服务端直接查询 CategoryType=2 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出

需求 11：40项细分能力分析页

用户故事： 作为测评报告的阅读者，我希望了解八大智能下 40 项细分能力的详细分析，以便精准定位具体的能力优劣势。

验收标准

1. THE Report_Page（40项细分能力分析页）SHALL 按八大智能分组显示 40 项细分能力的名称、得分百分比和星级
2. THE Report_Page（40项细分能力分析页）SHALL 对每项细分能力显示对应的结论文本，星级高的显示"最强能力解读"和"加强建议"，星级低的显示"较弱能力解读"和"提升改进"
3. THE Report_Page（40项细分能力分析页）SHALL 由服务端直接查询 CategoryType=3 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出
4. WHEN 40 项细分能力内容过长无法在单页（1309×926px）展示时，THE Report_Page（40项细分能力分析页）SHALL 支持分为多个子页面，每个子页面按智能维度分组展示

需求 12：先天学习类型分析页

用户故事： 作为测评报告的阅读者，我希望了解自己的先天学习类型，以便采用最适合的学习方式。

验收标准

1. THE Report_Page（先天学习类型分析页）SHALL 显示 CategoryType=4（先天学习类型）维度中所有分类的星级评分和排名
2. THE Report_Page（先天学习类型分析页）SHALL 对星级最高的学习类型显示详细的"最强能力解读"和"加强建议"
3. THE Report_Page（先天学习类型分析页）SHALL 对星级最低的学习类型显示"较弱能力解读"和"提升改进"建议
4. THE Report_Page（先天学习类型分析页）SHALL 由服务端直接查询 CategoryType=4 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出

需求 13：学习关键能力分析页

用户故事： 作为测评报告的阅读者，我希望了解自己在学习专注力、思考力、转化力、记忆力、动机力等关键能力上的表现，以便有针对性地提升学习效率。

验收标准

1. THE Report_Page（学习关键能力分析页）SHALL 显示 CategoryType=5（学习关键能力）维度中所有分类的星级评分和排名
2. THE Report_Page（学习关键能力分析页）SHALL 对每项学习能力显示对应的结论文本，包含具体表现和提升改进方法
3. THE Report_Page（学习关键能力分析页）SHALL 由服务端直接查询 CategoryType=5 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出

需求 14：科学大脑类型分析页

用户故事： 作为测评报告的阅读者，我希望了解自己的大脑类型分布（智力脑、创意脑、语言脑、运动脑、情绪脑），以便理解自身的认知优势。

验收标准

1. THE Report_Page（科学大脑类型分析页）SHALL 显示 CategoryType=6（科学大脑类型）维度中所有分类的星级评分和排名
2. THE Report_Page（科学大脑类型分析页）SHALL 对星级最高的大脑类型显示详细的"最强能力解读"和"培养建议"
3. THE Report_Page（科学大脑类型分析页）SHALL 对星级最低的大脑类型显示"较弱能力解读"和"提升改进"建议
4. THE Report_Page（科学大脑类型分析页）SHALL 由服务端直接查询 CategoryType=6 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出

需求 15：性格类型分析页

用户故事： 作为测评报告的阅读者，我希望了解自己的性格类型（孔雀/老虎/猫头鹰/变色龙/考拉），以便理解自身的行为模式和处事风格。

验收标准

1. THE Report_Page（性格类型分析页）SHALL 显示 CategoryType=7（性格类型）维度中星级最高的分类作为主要性格类型
2. THE Report_Page（性格类型分析页）SHALL 显示该性格类型的完整分析内容，包含：性格分析、名人代表、优点、缺点、处事风格
3. THE Report_Page（性格类型分析页）SHALL 显示所有性格类型的星级评分列表，以便展示各性格类型的相对强弱
4. THE Report_Page（性格类型分析页）SHALL 由服务端直接查询 CategoryType=7 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出

需求 16：未来关键发展能力分析页

用户故事： 作为测评报告的阅读者，我希望了解自己在信息运用力、创新创造力、目标成就力等 10 项未来关键能力上的表现，以便规划长期发展方向。

验收标准

1. THE Report_Page（未来关键发展能力分析页）SHALL 显示 CategoryType=8（未来关键发展能力）维度中所有分类的星级评分和排名
2. THE Report_Page（未来关键发展能力分析页）SHALL 对每项能力显示对应的结论文本，星级高的显示"最强表现分析"和"培养建议"，星级低的显示"较弱表现分析"和"改进建议"
3. THE Report_Page（未来关键发展能力分析页）SHALL 由服务端直接查询 CategoryType=8 的 Assessment_Result 和对应的 Assessment_Record_Conclusion 数据，将数据嵌入 HTML 输出
4. WHEN 10 项能力内容过长无法在单页（1309×926px）展示时，THE Report_Page（未来关键发展能力分析页）SHALL 支持分为多个子页面展示

需求 17：页面样式与视觉规范

用户故事： 作为测评报告的阅读者，我希望报告页面具有统一、专业的视觉风格，以便获得良好的阅读体验。

验收标准

1. THE Report_Renderer SHALL 使用统一的配色方案，主色调与学业邑规划品牌一致（主色 #4A90E2）
2. THE Report_Renderer SHALL 为每个报告维度使用固定的标识颜色，在雷达图、柱状图和详情页中保持一致
3. THE Report_Renderer SHALL 使用统一的字体层级，字体大小按 1309×926px 页面尺寸等比设计，确保截图后文字清晰可读
4. THE Report_Renderer SHALL 使用五角星图标展示星级评分，填充星表示已获得的星级，空心星表示未获得的星级
5. THE Report_Page SHALL 在页面顶部显示报告板块标题，在页面底部显示页码信息

需求 18：错误处理与渲染状态

用户故事： 作为后端截图服务，我希望报告页面在数据异常时有明确的错误展示，以便判断截图是否有效。

验收标准

1. IF 服务端查询数据库返回错误或数据不存在，THEN THE Report_Page SHALL 显示对应的错误信息文本，并在 document.body 上添加 data-render-error="true" 属性
2. IF 报告数据中某个板块的 Assessment_Record_Conclusion 结论文本为空，THEN THE Report_Page SHALL 在对应位置显示"暂无分析内容"的占位文本，不影响其他内容的正常展示
3. THE Report_Page SHALL 在服务端渲染输出的 HTML 中包含内联的 JavaScript，当页面中的图表等异步内容渲染完毕后，在 document.body 上添加 data-render-complete="true" 属性