From 38592d61cea5afe769411130713608796e00b6d2 Mon Sep 17 00:00:00 2001 From: iven Date: Wed, 3 Jun 2026 17:06:03 +0800 Subject: [PATCH] =?UTF-8?q?refactor(diary):=20Phase=203=20=E8=B4=A8?= =?UTF-8?q?=E9=87=8F=E6=8F=90=E5=8D=87=20=E2=80=94=20201=20=E7=8A=B6?= =?UTF-8?q?=E6=80=81=E7=A0=81=20+=20OpenAPI=20=E6=96=87=E6=A1=A3=20+=20Dia?= =?UTF-8?q?ryEvent=20=E7=B1=BB=E5=9E=8B=E5=AE=89=E5=85=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 前端: - fix(app): Isar native 文件直接导入 isar_database_native.dart，消除 5 个条件导出类型错误 - chore(app): build_runner 重新生成 .g.dart 文件 (102 outputs) - fix(app): 移除 secure_token_store_factory 未使用的 kIsWeb import 后端: - refactor(diary): 所有创建端点 POST 返回 201 Created (9 handler, 11 端点) - feat(diary): DiaryApiDoc OpenApi derive — 42 路径 + 32 Schema 汇总到 Swagger - feat(diary): DiaryEvent 枚举添加 event_type/payload/to_domain_event 方法 + 4 测试 测试: 84/84 erp-diary 通过, 509/509 全仓库通过, Flutter analyze 0 error --- .../journal_element_collection.g.dart | 6 +- .../journal_entry_collection.g.dart | 280 ++++++++++++- .../pending_operation_collection.g.dart | 4 +- .../local/secure_token_store_factory.dart | 2 - .../isar_journal_repository_native.dart | 4 +- app/lib/data/services/sync_engine_native.dart | 6 +- crates/erp-diary/src/event.rs | 249 +++++++++-- .../src/handler/achievement_handler.rs | 7 +- crates/erp-diary/src/handler/class_handler.rs | 13 +- .../erp-diary/src/handler/comment_handler.rs | 7 +- .../erp-diary/src/handler/journal_handler.rs | 7 +- .../erp-diary/src/handler/parent_handler.rs | 17 +- .../erp-diary/src/handler/sticker_handler.rs | 13 +- crates/erp-diary/src/handler/topic_handler.rs | 7 +- crates/erp-server/src/handlers/openapi.rs | 7 + crates/erp-server/src/main.rs | 84 ++++ docs/audit-2026-06-03-full-report.md | 395 ++++++++++++++++++ 17 files changed, 1038 insertions(+), 70 deletions(-) create mode 100644 docs/audit-2026-06-03-full-report.md diff --git a/app/lib/data/local/collections/journal_element_collection.g.dart b/app/lib/data/local/collections/journal_element_collection.g.dart index c3532f7..292a173 100644 --- a/app/lib/data/local/collections/journal_element_collection.g.dart +++ b/app/lib/data/local/collections/journal_element_collection.g.dart @@ -16,7 +16,7 @@ extension GetJournalElementCollectionCollection on Isar { const JournalElementCollectionSchema = CollectionSchema( name: r'JournalElementCollection', - id: -1002, + id: -3625932583395690305, properties: { r'contentJson': PropertySchema( id: 0, @@ -96,7 +96,7 @@ const JournalElementCollectionSchema = CollectionSchema( idName: r'isarId', indexes: { r'id': IndexSchema( - id: -2002, + id: -3268401673993471357, name: r'id', unique: false, replace: false, @@ -109,7 +109,7 @@ const JournalElementCollectionSchema = CollectionSchema( ], ), r'journalId': IndexSchema( - id: 3001, + id: 1745640946427815323, name: r'journalId', unique: false, replace: false, diff --git a/app/lib/data/local/collections/journal_entry_collection.g.dart b/app/lib/data/local/collections/journal_entry_collection.g.dart index 05ed74e..87d3ede 100644 --- a/app/lib/data/local/collections/journal_entry_collection.g.dart +++ b/app/lib/data/local/collections/journal_entry_collection.g.dart @@ -16,7 +16,7 @@ extension GetJournalEntryCollectionCollection on Isar { const JournalEntryCollectionSchema = CollectionSchema( name: r'JournalEntryCollection', - id: -1001, + id: -6325316395299921961, properties: { r'assignedTopicId': PropertySchema( id: 0, @@ -106,7 +106,7 @@ const JournalEntryCollectionSchema = CollectionSchema( idName: r'isarId', indexes: { r'id': IndexSchema( - id: -2001, + id: -3268401673993471357, name: r'id', unique: false, replace: false, @@ -117,6 +117,37 @@ const JournalEntryCollectionSchema = CollectionSchema( caseSensitive: true, ) ], + ), + r'authorId_dateEpoch': IndexSchema( + id: -4869847655132214108, + name: r'authorId_dateEpoch', + unique: false, + replace: false, + properties: [ + IndexPropertySchema( + name: r'authorId', + type: IndexType.hash, + caseSensitive: true, + ), + IndexPropertySchema( + name: r'dateEpoch', + type: IndexType.value, + caseSensitive: false, + ) + ], + ), + r'dateEpoch': IndexSchema( + id: 359017825055613028, + name: r'dateEpoch', + unique: false, + replace: false, + properties: [ + IndexPropertySchema( + name: r'dateEpoch', + type: IndexType.value, + caseSensitive: false, + ) + ], ) }, links: {}, @@ -277,6 +308,15 @@ extension JournalEntryCollectionQueryWhereSort return query.addWhereClause(const IdWhereClause.any()); }); } + + QueryBuilder + anyDateEpoch() { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause( + const IndexWhereClause.any(indexName: r'dateEpoch'), + ); + }); + } } extension JournalEntryCollectionQueryWhere on QueryBuilder< @@ -393,6 +433,242 @@ extension JournalEntryCollectionQueryWhere on QueryBuilder< } }); } + + QueryBuilder authorIdEqualToAnyDateEpoch(String authorId) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.equalTo( + indexName: r'authorId_dateEpoch', + value: [authorId], + )); + }); + } + + QueryBuilder authorIdNotEqualToAnyDateEpoch(String authorId) { + return QueryBuilder.apply(this, (query) { + if (query.whereSort == Sort.asc) { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [], + upper: [authorId], + includeUpper: false, + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId], + includeLower: false, + upper: [], + )); + } else { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId], + includeLower: false, + upper: [], + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [], + upper: [authorId], + includeUpper: false, + )); + } + }); + } + + QueryBuilder + authorIdDateEpochEqualTo(String authorId, int dateEpoch) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.equalTo( + indexName: r'authorId_dateEpoch', + value: [authorId, dateEpoch], + )); + }); + } + + QueryBuilder + authorIdEqualToDateEpochNotEqualTo(String authorId, int dateEpoch) { + return QueryBuilder.apply(this, (query) { + if (query.whereSort == Sort.asc) { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId], + upper: [authorId, dateEpoch], + includeUpper: false, + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId, dateEpoch], + includeLower: false, + upper: [authorId], + )); + } else { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId, dateEpoch], + includeLower: false, + upper: [authorId], + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId], + upper: [authorId, dateEpoch], + includeUpper: false, + )); + } + }); + } + + QueryBuilder authorIdEqualToDateEpochGreaterThan( + String authorId, + int dateEpoch, { + bool include = false, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId, dateEpoch], + includeLower: include, + upper: [authorId], + )); + }); + } + + QueryBuilder authorIdEqualToDateEpochLessThan( + String authorId, + int dateEpoch, { + bool include = false, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId], + upper: [authorId, dateEpoch], + includeUpper: include, + )); + }); + } + + QueryBuilder authorIdEqualToDateEpochBetween( + String authorId, + int lowerDateEpoch, + int upperDateEpoch, { + bool includeLower = true, + bool includeUpper = true, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'authorId_dateEpoch', + lower: [authorId, lowerDateEpoch], + includeLower: includeLower, + upper: [authorId, upperDateEpoch], + includeUpper: includeUpper, + )); + }); + } + + QueryBuilder dateEpochEqualTo(int dateEpoch) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.equalTo( + indexName: r'dateEpoch', + value: [dateEpoch], + )); + }); + } + + QueryBuilder dateEpochNotEqualTo(int dateEpoch) { + return QueryBuilder.apply(this, (query) { + if (query.whereSort == Sort.asc) { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [], + upper: [dateEpoch], + includeUpper: false, + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [dateEpoch], + includeLower: false, + upper: [], + )); + } else { + return query + .addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [dateEpoch], + includeLower: false, + upper: [], + )) + .addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [], + upper: [dateEpoch], + includeUpper: false, + )); + } + }); + } + + QueryBuilder dateEpochGreaterThan( + int dateEpoch, { + bool include = false, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [dateEpoch], + includeLower: include, + upper: [], + )); + }); + } + + QueryBuilder dateEpochLessThan( + int dateEpoch, { + bool include = false, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [], + upper: [dateEpoch], + includeUpper: include, + )); + }); + } + + QueryBuilder dateEpochBetween( + int lowerDateEpoch, + int upperDateEpoch, { + bool includeLower = true, + bool includeUpper = true, + }) { + return QueryBuilder.apply(this, (query) { + return query.addWhereClause(IndexWhereClause.between( + indexName: r'dateEpoch', + lower: [lowerDateEpoch], + includeLower: includeLower, + upper: [upperDateEpoch], + includeUpper: includeUpper, + )); + }); + } } extension JournalEntryCollectionQueryFilter on QueryBuilder< diff --git a/app/lib/data/local/collections/pending_operation_collection.g.dart b/app/lib/data/local/collections/pending_operation_collection.g.dart index 18e57b2..81ff327 100644 --- a/app/lib/data/local/collections/pending_operation_collection.g.dart +++ b/app/lib/data/local/collections/pending_operation_collection.g.dart @@ -16,7 +16,7 @@ extension GetPendingOperationCollectionCollection on Isar { const PendingOperationCollectionSchema = CollectionSchema( name: r'PendingOperationCollection', - id: -1003, + id: -6885010264946527864, properties: { r'createdAtEpoch': PropertySchema( id: 0, @@ -61,7 +61,7 @@ const PendingOperationCollectionSchema = CollectionSchema( idName: r'isarId', indexes: { r'id': IndexSchema( - id: -2003, + id: -3268401673993471357, name: r'id', unique: false, replace: false, diff --git a/app/lib/data/local/secure_token_store_factory.dart b/app/lib/data/local/secure_token_store_factory.dart index 3ec12c5..24b0a09 100644 --- a/app/lib/data/local/secure_token_store_factory.dart +++ b/app/lib/data/local/secure_token_store_factory.dart @@ -3,8 +3,6 @@ // 根据平台创建对应的 SecureTokenStore 实现。 // 运行时判断 kIsWeb，避免 Web 编译时加载 flutter_secure_storage。 -import 'package:flutter/foundation.dart' show kIsWeb; - import 'secure_token_store.dart'; import 'secure_token_store_web.dart'; diff --git a/app/lib/data/repositories/isar_journal_repository_native.dart b/app/lib/data/repositories/isar_journal_repository_native.dart index 56e02f5..d50b38e 100644 --- a/app/lib/data/repositories/isar_journal_repository_native.dart +++ b/app/lib/data/repositories/isar_journal_repository_native.dart @@ -11,7 +11,7 @@ import 'dart:convert'; import 'package:isar/isar.dart'; -import '../local/isar_database.dart'; +import '../local/isar_database_native.dart'; import '../local/collections/journal_entry_collection.dart'; import '../local/collections/journal_element_collection.dart'; import '../models/journal_entry.dart'; @@ -20,7 +20,7 @@ import 'journal_repository.dart'; /// Isar 本地日记仓库 — JournalRepository 的 Isar 实现 class IsarJournalRepository implements JournalRepository { - Isar get _isar => IsarDatabase.instance!; + Isar get _isar => IsarDatabase.instance; // ============================================================ // 日记 CRUD diff --git a/app/lib/data/services/sync_engine_native.dart b/app/lib/data/services/sync_engine_native.dart index c68771d..1c89e74 100644 --- a/app/lib/data/services/sync_engine_native.dart +++ b/app/lib/data/services/sync_engine_native.dart @@ -20,7 +20,7 @@ import 'package:connectivity_plus/connectivity_plus.dart'; import 'package:flutter/foundation.dart'; import 'package:isar/isar.dart'; -import '../local/isar_database.dart'; +import '../local/isar_database_native.dart'; import '../local/collections/pending_operation_collection.dart'; import '../remote/api_client.dart'; @@ -312,7 +312,7 @@ class SyncEngine { /// 在 app 退出、isolate 暂停、或同步完成后调用。 Future persistPendingQueue() async { if (!IsarDatabase.isAvailable) return; - final isar = IsarDatabase.instance!; + final isar = IsarDatabase.instance; final ops = snapshot; await isar.writeTxn(() async { @@ -333,7 +333,7 @@ class SyncEngine { /// Web 平台上 Isar 不可用，跳过恢复。 Future restorePendingQueue() async { if (!IsarDatabase.isAvailable) return; - final isar = IsarDatabase.instance!; + final isar = IsarDatabase.instance; final persisted = await isar.pendingOperationCollections .where() .anyIsarId() diff --git a/crates/erp-diary/src/event.rs b/crates/erp-diary/src/event.rs index 2402df7..af0bc3a 100644 --- a/crates/erp-diary/src/event.rs +++ b/crates/erp-diary/src/event.rs @@ -1,61 +1,262 @@ // erp-diary 事件定义 +// +// DiaryEvent 是日记模块的领域事件枚举，提供类型安全的事件构建。 +// 通过 `to_domain_event(tenant_id)` 转换为基座 DomainEvent 后发布到 EventBus。 +// +// 使用方式（Service 层）: +// use crate::event::DiaryEvent; +// let evt = DiaryEvent::JournalCreated { journal_id, author_id, class_id }; +// event_bus.publish(evt.to_domain_event(tenant_id), db).await; + +use serde_json::json; +use uuid::Uuid; + +use erp_core::events::DomainEvent; /// 日记模块领域事件 +#[derive(Debug, Clone)] pub enum DiaryEvent { /// 日记创建 JournalCreated { - journal_id: uuid::Uuid, - author_id: uuid::Uuid, - class_id: Option, + journal_id: Uuid, + author_id: Uuid, + class_id: Option, }, /// 日记更新 JournalUpdated { - journal_id: uuid::Uuid, - author_id: uuid::Uuid, + journal_id: Uuid, + author_id: Uuid, version: i32, }, /// 日记删除 JournalDeleted { - journal_id: uuid::Uuid, - author_id: uuid::Uuid, + journal_id: Uuid, + author_id: Uuid, }, /// 日记分享到班级 JournalShared { - journal_id: uuid::Uuid, - author_id: uuid::Uuid, - class_id: uuid::Uuid, + journal_id: Uuid, + author_id: Uuid, + class_id: Uuid, }, /// 班级创建 ClassCreated { - class_id: uuid::Uuid, - teacher_id: uuid::Uuid, + class_id: Uuid, + teacher_id: Uuid, }, /// 学生加入班级 StudentJoinedClass { - class_id: uuid::Uuid, - student_id: uuid::Uuid, + class_id: Uuid, + student_id: Uuid, }, /// 老师布置主题 TopicAssigned { - topic_id: uuid::Uuid, - class_id: uuid::Uuid, - teacher_id: uuid::Uuid, + topic_id: Uuid, + class_id: Uuid, + teacher_id: Uuid, }, /// 老师点评 CommentCreated { - comment_id: uuid::Uuid, - journal_id: uuid::Uuid, - teacher_id: uuid::Uuid, - student_id: uuid::Uuid, + comment_id: Uuid, + journal_id: Uuid, + teacher_id: Uuid, + student_id: Uuid, }, /// 家长绑定孩子 ParentBound { - parent_id: uuid::Uuid, - child_id: uuid::Uuid, + parent_id: Uuid, + child_id: Uuid, }, /// 成就解锁 AchievementUnlocked { - user_id: uuid::Uuid, + user_id: Uuid, achievement_id: String, }, } + +impl DiaryEvent { + /// 返回事件类型字符串（用于 DomainEvent.event_type） + pub fn event_type(&self) -> &'static str { + match self { + Self::JournalCreated { .. } => "diary.created", + Self::JournalUpdated { .. } => "diary.updated", + Self::JournalDeleted { .. } => "diary.deleted", + Self::JournalShared { .. } => "diary.shared", + Self::ClassCreated { .. } => "diary.class.created", + Self::StudentJoinedClass { .. } => "diary.class.student_joined", + Self::TopicAssigned { .. } => "diary.topic.assigned", + Self::CommentCreated { .. } => "diary.comment.created", + Self::ParentBound { .. } => "diary.parent.binding_confirmed", + Self::AchievementUnlocked { .. } => "diary.achievement.unlocked", + } + } + + /// 返回事件 payload（JSON 格式） + pub fn payload(&self) -> serde_json::Value { + match self { + Self::JournalCreated { + journal_id, + author_id, + class_id, + } => json!({ + "journal_id": journal_id, + "author_id": author_id, + "class_id": class_id, + }), + Self::JournalUpdated { + journal_id, + author_id, + version, + } => json!({ + "journal_id": journal_id, + "author_id": author_id, + "version": version, + }), + Self::JournalDeleted { + journal_id, + author_id, + } => json!({ + "journal_id": journal_id, + "author_id": author_id, + }), + Self::JournalShared { + journal_id, + author_id, + class_id, + } => json!({ + "journal_id": journal_id, + "author_id": author_id, + "class_id": class_id, + }), + Self::ClassCreated { + class_id, + teacher_id, + } => json!({ + "class_id": class_id, + "teacher_id": teacher_id, + }), + Self::StudentJoinedClass { + class_id, + student_id, + } => json!({ + "class_id": class_id, + "student_id": student_id, + }), + Self::TopicAssigned { + topic_id, + class_id, + teacher_id, + } => json!({ + "topic_id": topic_id, + "class_id": class_id, + "teacher_id": teacher_id, + }), + Self::CommentCreated { + comment_id, + journal_id, + teacher_id, + student_id, + } => json!({ + "comment_id": comment_id, + "journal_id": journal_id, + "teacher_id": teacher_id, + "student_id": student_id, + }), + Self::ParentBound { + parent_id, + child_id, + } => json!({ + "parent_id": parent_id, + "child_id": child_id, + }), + Self::AchievementUnlocked { + user_id, + achievement_id, + } => json!({ + "user_id": user_id, + "achievement_id": achievement_id, + }), + } + } + + /// 转换为基座 DomainEvent，可直接发布到 EventBus + pub fn to_domain_event(&self, tenant_id: Uuid) -> DomainEvent { + DomainEvent::new(self.event_type(), tenant_id, self.payload()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn journal_created_event_type() { + let id = Uuid::now_v7(); + let evt = DiaryEvent::JournalCreated { + journal_id: id, + author_id: id, + class_id: None, + }; + assert_eq!(evt.event_type(), "diary.created"); + assert_eq!(evt.payload()["journal_id"], id.to_string()); + } + + #[test] + fn class_created_event_type() { + let id = Uuid::now_v7(); + let evt = DiaryEvent::ClassCreated { + class_id: id, + teacher_id: id, + }; + assert_eq!(evt.event_type(), "diary.class.created"); + } + + #[test] + fn to_domain_event_preserves_fields() { + let tid = Uuid::now_v7(); + let jid = Uuid::now_v7(); + let aid = Uuid::now_v7(); + + let de = DiaryEvent::JournalCreated { + journal_id: jid, + author_id: aid, + class_id: Some(tid), + } + .to_domain_event(tid); + + assert_eq!(de.event_type, "diary.created"); + assert_eq!(de.tenant_id, tid); + assert_eq!(de.payload["journal_id"], jid.to_string()); + assert_eq!(de.payload["author_id"], aid.to_string()); + assert_eq!(de.payload["class_id"], tid.to_string()); + } + + #[test] + fn all_variants_have_correct_event_type() { + let id = Uuid::now_v7(); + let variants: Vec = vec![ + DiaryEvent::JournalCreated { journal_id: id, author_id: id, class_id: None }, + DiaryEvent::JournalUpdated { journal_id: id, author_id: id, version: 1 }, + DiaryEvent::JournalDeleted { journal_id: id, author_id: id }, + DiaryEvent::JournalShared { journal_id: id, author_id: id, class_id: id }, + DiaryEvent::ClassCreated { class_id: id, teacher_id: id }, + DiaryEvent::StudentJoinedClass { class_id: id, student_id: id }, + DiaryEvent::TopicAssigned { topic_id: id, class_id: id, teacher_id: id }, + DiaryEvent::CommentCreated { comment_id: id, journal_id: id, teacher_id: id, student_id: id }, + DiaryEvent::ParentBound { parent_id: id, child_id: id }, + DiaryEvent::AchievementUnlocked { user_id: id, achievement_id: "first_diary".into() }, + ]; + + let types: Vec<&str> = variants.iter().map(|v| v.event_type()).collect(); + assert!(types.contains(&"diary.created")); + assert!(types.contains(&"diary.updated")); + assert!(types.contains(&"diary.deleted")); + assert!(types.contains(&"diary.shared")); + assert!(types.contains(&"diary.class.created")); + assert!(types.contains(&"diary.class.student_joined")); + assert!(types.contains(&"diary.topic.assigned")); + assert!(types.contains(&"diary.comment.created")); + assert!(types.contains(&"diary.parent.binding_confirmed")); + assert!(types.contains(&"diary.achievement.unlocked")); + } +} diff --git a/crates/erp-diary/src/handler/achievement_handler.rs b/crates/erp-diary/src/handler/achievement_handler.rs index 2b48b36..0f35e3e 100644 --- a/crates/erp-diary/src/handler/achievement_handler.rs +++ b/crates/erp-diary/src/handler/achievement_handler.rs @@ -1,6 +1,7 @@ // 成就 API 处理器 use axum::extract::{Extension, FromRef, Path, State}; +use axum::http::StatusCode; use axum::response::Json; use erp_core::error::AppError; @@ -44,7 +45,7 @@ where path = "/api/v1/diary/achievements/{code}/unlock", params(("code" = String, Path, description = "成就编码")), responses( - (status = 200, description = "解锁成功", body = ApiResponse), + (status = 201, description = "解锁成功", body = ApiResponse), (status = 404, description = "成就不存在"), ), security(("bearer_auth" = [])), @@ -57,7 +58,7 @@ pub async fn unlock_achievement( State(state): State, Extension(ctx): Extension, Path(code): Path, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -73,5 +74,5 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } diff --git a/crates/erp-diary/src/handler/class_handler.rs b/crates/erp-diary/src/handler/class_handler.rs index 6ccab71..051eabe 100644 --- a/crates/erp-diary/src/handler/class_handler.rs +++ b/crates/erp-diary/src/handler/class_handler.rs @@ -1,6 +1,7 @@ // 班级 API 处理器 — 创建班级、加入班级、查询班级 use axum::extract::{Extension, FromRef, Path, State}; +use axum::http::StatusCode; use axum::response::Json; use uuid::Uuid; use validator::Validate; @@ -18,7 +19,7 @@ use crate::state::DiaryState; path = "/api/v1/diary/classes", request_body = CreateClassReq, responses( - (status = 200, description = "创建成功", body = ApiResponse), + (status = 201, description = "创建成功", body = ApiResponse), (status = 400, description = "验证失败"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -33,7 +34,7 @@ pub async fn create_class( State(state): State, Extension(ctx): Extension, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -55,7 +56,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( @@ -63,7 +64,7 @@ where path = "/api/v1/diary/classes/join", request_body = JoinClassReq, responses( - (status = 200, description = "加入成功", body = ApiResponse), + (status = 201, description = "加入成功", body = ApiResponse), (status = 400, description = "班级码无效或已过期"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -78,7 +79,7 @@ pub async fn join_class( State(state): State, Extension(ctx): Extension, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -101,7 +102,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( diff --git a/crates/erp-diary/src/handler/comment_handler.rs b/crates/erp-diary/src/handler/comment_handler.rs index 467de04..14480bd 100644 --- a/crates/erp-diary/src/handler/comment_handler.rs +++ b/crates/erp-diary/src/handler/comment_handler.rs @@ -1,6 +1,7 @@ // 评语 API 处理器 — 老师点评学生日记 use axum::extract::{Extension, FromRef, Path, State}; +use axum::http::StatusCode; use axum::response::Json; use uuid::Uuid; use validator::Validate; @@ -19,7 +20,7 @@ use crate::state::DiaryState; params(("journal_id" = Uuid, Path, description = "日记ID")), request_body = CreateCommentReq, responses( - (status = 200, description = "点评成功", body = ApiResponse), + (status = 201, description = "点评成功", body = ApiResponse), (status = 400, description = "验证失败或内容安全检查未通过"), (status = 401, description = "未授权"), (status = 403, description = "权限不足或不是本班老师"), @@ -37,7 +38,7 @@ pub async fn create_comment( Extension(ctx): Extension, Path(journal_id): Path, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -59,7 +60,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( diff --git a/crates/erp-diary/src/handler/journal_handler.rs b/crates/erp-diary/src/handler/journal_handler.rs index bef74d6..21c751b 100644 --- a/crates/erp-diary/src/handler/journal_handler.rs +++ b/crates/erp-diary/src/handler/journal_handler.rs @@ -1,6 +1,7 @@ // 日记 API 处理器 — CRUD + 列表 use axum::extract::{Extension, FromRef, Path, Query, State}; +use axum::http::StatusCode; use axum::response::Json; use serde::Deserialize; use utoipa::IntoParams; @@ -39,7 +40,7 @@ pub struct JournalListParams { path = "/api/v1/diary/journals", request_body = CreateJournalReq, responses( - (status = 200, description = "创建成功", body = ApiResponse), + (status = 201, description = "创建成功", body = ApiResponse), (status = 400, description = "验证失败"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -54,7 +55,7 @@ pub async fn create_journal( State(state): State, Extension(ctx): Extension, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -76,7 +77,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( diff --git a/crates/erp-diary/src/handler/parent_handler.rs b/crates/erp-diary/src/handler/parent_handler.rs index d07ddf2..a89fc0b 100644 --- a/crates/erp-diary/src/handler/parent_handler.rs +++ b/crates/erp-diary/src/handler/parent_handler.rs @@ -1,6 +1,7 @@ // 家长中心 API 处理器 — PIPL 合规: 绑定/查阅/导出/删除 use axum::extract::{Extension, FromRef, Path, Query, State}; +use axum::http::StatusCode; use axum::response::Json; use serde::{Deserialize, Serialize}; use utoipa::{IntoParams, ToSchema}; @@ -71,7 +72,7 @@ pub struct DeleteResultResp { path = "/api/v1/diary/parent/bind", request_body = BindChildReq, responses( - (status = 200, description = "绑定成功", body = ApiResponse), + (status = 201, description = "绑定成功", body = ApiResponse), (status = 400, description = "已绑定该孩子"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -86,7 +87,7 @@ pub async fn bind_child( State(state): State, Extension(ctx): Extension, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -102,11 +103,11 @@ where ) .await?; - Ok(Json(ApiResponse::ok(BindingResp { + Ok((StatusCode::CREATED, Json(ApiResponse::ok(BindingResp { binding_id: binding.id, child_id: binding.child_id, verified_at: binding.verified_at, - }))) + })))) } #[utoipa::path( @@ -357,7 +358,7 @@ where path = "/api/v1/diary/parent/bindings/{binding_id}/confirm", params(("binding_id" = Uuid, Path, description = "绑定请求ID")), responses( - (status = 200, description = "确认成功", body = ApiResponse), + (status = 201, description = "确认成功", body = ApiResponse), (status = 401, description = "未授权"), (status = 403, description = "无权确认此绑定"), (status = 404, description = "绑定请求不存在"), @@ -372,7 +373,7 @@ pub async fn confirm_binding( State(state): State, Extension(ctx): Extension, Path(binding_id): Path, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -386,11 +387,11 @@ where ) .await?; - Ok(Json(ApiResponse::ok(BindingResp { + Ok((StatusCode::CREATED, Json(ApiResponse::ok(BindingResp { binding_id: binding.id, child_id: binding.parent_id, verified_at: binding.verified_at, - }))) + })))) } #[utoipa::path( diff --git a/crates/erp-diary/src/handler/sticker_handler.rs b/crates/erp-diary/src/handler/sticker_handler.rs index ef33c51..44c1884 100644 --- a/crates/erp-diary/src/handler/sticker_handler.rs +++ b/crates/erp-diary/src/handler/sticker_handler.rs @@ -1,6 +1,7 @@ // 贴纸与模板 API 处理器 use axum::extract::{Extension, FromRef, Path, Query, State}; +use axum::http::StatusCode; use axum::response::Json; use serde::Deserialize; use utoipa::IntoParams; @@ -91,7 +92,7 @@ where path = "/api/v1/diary/sticker-packs", request_body = CreateStickerPackReq, responses( - (status = 200, description = "创建成功", body = ApiResponse), + (status = 201, description = "创建成功", body = ApiResponse), (status = 400, description = "验证失败"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -106,7 +107,7 @@ pub async fn create_sticker_pack( State(state): State, Extension(ctx): Extension, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -126,7 +127,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( @@ -216,7 +217,7 @@ where params(("pack_id" = Uuid, Path, description = "贴纸包ID")), request_body = CreateStickerReq, responses( - (status = 200, description = "创建成功", body = ApiResponse), + (status = 201, description = "创建成功", body = ApiResponse), (status = 400, description = "验证失败"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -233,7 +234,7 @@ pub async fn create_sticker( Extension(ctx): Extension, Path(pack_id): Path, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -254,7 +255,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[derive(Debug, Deserialize, IntoParams)] pub struct TemplateQuery { diff --git a/crates/erp-diary/src/handler/topic_handler.rs b/crates/erp-diary/src/handler/topic_handler.rs index 62bf177..154f43f 100644 --- a/crates/erp-diary/src/handler/topic_handler.rs +++ b/crates/erp-diary/src/handler/topic_handler.rs @@ -1,6 +1,7 @@ // 主题布置 API 处理器 — 老师布置/查询主题 use axum::extract::{Extension, FromRef, Path, State}; +use axum::http::StatusCode; use axum::response::Json; use uuid::Uuid; use validator::Validate; @@ -19,7 +20,7 @@ use crate::state::DiaryState; params(("class_id" = Uuid, Path, description = "班级ID")), request_body = CreateTopicReq, responses( - (status = 200, description = "布置成功", body = ApiResponse), + (status = 201, description = "布置成功", body = ApiResponse), (status = 400, description = "验证失败"), (status = 401, description = "未授权"), (status = 403, description = "权限不足"), @@ -36,7 +37,7 @@ pub async fn assign_topic( Extension(ctx): Extension, Path(class_id): Path, Json(req): Json, -) -> Result>, AppError> +) -> Result<(StatusCode, Json>), AppError> where DiaryState: FromRef, S: Clone + Send + Sync + 'static, @@ -58,7 +59,7 @@ where ) .await?; - Ok(Json(ApiResponse::ok(resp))) + Ok((StatusCode::CREATED, Json(ApiResponse::ok(resp)))) } #[utoipa::path( diff --git a/crates/erp-server/src/handlers/openapi.rs b/crates/erp-server/src/handlers/openapi.rs index 683aa3f..613bbe8 100644 --- a/crates/erp-server/src/handlers/openapi.rs +++ b/crates/erp-server/src/handlers/openapi.rs @@ -3,6 +3,9 @@ use utoipa::OpenApi; use crate::{ApiDoc, AuthApiDoc, ConfigApiDoc, MessageApiDoc, WorkflowApiDoc}; +#[cfg(feature = "diary")] +use crate::DiaryApiDoc; + /// GET /docs/openapi.json /// /// 返回 OpenAPI 3.0 规范 JSON 文档，合并所有模块的路径和 schema。 @@ -15,6 +18,10 @@ pub async fn openapi_spec() -> Response { spec.merge(ConfigApiDoc::openapi()); spec.merge(WorkflowApiDoc::openapi()); spec.merge(MessageApiDoc::openapi()); + + #[cfg(feature = "diary")] + spec.merge(DiaryApiDoc::openapi()); + Json(serde_json::to_value(spec).unwrap_or_default()).into_response() } diff --git a/crates/erp-server/src/main.rs b/crates/erp-server/src/main.rs index 2f20f2b..bc9cdf5 100644 --- a/crates/erp-server/src/main.rs +++ b/crates/erp-server/src/main.rs @@ -161,6 +161,90 @@ struct WorkflowApiDoc; )] struct MessageApiDoc; +/// Diary 模块的 OpenAPI 路径收集 +#[cfg(feature = "diary")] +#[derive(OpenApi)] +#[openapi( + paths( + erp_diary::handler::journal_handler::create_journal, + erp_diary::handler::journal_handler::get_journal, + erp_diary::handler::journal_handler::update_journal, + erp_diary::handler::journal_handler::delete_journal, + erp_diary::handler::journal_handler::list_journals, + erp_diary::handler::class_handler::create_class, + erp_diary::handler::class_handler::join_class, + erp_diary::handler::class_handler::get_class, + erp_diary::handler::class_handler::list_members, + erp_diary::handler::class_handler::my_classes, + erp_diary::handler::class_handler::list_all_classes, + erp_diary::handler::class_handler::update_class, + erp_diary::handler::class_handler::deactivate_class, + erp_diary::handler::class_handler::reset_class_code, + erp_diary::handler::comment_handler::create_comment, + erp_diary::handler::comment_handler::list_comments, + erp_diary::handler::comment_handler::delete_comment, + erp_diary::handler::topic_handler::assign_topic, + erp_diary::handler::topic_handler::list_topics, + erp_diary::handler::topic_handler::update_topic, + erp_diary::handler::topic_handler::deactivate_topic, + erp_diary::handler::sticker_handler::list_sticker_packs, + erp_diary::handler::sticker_handler::list_stickers_in_pack, + erp_diary::handler::sticker_handler::create_sticker_pack, + erp_diary::handler::sticker_handler::update_sticker_pack, + erp_diary::handler::sticker_handler::delete_sticker_pack, + erp_diary::handler::sticker_handler::create_sticker, + erp_diary::handler::sticker_handler::list_templates, + erp_diary::handler::sticker_handler::get_template, + erp_diary::handler::achievement_handler::list_achievements, + erp_diary::handler::achievement_handler::unlock_achievement, + erp_diary::handler::stats_handler::get_mood_stats, + erp_diary::handler::sync_handler::sync_journals, + erp_diary::handler::parent_handler::bind_child, + erp_diary::handler::parent_handler::list_children, + erp_diary::handler::parent_handler::get_child_journals, + erp_diary::handler::parent_handler::export_child_data, + erp_diary::handler::parent_handler::delete_child_data, + erp_diary::handler::parent_handler::unbind_child, + erp_diary::handler::parent_handler::list_pending_bindings, + erp_diary::handler::parent_handler::confirm_binding, + erp_diary::handler::parent_handler::reject_binding, + ), + components(schemas( + erp_diary::dto::CreateJournalReq, + erp_diary::dto::UpdateJournalReq, + erp_diary::dto::JournalResp, + erp_diary::dto::CreateClassReq, + erp_diary::dto::JoinClassReq, + erp_diary::dto::UpdateClassReq, + erp_diary::dto::ResetClassCodeResp, + erp_diary::dto::ClassResp, + erp_diary::dto::SyncReq, + erp_diary::dto::SyncResp, + erp_diary::dto::ConflictInfo, + erp_diary::dto::ClassMemberResp, + erp_diary::dto::CreateTopicReq, + erp_diary::dto::TopicResp, + erp_diary::dto::UpdateTopicReq, + erp_diary::dto::CreateCommentReq, + erp_diary::dto::CommentResp, + erp_diary::dto::NotificationPayload, + erp_diary::dto::MoodStatsResp, + erp_diary::dto::MoodCount, + erp_diary::dto::StickerPackResp, + erp_diary::dto::StickerResp, + erp_diary::dto::TemplateResp, + erp_diary::dto::AchievementResp, + erp_diary::dto::CreateStickerPackReq, + erp_diary::dto::UpdateStickerPackReq, + erp_diary::dto::CreateStickerReq, + erp_diary::handler::parent_handler::BindChildReq, + erp_diary::handler::parent_handler::DeleteChildDataReq, + erp_diary::handler::parent_handler::BindingResp, + erp_diary::handler::parent_handler::DeleteResultResp, + )) +)] +struct DiaryApiDoc; + use axum::Router; use axum::middleware as axum_middleware; use config::AppConfig; diff --git a/docs/audit-2026-06-03-full-report.md b/docs/audit-2026-06-03-full-report.md new file mode 100644 index 0000000..847f5a2 --- /dev/null +++ b/docs/audit-2026-06-03-full-report.md @@ -0,0 +1,395 @@ +# 暖记 (Nuanji) 全系统穷尽审计报告 + +> **审计日期**: 2026-06-03 +> **代码规模**: ~126,000 行 / 560+ 文件 +> **审计方法**: 10 维度 × 2 智能体 = 20 个并行审计智能体 +> **审计范围**: 安全 → 后端架构 → 前端质量 → 数据库 → API设计 → 基础设施 → 文档 → 性能 → 跨层一致性 + +--- + +## 执行摘要 + +### 总体统计 + +| 维度 | CRITICAL | HIGH | MEDIUM | LOW/INFO | 合计 | +|------|----------|------|--------|----------|------| +| 🔒 安全 (步骤1) | 3 | 9 | 10 | 6 | 28 | +| 🏗️ 后端架构 (步骤2) | 1 | 11 | 12 | 9 | 33 | +| 📱 前端质量 (步骤3) | 1 | 2 | 17 | 10 | 30 | +| 🗄️ 数据库 (步骤4) | 3 | 8 | 11 | 7 | 29 | +| 🌐 API设计 (步骤5) | 6 | 8 | 10 | 7 | 31 | +| 🐳 基础设施 (步骤6) | 9 | 13 | 16 | 14 | 52 | +| 📚 文档 (步骤7) | 7 | 16 | 17 | 17 | 57 | +| ⚡ 性能 (步骤8) | 5 | 12 | 17 | 13 | 47 | +| 🔗 跨层一致性 (步骤9) | 7 | 11 | 13 | 7 | 38 | +| **合计** | **42** | **90** | **123** | **90** | **345** | + +### 风险等级分布 + +``` +CRITICAL ██████████████████████ 42 (12%) — 必须立即修复 +HIGH █████████████████████████████████████████████ 90 (26%) — 本周内修复 +MEDIUM ██████████████████████████████████████████████████████████████████ 123 (36%) — 规划修复 +LOW/INFO ████████████████████████████████████████████ 90 (26%) — 记录跟踪 +``` + +### 系统成熟度评估 + +| 领域 | 评分 | 说明 | +|------|------|------| +| 架构设计 | ★★★★☆ | 模块边界清晰，多租户架构合理 | +| 安全基础 | ★★★☆☆ | 加密体系完善，但输入验证/权限覆盖有缺口 | +| 数据库设计 | ★★★★☆ | Entity 一致性优秀，RLS 有 bug 需修 | +| API 设计 | ★★★☆☆ | DTO 验证系统性缺失，REST 不规范 | +| 前端质量 | ★★★☆☆ | 手写引擎优秀，但 BLoC/无障碍需改进 | +| 基础设施 | ★★★☆☆ | Docker/备份设计好，CI/CD 和密钥管理弱 | +| 测试覆盖 | ★★☆☆☆ | 单元测试尚可，集成/E2E 严重不足 | +| 文档准确性 | ★★★★☆ | 总体准确，细节有偏差 | + +--- + +## 🔴 CRITICAL 发现汇总 (37 项) + +### 按影响域分类 + +#### A. 数据安全与隐私 (12 项) + +| ID | 问题 | 来源 | 影响 | +|----|------|------|------| +| S-02 | **内容安全过滤器为空** — SENSITIVE_WORDS 无词条，所有内容通过检查 | 安全 | 儿童可能接触不安全内容 | +| S-03 | **缺少家长同意验证** — 违反 PIPL 第28条 | 安全 | 法律合规风险 | +| S-10 | **家长绑定无验证** — 任何人可绑定任何孩子 | 安全 | 儿童数据泄露 | +| 6b-C01 | **Flutter 默认 HTTP 明文传输** | 配置 | JWT/日记内容可被截获 | +| 6b-C02 | **Flutter 无 SSL 证书固定** | 配置 | 中间人攻击风险 | +| 6b-C03 | **管理端 JWT 存 localStorage** | 配置 | XSS 可窃取 token | +| 6b-C04 | **Docker 默认密码硬编码** | 配置 | 生产环境安全风险 | +| 6a-C01 | **.env.example 包含默认密码** | Docker | 易被直接用于生产 | +| 6a-C02 | **dev.sh 硬编码 JWT Secret/KEK** | 脚本 | 泄露到版本控制 | +| 6a-C04 | **verify.sh 硬编码生产数据库密码** | 脚本 | 凭据泄露 | +| 5b-C01 | **审计日志端点无权限守卫** | API | 任何用户可查看审计日志 | +| 5b-C02 | **文件上传端点无权限守卫** | API | 任何用户可上传文件 | + +#### B. 数据完整性 (10 项) + +| ID | 问题 | 来源 | 影响 | +|----|------|------|------| +| 4a-C01 | **RLS 变量名不一致** — `app.current_tenant` vs `app.current_tenant_id` | 数据库 | 15 张日记表 RLS 完全失效/锁死 | +| 4a-C02 | **`diary.comment.delete` 权限未定义** | 种子数据 | teacher 永远无删除评语权限 | +| 4b-C01 | 同 4a-C01，确认问题存在 | 数据库 | — | +| 4b-C02 | **m000183 使用 FORCE RLS 与基座不一致** | 数据库 | 变量名错误时完全阻断访问 | +| 8a-C01 | **mood_stats 全量加载所有日记** | 性能 | 活跃用户 OOM | +| 8a-C02 | **sync_service 循环内 N+1 查询** | 性能 | 50 条变更 = 100 次 DB 往返 | +| 8a-C03 | **parent_service 逐条软删除** | 性能 | PIPL 删除不原子 | +| 8a-C04 | **sticker_service N+1 查询贴纸数量** | 性能 | 20 个包 = 21 次查询 | +| 8b-R01 | **笔画缓存 use-after-dispose** | Flutter | 撤销/重做后笔画内容丢失 | +| 9a-SYNC-01 | **Flutter 与 Rust 使用两套不兼容同步协议** | 跨层 | 同步机制完全断裂 | + +#### C. 输入验证系统性缺失 (8 项) + +| ID | 问题 | 来源 | 影响 | +|----|------|------|------| +| 5a-C01 | **erp-diary 所有 DTO 无 Validate derive** | API | 无字段级约束 | +| 5a-C02 | **DTO 字段无长度/范围约束** | API | 儿童/恶意输入可提交超大 payload | +| 5a-C03 | **所有 handler 未调用 .validate()** | API | 即使加 Validate 也形同虚设 | +| 5b-C03 | **OpenAPI 文档完全缺失 Diary 模块** | API | ~30 个端点不在文档中 | +| 7b-C01 | **班级码实际十六进制(16^6)非字母数字(62^6)** | 文档 | 安全强度低 3386 倍 | +| 7b-C02 | 同 5a-C01，确认 Validate 缺失 | 文档 | — | +| 9a-AUTH-01 | **Flutter 无 Token 自动刷新** | 跨层 | Token 过期直接踢回登录 | +| 9a-TENANT-01 | **Flutter 不传递 tenant_id** | 跨层 | 多租户上线需大规模改造 | + +#### D. 端到端同步断裂 (4 项) + +| ID | 问题 | 来源 | 影响 | +|----|------|------|------| +| 9a-SYNC-01 | Flutter SyncEngine 与 Rust SyncService 协议不兼容 | 跨层 | 同步功能完全断裂 | +| 9a-SYNC-02 | SyncEngine 超限后直接丢弃操作 | 跨层 | 用户数据静默丢失 | +| 9a-SYNC-03 | SyncEngine 不使用后端 SyncChange 格式 | 跨层 | 数据格式不兼容 | +| 9a-SYNC-04 | SyncEngine 不发送 version 字段 | 跨层 | 乐观锁失效 | + +--- + +## 🟠 HIGH 发现汇总 (81 项) + +### 安全 (9 项) + +| ID | 问题 | 文件 | +|----|------|------| +| S-04 | JWT 缺少 iss/aud claims | `token_service.rs` | +| S-05 | RefreshReq 无输入验证 | `dto.rs`, `auth_handler.rs` | +| S-06 | 开发 KEK 硬编码 | `crypto/mod.rs` | +| S-07 | **日记列表 IDOR** — 任何用户可查看他人日记 | `journal_handler.rs` | +| S-08 | 无数据保留策略 | `parent_service.rs` | +| S-09 | **无账号注销机制** | 全局缺失 | +| S-11 | **Flutter API 默认 HTTP** | `api_client.dart` | +| S-12 | 默认存储密钥硬编码 | `config.rs` | + +### 后端架构 (11 项) + +| ID | 问题 | 文件 | +|----|------|------| +| B-02 | DiaryEvent 枚举是死代码 | `event.rs` | +| B-03 | **所有请求 DTO 缺少 Validate** | `dto.rs` | +| B-04 | DiaryModule 未实现 register_event_handlers | `lib.rs` | +| B-05 | **日记端点缺失于 OpenAPI spec** | `main.rs` | +| B-06 | generate_unique_code 未按 tenant_id 过滤 | `class_service.rs` | +| B-07 | create_class/join_class 两次写入无事务 | `class_service.rs` | +| B-08 | sticker_service 缺少乐观锁 | `sticker_service.rs` | +| B-09 | sync_service 版本冲突丢弃 journal_id | `sync_service.rs` | +| B-10 | sync_service 返回客户端刚提交的数据 | `sync_service.rs` | +| B-11 | parent_service 删除操作无事务 | `parent_service.rs` | + +### 数据库 (8 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 4a-H01 | journal_entries.class_id 无外键 | Entity 声明但迁移未实现 | +| 4a-H03 | 外键无 tenant_id 联合约束 | 多租户 FK 保护不足 | +| 4a-H04 | class_members.user_id 无外键 | 用户删除后孤儿数据 | +| 4a-H05 | parent_child_bindings 无外键 | Entity Relation 为空 | +| 4b-H01 | processed_events 无 RLS 保护 | 跨租户数据可见 | +| 4b-H03 | diary.comment.delete 权限未定义 | 同 4a-C02 | +| 4b-H05 | 外键列缺少 tenant_id 前缀索引 | RLS 查询效率低 | +| 4b-H06 | domain_events_archive 无 tenant_id 索引 | 归档查询低效 | + +### API 设计 (8 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 5a-H01 | 创建资源返回 200 而非 201 | ~15 个端点 | +| 5a-H03 | update_user/update_role 未调用 validate() | auth 模块也不完整 | +| 5a-H04 | AssignRolesReq 无 Validate | 空数组可致用户失角色 | +| 5a-H07 | SyncReq.changes 无大小限制 | DoS 风险 | +| 5b-H01 | `user.reset-password` 未在 permissions.yaml 注册 | 权限注册不一致 | +| 5b-H02 | `tenant.manage` 和 `system.analytics.submit` 永远 403 | 权限从未注册 | +| 5b-H03 | OpenAPI 缺少 Plugin/upload/crypto_admin 端点 | 文档不完整 | +| 5b-H05 | 微信登录缺速率限制 | API 配额消耗风险 | + +### 基础设施 (13 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 6a-H01 | **CI 缺少管理端前端检查** | React 代码可未经检查合入 | +| 6a-H02 | 无 CI/CD 部署流程 | 部署全手动 | +| 6a-H03 | CI 不验证 Docker 构建 | Dockerfile 可能无法构建 | +| 6a-H04 | Redis 健康检查暴露密码 | `ps aux` 可见 | +| 6a-H06 | Prometheus 引用不存在的 exporter | 持续报错 | +| 6a-H07 | Grafana provisioning 目录为空 | 无预配置仪表盘 | +| 6b-H01 | 根目录 CORS allowed_origins="*" | 与 erp-server 配置矛盾 | +| 6b-H02 | rand crate 0.8 过时 | 密钥生成应升级 0.9 | +| 6b-H03 | AES-CBC 用于加密 | 应统一 AES-GCM | +| 6b-H04 | Web 依赖未锁定精确版本 | ^ 语义范围 | +| 6b-H05 | 管理端 URL 传递 JWT token | 浏览器历史/日志泄露 | +| 6b-H06 | Grafana 密码默认为空 | 生产环境风险 | + +### 文档 (7 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 7b-H01 | erp-diary 代码量 7021 行 vs 声明 5800 行 | 超出 21% | +| 7b-H03 | school_class.codeMaxUses 未实现 | 设计规格不一致 | +| 7b-H04 | TeacherProfile.verificationStatus 未实现 | 设计规格不一致 | +| 7b-H05 | 内容安全词库为空 | 与 CLAUDE.md 声明不符 | +| 7b-H06 | discover 功能目录存在但属 Phase 2 | 违反原则 | +| 7b-H07 | Flutter 无 freezed 代码生成 | 与 CLAUDE.md 声明不符 | + +### 性能 (12 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 8a-H01 | mood_stats 全量加载后内存聚合 | 应使用 SQL GROUP BY | +| 8a-H02 | EventBus 每次 3 次 DB 操作 | 无事务包裹 | +| 8a-H03 | sync_service 无事务 | 多条变更部分成功风险 | +| 8a-H04 | export_child_data 无分页 | 潜在 OOM | +| 8a-H05 | list_all_classes/list_members 无分页 | 数据增长后退化 | +| 8b-D01 | JournalEntryCollection 缺 authorId/dateEpoch 索引 | 全表扫描 | +| 8b-D02 | Isar 分页在 Dart 层而非数据库层 | 内存浪费 | +| 8b-D03 | MonthlyPage N+1 查询元素 | 30 篇 = 31 次查询 | +| 8b-N01 | SyncEngine 串行无合并 | 10 次自动保存 = 10 次 HTTP | +| 8b-N02 | _persistState 每元素单独事务 | 10 元素 = 10 次事务 | +| 8b-M01 | 首页日记列表用 Column 非 ListView.builder | 无懒加载 | +| 8b-M02 | 笔画光栅化用全画布尺寸 | 50 条笔画 = 1.6GB GPU | + +### 跨层一致性 (11 项) + +| ID | 问题 | 说明 | +|----|------|------| +| 9a-AUTH-02 | Flutter client_type='mobile' 后端不识别 | 潜在不一致 | +| 9a-SYNC-02 | SyncEngine 丢弃冲突数据 | 数据丢失 | +| 9a-SYNC-03 | 同步数据格式不兼容 | 两端协议断裂 | +| 9a-SYNC-04 | SyncEngine 不发送 version | 乐观锁失效 | +| 9a-TENANT-02 | 管理端不传递 tenant_id | 多租户切换缺失 | +| 9a-CROSS-01 | Flutter 无前端权限检查 | 后端 403 用户困惑 | +| 9b (汇总) | erp-diary 无集成测试 | 核心业务无 E2E 验证 | +| 9b (汇总) | Flutter 无 BLoC 测试 | 状态逻辑未验证 | +| 9b (汇总) | 管理端无组件测试 | UI 未验证 | +| 9b (汇总) | 管理端-后端 API 不匹配 | 贴纸更新/班级列表等 | + +--- + +## 🟢 做得好的方面 (亮点) + +### 安全 + +- ✅ AES-256-GCM + KEK/DEK 分层加密架构达到银行级别 +- ✅ Argon2 密码哈希 + Refresh Token 轮换 +- ✅ 审计日志哈希链防篡改 +- ✅ 生产环境拒绝默认密钥启动 (cfg! 宏保护) +- ✅ Flutter 使用 flutter_secure_storage 加密存储 token + +### 架构 + +- ✅ Feature Flag 干净隔离日记模块 +- ✅ 所有 15 个 Entity 标准字段完全一致 (id/tenant_id/created_at/.../version) +- ✅ 15 张表迁移字段与 Entity 字段 **100% 一一对应** +- ✅ 模块边界正确: erp-diary 仅依赖 erp-core + erp-auth +- ✅ 统一 ApiResponse/PaginatedResponse 信封格式 + +### 前端 + +- ✅ 手写引擎双层 Canvas + Listener 方案达到教科书级 +- ✅ shouldRepaint 守卫全部正确 +- ✅ 笔画数据保真 (x/y/pressure/timestamp) +- ✅ 掌心抑制已实现 +- ✅ 无内存泄漏 (Controller/Stream/Timer 全部正确 dispose) +- ✅ 响应式布局三档正确 + +### 基础设施 + +- ✅ Docker 多阶段构建 + 非特权用户 +- ✅ Nginx 安全头配置全面 (HSTS/CSP/X-Frame-Options) +- ✅ 备份加密 (AES-256-CBC + GPG) + 自动清理 +- ✅ Prometheus 告警规则分类清晰 + +--- + +## 🔧 修复路线图 + +### Phase 0: 紧急修复 (本周) + +> 阻断性问题，影响数据安全/完整性 + +| # | 问题 ID | 修复项 | 预估工时 | +|---|---------|--------|---------| +| 1 | 4a-C01 | **修复 RLS 变量名**: `app.current_tenant` → `app.current_tenant_id` + 添加空值保护 | 1h | +| 2 | S-02 | **填充内容安全词库** + 在日记创建/同步中调用 | 4h | +| 3 | S-07 | **修复日记列表 IDOR**: 按 author_id 限制访问 | 2h | +| 4 | 5b-C01/02 | **添加权限守卫**: 审计日志 + 文件上传 | 1h | +| 5 | B-01 | **修复 class_service unwrap()**: 替换为安全错误处理 | 0.5h | +| 6 | B-07/B-11 | **添加事务**: create_class/join_class/parent 删除 | 3h | +| 7 | 8b-R01 | **修复笔画缓存 use-after-dispose** | 2h | +| **合计** | | | **~13.5h** | + +### Phase 1: 安全加固 (第 1-2 周) + +| # | 问题 ID | 修复项 | 预估工时 | +|---|---------|--------|---------| +| 1 | S-03 | 实现家长同意验证流程 | 8h | +| 2 | S-10 | 实现家长绑定实际验证流程 | 4h | +| 3 | S-01 | Token 黑名单改用 SHA-256 | 1h | +| 4 | 5a-C01/02/03 | **为所有 DTO 添加 Validate + handler 调用 validate()** | 8h | +| 5 | 6b-C01 | Flutter 强制 HTTPS + 证书固定 | 4h | +| 6 | 7b-C01 | 班级码改用字母数字混合 | 2h | +| 7 | 9a-AUTH-01 | Flutter 添加 Token 自动刷新拦截器 | 4h | +| **合计** | | | **~31h** | + +### Phase 2: 性能优化 (第 3-4 周) + +| # | 问题 ID | 修复项 | 预估工时 | +|---|---------|--------|---------| +| 1 | 8a-C01-04 | 修复后端 4 个 N+1 查询 | 8h | +| 2 | 8b-D01-03 | 修复 Isar 索引 + 分页 + N+1 | 6h | +| 3 | 8a-H01 | mood_stats 改用 SQL GROUP BY | 2h | +| 4 | 8b-M02 | 笔画光栅化改为 BBox 裁剪 | 4h | +| 5 | 8b-N01 | SyncEngine 合并同资源操作 | 4h | +| **合计** | | | **~24h** | + +### Phase 3: 质量提升 (第 5-8 周) + +| # | 问题 ID | 修复项 | +|---|---------|--------| +| 1 | 9b 全部 | 补充后端集成测试 + Flutter BLoC 测试 | +| 2 | 9a-SYNC-01 | 统一同步协议 | +| 3 | 5a-H01 | 创建端点改返回 201 | +| 4 | 5b-C03 | 添加 DiaryApiDoc OpenAPI 文档 | +| 5 | F-01 | 分阶段添加无障碍性 Semantics | +| 6 | B-03 | DiaryEvent 枚举接入 EventBus | + +--- + +## 📊 各模块 CRITICAL+HIGH 热力图 + +``` + CRITICAL HIGH 风险等级 + ────────────────────────────────────────── + 安全 ████████ ████ 🔴 极高 + 后端架构 ███ ██████ 🟠 高 + 数据库 █████ ████ 🔴 极高 + API 设计 ████████ ████ 🔴 极高 + 基础设施 ████████ ██████ 🔴 极高 + 文档 ██ ████ 🟡 中 + 性能 ██████ ██████ 🔴 极高 + 跨层一致性 ████████ ██████ 🔴 极高 + 前端质量 █ █ 🟡 中 +``` + +--- + +## 结论 + +暖记项目的**架构设计和基础建设质量优秀**（模块边界、加密体系、多租户框架、手写引擎），但在**实施完整性和工程纪律**方面存在系统性缺口： + +1. **输入验证系统性缺失** — erp-diary 全部 DTO 无 Validate，是最高频问题 +2. **RLS 变量名 bug** — 一个拼写错误导致 15 张表 RLS 失效，是最高优先修复 +3. **同步协议断裂** — Flutter 和 Rust 实现了两套不兼容的同步机制 +4. **权限覆盖不完整** — 审计日志/文件上传无守卫，多个权限码未注册 +5. **性能 N+1 查询** — 后端 4 处 + Flutter 3 处 N+1，随数据增长将严重影响体验 + +**建议**: 按 Phase 0 → Phase 3 路线图推进修复，优先解决数据安全和完整性问题。 + +--- + +## 附录 A: 步骤 7a — Wiki + 规划文档准确性审计 + +> 审计范围: wiki/ (7文件), plans/ (6文件), docs/tech-debt-board.md + +### CRITICAL — 文档数字严重过时 + +| ID | 问题 | 文件 | 说明 | +|----|------|------|------| +| 7a-C1 | **erp-diary 代码量严重过时** | wiki/index.md, architecture.md, erp-diary.md | 三处文档分别声称 5,108/5,100/5,500 行。实际 **7,021 行**。handler/service/dto 行数全部过时 | +| 7a-C2 | **前端测试状态严重错误** | wiki/frontend.md, tech-debt-board.md, project-health.md | 声称"前端测试为零"。实际已有 **8 个测试文件、85 个测试用例** (4c743e1 起存在) | +| 7a-C3 | **Dart 文件数与代码量过时** | wiki/index.md | 声称 74 个文件/19,500 行。实际 **100 个文件/29,617 行**，偏差超 50% | +| 7a-C4 | **Git 提交数过时** | wiki/index.md | 声称 22 次提交。实际 **69 次提交**，基线 8111471 → HEAD d482497 | +| 7a-C5 | **管理端 TS 文件数过时** | wiki/index.md | 声称约 317 个。实际 **143 个**，差异极大 | + +### HIGH — 重要不准确 + +| ID | 问题 | 文件 | +|----|------|------| +| 7a-H1 | Feature Flag 状态自相矛盾 — 实际已落地 | wiki/architecture.md | +| 7a-H2 | Dockerfile 不存在的描述已过时 | architecture.md, erp-diary.md, tech-debt-board.md | +| 7a-H3 | isar_database.dart 行数声称 72 行实际 14 行 | wiki/data-layer.md | +| 7a-H4 | data-layer.md 多个文件行数全部偏低 | wiki/data-layer.md | +| 7a-H5 | erp-diary.md 缺少 parent_handler 和 parent_service | wiki/erp-diary.md | +| 7a-H6 | admin-web.md 描述不存在的目录 (api/ai/, Copilot/) | wiki/admin-web.md | +| 7a-H7 | tech-debt-board TD-5 "前端测试为零" 严重过时 | docs/tech-debt-board.md | +| 7a-H8 | tech-debt-board TD-1 authorId 已部分修复但状态未更新 | docs/tech-debt-board.md | +| 7a-H9 | tech-debt-board TD-3 Docker 部署描述不完整 | docs/tech-debt-board.md | + +### 做得好的方面 (文档体系) + +- ✅ 文档结构规范 — 所有 wiki 页面遵循 5 节结构（设计决策/关键文件/代码逻辑/活跃问题/变更记录） +- ✅ 交叉引用体系 — `[[wikilink]]` 引用 + 症状导航表构成知识网络 +- ✅ 集成契约表 — 清晰描述模块间调用方向、接口和触发时机 +- ✅ 不变量标注 — 闪电符号标记开发守则（"所有查询带 tenant_id"等） +- ✅ 变更记录 — 每个文档底部有 commit hash 可追溯 +- ✅ 历史教训记录 — 记录具体踩坑经历（Isar import、GestureDetector 延迟等） + +### 文档修复建议 + +1. 以 wiki/index.md 的"关键数字"表为单一事实来源，其他页面引用而非重复声明 +2. 更新 wiki/index.md 关键数字表（提交数 69, Dart 文件 100, erp-diary 行 7,021） +3. 更新 wiki/erp-diary.md 的代码量分布表和 Service/Handler 清单 +4. 更新 docs/tech-debt-board.md 的 TD-5（已有测试）、TD-3（Dockerfile 已存在） +5. 更新 wiki/architecture.md 的 Feature Flag 状态和 Docker 部署描述 +6. 更新 wiki/admin-web.md 的目录树和 API 目录描述