20260715172851

code/fms/REQUIREMENTS.md

@@ -1,870 +0,0 @@
-# FMS 后端 API 需求规范
-
-## 1. 设计定位
-
-FMS 是面向内部用户的多机构 ERP 系统。
-
-当前阶段只确定以下基础原则：
-
-- 所有 API 请求统一使用 `POST`。
-- 前端登录时通过请求头传递机构码。
-- 一个机构对应一个独立数据库。
-- 登录成功后机构码绑定到访问令牌，后续请求由后端从令牌获取机构码并选择数据库。
-- 前端不接触数据库连接信息。
-- 后端负责身份认证、机构数据库路由和统一响应。
-- 权限编码只用于前端禁用按钮，暂不作为后端业务接口的授权条件。
-- 普通查询和保存采用结构化数据协议，不要求前端编写参数占位符。
-- 高级只读查询可以通过独立的 `load_sql` 接口提交 SQL。
-- 新业务在现有数据库表和视图能够支持的情况下，只需开发前端页面，不需要增加后端业务接口。
-
-当前提供以下接口：
-
-| 方法 | 路径 | 用途 | 是否需要登录 |
-|------|------|------|--------------|
-| `POST` | `/api/auth/login` | 登录并获取用户及按钮权限 | 否 |
-| `POST` | `/api/data/load` | 通用结构化数据查询 | 是 |
-| `POST` | `/api/data/load_sql` | 高级只读 SQL 查询 | 是 |
-| `POST` | `/api/data/save` | 通用数据保存 | 是 |
-
-## 2. 通用请求规范
-
-### 2.1 HTTP 方法
-
-- 所有接口只使用 `POST`。
-- 不使用 `GET`、`PUT`、`PATCH` 或 `DELETE`。
-- 查询、创建、修改、删除和业务操作都通过后续定义的 `POST` 接口完成。
-
-### 2.2 数据格式
-
-- 请求和响应使用 `application/json; charset=utf-8`。
-- 除登录路由使用的 `orgid` 请求头外，请求参数放在 JSON 请求体中。
-- 需要登录的接口通过 Bearer Token 认证。
-- 响应不能包含数据库连接信息、令牌密钥、密码或服务端调用栈。
-
-需要登录的请求必须包含：
-
-```http
-Authorization: Bearer <access_token>
-Content-Type: application/json; charset=utf-8
-```
-
-### 2.3 命名规范
-
-- API 路径、请求字段和响应字段优先使用简短、明确的全小写名称。
-- 能使用单个单词或常用组合词时，不使用驼峰命名法，例如 `username`、`orgid`。
-- 多个单词无法简洁表达时使用 `snake_case`，例如 `access_token`、`display_name`。
-- JSON 字段不使用 `camelCase`，例如不使用 `accessToken`、`displayName`。
-- TypeScript 接口和类型名称遵循语言惯例使用 `PascalCase`，其字段名与 API JSON 字段保持一致。
-
-### 2.4 机构标识
-
-机构标识统一命名为 `orgid`。
-
-规则：
-
-- `orgid` 类型为非空字符串。
-- 登录请求必须通过 `orgid` 请求头传递机构标识。
-- 登录成功后，`orgid` 保存在访问令牌声明或服务端会话中。
-- 后续业务请求不在请求头或请求体中重复传递 `orgid`。
-- 后端从访问令牌中获取 `orgid` 并选择机构数据库。
-- 前端只传机构码，不能传数据库名称、地址、端口、账号或密码。
-- 机构码必须作为完整字段值传递，不能用于拼接数据库连接字符串或 SQL。
-- 机构码不存在、已停用或未配置数据库时，请求失败。
-
-登录请求头示例：
-
-```http
-orgid: SH001
-```
-
-### 2.5 通用成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {}
-}
-```
-
-### 2.6 通用失败响应
-
-```json
-{
-  "code": 1201,
-  "message": "organization not found",
-  "details": {
-    "orgid": "SH001"
-  }
-}
-```
-
-约定：
-
-- `code = 0` 表示成功。
-- HTTP 状态码表示错误类别，`code` 表示具体错误。
-- `data` 只在成功且接口有返回数据时出现。
-- `details` 为可选的结构化错误信息。
-
-## 3. 机构数据库路由
-
-### 3.1 数据隔离模型
-
-FMS 采用一个机构一个数据库的隔离方式：
-
-```text
-orgid: SH001 -> database: fms_sh001
-orgid: BJ001 -> database: fms_bj001
-orgid: GZ001 -> database: fms_gz001
-```
-
-上述映射只表示逻辑关系，真实数据库名称和连接信息不能返回给前端。
-
-### 3.2 后端处理流程
-
-后端收到请求后按以下顺序处理：
-
-1. 登录时从 `orgid` 请求头获取机构标识；后续请求从访问令牌获取机构标识。
-2. 校验 `orgid` 的格式。
-3. 从服务端机构配置中查找机构。
-4. 检查机构是否启用以及数据库配置是否可用。
-5. 获取该机构对应的数据库连接或连接池。
-6. 在该机构数据库中完成认证或后续业务操作。
-7. 返回统一响应，不暴露数据库连接信息。
-
-### 3.3 登录状态与机构绑定
-
-- 登录成功后，访问令牌必须绑定当前 `orgid` 和用户标识。
-- 后续请求只以访问令牌绑定的 `orgid` 为准。
-- 后续请求不能通过请求头或请求体覆盖令牌中的 `orgid`。
-- 用户需要切换机构时，必须在登录请求头中传入目标 `orgid` 并重新登录。
-- 当前不提供 refresh；访问令牌过期后需要重新登录。
-- 当前不提供 logout；客户端退出时删除本地访问令牌。
-
-### 3.4 连接管理
-
-- 数据库连接配置由后端集中管理。
-- 后端可以为每个机构维护独立连接池。
-- 同一次请求只能访问一个机构数据库。
-- 机构数据库不可用时，不能自动切换到其他机构数据库。
-- 日志可以记录机构码，但不能记录数据库密码或完整连接字符串。
-
-## 4. 登录接口
-
-### 4.1 登录页面
-
-登录页面必须提供以下输入项：
-
-| 输入项 | 必填 | 说明 |
-|--------|------|------|
-| 机构码 | 是 | 用户所属机构的 `orgid` |
-| 用户名 | 是 | 用户登录账号 |
-| 密码 | 是 | 用户登录密码 |
-
-用户点击登录后，前端将机构码放入 `orgid` 请求头，将用户名和密码放入 JSON 请求体。
-
-### 4.2 请求
-
-```http
-POST /api/auth/login
-orgid: SH001
-Content-Type: application/json; charset=utf-8
-```
-
-请求体：
-
-```json
-{
-  "username": "zhangsan",
-  "password": "password"
-}
-```
-
-| 字段 | 位置 | 类型 | 必填 | 说明 |
-|------|------|------|------|------|
-| `orgid` | header | string | 是 | 登录页面填写的机构码，用于选择机构数据库 |
-| `username` | body | string | 是 | 登录账号 |
-| `password` | body | string | 是 | 登录密码 |
-
-### 4.3 处理规则
-
-- 后端先根据 `orgid` 选择机构数据库，再验证用户名和密码。
-- 登录失败时不能说明账号是否存在。
-- 密码不能写入日志或错误响应。
-- 登录成功后令牌绑定机构码和用户标识。
-- 当前不签发 refresh token。
-
-### 4.4 成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "access_token": "access-token",
-    "token_type": "Bearer",
-    "expires_in": 1800,
-    "organization": {
-      "orgid": "SH001",
-      "name": "上海分公司"
-    },
-    "user": {
-      "id": 1001,
-      "username": "zhangsan",
-      "display_name": "张三"
-    },
-    "permissions": [
-      "sales.order.create",
-      "sales.order.approve",
-      "finance.payment.view"
-    ]
-  }
-}
-```
-
-## 5. 前端按钮权限
-
-- `permissions` 是当前登录用户拥有的权限编码数组。
-- 权限编码由机构数据库中的用户、角色和权限配置产生。
-- 权限编码建议使用 `<模块>.<资源>.<动作>` 格式。
-- 前端根据权限编码设置按钮的禁用状态。
-- 用户没有对应权限时，按钮保持可见但不可操作。
-- 当前权限只控制前端交互，不作为后端业务授权条件。
-
-前端判断示例：
-
-```typescript
-const canApprove = permissions.includes('sales.order.approve')
-```
-
-## 6. 通用加载接口
-
-### 6.1 设计原则
-
-- 前端提交数据源、返回字段、过滤条件、排序和分页。
-- 前端不提交 SQL，也不编写参数占位符。
-- 后端根据结构化请求生成查询 SQL，并在后端内部绑定所有数据值。
-- 查询数据源可以是数据库表或视图。
-- 复杂关联、聚合和计算字段优先封装为数据库视图，再通过本接口查询。
-- 后端不为具体业务定义查询接口。
-
-### 6.2 请求
-
-```http
-POST /api/data/load
-Authorization: Bearer <access_token>
-Content-Type: application/json; charset=utf-8
-```
-
-请求示例：
-
-```json
-{
-  "source": "v_sales_order_list",
-  "fields": [
-    "id",
-    "order_no",
-    "customer_name",
-    "status",
-    "total_amount",
-    "created_at"
-  ],
-  "filter": {
-    "logic": "and",
-    "items": [
-      {
-        "field": "status",
-        "op": "eq",
-        "value": "pending"
-      },
-      {
-        "logic": "or",
-        "items": [
-          {
-            "field": "customer_name",
-            "op": "contains",
-            "value": "海运"
-          },
-          {
-            "field": "order_no",
-            "op": "starts_with",
-            "value": "SO2026"
-          }
-        ]
-      }
-    ]
-  },
-  "sort": [
-    {
-      "field": "created_at",
-      "direction": "desc"
-    }
-  ],
-  "page": {
-    "page_no": 1,
-    "page_size": 20
-  },
-  "include_total": true
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `source` | string | 是 | 数据库表名或视图名 |
-| `fields` | string[] | 是 | 返回字段，必须是非空数组 |
-| `filter` | object | 否 | 过滤条件组 |
-| `sort` | array | 否 | 排序规则 |
-| `page` | object | 否 | 分页；省略时使用默认分页 |
-| `include_total` | boolean | 否 | 是否计算符合条件的总记录数，默认 `false` |
-
-### 6.3 标识符规则
-
-- `source`、字段名和排序字段只能是数据库标识符，不能包含 SQL 表达式。
-- 标识符必须符合 `^[a-z_][a-z0-9_]*$`。
-- `source` 可以包含一个 schema 前缀，例如 `public.v_sales_order_list`。
-- 带 schema 的数据源必须符合 `<schema>.<object>` 格式。
-- 后端必须正确引用标识符，不能把标识符当作数据值拼接。
-- 字段必须真实存在于指定数据源中。
-- `fields` 只返回前端明确请求的字段，不支持 `*`。
-
-### 6.4 过滤条件
-
-过滤条件分为条件项和条件组。
-
-条件项：
-
-```json
-{
-  "field": "status",
-  "op": "eq",
-  "value": "pending"
-}
-```
-
-条件组：
-
-```json
-{
-  "logic": "and",
-  "items": [
-    {
-      "field": "status",
-      "op": "eq",
-      "value": "pending"
-    },
-    {
-      "field": "total_amount",
-      "op": "gte",
-      "value": 1000
-    }
-  ]
-}
-```
-
-条件组规则：
-
-- `logic` 只允许 `and` 或 `or`。
-- `items` 必须是非空数组。
-- 条件组可以嵌套条件组。
-- 所有 `value` 都由后端内部参数绑定，不作为 SQL 文本执行。
-
-支持的操作符：
-
-| `op` | 说明 | `value` 规则 |
-|------|------|--------------|
-| `eq` | 等于 | 单个值 |
-| `ne` | 不等于 | 单个值 |
-| `gt` | 大于 | 单个值 |
-| `gte` | 大于或等于 | 单个值 |
-| `lt` | 小于 | 单个值 |
-| `lte` | 小于或等于 | 单个值 |
-| `in` | 在列表中 | 非空数组 |
-| `not_in` | 不在列表中 | 非空数组 |
-| `between` | 在范围内，包含边界 | 两个元素的数组 |
-| `contains` | 文本包含 | string |
-| `starts_with` | 文本开头匹配 | string |
-| `ends_with` | 文本结尾匹配 | string |
-| `is_null` | 为 `NULL` | 不传 `value` |
-| `is_not_null` | 不为 `NULL` | 不传 `value` |
-
-补充规则：
-
-- `eq` 的值为 `null` 时按 `is_null` 处理。
-- `ne` 的值为 `null` 时按 `is_not_null` 处理。
-- `contains`、`starts_with` 和 `ends_with` 中的 `%`、`_` 默认作为普通字符处理。
-- 空数组不能用于 `in`、`not_in` 或 `between`。
-
-### 6.5 排序和分页
-
-- `direction` 只允许 `asc` 或 `desc`。
-- 可以指定多个排序字段，后端按数组顺序生成排序规则。
-- `page_no` 从 1 开始，默认值为 1。
-- `page_size` 默认值为 20，最大值为 5000。
-- 前端需要稳定分页时，应包含主键或其他唯一字段作为最后一个排序字段。
-
-### 6.6 成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "rows": [
-      {
-        "id": 128,
-        "order_no": "SO20260001",
-        "customer_name": "长荣海运",
-        "status": "pending",
-        "total_amount": 3500,
-        "created_at": "2026-07-14T10:30:00+08:00"
-      }
-    ],
-    "row_count": 1,
-    "total": 36,
-    "page_no": 1,
-    "page_size": 20
-  }
-}
-```
-
-响应规则：
-
-- `rows` 始终是数组，没有记录时返回空数组。
-- `row_count` 是本次实际返回的记录数。
-- `total` 只在 `include_total = true` 时返回，否则为 `null`。
-- `total` 表示忽略分页后符合过滤条件的记录数。
-
-## 7. 高级 SQL 加载接口
-
-### 7.1 适用范围
-
-`/api/data/load_sql` 用于结构化 `/api/data/load` 无法表达的高级只读查询，例如复杂关联、CTE、窗口函数和聚合查询。
-
-规则：
-
-- 该接口是可选的高级能力。
-- 只允许执行单条只读 SQL。
-- 允许 `SELECT`，以及所有 CTE 都是只读查询的 `WITH`。
-- 不允许 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、DDL、权限管理和事务控制语句。
-- 不允许通过分号附加第二条语句。
-- 即使最外层是 `SELECT`，也不允许在 CTE 中写入数据。
-- SQL 不支持参数占位符，前端不能把最终用户输入直接拼接到 SQL 中。
-- 包含页面动态筛选值的查询应优先使用 `/api/data/load`。
-- 返回行数和执行超时遵循普通加载接口限制。
-
-### 7.2 请求
-
-```http
-POST /api/data/load_sql
-Authorization: Bearer <access_token>
-Content-Type: application/json; charset=utf-8
-```
-
-请求示例：
-
-```json
-{
-  "sql": "SELECT customer_id, customer_name, COUNT(*) AS order_count, SUM(total_amount) AS total_amount FROM v_sales_order_list GROUP BY customer_id, customer_name ORDER BY total_amount DESC LIMIT 100"
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `sql` | string | 是 | 单条只读 SQL |
-
-### 7.3 成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "rows": [
-      {
-        "customer_id": 42,
-        "customer_name": "长荣海运",
-        "order_count": 18,
-        "total_amount": 63000
-      }
-    ],
-    "row_count": 1
-  }
-}
-```
-
-响应规则：
-
-- `rows` 始终是数组，没有记录时返回空数组。
-- `row_count` 是本次实际返回的记录数。
-- 排序、分页和总数由 SQL 自身决定。
-
-## 8. 通用保存接口
-
-### 8.1 设计原则
-
-- 保存接口支持在一次请求中新增、修改或删除多条数据。
-- 前端提交目标表、操作类型、数据值和过滤条件。
-- 前端不提交 SQL，也不编写参数占位符。
-- 后端根据结构化请求生成 SQL，并在后端内部绑定所有数据值。
-- 一个请求中的所有变更使用同一个数据库事务。
-- 任一变更失败时，整个请求回滚。
-- 后端不为具体业务定义保存接口。
-
-### 8.2 请求
-
-```http
-POST /api/data/save
-Authorization: Bearer <access_token>
-Content-Type: application/json; charset=utf-8
-```
-
-请求示例：
-
-```json
-{
-  "changes": [
-    {
-      "action": "insert",
-      "target": "sales_order",
-      "values": {
-        "id": "019f62d5-4115-7b22-8c51-8f89e2e8b421",
-        "order_no": "SO20260001",
-        "customer_id": 42,
-        "status": "draft",
-        "version": 1
-      },
-      "returning": [
-        "id",
-        "order_no"
-      ],
-      "expect_rows": 1
-    },
-    {
-      "action": "insert",
-      "target": "sales_order_item",
-      "values": {
-        "id": "019f62d5-4115-79db-ab88-99e8c5dc7f21",
-        "order_id": "019f62d5-4115-7b22-8c51-8f89e2e8b421",
-        "product_id": 301,
-        "quantity": 2,
-        "unit_price": 1750
-      },
-      "returning": [
-        "id"
-      ],
-      "expect_rows": 1
-    }
-  ]
-}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `changes` | array | 是 | 按顺序执行的变更，必须是非空数组 |
-
-### 8.3 Change 结构
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `action` | string | 是 | `insert`、`update` 或 `delete` |
-| `target` | string | 是 | 目标表或可写视图 |
-| `values` | object | insert、update 必填 | 要写入的字段和值 |
-| `filter` | object | update、delete 必填 | 确定修改或删除范围的过滤条件 |
-| `returning` | string[] | 否 | 保存后需要返回的字段 |
-| `expect_rows` | integer | 否 | 实际影响行数必须等于该非负整数 |
-
-### 8.4 保存规则
-
-- `target` 和字段名遵循查询接口的标识符规则。
-- `values` 必须是非空对象。
-- `values` 的值可以是 string、number、boolean、null、array 或 object。
-- array 和 object 作为数据库字段值时，由数据库字段类型决定如何转换。
-- `update` 和 `delete` 必须提供非空 `filter`，不允许无条件修改或删除整表数据。
-- 保存过滤条件使用查询接口定义的条件结构和操作符。
-- `returning` 省略时返回空数组。
-- `expect_rows` 不匹配时整个请求失败并回滚。
-- 数据库默认值通过省略对应字段触发。
-- `values` 不支持 SQL 函数、字段引用或其他原始 SQL 表达式。
-
-### 8.5 多表保存和主键
-
-保存接口不提供步骤结果占位符，也不支持后续变更引用前序变更的返回值。
-
-多表新增时，前端应提前生成 UUID 主键，并把主键和外键直接写入各个 change 的 `values`：
-
-```text
-前端生成订单 id
--> 前端把订单 id 写入订单数据
--> 前端把同一个订单 id 写入明细的 order_id
--> 一次提交所有 changes
--> 后端在同一事务中保存
-```
-
-如果某个表必须使用数据库生成的主键，则只能在本次请求的 `returning` 中获取，不能在同一次保存请求的后续 change 中引用。需要多表原子保存时，应优先使用前端生成的 UUID 主键。
-
-### 8.6 修改和乐观锁示例
-
-```json
-{
-  "changes": [
-    {
-      "action": "update",
-      "target": "sales_order",
-      "values": {
-        "status": "approved",
-        "version": 4
-      },
-      "filter": {
-        "logic": "and",
-        "items": [
-          {
-            "field": "id",
-            "op": "eq",
-            "value": "019f62d5-4115-7b22-8c51-8f89e2e8b421"
-          },
-          {
-            "field": "version",
-            "op": "eq",
-            "value": 3
-          }
-        ]
-      },
-      "returning": [
-        "id",
-        "status",
-        "version"
-      ],
-      "expect_rows": 1
-    }
-  ]
-}
-```
-
-前端读取当前版本号，保存时同时提交旧版本条件和新版本值。当其他用户已经修改记录时，`expect_rows` 检查失败，整个请求回滚。
-
-### 8.7 成功响应
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "results": [
-      {
-        "index": 0,
-        "action": "insert",
-        "affected_rows": 1,
-        "rows": [
-          {
-            "id": "019f62d5-4115-7b22-8c51-8f89e2e8b421",
-            "order_no": "SO20260001"
-          }
-        ]
-      },
-      {
-        "index": 1,
-        "action": "insert",
-        "affected_rows": 1,
-        "rows": [
-          {
-            "id": "019f62d5-4115-79db-ab88-99e8c5dc7f21"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-响应规则：
-
-- `results` 顺序与请求中的 `changes` 一致。
-- `rows` 始终是数组。
-- `affected_rows` 表示该变更实际影响的记录数。
-- 事务提交成功后才返回成功响应。
-
-## 9. 错误规范
-
-| HTTP 状态码 | code | 说明 |
-|-------------|------|------|
-| 400 | 1001 | 请求 JSON 或字段结构错误 |
-| 400 | 1006 | 请求大小超限 |
-| 401 | 1101 | 机构码、用户名或密码错误 |
-| 401 | 1102 | 访问令牌无效或已过期 |
-| 404 | 1201 | 机构不存在 |
-| 409 | 1202 | 机构已停用 |
-| 500 | 1203 | 机构数据库未配置或配置无效 |
-| 400 | 1301 | 数据源、目标或字段标识符格式错误 |
-| 400 | 1302 | 过滤条件、排序或分页格式错误 |
-| 400 | 1303 | 保存变更结构错误 |
-| 400 | 1304 | SQL 为空、包含多条语句或不是只读查询 |
-| 409 | 2001 | `expect_rows` 与实际影响行数不一致 |
-| 409 | 2002 | 唯一键、外键、非空或检查约束冲突 |
-| 409 | 2003 | 死锁、序列化失败或其他并发冲突 |
-| 422 | 3001 | 数据源、目标或字段不存在 |
-| 422 | 3002 | 数据值无法转换为数据库字段类型 |
-| 500 | 3003 | 数据库执行失败 |
-| 503 | 9001 | 机构数据库不可用 |
-| 500 | 9002 | 服务端内部错误 |
-| 504 | 9003 | 查询或保存执行超时 |
-
-错误响应不能泄露真实数据库名称、地址、端口、账号、密码或连接字符串。
-
-保存请求执行失败时，错误响应的 `details` 应包含失败的 `change_index`。约束冲突可以返回约束名称，但不能返回生成后的完整 SQL。
-
-## 10. 执行限制
-
-默认限制：
-
-| 项目 | 限制 |
-|------|------|
-| 单次请求大小 | 2 MB |
-| load 最大返回行数 | 5000 行 |
-| load_sql 最大返回行数 | 5000 行 |
-| load 最大过滤条件数 | 200 个 |
-| save 最大变更数 | 100 个 |
-| 单个 change 最大字段数 | 500 个 |
-| load 执行超时 | 30 秒 |
-| load_sql 执行超时 | 30 秒 |
-| save 执行超时 | 60 秒 |
-
-规则：
-
-- 超过返回行数限制时请求失败，不静默截断结果。
-- save 超时包含全部变更和事务提交过程。
-- 限制值可以通过后端配置调整。
-
-## 11. 当前范围
-
-当前文档只定义：
-
-- 全部请求使用 `POST` 的通用规范。
-- 机构码传递和机构数据库路由规则。
-- 登录接口。
-- 登录响应中的用户信息和前端按钮权限。
-- 通用结构化查询接口。
-- 高级只读 SQL 查询接口。
-- 通用结构化保存接口。
-- 通用响应和基础错误码。
-
-当前不提供原有的 `/api/query` 和 `/api/transaction`。数据访问统一使用 `/api/data/load`、`/api/data/load_sql` 和 `/api/data/save`。
-
-文件、导入、导出、报表以及页面和菜单加载方式将在后续单独设计。
-
-## 12. TypeScript 类型参考
-
-```typescript
-interface ApiResponse<T> {
-  code: number
-  message: string
-  data?: T
-  details?: Record<string, unknown>
-}
-
-interface LoginRequest {
-  username: string
-  password: string
-}
-
-interface LoginResult {
-  access_token: string
-  token_type: 'Bearer'
-  expires_in: number
-  organization: {
-    orgid: string
-    name: string
-  }
-  user: {
-    id: string | number
-    username: string
-    display_name: string
-  }
-  permissions: string[]
-}
-
-type DataScalar = string | number | boolean | null
-type DataValue = DataScalar | DataValue[] | { [key: string]: DataValue }
-
-type FilterNode = FilterCondition | FilterGroup
-
-interface FilterCondition {
-  field: string
-  op:
-    | 'eq'
-    | 'ne'
-    | 'gt'
-    | 'gte'
-    | 'lt'
-    | 'lte'
-    | 'in'
-    | 'not_in'
-    | 'between'
-    | 'contains'
-    | 'starts_with'
-    | 'ends_with'
-    | 'is_null'
-    | 'is_not_null'
-  value?: DataValue
-}
-
-interface FilterGroup {
-  logic: 'and' | 'or'
-  items: FilterNode[]
-}
-
-interface LoadRequest {
-  source: string
-  fields: string[]
-  filter?: FilterGroup
-  sort?: Array<{
-    field: string
-    direction: 'asc' | 'desc'
-  }>
-  page?: {
-    page_no: number
-    page_size: number
-  }
-  include_total?: boolean
-}
-
-interface LoadResult<T = Record<string, unknown>> {
-  rows: T[]
-  row_count: number
-  total: number | null
-  page_no: number
-  page_size: number
-}
-
-interface LoadSqlRequest {
-  sql: string
-}
-
-interface LoadSqlResult<T = Record<string, unknown>> {
-  rows: T[]
-  row_count: number
-}
-
-type SaveAction = 'insert' | 'update' | 'delete'
-
-interface SaveChange {
-  action: SaveAction
-  target: string
-  values?: Record<string, DataValue>
-  filter?: FilterGroup
-  returning?: string[]
-  expect_rows?: number
-}
-
-interface SaveRequest {
-  changes: SaveChange[]
-}
-
-interface SaveResult<T = Record<string, unknown>> {
-  results: Array<{
-    index: number
-    action: SaveAction
-    affected_rows: number
-    rows: T[]
-  }>
-}
-```

code/fms/软件需求.md

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