# kunkunyangApp1 — 项目代码分析文档

## 1. 项目概述

**kunkunyangApp1** 是一个基于 **HarmonyOS（鸿蒙）** 原生开发的应用，使用 **ArkTS** 语言和 **ArkUI** 声明式 UI 框架构建。它是一个 AI 聊天客户端，主题风格围绕游戏角色"花火"（Sparkle / Hanabi），通过 TCP 套接字与 Python 后端进行实时通信，并提供聊天历史记录查看功能。

| 属性 | 值 |
|------|------|
| **包名** | `com.example.kunkunyangapp` |
| **版本** | 1.0.0（versionCode: 1000000） |
| **目标 SDK** | HarmonyOS API 6.0.2（级别 22） |
| **编译 SDK** | HarmonyOS 6.0.2.130 |
| **设备类型** | 手机（phone） |
| **应用标签** | "kunkunyangApp" |
| **API 模式** | Stage 模式（Stage Model） |

---

## 2. 技术栈

| 层级 | 技术 |
|------|------|
| **语言** | ArkTS（鸿蒙扩展 TypeScript） |
| **UI 框架** | ArkUI（声明式 UI） |
| **构建系统** | Hvigor |
| **包管理** | ohpm |
| **虚拟机** | Ark Engine 13.0.1.0 |
| **网络 — TCP** | `@ohos.net.socket` |
| **网络 — HTTP** | `@ohos.net.http` |
| **路由** | `@ohos:router` |
| **日志** | `@ohos:hilog` |
| **测试框架** | `@ohos/hypium` 1.0.25 |

---

## 3. 目录结构

```
kunkunyangApp1/
├── AppScope/                              # 应用级配置
│   ├── app.json5                          # 应用清单（bundleName、版本号、图标）
│   └── resources/base/
│       ├── element/string.json            # 字符串资源
│       └── media/                         # 应用图标（前景、背景、分层图标）
│
├── entry/                                 # 主入口模块（HAP）
│   ├── build-profile.json5                # 模块构建配置（混淆、编译选项）
│   ├── hvigorfile.ts                      # Hvigor 模块任务入口
│   ├── oh-package.json5                   # 模块依赖声明
│   ├── obfuscation-rules.txt              # 代码混淆规则
│   └── src/main/ets/
│       ├── entryability/
│       │   └── EntryAbility.ets           # 应用入口 UIAbility
│       ├── entrybackupability/
│       │   └── EntryBackupAbility.ets     # 备份扩展能力
│       └── pages/
│           ├── Index.ets                  # 开屏欢迎页
│           ├── souYe.ets                  # 主聊天页面
│           └── jiYi.ets                   # 聊天记录页面
│
├── hvigor/                                # 构建系统配置
│   └── hvigor-config.json5
├── hvigorfile.ts                          # 根构建任务入口
├── build-profile.json5                    # 根构建配置（产品、签名、模块）
├── oh-package.json5                       # 根依赖配置
├── code-linter.json5                      # 代码检查规则
└── local.properties                       # 本地开发配置
```

---

## 4. 页面路由

路由在 `main_pages.json` 中声明式配置：

```json
{
  "src": [
    "pages/Index",
    "pages/souYe",
    "pages/jiYi"
  ]
}
```

**路由流转：**

```
应用启动 → EntryAbility.onCreate → loadContent('pages/Index')
                │
                ▼
    Index（开屏动画页）──"进入应用"按钮──→ souYe（聊天主页）
                                              │
                                   右上角头像图标──→ jiYi（聊天记录页）
```

---

## 5. 页面详解

### 5.1 Index.ets — 开屏欢迎页

**文件路径：** `entry/src/main/ets/pages/Index.ets`

**功能：** 带序列动画的欢迎闪屏，分四段依次展示：

| 阶段 | 内容 | 延迟 | 字体样式 |
|------|------|------|----------|
| 第一段 | "欢迎欢迎" | 500ms | 36sp，粗体，粉色（#FF4081） |
| 第二段 | "来到花火大人的世界" | 1500ms | 28sp，蓝色（#3F51B5） |
| 第三段 | "那我们开始新的剧本吧" | 2500ms | 24sp，橙色（#FF9800） |
| 按钮 | "进入应用" | 3500ms | 蓝色按钮（#007DFF），白色文字 |

**动画实现：**
- 每次显示一段文字并执行 `animateTo` 弹跳动画
- 动画从 `translateY=50` 跳到 `Y=0`（主动画，800ms，EaseOut 曲线）
- 主动画完成后追加微弹跳效果（Y → -5 → 0）
- 点击"进入应用"按钮通过 `router.pushUrl` 导航到 `pages/souYe`

**响应式状态：** `showText1/2/3`、`showBat`、`offsetY1/2/3/4`

---

### 5.2 souYe.ets — 主聊天页面

**文件路径：** `entry/src/main/ets/pages/souYe.ets`

**功能：** 核心 AI 聊天界面，通过 TCP 套接字与 Python 后端通信。

#### 界面布局（自上而下）

```
┌─────────────────────────────────┐
│  "花火(─‿‿─)"  标题    [头像]  │  ← 标题栏，头像可点击跳转历史页
│  ● 连接状态                     │  ← 绿/红色圆点 + 文字
│                                 │
│  ┌─────────────────────────┐    │
│  │  用户消息（右对齐绿气泡） │    │
│  │     AI消息（左对齐蓝气泡） │    │  ← 聊天列表（Scroll）
│  │  AI 打字中...（实时显示） │    │
│  └─────────────────────────┘    │
│  [_________输入框_________] [发送]│  ← 输入区域
│  [呼叫火花花]   [清空内容]      │  ← 操作按钮
│  确保Python后端已启动并监听8889端口│
└─────────────────────────────────┘
```

#### 核心功能

**TCP 连接管理：**
- 连接到 `10.0.2.2:8889`（Android 模拟器中映射到宿主机 localhost）
- 按钮标签在"呼叫火花花"和"挂掉"之间切换
- 连接成功时清空聊天记录并重置状态
- 页面销毁（`aboutToDisappear`）时自动断开连接并清理定时器

**消息发送：**
- 用户输入通过 `socket.send()` 发送原始文本到服务器
- 发送锁（`isAiReplying`）：AI 回复期间禁止发送新消息
- 输入框和发送按钮在 AI 回复期间均禁用（灰色 `#CCCCCC`）

**AI 回复 — 打字机效果：**
- 服务端流式返回数据（`message` 事件），逐块追加到 `pendingText`
- 收到首个数据块后启动定时器，按 `typingSpeed`（默认 50ms/字）逐字显示
- 显示完所有字符后，将完整回复写入 `messages[]`，释放发送锁
- 打字过程中自动滚动到底部

**消息气泡样式：**
| 角色 | 对齐 | 气泡颜色 | 圆角 | 头像位置 |
|------|------|----------|------|----------|
| 用户 | 右对齐 | #E8F5E9（浅绿） | 左上8、右上8、左下8、右下0 | 右侧 |
| AI | 左对齐 | #F0F8FF（浅蓝） | 左上0、右上8、左下8、右下8 | 左侧 |

**响应式状态：** `messages[]`、`currentAiReply`、`pendingText`、`connectionStatus`、`isConnected`、`userInput`、`serverIP`、`serverPort`、`typingSpeed`、`isAiReplying`

---

### 5.3 jiYi.ets — 聊天记录页面

**文件路径：** `entry/src/main/ets/pages/jiYi.ets`

**功能：** 通过 HTTP 请求获取历史聊天记录并展示。

**HTTP 请求详情：**

| 属性 | 值 |
|------|------|
| **URL** | `http://10.0.2.2:8080/api/get_data` |
| **方法** | GET |
| **Content-Type** | application/json |
| **连接超时** | 5000ms |
| **读取超时** | 5000ms |

**后端响应格式：**
```typescript
interface BackendResponse<ChatRecord[]> {
  code: number;       // 200 表示成功
  msg: string;        // 状态信息
  data: ChatRecord[]; // 聊天记录数组
}

interface ChatRecord {
  id: number;
  user_input: string;   // 用户输入
  ai_reply: string;     // AI 回复
  chat_time: string;    // 聊天时间
}
```

**状态处理：**
| 状态 | UI 展示 |
|------|---------|
| 加载中 | `LoadingProgress` 旋转指示器 |
| 错误 | 红色错误信息 + "重新加载"按钮 |
| 无数据 | "暂无聊天记录"文字提示 |
| 有数据 | `List` 组件展示每条记录（用户输入 / 花火回复 / 时间） |

每条记录使用白色卡片布局，带有用户输入行、AI 回复行（标注"花火："）和时间行，卡片之间有分割线。

---

## 6. 网络通信架构

```
┌─────────────────────┐         ┌──────────────────────┐
│   HarmonyOS 应用     │         │     Python 后端        │
│                     │         │                      │
│  souYe.ets ──TCP──→ │  8889   │  AI 聊天服务（流式）   │
│  (实时聊天)          │         │                      │
│                     │         │                      │
│  jiYi.ets ──HTTP─→  │  8080   │  REST API 服务        │
│  (聊天记录)          │         │  GET /api/get_data    │
└─────────────────────┘         └──────────────────────┘
```

---

## 7. 权限配置

| 权限 | 用途 |
|------|------|
| `ohos.permission.INTERNET` | 网络访问（TCP + HTTP） |
| `ohos.permission.GET_NETWORK_INFO` | 获取网络状态信息 |

---

## 8. 应用入口 — EntryAbility

**文件路径：** `entry/src/main/ets/entryability/EntryAbility.ets`

继承自 `UIAbility`，是应用的生命周期入口：

| 生命周期方法 | 行为 |
|-------------|------|
| `onCreate` | 设置颜色模式为跟随系统（`COLOR_MODE_NOT_SET`） |
| `onWindowStageCreate` | 加载首页 `pages/Index` |
| `onForeground` / `onBackground` | 前后台切换日志 |
| `onDestroy` | 销毁日志 |

---

## 9. 状态管理

应用使用 **ArkUI 内置响应式状态管理**，无外部状态管理库：

- 每个页面是一个继承自 `ViewPU` 的类
- 使用 `@State` 装饰器标记响应式属性
  - `ObservedPropertySimplePU<T>` — 简单类型（string、number、boolean）
  - `ObservedPropertyObjectPU<T>` — 对象/数组类型
- 生命周期钩子：`aboutToAppear`、`aboutToDisappear`、`aboutToBeDeleted`
- 条件渲染通过 `If.create()` / `If.pop()` 和 `ForEach` 实现

---

## 10. 构建配置

### 构建模式

| 模式 | 混淆 | 说明 |
|------|------|------|
| debug | 关闭 | 开发调试用 |
| release | 开启 | 生产发布用，启用属性/文件名/导出混淆 |

### 代码检查

`code-linter.json5` 配置了安全规则：
- `@performance/recommended` — 性能规则
- `@typescript-eslint/recommended` — TypeScript 最佳实践
- 自定义安全规则：禁止弱加密算法（AES、哈希、MAC、DH、DSA、ECDSA、RSA、3DES）

### Hvigor 构建参数

- 严格模式：区分大小写检查 + 标准化 OHM URL
- Node 选项：`maxOldSpaceSize = 8192 MB`
- 编译模式：ES Module

---

## 11. 关键文件索引

| 文件 | 说明 |
|------|------|
| `AppScope/app.json5` | 应用清单 |
| `build-profile.json5` | 根构建配置 |
| `entry/build-profile.json5` | 模块构建配置 |
| `entry/src/main/ets/entryability/EntryAbility.ets` | 应用入口 |
| `entry/src/main/ets/pages/Index.ets` | 开屏引导页 |
| `entry/src/main/ets/pages/souYe.ets` | 主聊天页（TCP 通信） |
| `entry/src/main/ets/pages/jiYi.ets` | 聊天记录页（HTTP 请求） |
| `entry/src/main/resources/base/profile/main_pages.json` | 页面路由配置 |
| `code-linter.json5` | 代码检查规则 |
| `hvigor/hvigor-config.json5` | 构建系统配置 |