TianshangPeriodPal

Imported from Tianshang301/TianshangPeriodPal (AGENTS.md). Install upstream with npx skills add Tianshang301/TianshangPeriodPal. Copyright stays with the author.

TianshangPeriodPal（天殇 · 月记）v2.0.0

0. 产品名称与愿景

产品名称：TianshangPeriodPal 中文名称：天殇 · 月记 所属宇宙：Tianshang Universe

愿景： "殇"意为早逝、非正常之死。在月经健康数据被大肆商业收割的时代，用户的隐私权与数据主权早已"夭折"。天殇 · 月记是一座墓碑，埋葬的是被巨头蚕食的信任；同时，它也是一声警钟，提醒每一位用户：你的身体数据，本不该是他人的资产。

我们是一个完全离线、本地加密、开源免费的月经记录与管理工具。通过不可绕过的技术架构（零网络、强加密、可审计源码），我们确保数据永远只在用户手中。这里没有"云同步"的糖衣，没有第三方 SDK 的窃听，没有算法推荐的陷阱。天殇，是向隐私侵犯宣战的宣言；月记，是每位用户对自己身体的温柔记录。

1. 产品概览

一款纯粹的离线的原生 Android 应用，用于记录月经周期、预测经期与排卵期，提供痛经等多维度分析，并通过人性化提醒关怀用户。

核心差异化优势：

• 所有数据仅存储在设备本地，不联网，零网络权限
• SQLCipher AES-256 数据库加密（v2.0.0 起默认启用），Android Keystore 密钥管理
• 开源可审计，MIT 协议，全源码交付
• 终身维护承诺，不因商业利益而变更隐私立场

强调：隐私安全、可爱风格与高度自定义。

2. 技术栈与环境

• 语言/框架：Kotlin 1.9.24, Jetpack Compose (Material 3)
• 架构：MVVM + Repository + StateFlow（UiState 密封类模式）
• 数据库：Room 2.6.1 + SQLite，渐进式 SQLCipher 4.6.1 加密
• 加密：SQLCipher（AES-256），配合 Android Keystore 管理主密钥，Argon2id 哈希 PIN
• 最低 SDK：API 28（Android 9），目标 API 35（Android 15）
• 关键依赖：
  • AndroidX Navigation Compose（底部导航）
  • DataStore（用户偏好设置）
  • WorkManager（提醒任务调度，离线可用）
  • MPAndroidChart（趋势图）
  • Gson / Apache Commons CSV（导出/导入）
  • Bouncy Castle 1.78（Argon2id 实现）
  • Coil 2.5.0（图片加载）

关键限制：完全离线，无任何 INTERNET 权限，无第三方数据收集，无 Firebase/Analytics/Crashlytics。

版本锁定：Room 2.6.1 为当前天花板，禁止升级至 Room 2.8.x（SQLCipher 尚未兼容 beginTransactionReadOnly()）。

3. 全局设计要求

• 主题：粉色可爱风格（Hello Kitty 类型），默认粉色主色调（#FFB6C1 附近）。v2.0.0 升级为自定义色彩引擎，用户可自由调整 HSL。
• 可定制性：用户可更换主色、背景图片（从本地相册选取）。
• 应用锁：启动时强制指纹/面部验证，使用 BiometricPrompt 和自定义 PIN/密码回退。密码采用 Argon2id 哈希存储，后台切换立即锁定（可选延时）。
• 多语言：支持中文、英语、日语、韩语、法语、西班牙语、阿拉伯语。语言切换隐藏在"我的 → 设置 → Language"内，默认跟随系统（不支持时回退中文）。RTL 语言（阿拉伯语）布局已适配。
• 隐私政策与用户协议：首次启动强制展示，本地 HTML/文本，不可跳过，必须滚动到底并停留 5 秒后确认。不同意则退出应用。不联网。

4. 底部导航结构

5 个 Tab，图标 + 文字：

1. 日历首页（CalendarScreen）
2. 记录录入（RecordScreen）
3. 数据分析（AnalysisScreen）
4. 提醒设置（ReminderScreen）
5. 我的（ProfileScreen）

5. 数据库设计（Room Entities）

所有表均通过 Room 管理。v2.0.0 新安装默认 SQLCipher 加密；从 v1.5.x 升级的用户保持明文，可手动迁移。

5.1 PeriodRecord（月经记录）

5.2 DailySymptom（每日症状）

5.3 UserSettings（本地 DataStore + Room 单行表）

• 周期长度预测模式（自适应）
• 黄体期长度（默认 14 天）
• 提醒开关/时间/提前天数/类型
• 痛经分析偏好
• 主题颜色、背景图片 URI
• 应用锁密码哈希（Argon2id）
• 数据库加密状态标志（db_encrypted）

6. 核心功能模块规划

6.1 月经预测引擎（本地自适应算法）

• 输入：所有历史月经记录（至少 3 个周期开始有效预测）。
• 周期长度计算：(开始日 - 前一个开始日)，剔除异常值（IQR 方法），取加权中位数/均值，并可随时间加权近期数据。
• 经期长度：默认 (结束日 - 开始日 + 1)，同样自适应学习。
• 排卵日预测：基础算法 = 下一次经期开始日 - 黄体期长度。结合体征改进：
  • 若某日记录了排卵试纸阳性或宫颈黏液蛋清样，则实际排卵日调整为该日附近，并微调该周期黄体期长度。
  • 若连续测量基础体温（BBT），通过体温升高识别排卵，进一步提高准确度。
• 预测结果：输出未来 3-6 个月的预测经期、排卵期、易孕窗口（排卵日前 5 天 + 排卵日 + 后 1 天）。
• 更新时机：每次新增/编辑记录后重新计算。
• 可解释性：界面上展示预测依据（如"基于过去 10 个周期平均 28 天推算"）。

6.2 本地分析功能（数据分析页）

• 周期长度变化曲线：折线图，X 轴=周期序号，Y 轴=天数。
• 经期时长分布：柱状图/直方图。
• 痛经趋势：按周期统计平均痛经等级，绘制折线图，并标记异常。
• 症状统计：饼图/柱状图显示常见症状频率。
• 周期规律性评分：标准差除以均值，给出"规律/较规律/不规律"等级。
• 排卵期日历标记：在日历视图中用颜色圈出预测排卵日及易孕期。
• 导出功能：支持导出为 CSV（含周期记录和每日症状），可含预测数据。通过 Android Share Sheet 发送，全程离线。

6.3 提醒系统（基于 WorkManager）

• 提醒类型：
  1. 经期预测提醒（默认提前 1 天）
  2. 排卵期提醒
  3. 经前综合征（PMS）提醒（提前 5 天）
  4. 自定义备忘（用户自定义文本、日期时间）
• 独立开关与设置：每种提醒可独立开启/关闭，可调整提前天数、提醒时间（小时:分钟），可自定义通知内容模板（$date 等变量）。
• 通知通道：Android 8.0+ 多通道，支持静默或振动，需引导用户授予通知权限。
• 提醒触发逻辑：WorkManager 一次性任务，每次新预测结果或提醒设置变更时重新调度。加密数据库不影响后台访问（Keystore 密钥与 PIN 解耦）。

6.4 隐私与安全（v2.0.0 强化）

• 强制用户协议：首次启动全屏弹窗，内含用户协议与隐私政策（本地 HTML/文本），必须滚动到底且停留 5 秒后点击同意。不同意则退出应用。
• 应用锁：
  • 进入前台时要求生物识别（指纹/面部）或 PIN/密码。
  • 密码验证作为后备，密码采用 Argon2id 哈希存储于 EncryptedSharedPreferences。
  • 应用退到后台立刻锁定（可选延时）。
• 数据加密（v2.0.0）：
  • 新安装：Room 数据库默认 SQLCipher AES-256 加密，密钥由 Android Keystore 生成并加密存储。
  • 老用户：可选手动迁移，原子操作（导出→重建加密库→导入），失败自动回滚明文备份。
  • 密钥与 PIN 解耦：用户修改 PIN 不影响数据库密钥。
• FLAG_SECURE：敏感页面禁止截图/录屏。
• 垃圾箱/回收站：删除的记录进入回收站，30 天内可恢复，之后永久删除。

6.5 历史记录管理

• 编辑：可修改任何历史周期、每日症状。
• 删除：软删除，移入回收站，可批量删除。
• 恢复：回收站页面，显示删除时间，可恢复。
• 手动备份：提供数据库完整导出/导入（加密格式），导入时验证哈希。

6.6 界面与交互

• 日历首页：
  • 月视图日历，标记经期（红色）、预测经期（浅红）、排卵日（蓝色）、易孕期（浅蓝）。
  • 点击日期查看当日症状详情或快速记录。
  • 顶部显示当前周期天数/剩余天数。
• 记录录入：
  • 快速记录：一键记录今天开始/结束经期。
  • 详细页面：日期选择、流量、痛经等级、症状多选（可自定义新症状）、性生活、排卵试纸、宫颈黏液、基础体温、备忘。
• 数据分析：Tab 或滑动切换：周期、痛经、症状、排卵。
• 提醒设置：按类型排列，每个类型右侧有开关，点击展开详细设置。
• 我的：主题定制、密码锁定、语言、回收站、备份恢复、数据库加密状态、关于。

7. 开发路线图（Phase）

已完成（基于 v1.4.0）

1. 项目初始化：Gradle, 依赖, 基本导航, 主题框架。
2. 数据库配置：Room 实体与 DAO。
3. 用户协议与应用锁：隐私政策 UI 与验证逻辑，生物识别集成。
4. 记录功能：增删改查，日历视图标记。
5. 预测引擎：核心算法实现，结合体征校正。
6. 数据分析：图表绘制，统计逻辑。
7. 提醒系统：通知通道，WorkManager 调度，自定义通知内容。
8. 多语言与主题定制：字符串资源，颜色选择器，背景图片。
9. 回收站、备份与导出。
10. 工程化文档：README, SECURITY.md, CHANGELOG。

进行中 / 规划（v2.0.0）

11. SQLCipher 渐进加密：Keystore 密钥管理，原子迁移，失败回滚。
12. 加密数据库导出/导入格式：支持加密 ZIP 的完整备份/恢复。
13. 自定义色彩引擎：HSL 滑块，Material 3 Dynamic Color 适配。
14. Bouncy Castle Argon2id PIN 哈希：通过 SecurityProvider 集成。
15. 测试覆盖：单元测试（预测算法、Repository），UI 测试。
16. Google Play 上架：Pro 版付费功能（深度分析、无限历史、高级导出）。
17. TianshangCore 抽离：公共模块化为独立 Gradle 模块，供 TianshangHealth 复用。

8. 双版本维护策略

TianshangPeriodPal 采用物理隔离的双目录维护模型：

TianshangPeriodPal-Project/
├── TianshangPeriodPal-v1.5.0/     # 稳定维护分支（独立 Git 仓库）
└── TianshangPeriodPal-v2.0.0/     # 主开发分支（独立 Git 仓库）

迁移规则：v1.5.x 用户永不强制升级。v2.0.0 新装默认加密；老用户于 Settings → Data Security 手动触发迁移，原子操作，失败自动回滚。

8.1 VersionCode 管理规范

规则：

• v1.5.x 的 versionCode 必须保持在 1-999 范围内
• v2.0.x 的 versionCode 从 1000 开始递增
• 两段永不冲突，确保 Google Play 可区分版本
• v2.0.x 发布新版本时 versionCode 递增（如 v2.1.0 = 1001, v2.2.0 = 1002）

8.2 分支管理

8.3 Keystore 管理

• release keystore 文件：app/periodpal-release.jks
• 密码配置：local.properties 中的 KEYSTORE_PASSWORD、KEY_ALIAS、KEY_PASSWORD
• 注意：正式上架 Google Play 需要使用专用 release keystore，当前使用 debug 签名

8.4 发布流程

1. 确保 versionCode 和 versionName 已更新
2. 构建 APK：./gradlew assembleRelease（需设置 JAVA_HOME 为 JDK 17）
3. 提交代码并推送分支
4. 创建 GitHub Release 并上传 APK
5. Release Notes 中注明 versionCode 和 versionName

9. AI 协作规范

当 AI 协助本项目时，必须遵守：

1. 永不生成硬编码密钥或 fallback 密码。
2. 必须使用参数化查询，禁止 SQL 拼接。
3. 必须验证外部输入（白名单机制）。
4. 禁止添加 INTERNET 权限或云依赖库。
5. 优先使用 StateFlow<UiState> 密封类管理状态。
6. 不确定安全时，选择更严格的方案。
7. 发现现有代码安全问题时，必须先标记再添加新功能。
8. v2.0.0 中所有 Room DAO 必须兼容 SupportFactory，禁止硬编码数据库密码。
9. 新增数据库导出/导入功能必须验证加密格式的完整性哈希。
10. Keystore 密钥生成必须指定 PURPOSE_ENCRYPT | PURPOSE_DECRYPT，禁止使用 KeyGenParameterSpec 构建器之外的密钥生成路径。

10. 注意事项

• 所有"强制观看"协议本地存储，不联网。
• 多语言字符串需提前外部化，RTL 语言（阿拉伯语）布局适配。
• 应用锁不可绕过，必须保证加密数据库在未认证前不可访问。
• 提醒权限申请以温和方式多次引导，不强制。
• 预测算法必须可解释，在界面上展示预测依据。
• 终身维护：本项目由 Tianshang 维护至生命终结。不存在放弃场景，只有休眠与已知稳定版本。
• 数据主权：用户的数据物理上永远属于用户本人，开发者即使想获取也技术上行不通。