From 5de9f397cbd44de170f86947756b7a5f2464a000 Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Mon, 7 Sep 2026 17:25:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=90=8E=E7=AB=AF=E6=A8=A1=E5=9D=97=E7=BB=93=E6=9E=84=E4=B8=8E?= =?UTF-8?q?=E8=81=8C=E8=B4=A3=E9=80=9F=E8=A7=88=E9=A1=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 四模块（common/auth/user/pet）职责、端口、单迁移链纪律、 演进方向（微服务化/M5 FK 补回/media 域）一页速览， 挂「架构」导航首位，作为后端结构唯一权威入口。 Co-Authored-By: Claude Fable 5 --- docs/architecture/backend-modules.md | 68 ++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 69 insertions(+) create mode 100644 docs/architecture/backend-modules.md diff --git a/docs/architecture/backend-modules.md b/docs/architecture/backend-modules.md new file mode 100644 index 0000000..9867038 --- /dev/null +++ b/docs/architecture/backend-modules.md @@ -0,0 +1,68 @@ +# 后端模块结构与职责 + +> 本页是后端结构的**唯一权威速览**：模块怎么划分、各自负责什么、端口与依赖关系。 +> 结构性变更（新增/拆分模块）须经 ADR 决策并同步更新本页。 +> 最后更新：2026-09-07（M2 第二波，T2-03 进行中）。 + +## 一图速览 + +``` +patbond-api（Maven 多模块，Spring Boot 3.5 + JDK 17） +├── patbond-common 公共库（无端口，被其余模块依赖） +├── patbond-auth 认证服务 :8081 +├── patbond-user 用户服务 + 埋点 :8082 ← Flyway 迁移链唯一持有者 +└── patbond-pet 宠物健康档案服务 :8083 ← M2 新增（ADR-009） +``` + +部署形态：docker compose 四容器（postgres:18 + auth + user + pet），应用容器无状态（ADR-007）。 + +## 模块职责 + +### patbond-common（公共库） + +- 统一错误信封与业务错误码体系（`code`/`message`/`data` 结构，稳定错误码契约） +- 共享异常类型与基础组件 +- **不含业务逻辑、不起服务**；其余三个模块都依赖它 + +### patbond-auth（认证域，:8081） + +- 注册 / 登录 / 退出：`/api/v1/auth/**` +- JWT RS256 签发；access 15 分钟 / refresh 30 天轮换 / 多设备并行（ADR-003） +- 登录失败锁定（5 次错误 → 423 临时锁定） +- 首版仅账号 + 密码（ADR-004），凭证模型预留扩展 +- 会话真值在数据库（auth_sessions，token_family 轮换检测） + +### patbond-user（用户域 + 平台能力，:8082） + +- 用户资料：`/api/v1/me` +- **埋点接收**：`/api/v1/events`（批量 ≤50、202 逐条结果、唯一允许匿名的写端点、eventId 幂等），落 `platform.product_events` +- **Flyway 迁移链唯一持有者**：全部数据库迁移（V1 身份/媒体基线、V2 埋点表、V3 宠物健康域、V4 字典种子……）集中在本模块 `src/main/resources/db/migration/` 统一执行，**其他模块不得携带 Flyway**——避免多模块并发迁移竞争，pet 域建表也在这里 + +### patbond-pet（宠物健康档案域，:8083，M2 新增） + +- 宠物 CRUD 与品种目录：`/api/v1/pets`、breeds +- 成员权限模型：pet_owners 三角色（owner / caregiver 可写，viewer 只读；ADR-015），创建宠物者自动成为 primary owner +- 健康记录：体重（weights）、疫苗（vaccinations + vaccine catalog，状态机）、健康事件（health-events，六类）、照护提醒（care-reminders，四类，仅数据接口不做推送） +- 档案聚合摘要：summary（最新体重 / 疫苗进度 / 下次接种 / 当月花费，事实表实时聚合不持久化展示值） +- 照片/附件本迭代不做（ADR-010，media 域待对象存储选型） +- **当前状态**：模块骨架 + T2-03（CRUD + 权限框架）施工中；数据表已由 V3 建好 + +## 关键纪律 + +1. **契约先行**：所有对外端点以 `patbond-doc/docs/api/openapi.yaml` 为唯一事实源，新接口先冻结契约再实现（M2 起）。 +2. **单迁移链**：数据库迁移只进 patbond-user，新表按域用 schema 前缀区分（identity / platform / pet_health / …）。 +3. **服务间调用**：MVP 阶段 Feign 静态 URL 直连、无注册中心（ADR-002，Nacos 已移除）；微服务化阶段再引入。 +4. **配置**：敏感配置走 `.env` / `application.yml`（gitignore）+ `.sample` 模式，环境变量注入（`PATBOND_DB_URL` 等）。 +5. **测试**：集成测试一律 Testcontainers（postgres:18，ADR-006/008），每模块交付 `./mvnw clean test` 必绿。 + +## 演进方向 + +- **微服务化**（ADR-002 预留）：模块边界即服务边界，pet 域可整模块独立部署；届时引入配套版本 Spring Cloud Alibaba。 +- **M5 marketplace 域**：V3 已裁剪的 4 条跨 schema 外键（vaccinations/health_events → providers/bookings）由 M5 迁移补回。 +- **media 域**：对象存储选型拍板后另立迭代实现（宠物头像、疫苗证书、健康事件附件）。 + +## 相关文档 + +- 技术决策记录：[decisions.md](decisions.md)（ADR-001~015） +- API 契约：`docs/api/openapi.yaml` +- 各迭代过程报告：开发文档 → 第一/第二迭代 diff --git a/mkdocs.yml b/mkdocs.yml index fc72338..1299e74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,4 +46,5 @@ nav: - API: - 契约说明: api/index.md - 架构: + - 后端模块结构与职责: architecture/backend-modules.md - 技术决策记录: architecture/decisions.md