Files

T

CI / docs-build (push) Successful in 28s

Details

docs(architecture): 模块速览同步第一波终态——六容器/media 职责/pet 收官状态

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-09-09 09:33:30 +08:00

5.3 KiB

Raw Blame History

后端模块结构与职责

本页是后端结构的唯一权威速览：模块怎么划分、各自负责什么、端口与依赖关系。结构性变更（新增/拆分模块）须经 ADR 决策并同步更新本页。最后更新：2026-09-08（M3 第一波收口：六容器 + media 闭环）。

一图速览

patbond-api（Maven 多模块，Spring Boot 3.5 + JDK 17）
├── patbond-common     公共库（无端口，被其余模块依赖）
├── patbond-auth       认证服务          :8081
├── patbond-user       用户服务 + 埋点    :8082   ← Flyway 迁移链唯一持有者
├── patbond-pet        宠物健康档案服务    :8083   ← M2 新增（ADR-009）
└── patbond-community  社区服务          :8084   ← M3 新增（ADR-017）

部署形态：docker compose 六容器（postgres:18 + MinIO 对象存储（ADR-016，自托管、私有桶）+ auth + user + pet + community），应用容器无状态（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
media 上传流程（ADR-017）：POST /api/v1/media/uploads 两步上传（预签名 PUT 直传 MinIO → confirm ready）+ 预签名 GET 读取，存储经 ObjectStorage 适配层隔离供应商
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（最新体重 / 疫苗进度 / 下次接种 / 当月花费，事实表实时聚合不持久化展示值）
照片/附件 M2 未做（ADR-010）；media 基础能力 M3 已落地（ADR-016/017），宠物头像/疫苗证书接线另排
当前状态：M2 已收官全量交付（18 操作 + 契约 v1.2.0 冻结）

patbond-community（社区域，:8084，M3 新增）

社区 Feed / 帖子 / 单层评论 / 点赞收藏 / 关注（ADR-018 的 M3 MVP 范围；话题表已建但功能首版剪出）
只读写 community schema（数据表由 V5 建）；作者公开资料按 D3-9 方案 B 经 patbond-user 的 /internal 批量接口取数（后续波次落地）
/api/v1/** 自骨架起即接 RS256 资源侧校验（与 user/pet 同一公钥约定）；/health 探活在 /api/v1 之外
media 上传流程不在本模块（ADR-017：实现在 patbond-user，社区侧只做 asset 只读校验）
当前状态：第一波骨架（T3-02）已落地；业务端点随 M3 后续波次按契约实现

关键纪律

契约先行：所有对外端点以 patbond-doc/docs/api/openapi.yaml 为唯一事实源，新接口先冻结契约再实现（M2 起）。
单迁移链：数据库迁移只进 patbond-user，新表按域用 schema 前缀区分（identity / platform / pet_health / …）。
服务间调用：MVP 阶段 Feign 静态 URL 直连、无注册中心（ADR-002，Nacos 已移除）；微服务化阶段再引入。
配置：敏感配置走 .env / application.yml（gitignore）+ .sample 模式，环境变量注入（PATBOND_DB_URL 等）。
测试：集成测试一律 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 域扩展：基础上传链路已随 M3 落地（自托管 MinIO，ADR-016）；带宽/预算触发时迁云对象存储（适配层保证仅换配置）；宠物头像、疫苗证书、健康事件附件接线另排。

5.3 KiB Raw Blame History Unescape Escape