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`	多表事务保存

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

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

loaddata

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

{
  "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 关键字。

成功响应：

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

loaddatabysql

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

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

成功响应与 loaddata 相同。

page

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

{
  "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 和计算总记录数。

成功响应：

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

saveobjt

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

{
  "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 对应的主键值。
一次请求中的所有表和所有操作使用同一个数据库连接和事务。
全部操作成功后提交；任意操作失败时全部回滚。
保存成功只返回成功状态，不返回每张表的操作数量。

成功响应：

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

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

{
  "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 等版本路径升级。
文件、报表、导入、导出和其他通用接口无法完成的功能，可以单独定义特殊接口。

4.7 KiB Raw Blame History

FMS 管理系统需求规范

设计原则

固定接口

统一约定

4.7 KiB

Raw Blame History