feat: allow wildcard web origins for local tunnel testing
This commit is contained in:
陈煜 committed
1 parent
2a650853ee
commit
e4f4ff42e1
9 files changed
+115
-70
No files matched your search
@@ -40,3 +40,5 @@ pnpm check:staged # git add 后，提交前检查本地凭证和禁止提交的
|
||||
设计见 [数据模型与结构](docs/architecture.md)，已验证范围与后续工作见 [首版验收](docs/acceptance.md)。生产需要 HTTPS、COOKIE_SECURE=true、WEB_ORIGIN 为准确站点地址；前端构建由反向代理托管并代理 /api。API 生产启动：在 `apps/api` 中执行 `node dist/main.js`。生产认证限速需迁移到共享存储，数据库用户需最小权限，部署与运行监控尚未配置。
|
||||
|
||||
备份下载为 ZIP：manifest、settings、currencies、accounts、assets、debts、history、links、rates 各一个 JSON 文件，包含隐藏项目及全部历史，不含密码或会话凭据。导入先上传并预览，再确认追加；旧 JSON 备份继续兼容。不限制项目、历史、关联或汇率条数；上传文件最大 512 MB，ZIP 解压总计最大 1 GB，用于保护服务器资源。
|
||||
|
||||
内网穿透临时测试：本地 `apps/api/.env` 可设置 `WEB_ORIGIN=*` 并重启 API，允许来自任意 HTTP/HTTPS 站点的浏览器写入请求，仍需登录身份并校验数据归属。缺失或无效 Origin 仍拒绝；`NODE_ENV=production` 禁止此通配符。测试结束后恢复准确的站点地址。
|
||||
@@ -1,4 +1,5 @@
|
||||
DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/worthpath"
|
||||
PORT=3100
|
||||
WEB_ORIGIN=http://localhost:5173
|
||||
COOKIE_SECURE=false
|
||||
DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/worthpath"
|
||||
PORT=3100
|
||||
# Local tunnel testing may use WEB_ORIGIN=*. Production requires an exact origin.
|
||||
WEB_ORIGIN=http://localhost:5173
|
||||
COOKIE_SECURE=false
|
||||
+19
-1
@@ -22,6 +22,20 @@ import { credentials } from './validation';
|
||||
export type UserRequest = Request & { userId: string; sessionId: string; revealed: boolean };
|
||||
const Public = () => SetMetadata('public', true);
|
||||
const digest = (s: string) => createHash('sha256').update(s).digest('hex');
|
||||
export function allowedOrigin(
|
||||
origin: string | undefined,
|
||||
configured: string | undefined,
|
||||
production = false,
|
||||
) {
|
||||
if (configured !== '*') return !!origin && origin === configured;
|
||||
if (production || !origin) return false;
|
||||
try {
|
||||
const url = new URL(origin);
|
||||
return ['http:', 'https:'].includes(url.protocol) && url.origin === origin;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
@Injectable()
|
||||
export class AuthService {
|
||||
private attempts = new Map<string, { count: number; until: number }>();
|
||||
@@ -87,7 +101,11 @@ export class AuthGuard implements CanActivate {
|
||||
const req = ctx.switchToHttp().getRequest<UserRequest>();
|
||||
if (
|
||||
!['GET', 'HEAD', 'OPTIONS'].includes(req.method) &&
|
||||
req.headers.origin !== process.env.WEB_ORIGIN
|
||||
!allowedOrigin(
|
||||
req.headers.origin,
|
||||
process.env.WEB_ORIGIN,
|
||||
process.env.NODE_ENV === 'production',
|
||||
)
|
||||
)
|
||||
throw new ForbiddenException('请求来源不受信任');
|
||||
if (this.reflector.get<boolean>('public', ctx.getHandler())) return true;
|
||||
|
||||
@@ -48,6 +48,8 @@ class AppModule {}
|
||||
async function bootstrap() {
|
||||
if (!process.env.DATABASE_URL || !process.env.WEB_ORIGIN)
|
||||
throw Error('Missing local environment configuration');
|
||||
if (process.env.NODE_ENV === 'production' && process.env.WEB_ORIGIN === '*')
|
||||
throw Error('Production requires an explicit web origin');
|
||||
if (process.env.NODE_ENV === 'production' && process.env.COOKIE_SECURE !== 'true')
|
||||
throw Error('Production requires secure cookies');
|
||||
const app = await NestFactory.create(AppModule, { logger: false, bodyParser: false });
|
||||
|
||||
@@ -6,6 +6,22 @@ import { positionInput, date, amount, businessDate, toBusinessDate } from '../sr
|
||||
import { validateBackup } from '../src/backup';
|
||||
import { RatesService } from '../src/rates';
|
||||
import { Database } from '../src/database';
|
||||
import { allowedOrigin } from '../src/auth';
|
||||
test('development wildcard accepts HTTP origins while exact and production checks stay strict', () => {
|
||||
assert.equal(allowedOrigin('https://tunnel.example', '*'), true);
|
||||
assert.equal(allowedOrigin('http://example.test:8080', '*'), true);
|
||||
for (const origin of [
|
||||
undefined,
|
||||
'null',
|
||||
'file://host',
|
||||
'https://example.test/path',
|
||||
'https://name:secret@example.test',
|
||||
])
|
||||
assert.equal(allowedOrigin(origin, '*'), false);
|
||||
assert.equal(allowedOrigin('https://tunnel.example', '*', true), false);
|
||||
assert.equal(allowedOrigin('https://tunnel.example', 'http://localhost:5173'), false);
|
||||
assert.equal(allowedOrigin('http://localhost:5173', 'http://localhost:5173'), true);
|
||||
});
|
||||
const rev = (amount: string, day: string) => ({
|
||||
id: randomUUID(),
|
||||
amount,
|
||||
|
||||
@@ -6,7 +6,7 @@ import { PrismaClient } from '@prisma/client';
|
||||
import { today } from '../src/validation';
|
||||
import { readBackupZip } from '../src/zip';
|
||||
const base = process.env.TEST_API_URL || 'http://127.0.0.1:3100/api',
|
||||
origin = process.env.WEB_ORIGIN!;
|
||||
origin = process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!;
|
||||
test('real MySQL: authentication, isolation, history, backup and atomic failures', async () => {
|
||||
const db = new PrismaClient(),
|
||||
created: { id: string; username: string }[] = [];
|
||||
@@ -53,10 +53,10 @@ test('real MySQL: authentication, isolation, history, backup and atomic failures
|
||||
'Content-Type': 'application/json',
|
||||
Origin: 'https://untrusted.invalid',
|
||||
},
|
||||
body: JSON.stringify({ baseCurrency: 'USD' }),
|
||||
body: JSON.stringify({ showSidebar: true }),
|
||||
})
|
||||
).status,
|
||||
403,
|
||||
process.env.WEB_ORIGIN === '*' ? 200 : 403,
|
||||
);
|
||||
const make = async (
|
||||
kind: string,
|
||||
|
||||
@@ -12,7 +12,7 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
|
||||
const res = await fetch(base + path, {
|
||||
method,
|
||||
headers: {
|
||||
Origin: process.env.WEB_ORIGIN!,
|
||||
Origin: process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!,
|
||||
Cookie: cookie,
|
||||
...(data ? { 'Content-Type': 'application/json' } : {}),
|
||||
},
|
||||
@@ -131,7 +131,11 @@ test('privacy, minute history, backup-gated clear and idle sessions remain user
|
||||
form.append('file', new Blob([content]), 'backup.zip');
|
||||
const res = await fetch(base + '/backup/upload', {
|
||||
method: 'POST',
|
||||
headers: { Origin: process.env.WEB_ORIGIN!, Cookie: cookie },
|
||||
headers: {
|
||||
Origin:
|
||||
process.env.WEB_ORIGIN === '*' ? 'http://localhost:5173' : process.env.WEB_ORIGIN!,
|
||||
Cookie: cookie,
|
||||
},
|
||||
body: form,
|
||||
});
|
||||
return { status: res.status, data: await res.json() };
|
||||
|
||||
+35
-33
@@ -1,33 +1,35 @@
|
||||
# 首版验收（2026-10-01，Asia/Hong_Kong）
|
||||
|
||||
代码位于 E:\WorthPath，远程 origin 为用户指定 GitHub 仓库，分支 main。初始目录和仓库为空；没有覆盖已有项目文件。已有其他程序占用 API 默认端口，因此本项目使用 3100，前端使用 5173。
|
||||
|
||||
已验证：
|
||||
|
||||
- 后端和前端类型检查、生产构建通过。
|
||||
- 13 项单元测试通过：Decimal 精度、负债符号、缺失汇率、历史更正、汇率/余额归因、大额金额、输入和备份校验、固定公共汇率请求与失败保护。
|
||||
- 真实 MySQL 集成测试通过：注册、密码哈希、登录退出、会话失效、同源写入限制、双用户资源与历史隔离、客户端 userId 拒绝、信用卡负债、债务关联不重复求和、余额变化、同日多次更新、更正、还款金额和负债类型校验、归档金额编辑限制。
|
||||
- 备份不含认证数据；预览验证、明确确认、恢复后 ID 重建与关联保留、重复导入拒绝、已导入项目修改后重复导入仍拒绝、两请求并发导入仅一次成功，失败没有留下部分项目。
|
||||
- 四次可追踪迁移已应用，数据库结构处于最新状态，未运行 reset/db push。
|
||||
- 浏览器验收：注册、空状态、账户创建、同日连续余额更新、外币资产、独立债务与关联、历史汇率、总览趋势及变化归因、手机退出登录。编辑过程中撤销临时会话后，服务端拒绝保存，界面清除旧弹窗和草稿；重新登录后未恢复旧草稿，数据库原名称不变。
|
||||
- 浏览器真实下载版本化备份，选择重复文件显示拒绝说明；另一临时用户中预览并明确确认恢复成功。
|
||||
- 公共汇率实际请求成功并保存日期和十进制汇率，原币未改变。
|
||||
- 390×844 手机、742px 中间视口、1280×800 桌面布局检查；手机和桌面未出现页面横向溢出，宽历史表格单独滚动。
|
||||
- 临时测试用户及其项目已清理，网站没有预置演示资产。验收截图使用明确标为“验收临时”的项目。验收期间出现的非测试用户数据已保留，清理仅针对明确创建的临时用户。
|
||||
- 每次提交前扫描本地环境中的凭证与连接元数据，环境文件、数据库文件、依赖和构建产物未纳入提交。
|
||||
|
||||
首版限制：每次更新保留独立绝对余额记录，同日多次更新与备份恢复顺序已验证；更正替换该日记录，暂未另存更正操作的审计副本。归档项目仍计入财富，需要结清时先更新为零。首版支持十种常见币种；汇率为参考价，首次使用不会自动抓取全量历史。历史汇率缺失时该日期标记不完整，保留原币并提示换算不完整。备份仅追加，不能直接覆盖恢复到已有空间。列表暂不分页；适合个人规模数据。
|
||||
|
||||
尚未验证或未交付：连续多日无人值守运行、生产 HTTPS 与反向代理部署、多实例共享认证限速、运行告警、真实手机浏览器与触摸设备矩阵、大规模数据性能、密码找回/变更、家庭共享。开发服务在本机可启动，当前交付不等同于生产上线。
|
||||
|
||||
下一步建议：基于真实少量资产试用，完善筛选和分页、键盘焦点管理及历史更正审计；随后建立最小权限数据库账号、HTTPS 部署和共享限速，进行实际设备验收。家庭共享与报表作为后续独立模块。
|
||||
|
||||
## 功能更新验收
|
||||
|
||||
- 临时账号集成测试验证隐藏账户默认不进入列表、详情及总额；密码错误拒绝，另一会话和其他用户不继承查看权限，授权过期重新排除。
|
||||
- 分钟业务时间和变更额、v2 隐藏状态备份恢复及 v1 旧格式兼容通过。
|
||||
- 未下载备份、错误确认文字、伪造 userId、备份后数据变化均拒绝清空；成功仅删除当前临时用户数据，其他用户保留，当前用户仍可登录。
|
||||
- 用户侧栏和定时退出设置持久化，非法分钟数拒绝；过期会话及活动续期请求均被拒绝。
|
||||
- 浏览器已验证隐藏账户、密码解锁、分钟展示、侧栏隐藏后的手机导航、真实备份下载及清空下一步、一分钟无操作退出；未对实际用户执行清空操作。
|
||||
- ZIP 分文件内容及摘要校验、损坏/缺失/未知文件拒绝、真实上传与当前会话令牌隔离、确认后恢复已通过。超过 1000 个项目、单项目 10000 条历史、总计 20000 条历史的校验通过。未做 512 MB 边界和超大规模恢复压力测试。
|
||||
- 手动汇率写入 API 返回 404，界面入口已移除；已有历史汇率未删除。
|
||||
# 首版验收（2026-10-01，Asia/Hong_Kong）
|
||||
|
||||
代码位于 E:\WorthPath，远程 origin 为用户指定 GitHub 仓库，分支 main。初始目录和仓库为空；没有覆盖已有项目文件。已有其他程序占用 API 默认端口，因此本项目使用 3100，前端使用 5173。
|
||||
|
||||
已验证：
|
||||
|
||||
- 后端和前端类型检查、生产构建通过。
|
||||
- 14 项单元测试通过：Decimal 精度、负债符号、缺失汇率、历史更正、汇率/余额归因、大额金额、输入和备份校验、固定公共汇率请求与失败保护。
|
||||
- 真实 MySQL 集成测试通过：注册、密码哈希、登录退出、会话失效、同源写入限制、双用户资源与历史隔离、客户端 userId 拒绝、信用卡负债、债务关联不重复求和、余额变化、同日多次更新、更正、还款金额和负债类型校验、归档金额编辑限制。
|
||||
- 备份不含认证数据；预览验证、明确确认、恢复后 ID 重建与关联保留、重复导入拒绝、已导入项目修改后重复导入仍拒绝、两请求并发导入仅一次成功，失败没有留下部分项目。
|
||||
- 四次可追踪迁移已应用，数据库结构处于最新状态，未运行 reset/db push。
|
||||
- 浏览器验收：注册、空状态、账户创建、同日连续余额更新、外币资产、独立债务与关联、历史汇率、总览趋势及变化归因、手机退出登录。编辑过程中撤销临时会话后，服务端拒绝保存，界面清除旧弹窗和草稿；重新登录后未恢复旧草稿，数据库原名称不变。
|
||||
- 浏览器真实下载版本化备份，选择重复文件显示拒绝说明；另一临时用户中预览并明确确认恢复成功。
|
||||
- 公共汇率实际请求成功并保存日期和十进制汇率，原币未改变。
|
||||
- 390×844 手机、742px 中间视口、1280×800 桌面布局检查；手机和桌面未出现页面横向溢出，宽历史表格单独滚动。
|
||||
- 临时测试用户及其项目已清理，网站没有预置演示资产。验收截图使用明确标为“验收临时”的项目。验收期间出现的非测试用户数据已保留，清理仅针对明确创建的临时用户。
|
||||
- 每次提交前扫描本地环境中的凭证与连接元数据，环境文件、数据库文件、依赖和构建产物未纳入提交。
|
||||
|
||||
首版限制：每次更新保留独立绝对余额记录，同日多次更新与备份恢复顺序已验证；更正替换该日记录，暂未另存更正操作的审计副本。归档项目仍计入财富，需要结清时先更新为零。首版支持十种常见币种；汇率为参考价，首次使用不会自动抓取全量历史。历史汇率缺失时该日期标记不完整，保留原币并提示换算不完整。备份仅追加，不能直接覆盖恢复到已有空间。列表暂不分页；适合个人规模数据。
|
||||
|
||||
尚未验证或未交付：连续多日无人值守运行、生产 HTTPS 与反向代理部署、多实例共享认证限速、运行告警、真实手机浏览器与触摸设备矩阵、大规模数据性能、密码找回/变更、家庭共享。开发服务在本机可启动，当前交付不等同于生产上线。
|
||||
|
||||
下一步建议：基于真实少量资产试用，完善筛选和分页、键盘焦点管理及历史更正审计；随后建立最小权限数据库账号、HTTPS 部署和共享限速，进行实际设备验收。家庭共享与报表作为后续独立模块。
|
||||
|
||||
## 功能更新验收
|
||||
|
||||
- 临时账号集成测试验证隐藏账户默认不进入列表、详情及总额；密码错误拒绝，另一会话和其他用户不继承查看权限，授权过期重新排除。
|
||||
- 分钟业务时间和变更额、v2 隐藏状态备份恢复及 v1 旧格式兼容通过。
|
||||
- 未下载备份、错误确认文字、伪造 userId、备份后数据变化均拒绝清空；成功仅删除当前临时用户数据，其他用户保留，当前用户仍可登录。
|
||||
- 用户侧栏和定时退出设置持久化，非法分钟数拒绝；过期会话及活动续期请求均被拒绝。
|
||||
- 浏览器已验证隐藏账户、密码解锁、分钟展示、侧栏隐藏后的手机导航、真实备份下载及清空下一步、一分钟无操作退出；未对实际用户执行清空操作。
|
||||
- ZIP 分文件内容及摘要校验、损坏/缺失/未知文件拒绝、真实上传与当前会话令牌隔离、确认后恢复已通过。超过 1000 个项目、单项目 10000 条历史、总计 20000 条历史的校验通过。未做 512 MB 边界和超大规模恢复压力测试。
|
||||
- 手动汇率写入 API 返回 404，界面入口已移除；已有历史汇率未删除。
|
||||
|
||||
内网穿透测试更新：支持本地 `WEB_ORIGIN=*`；HTTP/HTTPS 来源探测均通过来源校验，缺失或 null 来源拒绝。精确来源模式及生产禁止通配符的单元校验通过。此轮 14 项单元测试、2 项数据库集成测试、类型检查和构建通过；未执行外网穿透链路端到端验收。
|
||||
+27
-27
@@ -1,27 +1,27 @@
|
||||
# WorthPath 首版设计
|
||||
|
||||
NestJS API、React/Vite 前端和 MySQL；同源 /api，开发环境由 Vite 代理。
|
||||
|
||||
用户拥有持有项目 Position（account/asset/debt）、汇率及登录会话。账户独立保留 asset/liability 属性；信用卡与贷款固定为负债。债务可链接到多个同用户项目，链接不参与求和。每个金额均为非负原币余额，负债按 side 减去。
|
||||
|
||||
Revision 保存按业务日期生效的绝对金额，每次金额更新新增记录，sequence 在数据库中单调分配以确定同日顺序；按业务日期和顺序读取，日趋势使用当日最后余额。错误记录须明确调用更正接口。历史前值和变化额按业务日期重新计算，避免更正早期记录后余额与趋势不一致。未来日期不允许。初始余额也写入历史。金额 DECIMAL(24,8)，汇率 DECIMAL(24,12)，API 使用十进制字符串；计算使用 Decimal，前端仅图形坐标使用 Number。
|
||||
|
||||
趋势按日期重放金额和当时可用汇率。汇率导致的变化和余额导致的变化分别归因；没有可用汇率时总额标记不完整，绝不默认为 1。归档项目仍参与统计，归档仅停止编辑，避免归档导致财富凭空消失。
|
||||
|
||||
认证采用 bcrypt 密码哈希和 HttpOnly 随机会话 Cookie；数据库只保存会话令牌 SHA-256 摘要。所有资源查询由会话用户范围限定。写入要求同源 Origin，登录限速；生产必须 HTTPS 并启用安全 Cookie。
|
||||
|
||||
备份采用 version=3 ZIP（多个可读 JSON 文件），包含项目、历史、关系、币种、本位币、汇率和导入来源，不包含用户认证数据。首版导入只追加完整的新项目并重映射 ID；项目 ID 和 importedFromId 识别重复，用户 + importedFromId 有唯一索引，项目修改后仍拒绝原备份重复导入；不同 ID 的同名项目允许共存。汇率冲突拒绝；已有本位币不自动更改，空空间恢复备份本位币。完整验证后以 Serializable 事务写入，不修改已有项目。总览和导出使用数据库事务读取一致的数据视图。
|
||||
|
||||
页面：注册登录、总览、账户/资产/债务列表及详情与编辑、历史、本位币/汇率设置、备份与导入。空数据无演示金额。
|
||||
|
||||
数据库使用 Prisma 可追踪 SQL 迁移，部署仅 migrate deploy，禁止 db push/reset。扩展家庭共享时可以引入空间和成员权限，现阶段严格按用户隔离。
|
||||
|
||||
代码边界：`auth.ts` 负责身份与 Cookie；`portfolio.ts` 负责持有项目、历史和关系；`calculation.ts` 是无数据库依赖的十进制计算；`rates.ts` 负责公共汇率获取、失败状态和个人设置；`backup.ts` 负责格式验证与原子恢复；`database.ts` 管理数据库生命周期；`validation.ts` 集中定义输入约束。前端 `api.ts` 定义服务访问及数据类型，`App.tsx` 组合各功能流程，共用金额编辑和历史展示，CSS 定义桌面侧栏及手机底栏布局。
|
||||
|
||||
时间：业务时间按北京时间精确到分钟，数据库 DATETIME(3) 保存对应 UTC 时间，显示按 Asia/Hong_Kong；旧日期记录迁移为原业务日的 00:00，不推测实际操作时刻。汇率仍使用 DATE。历史按时间及 sequence 排序，趋势按业务日汇总当日最后余额。创建和更新时间使用 UTC 时间戳。汇率定时检查在 API 进程内执行；更新尝试状态和认证限速当前在内存中，重启后重新初始化。多实例部署时需改为共享限速和独立调度任务。
|
||||
|
||||
隐私及设置：Position.hidden 对账户、资产和债务统一生效。默认列表、详情、历史及总览均在服务端过滤隐藏项目，净资产按显示范围计算。登录密码核验成功后仅当前 Session 获得 5 分钟查看权限，到期前端清除敏感视图，服务端每次请求检查授权期限；手动锁定和退出可立即撤销。备份始终包含该用户全部项目（包括隐藏项目）。showSidebar 和 idleMinutes 为用户设置，默认显示侧栏、30 分钟无操作退出；0 关闭定时退出，最大 1440 分钟。真实交互触发节流的活动请求，后台加载不延长会话；服务端检查 lastActivity，前端计时器退出登录并清除页面数据，保留浏览器标签页。侧栏隐藏后顶部导航保留设置入口。
|
||||
|
||||
安全清空：先通过认证下载备份，在当前 Session 记录备份内容摘要及 10 分钟有效期。下一步必须输入精确短语“确定清空”。Serializable 事务中重新校验当前数据摘要；变化后必须重新下载。清空仅删除当前用户的项目（级联历史/关联）及汇率，保留登录身份和个人设置，撤销该用户所有会话的查看及备份确认状态。汇率请求返回后再核对当前币种，避免清空期间正在执行的网络请求重建旧汇率。
|
||||
|
||||
备份现使用 version=3 ZIP：manifest.json 保存格式版本、导出时间及各数据文件 SHA-256；settings/currencies/accounts/assets/debts/history/links/rates 分别保存完整数据。业务时间与 hidden 保留。旧版 v1/v2 JSON 文件仍可上传，v1 缺少 hidden 时视为未隐藏。恢复仍只追加，按业务时间和 sequence 重建顺序；空空间恢复本位币和界面/退出偏好。取消项目数、历史数、关联数和汇率数上限；文件上传最多 512 MB，ZIP 解压总计 1 GB，拒绝未知/重复路径、缺失文件、加密 ZIP、摘要不符和格式错误，不向文件系统解压。预览文件暂存在系统临时目录，15 分钟有效，确认导入令牌绑定当前用户及会话，导入/失败/过期后清理。数据库事务最长 5 分钟以容纳较大恢复。手动汇率入口和写入 API 已删除，既有历史汇率保留。
|
||||
# WorthPath 首版设计
|
||||
|
||||
NestJS API、React/Vite 前端和 MySQL；同源 /api，开发环境由 Vite 代理。
|
||||
|
||||
用户拥有持有项目 Position（account/asset/debt）、汇率及登录会话。账户独立保留 asset/liability 属性；信用卡与贷款固定为负债。债务可链接到多个同用户项目，链接不参与求和。每个金额均为非负原币余额，负债按 side 减去。
|
||||
|
||||
Revision 保存按业务日期生效的绝对金额，每次金额更新新增记录，sequence 在数据库中单调分配以确定同日顺序；按业务日期和顺序读取，日趋势使用当日最后余额。错误记录须明确调用更正接口。历史前值和变化额按业务日期重新计算，避免更正早期记录后余额与趋势不一致。未来日期不允许。初始余额也写入历史。金额 DECIMAL(24,8)，汇率 DECIMAL(24,12)，API 使用十进制字符串；计算使用 Decimal，前端仅图形坐标使用 Number。
|
||||
|
||||
趋势按日期重放金额和当时可用汇率。汇率导致的变化和余额导致的变化分别归因；没有可用汇率时总额标记不完整，绝不默认为 1。归档项目仍参与统计，归档仅停止编辑，避免归档导致财富凭空消失。
|
||||
|
||||
认证采用 bcrypt 密码哈希和 HttpOnly 随机会话 Cookie；数据库只保存会话令牌 SHA-256 摘要。所有资源查询由会话用户范围限定。写入默认要求准确的 WEB_ORIGIN；本地穿透测试允许设置 `WEB_ORIGIN=*` 接受任意合法 HTTP/HTTPS 来源（仍拒绝缺失来源），生产模式禁止通配符。登录限速；生产必须 HTTPS 并启用安全 Cookie。
|
||||
|
||||
备份采用 version=3 ZIP（多个可读 JSON 文件），包含项目、历史、关系、币种、本位币、汇率和导入来源，不包含用户认证数据。首版导入只追加完整的新项目并重映射 ID；项目 ID 和 importedFromId 识别重复，用户 + importedFromId 有唯一索引，项目修改后仍拒绝原备份重复导入；不同 ID 的同名项目允许共存。汇率冲突拒绝；已有本位币不自动更改，空空间恢复备份本位币。完整验证后以 Serializable 事务写入，不修改已有项目。总览和导出使用数据库事务读取一致的数据视图。
|
||||
|
||||
页面：注册登录、总览、账户/资产/债务列表及详情与编辑、历史、本位币/汇率设置、备份与导入。空数据无演示金额。
|
||||
|
||||
数据库使用 Prisma 可追踪 SQL 迁移，部署仅 migrate deploy，禁止 db push/reset。扩展家庭共享时可以引入空间和成员权限，现阶段严格按用户隔离。
|
||||
|
||||
代码边界：`auth.ts` 负责身份与 Cookie；`portfolio.ts` 负责持有项目、历史和关系；`calculation.ts` 是无数据库依赖的十进制计算；`rates.ts` 负责公共汇率获取、失败状态和个人设置；`backup.ts` 负责格式验证与原子恢复；`database.ts` 管理数据库生命周期；`validation.ts` 集中定义输入约束。前端 `api.ts` 定义服务访问及数据类型，`App.tsx` 组合各功能流程，共用金额编辑和历史展示，CSS 定义桌面侧栏及手机底栏布局。
|
||||
|
||||
时间：业务时间按北京时间精确到分钟，数据库 DATETIME(3) 保存对应 UTC 时间，显示按 Asia/Hong_Kong；旧日期记录迁移为原业务日的 00:00，不推测实际操作时刻。汇率仍使用 DATE。历史按时间及 sequence 排序，趋势按业务日汇总当日最后余额。创建和更新时间使用 UTC 时间戳。汇率定时检查在 API 进程内执行；更新尝试状态和认证限速当前在内存中，重启后重新初始化。多实例部署时需改为共享限速和独立调度任务。
|
||||
|
||||
隐私及设置：Position.hidden 对账户、资产和债务统一生效。默认列表、详情、历史及总览均在服务端过滤隐藏项目，净资产按显示范围计算。登录密码核验成功后仅当前 Session 获得 5 分钟查看权限，到期前端清除敏感视图，服务端每次请求检查授权期限；手动锁定和退出可立即撤销。备份始终包含该用户全部项目（包括隐藏项目）。showSidebar 和 idleMinutes 为用户设置，默认显示侧栏、30 分钟无操作退出；0 关闭定时退出，最大 1440 分钟。真实交互触发节流的活动请求，后台加载不延长会话；服务端检查 lastActivity，前端计时器退出登录并清除页面数据，保留浏览器标签页。侧栏隐藏后顶部导航保留设置入口。
|
||||
|
||||
安全清空：先通过认证下载备份，在当前 Session 记录备份内容摘要及 10 分钟有效期。下一步必须输入精确短语“确定清空”。Serializable 事务中重新校验当前数据摘要；变化后必须重新下载。清空仅删除当前用户的项目（级联历史/关联）及汇率，保留登录身份和个人设置，撤销该用户所有会话的查看及备份确认状态。汇率请求返回后再核对当前币种，避免清空期间正在执行的网络请求重建旧汇率。
|
||||
|
||||
备份现使用 version=3 ZIP：manifest.json 保存格式版本、导出时间及各数据文件 SHA-256；settings/currencies/accounts/assets/debts/history/links/rates 分别保存完整数据。业务时间与 hidden 保留。旧版 v1/v2 JSON 文件仍可上传，v1 缺少 hidden 时视为未隐藏。恢复仍只追加，按业务时间和 sequence 重建顺序；空空间恢复本位币和界面/退出偏好。取消项目数、历史数、关联数和汇率数上限；文件上传最多 512 MB，ZIP 解压总计 1 GB，拒绝未知/重复路径、缺失文件、加密 ZIP、摘要不符和格式错误，不向文件系统解压。预览文件暂存在系统临时目录，15 分钟有效，确认导入令牌绑定当前用户及会话，导入/失败/过期后清理。数据库事务最长 5 分钟以容纳较大恢复。手动汇率入口和写入 API 已删除，既有历史汇率保留。
|
||||
Reference in new issue
Block a user