312 lines
11 KiB
Markdown
312 lines
11 KiB
Markdown
# 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` | 构建系统配置 |
|