Code Review: Uncommitted Changes

代码评审：未提交变更

Perform a comprehensive code review of all uncommitted git changes following EasyPlatform standards.

按照EasyPlatform标准对所有Git未提交变更进行全面的代码评审。

Summary

概述

Goal: Review all uncommitted changes via a report-driven four-phase process before commit.

Phase	Action	Key Notes
0	Collect changes & create report	`git status` , `git diff HEAD` , create `plans/reports/code-review-*.md`
1	File-by-file review	Read each diff, update report with summary/purpose/issues
2	Holistic review	Re-read accumulated report for architecture coherence
3	Finalize findings	Critical issues, recommendations, suggestions, commit message

Key Principles:

Be skeptical. Critical thinking. Everything needs traced proof. — Never accept code at face value; verify claims against actual behavior, trace data flow end-to-end, and demand evidence (file:line references, grep results, runtime confirmation) for every finding
Ensure code quality: no flaws, no bugs — Verify correctness of logic, data flow, edge cases, and error handling. Flag anything that could fail at runtime
Clean code and DRY — No duplication, clear naming, single responsibility, early returns. Code should be self-documenting
Follow existing conventions — Match project patterns, naming style, file organization, and architectural decisions already established in the codebase. Grep for similar implementations before flagging deviations
Docs must match code — If changes affect behavior, APIs, or features, verify related docs are updated: feature docs (
```
docs/business-features/
```
), test specs (
```
docs/test-specs/
```
), CHANGELOG, README, architecture docs, and inline code comments. Flag any doc that describes old behavior
Build report incrementally — update after EACH file, not at the end
Check logic placement in lowest layer (Entity > Service > Component)
Always suggest conventional commit message based on changes

目标： 通过报告驱动的四阶段流程，在提交前评审所有未提交的变更。

阶段	操作	关键说明
0	收集变更并创建报告	`git status` 、 `git diff HEAD` ，创建 `plans/reports/code-review-*.md` 文件
1	逐文件评审	查看每个差异，在报告中更新摘要/目的/问题
2	整体评审	重新阅读已整理的报告，检查架构一致性
3	确定最终评审结果	关键问题、建议、改进方案、提交信息

核心原则：

保持质疑，批判性思考。所有内容都需要可追溯的证据。 — 绝不表面接受代码；对照实际行为验证声明，端到端追踪数据流，每个评审结果都需要提供证据（文件:行号引用、grep结果、运行时确认）
确保代码质量：无缺陷、无Bug — 验证逻辑、数据流、边缘情况和错误处理的正确性。标记任何可能在运行时失败的内容
简洁代码与DRY原则 — 无重复代码、命名清晰、单一职责、提前返回。代码应具备自文档性
遵循现有约定 — 匹配代码库中已确立的项目模式、命名风格、文件组织和架构决策。标记偏差前先搜索类似实现
文档必须与代码匹配 — 如果变更影响行为、API或功能，验证相关文档是否已更新：功能文档（
```
docs/business-features/
```
）、测试规范（
```
docs/test-specs/
```
）、CHANGELOG、README、架构文档和内联代码注释。标记任何描述旧行为的文档
逐步构建报告 — 每完成一个文件的评审后立即更新报告，而非在最后统一更新
检查逻辑是否放置在最低层级（实体 > 服务 > 组件）
始终根据变更内容建议符合规范的提交信息

Review Approach (Report-Driven Four-Phase - CRITICAL)

评审方法（报告驱动的四阶段 - 至关重要）

⛔ MANDATORY FIRST: Create Todo Tasks for Review Phases Before starting, call TodoWrite with:

[Review Phase 0] Get git changes and create report file

- in_progress

[Review Phase 1] Review file-by-file and update report

- pending

[Review Phase 2] Re-read report for holistic assessment

- pending

[Review Phase 3] Generate final review findings

- pending

Update todo status as each phase completes. This ensures review is tracked.

⛔ 强制第一步：为评审阶段创建待办任务 开始前，创建以下待办任务：

[评审阶段0] 获取Git变更并创建报告文件

- 进行中

[评审阶段1] 逐文件评审并更新报告

- 待处理

[评审阶段2] 重新阅读报告进行整体评估

- 待处理

[评审阶段3] 生成最终评审结果

- 待处理

完成每个阶段后更新待办状态。这确保评审过程可追踪。

Phase 0: Get Changes & Create Report

阶段0：获取变更并创建报告

0.1 Get Change Summary

0.1 获取变更摘要

bash

undefined

bash

undefined

See all changed files

查看所有已变更文件

git status

See actual changes (staged and unstaged)

查看实际变更（暂存和未暂存）

git diff HEAD

undefined

git diff HEAD

undefined

0.2 Create Report File

0.2 创建报告文件

Create

plans/reports/code-review-{date}-{slug}.md

Initialize with Scope (list of changed files), Change Type (feature/bugfix/refactor)

创建

plans/reports/code-review-{date}-{slug}.md

文件

初始化内容包含范围（已变更文件列表）、变更类型（功能/修复/重构）

Phase 1: File-by-File Review (Build Report Incrementally)

阶段1：逐文件评审（逐步构建报告）

For EACH changed file, read the diff and immediately update report with:

File path and change type (added/modified/deleted)
Change Summary: what was modified/added/deleted
Purpose: why this change exists (infer from context)
Issues Found: naming, typing, responsibility, patterns
Continue to next file, repeat

对于每个已变更文件，查看差异并立即更新报告：

文件路径和变更类型（新增/修改/删除）
变更摘要：修改/新增/删除了什么
目的：该变更存在的原因（从上下文推断）
发现的问题：命名、类型、职责、模式
继续下一个文件，重复上述步骤

Review Checklist Per File

单文件评审检查清单

Architecture Compliance

架构合规性

Follows Clean Architecture layers (Domain, Application, Persistence, Service)
Uses correct repository pattern (I{Service}RootRepository<T>)
CQRS pattern: Command/Query + Handler + Result in ONE file
No cross-service direct database access

遵循整洁架构分层（领域层、应用层、持久化层、服务层）
使用正确的仓储模式（I{Service}RootRepository<T>）
CQRS模式：命令/查询 + 处理器 + 结果在同一个文件中
无跨服务直接数据库访问

Code Quality

代码质量

Single Responsibility Principle
No code duplication (DRY)
Appropriate error handling with PlatformValidationResult
No magic numbers/strings (extract to named constants)
Type annotations on all functions
No implicit any types
Early returns/guard clauses used

单一职责原则
无代码重复（DRY原则）
使用PlatformValidationResult进行适当的错误处理
无魔法数字/字符串（提取为命名常量）
所有函数都有类型注解
无隐式any类型
使用提前返回/守卫子句

Naming Conventions

命名约定

Names reveal intent (WHAT not HOW)
Specific names, not generic (
```
employeeRecords
```
not
```
data
```
)
Methods: Verb + Noun (
```
getEmployee
```
,
```
validateInput
```
)
Booleans: is/has/can/should prefix (
```
isActive
```
,
```
hasPermission
```
)
No cryptic abbreviations (
```
employeeCount
```
not
```
empCnt
```
)

名称揭示意图（做什么而非怎么做）
具体名称，而非通用名称（
```
employeeRecords
```
而非
```
data
```
）
方法：动词 + 名词（
```
getEmployee
```
、
```
validateInput
```
）
布尔值：以is/has/can/should为前缀（
```
isActive
```
、
```
hasPermission
```
）
无晦涩缩写（
```
employeeCount
```
而非
```
empCnt
```
）

Platform Patterns

平台模式

Uses platform validation fluent API (.And(), .AndAsync())
No direct side effects in command handlers (use entity events)
DTO mapping in DTO classes, not handlers
Static expressions for entity queries

使用平台验证流畅API（.And()、.AndAsync()）
命令处理器中无直接副作用（使用实体事件）
DTO映射在DTO类中完成，而非处理器中
实体查询使用静态表达式

Security

安全性

No hardcoded credentials or secrets
Proper authorization checks
Input validation at boundaries
No SQL injection risks

无硬编码凭据或密钥
适当的授权检查
边界处的输入验证
无SQL注入风险

Performance

性能

No O(n²) complexity (use dictionary for lookups)
No N+1 query patterns (batch load related entities)
Project only needed properties (don't load all then select one)
Pagination for all list queries (never get all without paging)
Parallel queries for independent operations
Appropriate use of async/await
Entity query expressions have database indexes configured
MongoDB collections have
```
Ensure*IndexesAsync()
```
methods
EF Core migrations include indexes for WHERE clause columns

无O(n²)复杂度（使用字典进行查找）
无N+1查询模式（批量加载关联实体）
仅投影所需属性（不要加载全部后再选择单个属性）
所有列表查询都有分页（绝不无分页获取全部数据）
独立操作使用并行查询
适当使用async/await
实体查询表达式已配置数据库索引
MongoDB集合具有
```
Ensure*IndexesAsync()
```
方法
EF Core迁移包含WHERE子句列的索引

Backend-Specific Checks

后端特定检查

CQRS patterns followed correctly
Repository usage (no direct DbContext access)
Entity DTO mapping patterns
Validation using PlatformValidationResult

正确遵循CQRS模式
仓储使用规范（无直接DbContext访问）
实体DTO映射模式
使用PlatformValidationResult进行验证

Frontend-Specific Checks

前端特定检查

Component base class inheritance correct (AppBase*)
State management via PlatformVmStore
Memory leaks (missing .pipe(this.untilDestroyed()))
Template binding issues
BEM classes on ALL template elements

组件基类继承正确（AppBase*）
通过PlatformVmStore进行状态管理
无内存泄漏（未缺失.pipe(this.untilDestroyed())）
模板绑定问题
所有模板元素都使用BEM类

Common Anti-Patterns to Flag

需要标记的常见反模式

Unused imports or variables
Console.log/Debug.WriteLine left in code
Hardcoded values that should be configuration
Missing async/await keywords
Incorrect exception handling
Missing validation

Test-Specific Checks (When Diff Includes Test Files)

测试特定检查（当差异包含测试文件时）

Apply these checks ONLY to files matching

*.Tests.*/*.cs

or

e2e/tests/**/*.spec.ts

:

仅对匹配

*.Tests.*/*.cs

或

e2e/tests/**/*.spec.ts

的文件应用以下检查：

Assertion Quality

断言质量

Every mutation test (create/update/delete) asserts at least one domain field, not just HTTP status
Preferred: follow-up query verification after mutations (proves DB round-trip)
Validation error tests parse response body and inspect error content (not just
```
IsSuccessStatusCode.Should().BeFalse()
```
)
Setup steps (arrange phase HTTP calls) have status assertion with descriptive
```
because
```
string
Domain boolean flags verified where applicable (
```
wasCreated
```
,
```
wasSoftDeleted
```
,
```
wasRestored
```
)
E2E update tests include post-mutation field re-read (not just
```
waitForLoading()
```
)

每个突变测试（创建/更新/删除）至少断言一个领域字段，而非仅HTTP状态码
推荐：突变后进行后续查询验证（证明数据库往返操作成功）
验证错误测试解析响应体并检查错误内容（而非仅
```
IsSuccessStatusCode.Should().BeFalse()
```
）
设置步骤（准备阶段的HTTP调用）带有状态断言和描述性
```
because
```
字符串
适用时验证领域布尔标志（
```
wasCreated
```
、
```
wasSoftDeleted
```
、
```
wasRestored
```
）
E2E更新测试包含突变后的字段重新读取（而非仅
```
waitForLoading()
```
）

Data Verification

数据验证

After create: asserts
```
id
```
not null + at least 1 domain field matches input
After update: asserts same
```
id
```
retained + at least 1 changed field
After delete: asserts domain flag or absence from list
Search tests: verify matched item contains search term (not just count > 0)

创建后：断言
```
id
```
不为空 + 至少一个领域字段与输入匹配
更新后：断言
```
id
```
保持不变 + 至少一个字段已变更
删除后：断言领域标志或列表中不存在该条目
搜索测试：验证匹配项包含搜索词（而非仅计数>0）

Test Structure

测试结构

TC-ID annotation present (
```
[Trait("TestCase", "...")]
```
or TC-ID in test title)
No hardcoded test data (uses
```
TestDataHelper
```
/
```
createTestSnippet()
```
)
Cleanup tracked in
```
currentTestData
```
(E2E) or UUID-isolated (integration)
```
because
```
strings on FluentAssertions calls (C#) are descriptive and unique

存在TC-ID注解（
```
[Trait("TestCase", "...")]
```
或测试标题中包含TC-ID）
无硬编码测试数据（使用
```
TestDataHelper
```
/
```
createTestSnippet()
```
）
清理工作在
```
currentTestData
```
（E2E）或UUID隔离（集成测试）中跟踪
FluentAssertions调用（C#）的
```
because
```
字符串具有描述性且唯一

Anti-Patterns to Flag in Tests

测试中需要标记的反模式

Status-only assertions:
```
response.StatusCode.Should().Be(OK)
```
with no body check or follow-up query
Missing intermediate assertions: setup calls without status verification
E2E tests ending at
```
waitForLoading()
```
with no field verification
Validation tests checking only
```
IsSuccessStatusCode.Should().BeFalse()
```
Identical
```
because
```
strings across multiple assertions

仅状态断言：
```
response.StatusCode.Should().Be(OK)
```
但未检查响应体或进行后续查询
缺失中间断言：设置调用未进行状态验证
E2E测试以
```
waitForLoading()
```
结束，未进行字段验证
验证测试仅检查
```
IsSuccessStatusCode.Should().BeFalse()
```
多个断言使用相同的
```
because
```
字符串

Phase 2: Holistic Review (Review the Accumulated Report)

阶段2：整体评审（审阅已整理的报告）

Phase 3: Generate Final Review Result

阶段3：生成最终评审结果

Update report with final sections:

在报告中添加以下最终部分：

Output Format

输出格式

Summary: Brief overall assessment of the changes

Critical Issues: (Must fix before commit)

Issue 1: Description and suggested fix
Issue 2: Description and suggested fix

High Priority: (Should fix)

Issue 1: Description
Issue 2: Description

Suggestions: (Nice to have)

Suggestion 1
Suggestion 2

Positive Notes:

What was done well

Architecture Recommendations: (If applicable)

Recommendation 1

Suggested Commit Message: Based on changes (conventional commit format)

<type>(<scope>): <description>

<body - what and why>

摘要： 对变更的简要整体评估

关键问题：（提交前必须修复）

问题1：描述及建议修复方案
问题2：描述及建议修复方案

高优先级：（应该修复）

问题1：描述
问题2：描述

建议： (锦上添花)

建议1
建议2

积极评价：

做得好的地方

架构建议：（如适用）

建议1

建议提交信息： 根据变更内容（符合规范的提交格式）

<类型>(<范围>): <描述>

<正文 - 做了什么和为什么>

IMPORTANT Task Planning Notes

重要的任务规划说明

Always plan and break many small todo tasks
Always add a final review todo task to review the works done at the end to find any fix or enhancement needed

始终规划并拆分为多个小待办任务
始终添加一个最终评审待办任务，在最后审阅已完成的工作，以发现任何需要修复或增强的内容

review-changes

Original

Translation

Code Review: Uncommitted Changes

代码评审：未提交变更

Summary

概述

Review Approach (Report-Driven Four-Phase - CRITICAL)

评审方法（报告驱动的四阶段 - 至关重要）

Phase 0: Get Changes & Create Report

阶段0：获取变更并创建报告

0.1 Get Change Summary

0.1 获取变更摘要

See all changed files

查看所有已变更文件

See actual changes (staged and unstaged)

查看实际变更（暂存和未暂存）

0.2 Create Report File

0.2 创建报告文件

Phase 1: File-by-File Review (Build Report Incrementally)

阶段1：逐文件评审（逐步构建报告）

Review Checklist Per File

单文件评审检查清单

Architecture Compliance

架构合规性

Code Quality

代码质量

Naming Conventions

命名约定

Platform Patterns

平台模式

Security

安全性

Performance

性能

Backend-Specific Checks

后端特定检查

Frontend-Specific Checks

前端特定检查

Common Anti-Patterns to Flag

需要标记的常见反模式

Test-Specific Checks (When Diff Includes Test Files)

测试特定检查（当差异包含测试文件时）

Assertion Quality

断言质量

Data Verification

数据验证

Test Structure

测试结构

Anti-Patterns to Flag in Tests

测试中需要标记的反模式

Phase 2: Holistic Review (Review the Accumulated Report)

阶段2：整体评审（审阅已整理的报告）

Phase 3: Generate Final Review Result

阶段3：生成最终评审结果

Output Format

输出格式

IMPORTANT Task Planning Notes

重要的任务规划说明