上传文件至「/」

2026-07-13 03:20:29 +00:00
parent 0e8e902af7
commit 1fad3ecc43
1 changed files with 311 additions and 0 deletions
@@ -0,0 +1,311 @@
+# 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` | 构建系统配置 |