FORGE 技术文档

1. 镜像概述和主要用途

FORGE 是一款选拔、评估与指导工具。客户通常为特种作战单位，使用 FORGE 记录候选人或成员的表现与性格数据，并通过生成的报告识别以下人员：

• 不适合该单位的候选人
• 需要补救或指导的人员
• 具备特定才能的人员

2. 核心功能和特性

• 数据记录与管理：记录候选人/成员的表现及性格数据
• 多维度评估：通过定制化指标进行综合评估
• 报告生成：自动生成候选人筛选、人员发展建议等报告
• API 接口：支持通过 API 进行数据交互与集成
• 权限控制：基于用户角色的访问控制（如超级用户）
• 数据分页：支持基于游标的分页查询，优化大数据集获取

3. 使用场景和适用范围

适用范围

• 主要用户：特种作战单位及需要人员选拔与评估的组织

典型使用场景

• 候选人选拔：评估候选人是否适合单位需求
• 人员发展：识别需要补救培训或指导的人员
• 人才识别：发掘具有特定才能的人员以优化团队配置
• 数据集成：通过 API 将评估数据与其他系统对接

4. 使用方法和配置说明

4.1 本地部署环境设置

本地开发环境设置详情请参考 SETUP.md。

4.2 ODS 数据库配置

4.2.1 部署数据库容器

使用以下命令启动 MSSQL Server 2019 容器：

bash
docker run -d \
  -e ACCEPT_EULA=Y \
  -e 'SA_PASSWORD=12qwaszx!@QWASZX' \
  -e MSSQL_PID=Express \
  -p 1433:1433 \
  -v mssql-data:/var/opt/mssql/ \
  --name ods-db \
  mcr.microsoft.com/mssql/server:2019-latest

环境变量说明：

• ACCEPT_EULA：是否接受最终用户许可协议（必须设置为 Y）
• SA_PASSWORD：SQL Server 系统管理员（sa）密码（需满足复杂度要求）
• MSSQL_PID：版本标识（Express 表示使用 Express 版本）

4.2.2 导入 bacpac 文件

1. 打开 Azure Data Studio 并连接本地数据库
2. 安装必要扩展：
   • SQL Server 管理包（Admin pack for sql server）
   • Windows 数据库管理工具扩展（database administration tool extensions for windows）
   • SQL Server Dacpac 扩展
3. 右键点击数据库连接，选择 "数据层应用向导"
4. 选择 "从 .bacpac 文件创建数据库（导入 bacpac）"
5. 指定 bacpac 文件路径并启动导入

4.2.3 配置数据库连接

1. 安装 freetds（通过 Homebrew）：

   bash
   brew install freetds
   

2. 编辑 database.yml 文件，替换必要配置：

   yaml
   development:
     primary:
       <<: *default
       database: forge_development
     ods:
       replica: true
       adapter: sqlserver
       database: CLD_MART_TESTDATA
       username: 'sa'
       password: 12qwaszx12QWASZX  # 与容器 SA_PASSWORD 对应
       host: localhost
   

5. FORGE API 使用指南

（为简洁起见，以下示例使用 cURL 命令）

5.1 获取认证令牌

• 请求方式：POST 至 /api/oauth/token
• 必要参数（-d）：
  • user_name：用户名（如 "dev"）
  • password：密码（如 "test"）
  • grant_type：授权类型（固定为 "password"，Doorkeeper 要求）
• 注意：指定用户必须为 :super_user 角色
• 可选参数：-L（若客户端返回 300/301 重定向时需添加）

示例命令：

bash
# 开发环境下运行 bin/setup 后可直接使用
curl -L -X POST "localhost:3000/api/oauth/token" -d "user_name=dev&password=test&grant_type=password"

# 返回 Bearer 令牌，例如：
=> lUyewt_myCaqblZDvkj1nfWniOsUibLSoXz8IelEkVE

注意：需根据 FORGE 部署地址更新 URL（如演示环境地址为 alpha.forgeapp.cloud）。部分情况下需使用 api 子域名（如 CLD 环境：api.cld.socom.mil）。

5.2 从 API 获取数据

5.2.1 必要请求头

• Bearer 令牌：Authorization: Bearer [token]（上文获取的令牌）
• 内容类型：Accept: application/json

5.2.2 可选参数

• -L：跟随重定向（cURL 需添加）
• 查询参数：
  • id：筛选指定 ID 的结果
  • cursor：获取下一页结果（分页用）
  • per_page：指定每页结果数

5.2.3 使用查询参数过滤结果

过滤当前请求

• FORGE API 响应包含数据对象的主键 :id 和关联字段 :RESOURCE_id（如军衔关联军种）
• 过滤格式：GET api/v1/enrollments?RESOURCE_id=ID
• 多参数用逗号分隔，支持链式过滤：/enrollments?cohort_id=7&job_id=1,2

获取子资源

• 示例：获取问卷 ID=1,2 的数据：

  bash
  curl -L -X GET "localhost:3000/api/v1/questionnaires?id=1,2" -H "Authorization: Bearer [token]" -H "Accept: application/json"
  

• 响应包含子资源 ID（如 perception_ids），可进一步请求：

  bash
  curl -L -X GET "localhost:3000/api/v1/perceptions?id=1" -H "Authorization: Bearer [token]" -H "Accept: application/json"
  

5.2.4 JSON 响应格式

所有响应包含分页元数据（pagination）和数据集（data）：

json
{
  "pagination": {
    "cursor": 0,
    "has_more": true,
    "per_page": 2
  },
  "data": [
    {
      "id": 1,
      "name": "Foo"
    },
    {
      "id": 2,
      "name": "Bar"
    }
  ]
}

示例：Attributes 端点

bash
curl -L -X GET "localhost:3000/api/v1/attributes" -H "accept: application/json" -H "Authorization: Bearer lUyewt_myCaqblZDvkj1nfWniOsUibLSoXz8IelEkVE"

响应结果：

json
{
  "pagination": {
    "cursor": 0,
    "has_more": true,
    "per_page": 5000
  },
  "data": [
    {
      "id": 1,
      "name": "Foo",
      "description": null,
      "parent_id": null,
      "weight": 1.0
    },
    ... 其他结果 ...
  ]
}

5.3 API 分页

FORGE API 采用基于游标的分页机制。

首次请求

可省略或显式指定 cursor=0：

localhost:3000/api/v1/scores
# 或
localhost:3000/api/v1/attributes?cursor=0

分页元数据说明

响应中的分页元数据包含：

• cursor：整数，当前页最后一条数据的 ID，用于请求下一页（默认/起始值为 0）
• has_more：布尔值，是否有更多结果
• per_page：整数，每页结果数（可通过查询参数自定义，默认 5000）

获取下一页

若 has_more 为 true，使用返回的 cursor 请求下一页：

# 示例：当前响应 cursor=121，请求下一页
localhost:3000/api/v1/attributes?cursor=121

6. API 开发指南

6.1 端点生成器

注意：需包含 api/v1/ 命名空间！

生成命令：

bash
bin/rails generate endpoint api/v1/cohorts

可通过传递参数自动生成属性、强参数等，具体选项参考 USAGE 说明。

6.2 使用 Swagger 生成 API 文档

创建 API 端点后，必须运行以下命令重新生成 Swagger 文档。需确保测试环境数据库存在，并使用 RAILS_ENV=test 前缀。

步骤：

1. 若测试数据库不存在，先准备测试环境：

   bash
   bin/rails db:test:prepare
   

2. 生成 Swagger 文档：

   bash
   RAILS_ENV=test bin/rails rswag:specs:swaggerize
   

© 2018 - 2023 SOFware LLC