name: prd-document
description: 产品 PRD / 页面设计文档模板。用于编写模块功能说明、页面布局、数据模型引用、交互流程和测试入口。按 M1-M9 章节模板组织。

适用场景

• 新功能模块或页面的设计文档
• 已有页面的功能演进记录
• 跨团队对齐的功能说明文档

文档结构（M1-M9）

每个 PRD 文档按 9 个章节组织。文件路径：docs/design/pages/<page-name>.md

M1 总章节说明

声明本文档职责、边界和各章节用途。一般包含一个速查表格。

## M1 总章节说明 本文档是 `docs/design/pages/` 下的 <页面名> 设计文档。 | 章节 | 说明 | |------|------| | M1 | 本文档职责和各章节用途 | | M2 | 页面入口、源码位置、参考规范 | | M3 | 页面目标、适用范围和不纳入范围 | | M4 | 页面布局和分区 | | M5 | 基础功能点 | | M6 | 核心交互与联动规则 | | M7 | 状态、数据流和提交事件流 | | M8 | 校验、异常和边界规则 | | M9 | 接口/模型边界、测试入口和维护触发 |

M2 页面入口与工作入口

## M2 页面入口与工作入口 | 类型 | 入口 | |------|------| | 页面路由 | `/create-event` | | 源码目录 | `src/pages/create-event/` | | 参考规范 | `docs/code-style/` 下的 components/pages/styles 等 | | 模型文档 | `docs/design/models/incident.md` | | 测试入口 | `__tests__/create-event-page.test.tsx` |

M3 页面目标与适用范围

## M3 页面目标与适用范围 <页面名> 服务 <用户角色> 完成 <核心任务>。 适用范围： - <场景1> - <场景2> 不纳入范围： - <边界外场景1>

M4 页面布局

## M4 页面布局 | 区域 | 内容 | 组件 | |------|------|------| | 顶部 | 面包屑 + 页面标题 | `<PageHeader>` | | 左侧 | 表单区（字段1/2/3） | `<FormSection>` | | 右侧 | AI 助手面板 | `<AssistantPanel>` | | 底部 | 操作按钮区 | `<ActionBar>` |

M5 基础功能点

用编号列表，每个功能点包含触发条件、行为和结果。

## M5 基础功能点 ### F1 表单填写 1. 用户进入页面 → 加载引用数据 → 渲染表单 2. 用户填写标题 → 实时校验长度（≤80 字符） 3. 用户选择分类 → 联动加载下级选项 ### F2 附件上传 1. 点击"上传附件" → 打开文件选择器 2. 选择文件 → 展示上传进度 → 完成后显示在列表中 3. 点击删除 → 弹出确认 → 确认后移除 ### F3 提交 1. 点击"提交" → 校验所有必填字段 2. 校验通过 → 构建 payload → 调用创建接口 3. 成功 → 提示 + 跳转到详情页 4. 失败 → 展示错误信息，保留表单数据

M6 核心交互与联动

## M6 核心交互与联动 ### 分类联动 - 选择一级分类 → 清空二级分类 → 加载对应二级选项 - 如果一级分类只有一个二级选项，自动选中 ### 搜索与筛选 - 输入框 onChange 只更新草稿态，不发起请求 - 回车 / 点击"查询" → 提交草稿并请求列表 - 点击"重置" → 清空草稿和已提交条件，回到第一页 ### AI 建议采纳 - AI 面板弹出建议 → 用户点击"采纳" - 采纳后自动填入对应表单字段 - 用户仍可手动修改被采纳的字段

M7 状态与数据流

## M7 状态与数据流 ### 状态分层 | 状态 | 存放位置 | 生命周期 | |------|----------|----------| | 表单数据 | 页面 store | 页面存活期间 | | 引用数据 | 全局 store | 应用存活期间 | | UI 临时态（展开/折叠） | 组件 local state | 组件存活期间 | | 提交 loading | 页面 local state | 提交期间 | ### 数据流

用户操作 → Hook/Store Action → API 请求 → 更新 Store → 视图刷新
↓ 失败
错误提示（不刷新）

M8 校验与异常

## M8 校验与异常 ### 校验规则 | 字段 | 规则 | |------|------| | 标题 | 必填，≤80 字符 | | 分类 | 必选 | | 描述 | 可选，≤500 字符 | ### 异常处理 | 场景 | 处理 | |------|------| | 网络断开 | 保留表单数据，提示用户稍后重试 | | 接口超时 | 显示超时提示，不禁用提交按钮 | | 并发提交 | 提交期间禁用按钮，防止重复 | | 引用数据加载失败 | 表单仍可填写，分类选择降级为输入框 |

M9 边界与测试

## M9 边界与测试 ### 接口依赖 | 接口 | 用途 | Mock 路径 | |------|------|-----------| | POST /api/incident | 创建工单 | `mock/incident.ts` | | GET /api/reference-data | 引用数据 | `mock/reference-data.ts` | ### 模型引用 | 模型文档 | 引用内容 | |----------|----------| | `docs/design/models/incident.md` | 工单字段定义、创建 payload | ### 测试覆盖 | 测试文件 | 覆盖范围 | |----------|----------| | `__tests__/create-event.test.tsx` | 表单填写、校验、提交成功/失败 | | `__tests__/create-event-ai.test.tsx` | AI 建议采纳、覆盖写入 | ### 维护触发 满足以下任一条件时更新本文档： - 新增或移除功能点 - 调整页面布局/分区 - 接口或模型引用变更 - 校验规则改变

文档维护规则

1. 只记录最终状态和当前约定，不保留历史版本
2. 功能文档只保留最新有效内容
3. 文档中的源码路径、接口路径必须可验证
4. 每个 PRD 必须声明最后校订时间