120 lines
5.0 KiB
Markdown
120 lines
5.0 KiB
Markdown
---
|
||
title: erp-diary 后端模块
|
||
updated: 2026-06-07
|
||
status: active
|
||
tags: [rust, axum, seaorm, diary, api]
|
||
---
|
||
|
||
# erp-diary — 暖记后端业务模块
|
||
|
||
> 从 [[index]] 导航。关联: [[architecture]] [[data-layer]]
|
||
|
||
## 1. 设计决策
|
||
|
||
### Q: 为什么独立 erp-diary crate？
|
||
|
||
基座解耦原则：erp-diary 通过 Feature Flag (`cargo build --features diary`) 按需引入。基座 crate 不依赖业务模块，其他项目可复用基座而不引入日记功能。
|
||
|
||
### Q: DiaryError 设计？
|
||
|
||
15 种变体枚举（NotFound / VersionConflict / Unauthorized / ContentUnsafe 等），实现 `Into<AppError>` 转换为 HTTP 状态码映射。集成测试验证每个错误码的正确 HTTP 响应。
|
||
|
||
### Q: 为什么内容安全过滤在 Service 层？
|
||
|
||
日记标题、文字元素的文本需要敏感词检查（含谐音/拼音变体）。放在 Service 层而非 Handler 层，确保即使有新的入口点（事件消费、管理 API）也不会绕过检查。
|
||
|
||
## 2. 关键文件 + 数据流
|
||
|
||
### 模块结构
|
||
|
||
```
|
||
crates/erp-diary/src/
|
||
├── lib.rs (280 行) — DiaryModule 实现 + Feature Flag 注册
|
||
├── dto.rs (640 行) — 请求/响应 DTO + Validate 注解
|
||
├── error.rs (193 行) — DiaryError 15 种变体 → HTTP 状态码
|
||
├── event.rs (61 行) — 事件定义 (diary.created 等)
|
||
├── state.rs (13 行) — DiaryState (DiaryModule 专用状态)
|
||
├── entity/ (15 文件) — SeaORM Entity
|
||
├── service/ (12 文件) — 业务逻辑
|
||
└── handler/ (10 文件) — HTTP Handler + utoipa 注解
|
||
```
|
||
|
||
### Entity 清单 (15 个)
|
||
|
||
achievement, class_member, comment, handwriting_stroke, journal_element, journal_entry, parent_child_binding, school_class, sticker, sticker_pack, teacher_profile, template, topic_assignment, user_achievement, user_settings
|
||
|
||
### Service 清单 (12 个)
|
||
|
||
journal, class, comment, content_safety, achievement, mood_stats, notification, sticker, sync, topic, **parent**, **discover**
|
||
|
||
### API 端点
|
||
|
||
| 端点前缀 | Handler | 主要操作 |
|
||
|---------|---------|---------|
|
||
| `/api/v1/diary/journals` | journal_handler | CRUD + 列表过滤 |
|
||
| `/api/v1/diary/journals/:id/elements` | journal_handler (同) | 元素 CRUD |
|
||
| `/api/v1/diary/classes` | class_handler | 班级 CRUD + 班级码 |
|
||
| `/api/v1/diary/comments` | comment_handler | 评论 CRUD |
|
||
| `/api/v1/diary/topics` | topic_handler | 主题布置 |
|
||
| `/api/v1/diary/achievements` | achievement_handler | 成就系统 |
|
||
| `/api/v1/diary/stickers` | sticker_handler | 贴纸管理 |
|
||
| `/api/v1/diary/stats` | stats_handler | 心情/写作统计 |
|
||
| `/api/v1/diary/sync` | sync_handler | 增量同步 API |
|
||
| `/api/v1/diary/discover` | discover_handler | 发现页聚合（每日推荐/热门话题/精选模板/达人日记） |
|
||
| `/api/v1/diary/parent` | parent_handler | 家长绑定 + 数据管理 |
|
||
|
||
### 集成契约
|
||
|
||
| 方向 | 模块 | 接口 | 触发时机 |
|
||
|------|------|------|---------|
|
||
| 提供 → | erp-server | `DiaryModule::routes()` | 启动 feature=diary |
|
||
| 调用 → | erp-core | `EventBus::publish()` | 日记创建/更新/删除 |
|
||
| 调用 → | erp-auth | `require_permission()` | 每个 handler 入口 |
|
||
| 调用 → | erp-message | 通知服务 | 评论/班级事件 |
|
||
|
||
## 3. 代码逻辑
|
||
|
||
### 不变量
|
||
|
||
⚡ **所有 Entity 含标准字段** — id / tenant_id / created_at / updated_at / created_by / updated_by / deleted_at / version
|
||
|
||
⚡ **软删除** — 查询带 `deleted_at IS NULL` 过滤，不做硬删除
|
||
|
||
⚡ **多租户隔离** — 中间件注入 tenant_id，handler 不从 API 路径获取
|
||
|
||
⚡ **权限守卫** — 每个 handler 方法第一行 `require_permission("diary.xxx")`
|
||
|
||
⚡ **输入验证** — DTO 使用 `#[derive(Validate)]` + handler 层调 `.validate()`
|
||
|
||
⚡ **内容安全** — 日记标题/文字通过 ContentSafetyService 检查
|
||
|
||
## 4. 活跃问题 + 陷阱
|
||
|
||
| 问题 | 级别 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| Docker 部署未验证 | HIGH | 待做 | docker/ 配置完善但 Dockerfile 不存在 |
|
||
| CI/CD 未建立 | MEDIUM | 待做 | 无自动化构建/测试/部署 |
|
||
| 文件上传未实现 | MEDIUM | 待做 | 照片/贴纸文件上传参考健康模块 |
|
||
| 代码分布 | INFO | 参考 | service 层 51.7%、handler 20.1%、entity 15.6%、dto 11.1% |
|
||
| 班级码硬编码 | LOW | 待修 | 前端 teacher 模块班级码 'a1b2c3' 未接入后端 |
|
||
| 发现页硬编码 | — | ✅ 已修复 | DiscoverBloc + GET /diary/discover 全链路打通 |
|
||
|
||
### 代码量参考
|
||
|
||
| 层 | 行数 | 占比 |
|
||
|---|---:|---:|
|
||
| entity/ | 796 | 15.6% |
|
||
| handler/ | 1,029 | 20.1% |
|
||
| service/ | 2,641 | 51.7% |
|
||
| dto.rs | 569 | 11.1% |
|
||
| 其他 | 473 | 9.3% |
|
||
| **合计** | **5,108** | **100%** |
|
||
|
||
## 5. 变更记录
|
||
|
||
| 日期 | 变更 |
|
||
|------|------|
|
||
| 2026-06-07 | 新增 discover_service + discover_handler (GET /diary/discover)、parent_handler 补充文档 |
|
||
| 2026-06-01 | 补充代码量分布、班级码硬编码问题 |
|
||
| 2026-06-01 | 初始创建 — Entity/Service/Handler 清单、API 端点、集成契约 |
|