Back to Details

architectural-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architectural Analysis

架构分析

Instructions

说明

Perform comprehensive architectural audit focused on structural issues, dead code, duplication, and systemic problems.
执行针对结构问题、死代码、重复内容和系统性问题的全面架构审计。

Phase 1: Discovery & Planning

阶段1：发现与规划

Step 1: Map Codebase Structure

步骤1：绘制代码库结构

bash
undefined
bash
undefined

Get directory structure

获取目录结构

find . -type d -not -path "/node_modules/" -not -path "/.git/"
find . -type d -not -path "/node_modules/" -not -path "/.git/"

Count files by type

按类型统计文件数量

find . -name ".ts" -o -name ".tsx" -o -name ".js" -o -name ".jsx" | wc -l
undefined
find . -name ".ts" -o -name ".tsx" -o -name ".js" -o -name ".jsx" | wc -l
undefined

Step 2: Identify Entry Points

步骤2：识别入口点

  • Main application entry (
    index.ts
    , 
    main.ts
    , 
    app.ts
    )
  • API routes/controllers
  • Public exports (
    index.ts
    files)
  • CLI entry points
  • Test files
  • 主应用入口（
    index.ts
    、
    main.ts
    、
    app.ts
    ）
  • API路由/控制器
  • 公共导出（
    index.ts
    文件）
  • CLI入口点
  • 测试文件

Step 3: Create Comprehensive File List

步骤3：创建完整文件列表

Use Glob to find all source files. Create todo list with one item per file to analyze.
使用Glob查找所有源文件。 创建待办事项列表，每个文件对应一个分析项。

Phase 2: Dead Code Detection

阶段2：死代码检测

For EACH file in the todo list:
对待办列表中的每个文件执行以下操作：

Step 1: Identify Exports

步骤1：识别导出内容

  • What does this file export?
  • Are exports functions, classes, types, constants?
  • Is anything exported at all?
  • 该文件导出了什么？
  • 导出的是函数、类、类型还是常量？
  • 是否有任何导出内容？

Step 2: Search for Usage

步骤2：搜索使用情况

For each export, search if it's imported/used anywhere:
bash
undefined
针对每个导出内容，搜索它是否在任何地方被导入/使用：
bash
undefined

Search for imports of this export

搜索该导出内容的导入情况

grep -r "import.ExportName" . --include=".ts" --include=".tsx" grep -r "from.filename" . --include=".ts" --include=".tsx"
grep -r "import.ExportName" . --include=".ts" --include=".tsx" grep -r "from.filename" . --include=".ts" --include=".tsx"

Search for direct usage

搜索直接使用情况

grep -r "ExportName" . --include=".ts" --include=".tsx"
undefined
grep -r "ExportName" . --include=".ts" --include=".tsx"
undefined

Step 3: Categorize Code

步骤3：分类代码

Dead Code (mark for removal):
  • Exported but never imported
  • Functions defined but never called
  • Classes instantiated nowhere
  • Types defined but never used
  • Constants defined but never referenced
  • Entire files with no imports from other files
Possibly Dead (needs verification):
  • Only used in commented-out code
  • Only used in dead code
  • Only used in other unused exports
  • Used only in tests for deprecated features
Internal Dead Code:
  • Functions defined in file but never called (not exported)
  • Variables assigned but never read
  • Parameters accepted but never used
死代码（标记为删除）：
  • 已导出但从未被导入
  • 已定义但从未被调用的函数
  • 从未被实例化的类
  • 已定义但从未被使用的类型
  • 已定义但从未被引用的常量
  • 完全没有被其他文件导入的整个文件
疑似死代码（需要验证）：
  • 仅在被注释的代码中使用
  • 仅在死代码中使用
  • 仅在其他未使用的导出内容中使用
  • 仅在已废弃功能的测试中使用
内部死代码：
  • 文件内定义但从未被调用的函数（未导出）
  • 已赋值但从未被读取的变量
  • 已接收但从未被使用的参数

Step 4: Check for False Positives

步骤4：检查误判情况

Not dead if:
  • Used in tests (may be public API)
  • Dynamically imported/required
  • Used via reflection/string references
  • Part of public API (even if not used internally)
  • Framework hooks (lifecycle methods, callbacks)
  • Accessed via 
    window
    or global scope
以下情况不属于死代码：
  • 在测试中使用（可能是公共API）
  • 动态导入/引用
  • 通过反射/字符串引用使用
  • 属于公共API（即使内部未使用）
  • 框架钩子（生命周期方法、回调函数）
  • 通过
    window
    或全局作用域访问

Step 5: Record Findings

步骤5：记录发现结果

File: path/to/file.ts
Status: [DEAD|POSSIBLY_DEAD|USED]
Exports: [list]
Dead Exports:
  - ExportName - No imports found
  - AnotherExport - Only used in test for deprecated feature
Confidence: [HIGH|MEDIUM|LOW]
文件：path/to/file.ts
状态：[DEAD|POSSIBLY_DEAD|USED]
导出内容：[列表]
死导出项：
  - ExportName - 未找到任何导入
  - AnotherExport - 仅在已废弃功能的测试中使用
置信度：[HIGH|MEDIUM|LOW]

Step 6: Mark Complete

步骤6：标记完成

Update todo list.
更新待办事项列表。

Phase 3: Duplication Detection

阶段3：重复内容检测

Step 1: Identify Duplicated Logic Patterns

步骤1：识别重复逻辑模式

Search for common patterns that suggest duplication:
  • Similar function names across files
  • Repeated code blocks
  • Multiple implementations of same concept
Manual Pattern Recognition:
  • Read files in same directory
  • Look for suspiciously similar code
  • Compare utilities/helpers across modules
  • Check for copy-pasted blocks
Grep-Based Detection:
bash
undefined
搜索表明存在重复的常见模式：
  • 跨文件的相似函数名
  • 重复的代码块
  • 同一概念的多种实现
手动模式识别：
  • 读取同一目录下的文件
  • 查找疑似相似的代码
  • 比较模块间的工具/辅助函数
  • 检查复制粘贴的代码块
基于Grep的检测：
bash
undefined

Find similar function signatures

查找相似的函数签名

grep -r "function validateEmail" . --include="*.ts" grep -r "async.*fetch.api" . --include=".ts" grep -r "export.UserForm" . --include=".tsx"
undefined
grep -r "function validateEmail" . --include="*.ts" grep -r "async.*fetch.api" . --include=".ts" grep -r "export.UserForm" . --include=".tsx"
undefined

Step 2: Analyze Duplicated Functionality

步骤2：分析重复功能

For each potential duplication:
  • Read both/all implementations
  • Are they actually the same logic?
  • Do they handle same cases?
  • Could one replace the other?
  • Are differences intentional or accidental?
针对每个潜在的重复项：
  • 阅读所有实现
  • 它们的逻辑是否完全相同？
  • 它们处理的场景是否相同？
  • 是否可以用其中一个替代其他？
  • 差异是有意设计还是意外造成的？

Step 3: Categorize Duplication

步骤3：分类重复类型

Exact Duplication (CRITICAL):
  • Identical or near-identical code in multiple places
  • Copy-pasted functions
  • Duplicated utility functions
  • Impact: Bug fixes need multiple updates, maintenance burden
Similar Logic (HIGH):
  • Same algorithm, different implementation
  • Slightly different parameter handling
  • Different names, same purpose
  • Impact: Inconsistency risk, harder to maintain
Conceptual Duplication (MEDIUM):
  • Multiple ways to do the same thing
  • Competing implementations
  • Overlapping utilities
  • Impact: Confusion, decision paralysis
Type Duplication (HIGH):
  • Same interface/type defined multiple times
  • Similar types that should be unified
  • Duplicate constants/enums
  • Impact: Type inconsistency, refactoring difficulty
完全重复（CRITICAL）：
  • 多个位置存在完全相同或几乎相同的代码
  • 复制粘贴的函数
  • 重复的工具函数
  • 影响：修复Bug需要更新多个位置，增加维护负担
相似逻辑（HIGH）：
  • 算法相同但实现不同
  • 参数处理略有差异
  • 名称不同但用途相同
  • 影响：存在不一致风险，维护难度更高
概念重复（MEDIUM）：
  • 实现同一功能的多种方式
  • 相互竞争的实现
  • 重叠的工具函数
  • 影响：造成混淆，难以决策
类型重复（HIGH）：
  • 同一接口/类型被多次定义
  • 可统一的相似类型
  • 重复的常量/枚举
  • 影响：类型不一致，重构困难

Step 4: Record Duplication

步骤4：记录重复内容

Duplication Group: Email Validation
Type: Exact Duplication
Instances:
  - src/utils/validators.ts:42 - validateEmail()
  - src/lib/email.ts:15 - isValidEmail()
  - src/components/forms/validation.ts:67 - checkEmailFormat()
Analysis: All three implement same regex check
Recommendation: Keep utils/validators.ts version, remove others
Impact: 3 places to update when logic changes
重复组：邮箱验证
类型：完全重复
实例：
  - src/utils/validators.ts:42 - validateEmail()
  - src/lib/email.ts:15 - isValidEmail()
  - src/components/forms/validation.ts:67 - checkEmailFormat()
分析：三个函数均实现相同的正则检查
建议：保留utils/validators.ts版本，移除其他版本
影响：逻辑变更时需要更新3个位置

Phase 4: Architectural Anti-Patterns

阶段4：架构反模式

Step 1: Identify God Objects/Classes

步骤1：识别God Objects/类

Search for files that do too much:
  • Files over 500 lines
  • Classes with 10+ methods
  • Files with many responsibilities
  • Modules that import from everywhere
bash
undefined
查找承担过多职责的文件：
  • 超过500行的文件
  • 包含10个以上方法的类
  • 承担多种职责的文件
  • 从各处导入依赖的模块
bash
undefined

Find large files

查找大文件

find . -name "*.ts" -exec wc -l {} + | sort -rn | head -20

Analyze large files:
- What does this file do?
- Does it have single responsibility?
- Should it be split?
find . -name "*.ts" -exec wc -l {} + | sort -rn | head -20

分析大文件：
- 该文件的功能是什么？
- 它是否符合单一职责原则？
- 是否应该拆分？

Step 2: Detect Circular Dependencies

步骤2：检测Circular Dependencies

Look for:
  • File A imports from B, B imports from A
  • Circular chains: A → B → C → A
  • Module coupling cycles
Use grep to trace import chains:
bash
undefined
查找以下情况：
  • 文件A导入B，B导入A
  • 循环链：A → B → C → A
  • 模块耦合循环
使用grep追踪导入链：
bash
undefined

Check what file imports

检查文件的导入内容

grep "^import.*from" src/services/auth.ts
grep "^import.*from" src/services/auth.ts

Check what imports this file

检查哪些文件导入了当前文件

grep -r "from.auth" src/ --include=".ts"
undefined
grep -r "from.auth" src/ --include=".ts"
undefined

Step 3: Find Tight Coupling

步骤3：查找紧密耦合

Identify:
  • High-level modules depending on low-level modules
  • Business logic depending on infrastructure
  • Core logic depending on framework specifics
  • Modules that import from many other modules
识别以下情况：
  • 高层模块依赖低层模块
  • 业务逻辑依赖基础设施
  • 核心逻辑依赖框架细节
  • 导入大量其他模块的模块

Step 4: Spot Layer Violations

步骤4：发现层级违规

Check architecture layers:
  • Do components import directly from database layer?
  • Do models import from views?
  • Do utilities import from business logic?
  • Is there proper separation of concerns?
检查架构层级：
  • 组件是否直接从数据库层导入？
  • 模型是否从视图层导入？
  • 工具函数是否从业务逻辑层导入？
  • 是否有适当的关注点分离？

Step 5: Identify Other Anti-Patterns

步骤5：识别其他反模式

Singleton Abuse:
  • Global state everywhere
  • Module-level mutable state
  • Static class methods accessing shared state
Anemic Domain Models:
  • Data classes with no behavior
  • All logic in services, models just have getters/setters
Shotgun Surgery:
  • Single feature change requires touching many files
  • Indicates poor cohesion
Feature Envy:
  • Methods that use more data from other classes than their own
Singleton滥用：
  • 全局状态随处可见
  • 模块级可变状态
  • 访问共享状态的静态类方法
贫血领域模型：
  • 仅包含数据而无行为的类
  • 所有逻辑都在服务中，模型仅包含getter/setter
霰弹式修改：
  • 单一功能变更需要修改多个文件
  • 表明内聚性差
特性羡慕：
  • 方法使用其他类的数据远多于自身类的数据

Phase 5: Type Issues Analysis

阶段5：类型问题分析

Step 1: Find Type Abuse

步骤1：查找类型滥用

Search for problematic type usage:
bash
undefined
搜索有问题的类型用法：
bash
undefined

Find 'any' usage

查找'any'用法

grep -r ": any" . --include=".ts" --include=".tsx" -n
grep -r ": any" . --include=".ts" --include=".tsx" -n

Find 'unknown' usage

查找'unknown'用法

grep -r ": unknown" . --include="*.ts" -n
grep -r ": unknown" . --include="*.ts" -n

Find type assertions

查找类型断言

grep -r "as any" . --include=".ts" -n grep -r "as unknown" . --include=".ts" -n
grep -r "as any" . --include=".ts" -n grep -r "as unknown" . --include=".ts" -n

Find @ts-ignore

查找@ts-ignore

grep -r "@ts-ignore" . --include=".ts" -n grep -r "@ts-expect-error" . --include=".ts" -n
undefined
grep -r "@ts-ignore" . --include=".ts" -n grep -r "@ts-expect-error" . --include=".ts" -n
undefined

Step 2: Analyze Type Confusion

步骤2：分析类型混淆

For each file with type issues:
  • Why is 
    any
    used?
  • Could proper type be defined?
  • Is type assertion hiding a real type error?
  • Are @ts-ignore comments masking actual problems?
针对每个存在类型问题的文件：
  • 为什么使用
    any
    ？
  • 是否可以定义合适的类型？
  • 类型断言是否隐藏了真实的类型错误？
  • @ts-ignore注释是否掩盖了实际问题？

Step 3: Find Type Duplication

步骤3：查找类型重复

Look for:
  • Same interface defined in multiple files
  • Similar types that could be unified
  • Types that could extend from common base
  • Constants/enums duplicated across files
查找以下情况：
  • 同一接口在多个文件中定义
  • 可统一的相似类型
  • 可扩展自公共基类的类型
  • 跨文件重复的常量/枚举

Step 4: Identify Missing Types

步骤4：识别缺失的类型

Check for:
  • Implicit 
    any
    from missing type annotations
  • Functions without return type
  • Callbacks without proper typing
  • Generic types that should be specific
检查以下情况：
  • 因缺少类型注解导致的隐式
    any
  • 无返回类型的函数
  • 无适当类型的回调函数
  • 应具体化的泛型类型

Phase 6: Code Smells Detection

阶段6：代码异味检测

Step 1: Long Methods/Functions

步骤1：长方法/函数

bash
undefined
bash
undefined

Find functions with many lines

查找行数较多的函数

(manual inspection of large files)

（手动检查大文件）


Flag functions over 50 lines - likely doing too much.

标记超过50行的函数——可能承担了过多职责。

Step 2: Long Parameter Lists

步骤2：长参数列表

Search for functions with 4+ parameters:
  • Could use object parameter instead?
  • Are parameters related (should be grouped)?
查找包含4个以上参数的函数：
  • 是否可以使用对象参数替代？
  • 参数是否相关（应分组）？

Step 3: Complex Conditionals

步骤3：复杂条件判断

Look for:
  • Deeply nested if statements (3+ levels)
  • Long boolean expressions
  • Switch statements with 10+ cases
  • Complex ternary operators
查找以下情况：
  • 深度嵌套的if语句（3层以上）
  • 长布尔表达式
  • 包含10个以上分支的switch语句
  • 复杂的三元运算符

Step 4: Magic Numbers/Strings

步骤4：魔法数字/字符串

Search for:
  • Hardcoded numbers with unclear meaning
  • String literals used repeatedly
  • Unexplained constants
Should be named constants.
查找以下情况：
  • 含义不明确的硬编码数字
  • 重复使用的字符串字面量
  • 未解释的常量
应替换为命名常量。

Step 5: Commented-Out Code

步骤5：被注释的代码

bash
undefined
bash
undefined

Find commented code blocks

查找被注释的代码块

grep -r "^[[:space:]]*//.function|class|const" . --include=".ts"

Commented code should be deleted (use git history).
grep -r "^[[:space:]]*//.function|class|const" . --include=".ts"

被注释的代码应删除（可使用git历史记录查看）。

Step 6: Poor Naming

步骤6：命名不佳

Look for:
  • Single letter variables (outside loops)
  • Abbreviations without context (
    usr
    , 
    msg
    , 
    tmp
    )
  • Misleading names
  • Names that don't reflect purpose
查找以下情况：
  • 单字母变量（循环外）
  • 无上下文的缩写（
    usr
    、
    msg
    、
    tmp
    ）
  • 误导性名称
  • 未反映用途的名称

Phase 7: Generate Report

阶段7：生成报告

Create report at 
.audits/architectural-analysis-[timestamp].md
:
markdown
undefined
在
.audits/architectural-analysis-[timestamp].md
路径下创建报告：
markdown
undefined

Architectural Analysis Report

架构分析报告

Date: [timestamp] Files Analyzed: X Dead Code Files: Y Duplication Groups: Z
日期：[时间戳] 已分析文件数：X 死代码文件数：Y 重复组数量：Z

Executive Summary

执行摘要

  • Dead Code: X files, Y exports completely unused
  • Duplicated Functionality: Z duplication groups
  • Architectural Anti-Patterns: W issues
  • Type Issues: V problematic usages
  • Code Smells: U instances
Estimated Cleanup: Remove ~X lines of dead code, consolidate Y duplications
  • 死代码：X个文件，Y个导出项完全未使用
  • 重复功能：Z个重复组
  • 架构反模式：W个问题
  • 类型问题：V个有问题的用法
  • 代码异味：U个实例
预估清理工作量：移除约X行死代码，合并Y处重复内容

Dead Code

死代码

Completely Dead Files (DELETE)

完全无用的文件（删除）

FileReasonConfidence
src/old/legacy-processor.ts
No imports foundHIGH
src/utils/unused-helper.ts
Exported but never usedHIGH
src/temp/temp-service.ts
Temporary file left behindHIGH
Total Lines: X,XXX lines can be deleted
文件原因置信度
src/old/legacy-processor.ts
未找到任何导入HIGH
src/utils/unused-helper.ts
已导出但从未被使用HIGH
src/temp/temp-service.ts
遗留的临时文件HIGH
总行数：约X,XXX行可删除

Dead Exports (REMOVE)

无用导出项（移除）

FileExportReason
src/utils/format.ts
formatOldDate()
Replaced by 
formatDate()
, no usage
src/services/auth.ts
oldLogin()
Deprecated, no usage found
文件导出项原因
src/utils/format.ts
formatOldDate()
已被
formatDate()
替代，无使用记录
src/services/auth.ts
oldLogin()
已废弃，未找到使用记录

Possibly Dead (VERIFY)

疑似无用内容（需验证）

FileExportReasonVerification Needed
src/lib/api.ts
fetchOldApi()
Only used in commented codeCheck if truly deprecated
文件导出项原因验证需求
src/lib/api.ts
fetchOldApi()
仅在被注释的代码中使用检查是否真的已废弃

Internal Dead Code

内部无用代码

  • src/services/user.ts:125
    - Private method 
    _validateLegacy()
    never called
  • src/components/form.tsx:89
    - Variable 
    tempData
    assigned but never read
  • src/services/user.ts:125
    - 私有方法
    _validateLegacy()
    从未被调用
  • src/components/form.tsx:89
    - 变量
    tempData
    已赋值但从未被读取

Duplicated Functionality

重复功能

CRITICAL: Exact Duplicates

严重：完全重复

Duplication Group 1: Email Validation

重复组1：邮箱验证

Instances: 3 Files:
  • src/utils/validators.ts:42
    - 
    validateEmail(email: string)
  • src/lib/email.ts:15
    - 
    isValidEmail(email: string)
  • src/components/forms/validation.ts:67
    - 
    checkEmailFormat(email: string)
Analysis: All three use identical regex pattern 
/^[^\s@]+@[^\s@]+\.[^\s@]+$/
Lines Duplicated: ~15 lines × 3 = 45 lines Recommendation:
  • Keep: 
    src/utils/validators.ts:validateEmail()
  • Remove: Other two implementations
  • Update: All imports to use validators version
实例数：3 文件：
  • src/utils/validators.ts:42
    - 
    validateEmail(email: string)
  • src/lib/email.ts:15
    - 
    isValidEmail(email: string)
  • src/components/forms/validation.ts:67
    - 
    checkEmailFormat(email: string)
分析：三个函数均实现相同的正则表达式
/^[^\s@]+@[^\s@]+\.[^\s@]+$/
重复行数：约15行 ×3 =45行 建议：
  • 保留：
    src/utils/validators.ts:validateEmail()
  • 移除：另外两个实现
  • 更新：所有导入改为使用validators版本

Duplication Group 2: API Error Handling

重复组2：API错误处理

Instances: 4 Files: [list] Analysis: [similar]
实例数：4 文件：[列表] 分析：[类似内容]

HIGH: Similar Logic

高优先级：相似逻辑

Duplication Group: Date Formatting

重复组：日期格式化

Instances: 2 Files:
  • src/utils/date.ts:30
    - 
    formatDate()
    - Uses date-fns
  • src/lib/format.ts:45
    - 
    formatDateTime()
    - Uses native Date
Analysis: Both format dates but use different libraries Recommendation: Standardize on date-fns, remove native version
实例数：2 文件：
  • src/utils/date.ts:30
    - 
    formatDate()
    - 使用date-fns
  • src/lib/format.ts:45
    - 
    formatDateTime()
    - 使用原生Date
分析：两者均格式化日期但使用不同库 建议：标准化使用date-fns，移除原生版本

Type Duplication

类型重复

Type Group: User Interface

类型组：用户接口

Instances: 3 Files:
  • src/types/user.ts
    - 
    User
    interface
  • src/models/user.ts
    - 
    UserModel
    interface (identical fields)
  • src/api/types.ts
    - 
    UserData
    interface (identical fields)
Recommendation: Use single 
User
type from 
src/types/user.ts
实例数：3 文件：
  • src/types/user.ts
    - 
    User
    接口
  • src/models/user.ts
    - 
    UserModel
    接口（字段完全相同）
  • src/api/types.ts
    - 
    UserData
    接口（字段完全相同）
建议：统一使用
src/types/user.ts
中的
User
类型

Architectural Anti-Patterns

架构反模式

God Objects

God Objects

src/services/application-manager.ts
(850 lines)

src/services/application-manager.ts
（850行）

Responsibilities: Database, auth, config, logging, caching, validation Issue: Violates SRP, does everything Recommendation: Split into:
  • database.service.ts
  • auth.service.ts
  • config.service.ts
  • logging.service.ts
职责：数据库、认证、配置、日志、缓存、验证 问题：违反单一职责原则，承担过多工作 建议：拆分为：
  • database.service.ts
  • auth.service.ts
  • config.service.ts
  • logging.service.ts

Circular Dependencies

Circular Dependencies

Cycle 1: 
auth.ts
↔ 
user.ts

循环1：
auth.ts
↔ 
user.ts

  • auth.ts
    imports 
    getUserById
    from 
    user.ts
  • user.ts
    imports 
    validateToken
    from 
    auth.ts
    Issue: Creates tight coupling, makes testing hard Recommendation: Extract shared types to separate file
  • auth.ts
    从
    user.ts
    导入
    getUserById
  • user.ts
    从
    auth.ts
    导入
    validateToken
    问题：导致紧密耦合，增加测试难度 建议：将共享类型提取到单独文件

Tight Coupling

紧密耦合

components/UserForm.tsx
→ 
services/database.ts

components/UserForm.tsx
→ 
services/database.ts

Issue: UI component directly importing database layer Recommendation: Use service layer abstraction
问题：UI组件直接导入数据库层 建议：使用服务层抽象

Layer Violations

层级违规

models/User.ts
imports from 
components/

models/User.ts
从
components/
导入

Issue: Model layer should not know about view layer Recommendation: Remove dependency, pass data via props
问题：模型层不应依赖视图层 建议：移除依赖，通过props传递数据

Type Issues

类型问题

any
Usage (X instances)

any
用法（X个实例）

FileLineContextSeverity
src/api/client.ts
45
response: any
HIGH
src/utils/parse.ts
23
data: any
HIGH
Total 
any
usages: X Recommendation: Define proper types for all cases
文件行号上下文严重程度
src/api/client.ts
45
response: any
HIGH
src/utils/parse.ts
23
data: any
HIGH
any
总使用次数：X 建议：为所有情况定义合适的类型

Type Assertions (Y instances)

类型断言（Y个实例）

FileLineAssertionIssue
src/lib/api.ts
67
as User
Unsafe cast, no validation
src/utils/parse.ts
89
as unknown as T
Double cast to bypass types
Issue: Type safety bypassed, runtime errors possible
文件行号断言内容问题
src/lib/api.ts
67
as User
不安全的类型转换，无验证
src/utils/parse.ts
89
as unknown as T
双重转换绕过类型检查
问题：绕过类型安全，可能导致运行时错误

@ts-ignore Comments (Z instances)

@ts-ignore注释（Z个实例）

FileLineReasonShould Fix
src/legacy/old.ts
34"Type error in legacy code"Refactor or remove file
文件行号原因是否应修复
src/legacy/old.ts
34"遗留代码中的类型错误"重构或删除文件

Code Smells

代码异味

Long Functions (>50 lines)

长函数（>50行）

FileFunctionLinesIssue
src/services/processor.ts
processData()
127Does too much, hard to test
Recommendation: Extract smaller functions
文件函数行数问题
src/services/processor.ts
processData()
127承担过多职责，测试难度大
建议：拆分为更小的函数

Complex Conditionals

复杂条件判断

FileLineIssue
src/utils/validator.ts
45Nested 4 levels deep
src/lib/parser.ts
89Boolean expression spans 3 lines
文件行号问题
src/utils/validator.ts
45嵌套4层深度
src/lib/parser.ts
89布尔表达式跨3行

Magic Numbers

魔法数字

FileLineMagic ValueShould Be
src/config/limits.ts
12
86400
SECONDS_PER_DAY
src/utils/format.ts
34
1000
MS_PER_SECOND
文件行号魔法值应替换为
src/config/limits.ts
12
86400
SECONDS_PER_DAY
src/utils/format.ts
34
1000
MS_PER_SECOND

Commented-Out Code

被注释的代码

Files with commented code: X
  • src/old/legacy.ts
    - 45 lines of commented code
  • src/services/auth.ts
    - Old implementation commented out
Recommendation: Delete all commented code (use git history)
包含被注释代码的文件数：X
  • src/old/legacy.ts
    - 45行被注释的代码
  • src/services/auth.ts
    - 被注释的旧实现
建议：删除所有被注释的代码（可使用git历史记录查看）

Statistics

统计数据

Dead Code:
  • Files: X
  • Exports: Y
  • Lines: Z (estimated)
Duplication:
  • Groups: X
  • Files affected: Y
  • Duplicated lines: ~Z
Architectural Issues:
  • God objects: X
  • Circular dependencies: Y
  • Layer violations: Z
Type Issues:
  • any
    usage: X
  • Type assertions: Y
  • @ts-ignore: Z
Code Smells:
  • Long functions: X
  • Complex conditionals: Y
  • Magic numbers: Z
死代码：
  • 文件数：X
  • 导出项数：Y
  • 行数：约Z行
重复内容：
  • 重复组数量：X
  • 受影响文件数：Y
  • 重复行数：约Z行
架构问题：
  • God Objects数量：X
  • Circular Dependencies数量：Y
  • 层级违规数量：Z
类型问题：
  • any
    使用次数：X
  • 类型断言次数：Y
  • @ts-ignore次数：Z
代码异味：
  • 长函数数量：X
  • 复杂条件判断数量：Y
  • 魔法数字数量：Z

Impact Assessment

影响评估

Code Cleanup Potential

代码清理潜力

  • Dead code removal: ~X,XXX lines
  • Duplication consolidation: ~Y,YYY lines
  • Total reduction: ~Z,ZZZ lines (AA% of codebase)
  • 死代码移除：约X,XXX行
  • 重复内容合并：约Y,YYY行
  • 总缩减量：约Z,ZZZ行（占代码库的AA%）

Maintainability Improvement

可维护性提升

  • Fewer places to update when fixing bugs
  • Clearer code responsibilities
  • Better type safety
  • Reduced cognitive load
  • Bug修复时需要更新的位置更少
  • 代码职责更清晰
  • 类型安全性更好
  • 认知负担降低

Risk Areas

风险区域

  • High coupling in 
    services/
    directory
  • Type safety compromised in 
    api/
    layer
  • Architectural violations in 
    components/
undefined
  • services/
    目录中的高耦合问题
  • api/
    层的类型安全性受损
  • components/
    中的架构违规问题
undefined

Phase 8: Summary for User

阶段8：向用户提供摘要

Provide concise summary:
markdown
undefined
提供简洁的摘要：
markdown
undefined

Architectural Analysis Complete

架构分析完成

Dead Code Found

发现的死代码

  • X completely dead files - Can be deleted immediately
  • Y unused exports - Can be removed
  • ~Z,ZZZ lines of dead code identified
  • X个完全无用的文件 - 可立即删除
  • Y个未使用的导出项 - 可移除
  • 约Z,ZZZ行死代码

Top Dead Files

主要无用文件

  1. src/old/legacy-processor.ts
    - No imports
  2. src/temp/temp-service.ts
    - Temporary file
  3. src/utils/unused-helper.ts
    - Exported but never used
  1. src/old/legacy-processor.ts
    - 无任何导入
  2. src/temp/temp-service.ts
    - 临时文件
  3. src/utils/unused-helper.ts
    - 已导出但从未被使用

Duplication Found

发现的重复内容

  • X duplication groups identified
  • Most duplicated: Email validation (3 copies)
  • ~Y,YYY lines of duplicated code
  • X个重复组
  • 重复最多的内容：邮箱验证（3份副本）
  • 约Y,YYY行重复代码

Architectural Issues

架构问题

  • Z god objects doing too much
  • W circular dependencies found
  • V layer violations detected
  • Z个God Objects承担过多职责
  • W个Circular Dependencies
  • V个层级违规

Type Issues

类型问题

  • X 
    any
    usages     - Should have proper types
  • Y type assertions - Bypassing type safety
  • Z @ts-ignore comments - Masking errors
  • X个
    any
    用法     - 应定义合适的类型
  • Y个类型断言 - 绕过类型安全
  • Z个@ts-ignore注释 - 掩盖错误

Code Smells

代码异味

  • X long functions (>50 lines)
  • Y complex conditionals (3+ nesting)
  • Z magic numbers - Should be constants
  • X个长函数（>50行）
  • Y个复杂条件判断（嵌套3层以上）
  • Z个魔法数字 - 应替换为命名常量

Cleanup Potential

清理潜力

Removing dead code and consolidating duplication could eliminate ~X,XXX lines (Y% of codebase)
Full Report: 
.audits/architectural-analysis-[timestamp].md
undefined
移除死代码和合并重复内容可消除约X,XXX行代码（占代码库的Y%）
完整报告：
.audits/architectural-analysis-[timestamp].md
undefined

Critical Principles

核心原则

  • NEVER EDIT FILES - This is analysis only, not cleanup
  • NEVER SKIP FILES - Analyze entire codebase systematically
  • BE THOROUGH - Dead code detection requires checking all imports
  • VERIFY DUPLICATES - Don't just match names, check if logic is same
  • UNDERSTAND ARCHITECTURE - See the big picture, not just individual files
  • QUANTIFY IMPACT - Count lines, estimate cleanup potential
  • BE CONFIDENT - Mark confidence level (HIGH/MEDIUM/LOW) for findings
  • TRACK PROGRESS - Use todo list for file-by-file analysis
  • 绝不修改文件 - 仅进行分析，不执行清理
  • 绝不跳过文件 - 系统地分析整个代码库
  • 全面彻底 - 死代码检测需要检查所有导入
  • 验证重复项 - 不要仅匹配名称，需检查逻辑是否相同
  • 理解架构 - 关注整体情况，而非仅单个文件
  • 量化影响 - 统计行数，预估清理潜力
  • 标注置信度 - 为发现结果标记置信度（HIGH/MEDIUM/LOW）
  • 跟踪进度 - 使用待办列表跟踪逐个文件的分析进度

Success Criteria

成功标准

A complete architectural analysis includes:
  • All files analyzed for dead code
  • All exports checked for usage
  • Duplication groups identified and cataloged
  • Architectural anti-patterns found and explained
  • Type issues located and categorized
  • Code smells flagged
  • Impact assessment quantified
  • Structured report generated
After completing the analysis, follow handbook 
15.04
to create 
tk
tickets for all surfaced issues.
完整的架构分析应包含：
  • 所有文件均已分析死代码
  • 所有导出项均已检查使用情况
  • 已识别并分类重复组
  • 已发现并解释架构反模式
  • 已定位并分类类型问题
  • 已标记代码异味
  • 已量化影响评估
  • 已生成结构化报告
完成分析后，按照手册
15.04
为所有发现的问题创建
tk
工单。