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
|
||||
Reference in New Issue
Block a user