# Freelance Timesheet（自由职业工时单）v1.0 交付说明

按《App 需求清单 v1》第 8 名「自由职业工时单（创意库 i279）」开发的第一版。

## 需求复核结论（开工前已做，信号未反转）

- 复核了 2026 年主流计时工具格局：Toggl Track 本身不做开票；Clockify 的开票是付费附加功能且整体是账号 + 团队导向；Harvest 能把工时变成发票，但免费版限 1 人 2 个项目、完整功能按席位订阅；Hubstaff、Time Doctor 等则主打团队监控。头部工具的「计时 → 对账单」都绑在账号、云端和订阅里。
- 同时注意到桌面/网页端出现了 Timbite、TallyHo 等主打「无账号、本地、单人」的新玩家，说明「去账号化的极简路线」是当前真实活跃的方向，不是伪需求。
- 结论：「按项目计时 → 一键生成月度对账单 PDF、全程离线、无账号、无团队」这条极简直线在主流移动产品里仍是空位，信号未反转，照计划开工。差异化押在三点：无账号、零联网（未申请 INTERNET 权限，已用 aapt 校验）、计时与对账单两步直达。
- 诚实标注：计时 + 导出本身市面上有零散老产品，本品的差异不在功能有无，而在于只做这一条线、路径最短。

## 产物

- APK：`~/workspace/your_files/FreelanceTimesheet-v1.0.apk`（约 15.6 MB，debug 签名，可直接装）
- 源码：`~/workspace/freelance-timesheet-android/`
- 包名 `com.freelancetimesheet.app`，versionCode 1 / versionName 1.0，minSdk 24 / targetSdk 34
- Kotlin + Jetpack Compose 纯原生（无 WebView），本地 SQLite 存储；aapt 校验确认**未申请 INTERNET 权限**（仅有 AndroidX 自动生成的内部权限），零联网、无账号。UI 英文优先。

## 第一版功能（按需求文档只做 2 个）

1. **按项目计时 + 补记工时**
   - 项目：名称、客户（可选）、时薪、币种（20 种可选）；新建项目默认带入设置里的默认时薪/币种。
   - 计时：点项目行上的 ▶ 即开始；计时中可暂停/继续（暂停时间不计费），结束时可填备注存档；开始新计时会自动结束上一个。计时状态存在数据库里，杀掉 App 重开照常续算，不依赖进程存活。
   - 补记：手动录入项目 + 日期 + 开始时间 + 时长（时/分）+ 备注。
   - 条目可改（日期、开始时间、时长、备注）、可删；列表按天分组，显示时长与金额。
   - 计费快照：每条记录在创建时锁定当时的项目名、客户、时薪、币种——之后改项目名或时薪只影响新记录，历史对账单永不被改写（这是有意设计，对账场景下这是正确行为）。
2. **月度对账单（PDF）**
   - 按月切换（‹ ›），可按项目筛选（全部 / 单个项目发给对应客户）。
   - 汇总区：每个项目一行（条数、总工时、总金额），多币种按币种分行给总额，不做汇率换算。
   - 明细区：逐条列出日期、起止时间、备注、工时、金额；多页自动分页。
   - 单据抬头用设置里的姓名/业务名与邮箱；一键生成 PDF 并走系统分享发给客户。

设置页：姓名/业务名、邮箱、默认时薪、默认币种。

## 未做（按 v1 范围砍掉，后续迭代候选）

订阅付费墙、云同步/账号、团队功能、CSV/Excel 导出、多语言 UI、发票编号/税率/付款状态跟踪、计时常驻通知、release 签名包、上架所需的隐私政策与 Play 类目声明。

## 已知问题（如实）

- 未做真机/模拟器实测（环境无模拟器），仅完成完整编译打包 + APK 结构校验；建议真机首验一遍「开始计时 → 暂停 → 结束 → 生成对账单 PDF → 分享」这条链。
- 计时中没有常驻通知提醒：计时靠时间戳计算、准确性不受影响，但用户要打开 App 才能看到正在计时的项目，长时间忘关计时器时只能事后编辑条目修正（可编辑时长已覆盖这个补救路径）。
- 条目编辑用文本框输入日期（yyyy-MM-dd）和时间（HH:mm），格式错了会弹提示，没有图形化日期选择器。
- 工时按秒累计、金额按精确小时数计算；对账单上的工时统一显示 2 位小数（如 2.50 h），不做 6 分钟/15 分钟取整规则（部分客户合同有取整要求，v1 未做）。