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