Skip to content

About

按行管理的中文工作日志:Cloudflare Worker + D1 + Vue 3;部署地址与标识只存在于 Secret,不写入仓库

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

案记 (case-notes)

律师的中文私人工作日志。记录、待办和日程共用有序文本行,由 Cloudflare Worker、D1 和 Vue 3 提供网页、REST API、MCP 与操作审计。卷宗文件保留在本机。(仓库名与 npm 包名均为 case-notes。)

部署在自己的域名上;部署地址、Cloudflare 账户/区域与数据库标识只存在于运行时 Secret 与本地 .dev.vars,不写进仓库,也不打进 APK。

目录

文档入口

文档 唯一职责
本 README 项目概览、实现入口、本地开发、发布和凭证配置
AGENTS.md 助理修改项目时的约束与验证要求
src/schemas.ts instructions 保存共用流程与记录语法;descriptions 说明动作行为,schemas 定义输入,outputSchemas 定义案件、行、查询结果及写入回执
MCP 初始化说明、工具清单与在线 OpenAPI 同源自动提供上述规则与参数,无独立操作文档

使用案记时连接 case-notes MCP,规则由服务随初始化和工具清单提供。外部工作目录不引用独立指南、不复制规则或依赖本地项目路径。周报等下游流程由使用方维护。

产品规则、参数和工具行为改变时统一更新 src/schemas.ts,MCP 与 OpenAPI 自动使用同一来源。README 和 AGENTS 只维护项目说明与开发约束,不复制使用规则。过程记录、旧方案和单次测试报告不作为长期文档保存,变更历史由 Git 与 CI 留存。

本地开发与验证

需要 Node.js 22+。在项目根目录执行:

npm ci
npm run setup:local
npm run dev

setup:local 应用本地结构迁移,在 .dev.vars 不存在时生成随机网页登录密码;不导入日志。已有环境启动只需 npm run dev,也可使用 start.cmd。wrangler.jsonc 由 tools/render-wrangler.mjs 从 wrangler.template.jsonc 与 .dev.vars/环境变量生成,本身不进版本库;npm run dev、npm run build、npm run db:migrate 与部署前都会自动生成一次,本地缺少部署值时使用占位域名。

网页地址为 http://127.0.0.1:8787,MCP 为 http://127.0.0.1:8787/mcp;本地回环与内网 IP 保持 HTTP,不触发线上 HTTPS 跳转。用 .dev.vars 中的 WEB_PASSWORD 登录;MCP 客户端通过 OAuth 登录授权后即可连接。更新已有本地环境时运行 npm run db:migrate 应用统一数据库迁移。本地数据库身份保持稳定,目录改名时 .wrangler/ 一起保留。本地库与云端库独立,修改不会自动同步。

npm run typecheck
npm test

npm test 的前置步骤已执行构建。npm run build 是 Wrangler dry-run,不部署。数据库测试使用临时隔离 Miniflare/D1;界面变更另按 AGENTS 中的要求检查浏览器。本地调试安卓壳需要 Node.js 22+,先在项目根目录执行 npm ci,再用 Android Studio 打开 android/;Gradle 的 prepareShell 自动生成公共资源与本地模块,生成资源不进 Git。

代码入口

位置 职责
src/worker.ts、auth.ts、oauth.ts HTTP 路由、参数校验、登录会话、AI 鉴权与 MCP OAuth 授权
src/schemas.ts、mcp.ts AI 工具定义、OpenAPI 与 MCP 适配
src/service.ts、parser.ts、ordering.ts、receipts.ts 事务读写、版本、审计、幂等、行解析、稀疏排序与回执存储
src/queries.ts、search.ts、web-queries.ts 版本校验分页、统一搜索与网页实时查询
public/index.html、legacy-app.js、legacy.css、theme.css Vue 页面、视图逻辑、布局样式与共享设计变量
public/page-deck.js、navigation.js Swiper 页面滑动、延迟展示与明确的返回层级
public/login.html、login.js、login.css 登录页面、密码显隐与登录反馈
public/404.html、404.css 自定义未找到页面与返回首页入口;静态资源未命中时返回 HTTP 404
public/oauth.js、oauth.css OAuth 授权页的密码显隐、提交反馈与布局;页面由 Worker 渲染
public/db-adapter.js、session-access.js、editor.js、paging.js、read-cache.js、persistent-cache.js 数据适配、网页会话与离线核验、行身份维护、连续分页、响应式内存缓存与会话隔离的 Dexie 持久缓存
migrations/business/、migrations/auth/ 统一数据库的结构迁移与旧鉴权库迁移历史
tests/ 隔离数据库、接口和前端逻辑测试
tools/ 环境初始化、部署配置渲染、本地备份、域名与资源防护配置、线上核验
android/ 安卓 Web 套壳:单 WebView 打开本机填写的服务器域名,包名 com.teamilkman.casenotes
.github/workflows/deploy.yml 检查与 CI 发布流程
.github/workflows/android-apk.yml 安卓质量核验(手动/PR):构建调试包与 JVM 单元测试,不阻塞发布
.github/workflows/android-release.yml 安卓 APK 的签名与 android-latest Release 发布

当前实现

鉴权与数据

网页会话与 AI OAuth 令牌分别鉴权,REST 与 MCP 调用同一业务服务。AI 访问只通过 OAuth 登录授权,没有固定令牌;OAuth 使用现有网页登录密码或有效网页会话确认授权,不需要第三方账号或新增 Secret。网页会话有效期 30 天;剩余不足 15 天时在已认证访问中自动续期至 30 天并重发 Cookie,令牌与缓存范围不变,活跃用户不因固定到期日被集中要求重新登录。

MCP 使用无状态 POST/JSON 请求响应,不提供独立 SSE 监听流;其他方法直接返回 405 与 Allow: POST,不访问数据库或创建传输实例,避免空闲连接关闭后自动重连。动态接口在解析请求体与数据库鉴权前通过 Workers Rate Limiting binding 按 IP 共用每分钟 120 次的计数,登录与 OAuth 另按 IP 共用每分钟 20 次;认证后的 AI 请求在 REST 与 MCP 间按工作空间和 OAuth 客户端共用每分钟 30 次,不因刷新令牌或切换 IP 重置。网页预加载不占 AI 客户端计数。超限返回 429、Retry-After 与明确的未提交状态;OAuth 保持自身错误格式。原有失败登录限流继续保留。计数不写 D1,按 Cloudflare 数据中心近似执行,不是全局精确配额。

CI 同步维护专用部署区域的全站免费 WAF 边缘规则:每 IP 10 秒 100 次,超限拦截 10 秒,在 Worker 执行前拦截以减少调用额度消耗。规则作用于整个 Zone 的全部主机、路径和方法,页面、静态资源、API、MCP 都计数,阈值为首次页面加载和框架预缓存留有余量;该区域专用于案记,后续子域名也共享计数。默认 workers.dev 地址和版本预览地址均关闭,网页、REST 与 MCP 统一使用自定义域名,避免绕过区域边缘防护;CI 回读核验两类入口保持关闭。CI 通过稳定规则 ref 创建或更新并回读核验,不替换整个规则集;免费规则名额被其他规则占用时中止发布,不覆盖他人规则。应用内限流本身仍消耗 Worker 调用,边缘规则也有计数延迟,两层均不承诺每日额度硬上限。

CI 同时维护部署区域的 Always Use HTTPS 与 HSTS(180 天,含子域),HTTP 请求在边缘升级到 HTTPS;Worker 另对 /、/index.html 和 /login.html 的明文导航返回 308,本地回环地址与内网 IP 除外。API 请求不在 Worker 内做跨协议跳转,避免 credentials: 'same-origin' 在跳转后丢失 Cookie。网页 Cookie 带 Secure,明文页面既不会发送也不会被允许覆盖它,因此登录和退出都只在 HTTPS 下工作。

OAuth 提供资源与授权服务器发现、动态客户端注册、S256 PKCE 授权码、刷新令牌轮换及撤销。客户端连接 /mcp 后通过浏览器明确同意授权;访问令牌有效期 1 小时,授权最多保留 30 天,客户端注册有效期 1 年。授权码有效期 5 分钟且只能兑换一次;重复使用刷新令牌会撤销该授权,客户端应串行续期。令牌绑定连接时的域名、MCP 地址、工作空间及客户端,令牌不能跨域名使用;OAuth 令牌用于 REST 与 MCP,保持 AI 权限与客户端审计身份,不能调用网页专属接口。鉴权表仅保存随机凭证摘要,不保存明文授权码、访问令牌、刷新令牌或客户端密钥;网页登录密码仍由 Secret 配置。公开注册与授权入口限流,过期记录按索引限量清理。

统一数据库 DB 用不同表保存日志、网页登录会话与 OAuth 客户端、授权请求及令牌摘要;绑定和静态资源配置见 wrangler.jsonc(由 wrangler.template.jsonc 生成,见「本地开发与验证」)。

数据 职责
cases、case_aliases 案件/事务元数据、状态、别名及版本
log_lines 原始文字、稳定行 ID、顺序、行版本与软删除状态,日志事实来源
line_index 有效行的派生类型、日期、待办状态与期限、日程及诊断;案件键和日期索引支持最近活动与日期范围读取
operations、audit_changes、write_guards 幂等回执、修改前后留痕与事务内版本保护
read_snapshots、read_snapshot_rows 已停用的历史结构,当前查询不读写

自动资源防护

Cloudflare 原生 Monitors 每 5 分钟查询一次分析数据:全账号 UTC 当天 Worker 调用量达到 5 万次提醒、8 万次紧急提醒;案记最近 5 分钟达到 300 次调用时提醒。所有状态码均计数,不把持续返回 200 的重连当作正常;提醒由 Cloudflare 自行发送到 RESOURCE_ALERT_EMAIL,不用另建发信服务。每日提醒重复间隔 24 小时,短时提醒重复间隔 1 小时。查询使用带采样权重的原生分析数据,不读取日志正文、凭证或卷宗。已有其他通知策略保持不变。

Worker 的定时任务每 15 分钟复查同一份分析数据,每天最多 96 次计划执行,不在浏览器轮询,也不高频运行 GitHub CI。账号当天达到 8 万次时,自动在边缘暂停 MCP 和带 Authorization 的 AI REST 请求,等 UTC 次日零点(北京时间 08:00)后复查用量再恢复;网页 Cookie 会话及网页使用的 REST 仍放行。案记最近 5 分钟达到 300 次,或至少 100 次且达到此前 30 分钟平均每 5 分钟用量的 10 倍时,同样暂停 AI;该 5 分钟窗口每 15 分钟取样一次,更短的尖峰由上述 5 分钟一次的原生提醒捕获。首次冷却 15 分钟,短期反复异常延长到 30、60 分钟。冷却结束后需重新读取指标,仍异常则续停,恢复不主动调用任何 AI 工具。无手动暂停开关。

自动状态保存在本项目 WAF 自定义规则的描述与启用状态中,不写业务 D1;发布保留当前冷却,不会重新开放已暂停的入口。指标缺失、请求失败、状态不合法或检测到并发更新时不自动恢复,等后续定时任务重查。RESOURCE_GUARD_TOKEN 是仅具账号分析读取及部署区域 WAF 编辑权限的独立运行时 Secret,不使用 CI 的部署令牌。定时器、分析数据和规则传播均可能延迟,因此这是尽力保护,不是全局精确每日额度硬上限。

浏览器统一遵守 Retry-After,限流期间的新读取和写入在本机停止,不排队补发;迟到成功响应不清除其他请求的冷却。连续网络/响应失败按 1、2 秒退避,第三次起冷却 60 秒;只有登录的网络失败最多自动尝试三次,并增加随机间隔,认证拒绝、限流和服务器错误不自动重试。业务写入仍仅由用户操作重试,保留原请求键及草稿;不增加后台刷新。第三方 MCP 客户端遵守服务器的 405/429 语义,项目不会修改外部客户端配置。

写入与查询

写入在一个 D1 批次事务中提交原文、索引、版本、审计和回执。已有行按行版本检查,元数据按元数据版本检查,整段保存和锚点插入按文档版本检查;普通追加不要求先读版本。笔记保存复用已有排序键,追加、删除和有足够间隔的插入只写变化行;移动或间隔不足时只调整所需区间,保留未变行的 ID、版本、排序与修改时间。新增审计按本次行 ID 读取,不扫描全库。软删除保留原文、身份、版本及审计,由同一事务中的触发器移除派生索引。网页勾选完成会软删除原待办并在末尾新增完成行;AI 改写原待办为完成记录时保留原行 ID。较大的新回执行数组使用 gzip 压缩存储,提交时元数据仍在事务内生成;返回和同键重放恢复完整原回执,兼容已有未压缩回执,不清理历史回执或审计。

AI 查询使用只读排序键游标,不创建或清理持久快照。每页在一个 D1 批次事务中读取版本、元数据和结果,复用案件现有正文及元数据版本检测跨页修改;工作区查询同时使用案件数量与版本之和,单案查询只校验该案。续页复用首次数量,不重复统计,全文响应按 UTF-8 体积分页。搜索先筛选和分页排序键,只为当前页涉及的案件生成一次元数据,计数不构造案件 JSON。网页列表使用实时排序键游标;案件详情共用 AI 的版本校验读取。网页案件、待办和日程列表按页读取,详情读全文,日历按月读取,热力图只取日期计数。待办和日程从类型索引开始读取,近期统计和列表从日期范围索引开始读取;最近活动通过有效行的案件/日期覆盖索引求最大值,不遍历案件正文。中文正文搜索使用数据库字面片段匹配,半角英文字母不区分大小写;总数计算、正文搜索及表达式排序仍可能扫描候选行,大规模优化应依据查询计划与 D1 读取量。失败登录按过期索引每次最多清理 100 个失效桶,保留尚未到期的限流状态。

网页品牌统一为“案记”(Case Notes),旧浏览器会话首次验证时换发新 Cookie,保留原会话期限。旧草稿和未确认请求键原样迁到新存储名称;冲突时保留两个副本,复制失败不删除旧记录。旧读取缓存经会话验证后清理,新读取缓存重新按需建立。历史标识只在兼容迁移代码及历史记录中保留。

网页界面

案件列表顶部提供「新建笔记」,输入名称并选择案件或事务后创建,直接进入现有正文编辑器;创建结果不明时保留原请求供重试核对,离线时禁用创建。

详情使用统一的「编辑笔记」入口,同时编辑名称、状态、案由、案号、法院、创建日期及正文;资料字段随文字扩宽,到达可用宽度后换行增高,状态使用文字下拉框。手机端资料编辑使用紧凑控件与间距,编辑状态提示与正文插入工具同排,为正文保留更多可用高度。保存同时核验正文和变更资料的版本,在一次事务提交正文、元数据、索引、审计及回执;归档案件可改资料,正文保持只读。资料与正文草稿共同保留,冲突时保留输入供核对。

网页使用统一的浅色绿系主题,保留看板、案件和日历三个主视图。正文按视觉人体工学设定字号下限(正文 15px、列表 13–14px、辅助信息 12px、角标 11px),中文行距 1.65–2,案件长文行宽限制在 44em 内,避免过宽行与过小文字引发的视疲劳;沿用浅色正极性配色,不引入纯黑白高反差或闪烁动画。工作统计常驻顶部导航区;看板与案件采用全宽布局,主视图不设置独立的页面大标题,待办截止日期与案件名称同排显示。手机三个主视图共用紧凑页头并省去副标题;看板保留待办和开庭两个分栏,看板分栏、开庭筛选及案件分组选项卡共用 44px 高度、内边距、字号和选中指示样式;近期完成控件采用紧凑留白,省去分栏内重复标题,开庭卡片收紧内边距、行距及行间留白,状态徽标紧跟案名,保留 44px 点击高度,完整在办案件列表统一在案件主视图查看;桌面看板继续并列显示三个分栏。看板开庭安排默认显示未来日程;案件详情展示元数据和工作记录;桌面使用紧凑案名操作栏、横向元信息与轻量记录页眉,长元信息自动换行,正文使用剩余高度,编辑标签与插入工具同排,桌面编辑支持并排预览,手机通过标签切换编辑与预览,日程插入弹窗支持键盘焦点和 Escape 关闭;插入工具按钮不夺取正文焦点,手机端不会因此收起输入法或跳动布局,点击一次即可切换并保留光标位置。登录页提供密码显隐和提交状态。日历以月历与当日安排并列展示,默认只显示开庭;将月历顶部工具栏的开关从「仅开庭」切换到「全部日程」后,按月补充待办、记录、完成记录与事务日程,并在月历和当日安排中显示类型,开庭统计与年度分布仍只统计开庭。手机使用 48px 日期格、圆点和时间摘要,精简重复标题、汇总、图例、说明与跳转栏,隐藏下一开庭日链接,紧凑排列月历和当日安排以尽量同屏显示;月份跳转使用统一样式的年份与月份面板,支持键盘操作;横屏月历随可用高度布局,当日安排在面板内滚动,并保留键盘选日及年度开庭分布,打开案件后返回保留所选日期和滚动位置。日历同时按年读取法定节假日(数据来自 NateScarlet/holiday-cn,经 Worker 按年代理并写入边缘缓存,浏览器只访问本站接口),节假日日期格显示暖红色块与「休」标,调休上班日显示「班」标,节假日名称出现在日期格与当日安排中。

手机和触控设备的主要操作保留至少 44px 触控高度,待办复选框使用 44px 点击区域并对齐正文首行,案名和截止信息紧凑排列。手机竖屏及短横屏使用本地提供的 Swiper 14 页面滑动:三个主视图、看板分栏、案件分组、案件列表与详情、编辑与预览及日历月份支持跟手横拖、松手切换或回弹,按钮切换也沿水平方向移动。横划支持边缘起手和轻微斜向,内部滑动优先,分栏边界可交给主视图;文字输入、横向代码/表格和热力图保留自身交互,纵向滚动、多指及取消手势不提交页面切换。首屏加载完成后准备并保留主视图邻页,月份预览提前布局,避免拖动过程中挂载整页;月历区域的手势始终用于切换月份,快速滑动、越界或切换尚未结束时不传给主视图;换月动画完整结束后再接新拖动,取消未被接纳的触摸不回退已提交的切换,切换至减少动画偏好时完成当前目标并解除过渡状态。已读取页面、分页、各栏滚动和草稿继续复用,离屏页不自动续读,重新选中时按需检查写入后的失效查询。日程弹窗在手机上以底部面板显示,页面适配安全区与动态视口;编辑正文获得焦点时收起统计和主导航,为软键盘留出空间。页面不使用上下入场动画,过渡与手势遵循系统减少动画偏好。

读取缓存与离线

前端使用页面内存与 Dexie/IndexedDB 两层读取缓存,共享在途读取并隔离迟到响应。读取时先显示本地旧缓存与加载中状态,再做离线判断:联网成功即完成更新,无法成功则维持现有的离线状态继续显示旧副本。启动时先采用本机已存会话定位旧副本以便即时显示,并并行核验一次会话刷新变更令牌,仅当工作空间确有变化才刷新当前视图;前台恢复核验发现令牌变化时,同样使内存列表失效并重读。核验期间页面顶部显示「正在同步缓存内容…」,成功后消失,失败转为离线只读提示。看板、案件等列表首屏同样先用持久旧页即时占位,再从原请求页联网核验;新页整体替换占位,不沿用旧页游标或保留已移除的行,后续分页才追加。网络或云端认证不可用时,可继续读取本机此前验证身份下的离线副本,不因云端会话过期停止查看。认证拒绝不授予云端访问权限;没有已验证的本地身份、服务器业务错误或存储异常不能生成离线副本。不同登录范围切换会清理旧副本。

持久副本的自动联网新鲜度由服务端工作空间变更令牌决定:/api/session 随会话返回案件计数、正文修订与元数据版本聚合的令牌,复制副本时记录当时令牌,页面加载核验同一令牌即证明副本仍是最新,无需计时器、也不存在超时强制刷新;令牌变化表示数据已改,旧副本先作为旧缓存显示并保持加载中,再联网重新读取,未带令牌或令牌不同的副本一律不直接作为最新复用,但仍保留在原处供离线查看。云端会话过期不影响已有副本的离线查看;需要重新登录时保持只读离线模式,由用户选择登录后同步。最多 256 条、正文总计 16 MiB,单条超过 2 MiB 不持久化;达到容量时淘汰最早保存的副本,主动退出、切换登录范围及业务写入失效时清理相关副本;认证不可用时保留本地副本和草稿。IndexedDB 缓存结构版本 2 移除旧保留期限索引,原行、控制代次和会话标识原样保留。首次使用新缓存库时,将已发布 v2 库中此前验证身份下的副本复制到新库,保留原响应、行身份与控制代次;离线迁移不删除源副本,不覆盖已存在的新库身份,失效或退出后不重新导入旧副本。主动退出同时清理新旧读取库。内存中的已加载视图继续复用。

页面明确显示离线缓存状态,未缓存的查询页、搜索、月份和案件详情需要联网,保存与完成待办不离线提交。恢复联网或点击重新连接后核验会话,失效内存读取并更新当前视图,保留滚动、选中案件和草稿。手机端在列表或页面顶部单指下拉、达到提示后松开,可主动核验会话并刷新当前视图;主动刷新也重新核对令牌未变的副本,旧副本保留供离线回退,迟到响应仍受代次保护。横向滑动、多指、输入、弹窗及未到顶部的滚动不触发刷新,编辑和保存期间不触发下拉刷新。同步提示等待当前可见读取完成后再结束。缓存仅保存已读取的查询页、案件全文及月份结果,搜索与分页继续由服务端执行;法定节假日按年保存在本机,联网时按 7 天新鲜度刷新,接口失败或离线时沿用已有年份;没有全库下载、离线写入或跨设备实时推送。浏览器存储不可用时回退到内存缓存;联网验证后尽力申请持久存储,实际保留仍取决于浏览器及用户是否清理应用数据。保存后失效持久副本,事务代次阻止其他标签页的迟到读取写回旧数据;保存回执即时显示成功,缓存落盘不阻塞反馈。persistent-cache.js 的数据库名后缀是响应格式版本,兼容的缓存结构升级使用 Dexie 版本迁移保留副本,不兼容响应格式变更时须升级名称并清理旧库。

首屏结束且当月日历加载成功后,预加载前后各三个月,切换月份后补齐周边范围。笔记保存后重新选中看板会按需更新待办、开庭与已展开的近期完成,勾选状态不阻挡刷新;待办仅保留行 ID 与版本均未改变的勾选。失效列表重读已浏览范围,续页入口同样检查写入代次,避免沿旧游标追加旧数据。提交完成待办时隔离旧续页响应,版本冲突后重新核对列表。近期完成折叠时随统计请求读取近 7 天与近 30 天的数量,展开后才按页读取记录。草稿在当前标签页保存基准版本和行身份,旧草稿不能覆盖服务器更新;主动退出成功时清理私有缓存与草稿,清理持久副本完成后跳转登录页;云端认证不可用时保留副本和草稿,提示登录后同步。网页 Service Worker 在页面加载时立即注册,联网恢复时重试注册;必需应用壳资源完整安装后才激活,可选图标下载失败不阻断离线安装。网页应用壳不设置到期时间,按版本优先读取缓存,仅在完整新版本激活后删除旧壳;首页查询参数不妨碍离线启动,修改壳资源时同步升级 sw.js 的缓存版本。私人 API 响应不进入 Service Worker 缓存。手机浏览器需先联网完成应用壳安装;浏览器或用户清理站点存储后需联网重建。安卓 APK 自带应用壳,首次无网启动也显示框架。查看私人数据仍需先联网登录并读取;没有已读取副本或副本被清理时需要联网。完整案件编辑及预览的成本随单案长度增长,网页整段保存受 1 MiB 请求体和 5,000 行限制,批量索引与审计参数按字节分块并在同一事务提交。

安卓应用

地址与离线壳

手机 App 使用同一套网页业务代码,完整公共框架随 APK 安装并长期保留,不依赖 HTTP 缓存或 Service Worker 安装。首次启动需填写服务器域名,只保存在本机设置里,APK 与仓库内都不含任何服务器地址;填错可在打不开时的「重新设置服务器地址」里修改。tools/pack-android-shell.mjs 将公共资源打包到构建输出,HTML 资源地址改为 __app__/ 下的相对路径;WebView 与遗留 Service Worker 的请求由 BundledShell 按本机填写的域名拦截,只提供本次构建清单中的公共文件,私人 API 继续访问原线上路径。地址填写一次后,已有 Cookie 和 IndexedDB 副本继续使用;原生页面不注册新 Service Worker,避免网页壳与 APK 资源混用。渲染进程崩溃(内存或驱动问题)时按 onRenderProcessGone 重建 WebView 并回到崩溃前的地址,应用不会随之退出。应用联网时会在后台向本仓库的 android-latest Release 查询最新 versionCode(不携带本机数据),发现新版本时弹框提供应用内下载:经系统 DownloadManager 下载到公共 Download 目录(通知栏显示进度),完成后通知点击或回到应用时拉起系统安装器;也可选择打开下载页面手动下载。顶栏的「检查更新」按钮可随时手动触发一次检查(已是最新或检查失败会提示)。浏览器打开网页时顶栏对应位置为「下载App」,指向 android-latest Release。离线或查询失败时自动检查静默跳过。App 回到前台或浏览器窗口重新获得焦点时静默核验一次会话(5 秒内合并重复触发,不打扰当前操作),工作空间有变化才刷新视图。框架更新随 APK 升级完成;进程重建保存并重新加载当前 URL 和哈希路由,不依赖 restoreState 恢复页面内容。站内跳转留在应用内,站外链接调用系统浏览器。返回键调用网页与右滑共用的层级导航:先关闭弹窗或退出编辑(保留当前标签页的草稿),案件详情返回打开它的案件列表、看板或日历,其他主视图返回看板;已经在首页看板时,第一次返回提示“再按一次返回退出”,2 秒内再次返回退出,超时需重新确认。返回上级、重新加载页面或应用转入后台会清除退出确认状态。Android 13 及以上接入系统返回回调,旧系统使用同一处理逻辑,不使用 WebView 网页历史作为返回层级。登录态沿用网页会话,与浏览器一致。

出包与签名

发新包时在 android/app/build.gradle 同步递增 versionCode。出包走 CI,两条工作流分离:Android quality check 在改动安卓代码的 PR 或手动触发时构建调试包并跑 JVM 单元测试,它是质量信号,不阻塞发布;Release Android APK 在 main 上签名并发布 android-latest Release 的 case-notes-release.apk,PR 不触发;发布正文带上 versionCode,供已安装应用后台检查更新。壳的路径、MIME 与放行规则由 BundledShellTest(Robolectric)覆盖,tests/android-shell.test.ts 覆盖打包资源图与 /__app__/ 路径;仓库与 APK 内都不含真实部署地址。原先在关闭全部网络的模拟器上核验冷启动、活动重建与合成 IndexedDB 副本的检查已移除:GitHub 托管运行器上客机在测试中途必定消失(模拟器进程无输出退出、5554 端口拒绝连接),换 GPU 后端与系统镜像都无法稳定,留着只会每周变红且没有可读的失败信息。

安卓应用 ID 已统一为 com.teamilkman.casenotes。从旧应用迁移时需要安装为新应用并重新登录,云端案件和日志继续保留;后续同包名版本可覆盖升级。Release 包用固定密钥签名以保证后续覆盖升级。密钥由 ANDROID_KEYSTORE_BASE64、ANDROID_STORE_PASSWORD、ANDROID_KEY_ALIAS、ANDROID_KEY_PASSWORD 四个 GitHub Secret 提供,本地副本存在 backups/(已被忽略,不进版本库,勿外泄)。本地无密钥时 assembleRelease 产出未签名包,仅 CI 可出可安装的 release 包。

CI 发布与凭证

发布统一走 GitHub Actions。main 推送或在 main 分支手动触发后执行检查、渲染部署配置、云端结构迁移、可选运行时 Secret 同步、Worker 部署、域名绑定与线上核验;PR 和其他分支的手动运行只检查。旧系统导入、parser v2 升级与 ai-log 资源改名迁移均已完成并退役,发布不再执行导入、索引升级或资源转移脚本;tools/rename-resources.ts --stage-config 仍用于生成不含路由的部署配置。结构迁移历史保留,已应用的迁移不会重复执行。失败可重试 CI。

用途 运行时/本地变量 GitHub Secret
网页登录 WEB_PASSWORD WEB_PASSWORD
Cloudflare 部署权限 CLOUDFLARE_API_TOKEN CLOUDFLARE_API_TOKEN
Cloudflare 账户 CLOUDFLARE_ACCOUNT_ID CLOUDFLARE_ACCOUNT_ID
部署地址与自定义域名 DEPLOYMENT_URL、DOMAIN DEPLOYMENT_URL、DOMAIN
区域与数据库标识 ZONE_ID、D1_DATABASE_ID ZONE_ID、D1_DATABASE_ID
原生资源告警收件人 RESOURCE_ALERT_EMAIL(仅 CI) RESOURCE_ALERT_EMAIL
自动防护运行时令牌 RESOURCE_GUARD_TOKEN RESOURCE_GUARD_TOKEN

需要更新 CI 凭证时,node tools/setup-ci-secrets.mjs 可将 .dev.vars 中对应值提交到 GitHub Secrets,不输出凭证;目标仓库默认 teamilkman/case-notes,可用 CI_REPO 覆盖。Cloudflare 账户管理凭证与日志应用令牌用途不同。部署地址与标识同样按 Secret 处理:CI 运行时把它们渲染进 wrangler.jsonc,输出日志中的取值会被 GitHub 掩码成 ***。运行时登录密码只在提供了 WEB_PASSWORD 时才重新同步,未提供时保留云端现有值。

CLOUDFLARE_API_TOKEN 还需部署区域的 Zone WAF Edit、Zone Settings Edit、账号 Account Analytics Read 和 Notifications Write 权限,用于边缘规则、HTTPS 强制及 Cloudflare 原生提醒的配置、查询预览和回读核验;缺少权限时 CI 明确失败,不将防护记为已启用。RESOURCE_GUARD_TOKEN 不需要 Worker 部署、通知发送或 D1 权限。CI 将既有账号、区域、域名标识分别写入 Worker 的 GUARD_ACCOUNT_ID、GUARD_ZONE_ID、GUARD_HOSTNAME Secret,不提交标识取值。部署时同步定时任务和原生提醒;线上核验识别自动冷却,暂停期间验证边缘拦截及网页正常访问,不为核验而解除冷却。

线上核验先检查默认地址和版本预览地址均已关闭,仅在自定义域名用网页密码换取一个 OAuth 令牌,再覆盖 HTTPS 强制与 HSTS 回读、OAuth 发现挑战与元数据、MCP 初始化说明与 OpenAPI 描述的同源一致性、工具发现与调用、登录/退出、未认证拒绝、网页数据库列表及出现续页时的游标读取;搜索限定事务,以小页长分别核验 REST 和 MCP 的只读分页,不向正式日志写测试记录。OAuth 授权、兑换、续期与撤销在隔离 Miniflare/D1 测试中核验。识别到每日 D1 额度错误后停止即时重试,接口返回明确错误和 UTC 重置时刻。以对应提交的 CI 结果判断是否已部署,不把本地构建成功当作上线成功。

数据保护与备份

真实日志、卷宗、凭证、本地数据库、备份和测试截图不提交 Git。日志正文按数据库接口读取;卷宗不上云。业务数据库不再保存旧系统导入原文、旧元数据、导入回执或迁移审计,当前日志的稳定身份、版本和正常操作审计继续保留;旧系统备份由用户在项目外维护。

npm run backup:local 将本地统一数据库导出为 backups/ 下的 SQL;它包含本地日志和鉴权记录,不包含云端数据。当前项目没有自动云端导出备份任务。合并后完整备份含鉴权摘要;D1 Time Travel 会同时回退日志与会话、OAuth 轮换和撤销状态,恢复后须清除会话与 OAuth 授权并重新登录授权。需要迁移或恢复时先明确源库、目标库与覆盖范围,按当前 schema 和解析规则核验,不能用本地备份代表云端现状。

贡献与许可

本项目为私人项目,未设置开源许可证,不接受外部贡献。改动直接在 main 分支提交,正式发布统一走 CI(见「CI 发布与凭证」),变更历史由 Git 与 CI 留存。

About

按行管理的中文工作日志:Cloudflare Worker + D1 + Vue 3;部署地址与标识只存在于 Secret,不写入仓库

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages