Fast-Vben-Admin AGENTS.md

Fast Vben Admin Agent Development Standard

本文件是所有自动化编码模型、代码生成模型和人工协作者的仓库级开发规范。进入任何子目录工作时，还必须读取并遵守距离目标文件最近的 AGENTS.md。子目录规范只能补充本文件，不能放宽本文件中的架构、安全和验证要求。

• 规范版本：1.0
• 架构基线：docs/modular-architecture-implementation.md
• 维护方式：架构变更与相关 AGENTS.md 在同一变更中更新

1. 开始工作前

在修改代码前，按顺序完成：

1. 阅读本文件和目标目录下的 AGENTS.md。
2. 阅读与任务相关的事实源、ADR、现有实现和测试。
3. 执行 git status --short，识别并保留用户已有修改。
4. 用 rg 定位现有实现、调用方、测试和兼容入口。
5. 明确变更边界、数据所有者、迁移影响、Edition 影响和验证范围。

不要只依据需求描述、文件名或旧对话推断当前实现。代码、迁移、CI 和当前文档才是工作区事实。

2. 决策优先级

发生冲突时按以下顺序处理：

1. 当前任务的明确要求。
2. 已接受的 ADR。
3. 模块化架构实施基线。
4. 模块开发指南和目标目录规范。
5. 当前代码与测试反映的兼容约束。

不要直接改写已经 Accepted 的 ADR 历史结论。需要改变已接受决策时，新增 ADR 并声明替代关系。Proposed ADR 不能由模型自行改成 Accepted；必须有团队签署和文档要求的演练证据。

3. 固定架构

• 架构形态是“模块化单体 + 构建期 Edition 组合”。当前阶段不拆微服务、不引入运行时微前端、不维护产品分支。
• platform 是每个 Edition 必选的交付模块。kernel、system、infra 只是 Platform 内部限界上下文，不得加入 Edition YAML 或单独授权。
• items 是业务模块样板。新增 IOA、ERP 等模块必须复用同一种模块契约、迁移、公开 API、事件和前端装配方式。
• 新业务能力进入 backend/app/modules/<module_code> 和 frontend/apps/web-antd/src/modules/<module_code>，不得继续扩大中央业务模型、中央 Router 或全局业务页面。
• 业务模块只能依赖 Platform 稳定公开接口和其他模块的 public_api。禁止导入其他模块的 domain、application、infrastructure、routes 或 ORM 实体。
• 可选能力通过 capability 契约和组合根选择 Provider。禁止从可选模块实现建立静态依赖。

4. 唯一事实源

信息	人工维护的唯一事实源	禁止做法
Edition 模块集合	editions/<edition>.yaml	用环境变量或菜单临时增加模块
模块契约	ModuleDefinition	在多个组合根重复声明 Router、权限或事件
构建组合	生成的 build-manifest.json	前后端相互覆盖 Manifest
模块期望/实际状态	ModuleRegistry 与迁移/健康检查	请求鉴权时同步或创建运行时记录
套餐权益/例外/租户偏好	TenantPlanModule / TenantModuleEntitlementOverride / TenantModule	通过菜单或表存在性推断模块可用
用户权限	Permission、Role、Menu 关系	只依赖前端按钮隐藏
数据表所有权	Platform migration metadata 或模块自己的 migration namespace	多模块共同拥有同一张表

派生文件必须通过仓库命令生成，不得手工维护生成结果。

5. 多租户与安全红线

• 租户身份只能来自已验证 JWT、可信事件信封、受控 client-to-tenant resolver、Schedule 的平台枚举结果或显式受审计的平台入口。
• 不得直接信任 body、query、header 中的 tenant_id。公开回调必须先通过租户编码、客户端凭据或其他可信映射解析租户，再进入 UoW。
• Tenant-owned 数据必须在对应 TenantUnitOfWork 内访问。API、Worker、Schedule、CLI 使用相同隔离原则。
• privileged=True 仅用于已经完成平台级授权的受控跨租户操作。调用点必须可审计，并具有跨租户负向测试。
• ORM tenant 过滤不是 PostgreSQL RLS 的替代品；RLS 也不是可信租户解析的替代品。扩展 RLS 时必须同时更新模型集合、迁移、runtime 角色测试和调用路径。
• 不得假设所有带 tenant_id 的历史表已经启用 RLS。OAuth2/OIDC、租户全局目录和全局模块运行时表的前置设计见实施基线和 ADR-0013。
• 运行时进程使用无超级用户、无建库/建角色、无 BYPASSRLS 的 app_runtime。迁移管理员凭据不得注入 API 或 Worker。
• 禁止提交密钥、真实密码、访问令牌、个人数据或生产连接信息。