Skip to content

二、架构与工程纪律 ​

本章速览:读完后你会知道 —— ① 代码为什么这样分层、模块边界靠什么守住;② 一次后台请求经过哪些拦截器与鉴权;③ 没有 MQ/Redis 时,幂等、调度与失败补偿靠什么;④ 隐私内容在离开进程前要过哪四道关;⑤ 新增功能必须同步哪些闸门。

2.1 分层与依赖规则 ​

浏览器 ──HTTP──> Controller(参数/鉴权/返回 R) ──> Service(业务规则/事务)
                                                       ├─> Mapper(MyBatis-Plus) ──> MySQL
                                                       ├─> 其它模块的 Service 接口(同进程)
                                                       └─> SPI 端口(common.port.*)──> 具体实现
外部(DSH/桥/Hindsight)──HTTP──> 专用控制器(/api/agent/**,独立令牌拦截器)

三条硬规则(都由测试或架构闸守住):

  1. Controller 不写业务:只做参数校验、身份提取、调用 Service、包装 R。
  2. 模块间只通过 Service 接口交互,禁止直接注入别的模块的 Mapper/Entity; ModuleBoundaryTest 扫描 import 与字段类型,越界即红。
  3. 跨模块能力用"端口"表达:common/port 与 common/spi 下的接口(FileStoragePort、 EgressGatePort、MemoryHealthPort、MemoryVectorPort、JobRunnerPort、AuditPort、 MediaReferenceProvider、JobLogRecorder 等)由具体模块实现,调用方只依赖接口 —— 这样"记忆模块依赖向量化"不会反向导致 Spring 循环依赖(MemoryReadService 的 javadoc 专门解释了这条)。

2.2 横切关注点落在哪 ​

关注点实现位置说明
认证 / 授权framework/security/*Interceptor + AgentAuthInterceptor三套主体:后台用户(JWT)、Agent 令牌(scope)、API Key
审计AuditAspect + @AuditLog 注解自动记录操作人/动作/参数摘要/结果,写入 sys_audit_log
异常 → 响应GlobalExceptionHandler业务错误回 200 + code;协议层错误回真实状态码(401/404/405/409/413)
日期/时区TimezoneGuard + TimeConfigJVM 固定 Asia/Shanghai;扩展平台时间存 UTC(见 4.6)
JSON/大整数JacksonConfigLong 序列化为字符串,避免前端 JS 精度丢失(MCP 工具尤其致命)
定时任务不可重入NonReentrantJobAspect + @NonReentrant单实例下防止 Job 与自己叠加;同时写入 sys_job_log
请求级缓存/幂等TxHooks、DuplicateKeyException 捕获"先插唯一键抢占"是全项目的幂等范式

2.3 请求生命周期(一次后台请求发生了什么) ​

  1. IP 白名单(AdminIpGuardInterceptor,仅 /api/admin):不在白名单直接 403; 它先于 JWT 校验,因为登录接口也要受网络层兜底。
  2. 维护模式(MaintenanceInterceptor):site.maintenance.enabled=1 时,非白名单请求回维护提示。
  3. JWT(AuthInterceptor):解析 Authorization: Bearer,校验签名/过期/黑名单; 登录接口与健康检查/验证码等公开路径排除。/api/agent 走另一套 AgentAuthInterceptor (专用令牌 + IP 白名单 + 速率限制),两者互不混用。
  4. Controller:@Validated 校验 DTO;查询参数绑定失败由 GlobalExceptionHandler 转成 "参数 xxx 取值不合法"(不透出 Spring 异常原文)。
  5. Service:业务规则、事务(@Transactional)、幂等键、事件发布(业务事件用 @TransactionalEventListener(AFTER_COMMIT),避免"事务还没提交监听器就发通知")。
  6. 响应:R<T>{code,message,data,success};success 由 R.isSuccess() 派生(不是独立字段), Jackson 自动序列化。分页统一 {records,total,current,size}。

错误语义约定:业务/参数/权限问题 → HTTP 200 + code(前端统一提示); 请求方式不对 → 405;资源不存在 → 404;未登录 → 401;课程/系列冲突 → 409; 上传超限 → 413。理由:监控与安全扫描需要协议层事实,业务错误再用 code 区分。

2.4 调度与后台任务模型 ​

项目没有 MQ、没有分布式锁,调度靠两种机制:

机制实现适用
Spring @Scheduled27 个方法(附录 C);NonReentrantJobAspect 防叠加;每轮写 sys_job_logJava 侧固定任务(清理、日报轮询、向量 GC、会话镜像…)
扩展平台触发器ExtensionTriggerScheduler 每 30s 轮询 next_run_at(UTC),认领后异步执行系统扩展与第三方插件的定时/手动/webhook 触发

约定:

  • 单实例假设:限流、锁、缓存都是进程内;多实例会重复执行(docs/全项目审查记录.md 已把 "单实例"列为已知边界)。
  • 重启不丢任务:Java 任务把"在跑但进程重启"的记录由 StaleJobLogReconciler 标成失败并注明; 扩展运行靠 run identity + dedup_key 幂等续跑;摄取/采集靠服务端水位。
  • AI 调用不占调度线程:长任务(日报生成、扩展 agent 运行)提交到 aiExecutor/独立线程池, 避免把每分钟的日程提醒拖住(DailyDigestJob 的 javadoc 专门解释)。
  • 慢任务必须可见:每轮至少写一行 job log,写明"扫描 N / 处理 M / 跳过原因"; 失败写 fail 与异常摘要。

2.5 数据与一致性纪律 ​

纪律具体做法
迁移只前进Flyway V{n}__描述.sql;生产 flyway_schema_history 与仓库逐文件一致(163/V163)
无物理外键逻辑引用列 + 应用层校验;删除走软删(deleted)或显式级联,避免迁移顺序与锁表地狱
唯一键做幂等提醒 dedup_key、通知 dedup_key、摄取 (session_id,line_no)、扩展 run identity、订阅邮箱等
事务边界清晰Service 方法上 @Transactional;禁止在事务内做外部 HTTP(AI/微信/邮件都在提交后异步或监听器 AFTER_COMMIT)
时间口径业务时间用 Asia/Shanghai;扩展平台 next_run_at/last_run_at 存 UTC(UTC_TIMESTAMP() 判据)
ID雪花 ID(Long),对外 JSON 一律字符串化;MCP 参数兼容字符串/数字但回执用字符串
缓存配置单键 30s 缓存(保存即失效);查询向量缓存 60s/LRU 512;不引入外部缓存
删除内容类软删(可恢复);日志类按保留期物理删(*RetentionJob),清理前有引用反查防误删

2.6 隐私与出网(这个项目最在意的横切面) ​

内容分三级:public(门户可见)/ internal(仅博主与助手可见)/ private(不进模型上下文)。

四道防线:

  1. 数据层过滤:门户只读接口在 SQL 层强制 status=1、is_public=1;RAG 的访客版 (publicOnly=true)在 SQL 层排除私有笔记 —— 即使上层代码疏漏,私有内容也进不了检索结果。
  2. 出网台账(EgressLedger):每次把内容交给模型/外部(chat、embed、上下文注入) 写一行 ai_egress_log:场景、通道、各级条数、字节数,不记正文;写失败绝不抛异常(旁路数据)。
  3. 出网闸(EgressGate):site.ai.egress 三档 normal/minimal/frozen; frozen 下 chat/embed/生图一律拒绝;读侧对未知值 fail-open 但打 warn(写侧已校验,见 6.2)。
  4. 可见性收窄:后台接口默认 admin-only;MCP 工具按 scope 校验;微信桥只服务白名单用户; 后台附件下载要求归属会话且 nosniff + inline。

2.7 安全设计速览 ​

面措施
登录bcrypt 密码、失败锁定、JWT 签名(COSMOS_JWT_SECRET)、登录日志与异地告警(sys_login_log)
Agent独立令牌文件(600 权限)、scope(memory/daily/mcp/ext)、IP 白名单、限速、审计到 agent_tool_call_log
程序接入sys_api_key(前缀展示、哈希存储)+ /api/agent 白名单
访客写验证码 → IP 频率限制 → 敏感词 → 审核开关(评论/留言/友链四层)
上传扩展名/MIME 白名单、大小上限、随机文件名、私有目录、下载时强制 X-Content-Type-Options: nosniff
渲染后端 MarkdownRenderer 输出 HTML 时做白名单清洗(escapeHtmlForImport 用于导入);门户 CSP script-src 'self'
配置密钥SMTP 授权码/API Key 以 enc: 密文入库(CryptoUtil + COSMOS_SECRET_KEY),接口只回掩码
依赖/构建前端依赖锁版本;md-editor 扩展走本地同源(避开 CSP 与 CDN)

2.8 可观测性:让"没发生"也能被看见 ​

账本/信号写什么怎么用
sys_job_log每个 Java 任务每轮:名字、状态、消息、耗时后台"任务日志";能力健康看板的判据之一
notify_log / webhook_delivery每次投递:通道、状态、重试、响应摘要排查"消息发没发";重试 Job 的对象
extension_run / _run_event / _capability_call / _policy_decision / _effect扩展运行全生命周期扩展中心与运维看板的唯一事实来源
ai_egress_log / ai_token_usage出网台账、token 与成本隐私审计、用量报表、熔断
proactive_log每条主动消息的去重键与结果预算、反馈、夜间安静策略
心跳 sys_job_log 行(bridgeHeartbeat/chainProbe)外部进程存活与最后上报doctor.sh 与能力健康看板
/api/health、/api/health/readyDB/Hindsight/桥/启动自检监控与发布验证
doctor.sh(25 项)端口/挂载/令牌/备份/迁移/环回绑定…手动体检;发布后必跑

2.9 变更纪律:加东西之前先看这几条 ​

  • 加模块:module_xxx/controller|service|mapper|entity,禁止 import 别的模块 mapper; 在 docs 与 ConfigKeys/迁移里登记;跑 ModuleBoundaryTest。
  • 加端点:必须写进附录 L(文档检查器按源码注解逐条核对);无 UI 入口的要在 §8.4 登记。
  • 加表/列:新迁移(不许改旧迁移);表名写进附录 M;实体加 @TableName。
  • 加配置键:先写迁移种子(INSERT sys_config),再用 ConfigKeys 常量读取; check-config-registry.mjs 会核"键↔面板↔读点"三方一致。
  • 加能力:CapabilityCatalog 登记(type/risk/dataClass/egress/systemOnly), 在 DefaultCapabilityGateway 实现,能力调用走审计网关。
  • 加定时任务:@Scheduled + @NonReentrant + 每轮写 sys_job_log;附录 C 同步。
  • 改数字:改完先跑 mvn -B -o clean test,架构闸会告诉你文档哪里没同步。

2.10 架构闸:24 条规则在防什么 ​

ArchitectureGuardTest 是"项目宪法"的可执行版本,24 条规则大致分五类:

类别例子
分层/边界业务模块不得互相依赖实现;扩展 runtime 不得直接依赖业务模块
纪律落地业务事件监听器必须 AFTER_COMMIT;定时任务必须可重入保护;出网必须走网关
数字/清单文档规模数字、表清单、迁移号、端点路径、配置键与源码一致
死代码无注解/无接口/无引用的 public 方法;无引用的 @TableName 字段(逐条扫描)
安全/文档禁止硬编码密钥;代码引用的 docs/*.md 必须存在;MCP 工具清单一致

本页由 docs/vite-cosmos-项目说明.md 自动生成;请改源文件,不要改生成物。