# 知习 ZhiXi — 项目架构

> 更新时间：2026-05-10

## 一、项目结构

```
AIStudyApp/
├── AIStudyAppApp.swift              # 应用入口 + 引导流程路由
│   ├── OnboardingFlowView           # Splash → Welcome → Login → Onboarding → GoalSetup
│   ├── SplashPage                   # 启动页
│   ├── WelcomePage                  # 欢迎页
│   ├── LoginPage                    # 登录页
│   ├── OnboardingPage               # 功能引导
│   └── GoalSetupPage                # 学习目标设置
│
├── ContentView.swift                # 5-Tab 主界面
│   ├── ZXTabBar                     # 自定义底部 Tab 栏
│   ├── ZXAIInputBar                 # AI 输入栏
│   ├── ZXScoreBox                   # 评分组件
│   └── ZXIconBtn                    # 图标按钮
│
├── Core/
│   └── DesignSystem/
│       └── DesignTokens.swift        # 颜色/渐变/圆角/间距/字号/排版
│
├── Features/
│   ├── AI/
│   │   ├── AIHomeView.swift          # AI 首页（Tab 1）
│   │   └── DailyThinkingPage.swift   # 今日思考 + AIChat + RecallTest + WeakPoints + AIFeedback
│   │
│   ├── Library/
│   │   ├── LibraryHomeView.swift     # 知识库首页（Tab 2）
│   │   └── LibrarySubpages.swift     # Create/Detail/Add/Import/KnowledgeDetail/Edit
│   │
│   ├── Study/
│   │   └── StudyHomeView.swift       # 学习工作台（Tab 3）
│   │
│   ├── Analysis/
│   │   └── AnalysisHomeView.swift    # 学习分析（Tab 4）
│   │
│   └── Profile/
│       └── ProfileView.swift         # 我的（Tab 5）
│
└── Assets.xcassets/                  # 资源文件
```

## 二、导航架构

```
@main AIStudyAppApp
├── hasCompletedOnboarding == false
│   └── OnboardingFlowView
│       ├── step 0: SplashPage ──(2s)──→ step 1
│       ├── step 1: WelcomePage ──"开始使用"──→ step 2
│       │                      ──"已有账号"──→ hasCompletedOnboarding = true
│       ├── step 2: LoginPage ──"登录"──→ step 3
│       │                    ──"跳过"──→ hasCompletedOnboarding = true
│       ├── step 3: OnboardingPage ──"下一步"──→ step 4
│       └── step 4: GoalSetupPage ──"开始学习"──→ hasCompletedOnboarding = true
│
└── hasCompletedOnboarding == true
    └── ContentView (5-Tab)
        ├── Tab "AI"      → NavigationStack { AIHomeView }
        │   ├── → DailyThinkingPage → AIFeedbackPageView
        │   ├── → RecallTestPage
        │   ├── → WeakPointsPage
        │   └── → AIChatPage
        │
        ├── Tab "知识库"   → NavigationStack { LibraryHomeView }
        │   ├── → LibraryDetailPage → KnowledgeDetailPage
        │   ├── → CreateLibraryPage
        │   ├── → AddKnowledgePage
        │   ├── → ImportPage
        │   └── → EditKnowledgePage
        │
        ├── Tab "学习"    → NavigationStack { StudyHomeView }
        ├── Tab "分析"    → NavigationStack { AnalysisHomeView }
        └── Tab "我的"    → NavigationStack { ProfileView }
```

## 三、数据流（当前均为静态 Mock）

所有页面目前使用 `@State` 管理的本地假数据，尚未接入真实后端：

| 数据 | 当前状态 |
|------|----------|
| 用户信息 | ProfileView 中硬编码 |
| 知识库列表 | LibraryHomeView 中硬编码 4 个 |
| 学习任务 | StudyHomeView 中硬编码 5 个 |
| AI 分析结果 | 各 AI 页面静态文本 |
| 学习统计 | AnalysisHomeView 中硬编码 |
| 登录状态 | @AppStorage 布尔值控制 |

## 四、技术栈

| 层 | 技术 | 备注 |
|----|------|------|
| 语言 | Swift | — |
| UI 框架 | SwiftUI | iOS 17+ |
| 架构模式 | 当前未分层（View 内聚） | 计划 MVVM + Service + Repository |
| 设计系统 | 自定义 DesignTokens | 从 React 原型 1:1 提取 |
| 构建工具 | Xcode | — |
| 目标平台 | iPhone (iOS 17+) | 未做 iPad/Mac 适配 |

## 五、与计划架构的差异

计划文档（`官网与技术基础.md`）中定义的 iOS 目录结构：

```
计划架构                                    当前实现
─────────────────────────────────          ─────────────────
App/AIStudyApp.swift                       AIStudyAppApp.swift ✅
App/AppConfig.swift                        未实现 ❌
App/AppRouter.swift                        未实现 ❌
Core/Network/                              未实现 ❌
Core/Auth/                                 未实现 ❌
Core/Storage/                              未实现 ❌
Core/Localization/                         未实现 ❌
Core/DesignSystem/                         DesignTokens.swift ✅ (部分)
Features/*/Views/                          Features/*/ ✅
Features/*/ViewModels/                     未实现 ❌ (View 内聚状态)
Features/*/Models/                         未实现 ❌ (无独立 Model)
Shared/Components/                         分散在各 View 文件中 ⚠️
Shared/Extensions/                         仅 Color hex 扩展 ✅
Shared/Utils/                              未实现 ❌
Shared/Constants/                          未实现 ❌
Resources/Localizable.xcstrings            未实现 ❌
Resources/PreviewData/                     未实现 ❌
```

## 六、待重构项

1. **View 文件过大**：`AIStudyAppApp.swift` 包含 5 个独立页面，应拆分到各自文件
2. **无 ViewModel 层**：所有状态和数据逻辑写在 View 中，需要抽离
3. **无 Model 层**：数据结构（如学习任务、知识库卡片）分散在 View 中用局部变量定义
4. **共享组件未集中**：`ZXTabBar`、`ZXBackHeader` 等组件散落在不同文件中
5. **无网络层**：无 API Client、无 Auth Service、无 Storage 层
6. **无本地化**：所有文案硬编码，未使用 `LocalizedStringKey`