Skip to content

API.md

Latest commit

 

History

History
142 lines (103 loc) · 5.96 KB

API.md

File metadata and controls

142 lines (103 loc) · 5.96 KB
Raw

当前遗留 API 参考

实现状态：CURRENT LEGACY + PHASE 2 WORKTREE。 本文件主体仍记录冻结遗留接口。阶段 2 工作树已实现部分 /api/v1 会话、TOTP、激活、通知和组织只读接口，但阶段仍为 IN_PROGRESS，尚未通过用户审查，也不表示生产可用；阶段 3 以后库存、申请、多仓执行和会计接口仍未实现。实施顺序见 实施计划，版本策略见 ADR 0036。

当前遗留后端 API 的默认基地址为 http://localhost:8081。所有请求和响应均使用 application/json; charset=utf-8。

登录

POST /api/login

请求体：

{
  "username": "<username>",
  "password": "<password>"
}

成功响应 200：

{
  "token": "<token>",
  "role": "admin",
  "username": "<username>"
}
状态码 说明
400 用户名或密码为空
401 用户名不存在或密码不匹配
500 数据库查询或密码哈希升级失败

系统不提供默认登录口令。首次管理员由服务端环境变量创建，其他账户由管理员按部署流程配置。

查询货物

GET /api/goods?name=<name>&status=<status>

请求头：

Authorization: Bearer <token>

name 为可选模糊匹配，status 可取 stored 或 taken。 结果继续按数字 id 升序返回，以保持遗留协议行为。

成功响应 200：

{
  "items": [
    {
      "id": "G000001",
      "name": "显示器",
      "location": "A-01",
      "status": "stored",
      "storedAt": "2026-07-18 10:00:00",
      "takenAt": "",
      "operator": "warehouse-admin"
    }
  ]
}

入库

POST /api/goods，需要 manager 或 admin。

{
  "name": "显示器",
  "location": "A-01"
}

name 必填；location 为空时使用“默认货架”。成功返回 201 和新建的 item。

取出货物

POST /api/goods/take，需要 manager 或 admin。

{
  "id": "G000001"
}

编号也可以使用不带 G 前缀的数字。成功返回 200 和更新后的 item。

静态资源

路径 文件
/、/index.html public/index.html
/app.js public/app.js
/styles.css public/styles.css

非 /api/ 的 GET 请求由 public/ 提供；其他方法返回 405。

通用行为

  • 所有 /api/goods* 端点都要求 Authorization: Bearer <token>。
  • Token 由 libsodium 生成 256 位随机值并保存在进程内存中，服务重启后失效；它尚不具备目标 Cookie 会话的期限和统一撤销能力。
  • 跨源默认不授权；只有 WAREHOUSE_CORS_ALLOWED_ORIGINS 精确列出的来源才收到对应的 Access-Control-Allow-Origin，不接受通配符。
  • 服务使用有界 HTTP 工作线程与队列，并限制请求头、JSON 和总载荷；畸形 JSON 或字段类型错误返回 400。
  • 查询、入库和取出不再物理删除历史记录；30 天待归档规则将在后续库存生命周期阶段实现。

阶段 2 工作树接口与后续目标边界

阶段 2 工作树当前包含 POST /api/v1/sessions、GET|DELETE /api/v1/sessions/current、TOTP 绑定/确认与重新认证、离线激活凭据消费/重发/撤销、本人通知以及仓库/货位只读查询。它们仍处于阶段内集成和验证，不能描述为已批准或生产可用。

已注册的激活审计写路由返回 X-Request-Id；失败时错误对象的 requestId 与该响应头、应用命令和审计关联使用同一服务端值。默认审计 IP 为直接对等地址并忽略 X-Forwarded-For 与 Forwarded；只有按 ADR 0045 显式配置受信代理 CIDR 时才严格解析 X-Forwarded-For。这些传输字段只用于观察和审计，不构成身份凭据或授权依据。

登录、TOTP 确认和重新认证响应返回当前账户及新会话对应的随机 csrfToken，并由服务端设置 __Host-warehouse_session。GET /api/v1/sessions/current 返回：

{
  "account": {
    "id": "<account-id>",
    "username": "<username>",
    "role": "MANAGER",
    "assignmentComplete": true,
    "totpRequired": true,
    "totpEnrolled": true,
    "accessState": "FULL",
    "recentlyReauthenticated": true
  },
  "csrfToken": "<memory-only-recovery-token>"
}

current 响应使用 Cache-Control: no-store，读取严格只读，不刷新活动时间、期限、step-up 或访问状态。Cookie 写请求仍必须通过 Origin、Fetch Metadata 和 X-CSRF-Token；服务端接受当前会话保存的初始随机 CSRF 哈希或按 ADR 0044 现场派生的当前恢复值。恢复值不是长期凭据，不得进入浏览器持久化存储。

单元 3B 已冻结但尚未注册的目标合同包括：warehouse/location 创建与单资源 GET、governance request/decision 创建与单资源 GET，以及 POST /api/v1/governance/requests/{requestId}/activation-credential 和 /reissue。创建 Location 必须可由对应 GET 解引用；治理读取只允许申请发起者、已记录决定者或当前具全局账户治理权限的经理/监察员，且任何响应不得包含激活秘密。账户创建 receipt 只返回 accountId，不伪造尚未开放的账户资源 link。

仓库/货位创建、治理申请和治理决定要求 ADR 0046 的版本化永久 Idempotency-Key 合同；凭据领取/轮换绝不持久化或重放明文 receipt，响应丢失只能轮换。上述端点必须等 3B-2 至 3B-5 的迁移、codec、MySQL 工作单元和组合根全部完成后才可列为当前接口。

其他后续目标资源包括 SKU 与汇总库存、附件、公共库存申请及审批/复核/取消/执行、会计、跨仓调拨和账册集成。普通列表使用默认 50、最大 200 条的稳定键游标并返回 items/nextCursor；错误对象包含 code、message、details、requestId。旧接口在对应新用例、数据迁移、对账和用户审批完成前冻结保留。