From f2a1e2d6fe94c3af8ce960372c7de3e580ab4267 Mon Sep 17 00:00:00 2001 From: wsy182 <2392948297@qq.com> Date: Fri, 27 Feb 2026 11:02:50 +0800 Subject: [PATCH] docs: add redesigned requirements and project structure scaffold --- PROJECT_STRUCTURE.md | 88 +++++++++++++++++++++++++ REQUIREMENTS.md | 86 ++++++++++++++++++++++++ memora-api/cmd/server/.gitkeep | 0 memora-api/internal/domain/.gitkeep | 0 memora-api/internal/repository/.gitkeep | 0 memora-web/src/modules/auth/.gitkeep | 0 memora-web/src/modules/review/.gitkeep | 0 memora-web/src/modules/stats/.gitkeep | 0 memora-web/src/modules/study/.gitkeep | 0 memora-web/src/modules/words/.gitkeep | 0 10 files changed, 174 insertions(+) create mode 100644 PROJECT_STRUCTURE.md create mode 100644 REQUIREMENTS.md create mode 100644 memora-api/cmd/server/.gitkeep create mode 100644 memora-api/internal/domain/.gitkeep create mode 100644 memora-api/internal/repository/.gitkeep create mode 100644 memora-web/src/modules/auth/.gitkeep create mode 100644 memora-web/src/modules/review/.gitkeep create mode 100644 memora-web/src/modules/stats/.gitkeep create mode 100644 memora-web/src/modules/study/.gitkeep create mode 100644 memora-web/src/modules/words/.gitkeep diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..3252472 --- /dev/null +++ b/PROJECT_STRUCTURE.md @@ -0,0 +1,88 @@ +# Memora 前后端项目结构（重设计） + +> 目标：在现有 `memora-api` / `memora-web` 基础上，采用更清晰的领域分层与模块化结构，便于持续开发。 + +## 1. 根目录结构 + +```text +memora/ +├── README.md +├── REQUIREMENTS.md # 需求文档（本次新增） +├── PROJECT_STRUCTURE.md # 项目结构文档（本次新增） +├── docker-compose.yml +├── memora-api/ # 后端服务（Go + Gin） +├── memora-web/ # 前端应用（Vue3 + Vite） +└── memora-engine/ # 记忆引擎（可逐步独立） +``` + +## 2. 后端结构（memora-api） + +```text +memora-api/ +├── cmd/ +│ └── server/ # 程序入口（建议逐步迁移 main） +├── internal/ +│ ├── app/ # 应用启动编排 +│ ├── bootstrap/ # 配置、数据库、中间件初始化 +│ ├── domain/ # 领域模型与领域服务（建议新增） +│ ├── repository/ # 数据访问抽象（建议新增） +│ ├── service/ # 业务服务 +│ ├── handler/ # HTTP Handler +│ ├── router/ # 路由注册 +│ ├── middleware/ # 中间件 +│ ├── request/ # 请求 DTO +│ ├── response/ # 响应 DTO +│ └── model/ # 数据库模型 +├── sql/ +├── audio/ +└── config*.yaml +``` + +### 后端分层规则 +- Handler 只做参数校验和调用 service +- Service 负责业务流程编排 +- Repository 负责数据库读写（GORM） +- Domain 放核心规则（SRS 计算、复习策略） + +## 3. 前端结构（memora-web） + +```text +memora-web/ +├── src/ +│ ├── app/ # 应用启动、全局注入 +│ ├── router/ # 路由 +│ ├── stores/ # Pinia 状态管理 +│ ├── services/ # API 请求封装 +│ ├── modules/ # 业务模块（建议新增） +│ │ ├── auth/ +│ │ ├── words/ +│ │ ├── study/ +│ │ ├── review/ +│ │ └── stats/ +│ ├── views/ # 页面视图 +│ ├── components/ # 通用组件 +│ ├── composables/ # 组合式逻辑 +│ ├── utils/ +│ ├── styles/ +│ └── assets/ +└── public/ +``` + +### 前端模块化规则 +- 以 `modules/*` 聚合业务（API、store、types、hooks） +- `views` 负责页面组合，不写重业务逻辑 +- 通用组件与业务组件分离 + +## 4. 开发顺序建议（不断完善） +1. **认证闭环**：登录、鉴权拦截、会话保持 +2. **词库模块**：列表、详情、搜索、标签过滤 +3. **学习模块**：学习会话 + 答题提交 +4. **复习模块**：SRS 调度 + 每日任务 +5. **统计模块**：趋势图 + 连续学习天数 +6. **稳定性**：日志、错误码、单测、性能优化 + +## 5. 本次交付 +- 已在根目录新增： + - `REQUIREMENTS.md` + - `PROJECT_STRUCTURE.md` +- 后续将按本文档持续推进实现与代码重构。 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..bed6dd0 --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,86 @@ +# Memora 需求文档（重设计版） + +## 1. 项目目标 +Memora 是一个以「长期记忆留存」为目标的背单词系统，面向中文学习者，提供： +- 单词学习与复习闭环（学习 → 测试 → 复习） +- 基于遗忘曲线的复习调度 +- 数据可视化与学习反馈 +- Web 端优先，后续支持移动端复用 API + +--- + +## 2. 用户角色 +- 普通用户：学习、复习、查看统计 +- 管理员（可选）：词库管理、运营配置、异常数据处理 + +--- + +## 3. 核心功能需求 + +### 3.1 账户与身份 +- 用户注册/登录（邮箱或手机号，后续可扩展 OAuth） +- Token 鉴权（JWT） +- 个人学习偏好（每日目标、提醒时间、难度偏好） + +### 3.2 词库与学习内容 +- 词书管理：内置词书 + 自定义词书 +- 单词详情：拼写、音标、词性、释义、例句、发音 +- 标签体系：阶段（新词/熟词/难词）、来源、主题 + +### 3.3 学习流程 +- 新词学习：按计划推送 +- 测试模式：拼写题、选择题、释义匹配（可扩展） +- 学习结果记录：正确率、耗时、连续正确次数 + +### 3.4 复习调度（核心） +- 基于 SRS（间隔重复）策略生成复习计划 +- 每日待复习队列 +- 复习结果回写并动态调整下次复习时间 + +### 3.5 统计与反馈 +- 今日学习量、复习量、正确率 +- 连续学习天数 +- 周/月趋势图 +- 难词排行与建议复习列表 + +### 3.6 系统能力 +- 统一错误码与错误响应 +- 审计日志（关键操作） +- 基础监控（接口耗时、错误率） + +--- + +## 4. 非功能需求 +- 可维护性：前后端分层清晰，模块边界明确 +- 可扩展性：后续可拆分记忆引擎为独立服务 +- 性能：常用接口 P95 < 300ms（本地单机目标） +- 安全性：鉴权、限流、输入校验、敏感信息脱敏 +- 可测试性：核心调度逻辑具备单元测试 + +--- + +## 5. API 需求（第一阶段） +- `POST /api/v1/auth/register` +- `POST /api/v1/auth/login` +- `GET /api/v1/words`（分页） +- `GET /api/v1/words/:id` +- `POST /api/v1/study/sessions` +- `POST /api/v1/study/answers` +- `GET /api/v1/review/today` +- `POST /api/v1/review/submit` +- `GET /api/v1/stats/overview` + +--- + +## 6. 里程碑 +- M1：基础骨架 + 认证 + 词库查询 + 学习记录 +- M2：SRS 调度 + 每日复习 + 统计面板 +- M3：体验优化 + 管理能力 + 稳定性增强 + +--- + +## 7. 验收标准（当前阶段） +1. 能完成注册/登录并访问受保护接口 +2. 能查看单词并完成一次学习-复习提交 +3. 能生成当日复习任务 +4. Web 端可展示学习概览数据 diff --git a/memora-api/cmd/server/.gitkeep b/memora-api/cmd/server/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-api/internal/domain/.gitkeep b/memora-api/internal/domain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-api/internal/repository/.gitkeep b/memora-api/internal/repository/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-web/src/modules/auth/.gitkeep b/memora-web/src/modules/auth/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-web/src/modules/review/.gitkeep b/memora-web/src/modules/review/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-web/src/modules/stats/.gitkeep b/memora-web/src/modules/stats/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-web/src/modules/study/.gitkeep b/memora-web/src/modules/study/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/memora-web/src/modules/words/.gitkeep b/memora-web/src/modules/words/.gitkeep new file mode 100644 index 0000000..e69de29