# 记之项目交接档案

生成时间：2026-07-23  
项目路径：`C:\Users\nanxun\Documents\dsworkspace\jizhang`

## 1. 项目概况

这是一个记账 App 项目，当前品牌名为“记之”。项目包含：

- Flutter 客户端：`frontend`
- Android 原生能力：`frontend/android/app/src/main/kotlin/com/nx/miaoji`
- .NET 后端：`backend`
- 当前内测服务地址：`https://lt.frp-say.com:38012`
- 当前内测包名：`com.nx.miaoji.internal`
- 正式生产包名：`com.nx.miaoji`

当前测试主线集中在：AI 记账、截屏/OCR 记账、无障碍/通知智能识别、游客离线、本地数据安全、更新检测和深色模式。

## 2. 当前最近版本

最近成功构建版本：

```text
包名：com.nx.miaoji.internal
显示名称：记之·内测
显示版本号：1.2.5-internal
构建版本号：132
APK 路径：C:\Users\nanxun\Documents\dsworkspace\jizhang\release\JiZhi-1.2.5-internal-132.apk
APK SHA-256：2BE1DF66A92FC2D35F41197CDEEEC3240B568EFADE3FCA7A5442DC914AFC5316
签名证书 SHA-256：dc625141f914c86e30001a2c6187eb4a73babcd62e739d4b053f1fc7e93d3e6c
```

对应更新说明：

```text
C:\Users\nanxun\Documents\dsworkspace\jizhang\release-notes\JiZhi-1.2.5-internal-132.md
```

ADB 当时未发现在线设备，所以没有自动覆盖安装。

## 3. 最近已实现重点

### 3.1 无障碍支付识别与本地 OCR

最近一轮实现目标：修复微信/支付宝红包、支付去重和识别时间问题。

主要实现点：

- 支付流程状态支持 `payment`、`transfer`、`red_packet_send`。
- 微信、支付宝红包资金变化支持：
  - 发红包：支出，默认分类提示 `人情`
  - 红包到账：收入，默认分类提示 `红包`
  - 红包退回：收入，默认分类提示 `红包`
  - 普通红包消息、未领取红包、他人领取消息不自动入账
- 微信支付结果页如果缺金额，在严格证据成立时使用付款前唯一金额入账。
- 支付宝成功页刷新、返回重进、通知和 OCR 同时到达时合并为同一个候选，降低重复入账。
- 连续两笔真实相同金额交易仍通过新提交动作生成新流程 ID，不会被错误合并。
- 本地 OCR 图片只在内存中处理，不保存原图，不上传。
- 诊断信息新增：流程类型、金额来源、结果页指纹、拒绝原因等。

关键文件：

```text
frontend/android/app/src/main/kotlin/com/nx/miaoji/PaymentParser.kt
frontend/android/app/src/main/kotlin/com/nx/miaoji/LocalPaymentOcr.kt
frontend/android/app/src/main/kotlin/com/nx/miaoji/ScreenshotAccessibilityService.kt
frontend/android/app/src/main/kotlin/com/nx/miaoji/RecognitionDiagnostics.kt
frontend/android/app/src/main/kotlin/com/nx/miaoji/RecognitionStore.kt
frontend/lib/shared/services/screenshot_channel.dart
frontend/lib/shared/services/recognition_import_service.dart
frontend/lib/features/settings/screenshot_settings_page.dart
```

### 3.2 时间修复

用户反馈无障碍入账时间显示成 1970 或 14 点，实际应为上海时间 22 点。

已做修复：

- 后端 EF 读取 MySQL `DateTime` 时统一恢复 `DateTimeKind.Utc`。
- 后端 JSON 输出 UTC 时间时应稳定带 `Z`。
- Flutter 新增旧格式兼容：无时区字符串按 UTC 解释，再转换为上海时间显示。
- 不迁移数据库已有值，已有 `14:xx` UTC 值修复后显示为上海时间 `22:xx`。

关键文件：

```text
backend/MiaoJiZhang.Infrastructure/Persistence/AppDbContext.cs
frontend/lib/shared/services/shanghai_time.dart
frontend/test/theme_and_time_test.dart
```

### 3.3 更新检测

已接入 VersionFlow：

```text
更新接口根地址：https://version.nxsir.cn
接口路径：/api/client/v1/update
Android/iOS AppKey：已配置在项目中，但交接时不要外传到公开渠道
Internal 渠道：beta
Production 渠道：stable
```

功能点：

- 启动后自动检查一次。
- “我的”页面支持手动检查更新。
- 非强制更新支持忽略版本。
- 强制更新阻止继续使用。
- Android Internal 支持前台下载 APK、SHA-256 校验、包名/版本/签名校验和安装。
- Android Production 和 iOS 走外链，不内置 APK 自更新安装权限。

### 3.4 内测环境

当前约定：

- 只构建 `com.nx.miaoji.internal` 内测包。
- Internal 注入：

```text
INTERNAL_BUILD=true
API_BASE_URL=https://lt.frp-say.com:38012
APP_VERSION=20260722-132
```

- 之前误装过正式包 `com.nx.miaoji`，测试阶段应优先使用 `com.nx.miaoji.internal`。
- 后端应监听 `127.0.0.1:3000`，由 FRP 映射到 `https://lt.frp-say.com:38012`。

## 4. 已完成过的重要功能方向

这些内容在本会话中多轮推进过，后续 AI 需要沿着现有实现继续，不要重做：

- App 改名为“记之”。
- 正式包名锁定 `com.nx.miaoji`，Internal 包名 `com.nx.miaoji.internal`。
- 正式备案用 Release Key 已生成过，Debug MD5 不用于备案。
- 图标资源已换成用户提供的黑白记事本/笔图标方向。
- AI Agent 已从正则意图迁移到工具调用方向，收入/支出类型不能硬编码为支出。
- AI 查询应读取账本实时数据，不凭空回答金额。
- 截屏记账走一次性截图/授权，不保留长期 MediaProjection。
- 磁贴截图不应强制依赖无障碍；无障碍可用则静默，否则走一次性授权。
- 音量键快捷触发已放弃，系统音量键应恢复原生调音量。
- 游客模式应能离线记账、统计、预算和导出；游客不能使用 AI。
- AI 权限支持按用户关闭，关闭后所有 AI 入口不可见。
- 深色模式已加入三态：跟随系统、浅色、深色。
- 智能识别包含无障碍事件识别、通知识别、AI 截图补全三个开关。

## 5. 当前验证结果

最近一次验证结果：

```text
Android 单元测试：通过
Flutter theme_and_time_test：通过
后端 dotnet build：通过，0 warning / 0 error
Flutter analyze：无 error/warning，剩余 82 条 info 级既有风格提示
Android Internal Release 构建：通过
```

未完成验证：

- 后端集成测试依赖 Docker Desktop / Docker Linux Engine，当时 Docker 未启动，无法跑完。
- ADB 没有在线设备，因此未自动覆盖安装 APK。
- 微信/支付宝红包和支付流程仍需 Vivo 真机继续验收。

## 6. 常用命令

### Android Internal 单测

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang\frontend\android
$env:FLUTTER_ALREADY_LOCKED='true'
$defs=@('INTERNAL_BUILD=true','API_BASE_URL=https://lt.frp-say.com:38012','APP_VERSION=20260722-132') | ForEach-Object { [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($_)) }
.\gradlew.bat --no-daemon :app:testInternalReleaseUnitTest "-Pdart-defines=$($defs -join ',')"
```

### Flutter 测试

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang\frontend
C:\Users\nanxun\Documents\flutter\bin\cache\dart-sdk\bin\dart.exe C:\Users\nanxun\Documents\flutter\bin\cache\flutter_tools.snapshot test --no-pub test\theme_and_time_test.dart
```

### Flutter 静态检查

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang\frontend
C:\Users\nanxun\Documents\flutter\bin\cache\dart-sdk\bin\dart.exe C:\Users\nanxun\Documents\flutter\bin\cache\flutter_tools.snapshot analyze --no-pub
```

### 后端编译

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang\backend
dotnet build MiaoJiZhang.sln --no-restore
```

### 构建 Internal Release APK

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang\frontend\android
$env:FLUTTER_ALREADY_LOCKED='true'
$defs=@('INTERNAL_BUILD=true','API_BASE_URL=https://lt.frp-say.com:38012','APP_VERSION=20260722-132') | ForEach-Object { [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($_)) }
.\gradlew.bat --no-daemon :app:assembleInternalRelease "-Pdart-defines=$($defs -join ',')"
```

### 查看 APK 信息和 SHA-256

```powershell
cd C:\Users\nanxun\Documents\dsworkspace\jizhang
C:\Users\nanxun\AppData\Local\Android\Sdk\build-tools\36.1.0\aapt.exe dump badging release\JiZhi-1.2.5-internal-132.apk
C:\Users\nanxun\AppData\Local\Android\Sdk\build-tools\36.1.0\apksigner.bat verify --print-certs release\JiZhi-1.2.5-internal-132.apk
Get-FileHash release\JiZhi-1.2.5-internal-132.apk -Algorithm SHA256
```

### ADB 安装

```powershell
C:\Users\nanxun\Documents\platform-tools\adb.exe devices
C:\Users\nanxun\Documents\platform-tools\adb.exe install -r C:\Users\nanxun\Documents\dsworkspace\jizhang\release\JiZhi-1.2.5-internal-132.apk
```

## 7. 下一步建议

优先级从高到低：

1. Vivo 真机继续验收微信/支付宝红包、扫码支付、转账、通知与 OCR 双通道去重。
2. 启动 Docker Desktop 后补跑后端集成测试，尤其是 UTC 时间序列化、幂等入账、用户隔离和账本隔离。
3. 检查更新弹窗对 Markdown 的渲染能力；若仍无法解析，建议把更新说明限制为纯文本 Markdown 子集：标题、短横列表、空行。
4. 清理 Flutter analyze 的 82 条 info 级提示，至少优先清掉本轮触碰过的文件。
5. 继续优化智能识别诊断页，让“没事件、截图失败、OCR 无结果、规则拒绝、已入账、已合并”一眼能分清。
6. 把隐私政策、权限用途和第三方 SDK 清单里的 ML Kit 本地 OCR 描述补齐，方便后续上架审查。
7. 测试游客离线、登录同步、AI 权限关闭、AI 对话次数限制和深色模式全页面一致性。

## 8. 注意事项

- 不要把正式备案包 `com.nx.miaoji` 和内测包 `com.nx.miaoji.internal` 混用。
- 测试阶段不要构建或安装 Production，除非用户明确要求。
- 不要恢复音量键快捷截图，用户已经要求恢复系统原生音量键。
- 不要绕过 `FLAG_SECURE` 或支付 App 的安全截屏限制。
- 不要保存、上传或记录完整 OCR 原文、控件树、截图图片、API Key、JWT 或签名密码。
- 数据库里已有 UTC 墙钟时间不要迁移，当前策略是在读取和显示层修复。
- 若用户继续反馈“识别不到”，优先看智能识别最近诊断：事件是否收到、流程类型、金额来源、拒绝原因、OCR 是否 capture_failed。