Imported from AperturePlus/imld-system (AGENTS.md). Install upstream with npx skills add AperturePlus/imld-system. Copyright stays with the author.

AGENTS.md

项目定位

• 项目类型：Spring Boot 模块化单体（Modular Monolith）。
• 业务领域：医疗健康（基层医疗机构、个人用户、隐私要求高的大型医院）。
• 核心目标：一套代码同时支持 SaaS 与内网私有化，并在必要业务下实现受控云端通信。
• 第一优先级：数据安全、隐私保护、合规可审计，在此前提下控制研发与运维成本。

部署策略（明确业务分层）

• SaaS：面向基层医疗机构与个人用户，不要求内网部署，直接使用云端服务。
• 私有化：面向对隐私与合规要求更高的大型医院，核心业务系统部署在院内网络。
• 私有化商业模式：买断制交付 Docker 镜像，默认包含 1 年技术支持。
• 支持与升级：支持期内可免费获取升级；支持期后可续费购买技术支持并恢复升级权益。
• 混合通信：私有化医院在特定场景下与云端通信，典型包括：
  • 随访信息推送。
  • 面向在院就诊患者的 VIP 订阅权益联动。
• 架构约束：无论 SaaS 还是私有化，必须基于同一代码仓、同一模块边界、同一主干演进。

启动指令基线（开发与交付）

• 开发联调统一使用 spring.profiles.active 组：
  • dev-saas：.\gradlew.bat bootRun --args="--spring.profiles.active=dev-saas"
  • dev-private：.\gradlew.bat bootRun --args="--spring.profiles.active=dev-private"
  • dev-private-bridge：.\gradlew.bat bootRun --args="--spring.profiles.active=dev-private-bridge"
• dev-private 与 dev-private-bridge 默认加载 dev-license-bypass，本地开发不做许可证启动验签。
• 若开发环境需要显式验证真实许可证，可通过启动参数开启：
  • .\gradlew.bat bootRun --args="--spring.profiles.active=dev-private --imld.licensing.private-edition.startup-validation-enabled=true --imld.licensing.private-edition.public-key-file-path=C:\imld\license\public.pem --imld.licensing.private-edition.license-file-path=C:\imld\license\license.json --imld.licensing.private-edition.activation-state-file-path=C:\imld\license\activation-state.json"
  • 或设置环境变量 IMLD_PRIVATE_STARTUP_VALIDATION_ENABLED=true 后再启动 dev-private。
• 交付环境建议使用部署形态 profile：
  • saas
  • private
  • private,private-bridge
• private 与 private-bridge 默认要求签名许可证校验；上线前必须明确：
  • IMLD_LICENSE_FILE_PATH
  • IMLD_LICENSE_PUBLIC_KEY_FILE_PATH
  • IMLD_ACTIVATION_STATE_FILE_PATH
• 若仅用于本地联调且不做授权验签，只允许使用开发 profile 默认跳过或临时设置 IMLD_PRIVATE_STARTUP_VALIDATION_ENABLED=false；不得作为生产配置。
• 当 profile 名称、激活参数、启动方式变更时，必须同时更新 README.md 启动命令章节与本节内容。

工作总原则

• 单代码基线：通过配置、策略、适配器区分部署形态，禁止维护两套功能等价系统。
• 模块边界清晰：模块内高内聚，跨模块仅经稳定接口调用，避免隐式耦合。
• 本地优先与最小出域：私有化场景默认“数据留院内”，只有被授权的最小必要数据允许出域。
• 安全默认开启（Secure by Default）：默认拒绝、最小权限、全链路可审计。
• 兼容性优先：任何变更必须评估对 SaaS、私有化、混合通信三种运行方式的影响。

架构与代码约束

• 保持模块化单体，不为“可能的分布式”提前拆微服务。
• 建议按业务能力分层模块：
  • 核心诊疗域（患者、病历、处置等），支持本地独立运行。
  • 云协同域（消息推送、会员订阅、跨院增值服务），可按部署策略启停。
  • 基础支撑域（认证授权、审计、配置、集成适配）。
• 外部依赖统一抽象接口（消息、存储、网关、密钥管理、通知渠道），按部署环境加载实现。
• 使用 profiles + 显式配置开关，不允许硬编码“云端专用”或“私有化专用”业务分支。
• 数据库变更必须通过可回滚、可审计迁移脚本管理。

安全与隐私基线

• 敏感数据分类分级：个人健康信息（PHI）默认高敏，优先本地处理。
• 数据出域原则：私有化医院仅可同步“最小必要字段”，优先脱敏、去标识化、令牌化。
• 传输保护：院内到云端通信强制 TLS/mTLS，请求签名与重放防护必须开启。
• 网络边界：通过受控网关/防火墙策略开放必要出口，不允许院内核心库被云端反向直连。
• 存储保护：敏感字段按需加密；密钥不入库、不入代码，统一密钥管理。
• 日志与审计：禁止记录明文敏感信息；关键操作与跨域同步必须完整审计可追溯。
• 访问控制：RBAC + ABAC 组合授权，默认拒绝（deny by default）。

云端通信设计要求（私有化医院）

• 仅允许“业务允许清单”中的场景触发云通信（如随访推送、VIP 权益联动）。
• 采用事件契约而非共享数据库；契约版本化并向后兼容。
• 建议使用双标识策略：院内 patient_id 与云端 cloud_subject_id 映射隔离，避免直接暴露真实身份标识。
• 同步链路必须具备失败重试、幂等、死信处理与人工补偿机制。
• 默认单向出站优先，若需双向能力必须经过专项安全评审。

许可证与升级策略

• 私有化部署需激活：现场输入激活码，仅作为开通入口，不作为唯一授权依据。
• 运行授权采用签名许可证文件（离线可验签），许可证至少包含部署模式、医院标识、支持期、可用场景与可选机器绑定信息。
• 升级授权采用签名发布清单（release manifest），并基于支持期进行准入控制。
• 授权规则建议：
  • support_end_date >= release_date 时允许升级。
  • 超过支持期默认拒绝升级；若为安全补丁且策略允许，可例外放行。
• 禁止使用可伪造的纯文本开关替代签名授权。

合规与质量要求

• 设计与实现需预留合规扩展点，按部署地区适配监管要求（如等保、HIPAA、GDPR/PIPL）。
• 所有新功能至少包含单元测试、集成测试与关键安全测试（越权、泄露、注入、重放）。
• 涉及跨域同步的功能，必须补充数据字典与“字段出域依据”文档。
• API 与事件契约遵循向后兼容策略；破坏性变更需版本化并给出迁移方案。

多租户与环境策略

• SaaS 默认多租户，所有租户数据访问必须显式携带租户上下文。
• 私有化默认单租户可运行，但代码层不得删除多租户能力，只通过配置降级。
• 租户隔离方案可配置（共享库分租户/独立库），业务代码不得与具体方案强绑定。

医生端辅助诊断接口对齐（Web）

• 医生端辅助诊断统一使用 DiagnosesApi 契约（复数路径），主路径为：
  • GET /api/v1/web/diagnoses/sessions
  • GET /api/v1/web/diagnoses/sessions/{sessionId}
  • POST /api/v1/web/diagnoses/sessions
  • POST /api/v1/web/diagnoses/feedbacks
• 所有 diagnoses 接口请求必须携带 X-Tenant-Id，不得在后端硬编码租户。
• 辅助诊断“启动会话”必须落库并可审计：
  • 写入 diagnosis_session（含 input_snapshot）。
  • 写入 diagnosis_result（含模型证据快照 evidence_json）。
  • 写入 diagnosis_recommendation（由模型建议映射）。
• 医生签发/复核统一走 submitDoctorFeedback，不得新增旁路“签发表”绕过审计链路。
• 模型注册优先复用 model_registry；缺省模型仅可自动补齐为本地模型配置，不得引入未授权云模型依赖。
• 前端开发可保留旧 mock 路径作为回退（/api/v1/web/diagnosis/*），但生产联调必须以 /api/v1/web/diagnoses/* 为准。
• 若接口字段或路径变化，必须同步更新：
  • web/src/api/diagnosis.ts
  • web/src/api/types.ts
  • 本文件 AGENTS.md 对应章节

变更执行清单（每次任务都要检查）

• 是否仍保持“同一套代码支持 SaaS 与私有化”？
• 私有化场景下是否仍可在不联网时完成核心诊疗流程？
• 该变更是否改变了数据出域边界、字段范围或网关策略？
• 是否引入跨模块耦合、隐藏技术债或不可观测链路？
• 是否同步更新配置、迁移脚本、测试、审计与回滚方案？

协作约定（对 Codex/开发者）

• 先读上下文再改代码；优先小步、可回滚的增量提交。
• 涉及安全、权限、数据模型、跨域同步的改动，必须写清风险、防护点与出域依据。
• 如需求与本文件冲突：先满足患者隐私与合规要求，再与业务方确认取舍。