财务小助手架构剖析

项目已经完成并公网部署。这一课借助架构图，把路由、API、权限、数据库与公网接入的机制和设计串起来，理解已经搭建的系统如何工作。

本课怎么学

先看整体架构，再按五个知识点复盘。每节都包含概念、生活实例、机制与设计，以及相应的理解验证。API 与数据库安排实际操作，路由用例子讲解，权限用分类与矩阵说明，公网部分串起访问链路。

学习准备：已上线的财务助手地址、可用的测试账号或测试 Token、项目接口文档，以及可用于教学的数据库副本。正文采用一套统一的教学地址和数据结构说明机制；操作自己的系统时，接口和字段从已有文档中选择。

架构总览：从浏览器或 Agent 到数据库

个人财务助手系统架构图 v1.0：Human 与 Agent 双入口、FastAPI、IAM、业务模块与数据层

个人财务助手系统架构图 v1.0，2026-10-13，用户提供。点击可查看大图。原图包含“当前开发”与“生产待补”的标记；本课结合已经部署的项目讲解公网访问机制。

图中 Human 和 Agent 是两种使用主体，Web UI 与 API / CLI 是相应入口。请求进入应用后，经过身份与权限判断，再由已有业务能力处理，最终读写数据。本图的 IAM 位于 FastAPI 应用内部，是逻辑分工中的一层。

本课知识点	图上位置	复盘时要弄明白的问题	学习方式
路由	统一入口、FastAPI 页面/API 路由	一个请求怎样找到负责处理它的函数？	举例与代码对照
API 调用	Human REST API、Agent API / CLI	调用双方怎样约定输入输出？	手动调用与观察
权限设计	IAM、空间与成员、后台权限	怎样设计谁能对哪些数据做什么？	分类与权限矩阵
数据库连接与查阅	数据库、数据访问层	应用怎样连接数据库，表怎样保存和关联数据？	连接、看表与 SQL 查询
公网访问链路	域名、HTTPS、反向代理入口	输入公网地址后，请求怎样到达应用？	链路图解与浏览器查看

贯穿案例：在家庭账本中查询一笔“午餐 36 元”。先分别理解五个部分，最后把它们连成一次完整请求。

知识点一：路由——请求如何找到处理函数

概念与生活实例

路由是把请求分配给相应处理程序的规则。像办事大厅：同一个大厅里，查询窗口与办理窗口各有职责；请求带着业务地址和操作类型，由系统分配到对应函数。

在 Web 应用中，通常由 HTTP 方法和 URL 路径共同确定处理入口。GET 常用于读取，POST 常用于创建或提交处理任务；具体行为由接口约定。

请求	处理入口	含义
`GET /api/transactions`	`list_transactions`	查询交易列表
`GET /api/transactions/101`	`get_transaction`	查询 ID 为 101 的交易
`POST /api/transactions`	`create_transaction`	提交一笔新交易
`GET /api/reports/monthly`	`monthly_report`	查询月度报告

同一个 /api/transactions 路径，可以因为方法不同而匹配到不同函数。?category=餐饮 是查询参数，传给已匹配的函数，用于进一步筛选结果。

看一段最小路由代码

from fastapi import FastAPI

app = FastAPI()

@app.get("/api/transactions/{transaction_id}")
def get_transaction(transaction_id: int):
    return {"id": transaction_id, "description": "午餐"}

发送 GET /api/transactions/101 时，FastAPI 匹配这条规则，把路径中的 101 作为 transaction_id 传入函数，再把返回的字典编码为 JSON 响应。代码中 : int 同时声明参数类型，并参与输入校验。

怎么设计路由

先按资源组织路径，如 /ledgers、/transactions，再用方法表达读取、创建等操作；单条资源带 ID。按模块设置统一前缀，便于理解和维护，例如 /api/transactions 与 /api/reports。

图中还有另一种“分发”：Nginx 根据域名和路径将请求转发到后端应用；请求到达 FastAPI 后，应用路由再匹配函数。前者确定交给哪个服务，后者确定交给哪个处理入口。

验证理解

给出 GET /api/transactions/101、GET /api/transactions?category=餐饮、POST /api/transactions，分别说出它们进入哪个处理函数，以及 ID、分类条件、新交易字段各从哪里传入。

查看参考解释

第一条匹配单条查询函数，101 来自路径；第二条匹配列表查询函数，分类来自查询参数；第三条匹配创建函数，新交易字段通常来自 JSON 请求体。浏览器或客户端把请求送到应用，应用再按方法和路径匹配入口。

知识点二：API 调用——双方怎样约定输入输出

概念与生活实例

API 是程序向外提供能力的接口。像提交一张业务申请：要明确交给哪个窗口、办什么事、填哪些字段，以及会收到怎样的回执。接口设计就是把这些约定写清楚，使网页、CLI 和 Agent 都能据此调用。

一个 HTTP API 请求主要包括以下部分：

部分	教学示例	作用
服务地址	`https://finance.example.com`	找到目标服务
方法与路径	`GET /api/transactions`	指定要执行的操作
查询参数	`ledger_id=10&category=餐饮`	传递筛选条件
Header	`Authorization: Bearer <测试凭证>`	携带认证等请求信息
Body	新交易的日期、金额、分类	传递结构化业务数据

响应包括状态码、Header 和响应体。状态码说明处理结果的大类，JSON 中的字段说明具体结果。常见示例：200 查询成功、201 创建成功、401 需要有效认证、403 操作未获授权、422 输入未满足接口模型要求；实际项目也会按自己的接口规范返回错误。

接口设计要写清哪些约定

以“新增交易”为例，至少说明：账本 ID、日期、金额和币种的类型及必填性，金额单位，是否允许空分类，成功后返回的 ID 与状态，以及输入错误的返回格式。列表接口还要约定筛选条件、分页方式和返回结构。

下面是一套教学约定：用整数“分”表示金额，amount_cents=3600 表示 36 元。这样调用者与服务端对单位有同一个理解。

{
  "ledger_id": 10,
  "date": "2026-10-15",
  "amount_cents": 3600,
  "currency": "CNY",
  "category": "餐饮",
  "description": "午餐"
}

调用时，客户端将这些字段编码为 JSON；服务端解析请求体，按接口模型检查类型和必填项，将参数交给已有处理逻辑；最后把结果编码为响应。网页和 Agent 都可以按这份约定调用。

实操：用已有接口看清请求与响应

优先使用项目的 Swagger UI：FastAPI 默认文档地址是 /docs，页面可直接填写参数并发送请求。也可以把项目的 OpenAPI 文档导入已有的 Postman / Apipost。

打开已部署项目的接口文档，选择交易列表的 GET 接口，填写已有账本 ID 与测试凭证。
点击 Try it out，填写参数，再点击 Execute。查看 Request URL、请求头、状态码和 Response body，指出哪些内容由自己填写，哪些由服务端返回。
增加一个分类或日期条件，再执行一次。对照请求 URL 与返回记录，解释筛选条件如何传递。
选择项目已有的创建交易接口，在测试账本提交“午餐 36 元”。按文档填写真实字段，观察请求体、返回 ID 和状态。
把一个必填数字字段改成无法转换的文本，观察错误响应，并找到它指出的字段。由此理解接口模型如何约束输入。

当项目只提供网页登录会话时，使用它实际支持的认证方式；在文档页面中保持登录，或使用课程前面已配置的 Agent 测试 Token。请求中的 Cookie 与 Token 都是认证材料，不同入口可以使用不同方式。

验证理解

能够解释这次调用的“目标地址、操作、输入位置、输入约定、输出结果”；能够根据错误信息定位是参数类型、认证还是授权问题。新增记录只是观察输入如何变成响应的案例。

思考：网页已经可以新增交易，为什么还要手动调用 API？

手动调用会展开页面背后隐藏的请求结构，便于理解字段、方法和响应的约定。网页、CLI、Agent 可以分别作为客户端，遵循接口约定访问服务。

知识点三：权限设计——谁能对哪些数据做什么

概念与生活实例

公司里有员工身份、岗位职责和工作范围：同一个人在苏州办公室负责财务，在另一个项目组可能只有查阅权限。系统也需要同时描述调用者、允许的操作和数据范围。

认证确认调用者是谁，例如登录后识别用户，或者验证 Token 所代表的主体。授权根据身份、操作和资源，判断请求是否可以执行。

先给权限分类

分类	回答的问题	财务助手示例
功能／操作权限	能做什么？	读取交易、新增、编辑、审核、导出
数据权限	能操作哪些数据？	个人空间、家庭空间、指定账本
管理权限	能配置什么？	邀请成员、分配角色、管理 Agent 授权

常用的组织方式是 RBAC，即按角色组织权限：把一组操作赋给“查看者”“记账员”等角色，再把角色赋给相应空间中的成员。Role 组织职责，Space / Ledger 限定资源范围。Token 的 Scope 可进一步限制某次调用授权，如只允许 transactions:read。

一张设计用权限矩阵

下面是供讲解的角色设计。每个角色的资源范围都需要单独指定。

角色	查看交易	新增交易	编辑交易	审核交易	管理成员	数据范围
查看者	✓	—	—	—	—	已授权账本
记账员	✓	✓	自己创建的交易	—	—	已授权账本
审核员	✓	—	—	✓	—	指定空间的账本
空间管理员	✓	✓	✓	✓	✓	所管理的空间

Agent 可以按职责获得查看者或记账员等授权，同时用 Scope 缩小可调用操作。例如，月度分析 Agent 具有家庭账本读取权限；它关联的账号即使能够记账，这枚只读 Token 也只允许读取。

平台管理员负责全局账号或配置时，其管理权限也应单独定义；是否允许读取各空间财务数据，是需要明确决定的一条授权规则。

权限如何组织与执行

用户／Agent → 空间成员关系 → 角色 → 允许的操作
                        ＋ 账本归属与资源范围
                        ＋ 本次 Token 的 Scope（使用 Token 时）
                        → 本次请求是否允许

一个人在家庭空间是管理员，在公司空间是查看者，适合把角色记录在“主体与空间的成员关系”上。这样同一个主体可以在不同空间承担不同职责。

以“编辑交易”为例，应用需要取得调用主体、交易所属空间与账本、成员角色、允许的操作，并按设计检查是否只允许编辑自己创建的记录。服务端在执行操作前完成判断，列表和统计查询也要限制到授权的数据范围。前端据此展示按钮，后端负责执行规则。图中的 IAM 就承接这些认证与授权判断。

验证理解：根据矩阵推演

同一个人在家庭空间是管理员，在公司空间是查看者，能否修改公司交易？
记账员能否编辑另一位成员创建的交易？需要哪个字段参与判断？
账号能记账，但这次使用的 Token 只有读取 Scope，能否通过它新增交易？
月度分析 Agent 应获得哪些操作和数据范围？

查看参考解释

1. 公司空间的查看者角色不允许修改。2. 按本例矩阵，只能编辑自己创建的记录，需要交易的创建者 ID 与当前主体 ID。3. 只读 Token 不允许新增。4. 为其指定需要分析的家庭账本，并授予交易读取及确实需要的报告读取操作。每个判断都同时考虑操作与资源范围。

知识点四：数据库连接与查阅——应用怎样取得数据

概念与生活实例

数据库像按规则组织的电子账簿：每张表保存一类记录，每列是一个字段，每行是一条记录。连接是程序打开这套账簿的通道，SQL 是向数据库表达查询和修改意图的语言。

图中 SQLite 保存为数据库文件，应用通过文件路径打开连接。PostgreSQL 作为数据库服务运行，连接通常包含主机、端口、数据库名和认证信息。两者都可以执行查询，但连接方式不同。

表与关联怎么设计

表	示例字段	设计含义
`spaces`	`id`, `name`	每个空间有唯一 ID
`ledgers`	`id`, `space_id`, `name`	通过 `space_id` 表示账本属于哪个空间
`transactions`	`id`, `ledger_id`, `date`, `amount_cents`, `category`, `description`	通过 `ledger_id` 表示交易属于哪个账本

主键标识一条记录，外键表达关联。交易保存 ledger_id，查询时再关联账本；账本改名后，交易仍指向同一本账。金额字段明确以分存储，时间字段明确日期或时间戳的口径，才能让接口与查询采用一致含义。

图中的 SQLAlchemy / Repository 组织应用的数据访问；它们最终仍通过数据库连接完成读写。Alembic 用于管理表结构的版本变化。本节聚焦连接、表与查询，先把这条数据路径看清。

实操 A：打开数据库，直接看表

下载本课样例数据库 · 下载查询练习 SQL · 下载可运行 Notebook

用 DB Browser for SQLite 打开本课样例，或打开已部署项目的教学数据库副本。SQLite 数据库在服务器上时，取得一致性备份再在本地查看；课程查询在副本上进行。

选择 Open Database 打开数据库文件，在 Database Structure 查看表、字段、主键与外键。
在 Browse Data 切换账本表和交易表。根据某笔交易的 ledger_id，找到对应账本，再找到空间。
在 Execute SQL 先运行下面的通用语句，列出表，再查看选定表的字段。

SELECT name FROM sqlite_master
WHERE type = 'table' ORDER BY name;

PRAGMA table_info(transactions);

对本课样例运行关联查询，观察字段如何从两张表组合成结果：

SELECT t.id, l.name AS ledger_name,
       t.date, t.category,
       t.amount_cents / 100.0 AS amount_yuan
FROM transactions AS t
JOIN ledgers AS l ON l.id = t.ledger_id
WHERE l.space_id = 1
ORDER BY t.id;

本课样例包含家庭空间 36 元餐饮、8 元交通，公司空间 99 元餐饮。上述查询只返回家庭空间的两笔交易。对自己的副本操作时，先查看实际表结构，再选取对应字段与关联条件。

实操 B：从程序连接并查询

Notebook 用 Python 自带的 sqlite3 展示每一步；可在自己的 Jupyter 中运行，也可打开 JupyterLite，进入其 Notebook 示例后上传本课 Notebook，按顺序执行。Notebook 会自行生成相同的教学数据，仅使用 Python 标准库。

看核心代码时，重点理解连接对象、SQL、参数与结果之间的关系：

import sqlite3
from pathlib import Path

# 指向已下载的样例文件；只读连接会在文件不存在时报错。
db_path = Path("finance-review.sqlite").resolve()
conn = sqlite3.connect(db_path.as_uri() + "?mode=ro", uri=True)
rows = conn.execute(
    "SELECT category, SUM(amount_cents) "
    "FROM transactions WHERE ledger_id = ? GROUP BY category",
    (10,),
).fetchall()
conn.close()
for category, cents in rows:
    print(category, f"{cents / 100:.2f} 元")

connect 打开数据库；execute 将 SQL 和参数交给数据库；? 是参数占位符；fetchall 取得结果行；close 关闭连接；最后将整数分转换成元显示。把 (10,) 改成 (20,) 再运行，比较查询范围与结果。

从数据库结果回到 API

数据库行可以保存 amount_cents=3600，API 可以按约定返回整数分，也可以返回格式化金额；页面再按显示规则展示“36.00 元”。理解这几步转换，就能解释表字段、JSON 字段和页面文字为何可能不同。

在自己的项目中选一笔已有交易，用 API 查询其 ID，再到数据库副本查询同一条记录，对照金额单位、日期和账本归属；数据库副本的取得时间也决定能看到哪些记录。

验证理解

能够解释当前连接的是哪个文件或服务，指出账本与交易通过什么字段关联，读懂查询条件，并把 SQL 结果与 API 字段对应起来。

本课样例的预期结果

空间 1（家庭）包含餐饮 36 元、交通 8 元，合计 44 元；空间 2（公司）包含餐饮 99 元。按账本 10 查询得到家庭两笔，按账本 20 查询得到公司一笔。WHERE 条件决定查询范围，JOIN 通过 ID 关联表，GROUP BY 与 SUM 按分类汇总。

知识点五：公网访问——域名怎样连接到应用

概念与生活实例

把系统想成一栋办公楼：域名是便于记忆的名称，DNS 帮助找到网络地址，端口区分提供服务的入口，反向代理负责接待与转交，应用负责具体处理。HTTPS 为客户端与其连接的服务端提供加密传输及服务器身份验证。

对典型 Nginx + FastAPI 部署，一次访问的顺序是：浏览器解析 URL，查询 DNS，连接公网 HTTPS 入口；Nginx 按规则将请求转给应用，FastAPI 再匹配到函数，响应沿连接返回。

环节	示例	机制与设计重点
域名与 DNS	`finance.example.com` 对应网络入口	DNS 解析主机名；URL 的 `/api/transactions` 路径由后续服务处理
HTTPS 与证书	`https://…`，通常使用 443 端口	证书匹配所访问域名，客户端校验身份并建立加密连接
公网监听入口	Nginx 监听 443	安全组／防火墙规则控制网络可达性，服务还需实际监听
反向代理	请求转给 `127.0.0.1:8000`	统一接入后把请求转到应用监听地址
应用监听与路由	FastAPI 处理方法＋路径	应用在指定地址与端口运行，再分配到对应函数

看一段反向代理配置

以下片段放在已配置 HTTPS 的 Nginx server 中，表达 API 请求如何转发；保留 /api/ 前缀，让后端按相同路径匹配。

location /api/ {
    proxy_pass http://127.0.0.1:8000;
}

这时外部访问 https://finance.example.com/api/transactions，Nginx 会向本机 8000 端口的应用发送 /api/transactions 请求。proxy_pass 此处没有附加 URI，路径按本例保留；修改代理配置时，要同时考虑转发后的路径与后端路由是否一致。

应用可以只监听本机，由 Nginx 提供公网入口；应用端口无需因此直接暴露。配置中的 127.0.0.1 代表 Nginx 所在网络环境的本机；容器部署时需使用相应服务地址。若项目采用云网关或托管平台，将“公网入口与转发”这一职责对应到所用平台即可。

查看与验证理解

用电脑打开已上线的财务助手，进入浏览器开发者工具的 Network，执行一次查询，查看 Request URL、Method、Status 与 Response。
将 URL 拆成协议、域名、端口、路径与查询参数。HTTPS 未显式填写端口时，默认使用 443。
结合已有部署配置，由教师标出公网入口、应用监听地址以及路径转发规则。说明浏览器访问的地址为什么可以不同于应用监听地址。
回答：域名解析到正确入口后，如果应用进程停止，为什么页面的 API 仍可能出现 502？

查看参考解释

DNS 只解决域名解析；HTTPS、代理和应用处理还要依次完成。Nginx 可达但连接后端应用失败时，可能返回 502。外部域名和 443 是对客户端提供的入口，127.0.0.1:8000 是本例中代理向后端连接的内部地址。

回到整张图：串起一次查询

现在重新看“查询家庭账本的餐饮支出”：

浏览器或 Agent 按 API 约定构造查询请求。
域名解析与 HTTPS 连接使请求到达公网入口，反向代理将它交给应用。
FastAPI 根据方法和路径找到处理函数，并取得查询参数。
IAM 识别调用者，检查读取操作与家庭账本的数据范围。
应用通过数据访问层连接数据库，执行包含账本与分类条件的查询。
数据结果按接口约定编码为 JSON，客户端再展示。

能指着图解释每一步“接收什么、依据什么规则处理、交给谁”，就完成了本次架构复盘。

本课理解检查

路由：同一路径为什么能分别处理查询与新增？
API：分类筛选放在哪里，新增交易字段放在哪里，金额单位怎样约定？
权限：如何表达“同一个人在家庭空间能管理，在公司空间只能查看”？
数据库：连接、表关联、SQL 执行和结果格式化各负责什么？
公网：域名、DNS、HTTPS、反向代理与应用监听端口如何协作？

继续查阅