# 字词学习平台 - 产品需求文档

## 1. 项目概述

### 1.1 项目背景
为 Doodle 小程序提供字词学习数据支撑，包括汉字、词语、英语单词和字母的完整学习资源管理。

### 1.2 项目目标
- 建立完整的字词学习资源库
- 提供高效的后台管理系统
- 支持多维度数据关联和查询
- 实现图片标准化处理流程

## 2. 核心功能需求

### 2.1 字词数据管理

#### 2.1.1 基础信息
- **字词内容**：汉字、词语、英语单词、英语字母
- **类型标识**：汉字、词语、英语单词、英语字母
- **年级信息**：根据人教版语文书判断学习年级（1-9年级）
- **拼音信息**：支持多个拼音（多音字场景）
- **读音信息**：音频文件或读音标注

#### 2.1.2 SVG 笔画数据
- 存储 SVG 格式的笔画数据
- 支持编辑和修改 SVG 配置
- 用于小程序中的笔画展示和练习

#### 2.1.3 图片资源
- **多图支持**：一个字词可以关联多张图片
- **图片类型**：
  - 原图：用户上传的原始图片
  - 标准图：经过标准化处理的图片（背景半透明、统一像素大小）
- **图片用途**：示例图、练习图、卡片图等

#### 2.1.4 关联关系
- **字词关联**：
  - 一个字可以关联多个常用组词
  - 一个词可以关联多个组成字
- **句子关联**：一个字词可以关联多条例句

### 2.2 后台管理功能

#### 2.2.1 汉字管理（第一阶段）

**2.2.1.1 汉字卡片列表**
- **展示形式**：卡片列表形式展示汉字
- **分页规则**：
  - 每页展示 9 个卡片
  - 每次请求返回一页数据（9 个汉字）
  - 支持分页导航
- **搜索功能**：
  - 仅支持汉字内容搜索
  - 实时搜索，支持模糊匹配
- **排序规则**：
  - 按年级排序：低年级排在前面，高年级排在后面
  - 年级相同时按创建时间排序
- **卡片内容**：
  - **左上角**：汉字内容（大号字体）
  - **右上角上方**：拼音信息（多音字用 "|" 分割，如：zhōng|zhòng）
  - **右上角下方**：SVG 笔画标识
    - 有 SVG 数据：显示绿色标识
    - 无 SVG 数据：显示灰色标识
  - **下方**：关联图片（仅展示第一张图片，如果有多张图片）

**2.2.1.2 汉字详情弹窗**
- **触发方式**：点击卡片后，右侧滑出 Popup 弹窗
- **弹窗布局**：
  - **第一行**：
    - **左侧**：田字格 + Canvas 渲染
      - 有 SVG 数据：使用 Canvas 渲染笔画，颜色为黑色
      - 无 SVG 数据：在田字格中直接展示文字，颜色为灰色
    - **右侧上方**：拼音信息（多音字用 "|" 分割）
    - **右侧下方**：按笔画顺序展示多个小田字格和笔画
  - **第二行**：汉字对应的图片
    - 最多支持上传 4 张图片
    - 支持图片预览、删除、排序
  - **第三行**：汉字对应的多个词语
    - 展示关联的词语列表
    - 支持添加、删除、编辑词语
  - **第四行**：汉字对应的多个句子
    - 展示关联的句子列表
    - 支持添加、删除、编辑句子

**2.2.1.3 编辑功能**
- **查看模式**：默认模式，仅展示数据，不可编辑
- **编辑模式**：
  - 点击编辑按钮进入编辑模式
  - 汉字、拼音、SVG 数据不可编辑（通过其他方式导入）
  - 图片可编辑：支持上传、删除、排序（最多 4 张）
  - 词语可编辑：支持添加、删除、编辑
  - 句子可编辑：支持添加、删除、编辑
- **无新建功能**：汉字、拼音、SVG 数据通过其他方式导入，不支持在后台新建

#### 2.2.2 字词列表管理（后续功能）
- **列表视图**：表格形式展示字词列表
- **卡片视图**：卡片形式分页展示
- **分页功能**：支持分页浏览
- **筛选功能**：
  - 按类型筛选（汉字/词语/英语单词/英语字母）
  - 按年级筛选
  - 按拼音筛选
  - 关键词搜索

#### 2.2.3 字词编辑功能（后续功能）
- **基础信息编辑**：
  - 字词内容
  - 类型选择
  - 年级设置
  - 拼音添加/删除
  - 读音上传/编辑
- **SVG 配置编辑**：
  - 上传/编辑 SVG 笔画数据
  - SVG 预览功能
- **图片管理**：
  - 上传多张图片
  - 图片预览
  - 删除图片
  - 设置主图
- **关联管理**：
  - 添加/删除关联词语
  - 添加/删除关联句子
  - 关联关系可视化展示

#### 2.2.4 词语查询功能（后续功能）
- 独立的词语列表页面
- 支持词语搜索和筛选
- 查看词语关联的字和句子

### 2.3 图片处理功能

#### 2.3.1 图片标准化处理
- **背景处理**：将白色背景变为半透明
- **尺寸统一**：统一像素大小（默认 300x300）
- **格式转换**：统一输出为 PNG 格式
- **水印去除**：自动检测并去除底部水印

#### 2.3.2 图片存储策略
- **原图保存**：保留用户上传的原始图片
- **标准图生成**：自动生成标准化处理后的图片
- **存储路径管理**：清晰的目录结构

### 2.4 用户权限管理

#### 2.4.1 用户角色
- **超级管理员**：
  - 所有数据管理权限
  - 用户管理权限（添加/删除管理员）
  - 系统配置权限
- **一般管理员**：
  - 字词数据管理权限
  - 图片上传和编辑权限
  - 无用户管理权限

#### 2.4.2 权限控制
- 基于角色的访问控制（RBAC）
- 操作日志记录
- 数据修改审核（可选）

## 3. 非功能需求

### 3.1 性能要求
- 列表查询响应时间 < 500ms
- 图片上传处理时间 < 5s
- 支持并发用户数 > 50

### 3.2 数据要求
- 数据完整性：保证关联关系的一致性
- 数据准确性：年级信息需准确对应人教版教材
- 数据可扩展性：支持后续功能扩展

### 3.3 安全要求
- 用户认证和授权
- 数据操作审计
- 图片上传安全校验

## 4. 技术约束

### 4.1 后端技术
- NestJS 框架
- RESTful API

### 4.2 前端技术
- React 框架
- 响应式设计

### 4.3 图片处理
- Node.js + Jimp 库
- 支持批量处理

## 5. 后续扩展需求

### 5.1 数据导入导出
- 批量导入字词数据
- 数据导出功能

### 5.2 统计分析
- 字词使用统计
- 图片使用统计
- 用户操作统计

### 5.3 API 接口
- 为小程序提供数据接口
- 支持分页、筛选、搜索