# fenlu.abp

**Repository Path**: longphui/fenlu.abp

## Basic Information

- **Project Name**: fenlu.abp
- **Description**: 分路abp
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fenlu ERP ABP 项目说明

## 0. 当前最高架构准则：以 `fenlu.server` 标准 ABP 模块化后端为准

从 2026-06-27 起，Fenlu ERP 后端重建以 [fenlu.server](./fenlu.server) 为新的标准 ABP 基线。团队后续后端开发、AI 主控开发、架构评审、代码生成和重构验收，必须优先遵守 ABP Framework 官方分层、模块化、DDD、EF Core、Identity/OpenIddict、Permission、Setting、BackgroundJob、Audit、EventBus、UnitOfWork、Repository 等标准能力。

旧目录 [backend](./backend) 只能作为以下资料来源：

- 业务资源、菜单、接口、状态、动作、流程和历史实现参考。
- 迁移旧业务语义和测试用例的来源。
- 对照差异、识别反模式和防止回退的审计样本。

旧 `backend` 的以下做法不得作为新后端继续扩展的架构样板：

- `*StructuredPersistence.cs` 承载核心业务读写。
- `Dictionary<string, object?>` / resource 字符串分发作为核心契约。
- `payload_json` / `extension_json` 保存核心 ERP 业务字段。
- 通用 `xxx_records + resource` 或 `xxx_documents + payload` 冒充领域模型。
- 单一全局 DbContext 反向 `<Compile Include>` 拉取模块 EF 源码。
- 手写大而全 Controller 正则路由替代 ABP Application Service / Auto API。
- 自研 JWT 绕开 ABP Identity/OpenIddict。
- 自研 Repository、分页、UnitOfWork、Setting、Permission、BackgroundJob、Audit、EventBus、DistributedLock 等 ABP 已提供能力。

新后端开发顺序必须是：

1. 先查 ABP 官方模块和项目内 `.codex/skills/abp-*` 规则，确认是否已有标准能力可用。
2. 再做 DDD 领域建模：聚合根、实体、值对象、领域服务、领域事件、仓储接口。
3. 再做 Application.Contracts / Application / EntityFrameworkCore / HttpApi 的标准分层实现。
4. 最后才考虑兼容旧接口或前端适配。

任何主控或团队成员如果要修改后端，必须先阅读：

- [Fenlu-ERP-ABP与标准模板差异分析报告.md](./Fenlu-ERP-ABP与标准模板差异分析报告.md)
- [Fenlu-ERP-ABP标准化重构实施计划.md](./Fenlu-ERP-ABP标准化重构实施计划.md)
- [团队开发规范.md](./团队开发规范.md)
- [.codex/skills/fenlu-abp-architect/SKILL.md](./.codex/skills/fenlu-abp-architect/SKILL.md)
- [.codex/skills/fenlu-team-development/SKILL.md](./.codex/skills/fenlu-team-development/SKILL.md)

如果上述文件与历史文档冲突，以本节和 `fenlu.server` 标准 ABP 基线为准。

Fenlu ERP 是基于 ABP Framework 重建的企业资源计划系统，当前仓库包含后端 ABP 模块化单体、前端 Vue3 客户端、接口契约、团队开发规范和项目级 AI 开发规则。

统一认证由独立 `Fenlu.Server.AuthServer.Host` 提供，用户名密码、API Key/Secret 与 OAuth2 `client_credentials` 均先换取 Access Token；所有业务 Host 只接受 Bearer Token，并通过 AuthServer 的 Discovery/JWKS 本地验签。公司切换也由 AuthServer 校验任职后重新签发 Token，禁止用公司或租户 Header 覆盖授权上下文。

本文件是团队成员克隆项目后的第一入口。新成员应先阅读本文件，再按自己使用的 AI 工具初始化项目规则，最后启动自己的 AI agent 按团队规范开发。

当前公司、员工、部门、岗位等 ERP 业务身份必须通过 `fenlu.server` 全局 `ICurrentBusinessContext` 获取。Header 或 Claim 只能作为服务端签发和校验后的业务身份载体，不能由前端请求直接伪造为授权事实。真实业务身份必须绑定到 ABP 登录用户、MasterData 员工账号绑定和任职关系；任何模块都不得直接信任 `X-Fenlu-CompanyId`、`X-Company-Id`、`CompanyId` Claim 等客户端传入值。

## 1. 项目目标

本项目以 ABP Framework 为后端基础，围绕 Fenlu ERP 业务构建统一平台能力和业务模块能力。

后端核心目标：

- 遵守 ABP 分层架构。
- 使用模块化单体组织业务。
- 保持 Host / HttpApi / Application / Domain / EntityFrameworkCore 边界清晰。
- 使用 PostgreSQL 和 EF Core Migration。
- 使用平台中心承载认证、权限、状态机、业务动作、审批、关系、幂等、锁、审计等通用能力。
- 核心业务数据结构化落表，避免回到 `payload_json`。

前端核心目标：

- 使用当前 `vue3-visual-baseline` 客户端。
- 遵守 Vue3、TypeScript、Vite、Pinia、Vue Router、Ant Design Vue、Axios 技术栈。
- 默认关闭 mock，真实调用后端 `/api/v1`。
- 页面操作、列表、筛选、表单、动作流必须真实联调接口。

## 2. 目录结构

```text
fenlu.abp/
  fenlu.server/                    ABP 后端工程
    Fenlu.Server.sln               后端解决方案
    src/
      Fenlu.Server.Domain.Shared
      Fenlu.Server.Domain
      Fenlu.Server.Application.Contracts
      Fenlu.Server.Application
      Fenlu.Server.EntityFrameworkCore
      Fenlu.Server.HttpApi
      Fenlu.Server.HttpApi.Host
      Fenlu.Server.DbMigrator
      modules/                     业务模块与模块 HttpApi
    docs/                          后端设计、审计、联调、团队规范
    scripts/                       构建、边界、结构化审计、smoke 脚本

  vue3-visual-baseline/            当前最新前端客户端
    README.md                      前端项目说明
    docs/api-contract/             前后端接口契约
    src/                           Vue3 源码

  .codex/
    skills/                        项目级 Codex skills
    scripts/install-codex-skills.ps1

  Fenlu-ERP-ABP后端总设计.md        后端总设计
  README.md                        当前项目入口说明
```

注意：后续前端开发以 `vue3-visual-baseline` 为准，不要使用旧客户端目录。

## 3. 关键文档

团队日常开发默认阅读：

- `README.md`
- `团队开发规范.md`
- `Fenlu-ERP-ABP后端总设计.md`
- `vue3-visual-baseline/README.md`
- `vue3-visual-baseline/docs/api-contract`

结构化持久化或数据库相关任务再阅读：

- `backend/docs/业务数据持久化审计清单.md`
- `backend/docs/ERP业务数据结构化持久化整改计划.md`

历史追溯或旧问题定位再阅读：

- `Fenlu-ERP-ABP开发实施计划.md`
- `backend/docs/实施问题清单.md`
- `backend/docs/接口实施矩阵.md`

## 4. 开发环境要求

后端：

- .NET SDK：`10.0.x`，当前项目目标框架为 `net10.0`，本地已验证版本为 `10.0.301`。
- ABP Framework：`10.4.1`，以各 `.csproj` 中 `Volo.Abp.*` 包版本为准，团队成员不要单独升级局部 ABP 包。
- PostgreSQL：建议 `16.x` 或 `17.x`，本地开发默认端口 `5432`，数据库连接按 `appsettings.Development.json` 配置。
- Redis：建议 `5.x` 及以上，本地已验证 `5.0.14.1`，项目默认连接 `127.0.0.1:3683`。

前端：

- Node.js：建议 `20.x LTS`，本地已验证 `20.18.0`。
- pnpm：建议 `8.x`，本地已验证 `8.14.0`，当前 lockfile 版本为 `6.0`。
- Vue：`^3.5.13`。
- Vite：`^6.0.5`。
- TypeScript：`^5.7.2`。
- Ant Design Vue：`^4.2.6`。
- Axios：`^1.7.9`。

AI 开发：

- 可使用 Codex Desktop、Codex CLI、Claude Code 或其他支持读取项目文件的 AI 编程工具。
- Codex 用户可安装本仓库 `.codex/skills` 中维护的项目级 skills。
- Claude Code 或其他工具用户不需要安装 Codex skills，但必须让 agent 读取 `README.md`、`团队开发规范.md`、`Fenlu-ERP-ABP后端总设计.md`、`vue3-visual-baseline/README.md`、`vue3-visual-baseline/docs/api-contract`，并按这些规则执行。

### 4.1 环境配置说明

后端默认开发环境使用 `Development` 配置。团队成员应先检查以下配置文件：

```text
fenlu.server/src/Fenlu.Server.HttpApi.Host/appsettings.json
fenlu.server/src/Fenlu.Server.HttpApi.Host/appsettings.Development.json.example
fenlu.server/src/Fenlu.Server.DbMigrator/appsettings.json
fenlu.server/src/Fenlu.Server.DbMigrator/appsettings.Development.json.example
```

数据库使用 PostgreSQL。首次启动前需要确认连接字符串指向本机或团队指定数据库，常见配置项包括：

```json
{
  "ConnectionStrings": {
    "Default": "Host=127.0.0.1;Port=5432;Database=fenlu_abp;Username=postgres;Password=你的密码"
  }
}
```

如果本机 PostgreSQL 用户、密码、数据库名不同，只修改本机开发配置，不要把个人密码提交到仓库。涉及数据库结构变更时必须新增 EF Core Migration，并执行 DbMigrator：

```powershell
dotnet run --project fenlu.server/src/Fenlu.Server.DbMigrator/Fenlu.Server.DbMigrator.csproj
```

团队协作中，数据库迁移必须先同步最新 `origin/master` 后再生成，避免 `FenluAbpDbContextModelSnapshot.cs` 大面积冲突。迁移文件、`.Designer.cs`、Snapshot、实体、DbSet、ModelBuilder、仓储路由、审计脚本和受影响 smoke/docs 必须一起提交。已合并到 `master` 的迁移禁止修改或删除，后续调整必须新增修正迁移。完整规则见 [团队开发规范.md](./团队开发规范.md) 的“数据库迁移规范”。

Redis 用于缓存、锁、消息等平台能力。团队成员需要确认本机 Redis 已启动，并检查后端配置中的 Redis 连接地址。常见本地配置为：

```json
{
  "Redis": {
    "Configuration": "127.0.0.1:3683",
    "InstanceName": "fenlu:abp:"
  }
}
```

后端 Host 默认使用 5000 端口：

```powershell
dotnet run --project fenlu.server/src/Fenlu.Server.HttpApi.Host/Fenlu.Server.HttpApi.Host.csproj --urls http://127.0.0.1:5000
```

启动后需要确认：

```text
http://127.0.0.1:5000/swagger
http://127.0.0.1:5000/openapi/v1.json
```

前端以 `vue3-visual-baseline` 为准。开发前检查前端环境文件：

```text
vue3-visual-baseline/.env.development
vue3-visual-baseline/.env.local.example
vue3-visual-baseline/.env.production
```

本地联调必须使用真实后端接口，不允许默认 mock：

```text
VITE_API_PROXY_TARGET=http://127.0.0.1:5000
VITE_USE_REMOTE=true
VITE_AUTH_ENABLED=true
VITE_AUTH_MOCK=false
```

前端默认使用 5173 端口：

```powershell
cd vue3-visual-baseline
pnpm install
pnpm run dev -- --port 5173 --strictPort
```

浏览器访问：

```text
http://127.0.0.1:5173
```

如果登录失败，优先检查：

- DbMigrator 是否成功执行。
- 后端 Host 是否运行在 `http://127.0.0.1:5000`。
- 前端代理是否指向 `http://127.0.0.1:5000`。
- `VITE_AUTH_MOCK` 是否为 `false`。
- 浏览器 Network 中 `/api/v1/auth/login`、`/api/v1/auth/context` 是否真实返回。
- 数据库中是否已有开发账号和基础权限种子数据。

团队成员不要把个人 `.env.local`、数据库密码、临时日志、浏览器截图、agent 草稿提交到仓库。

## 5. 初始化 AI 开发规则

本仓库维护了项目级 AI 开发规则。Codex 用户可以把这些规则安装为 skills；Claude Code 或其他 AI 工具用户可以直接让 agent 读取这些规则文件。
这些规则文件都保存在仓库内，属于项目资料的一部分，不依赖某一个 AI 工具才能阅读。

当前规则文件包括：

- `fenlu-team-development`：团队开发规范，覆盖 Git、ABP、Vue3、接口、注释、测试、文档、合并门禁。
- `fenlu-abp-architect`：ABP/Fenlu 后端架构守护，检查分层、模块、结构化持久化、业务边界。
- `fenlu-code-review`：Fenlu 代码评审。
- `fenlu-ponytail`：最小实现纪律，避免过度设计和无关重构。
- `abp-*`：从 ABP 官方源码仓库 `.agents/skills` 转入的 Codex skills，覆盖 DDD、EF Core、Application Layer、Module、Dependency Rules、Infrastructure、Multi-Tenancy、Authorization、Testing、Development Flow 等 ABP 官方开发模式。

Fenlu 专用 skills 是项目最终约束；`abp-*` skills 是 ABP 官方模式参考。后端开发、审计和返工时，应先使用 Fenlu 专用 skills，再按任务类型联动对应 ABP skill，避免重复造 ABP 已经提供的框架能力。

### 5.1 Codex 用户

Codex 用户首次克隆后，在仓库根目录执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .codex\scripts\install-codex-skills.ps1 -SkipPonytailMarketplace
```

如果需要同时注册 Ponytail 插件市场，可以执行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .codex\scripts\install-codex-skills.ps1
```

安装脚本会把项目 skills 复制到当前用户的 Codex skills 目录：

```text
%USERPROFILE%\.codex\skills
```

项目 skills 更新后，团队成员应重新执行安装脚本刷新本机 skills。

本仓库已内置 Fenlu 专用 skills 和 ABP 官方模式 skills。安装后，Codex 用户在新会话或重启 Codex 后应能看到以下两类 skills：

```text
Fenlu 专用：
fenlu-team-development
fenlu-abp-architect
fenlu-code-review
fenlu-ponytail

ABP 官方模式参考：
abp-core
abp-ddd
abp-ef-core
abp-application-layer
abp-module
abp-dependency-rules
abp-infrastructure
abp-multi-tenancy
abp-authorization
abp-development-flow
abp-testing
abp-cli
abp-mvc
abp-angular
abp-blazor
abp-microservice
abp-mongodb
abp-app-nolayers
```

后端任务触发建议：

- 领域模型、聚合根、领域服务、领域事件：使用 `fenlu-abp-architect` + `abp-ddd`。
- DbContext、EF Repository、迁移、索引、种子数据：使用 `fenlu-abp-architect` + `abp-ef-core`。
- AppService、DTO、分页返回、验证、对象映射：使用 `fenlu-team-development` + `abp-application-layer`。
- 模块边界、项目引用、依赖方向：使用 `fenlu-abp-architect` + `abp-module` + `abp-dependency-rules`。
- 设置、缓存、事件总线、后台任务、分布式锁：使用 `fenlu-abp-architect` + `abp-infrastructure`。
- 多租户、多组织、权限和安全：使用 `fenlu-abp-architect` + `abp-multi-tenancy` + `abp-authorization`。
- 测试和验收：使用 `fenlu-team-development` + `abp-testing`。

注意：当前会话中新增或更新的 skills 通常不会立刻刷新，建议完整重启 Codex 或新开任务会话后再开始正式开发。

Codex skills 的详细安装说明见：

```text
CODEX_SKILLS_SETUP.md
```

### 5.2 Microsoft Learn MCP

团队成员建议为自己的 AI 编程工具配置 Microsoft Learn MCP。该 MCP 用于查询 Microsoft 官方文档，主要帮助确认 .NET、ASP.NET Core、EF Core、C#、认证授权、中间件、Swagger、HostedService、EF Core Migration 等官方行为。

Microsoft Learn MCP 只作为官方资料来源，不能替代本项目规则。Fenlu ERP 的 ABP 分层、DDD 模块边界、结构化持久化、接口契约、中文注释、Git 流程和合并门禁，仍以本仓库 `README.md`、`团队开发规范.md`、`.codex/skills` 和后端总设计为准。

Codex 用户可在 `%USERPROFILE%\.codex\config.toml` 中加入以下配置：

```toml
[mcp_servers.microsoft-docs]
url = "https://learn.microsoft.com/api/mcp"
```

配置后需要完整重启 Codex 桌面应用或重新启动对应 AI 工具会话，工具列表中才可能出现 Microsoft Learn MCP 能力。重启后可让 agent 先确认 MCP 是否可用；如果当前工具没有暴露 MCP，也可以继续按项目文档开发，只是在涉及官方框架行为争议时改用浏览器或官方文档人工确认。

推荐在任务话术中加入：

```text
如果当前 AI 工具已配置 Microsoft Learn MCP，遇到 .NET、ASP.NET Core、EF Core、C#、认证授权、中间件、Swagger、HostedService、EF Core Migration 等官方行为不确定时，优先查询 Microsoft Learn MCP 或 Microsoft Learn 官方文档；但 Fenlu ERP 的业务架构、ABP 分层、模块边界、结构化持久化和团队规范必须以本仓库规则为准。
```

### 5.3 NuGet MCP

NuGet MCP 是选择性安装项，不是所有团队成员和所有 AI agent 的强制前置条件。它主要用于帮助 Codex 或其他受沙箱、网络、包管理权限限制的 agent 查询 NuGet 官方包信息、版本、兼容性、依赖关系、漏洞、升级建议和 NuGet 配置状态。

如果你使用的 AI agent 不受沙箱限制，能够正常访问 NuGet、执行 `dotnet restore`、读取项目包引用并检查依赖冲突，可以不安装 NuGet MCP。但无论是否安装 NuGet MCP，涉及包新增、升级、漏洞修复、依赖冲突和 ABP 模块引用时，都必须核验包来源、版本、兼容性和影响范围。

NuGet MCP 只能辅助查包、选版本和分析依赖，不能替代项目架构判断。Fenlu ERP 仍然遵守以下规则：

- ABP Framework 已有模块或基础设施时，优先引用和扩展 ABP，不重复造轮子。
- ERP 业务领域模型、业务链路、状态动作、结构化表、补偿规则仍由 Fenlu 自己按 DDD 实现。
- 不允许主控凭记忆编造包名、版本号或依赖关系。
- 不允许未经评审单独升级局部 ABP 包；ABP 包版本必须保持一致。

Codex 用户可在 `%USERPROFILE%\.codex\config.toml` 中加入以下配置：

```toml
[mcp_servers.nuget]
command = "dnx"
args = ["NuGet.Mcp.Server@1.4.15", "--source", "https://api.nuget.org/v3/index.json", "--yes"]
startup_timeout_sec = 120

[mcp_servers.nuget.env]
DOTNET_CLI_TELEMETRY_OPTOUT = "true"
```

前置条件：

- `.NET SDK 10.0.x`，本机已验证 `10.0.301`。
- `dnx` 命令可用，可通过 `Get-Command dnx` 检查。
- 能访问 NuGet 源 `https://api.nuget.org/v3/index.json`，或团队配置的私有 NuGet 源。

配置后需要完整重启 Codex 桌面应用或重新启动对应 AI 工具会话，工具列表中才可能出现 NuGet MCP 能力。未安装 NuGet MCP 的 agent，可以使用 NuGet 官方网站、`dotnet list package`、`dotnet restore`、`dotnet nuget` 等方式完成同等核验。

推荐在任务话术中加入：

```text
如果当前 AI 工具已配置 NuGet MCP，遇到 NuGet 包新增、升级、漏洞修复、依赖冲突、ABP 模块引用、包版本兼容性、NuGet.Config、Central Package Management、Package Source Mapping 等问题时，优先查询 NuGet MCP。不得凭记忆编造包名、版本号或依赖关系；报告中必须写明查询到的包名、版本、来源和采用原因。
```

### 5.4 Claude Code 或其他 AI 工具用户

Claude Code 或其他 AI 工具不需要执行 Codex skills 安装脚本，但必须在任务开始前要求 agent 读取以下文件：

```text
README.md
团队开发规范.md
Fenlu-ERP-ABP后端总设计.md
vue3-visual-baseline/README.md
vue3-visual-baseline/docs/api-contract
.codex/skills/fenlu-team-development/SKILL.md
.codex/skills/fenlu-team-development/references/team-development-rules.md
.codex/skills/fenlu-abp-architect/SKILL.md
.codex/skills/fenlu-code-review/SKILL.md
.codex/skills/abp-ddd/SKILL.md
.codex/skills/abp-ef-core/SKILL.md
.codex/skills/abp-application-layer/SKILL.md
.codex/skills/abp-module/SKILL.md
.codex/skills/abp-dependency-rules/SKILL.md
.codex/skills/abp-infrastructure/SKILL.md
.codex/skills/abp-multi-tenancy/SKILL.md
.codex/skills/abp-authorization/SKILL.md
.codex/skills/abp-development-flow/SKILL.md
```

如果使用的工具支持项目级规则文件，可以把 Fenlu 专用 skills 和常用 `abp-*` skills 转成该工具的项目规则；如果不支持，就在每次启动任务时把第 7 节话术发给 agent。

### 5.5 将 Codex Skills 转换为其他 AI 工具规则的话术

如果团队成员使用 Claude Code、Cursor、Trae、Continue 或其他 AI 编程工具，可以先让该工具读取 Codex skills，再转换成该工具自己的项目规则文件。参考话术：

```text
你现在需要为 Fenlu ERP ABP 项目初始化本工具可识别的项目级 AI 开发规则。

工作目录：
当前仓库根目录

请先读取以下 Codex skills 和项目规范，把它们当作规则来源，而不是只当普通文档摘要：
- .codex/skills/fenlu-team-development/SKILL.md
- .codex/skills/fenlu-team-development/references/team-development-rules.md
- .codex/skills/fenlu-abp-architect/SKILL.md
- .codex/skills/fenlu-code-review/SKILL.md
- .codex/skills/fenlu-ponytail/SKILL.md
- .codex/skills/abp-ddd/SKILL.md
- .codex/skills/abp-ef-core/SKILL.md
- .codex/skills/abp-application-layer/SKILL.md
- .codex/skills/abp-module/SKILL.md
- .codex/skills/abp-dependency-rules/SKILL.md
- .codex/skills/abp-infrastructure/SKILL.md
- .codex/skills/abp-multi-tenancy/SKILL.md
- .codex/skills/abp-authorization/SKILL.md
- .codex/skills/abp-development-flow/SKILL.md
- .codex/skills/abp-testing/SKILL.md
- README.md
- 团队开发规范.md
- Fenlu-ERP-ABP后端总设计.md
- vue3-visual-baseline/README.md
- vue3-visual-baseline/docs/api-contract

请根据当前 AI 工具的规则机制，生成或更新项目级规则文件。
如果你是 Claude Code，优先生成或更新 CLAUDE.md。
如果你是其他工具，请生成该工具推荐的项目规则文件。

转换要求：
1. 保留 Fenlu ERP 专用规则，不要泛化成普通 ABP 或普通 Vue 项目规则。
2. 明确前端以 vue3-visual-baseline 为准。
3. 明确后端必须遵守 ABP Framework 分层和 Fenlu 模块边界。
4. 明确 Host 只做运行时装配，HttpApi 只做 Controller 转发，Application 做业务编排，Domain 做领域规则，EntityFrameworkCore 做持久化。
5. 明确核心业务字段不得写入 payload_json，extension_json 只能保存非核心扩展字段。
6. 明确全项目所有当前和未来核心业务资源不得用 `xxx_records + resource`、`xxx_support_records + resource`、通用主数据表、配置表或 JSON payload 冒充结构化表；ERP 核心业务必须真实表、真实列、真实索引、真实关系。
7. 明确不允许默认 mock，不允许静态数据冒充接口。
8. 明确 public C# 类、接口、record、方法、属性、DTO 必须有中文 XML 注释，复杂 private/internal 逻辑也要有中文注释。
9. 明确中文注释必须有真实业务含义，禁止批量模板注释；`DbSet`、常量、参数、Controller action、AppService、Domain Policy、Persistence 注释必须与真实职责一致。
10. 明确开发必须在独立分支，提交前必须执行项目门禁。
11. 明确修改接口、数据库、业务流程或前端页面时，必须同步更新验证和文档。
12. 明确后端开发必须优先复用 ABP 官方能力，不允许重复造 Repository、分页、ApplicationService、Setting、Permission、Audit、BackgroundJob、Blob、EventBus、MultiTenancy 等基础设施。
13. 明确 `abp-*` skills 是 ABP 官方模式参考，Fenlu 专用 skills 是本项目最终约束；两者冲突时，以 Fenlu ERP 总设计和团队规范为准。
14. 输出生成的规则文件路径、主要规则摘要，以及你没有转换的内容。

注意：
- 不要删除或改写 .codex/skills 原文件。
- 不要把个人本地配置、密码、token、临时日志写入规则文件。
- 如果你不确定某条规则如何映射到当前工具，请保留为普通文本规则。
```

## 6. AI Agent 启动前准备

启动自己的 AI agent 前，请先确认：

```powershell
git status --short --branch
git fetch origin
git checkout master
git pull --ff-only origin master
```

Codex 用户还需要刷新项目 skills：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .codex\scripts\install-codex-skills.ps1 -SkipPonytailMarketplace
```

新功能开发必须从最新 `master` 切独立分支：

```powershell
git checkout -b feature/<module>-<task>
```

不要让 agent 直接在 `master` 上做大功能。

## 7. 给 AI Agent 的参考话术

团队成员可以复制下面的话术给自己的 agent：

```text
你现在在 Fenlu ERP ABP 项目中协助开发。

工作目录：
当前仓库根目录

你可以是 Codex、Claude Code 或其他 AI 编程工具，但必须按本项目规则工作。

如果你支持 Codex skills，请优先使用：
- fenlu-team-development
- fenlu-abp-architect
- fenlu-code-review
- fenlu-ponytail

后端 ABP 开发还必须按任务类型联动使用：
- abp-ddd
- abp-ef-core
- abp-application-layer
- abp-module
- abp-dependency-rules
- abp-infrastructure
- abp-multi-tenancy
- abp-authorization
- abp-development-flow
- abp-testing

如果你不支持 Codex skills，请把下面这些文件作为项目规则读取和遵守：
- .codex/skills/fenlu-team-development/SKILL.md
- .codex/skills/fenlu-team-development/references/team-development-rules.md
- .codex/skills/fenlu-abp-architect/SKILL.md
- .codex/skills/fenlu-code-review/SKILL.md
- .codex/skills/abp-ddd/SKILL.md
- .codex/skills/abp-ef-core/SKILL.md
- .codex/skills/abp-application-layer/SKILL.md
- .codex/skills/abp-module/SKILL.md
- .codex/skills/abp-dependency-rules/SKILL.md
- .codex/skills/abp-infrastructure/SKILL.md
- .codex/skills/abp-multi-tenancy/SKILL.md
- .codex/skills/abp-authorization/SKILL.md
- .codex/skills/abp-development-flow/SKILL.md

如果当前 AI 工具已配置 Microsoft Learn MCP，遇到 .NET、ASP.NET Core、EF Core、C#、认证授权、中间件、Swagger、HostedService、EF Core Migration 等官方行为不确定时，优先查询 Microsoft Learn MCP 或 Microsoft Learn 官方文档；但 Fenlu ERP 的业务架构、ABP 分层、模块边界、结构化持久化和团队规范必须以本仓库规则为准。

如果当前 AI 工具已配置 NuGet MCP，遇到 NuGet 包新增、升级、漏洞修复、依赖冲突、ABP 模块引用、包版本兼容性、NuGet.Config、Central Package Management、Package Source Mapping 等问题时，优先查询 NuGet MCP。不得凭记忆编造包名、版本号或依赖关系；报告中必须写明查询到的包名、版本、来源和采用原因。

请先阅读并遵守：
- README.md
- 团队开发规范.md
- Fenlu-ERP-ABP后端总设计.md
- vue3-visual-baseline/README.md
- vue3-visual-baseline/docs/api-contract

如果任务涉及数据库表、结构化持久化、payload_json、extension_json、fenlu.server persistence boundary scan，再读取：
- backend/docs/业务数据持久化审计清单.md
- backend/docs/ERP业务数据结构化持久化整改计划.md

如果任务涉及历史进度或旧问题追踪，再读取：
- Fenlu-ERP-ABP开发实施计划.md
- backend/docs/实施问题清单.md
- backend/docs/接口实施矩阵.md

开发要求：
1. 不要直接在 master 上做大功能。
2. 先从最新 master 切独立分支。
3. 后端必须遵守 ABP Framework 分层和 Fenlu 模块边界。
4. 前端必须使用 vue3-visual-baseline 和现有 Vue3 技术栈。
5. 不允许默认 mock，不允许静态数据冒充接口。
6. 核心业务字段不得写入 payload_json。
7. extension_json 只能保存非核心扩展字段。
8. 全项目所有当前和未来核心业务资源不得用 `xxx_records + resource`、`xxx_support_records + resource`、通用主数据表、配置表或 JSON payload 冒充结构化表，`ExtensionJson(data, [])` 必须视为错误。
9. 所有 public 类、接口、record、方法、属性、DTO 必须有中文 XML 注释。
10. private/internal 的复杂业务逻辑也要写有效中文注释。
11. 中文注释必须说明真实业务含义，禁止“方法体调用”“返回下游结果”“保存当前记录业务数据”“参数输入值”“只读展示值”等模板注释。
12. XML `param` 必须与真实签名一致，不能出现 `null`、重复参数名或大小写不一致。
13. 数据库 schema 变更必须先同步最新 master，再生成 EF Core Migration；迁移、Snapshot、实体映射、审计脚本和 smoke/docs 必须一起提交。
14. 修改接口、业务、数据库、页面时，必须同步更新测试、文档和验证记录。

每次提交前必须执行：
- git status --short --branch
- dotnet build fenlu.server/Fenlu.Server.sln --no-restore -v:minimal
- backend/scripts/fenlu.server module boundary scan -Json
- backend/scripts/fenlu.server persistence boundary scan -Json
- cd vue3-visual-baseline && pnpm run check && pnpm run typecheck && pnpm run build

涉及数据库 schema 时必须执行 DbMigrator。
涉及模块业务时必须跑对应模块 smoke。

完成后请提交并推送分支，输出：
- 分支名
- commit id
- 改动文件摘要
- 验证结果
- 剩余问题
- 是否建议合并
```

## 8. 模块开发第一步：领域模型与持久化矩阵

团队成员开发任何模块前，第一步不是直接写接口、页面或数据库表，而是先让 AI agent 对该模块做全量资源矩阵和 DDD/结构化持久化审计。这个步骤适用于研发、采购、销售、仓储、生产、质检、财务、人力、售后、设备、能耗、设置以及后续新增模块。

可复制下面的话术，把 `<模块名称>`、`<模块代码或目录>` 替换成当前任务对应模块：

```text
你现在负责 Fenlu ERP ABP 项目的 <模块名称> 模块开发前置审计与整改规划。

工作目录：
当前仓库根目录

本次不要先写功能代码，不要先做 Controller、AppService、前端页面或 smoke。第一步必须从以下四个维度对 <模块名称> 模块做全量资源矩阵：

1. 前端菜单维度
- 检查 vue3-visual-baseline 中该模块的菜单、子菜单、路由、页面、弹窗、按钮、表单、筛选、导入、导出、打印、设置、选择器和详情页。
- 列出每个页面资源和每个用户动作对应的业务含义。

2. 接口契约维度
- 检查 vue3-visual-baseline/docs/api-contract 中该模块相关接口。
- 覆盖列表、详情、新增、编辑、删除、状态动作、审批动作、导入、导出、打印、设置、options、tree、picker、metrics、dashboard 等接口。
- 标记每个接口对应的资源、请求字段、响应字段、状态字段、行明细字段和上下游关系。

3. 后端模块维度
- 检查 fenlu.server/src/modules/<模块代码或目录> 以及对应 HttpApi、Application、Domain、EntityFrameworkCore 文件。
- 按 ABP/DDD 思路判定每个资源应属于聚合根、实体、值对象、领域服务、应用服务、仓储、平台中心调用还是只读投影。
- 重点确认业务逻辑是否留在 Domain/Application，Controller 是否只是转发，Host 是否没有业务逻辑。

4. 数据库 schema 维度
- 检查当前 PostgreSQL schema、EF Core Entity、DbSet、ModelBuilder、Migration、Repository 路由。
- 对每个资源判定是否已经有真实业务表、真实字段、真实索引、唯一约束、外键或已文档化的跨模块 RelationCenter 关系。
- 递归检查 payload_json、extension_json、settings、dynamic_configs、master_data_records、xxx_documents、xxx_records、xxx_support_records 中是否存在核心业务字段泄漏，包括嵌套 form/items/lines/records 等对象和数组。

审计判断标准：
- 不能只看“有没有表”，必须看核心业务字段是否真实列化、明细是否拆表、关系是否可追踪、索引和约束是否能支撑 ERP 查询和计算。
- 只要字段参与查询、筛选、业务计算、状态流转、审批、上下游关联、权限过滤、审计、报表、库存、生产、质量、人力或财务核算，就必须进入真实领域模型和结构化表。
- 单位、品牌、分类、供应商、客户、仓库、库位、员工、设备、财务科目等基础资料如果已有设置中心、主数据或模块子菜单维护入口，业务表只能保存稳定引用，例如 code/id，不能把完整对象复制到 JSON。
- extension_json 只允许保存非核心、低频、不可查询、不可计算、不参与流程和关系的扩展字段，并且必须有白名单说明。
- payload_json 只能作为历史兼容、迁移回填、平台过程数据或低频配置数据，不能作为核心业务主存储。

输出要求：
1. 输出 <模块名称> 全量资源矩阵，字段包括：前端页面/菜单、接口契约、后端资源、DDD 模型归属、数据库表、核心字段、明细表、关系、索引/约束、JSON 泄漏、缺口等级。
2. 对每个资源给出结论：已合格、需补表、需补字段、需拆明细、需补关系、需补索引、需清理 JSON、需走平台中心、需补接口联调。
3. 如果发现核心字段在 payload_json 或 extension_json 中，列出具体表、字段路径、样例 key、应迁移到的真实表/列。
4. 给出整改实施顺序，优先处理高频主数据、交易单据、库存/财务/生产/质量/人力计算链路。
5. 明确需要新增或修改的 Entity、DbSet、ModelBuilder、Migration、Repository、Domain Policy、Application Service、HttpApi Adapter、前端 API、页面联调、smoke、fenlu.server persistence boundary scan 和文档。
6. 不要把 xxx_records + resource、xxx_support_records + resource、通用 master-data 表、settings 表、payload_json 或 extension_json 当成 ERP 核心业务的最终结构化方案。
7. 完成审计后再开始整改；整改必须持续推进到 build、DbMigrator、边界审计、结构化审计、模块 smoke、前端 check/typecheck 通过，并提交推送分支。
```

## 9. 后端常用命令

构建：

```powershell
dotnet build fenlu.server/Fenlu.Server.sln --no-restore -v:minimal
```

启动后端 Host：

```powershell
dotnet run --project fenlu.server/src/Fenlu.Server.HttpApi.Host/Fenlu.Server.HttpApi.Host.csproj --urls http://127.0.0.1:5000
```

Swagger：

```text
http://127.0.0.1:5000/swagger
```

运行 DbMigrator：

```powershell
dotnet run --project fenlu.server/src/Fenlu.Server.DbMigrator/Fenlu.Server.DbMigrator.csproj
```

架构边界检查：

```powershell
backend/scripts/fenlu.server module boundary scan -Json
```

结构化持久化检查：

```powershell
backend/scripts/fenlu.server persistence boundary scan -Json
```

## 10. 前端常用命令

进入前端目录：

```powershell
cd vue3-visual-baseline
```

启动前端：

```powershell
pnpm run dev -- --port 5173 --strictPort
```

前端地址：

```text
http://127.0.0.1:5173
```

检查：

```powershell
pnpm run check
pnpm run typecheck
pnpm run build
```

前端真实接口开发必须确认：

```text
VITE_API_PROXY_TARGET=http://127.0.0.1:5000
VITE_USE_REMOTE=true
VITE_AUTH_ENABLED=true
VITE_AUTH_MOCK=false
```

## 11. Git 开发流程

新任务：

```powershell
git fetch origin
git checkout master
git pull --ff-only origin master
git checkout -b feature/<module>-<task>
```

开发中同步主干：

```powershell
git fetch origin
git merge origin/master
```

提交：

```powershell
git status --short --branch
git add <files>
git commit -m "feat: add xxx"
git push origin <branch>
```

提交信息示例：

```text
feat: add finance voucher balance validation
fix: handle warehouse outbound stock deduction
test: verify purchase approval smoke
docs: update frontend real api regression report
```

## 12. 合并前门禁

合并回 `master` 前必须通过：

- 后端 build。
- `fenlu.server module boundary scan`。
- `fenlu.server persistence boundary scan`。
- DbMigrator，若涉及数据库。
- 受影响模块 smoke。
- 前端 check/typecheck/build。
- 文档更新。
- 无 P0/P1。
- 无未说明的 mock/fallback。
- 无核心字段 JSON 泄漏。

## 13. 当前重点约束

1. 后端业务逻辑不得进入 Host 或 Controller。
2. 业务模块代码必须留在自己的模块内。
3. 平台能力必须复用 Platform 中心，不得模块私有实现。
4. 核心业务数据必须结构化落表。
5. 前端必须真实调用后端接口。
6. 团队代码必须有中文注释。
7. 大功能必须分支开发、验证、提交、推送、评审后合并。

## 14. 问题处理

遇到以下情况必须停止合并并先修复：

- build 失败。
- Host 无法启动。
- DbMigrator 失败。
- boundary error。
- structured audit error。
- smoke 失败。
- 前端 check/typecheck/build 失败。
- 登录失败。
- 页面默认 mock。
- 核心新增/编辑/状态动作失败。
- 财务金额、库存、核销、凭证错误。

P2/P3 可以记录后继续，但必须写入对应报告或问题清单。

## 15. 给团队的建议

每位成员开始任务前先让 agent 读项目 README 和团队规范，不要直接让 agent “看代码开干”。

每次任务结束要求 agent 输出：

- 做了什么。
- 改了哪些文件。
- 跑了哪些验证。
- 哪些没跑。
- 有哪些剩余风险。
- 是否已经 push。

这样可以减少跑偏、重复返工和合并冲突。

## 2026-06-27 `fenlu.server` ABP 骨架收口记录

本轮已在 `fenlu.server` 建立新的 ABP 标准骨架基线，目标仅限后端骨架和模块边界，不迁移旧 `backend` 业务代码，不实现采购、销售、仓储等具体业务逻辑。

已确认并保留的基础结构：

- `Fenlu.Server.sln` 可打开并包含标准主项目、测试项目，以及本轮新增的 `platform`、`master-data` 标准模块项目。
- `src/` 下保留 `Domain.Shared`、`Domain`、`Application.Contracts`、`Application`、`EntityFrameworkCore`、`HttpApi`、`HttpApi.Client`、`HttpApi.Host`、`DbMigrator`。
- `test/` 下保留 `TestBase`、`Domain.Tests`、`Application.Tests`、`EntityFrameworkCore.Tests`、`HttpApi.Client.ConsoleTestApp`。
- `common.props` 继续作为 ABP、EF Core、Microsoft.Extensions 版本集中管理入口，新增项目不散落硬编码 ABP 包版本。

`src/modules` 当前状态：

- 已建立 6 项目 ABP 骨架：`platform`、`master-data`。
- 仅目录占位：`purchase`、`sales`、`warehouse`、`production`、`quality`、`finance`、`hr`、`after-sales`、`rd`、`equipment`、`energy`、`settings`、`integration`。

本阶段明确复用 ABP 能力：Identity、OpenIddict、Permission、Setting、Feature、BackgroundJob、AuditLogging、EventBus、UnitOfWork、Repository、DistributedCache、DistributedLock、BlobStoring。Fenlu ERP 平台语义如业务动作、状态机、单据关系、编号规则、审批语义、待办语义、业务事件目录、数据权限投影、多公司/多组织上下文扩展，留到后续阶段在 `platform` 模块内按 DDD 建模。

遗留风险：测试项目 `Fenlu.Server.EntityFrameworkCore.Tests` 仍存在 `SQLitePCLRaw.lib.e_sqlite3 2.1.11` NuGet 高危警告；NuGet MCP 查询显示该包最新稳定版仍为 `2.1.11`，本轮不引入预发行包。生产项目的 AutoMapper、KubernetesClient、MessagePack 传递依赖警告已按 NuGet MCP 最小修复方案用直接引用覆盖。提交级 `appsettings.json` 不保存数据库密码、OpenIddict 证书口令或 StringEncryption passphrase；DbMigrator 需由本地私密配置或环境变量提供连接串后再执行。