teapot_system/铜壶管理系统开发任务计划书.md

# 铜壶管理系统开发任务计划书

## 1. 计划目标
本计划书用于指导铜壶管理系统从文档阶段进入实施阶段，目标是在前后端分离架构下，完成多用户登录、权限控制、商品目录、商品详情、订单管理、标签导出、统计分析等核心模块开发，并满足“图片存数据库”的明确要求。

本计划默认采用以下实施前提：
1. 前端与后端独立开发、独立部署。
2. 商品图片与标签模板通过统一附件能力管理，其中图片必须保存到 SQLite 数据库。
3. 本计划不包含 Git 分支管理流程，交付以源码包、数据库脚本、部署文档为准。
4. 系统仅设置两类用户：管理员与普通用户；管理员拥有全量权限，普通用户权限由管理员创建和分配。

---

## 2. 交付范围
本次交付建议至少包含以下内容：
* 前端管理端项目一套
* 后端 API 服务项目一套
* SQLite 建表与初始化脚本一套
* 登录认证与用户权限管理能力
* 附件上传、读取、下载与标签导出能力
* 部署说明、初始化说明、验收清单

不在本次优先范围内的内容：
* 小程序或移动 App
* 多租户能力
* 复杂组织架构、部门审批、数据域级权限中心
* 自动化 CI/CD 流程

---

## 3. 推荐项目结构
建议后续源码按以下目录拆分：

```text
teapot_system/
  docs/
  frontend/
  backend/
  sql/
  deploy/
```

说明：
* `frontend`：前端管理端源码
* `backend`：后端 API 服务源码
* `sql`：建表脚本、初始化数据、升级脚本
* `deploy`：部署说明、环境变量模板、打包说明

---

## 4. 工期与人员建议
建议投入方式如下：
* **标准配置**：1 名前端 + 1 名后端 + 1 名兼职测试/业务验收
* **并行开发周期**：约 5 至 7 周
* **单人开发周期**：约 8 至 10 周

如需更快交付，可优先上线“登录权限 + 商品管理 + 订单管理 + 标签下载”主链路，统计功能作为第二阶段补充。

---

## 5. 阶段计划

| 阶段 | 预计工期 | 主要目标 | 前端任务 | 后端任务 | 产出物 | 验收重点 |
| --- | --- | --- | --- | --- | --- | --- |
| 阶段 1：需求冻结与原型细化 | 2 天 | 固化业务规则和页面流转 | 确认页面清单、字段清单、路由结构 | 确认接口域、状态流转、数据实体 | 最终设计文档、页面草图、字段清单 | 需求边界明确，无冲突点 |
| 阶段 2：架构与数据库设计 | 2-3 天 | 明确前后端边界与 SQLite 表结构 | 规划页面布局、接口调用层、状态管理结构、权限展示规则 | 设计数据库、接口规范、统一返回结构 | ER 图、接口清单、SQLite 脚本初版 | 表结构可覆盖用户、商品、订单、图片入库需求 |
| 阶段 3：基础工程搭建 | 2 天 | 搭好可运行项目骨架 | 初始化 Vue 项目、路由、Pinia、请求封装、基础布局 | 初始化 Spring Boot 项目、SQLite 连接、统一异常处理、参数校验、接口骨架 | 前后端可运行空壳工程 | 前后端基础访问联通 |
| 阶段 4：登录与权限 | 3-4 天 | 完成登录、鉴权和用户管理基础能力 | 开发登录页、登录态保持、路由守卫、权限菜单、用户管理页 | 完成登录认证、密码加密、接口鉴权、用户 CRUD、权限分配接口 | 登录页、用户管理页、认证接口 | 管理员和普通用户权限差异生效 |
| 阶段 5：类目与商品列表 | 4-5 天 | 完成目录树与款式墙主流程 | 开发左侧目录树、商品卡片墙、筛选条件、快捷加购入口 | 完成类目 CRUD、商品列表、商品 CRUD 接口 | 目录页和商品列表页 | 目录切换、卡片加载、商品新增编辑正常 |
| 阶段 6：商品详情与图片入库 | 4-5 天 | 完成商品详情编辑与附件入库 | 开发商品详情页、图片上传组件、标签文件上传组件、多图排序、只读态展示 | 完成附件上传入库、缩略图生成、原图下载、标签文件管理接口 | 商品详情页、附件表、附件接口 | 图片刷新后可读取，且确实保存在数据库 |
| 阶段 7：订单与标签导出 | 5-6 天 | 完成订单创建、编辑、完成、标签下载 | 开发订单列表页、订单详情页、数量编辑、完成按钮、快递单号录入、权限按钮控制 | 完成订单 CRUD、库存校验、完成流转、标签按量导出 | 订单模块主流程 | 未完成订单可编辑，已完成订单默认只读且管理员可删除，标签下载正确 |
| 阶段 8：统计分析 | 2-3 天 | 完成月度与年度统计 | 开发统计筛选页、表格与汇总展示 | 开发月度/年度统计聚合接口 | 统计页面 | 数量、单价、小计、总价计算准确 |
| 阶段 9：联调、测试与部署 | 3-4 天 | 修复问题并形成交付物 | 接口联调、页面细节修正、异常提示完善 | 性能优化、SQL 校验、导出测试、部署脚本整理 | 部署说明、验收清单、发布包 | 主流程稳定可用，可完成验收 |

建议预留 2 天缓冲时间，用于处理标签排版细节、数据修正或现场反馈调整。

---

## 6. 模块级任务拆解

### 6.1 前端任务清单
1. 搭建基础框架：路由、状态管理、请求封装、全局异常提示。
2. 开发登录页、退出登录、登录态保持和路由守卫。
3. 开发主布局：左侧树、顶部订单入口、当前用户信息、右侧内容区。
4. 开发菜单级、页面级、按钮级权限控制，根据当前用户动态显示入口与操作按钮。
5. 开发管理员用户管理页：用户新增、编辑、启停、密码重置、权限分配。
6. 开发类目树组件：树节点增删改、展开收起、点击跳转。
7. 开发商品卡片墙：卡片展示、状态标签、筛选、分页、快捷加购。
8. 开发商品详情页：基础表单、多图上传、主图设置、原图下载、标签文件上传、只读展示。
9. 开发订单列表页：全部/未完成/已完成切换、搜索筛选、删除操作、权限差异展示。
10. 开发订单详情页：订单明细、数量编辑、金额汇总、快递单号录入、标签下载。
11. 开发统计页面：月度统计、年度统计、筛选条件、汇总展示。
12. 完成接口联调、错误提示、空状态和加载状态处理。

### 6.2 后端任务清单
1. 初始化项目骨架：统一返回结构、异常处理、日志、参数校验。
2. 实现登录认证：用户名密码校验、密码哈希存储、登录令牌签发与退出。
3. 实现接口鉴权：基于管理员全量权限和普通用户权限编码控制 API 访问。
4. 实现用户管理：管理员新增普通用户、编辑用户、重置密码、启停账号、分配权限。
5. 设计并实现类目管理接口与商品管理接口。
6. 实现附件上传能力：接收图片、校验格式、生成缩略图、写入数据库。
7. 实现附件读取能力：缩略图预览、原图下载、标签模板下载。
8. 实现订单模块：创建订单、编辑订单、删除订单、订单完成。
9. 实现库存校验逻辑：下单不得超过库存，订单完成逻辑可选扣减库存或锁定库存。
10. 实现标签导出逻辑：根据订单明细和数量生成 PDF 或 ZIP。
11. 实现统计接口：月度与年度维度聚合统计。
12. 输出部署配置、SQLite 初始化脚本、测试数据脚本。

### 6.3 数据库任务清单
1. 设计用户、用户权限、类目、商品、附件、订单、订单明细、订单日志表。
2. 明确 SQLite 中图片 BLOB 字段、缩略图字段和索引策略。
3. 建立用户类型、账号状态、订单状态、商品状态、附件类型、权限编码等枚举规范。
4. 输出建表脚本与初始化脚本，并配置 WAL 模式与基础 pragma 策略。
5. 输出 SQLite 数据库文件备份策略，确保图片入库后可完整恢复。

### 6.4 测试任务清单
1. 测试登录、退出登录、未登录拦截、停用账号拦截。
2. 测试管理员创建普通用户、重置密码、分配权限是否生效。
3. 测试普通用户菜单显示、页面访问和接口访问是否与权限一致。
4. 测试目录新增、编辑、删除和跳转。
5. 测试商品新增、编辑、状态变更、库存修改。
6. 测试图片上传、刷新读取、原图下载、多图排序。
7. 测试标签模板上传与订单标签导出。
8. 测试订单创建、编辑、删除、完成、快递单号校验。
9. 测试月度与年度统计是否与订单明细一致。
10. 测试大图片上传、异常文件上传、库存不足下单、越权访问等边界场景。

---

## 7. 关键里程碑定义
1. **M1：基础架构完成**
   前后端空壳工程可运行，数据库脚本初版完成。
2. **M2：登录与权限完成**
   管理员和普通用户可登录，权限菜单、接口鉴权和用户管理能力可用。
3. **M3：商品管理主流程完成**
   可完成目录管理、商品列表和商品详情编辑。
4. **M4：图片入库完成**
   图片上传后写入数据库，前端可正常显示缩略图并下载原图。
5. **M5：订单链路完成**
   可创建订单、编辑未完成订单、填写快递单号后完成订单。
6. **M6：标签下载完成**
   可根据订单数量导出对应标签文件。
7. **M7：统计与验收完成**
   月度/年度统计上线，系统进入验收阶段。

---

## 8. 验收清单
1. 系统支持用户名密码登录、退出登录，未登录状态不能进入业务页面。
2. 管理员拥有全部查看和编辑权限，可进入用户管理页面。
3. 管理员可创建普通用户、重置密码、启停账号并分配权限。
4. 商品查看权限用户只能浏览商品列表与详情，不可编辑商品和上传附件。
5. 打包工权限用户可查看订单、填写快递单号并完成订单，但不可编辑商品和用户。
6. 左侧目录可维护，点击型号和产品节点的跳转行为正确。
7. 商品列表页能显示缩略图、状态、库存、价格，并支持快捷加购。
8. 商品详情页可以维护 SKU、价格、库存状态、库存数量。
9. 商品详情页支持上传多张图片，上传后图片保存于数据库而不是磁盘路径。
10. 订单列表可区分全部、未完成、已完成。
11. 未完成订单可以修改数量、删除商品、删除整单。
12. 填写快递单号后订单可完成，完成后普通用户不可编辑；管理员可删除已完成订单。
13. 订单详情页可下载对应数量的标签文件。
14. 统计页面可按月、按年查看款式数量、单价、小计和总价。
15. 数据库备份后可恢复图片与业务数据。

---

## 9. 风险与应对措施
1. **图片入库导致数据库体积增长过快**
   方案：附件表与业务表分离，列表接口不查 BLOB，建立定期备份与归档策略。
2. **标签导出排版复杂，容易反复调整**
   方案：优先确认固定标签模板，再进入导出开发阶段。
3. **SQLite 写并发能力有限**
   方案：采用单实例部署，启用 WAL 模式，订单创建与修改时增加事务校验并缩短写事务时间。
4. **仅做前端隐藏导致权限越权**
   方案：前后端双重校验权限，所有核心接口都做服务端鉴权。
5. **无 Git 流程时版本留痕不足**
   方案：按里程碑输出压缩包、数据库脚本编号和变更说明文档。

---

## 10. 交付与备份建议
由于本项目不采用 Git 流程，建议至少执行以下管理方式：
1. 每个里程碑打一个源码压缩包，例如 `teapot_system_m3_20260411.zip`。
2. 数据库脚本按版本号编号，例如 `V001__init.sql`、`V002__order_module.sql`。
3. 每次发布前保留 SQLite 数据库文件全量备份，并同时关注 WAL 或日志文件。
4. 发布包中同时包含部署说明、环境变量说明和初始化 SQL。

---

## 11. 实施顺序建议
如需尽快上线，建议按以下优先级实施：
1. 登录与权限
2. 左侧目录 + 商品卡片墙
3. 商品详情页 + 图片入库
4. 订单创建/编辑/完成
5. 标签按量下载
6. 统计分析

这样可以先打通登录权限、商品与订单主链路，再补统计和优化项。