# FMS 管理系统需求规范

## 设计原则

- FMS 是一个前后端分离的多机构管理系统。
- 一个机构对应一个独立数据库，机构码统一命名为 `orgid`。
- 登录时必须提交机构码、用户名和密码。后端根据机构码连接对应数据库并验证用户。
- 登录成功后，登录凭证与机构码绑定。后续请求只操作当前登录机构的数据库，切换机构必须重新登录。
- 后端只负责登录、机构数据库路由、通用数据接口、事务和少量特殊接口。
- 页面、查询条件、SQL、数据组织、校验和普通业务流程均由前端完成。
- 当前阶段不考虑安全性，前端可以直接拼接查询条件和 SQL。
- 后端通用接口完成后，应尽量保持稳定。增加普通业务时只修改前端和数据库，不增加后端业务接口。

## 固定接口

| 方法 | 路径 | 用途 |
|------|------|------|
| `POST` | `/api/auth/login` | 机构登录 |
| `POST` | `/api/data/loaddata` | 按表或视图加载数据 |
| `POST` | `/api/data/loaddatabysql` | 执行完整查询 SQL |
| `POST` | `/api/data/page` | 执行分页查询 |
| `POST` | `/api/data/saveobjt` | 多表事务保存 |

**登录**

```json
{
  "orgid": "G3HD",
  "username": "admin",
  "password": "123456"
}
```

登录成功后返回登录凭证和用户信息。后续请求携带登录凭证，不再重复提交 `orgid`。

**loaddata**

用于表或视图的普通查询，不执行分页。

```json
{
  "source": "v_bs_business",
  "fields": ["b_id", "b_state", "customer_name"],
  "where": "b_state = '草拟'",
  "order_by": "b_id desc"
}
```

- `source` 必填，表示表名或视图名。
- `fields` 可省略，省略时返回全部字段。
- `where` 可省略，由前端直接拼接，不包含 `WHERE` 关键字。
- `order_by` 可省略，不包含 `ORDER BY` 关键字。

成功响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "rows": [],
    "row_count": 0
  }
}
```

**loaddatabysql**

用于关联、聚合、统计等完整 SQL 查询，不执行分页。SQL 由前端直接拼接。

```json
{
  "sql": "select customer_id, sum(amount) as total from v_fee where fee_date >= '2026-01-01' group by customer_id"
}
```

成功响应与 `loaddata` 相同。

**page**

所有分页查询统一使用本接口。

```json
{
  "sql": "select * from v_bs_business where b_state = '草拟'",
  "order_by": "b_id desc",
  "page_no": 1,
  "page_size": 20
}
```

- `sql` 必填，不包含分页语句。
- `order_by` 必填，用于保证分页顺序稳定。
- `page_no` 从 1 开始，默认值为 1。
- `page_size` 默认值为 20。
- 后端负责生成分页 SQL 和计算总记录数。

成功响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "rows": [],
    "row_count": 0,
    "total": 0,
    "page_no": 1,
    "page_size": 20
  }
}
```

**saveobjt**

用于一个或多个表的新增、修改和删除。

```json
{
  "tables": [
    {
      "table": "bs_business",
      "key_field": "b_id",
      "inserts": [],
      "updates": [
        {
          "b_id": "10001",
          "b_state": "草拟"
        }
      ],
      "deletes": []
    },
    {
      "table": "bs_business_container",
      "key_field": "subid",
      "inserts": [],
      "updates": [],
      "deletes": [
        {
          "subid": "20001"
        }
      ]
    }
  ]
}
```

- `tables` 必须是非空数组。
- `table` 是目标表名，`key_field` 是该表的单个主键字段。
- `inserts`、`updates` 和 `deletes` 均为可选数组，省略时按空数组处理。
- 修改和删除的数据必须包含 `key_field` 对应的主键值。
- 一次请求中的所有表和所有操作使用同一个数据库连接和事务。
- 全部操作成功后提交；任意操作失败时全部回滚。
- 保存成功只返回成功状态，不返回每张表的操作数量。

成功响应：

```json
{
  "code": 0,
  "message": "保存成功"
}
```

保存失败时可以返回失败位置：

```json
{
  "code": 2001,
  "message": "保存失败",
  "details": {
    "table": "bs_business_container",
    "action": "update",
    "index": 2
  }
}
```

## 统一约定

- API 路径使用全小写名称，JSON 多单词字段使用 `snake_case`。
- `code = 0` 表示成功，非零值表示失败。
- 查询结果统一放在 `data.rows` 中，没有数据时返回空数组。
- 不使用参数占位符，查询条件和 SQL 均由前端拼接完成。
- 不增加功能相同但名称不同的接口。
- 不使用 `V2`、`V3`、`new`、`old`、`test` 或 `bak` 等临时名称。
- 接口发生不兼容升级时，统一通过 `/api/v2` 等版本路径升级。
- 文件、报表、导入、导出和其他通用接口无法完成的功能，可以单独定义特殊接口。