244 lines
10 KiB
Markdown
244 lines
10 KiB
Markdown
# 记之项目交接档案
|
||
|
||
生成时间：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。
|