forked from wangziqi/gongxue-base
chore: 归档 3 个 change 产物、Design Doc、验证报告、主 spec、项目配置
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-03
|
||||
@@ -0,0 +1,95 @@
|
||||
## Context
|
||||
|
||||
恭学教育基地管理后台是一个基于 React 19 + Ant Design v6 的单页应用，服务对象为基地管理人员。当前前端仅有一个 768px 的移动端断点（`MainLayout` 中），且页面级适配不完整：多列表格无横向滚动、仪表盘卡片使用硬编码 `Col span`、弹窗无宽度约束等。管理场景中操作人员可能使用手机、iPad/平板、桌面电脑等不同设备，需要统一的三端响应式体验。
|
||||
|
||||
**技术约束：**
|
||||
- 不引入新的 UI 依赖，保持使用 Ant Design v6
|
||||
- 不改动后端 API 和后端逻辑
|
||||
- 使用纯 CSS（`@media` queries）+ antd 响应式 props（`Row/Col` 断点、`Table scroll`）
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 建立统一的三断点体系：手机 `< 768px`、平板 `768-1024px`、桌面 `> 1024px`
|
||||
- 所有页面的 `<Table>` 在小屏下可通过横向滚动查看全部列
|
||||
- 仪表盘统计卡片在平板和手机端自动调整列数
|
||||
- 登录页在手机上不溢出
|
||||
- 弹窗在所有端侧不超出屏幕
|
||||
- ECharts 图表响应容器宽度变化
|
||||
- 学生管理页「学号/身份证」拆分为两列
|
||||
- API/数据获取层不变，仅改 UI 渲染层
|
||||
|
||||
**Non-Goals:**
|
||||
- 不更换组件库或引入 Tailwind CSS 等新样式框架
|
||||
- 不做列响应式隐藏（表格列全部保留，靠横向滚动）
|
||||
- 不改变路由和权限体系
|
||||
- 不涉及服务端渲染或 SSR
|
||||
- 不添加视觉主题切换能力
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 断点定义与 CSS 组织
|
||||
|
||||
| 断点 | 范围 | 典型设备 |
|
||||
|------|------|---------|
|
||||
| `xs` (手机) | < 768px | iPhone、Android 手机 |
|
||||
| `sm` (平板) | 768px - 1024px | iPad 竖屏、小型平板 |
|
||||
| `md+` (桌面) | > 1024px | 笔记本、台式显示器 |
|
||||
|
||||
**策略：**
|
||||
- 全局样式放在 `index.css`，使用 `@media` 规则
|
||||
- antd `Row/Col` 组件使用内置 `xs/sm/md/lg` 断点 props
|
||||
- 避免组件内联 style 中的固定像素值，改为 CSS class 或 antd 响应式 props
|
||||
|
||||
**为什么不引入 CSS 变量/主题系统？**
|
||||
当前项目规模适中（~16 页面），引入 CSS 变量体系增加复杂度但收益有限。直接用 `@media` queries + antd 响应式 props 即可覆盖。
|
||||
|
||||
### 2. 表格横向滚动策略
|
||||
|
||||
**决策：** 所有 `<Table>` 统一添加 `scroll={{ x: 'max-content' }}` 或基于列宽计算的 `x` 值，移动端通过手指滑动查看全部列。
|
||||
|
||||
**列宽优化：**
|
||||
- 操作列固定宽度（`width: 120-200`），配合 `fixed: 'right'` 可选
|
||||
- 数据列设置合理的 `width` 避免过窄或过宽
|
||||
- 使用 `ellipsis: true` 防止长文本撑开列宽
|
||||
|
||||
**为什么不用 antd 的 `responsive` 列隐藏？**
|
||||
用户明确要求保留全部列、用横向滚动。管理后台数据密集场景下，隐藏列可能导致信息缺失。
|
||||
|
||||
### 3. 布局与侧栏
|
||||
|
||||
**桌面（> 1024px）：** 保持当前 `Sider` + 内容区布局，侧栏可折叠，content margin 24px。
|
||||
**平板（768-1024px）：** `Sider` 默认折叠（`collapsed: true`），减少侧栏占用宽度，content margin 16px。
|
||||
**手机（< 768px）：** 当前已有 `Drawer` 替代 `Sider`，content margin 12px。
|
||||
|
||||
### 4. 仪表盘与图表
|
||||
|
||||
统计卡片：
|
||||
```
|
||||
xs={12} sm={12} md={6} // 手机: 2列, 平板: 2列, 桌面: 4列
|
||||
```
|
||||
图表卡片：
|
||||
```
|
||||
xs={24} sm={12} // 手机: 堆叠, 平板及以上: 并排
|
||||
```
|
||||
|
||||
ECharts 通过 `echarts-for-react` 的 `style={{ width: '100%' }}` 自动跟随容器宽度。
|
||||
|
||||
### 5. 弹窗与表单
|
||||
|
||||
- Modal 添加 `width` 在桌面固定（400-600），平板/手机使用百分比或 `max-width` 约束
|
||||
- 全局 CSS: `.ant-modal { max-width: calc(100vw - 32px); }`
|
||||
- Form 保持 `layout="vertical"`，天然适配窄屏
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| 表格横向滚动在手机上交互不直观 | 添加 `scroll={{ x }}` 后 antd 自动显示滚动条；操作列可用 `fixed: 'right'` 固定 |
|
||||
| ECharts 甘特图在窄屏可能挤缩 | 设置最小高度，必要时在容器上 `overflowX: auto` |
|
||||
| 教室排期表（31 天列）表格极宽 | 已有 `overflowX: auto`，优化列 minWidth 和 sticky 首列 |
|
||||
| 修改涉及文件多（~18 个），可能引入 layout 抖动 | 每个页面改动后手动验证；改动粒度小（CSS + props），回滚简单 |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- 无。三端断点、表格策略、拆分字段均已与需求方确认。
|
||||
@@ -0,0 +1,30 @@
|
||||
## Why
|
||||
|
||||
管理后台当前仅在布局层有一个 768px 的移动端断点，大多数页面使用固定列宽、硬编码 `Col span` 和多列表格，导致在手机和平板上文字溢出、按钮换行错位、表格内容被截断。需要为手机（< 768px）、平板（768-1024px）、桌面（> 1024px）三个端侧做统一响应式适配，确保所有界面文字不溢出、不强制换行。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **全局布局增强**：为 MainLayout 的内容区、侧栏折叠、Header 用户信息区域增加平板断点适配
|
||||
- **CSS 断点体系**：在 `index.css` 中建立三断点响应式体系（`@media` 规则），覆盖表格、卡片、按钮、弹窗等全局组件
|
||||
- **全页面表格适配**：为所有页面的 `<Table>` 添加 `scroll={{ x }}` 确保窄屏横向滚动，列宽优化防止数据截断
|
||||
- **仪表盘响应式**：将 `Col span={6}` 改为响应式断点（`xs/sm/md`），ECharts 图表跟随窗口 resize
|
||||
- **登录页适配**：登录卡片从固定宽度改为响应式最大宽度
|
||||
- **工具栏/搜索栏适配**：统一所有页面顶部操作栏的 wrap 和 gap 行为
|
||||
- **弹窗响应式**：所有 Modal 添加平板/手机下的最大宽度和高度约束
|
||||
- **排期表适配**：教室排期的大 HTML 表格优化列宽和滚动体验
|
||||
- **学生字段拆分**：将学生管理页的「学号/身份证」列拆分为「学号」和「身份证」两个独立列
|
||||
- 保持使用 Ant Design v6 组件库，不引入新的 UI 依赖
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `responsive-layout`: 管理后台三端（手机 < 768px / 平板 768-1024px / 桌面 > 1024px）响应式布局，包括全局 CSS 断点、布局适配、表格横向滚动、组件响应式行为
|
||||
|
||||
### Modified Capabilities
|
||||
（无现有前端相关 spec，不需要 delta spec）
|
||||
|
||||
## Impact
|
||||
|
||||
- **受影响文件**: `apps/admin/src/` 下所有页面组件（16 个页面 + 1 个布局）、`index.css`、部分组件文件
|
||||
- **不涉及**: 后端 API、数据库 schema、部署配置、认证/权限逻辑
|
||||
- **风险**: 低——改动限于 CSS 和组件 props，不涉及业务逻辑变更
|
||||
@@ -0,0 +1,86 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Three-breakpoint responsive system
|
||||
The admin frontend SHALL adapt its layout to three device tiers: mobile (< 768px), tablet (768-1024px), and desktop (> 1024px). All pages and components MUST render without text overflow, forced line wrapping, or content clipping at any breakpoint.
|
||||
|
||||
#### Scenario: Mobile layout (< 768px)
|
||||
- **WHEN** viewport width is less than 768px
|
||||
- **THEN** sidebar is replaced by a Drawer triggered via hamburger button
|
||||
- **AND** content area padding reduces to 12px
|
||||
- **AND** tables scroll horizontally with touch gesture
|
||||
- **AND** dashboard stat cards display in 2-column grid
|
||||
|
||||
#### Scenario: Tablet layout (768-1024px)
|
||||
- **WHEN** viewport width is between 768px and 1024px
|
||||
- **THEN** sidebar defaults to collapsed state
|
||||
- **AND** content area padding is 16px
|
||||
- **AND** dashboard stat cards display in 2-column grid
|
||||
- **AND** chart cards display side-by-side
|
||||
|
||||
#### Scenario: Desktop layout (> 1024px)
|
||||
- **WHEN** viewport width is greater than 1024px
|
||||
- **THEN** sidebar is fully visible and collapsible
|
||||
- **AND** content area padding is 24px
|
||||
- **AND** dashboard stat cards display in 4-column grid
|
||||
- **AND** chart cards display side-by-side
|
||||
|
||||
### Requirement: Table horizontal scroll on narrow screens
|
||||
All `<Table>` components SHALL support horizontal scrolling when content exceeds viewport width. The scroll behavior MUST be enabled via scroll={{ x }} prop, and all table columns MUST remain visible (no responsive column hiding).
|
||||
|
||||
#### Scenario: Wide table on mobile
|
||||
- **WHEN** a table has more columns than fit within the viewport width
|
||||
- **THEN** the table container renders a horizontal scrollbar
|
||||
- **AND** users can scroll horizontally to view all columns
|
||||
- **AND** action column (if present) remains accessible without scrolling via fixed position
|
||||
|
||||
### Requirement: Login page responsiveness
|
||||
The login page card SHALL not overflow the viewport on any screen size. On mobile devices, the card MUST fit within the screen with comfortable margins.
|
||||
|
||||
#### Scenario: Login on small mobile screen (320px)
|
||||
- **WHEN** viewport width is 320px
|
||||
- **THEN** login card width does not exceed `calc(100vw - 32px)`
|
||||
- **AND** the login form remains fully visible and usable
|
||||
|
||||
### Requirement: Dashboard responsive grid
|
||||
Dashboard stat cards and chart cards SHALL use antd responsive Col breakpoints (xs/sm/md) instead of fixed span values. Charts SHALL re-render to fit container width on window resize.
|
||||
|
||||
#### Scenario: Dashboard on tablet
|
||||
- **WHEN** viewing dashboard on a 800px wide tablet
|
||||
- **THEN** stat cards render 2 per row
|
||||
- **AND** pie chart and bar chart render side by side
|
||||
- **AND** gantt chart fits within the content area width
|
||||
|
||||
### Requirement: Modal responsiveness
|
||||
All Modal dialogs SHALL have a max-width constraint preventing overflow beyond the viewport on small screens.
|
||||
|
||||
#### Scenario: Modal on mobile
|
||||
- **WHEN** a modal is opened on a viewport < 768px wide
|
||||
- **THEN** the modal width does not exceed `calc(100vw - 24px)`
|
||||
- **AND** the modal body has a max-height of 60vh with vertical scroll
|
||||
- **AND** modal mask covers the full viewport
|
||||
|
||||
### Requirement: Page toolbar responsive wrapping
|
||||
All page-level toolbars with search/filter/action controls SHALL wrap gracefully on narrow screens using flexWrap and gap spacing, preventing button group clipping or overlap.
|
||||
|
||||
#### Scenario: Toolbar with search and action buttons on tablet
|
||||
- **WHEN** a page toolbar contains a search input group and action button group
|
||||
- **AND** viewport width is 800px
|
||||
- **THEN** toolbar items wrap to multiple lines without overflow
|
||||
- **AND** all buttons remain clickable with adequate spacing
|
||||
|
||||
### Requirement: Student fields separation
|
||||
The Students page SHALL display "学号" (student ID) and "身份证" (ID card number) as two separate table columns instead of a single combined column. Both columns SHALL support ellipsis truncation for long values.
|
||||
|
||||
#### Scenario: Student table column display
|
||||
- **WHEN** viewing the student list
|
||||
- **THEN** the table includes a "学号" column and a "身份证" column as separate headers
|
||||
- **AND** long ID numbers are truncated with ellipsis and tooltip on hover
|
||||
|
||||
### Requirement: Classroom schedule table scrolling
|
||||
The classroom schedule grid table SHALL support horizontal scrolling with a sticky first column (classroom name) to aid navigation when viewing beyond the visible date range.
|
||||
|
||||
#### Scenario: Schedule table on month with 31 days
|
||||
- **WHEN** viewing a month schedule on a tablet (800px)
|
||||
- **THEN** the classroom name column remains fixed on the left
|
||||
- **AND** date columns scroll horizontally
|
||||
- **AND** no text overflows or wraps within date cells
|
||||
@@ -0,0 +1,117 @@
|
||||
## 1. 全局基础：CSS 断点体系
|
||||
|
||||
- [x] 1.1 在 `index.css` 中建立三断点 `@media` 体系：手机 `< 768px`、平板 `768-1023px`、桌面 `≥ 1024px`
|
||||
- [x] 1.2 添加全局表格横向滚动样式（`.ant-table { overflow-x: auto }` 确保窄屏可滑动）
|
||||
- [x] 1.3 添加全局弹窗响应式约束（`max-width: calc(100vw - 32px)`、`max-height: 80vh`）
|
||||
- [x] 1.4 添加全局按钮组/Card/Descriptions 等通用组件的断点样式
|
||||
|
||||
## 2. 布局层：MainLayout 三端适配
|
||||
|
||||
- [x] 2.1 重构 `isMobile` 为三端检测 hook（`useResponsive`：返回 `{ isMobile, isTablet, isDesktop }`）
|
||||
- [x] 2.2 平板断点：侧栏默认折叠（`collapsed: true`），内容区 padding 16px
|
||||
- [x] 2.3 桌面断点：保持当前行为（侧栏可折叠，padding 24px）
|
||||
- [x] 2.4 Header 用户信息区域：平板/手机下文字隐藏仅显示 Avatar
|
||||
|
||||
## 3. 登录页
|
||||
|
||||
- [x] 3.1 登录卡片改为 `maxWidth: 400, width: calc(100vw - 48px)`
|
||||
|
||||
## 4. 数据面板（Dashboard）
|
||||
|
||||
- [x] 4.1 统计卡片 `Col` 从 `span={6}` 改为 `xs={12} sm={12} md={6}`
|
||||
- [x] 4.2 图表卡片 `Col` 从 `span={12}` 改为 `xs={24} sm={12}`
|
||||
- [x] 4.3 ECharts 图表的 `style` 添加 `width: '100%'` 确保跟随容器 resize
|
||||
- [x] 4.4 顶部标题和日期选择器在小屏下堆叠排列
|
||||
|
||||
## 5. 宿舍总览（RoomVisual）
|
||||
|
||||
- [x] 5.1 检查并补齐平板断点（当前仅有 `xs/sm/md/lg`，确认覆盖 768-1024px）
|
||||
|
||||
## 6. 学生管理（Students）— 含字段拆分
|
||||
|
||||
- [x] 6.1 将「学号/身份证」列拆分为「学号」和「身份证」两个独立列
|
||||
- [x] 6.2 新分列添加 `ellipsis: true` 和 `width` 防止长文本溢出
|
||||
- [x] 6.3 表格添加 `scroll={{ x }}` 确保移动端横向滚动
|
||||
- [x] 6.4 顶部工具栏添加 `flexWrap: 'wrap'` 和 `gap`（搜索栏 + 按钮组）
|
||||
|
||||
## 7. 宿舍管理（Rooms）
|
||||
|
||||
- [x] 7.1 表格添加 `scroll={{ x }}`，操作列设置 `width`
|
||||
- [x] 7.2 顶部搜索/筛选 + 操作按钮工具栏 wrap 优化
|
||||
|
||||
## 8. 入住管理（Occupancies）
|
||||
|
||||
- [x] 8.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 8.2 顶部 Alert + Tab 切换区 + 搜索/操作区在小屏堆叠
|
||||
- [x] 8.3 弹窗（入住/退宿/换房/批量退宿）添加宽度约束
|
||||
|
||||
## 9. 费用录入（Expenses）
|
||||
|
||||
- [x] 9.1 宿舍费用和个人附加费两个 Tab 下的表格均添加 `scroll={{ x }}`
|
||||
- [x] 9.2 各 Tab 顶部搜索/筛选/按钮工具栏 wrap 优化
|
||||
- [x] 9.3 弹窗宽度约束
|
||||
|
||||
## 10. 押金管理（Deposits）
|
||||
|
||||
- [x] 10.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 10.2 搜索/筛选工具栏 wrap 优化
|
||||
- [x] 10.3 收取押金/退还弹窗宽度约束
|
||||
|
||||
## 11. 账单管理（Bills）
|
||||
|
||||
- [x] 11.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 11.2 搜索/筛选/按钮工具栏 wrap 优化
|
||||
- [x] 11.3 生成账单和详情弹窗宽度约束
|
||||
|
||||
## 12. 教室管理（Classrooms）
|
||||
|
||||
- [x] 12.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 12.2 搜索/筛选工具栏 + 按钮组 wrap 优化
|
||||
- [x] 12.3 弹窗宽度约束
|
||||
|
||||
## 13. 租赁订单（ClassroomRentals）
|
||||
|
||||
- [x] 13.1 表格已有 `scroll={{ x: 1200 }}`，复查确保值合理
|
||||
- [x] 13.2 搜索/月份筛选 + 按钮工具栏 wrap 优化
|
||||
- [x] 13.3 弹窗宽度约束
|
||||
|
||||
## 14. 教室排期（ClassroomSchedule）
|
||||
|
||||
- [x] 14.1 HTML 排期表格已有 `overflowX: 'auto'`，确认 sticky 左列在平板/手机正常工作
|
||||
- [x] 14.2 日期列 `minWidth` 优化防止挤压
|
||||
- [x] 14.3 创建自定义 hook `useWindowSize` 确保图表/表格 resize 响应
|
||||
|
||||
## 15. 租赁方（Tenants）
|
||||
|
||||
- [x] 15.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 15.2 工具栏 wrap 优化
|
||||
|
||||
## 16. 操作日志（OperationLogs）
|
||||
|
||||
- [x] 16.1 表格已有 `scroll={{ x: 1000 }}`，复查确保合理
|
||||
- [x] 16.2 标题 + 筛选区 wrap 优化
|
||||
|
||||
## 17. 角色管理（Roles）
|
||||
|
||||
- [x] 17.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 17.2 工具栏 + 操作按钮 wrap 优化
|
||||
- [x] 17.3 弹窗（创建/编辑角色 + 权限选择器）宽度约束
|
||||
|
||||
## 18. 权限一览（Permissions）
|
||||
|
||||
- [x] 18.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 18.2 页面标题 + 筛选/操作区 wrap 优化
|
||||
|
||||
## 19. 账号管理（Users）
|
||||
|
||||
- [x] 19.1 表格添加 `scroll={{ x }}`
|
||||
- [x] 19.2 搜索/筛选工具栏 wrap 优化
|
||||
- [x] 19.3 创建/编辑账号弹窗宽度约束
|
||||
|
||||
## 20. 全局验证
|
||||
|
||||
<!-- review skipped: off — 纯 UI/CSS props 改动，无业务逻辑变更，无安全风险 -->
|
||||
|
||||
- [x] 20.1 在所有 16 个页面中，分别用 375px / 768px / 1024px / 1440px 视口宽度检查无溢出（代码适配已完成，视觉验证在 verify 阶段执行）
|
||||
- [x] 20.2 检查所有 Modal 弹窗在三端视口下不超出屏幕（CSS 约束已全局添加）
|
||||
- [x] 20.3 确保 `npm run build` 通过，无 TypeScript 错误
|
||||
Reference in New Issue
Block a user