diff --git "a/docs/\345\211\215\347\253\257\345\210\206\345\267\245\345\225\206\351\207\217\344\271\246.md" "b/docs/\345\211\215\347\253\257\345\210\206\345\267\245\345\225\206\351\207\217\344\271\246.md" new file mode 100644 index 0000000..62a0c83 --- /dev/null +++ "b/docs/\345\211\215\347\253\257\345\210\206\345\267\245\345\225\206\351\207\217\344\271\246.md" @@ -0,0 +1,452 @@ +# 图书馆智能管理系统 — Android 前端分工商量书 + +> **版本**: v1.0 +> **日期**: 2026-06-15 +> **目标**: 两人协作完成 Android 前端全部开发工作 +> **项目当前状态**: 框架已搭建(Gradle 构建、依赖就位、底部导航骨架、3 个 Fragment 桩代码),业务代码待实现 + +--- + +## 目录 + +1. [工作概览与总量统计](#1-工作概览与总量统计) +2. [分工原则](#2-分工原则) +3. [人员 A:基础架构 + 图书检索 + 个人中心](#3-人员-a基础架构--图书检索--个人中心) +4. [人员 B:借阅管理 + 预约管理 + 知识图谱 + 后台管理](#4-人员-b借阅管理--预约管理--知识图谱--后台管理) +5. [协作约定](#5-协作约定) +6. [里程碑与交付节奏](#6-里程碑与交付节奏) + +--- + +## 1. 工作概览与总量统计 + +### 1.1 数据来源 + +前端工作量估算基于以下两份已锁定文档: + +- **[library-api.yaml](api/library-api.yaml)** — OpenAPI 3.0 契约,定义 30+ 个 REST 接口 +- **[系统架构设计文档.md](系统架构设计文档.md)** — §3.2.2 前端技术栈 + §3.3.2 Android 目标目录结构 + +### 1.2 功能模块全景 + +``` +┌──────────────────────────────────────────────────────────────┐ +│ Android 前端功能模块 │ +├────────────┬────────────┬────────────┬────────────┬──────────┤ +│ 认证模块 │ 图书检索 │ 借阅管理 │ 预约管理 │ 个人中心 │ +│ (4 接口) │ (8 接口) │ (6 接口) │ (4 接口) │ (5 接口) │ +├────────────┼────────────┼────────────┼────────────┼──────────┤ +│ 知识图谱 │ 智能采编 │ 系统管理 │ 分类管理 │ 公共层 │ +│ (4 接口) │ (5 接口) │ (5 接口) │ (3 接口) │ (横切) │ +└────────────┴────────────┴────────────┴────────────┴──────────┘ +``` + +**合计约 44 个 API 端点**,对应约 **12-15 个主要界面**。 + +### 1.3 工作量估算 + +| 层次 | 工作内容 | 估算人天 | +|------|----------|----------| +| **公共基础设施** | model 包(VO/DTO 模型类)、network 包(Retrofit 接口 + OkHttp 拦截器)、di 包(Hilt Module)、repository 基类、工具类 | 3-4 天 | +| **认证模块** | 登录/注册/Token 刷新/登出 UI + ViewModel | 2 天 | +| **图书检索** | 搜索页(关键词+高级+自动补全)、图书详情页、热门榜、分类树浏览、条码扫描 | 5-6 天 | +| **借阅管理** | 借书/还书/续借、我的借阅列表(状态筛选)、借阅详情、超期管理 | 4-5 天 | +| **预约管理** | 预约/取消预约、预约列表、排队位置查询 | 2-3 天 | +| **个人中心** | 个人信息查看/编辑、借阅历史(年份筛选)、借阅统计图表(MPAndroidChart)、个性化推荐列表 | 4-5 天 | +| **知识图谱** | 图书知识图谱可视化(WebView+ECharts 或 Canvas 绘制)、文献溯源、学科网络、实体搜索 | 5-6 天 | +| **智能采编** | 采购预测图表、查重结果展示、缺口分析、谈判记录与建议 | 4-5 天 | +| **系统管理** | 用户列表(角色/状态筛选)、用户状态变更、图书编目 CRUD | 3-4 天 | +| **联调与适配** | 真机适配、异常状态处理、Loading/Empty/Error 态统一 | 3 天 | + +> 以上为乐观估算(两人并行),实际可按接口优先级动态调整。 + +--- + +## 2. 分工原则 + +1. **先公共,后业务** — 第一周两人合力完成公共层(model / network / di / util / repository 基类),消除阻塞。 +2. **按业务域垂直切分** — 每人独立负责完整业务栈(UI → ViewModel → Repository → API 调用),减少交叉等待。 +3. **接口先行** — Retrofit API 接口定义文件由两人按分工各自编写但 style 统一,合并前交叉 Review。 +4. **高内聚低耦合** — 各人负责的 Fragment / ViewModel 独立,仅共享公共层。 + +--- + +## 3. 人员 A:基础架构 + 图书检索 + 个人中心 + +> **角色定位**:偏"读者体验"方向 —— 负责用户从打开 App 到找到书、看到推荐、管理个人数据的主链路。 + +### 3.1 公共基础设施(与人员 B 协作完成) + +| 子任务 | 说明 | 产出物 | +|--------|------|--------| +| **数据模型类** | 根据 OpenAPI schemas 建立全部 VO/DTO 类(BookVO, UserProfile, BorrowRecordVO, PageResult 等) | `model/` 包下全部类 | +| **网络层** | Retrofit `LibraryApi` 接口全量定义(分工编写,统一 Review);OkHttp 拦截器(Auth 拦截器自动附加 Token、Logging 拦截器、Token 过期自动刷新) | `network/LibraryApi.java`、`network/interceptor/` | +| **Hilt DI 模块** | NetworkModule(Retrofit/OkHttp 实例)、DatabaseModule(Room 实例)、RepositoryModule | `di/` 包 | +| **统一 UI 组件** | Loading/Empty/Error 状态控件、通用 RecyclerView Adapter 基类、分页加载基类 | `ui/common/` | +| **导航图扩展** | 在现有 3 个 Fragment 基础上补充全部目的地的 `nav_graph.xml` | `res/navigation/nav_graph.xml` | + +> 其中 **数据模型类和导航图** 由人员 A 主导编写,人员 B 参与 Review;**Retrofit 接口**按模块分工各写各的;**拦截器 + DI + 通用组件** 两人一人一半或由 A 主导。 + +### 3.2 图书检索模块(8 个 API 端点) + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `GET /books/search` | 关键词搜索(含分类/作者/排序筛选) | SearchFragment 主搜索页 | +| `GET /books/search/advanced` | 高级组合搜索(标题/ISBN/出版社/年份/可借) | 高级搜索底部弹窗或独立页面 | +| `GET /books/suggest` | 搜索输入自动补全 | 搜索框下拉建议 | +| `GET /books/hot` | 热门图书榜(可按分类筛选) | 热门榜页面 / 首页推荐区 | +| `GET /books/{id}` | 图书详情(含关键词、预约人数) | BookDetailActivity/Fragment | +| `GET /books/{id}/related` | 相关图书推荐(知识图谱关联) | 图书详情页"相关推荐"区域 | +| `GET /categories/tree` | 分类树(多级嵌套) | 分类浏览页(可展开/折叠的树形列表) | +| `GET /categories` | 分类平铺列表 | 搜索筛选器中的分类下拉 | + +**核心界面清单**: + +1. **SearchFragment(重写)** — 搜索首页 + - 顶部搜索栏 + 自动补全下拉(`/books/suggest`) + - 热门搜索词标签云 + - 热门图书横向滚动卡片(`/books/hot`) + - 分类快捷入口(`/categories/tree` 一级节点) + - 搜索结果列表(分页加载,`/books/search`) + +2. **AdvancedSearchSheet** — 高级搜索 + - 多字段表单(标题、作者、ISBN、出版社、年份范围、仅可借开关) + - 调用 `/books/search/advanced` + +3. **BookDetailActivity** — 图书详情 + - 封面 + 基本信息(ISBN/作者/出版社/出版日期/馆藏位置) + - 可借册数 / 总册数 + 当前预约人数 + - 借阅按钮(调用借阅接口)→ 跳转借阅确认 + - 预约按钮(库存为 0 时显示) + - 关键词标签 + - 相关图书推荐列表(`/books/{id}/related`) + +4. **CategoryTreeFragment** — 分类浏览 + - 可展开/折叠的树形列表(`/categories/tree`) + - 点击分类跳转到该分类下的搜索结果 + +5. **HotBooksFragment** — 热门排行 + - 排行榜列表(编号 1-50) + - 分类筛选下拉 + +### 3.3 个人中心模块(5 个 API 端点) + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `GET /users/me` | 个人信息 | 个人中心首页 | +| `PUT /users/me` | 更新个人信息 | 编辑资料页 | +| `GET /users/me/history` | 借阅历史(支持年份筛选) | 借阅历史列表 | +| `GET /users/me/stats` | 借阅统计(总数/分类分布/月度趋势) | 统计图表页 | +| `GET /users/me/recommendations` | 个性化推荐(混合推荐+理由) | 推荐图书列表 | + +**核心界面清单**: + +1. **ProfileFragment(重写)** — 个人中心首页 + - 头像 + 用户名 + 角色标签 + - 借阅数据概览卡片(当前借阅数 / 历史总数 / 超期次数) + - 快捷入口:借阅历史 → 借阅统计 → 个性化推荐 → 编辑资料 + - 设置区:修改密码、关于、退出登录 + +2. **EditProfileFragment** — 编辑资料 + - 表单(邮箱、手机号) + - 调用 `PUT /users/me` + +3. **BorrowHistoryFragment** — 借阅历史 + - 按年份筛选的下拉或 Tab + - 分页列表(`/users/me/history`) + - 每条记录显示:书名、借阅日期、归还日期、状态标签 + +4. **BorrowStatsFragment** — 借阅统计 + - 使用 MPAndroidChart: + - 饼图:分类分布(`categoryDistribution`) + - 折线图:月度趋势(`monthlyTrend`) + - 数字卡片:总借阅数 / 当前借阅 / 超期次数 / 罚款总额 + +5. **RecommendationsFragment** — 个性化推荐 + - 推荐图书列表(书名 + 封面 + 推荐分数 + 推荐理由) + - 支持下拉刷新 + +### 3.4 认证模块(人员 A 主导,人员 B 配合) + +> 认证是 App 入口,建议人员 A 主导 —— 因为登录后的路由跳转与个人中心紧密关联。 + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `POST /auth/login` | 用户登录 | LoginActivity | +| `POST /auth/register` | 用户注册 | RegisterActivity | +| `POST /auth/refresh` | 刷新 Token | 拦截器自动处理 | +| `POST /auth/logout` | 登出 | 设置页按钮触发 | + +**产出物**: +- `LoginActivity` + `RegisterActivity` +- Token 管理(SharedPreferences 存储 + OkHttp 拦截器自动附加 + 过期自动刷新) +- 登录状态判断(未登录→跳转登录页,已登录→进入 MainActivity) + +--- + +## 4. 人员 B:借阅管理 + 预约管理 + 知识图谱 + 后台管理 + +> **角色定位**:偏"业务操作 + 高级功能"方向 —— 负责借还书核心流程、预约排队、知识图谱可视化、管理员功能。 + +### 4.1 借阅管理模块(6 个 API 端点) + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `POST /borrows` | 借书申请 | 借阅确认弹窗/页面 | +| `GET /borrows/my` | 我的借阅列表(按状态筛选) | BorrowFragment 主页面 | +| `GET /borrows/{id}` | 借阅详情 | 借阅详情页 | +| `PUT /borrows/{id}/return` | 归还图书 | 借阅详情页按钮 | +| `PUT /borrows/{id}/renew` | 续借 | 借阅详情页按钮 | +| `GET /borrows/overdue` | 超期未还记录(管理员) | 超期管理页 | + +**核心界面清单**: + +1. **BorrowFragment(重写)** — 借阅管理首页 + - Tab 切换:全部 / 借阅中 / 已归还 / 已超期(对应 `status` 枚举) + - 借阅记录列表(分页),每条显示:书名、借阅日期、应还日期、状态标签 + - 列表项点击进入借阅详情 + - FAB 或扫码按钮触发借书(调用相机扫码 ISBN → 搜索 → 确认借阅) + +2. **BorrowDetailFragment** — 借阅详情 + - 图书信息(封面 + 书名 + 作者) + - 借阅日期 / 应还日期 / 实际归还日期 + - 续借次数(最多 1 次)+ 续借按钮 + - 归还按钮 + - 罚款信息(如有超期) + +3. **BorrowConfirmDialog** — 借阅确认 + - 展示图书摘要信息 + - 最大借阅数提示 + - 确认借阅按钮 + +4. **OverdueFragment** — 超期管理(管理员可见) + - 超期未还列表(分页) + - 管理员可查看所有用户的超期记录 + +### 4.2 预约管理模块(4 个 API 端点) + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `POST /reservations` | 预约图书 | 图书详情页按钮触发 | +| `GET /reservations/my` | 我的预约列表 | 预约列表页 | +| `DELETE /reservations/{id}` | 取消预约 | 列表项滑动/长按删除 | +| `GET /reservations/{id}/queue-position` | 查询排队位置 | 预约详情/列表刷新 | + +**核心界面清单**: + +1. **ReservationListFragment** — 我的预约 + - 状态筛选:等待中 / 已通知 / 已锁定 / 已完成 / 已取消 + - 每条显示:书名、预约时间、排队序号、状态标签 + - 下拉刷新排队位置 + - 左滑取消预约 + +2. **ReservationStatusCard** — 预约状态组件(可嵌入图书详情页) + - 显示当前排队位置 / 总等待人数 + - 已通知时显示倒计时(48h) + - 取消预约按钮 + +### 4.3 知识图谱模块(4 个 API 端点) + +> 这是前端最有挑战性的模块 —— 知识图谱数据需要可视化渲染。 + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `GET /kg/book/{id}/graph` | 图书知识图谱(主题关联网络,1-2 跳) | 力导向图可视化 | +| `GET /kg/book/{id}/trace` | 文献溯源(引用链,方向+深度参数) | 溯源路径图 | +| `GET /kg/subject/{name}` | 学科主题网络(含 PageRank 中心度) | 学科网络图 | +| `GET /kg/search` | 知识实体搜索 | 图谱实体搜索页 | + +**核心界面清单**: + +1. **KnowledgeGraphFragment** — 知识图谱可视化 + - 采用 **WebView + ECharts**(推荐)或 **自定义 Canvas 绘制**(备选) + - 力导向图渲染节点(作者/图书/关键词/学科)和边(引用/属于/关联) + - 节点大小按 PageRank 中心度缩放 + - 边粗细按权重缩放 + - 支持手势缩放与拖拽 + - 点击节点跳转对应详情 + - 深度参数调节(1-3 跳) + +2. **LiteratureTraceFragment** — 文献溯源 + - 有向图渲染引用链(前向/后向/双向) + - 最大跳数可调(1-5 跳) + - 路径高亮与权重标注 + +3. **SubjectNetworkFragment** — 学科主题网络 + - 学科关键词关联网络 + - Top-K 调节(50-200 节点) + +4. **EntitySearchFragment** — 知识实体搜索 + - 搜索框 + 实体类型筛选(图书/作者/关键词/学科) + - 结果列表(含 PageRank 中心度) + +### 4.4 系统管理模块(5 个 API 端点) + +> 需管理员权限(Admin 角色),UI 需做权限判断隐藏/显示。 + +对应后端 API: + +| API 端点 | 说明 | 界面 | +|----------|------|------| +| `GET /admin/users` | 用户列表(分页+角色/状态/关键词筛选) | 用户管理页 | +| `PUT /admin/users/{id}/status` | 变更用户状态(冻结/解冻/禁用) | 用户详情操作 | +| `POST /admin/books` | 新增图书(编目) | 图书编目表单 | +| `PUT /admin/books/{id}` | 修改图书信息 | 图书编辑表单 | +| `DELETE /admin/books/{id}` | 删除图书 | 确认对话框 | + +**核心界面清单**: + +1. **AdminUserListFragment** — 用户管理 + - 搜索栏 + 角色下拉筛选 + 状态下拉筛选 + - 分页列表:用户名、姓名、角色、状态、当前借阅数、超期次数 + - 点击用户 → 底部操作弹窗(冻结/解冻/禁用) + +2. **BookEditActivity** — 图书编目(新增/修改) + - 完整表单:ISBN、书名、作者、出版社、出版日期、分类下拉、总册数、馆藏位置、关键词 + - 表单验证(必填项、ISBN 格式等) + +### 4.5 条码扫描(与借阅关联) + +- 集成 `ZXing` 库实现 ISBN 条码扫描 +- 扫描结果 → 自动调用图书搜索 → 展示搜索结果 +- 可复用于:借书入口、图书编目入口 + +### 4.6 智能采编模块(可选,按时间决定) + +> 优先级较低,若进度允许则实现。 + +对应后端 API:`GET /acquisition/predict`、`POST /acquisition/duplicate-check`、`GET /acquisition/gap-analysis`、`POST /acquisition/negotiation`、`GET /acquisition/negotiation/{id}/suggestion` + +**界面清单**(仅列核心): + +1. **PredictionChartFragment** — 采购预测图表 +2. **DuplicateCheckFragment** — 查重结果展示 +3. **GapAnalysisFragment** — 缺口分析 +4. **NegotiationFragment** — 谈判建议/记录 + +--- + +## 5. 协作约定 + +### 5.1 代码规范 + +| 规范项 | 约定 | +|--------|------| +| **命名** | Java 驼峰:类 `UpperCamelCase`,方法/变量 `lowerCamelCase`,常量 `UPPER_SNAKE_CASE` | +| **包结构** | 严格遵循架构文档 §3.3.2 的目标目录结构 | +| **资源命名** | `snake_case`:`activity_book_detail.xml`,`ic_book_placeholder.xml` | +| **注释语言** | Javadoc 中文,关键逻辑英文注释 | +| **字符串** | 用户可见文本统一在 `strings.xml` 定义,禁止硬编码 | + +### 5.2 Git 协作流程 + +``` +main + ├── feature/frontend-common # 公共基础设施(第一周,两人共同) + ├── feature/frontend-search # 人员 A:搜索 + 个人中心 + 认证 + ├── feature/frontend-borrow # 人员 B:借阅 + 预约 + 图谱 + 管理 + └── feature/frontend-integration # 集成联调 + bugfix +``` + +- **每日同步**:至少一次 `git pull --rebase origin main` +- **提交粒度**:每个独立界面或功能点一次 commit +- **Commit 规范**:`feat(android): 实现图书搜索页关键词搜索与分页`(Conventional Commits) +- **合并前**:交叉 Code Review(A 的 PR B 来审,B 的 PR A 来审) + +### 5.3 接口层协调 + +Retrofit API 接口统一定义在 `network/LibraryApi.java`: + +```java +public interface LibraryApi { + // =========== 人员 A 负责的接口区域 =========== + // 认证、图书检索、分类、个人中心 + + // =========== 人员 B 负责的接口区域 =========== + // 借阅、预约、知识图谱、系统管理、采编 +} +``` + +> 两人按分工往同一个接口文件中追加方法,用注释分隔区域。合并冲突时沟通解决。 + +### 5.4 依赖关系与解耦 + +``` +人员 A 的 Fragment / ViewModel ──→ Repository ──→ LibraryApi (共享) + │ +人员 B 的 Fragment / ViewModel ──→ Repository ──→ LibraryApi (共享) +``` + +- ViewModel 不直接持有 Fragment 引用(使用 LiveData / RxJava Observable 驱动 UI) +- Repository 是唯一的数据入口,内部封装网络请求 + 本地缓存降级 + 错误处理 +- 两人各自的 Fragment 之间不直接跳转,统一通过 NavController + SafeArgs 传参 + +### 5.5 公共资源分配 + +| 公共资源 | 负责人 | 完成时间 | +|----------|--------|----------| +| `model/` 全部 VO/DTO 类 | A(主导) + B(Review) | 第一周 | +| `network/LibraryApi.java` | 按模块分工,各自追加 | 第一周 | +| `network/interceptor/AuthInterceptor.java` | A | 第一周 | +| `di/NetworkModule.java` | A | 第一周 | +| `di/DatabaseModule.java` | B | 第一周 | +| `ui/common/` 通用组件 | A(Loading/Empty/Error)+ B(BaseAdapter) | 第一周 | +| `nav_graph.xml` | A(主导) + B(补充) | 第一周 | +| `strings.xml` / `colors.xml` | 各自添加自己模块需要的 | 持续 | + +--- + +## 6. 里程碑与交付节奏 + +### 第一周:公共基础 + 认证 + +| 时间 | 人员 A | 人员 B | +|------|--------|--------| +| Day 1-2 | 全部 VO/DTO 模型类编写、AuthInterceptor | Room 数据库(本地缓存表)、DatabaseModule、BaseAdapter | +| Day 3-4 | LoginActivity / RegisterActivity + Token 管理 | SearchFragment 框架(搜索栏 + RecyclerView + 分页) | +| Day 5 | NetworkModule + RepositoryModule DI 配置 | BorrowFragment 框架 | + +**交付物**:App 可编译运行、可登录跳转主页、搜索/借阅/个人中心 Tab 可切换(内容可以为空态) + +### 第二周:核心业务 + +| 时间 | 人员 A(搜索 + 分类) | 人员 B(借阅 + 预约) | +|------|----------------------|----------------------| +| Day 1-2 | SearchFragment 完整实现(关键词搜索+自动补全+分页) | BorrowFragment 完整实现(借阅列表+状态Tab+分页) | +| Day 3-4 | BookDetailActivity + 分类树浏览 | 借阅详情 + 归还/续借操作 + 借阅确认 | +| Day 5 | 高级搜索 + 热门榜 | 预约列表 + 预约/取消 + 排队位置 | + +### 第三周:个人中心 + 知识图谱 + +| 时间 | 人员 A(个人中心) | 人员 B(知识图谱) | +|------|-------------------|-------------------| +| Day 1-2 | ProfileFragment 完整实现 + 编辑资料 | WebView + ECharts 环境搭建 + 图谱数据模型适配 | +| Day 3-4 | 借阅历史 + 借阅统计图表(MPAndroidChart) | 知识图谱力导向图渲染 + 交互(缩放/拖拽/点击) | +| Day 5 | 个性化推荐列表 | 文献溯源图 + 学科网络 + 实体搜索 | + +### 第四周:收尾 + 高级功能 + +| 时间 | 人员 A | 人员 B | +|------|--------|--------| +| Day 1-2 | 条码扫描集成(ZXing)、UI 打磨 | 系统管理模块(用户管理 + 图书编目) | +| Day 3-4 | 全链路联调、边界情况处理(网络异常/空数据/Token 过期) | 全链路联调、权限判断(管理员入口显隐) | +| Day 5 | Bugfix + Code Review | 智能采编(若进度允许)/ Bugfix | + +--- + +> **总结**:两人分工覆盖全部 44 个 API 端点,约 12-15 个核心界面。人员 A 侧重"读者主链路"(搜索 → 详情 → 个人中心),人员 B 侧重"业务核心流"(借还书 → 预约排队 → 知识图谱 → 管理后台)。公共层协作完成,业务层各自独立,通过统一的 `LibraryApi` 接口和 Repository 层解耦。 +> +> **风险提示**: +> 1. 知识图谱可视化为技术难点,建议提前验证 WebView + ECharts 方案的可行性 +> 2. 智能采编和系统管理模块按优先级可裁减,若时间紧张可延后到 v1.1 +> 3. 真机适配(不同屏幕尺寸、权限申请)至少预留 1 天