outsource/odf_new
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3257099db1
odf_new/.kiro/specs/flutter-to-uniapp-rewrite/requirements.md

18 KiB
Raw Blame History

需求文档：绥时录 — Flutter 到 UniApp 重写

简介

将现有 Flutter 版本的"绥时录"ODF（光纤配线架）端口管理系统完全重写为 UniApp 版本。该系统用于管理公司 → 地区 → 机房 → 机架(ODF) → 端口的层级数据，支持端口状态查看、备注编辑、搜索、历史故障记录等功能。目标项目目录为 odf-uniapp/。

术语表

  • Application: 绥时录 UniApp 移动端应用程序
  • Auth_Module: 负责用户认证、token 管理和权限校验的模块
  • Navigation_Module: 负责页面路由和导航的模块
  • API_Client: 负责与后端服务器通信的 HTTP 请求模块，基础地址为 http://49.233.115.141:11082
  • Storage_Module: 负责本地数据持久化的模块（基于 uni.setStorageSync / uni.getStorageSync）
  • Company_List_Page: 首页，展示公司列表
  • Region_List_Page: 地区列表页，展示指定公司下的地区
  • Room_List_Page: 机房列表页，展示指定地区下的机房
  • Rack_List_Page: 机架列表页，展示指定机房下的 ODF 机架
  • Rack_Detail_Page: 机架详情页，展示端口矩阵和端口状态
  • Search_Page: 搜索页，支持按备注关键词搜索机房和端口
  • Settings_Page: 设置页，提供修改密码和退出登录功能
  • Change_Password_Page: 修改密码页
  • Login_Page: 登录页
  • Start_Page: 启动页，负责 token 检测和路由分发
  • Port_Edit_Dialog: 端口编辑弹窗，用于查看和编辑端口详细信息
  • Add_Note_Dialog: 添加备注弹窗，用于快速生成格式化备注
  • Update_Dialog: 版本更新弹窗，提示用户下载新版本
  • ODF: 光纤配线架（Optical Distribution Frame）
  • Port: ODF 机架上的单个光纤端口
  • Frame: ODF 机架内的分组单元，每个 Frame 包含多行端口
  • Token: JWT 格式的用户认证令牌
  • Permission: 用户对 ODF 端口的编辑权限（isPermission 标志）
  • Dict_Data: 系统字典数据，包括设备型号和业务类型

需求

需求 1：应用启动与认证流程

用户故事： 作为用户，我希望应用启动时自动检测登录状态并跳转到正确页面，以便快速进入工作界面。

验收标准

  1. WHEN Application 启动时, THE Start_Page SHALL 从 Storage_Module 读取本地存储的 Token
  2. WHILE Token 存在且非空, THE Auth_Module SHALL 调用权限检测接口 GET /business/OdfPorts/odf 验证 Token 有效性
  3. WHEN 权限检测接口返回状态码 200, THE Auth_Module SHALL 设置 Permission 为 true 并将 Navigation_Module 导航至 Company_List_Page
  4. WHEN 权限检测接口返回状态码 403, THE Auth_Module SHALL 设置 Permission 为 false 并将 Navigation_Module 导航至 Company_List_Page
  5. WHEN 权限检测接口返回状态码 401, THE Navigation_Module SHALL 导航至 Login_Page
  6. WHEN Token 不存在或为空, THE Navigation_Module SHALL 直接导航至 Login_Page
  7. THE Start_Page SHALL 在页面中央显示应用名称"绥时录"作为启动标识

需求 2：用户登录

用户故事： 作为用户，我希望通过账号密码登录系统，以便获取操作权限。

验收标准

  1. THE Login_Page SHALL 提供账号输入框（提示文字"请输入账号"）和密码输入框（提示文字"请输入密码"，密码模式遮蔽显示）
  2. WHEN 用户点击"登录"按钮, THE Auth_Module SHALL 调用 POST /appLogin 接口发送 username 和 password 参数
  3. WHEN 登录接口返回状态码 200, THE Auth_Module SHALL 从响应数据中提取 jwt、userId、userName，将 Token 存储至 Storage_Module，并将 userId 和 userName 保存到全局状态
  4. WHEN 登录接口返回状态码 200, THE Auth_Module SHALL 调用权限检测接口确认权限后导航至 Company_List_Page
  5. IF 登录接口返回非 200 状态码, THEN THE Application SHALL 以 Toast 形式显示服务器返回的错误消息
  6. THE Login_Page SHALL 使用背景图片覆盖整个页面，主题色为 #1A73EC

需求 3：首页（公司列表）

用户故事： 作为用户，我希望在首页看到所有公司列表，以便选择目标公司进入下级管理。

验收标准

  1. WHEN Company_List_Page 加载时, THE API_Client SHALL 调用 GET /business/OdfRooms/getcompany 获取公司列表数据
  2. THE Company_List_Page SHALL 以卡片列表形式展示每个公司的 deptName
  3. WHEN 用户点击某个公司卡片, THE Navigation_Module SHALL 携带该公司的 deptId 导航至 Region_List_Page
  4. THE Company_List_Page SHALL 支持下拉刷新，刷新时重新调用公司列表接口
  5. THE Company_List_Page SHALL 在顶部栏左侧显示刷新图标、中间显示"公司列表"标题、右侧显示设置图标
  6. WHEN 用户点击设置图标, THE Navigation_Module SHALL 导航至 Settings_Page
  7. THE Company_List_Page SHALL 在标题栏下方显示搜索入口栏（提示文字"请输入要搜索的备注内容"）
  8. WHEN 用户点击搜索入口栏, THE Navigation_Module SHALL 导航至 Search_Page
  9. WHEN Company_List_Page 加载时, THE API_Client SHALL 同时调用设备型号字典接口 GET /system/dict/data/type/odf_ports_unit_type 和业务类型字典接口 GET /system/dict/data/type/odf_ports_business_type，并将结果存储到全局状态
  10. WHEN Company_List_Page 加载时, THE Application SHALL 调用版本检查接口 GET /webapi/CheckAppVersion 并传入当前应用版本号

需求 4：版本更新检查

用户故事： 作为用户，我希望应用能自动检测新版本并提示更新，以便使用最新功能。

验收标准

  1. WHEN 版本检查接口返回 needUpdate 为 true, THE Application SHALL 弹出 Update_Dialog
  2. THE Update_Dialog SHALL 显示更新图标、"有新版本请更新"提示文字和"去更新"按钮
  3. WHEN 用户点击"去更新"按钮, THE Application SHALL 使用系统浏览器打开 downloadUrl 指定的下载地址
  4. THE Update_Dialog SHALL 为模态弹窗，用户无法通过点击空白区域或返回键关闭

需求 5：地区列表

用户故事： 作为用户，我希望查看指定公司下的地区列表，以便选择目标地区。

验收标准

  1. WHEN Region_List_Page 加载时, THE API_Client SHALL 调用 GET /business/OdfRooms/getregion 并传入 deptId 参数获取地区列表
  2. THE Region_List_Page SHALL 以卡片列表形式展示每个地区的 deptName
  3. WHEN 用户点击某个地区卡片, THE Navigation_Module SHALL 携带该地区的 deptId 导航至 Room_List_Page
  4. THE Region_List_Page SHALL 在顶部显示返回按钮和"地区列表"标题

需求 6：机房列表

用户故事： 作为用户，我希望查看指定地区下的机房列表，以便选择目标机房。

验收标准

  1. WHEN Room_List_Page 加载时, THE API_Client SHALL 调用 GET /business/OdfRooms/list 并传入 pageNum=1、pageSize=20、deptId 参数获取机房列表
  2. THE Room_List_Page SHALL 以卡片形式展示每个机房的 roomName（机房名）、roomAddress（地址）和 racksCount（ODF 数量，格式为"ODF: N台"）
  3. WHEN 用户点击某个机房卡片, THE Navigation_Module SHALL 携带该机房的 id 和 roomName 导航至 Rack_List_Page
  4. THE Room_List_Page SHALL 支持下拉刷新，刷新时重置 pageNum 为 1 并重新加载数据
  5. WHEN 用户滚动至列表底部（距底部 100px 以内）, THE API_Client SHALL 自动递增 pageNum 并加载下一页数据追加到列表末尾
  6. THE Room_List_Page SHALL 在顶部显示返回按钮和"机房列表"标题

需求 7：机架列表

用户故事： 作为用户，我希望查看指定机房下的 ODF 机架列表，以便选择目标机架查看端口详情。

验收标准

  1. WHEN Rack_List_Page 加载时, THE API_Client SHALL 调用 GET /business/OdfRacks/list 并传入 pageNum=1、pageSize=20、roomId 参数获取机架列表
  2. THE Rack_List_Page SHALL 以卡片列表形式展示每个机架的 rackName
  3. WHEN 用户点击某个机架卡片, THE Navigation_Module SHALL 携带该机架的 id、rackName 和 roomName 导航至 Rack_Detail_Page
  4. THE Rack_List_Page SHALL 支持下拉刷新，刷新时重置 pageNum 为 1 并重新加载数据
  5. WHEN 用户滚动至列表底部（距底部 100px 以内）, THE API_Client SHALL 自动递增 pageNum 并加载下一页数据追加到列表末尾
  6. THE Rack_List_Page SHALL 在顶部显示返回按钮和"机房详情"标题

需求 8：机架详情（端口矩阵）

用户故事： 作为用户，我希望查看机架内所有端口的状态矩阵，以便快速了解端口连接情况。

验收标准

  1. WHEN Rack_Detail_Page 加载时, THE API_Client SHALL 调用 GET /business/OdfPorts/mlist 并传入 RackId 参数获取机架详情数据
  2. WHILE 数据加载中, THE Application SHALL 显示"loading..."加载提示
  3. THE Rack_Detail_Page SHALL 在顶部显示返回按钮和"{rackName}详情"标题，标题下方显示 roomName（蓝色 #1A73EC 字体加粗）
  4. THE Rack_Detail_Page SHALL 在 roomName 下方显示状态图例：绿色圆点标注"已连接"、红色圆点标注"已断开"
  5. THE Rack_Detail_Page SHALL 按 Frame 分组展示端口数据，每个 Frame 显示为一个白色卡片，卡片顶部显示 Frame 名称
  6. THE Rack_Detail_Page SHALL 在每个 Frame 卡片内按行排列端口，每个端口显示为圆形图标：status=1 时为绿色（已连接），status=0 时为红色（已断开），圆形内显示 tips 文字，圆形下方显示端口 name
  7. WHEN 端口行内容超出屏幕宽度, THE Rack_Detail_Page SHALL 支持水平滚动查看
  8. WHEN 用户点击某个端口圆形图标, THE Application SHALL 弹出 Port_Edit_Dialog 并传入该端口的 id

需求 9：端口编辑弹窗

用户故事： 作为用户，我希望查看和编辑端口的详细信息，以便维护端口数据。

验收标准

  1. WHEN Port_Edit_Dialog 打开时, THE API_Client SHALL 调用 GET /business/OdfPorts/{id} 获取端口详细信息
  2. WHILE 数据加载中, THE Application SHALL 显示"loading..."加载提示
  3. THE Port_Edit_Dialog SHALL 显示端口位置信息（格式为"位置:{frameName}{name}"）和当前状态（绿色/红色圆点 + "已连接"/"已断开"文字）
  4. THE Port_Edit_Dialog SHALL 提供备注说明多行输入框（5行高度，提示文字"请输入备注说明"）
  5. THE Port_Edit_Dialog SHALL 在备注输入框旁显示"添加备注"按钮，点击后弹出 Add_Note_Dialog
  6. THE Port_Edit_Dialog SHALL 提供光衰信息单行输入框（提示文字"请输入光衰信息"）
  7. THE Port_Edit_Dialog SHALL 提供历史障碍记录区域，显示已有记录列表，每条记录包含时间选择器和故障原因输入框
  8. THE Port_Edit_Dialog SHALL 提供"添加新记录"链接，点击后在历史障碍列表末尾添加一条空记录
  9. THE Port_Edit_Dialog SHALL 在每条历史障碍记录右侧显示删除按钮（红色"-"），点击后移除该条记录
  10. THE Port_Edit_Dialog SHALL 提供光缆段信息单行输入框（提示文字"请输入光缆段信息"）
  11. WHILE Permission 为 true, THE Port_Edit_Dialog SHALL 显示"改变状态"区域，包含"连接"（绿色）和"断开"（红色）两个切换按钮，以及提示文字"断开后只清空备注说明,其他内容不影响"
  12. WHILE Permission 为 true, THE Port_Edit_Dialog SHALL 显示"取消"和"提交"两个操作按钮
  13. WHILE Permission 为 false, THE Port_Edit_Dialog SHALL 禁用所有输入框和编辑功能，仅显示"关闭"按钮
  14. WHEN 用户点击"提交"按钮, THE API_Client SHALL 调用 POST /business/OdfPorts/save 发送 Id、Status、Remarks、OpticalAttenuation、HistoryRemarks、HistoryFault、OpticalCableOffRemarks 参数
  15. IF 历史障碍记录中存在未选择时间的条目, THEN THE Application SHALL 以 Toast 显示"请选择障碍发生时间!"并阻止提交
  16. WHEN 保存接口返回成功, THE Port_Edit_Dialog SHALL 关闭弹窗并触发父页面刷新机架详情数据

需求 10：添加备注弹窗

用户故事： 作为用户，我希望通过结构化表单快速生成格式化备注，以便提高备注录入效率。

验收标准

  1. THE Add_Note_Dialog SHALL 显示"添加备注"标题
  2. THE Add_Note_Dialog SHALL 提供业务名称输入框（提示文字"请输入业务名称"）
  3. THE Add_Note_Dialog SHALL 提供设备型号下拉选择器，选项来源于全局存储的 Dict_Data（odf_ports_unit_type），默认选中第一项
  4. THE Add_Note_Dialog SHALL 提供业务类型下拉选择器，选项来源于全局存储的 Dict_Data（odf_ports_business_type），默认选中第一项
  5. THE Add_Note_Dialog SHALL 提供三组端口号数输入框（提示文字分别为"1号端口数"、"2号端口数"、"3号端口数"），仅允许输入数字
  6. WHEN 用户点击"提交"按钮, THE Add_Note_Dialog SHALL 校验业务名称和三组端口号均不为空
  7. IF 业务名称为空, THEN THE Application SHALL 以 Toast 显示"请输入业务名称"
  8. IF 任一端口号为空, THEN THE Application SHALL 以 Toast 显示"请输入端口号"
  9. WHEN 校验通过, THE Add_Note_Dialog SHALL 将备注内容格式化为"{业务名称} {设备型号} {业务类型} {端口号1}/{端口号2}/{端口号3}"并回填至 Port_Edit_Dialog 的备注输入框，然后关闭弹窗
  10. THE Add_Note_Dialog SHALL 提供"取消"按钮，点击后关闭弹窗不做任何操作

需求 11：搜索功能

用户故事： 作为用户，我希望通过备注关键词搜索端口和机房，以便快速定位目标设备。

验收标准

  1. THE Search_Page SHALL 在顶部显示返回按钮和"搜索"标题
  2. THE Search_Page SHALL 提供搜索输入框（提示文字"请输入要搜索的备注内容"）和"搜索"按钮
  3. WHEN 用户点击"搜索"按钮或在键盘上按下搜索键, THE API_Client SHALL 调用 GET /business/OdfPorts/search2 并传入 key、pageNum=1、pageSize=20 参数
  4. THE Search_Page SHALL 将搜索结果分为"机房"和"备注信息"两个区域展示
  5. THE Search_Page SHALL 在"机房"区域以卡片形式展示匹配的机房列表，每个卡片显示 roomName
  6. WHEN 用户点击机房卡片, THE Navigation_Module SHALL 携带 roomId 和 roomName 导航至 Rack_List_Page
  7. THE Search_Page SHALL 在"备注信息"区域以卡片形式展示匹配的端口列表，每个卡片显示 roomName、address、rackName（ODF名称）、frameName+name（点位置）、remarks（备注）、opticalAttenuation（光衰信息）、historyRemarks（历史故障原因及时间）、opticalCableOffRemarks（光缆段信息）和当前状态（圆点+文字）
  8. WHEN 用户点击端口卡片, THE Navigation_Module SHALL 携带 rackId、rackName、roomName 和端口 id 导航至 Rack_Detail_Page，并自动弹出该端口的 Port_Edit_Dialog
  9. WHEN 用户滚动至搜索结果底部（距底部 100px 以内）, THE API_Client SHALL 自动递增 pageNum 并加载下一页端口数据追加到列表末尾

需求 12：设置与密码修改

用户故事： 作为用户，我希望能修改密码和退出登录，以便管理账户安全。

验收标准

  1. THE Settings_Page SHALL 在顶部显示返回按钮和"设置"标题
  2. THE Settings_Page SHALL 显示"修改密码"选项卡片和"退出登录"选项卡片（红色文字）
  3. WHEN 用户点击"修改密码"卡片, THE Navigation_Module SHALL 导航至 Change_Password_Page
  4. WHEN 用户点击"退出登录"卡片, THE Auth_Module SHALL 清除 Storage_Module 中的 Token 并将 Navigation_Module 导航至 Login_Page（清除导航栈）
  5. THE Change_Password_Page SHALL 在顶部显示返回按钮和"修改密码"标题
  6. THE Change_Password_Page SHALL 提供旧密码输入框（提示文字"请输入旧密码"）和新密码输入框（提示文字"请输入新密码"）
  7. WHEN 用户点击"确认修改"按钮, THE API_Client SHALL 调用 POST /system/user/profile/updateUserPwd 发送 oldPassword 和 newPassword 参数
  8. IF 旧密码输入框为空, THEN THE Application SHALL 以 Toast 显示"请输入旧密码!"
  9. IF 新密码输入框为空, THEN THE Application SHALL 以 Toast 显示"请输入新密码!"
  10. WHEN 修改密码接口返回状态码 200, THE Application SHALL 以 Toast 显示"修改成功"并返回上一页
  11. WHEN 修改密码接口返回状态码 110, THE Application SHALL 以 Toast 显示服务器返回的错误消息

需求 13：API 通信层

用户故事： 作为开发者，我希望有统一的 API 通信层，以便所有接口请求遵循一致的规范。

验收标准

  1. THE API_Client SHALL 以 http://49.233.115.141:11082 作为所有请求的基础地址
  2. THE API_Client SHALL 在每个请求的 Header 中携带 Authorization: Bearer {token}、Userid 和 Username 三个字段
  3. THE API_Client SHALL 将请求超时时间设置为连接超时 20 秒、发送超时 10 秒、接收超时 20 秒
  4. THE API_Client SHALL 统一解析响应 JSON 结构，提取 code、msg、data 三个字段
  5. IF 网络请求发生异常, THEN THE API_Client SHALL 返回包含错误码 -1 和异常描述的错误对象
  6. THE API_Client SHALL 支持 GET 和 POST 两种请求方法，GET 请求参数通过 queryParameters 传递，POST 请求参数通过 request body 传递

需求 14：全局 UI 规范

用户故事： 作为用户，我希望应用具有统一的视觉风格和交互体验。

验收标准

  1. THE Application SHALL 使用 #1A73EC 作为主题色，应用于按钮、搜索框、链接等交互元素
  2. THE Application SHALL 在所有列表页面使用统一的背景图片覆盖
  3. THE Application SHALL 使用绿色圆点表示"已连接"状态，红色圆点表示"已断开"状态
  4. THE Application SHALL 在所有需要等待的操作中显示"loading..."加载提示
  5. THE Application SHALL 使用 Toast 消息提示用户操作结果和错误信息
  6. THE Application SHALL 在所有二级页面顶部提供统一的返回按钮和居中标题栏布局
  7. THE Application SHALL 在所有列表页面支持下拉刷新功能，刷新指示器颜色为 #1A73EC
  8. WHILE 列表数据支持分页加载, THE Application SHALL 使用 pageSize=20 作为默认分页大小