ios-projects/AIStudyApp/docs/architecture.md

知习 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