11 KiB
11 KiB
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 中声明式配置：
{
"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 |
后端响应格式：
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 |
构建系统配置 |