workspace/code/fms/FMS新系统核心架构实施计划.md

# FMS 新系统核心架构实施计划 V1.0

> 文档版本：V1.0  
> 编制日期：2026-09-30  
> 适用范围：FMS/ERP 新系统第一阶段核心架构重构  
> 执行方式：由多个 AI 按任务卡顺序执行，人负责最终取舍和验收

## 1. 计划目标

本计划用于指导其他 AI 实现 FMS 新系统第一阶段核心架构。

第一阶段只解决以下问题：

- SQL Server 数据库如何迁移和版本化；
- 租户数据库如何连接和路由；
- 用户、公司、组织、仓库和账簿如何形成统一上下文；
- 业务域如何组织自己的表、SQL、服务、接口和页面；
- SQL 如何成为查询、报表和数据处理的主要实现；
- 简单基础资料如何使用通用 CRUD；
- 核心业务如何使用专用 SQL 和业务处理器；
- 如何用一个完整业务域验证架构。

第一阶段不实现完整 ERP，也不建设通用低代码平台。

## 2. 已确定的架构约束

其他 AI 执行所有任务时必须遵守以下约束：

1. SQL Server 是第一阶段唯一数据库目标。
2. 一个租户对应一个数据库，租户库内不使用 `tenant_id` 做日常业务过滤。
3. 业务域代码包是代码组织中心。
4. 真实业务表和 SQL 视图是事实来源。
5. SQL 文件是查询、报表和数据处理的主要实现。
6. 业务代码负责业务动作、事务和复杂业务规则。
7. 页面配置只负责表现和少量参数。
8. 不做全量 EAV，不做运行时任意生成业务表。
9. 通用 CRUD 只用于简单基础资料，不作为核心业务默认实现。
10. 工作流负责流程编排，库存、财务和结算动作必须由业务处理器完成。
11. 第一阶段不引入通用配置版本引擎、通用公式引擎和通用规则解释器。
12. 内部开发人员可以直接维护 SQL，不增加 SQL 安全沙箱、ORM 替代层或复杂 SQL DSL。
13. 所有新代码必须遵守统一目录、命名和 SQL 文件风格。

## 3. 阶段依赖

```text
T0 架构基线和代码规范
    ↓
T1 SQL Migration 和数据库运行时
    ↓
T2 租户路由和业务上下文
    ↓
T3 系统基础数据和权限
    ↓
T4 业务域模板和 SQL 调用约定
    ↓
T5 客户或产品示例业务域
    ↓
T6 工作流、审计和多语言接入
    ↓
T7 第一阶段验收和旧设计迁移清单
```

T0 到 T4 必须顺序完成。T5 完成后，T6 可以拆分给不同 AI，但最终必须统一接口和风格。

## 4. 任务 T0：架构基线和代码规范

### 4.1 目标

把新架构的原则转成开发人员和 AI 都能执行的规则。

### 4.2 工作内容

- 阅读并理解以下文档：
  - `ERP动态配置多租户多公司多语言需求分析.md`；
  - `FMS新系统核心表结构设计.md`；
  - `FMS新系统核心架构设计.md`。
- 确定 SQL Server 版本和连接方式；
- 确定数据库迁移目录和文件命名；
- 确定业务域目录结构；
- 确定表名、字段名、索引、主键和时间字段规范；
- 确定 SQL 文件参数和返回结果规范；
- 明确哪些旧设计暂时不迁移。

### 4.3 输出物

```text
开发规范补充文档
SQL Migration 目录
业务域目录模板
SQL 文件示例
架构决策记录
```

### 4.4 验收标准

- 新增一个业务域时不需要重新发明目录结构；
- SQL 文件可以被数据库工具独立执行和验证；
- 不存在同时使用两套字段命名和 SQL 组织方式的说明；
- 其他 AI 可以只读本阶段输出物开始后续工作。

## 5. 任务 T1：SQL Migration 和数据库运行时

### 5.1 目标

让每个租户数据库可以可靠地初始化、升级和记录结构版本。

### 5.2 工作内容

- 创建迁移记录表；
- 实现迁移文件扫描和顺序执行；
- 实现重复执行判断；
- 记录迁移名称、版本、checksum、执行时间和结果；
- 支持初始化新租户数据库；
- 支持租户数据库版本查询；
- 补充失败迁移的人工处理方式。

### 5.3 Migration 规则

```text
V001__create_core_tables.sql
V002__create_company_tables.sql
V003__create_audit_tables.sql
```

Migration 可以包含建表、改表、索引、视图、约束和必要的数据回填。

Migration 不负责页面布局和用户偏好，也不作为通用配置表使用。

### 5.4 验收标准

- 空数据库可以从零初始化；
- 已执行的迁移不会重复执行；
- 迁移失败时可以明确定位文件和错误；
- 两个租户数据库可以独立升级；
- 应用启动时可以读取数据库结构版本。

## 6. 任务 T2：租户路由和业务上下文

### 6.1 目标

建立统一的数据库连接、租户识别和请求上下文，不让业务域自行处理这些基础问题。

### 6.2 工作内容

- 定义 `TenantRegistry` 接口；
- 首期使用配置文件实现租户注册；
- 实现租户数据库连接创建和复用；
- 实现请求级数据库连接选择；
- 实现请求级业务上下文；
- 请求结束后清理上下文；
- 记录当前租户、用户、公司和请求编号。

### 6.3 上下文结构

```text
tenant_code
user_id
company_id
organization_id
warehouse_id
ledger_id
language
timezone
currency
request_id
```

### 6.4 验收标准

- 同一个请求内所有业务 SQL 使用同一个租户数据库；
- 业务域不需要自己读取租户配置文件；
- 用户可以切换授权公司并重新建立上下文；
- 上下文不会泄漏到下一个请求；
- 日志可以定位租户、用户、公司和请求。

## 7. 任务 T3：系统基础数据和权限

### 7.1 目标

建立所有业务域依赖的用户、角色、公司、组织、仓库和账簿。

### 7.2 第一批表

```text
s_user
s_role
s_user_role
s_role_permission
s_role_data_scope
s_company
s_organization
s_warehouse
s_ledger
s_user_company
s_user_organization
s_user_warehouse
s_user_ledger
```

### 7.3 权限范围

首期只实现：

- 用户可用公司；
- 用户可用组织；
- 用户可用仓库；
- 模块访问权限；
- 业务动作权限；
- 全部、指定公司、本组织、本组织及下级、本人和指定仓库等简单数据范围。

不实现角色继承、拒绝权限和通用权限表达式。

### 7.4 验收标准

- 一个用户可以属于多个公司；
- 一个用户可以在不同公司拥有不同角色；
- 公司、组织、仓库和账簿不会混用编码；
- 权限查询可以使用 SQL 完成；
- 所有业务查询可以取得当前公司上下文。

## 8. 任务 T4：业务域模板和 SQL 调用约定

### 8.1 目标

建立所有业务域共同遵守的实现模板，解决“一个文件一个风格”的问题。

### 8.2 业务域模板

```text
domains/<domain_code>/
├── migration/
├── sql/
├── repository/
├── service/
├── api/
├── page/
└── i18n/
```

### 8.3 SQL 文件命名

```text
<object>_list.sql
<object>_detail.sql
<object>_save.sql
<object>_<action>.sql
<object>_report.sql
```

### 8.4 访问约定

- 查询由 repository 调用 SQL；
- 保存由 repository 调用保存 SQL或 service 组织多条 SQL；
- 业务动作由 service 作为唯一入口；
- 页面只调用 API；
- 业务域不直接修改另一个业务域的内部表；
- 复杂业务必须有明确事务边界；
- 简单资料才允许使用通用 CRUD。

### 8.5 验收标准

- 创建新业务域只需复制模板并替换业务名称；
- list、detail、save、action 的代码结构统一；
- SQL 不散落在页面、控制器和配置数据库中；
- 通用 CRUD 的适用范围有明确示例。

## 9. 任务 T5：客户或产品示例业务域

### 9.1 目标

用一条完整业务链路验证新架构，而不是先建设一个空的通用引擎。

### 9.2 推荐对象

优先选择客户或产品，不要一开始选择库存或财务。

### 9.3 工作内容

```text
SQL Migration
→ b_customer 或 b_product
→ 查询 SQL
→ 保存 SQL
→ 业务域 service
→ API
→ 页面
→ 公司范围
→ 审计
→ 多语言名称
```

### 9.4 验收标准

- 可以在 SQL Server 中直接执行列表和详情查询；
- 页面不需要通用模块解释器才能运行；
- 保存过程经过明确的 repository/service；
- 公司范围可以生效；
- 关键变更有审计记录；
- 新增字段可以通过 Migration 完成；
- 业务域目录、SQL 命名和代码风格符合 T4。

## 10. 任务 T6：工作流、审计和多语言接入

### 10.1 工作流

保留 `wf_*` 工作流子系统，但绑定业务动作，不绑定任意页面配置：

```text
sales_order.submit
sales_order.approve
purchase_order.submit
expense.approve
```

工作流实例固定流程版本，真正的库存、财务和结算动作由业务域 service 执行。

### 10.2 审计

审计至少记录：

```text
user_id
company_id
domain_code
business_id
operation
before_value
after_value
request_id
occurred_at
```

### 10.3 多语言

第一阶段只实现：

```text
s_i18n_type
s_i18n
```

业务主数据按业务域使用翻译表。暂不实现多层 overlay、翻译变更集和运行时语言管理。

### 10.4 验收标准

- 工作流可以调用一个业务域动作；
- 流程实例记录固定的流程版本；
- 业务动作和审批动作有审计记录；
- 系统文案和主数据翻译可以按语言读取；
- 翻译读取不影响业务 SQL 查询。

## 11. 任务 T7：第一阶段验收和旧设计迁移清单

### 11.1 验收重点

第一阶段不是验收页面数量，而是验收架构是否成立：

- SQL 是事实来源；
- 业务域可以独立拥有表、SQL、服务和页面；
- 不依赖通用模块解释器才能运行；
- 简单对象可以使用通用 CRUD；
- 核心动作使用专用 service 和 SQL；
- 多公司上下文贯通查询、保存、权限和审计；
- 数据库结构变更通过 Migration 管理；
- 代码目录和 SQL 风格统一。

### 11.2 旧设计迁移分类

```text
保留：真实业务表、成熟 SQL、工作流运行表
迁移：散落 SQL、通用保存调用、模块页面配置
降级：s_module、s_field、s_module_schema 只做登记和表现
后置：全局配置版本、通用规则引擎、多层配置覆盖
删除：以元数据解释器为中心的核心业务运行时
```

## 12. 给其他 AI 的执行规则

每个 AI 接任务时必须先阅读：

1. `FMS新系统核心架构设计.md`；
2. `FMS新系统核心架构实施计划.md`；
3. 与当前任务直接相关的旧设计文档。

每个 AI 的任务输出必须包含：

```text
完成内容
修改文件
数据库变更
验证方式
未完成事项
风险或需要人工决策的地方
```

执行限制：

- 不得自行增加通用配置引擎；
- 不得把业务逻辑放进页面 JSON；
- 不得为一个业务对象创建第二套 SQL 调用方式；
- 不得修改无关业务域；
- 不得为了“以后可能需要”提前抽象；
- 不得删除旧表或旧接口，除非任务明确要求迁移；
- 不得把 SQL 改写成 ORM 查询作为默认方案；
- 不得只提交页面而没有 SQL、服务和验收说明。

## 13. 第一张任务卡

可以把下面内容直接交给第一个 AI：

```text
你负责 FMS 新系统核心架构实施计划的 T0 任务：架构基线和代码规范。

请先阅读：
1. FMS新系统核心架构设计.md
2. FMS新系统核心架构实施计划.md
3. FMS新系统核心表结构设计.md
4. 开发规范.md

你的目标是确定 SQL Server、Migration、业务域目录、SQL 文件命名、数据库命名和业务动作入口规范。

要求：
- 不实现业务模块；
- 不新增通用低代码引擎；
- 不修改无关文件；
- 不把 SQL 改写成 ORM 查询；
- 输出一份开发规范补充文档；
- 提供一个客户或产品业务域的空目录模板；
- 提供至少三个 SQL 文件示例；
- 最后报告修改文件、验证方式和未决问题。
```

## 14. 计划结论

第一阶段的正确顺序不是先做一个“万能模块引擎”，而是：

```text
统一规范
→ 数据库迁移
→ 租户和公司上下文
→ 系统基础数据
→ 业务域模板
→ 一个完整业务域
→ 工作流和通用能力
```

先用一个真实业务域验证架构，再决定哪些能力值得抽象。所有通用能力都必须来自实际重复，而不是来自对未来场景的猜测。