# 知习 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 }
```

## 三、数据流

> 详细实现状态见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)

| 层 | 当前状态 |
|------|----------|
| Auth | ✅ 已对接后端（Apple 登录 + JWT + refresh） |
| Network | ✅ APIClient + Endpoint + Error |
| Service | 🔶 AuthService 完成，其余 Service 协议已定义 |
| ViewModel | 🔶 部分页面已迁移（ReviewPlan/AIChat/StudyHome） |
| Model | ✅ 10 个数据实体 |
| Storage | ✅ KeychainStore + TokenStore |
| 其他页面数据 | ❌ 仍为静态 Mock（知识库/学习/复习/分析） |

## 四、技术栈

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

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

计划文档中定义的 iOS 目录结构 vs 当前实现：

```
计划架构                                    当前实现
─────────────────────────────────          ─────────────────
App/AIStudyApp.swift                       AIStudyAppApp.swift ✅
App/AppConfig.swift                        未实现 ❌
App/AppRouter.swift                        AppSession 替代 ✅
Core/Network/                              APIClient + Endpoint + Error ✅
Core/Auth/                                 AuthService + AuthServiceProtocol ✅
Core/Storage/                              KeychainStore + TokenStore ✅
Core/Localization/                         ZXStrings + LanguageManager ✅
Core/DesignSystem/                         DesignTokens.swift ✅
Features/*/Views/                          Features/*/ ✅
Features/*/ViewModels/                     🔶 部分完成
Features/*/Models/                         ✅ Core/Models/ 下 10 个实体
Shared/Components/                         Shared/Components/ 下 20+ 组件 ✅
Shared/Extensions/                         Color hex 扩展 ✅
Shared/Utils/                              未实现 ❌
Shared/Constants/                          未实现 ❌
Resources/Localizable.xcstrings            Localizable.strings ✅
Resources/PreviewData/                     未实现 ❌
```