PanWatch AI 盯盘后端架构解读web → modules → platform 单向依赖如何防止大泥球【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatchPanWatch盯盘侠是一款覆盖 A股、港股、美股的 AI 盯盘工具提供持仓分析、实时提醒与自动报告。它的后端采用模块化单体架构一个 FastAPI 应用、一个共享数据库但代码被严格组织成web → modules → platform的单向依赖并用架构测试在每次推送前强制校验。本文讲清楚这套防大泥球机制的设计思路与落地方式。先回答一个问题为什么不拆微服务很多团队的第一反应是模块多 微服务多PanWatch 反其道而行。按 ARCHITECTURE.md 的定义目标是不是为每个领域拆微服务而是让每段业务代码都有明确的所有者、依赖方向和测试边界避免重新形成无边界的core目录。所谓大泥球Big Ball of Mud就是所有代码挤在一起、互相导入、改一处崩三处的状态。PanWatch 的解法很朴素分层 单向依赖 测试守卫。三层依赖方向速览整个后端只有四个顶层目录依赖只能从上往下流动web ───────────────► modules ───────────────► platform │ │ │ │ └─ public service / DTO ──┘ └────────────────────────► platform目录定位一句话职责src/web/HTTP 技术组件只做跨模块复用的输入输出映射不含业务逻辑src/modules/业务能力一个一级目录 一个产品能力拥有自己的 router 与 servicesrc/platform/技术平台与业务无关的怎么连接、怎么执行不碰任何投资决策src/bootstrap/应用装配唯一创建 FastAPI 应用并注册 router 的位置反向依赖一律禁止platform不得导入modulesweb不承载复杂 SQL 或策略判断。platform 技术底座只回答怎么连不回答做什么platform/下的每个子目录都是一个技术能力职责边界写得很死节选自 src/ARCHITECTURE.md子目录责任不应包含persistence/数据库 engine、ORM 模型、全部迁移持仓、策略等业务判断ai/AI provider 客户端、故障切换提示词、工具授权marketdata/行情客户端、供应商路由、数据归一化告警阈值、选股规则events/SSE 等事件传输事件的业务含义scheduling/cron 解析、交易日历Agent 调度流程notifications/通道发送、基础去重哪种业务事件该通知observability/日志上下文、trace领域指标推导这样做的直接收益换 AI 供应商只动platform/ai/换行情源只动 src/platform/marketdata/业务代码零感知。modules 业务能力一个目录一个所有者modules/是产品的业务心脏九个模块各管一摊跨模块想找别人办事只能走对方公开的 service / DTOassistant— AI 对话助手与任务快照公开边界是AssistantServiceautomation— 定时分析 Agent、TradingAgents、调度器market— 标的、行情、K 线、新闻、价格告警portfolio— 账户、仓位、诊断、业绩基准research / strategy— 分析上下文、因子与信号paper_trading— 模拟盘执行与账本reporting / administration— PDF 报告、设置与健康检查每个模块的内部推荐结构是api/ service.py repository.py schemas.py其中service 是优先的公开边界——其他模块应调用 service而不是绕过它去摸 repository。以portfolio模块为例仪表盘、账户历史等接口全部位于 src/modules/portfolio/api/业务编排在 portfolio/service.py而不是散落在公共目录里。web 与 bootstrap唯一的装配层web/目录小到令人意外只有响应包装与错误适配这类纯技术组件。例如 src/web/response.py 实现了一个响应包装中间件把所有/api/响应统一成{code, success, data, message}格式并且对 SSE 流式响应做了逐块直通处理——它不关心数据从哪来。而 src/bootstrap/application.py 是整个项目唯一创建 FastAPI 实例的地方导入各模块的 router、挂中间件、注册认证依赖。它像一份总装清单一行业务规则都不写。一个典型业务 router如 src/modules/market/api/stocks.py只做三件事校验 HTTP 输入创建 command / DTO获取本模块 service把结果映射为 HTTP response 或错误码。跨模块协作只走公开 service 和 DTO这是最容易腐化的地方规则因此定得最严❌ 禁止跨模块导入对方的models.py、repository.py、api/router✅ 需要别人模块的数据走对方暴露的 service / DTO✅ 异步、可延迟、多所有者参与的工作发布领域 event由订阅模块自行处理。举个真实例子如果strategy模块需要持仓摘要不应导入portfolio.repository而应由portfolio暴露专门的 service。再看价格告警这类典型链路——告警引擎在market模块price_alert_engine.py触发后由platform/notifications负责通道发送和去重业务含义始终留在模块内。架构测试把依赖规则写进推送前检查只靠文档约束三个月后必然失效。PanWatch 的关键一步是用 AST 扫描把所有依赖规则变成测试。tests/test_architecture_boundaries.py 会解析每个 Python 文件的 import 语句并拦截以下行为platform/下任何文件导入src.modules.* 模块 A 跨模块导入模块 B 的models/repository/api或*_api 旧目录复活src/core、src/agents、src/web/api、src/web/database.py等迁移前遗留路径一旦重新出现测试直接失败✅bootstrap/application.py必须是唯一应用工厂。姊妹文件 tests/test_module_ownership.py 则校验实现归位比如ai_client必须住在src/platform/ai/paper_trading_engine必须住在src/modules/paper_trading/——防止有人把通用代码偷偷搬回公共目录。最后scripts/pre-push git hook 在推送前跑全量pytest失败即中止推送。也就是说违反依赖方向的新代码根本进不了仓库。新代码放哪一张速查表架构文档还附了放置指南遇到新需求先对号入座完整版见 src/ARCHITECTURE.md需求放置位置新 AI / 行情 / 通知供应商对应platform/*adapter新投资、分析或用户工作流对应modules/domainservice新 API所属模块的api/包新后台任务业务执行在模块cron/日历用platform/scheduling新 ORM 表或迁移platform/persistence由所属模块 service 使用带业务含义的 helper归其所属 module不得创建新的core小结PanWatch 防大泥球的思路可以浓缩成三句话分层即分权——web、modules、platform各司其职依赖只能单向流动边界即契约——跨模块只走公开 service / DTO / event禁止互摸 ORM 模型测试即执法——AST 扫描 pre-push 全量测试让违反依赖方向的代码无法入库。分层不是为了显得高级而是让每段代码的归属、依赖和演进方式都清晰可见。这也是模块化单体在 AI 盯盘这类持续加功能的项目里比盲目拆微服务更务实的答案。【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK US markets, powered by TradingAgents. Portfolio insights, real-time alerts automated reports.盯盘侠覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考