Skip to content

docs(account): document the risk assessment endpoint - #1332

Open
hogan-yuan wants to merge 9 commits into
mainfrom
docs/risk-assessment
Open

hogan-yuan wants to merge 9 commits into
mainfrom
docs/risk-assessment

Conversation

@hogan-yuan

Copy link
Copy Markdown
Member

Adds GET /v1/members/me/risk-assessment to the API Reference, and documents the longbridge risk-assessment CLI command and the trade.risk_assessment serve method, in en / zh-CN / zh-HK.

New Account / Profile subgroup — the existing Account subgroups (Portfolio, Alerts, DCA) are activity-based and none covers member profile data.

The API does not define pi's code values, the unit of pi_end_at / deadlines, or the scale of risk, so the docs state that explicitly rather than guessing. approvals values are documented as strings ("false", not boolean). strategy_risk_levels is described as the member's levels, with no claim about what they permit.

The response example keeps "pi_end_at": "0" as the string the gateway actually sends, while the CLI --format json example shows 0 as the integer the SDK exposes; the CLI page explains why they differ.

Also fixes a latent problem in serve.mdx: its method list claimed to be "what version 0.28.0 exposes", which adding a method would have turned into a false statement. It now defers to initialize and names no version.

Do not merge before the route ships

GET /v1/members/me/risk-assessment currently returns 404000 api not found in production (verified; /v1/risk/margin-ratio returns 401 on the same credentials, so this is routing, not auth). The CLI command and the serve method are also on unreleased branches. Merging now would publish request examples and a "try it" button that 404, and document a CLI command nobody can run.

Verification

  • openapi.yaml parses; npx vitest run passes (6 files / 60 tests), including the API-reference loader test
  • autocorrect --lint clean on all new and changed files
  • Every code sample's signature checked against the real SDK source (Rust, Node.js, Java, Python sync + async, C++, Go) and the CLI table output against src/cli/trade.rs

Depends on: longbridge/openapi#625

Adds `GET /v1/members/me/risk-assessment` to the API Reference, plus the
`longbridge risk-assessment` CLI command and the `trade.risk_assessment` serve
method, in en / zh-CN / zh-HK.

New `Account / Profile` subgroup: the existing Account subgroups (Portfolio,
Alerts, DCA) are activity-based and none covers member profile data.

The API does not define `pi`'s code values, the unit of `pi_end_at` and
`deadlines`, or the scale of `risk`, so the pages say exactly that instead of
guessing. `approvals` values are documented as strings ("false", not boolean),
and `strategy_risk_levels` as the member's levels, with no claim about what
they permit.

The HTTP response example keeps `"pi_end_at": "0"` as the string the gateway
actually sends, while the CLI `--format json` example shows `0` as the integer
the SDK exposes; the CLI page explains the difference.

The serve.mdx method list claimed to be "what version 0.28.0 exposes", which
adding a method would have made false. It is now version-agnostic and defers
to `initialize`.
The previous pass replaced "资质项"/"資質項" but the intro prose says 各项资质
— different word order, so the blind replace missed it in both Chinese
locales and in both openapi.yaml descriptions. Each of those files then
contradicted its own schema table two screens lower. Match the English
("the approval state of each item") everywhere.

The replace also left 各项的审核状态 with no head noun; say 各审核项的状态,
以项名为键, which carries the English "keyed by item name" the tables already
had and openapi.yaml did not.

The CLI permission line said "OAuth trade or account permission", a hedge
that cannot be checked while the route 404s and that no sibling page uses.
Say what every other account command says.
The permission line said OAuth account permission is required, copied from the
sibling account commands. Production says otherwise: this endpoint answers
403207 (access key product forbidden, a product-level check) while
margin-ratio answers 403308 (scope not authorized). The two are not gated
alike, so pointing readers at the account scope would have had them grant
something that does not unblock this call. State the error they will actually
see and what to do about it, without claiming a mechanism that has not been
confirmed.
The section was wrong twice over. It first claimed OAuth account permission,
copied from the sibling account commands; correcting that produced a second
section describing a 403207 and telling readers to contact Longbridge — an
internal onboarding instruction, and a description of the temporary state of
an un-provisioned test key rather than of the endpoint. It also implied the
command needs special provisioning, which nothing establishes.

The tool belongs to the General scope, and General commands carry no
permission section. The pages now end with the field-reading notes, like
their siblings.
Removing the wrong permission section took the login requirement with it. The
endpoint is /v1/members/me/*, so it needs a logged-in member, and 13 of the 14
sibling pages under cli/account carry that line. Use statement.mdx's wording
and claim nothing beyond it — what gates this endpoint above login was not
established: a 403207 can short-circuit before any scope check runs, and the
CLI authenticates by OAuth, which was never tested against this endpoint.
The opening sentence said the endpoint returns the profile of "the logged-in
member", and contradicted the sentence two lines below it, which already said
what is true: it always describes the member the access token belongs to.
There is no login at the API level — a caller signing requests with an app key
never logs in, and `me` resolves from the token. Both the English and the two
Chinese descriptions carried the invented version.

`approvals` was also described as "各审核项" (audit items). The four keys are
not one kind of thing: `car` / `cka` / `risk_audit` answer `pass`, but
`is_corporate_client` answers `"false"` — a flag, not an audit result. The
server gives a field named `approvals` and four keys; it does not say what the
keys are. Say "`approvals` 中各项", which follows the field name and claims
nothing further. English already did this ("each item"); only the Chinese had
added the extra layer.
`deadlines` was described as "each item's deadline" / 各项的截止时间, which
asserts two things the API does not establish: that its keys are the same
items as `approvals`, and that its values are points in time. The unit is
undocumented — seconds and milliseconds are both open — so even "time" is an
inference from the field name. Both environments have only ever returned an
empty object, so nothing observed supports either reading.

Say what is known: these are the `deadlines` entries, keyed by item name,
raw integers whose unit is undefined. `pi_end_at` keeps its wording because
the field explicitly documents `0` as "not set", which the server's own
behaviour shows.
Two layers of inference came off the description.

"(suitability questionnaire)" / "(适当性问卷)" equated this endpoint's risk
assessment with a suitability assessment in the compliance sense. The server
calls it `risk-assessment` and nothing more; the equivalence is domain
knowledge applied on top. "最近一次问卷的" and "问卷得分" carried the same
assumption about the form the assessment takes — the fields are only `risk`,
`score` and `risk_assessment_at`, so say 测评 / assessment.

The subject is now the account the access token belongs to, in all three
languages and in the field descriptions, per the product's own terminology.
Note that the path, the gRPC service and the token's `mid` all say member, and
the token carries `mid` and `aaid` separately, so the two are distinct ids in
the backend — the docs follow the product's wording rather than the backend's.
It said the data is "served by the trading API" / 由交易接口提供. The endpoint
is /v1/members/me/risk-assessment — nothing to do with orders, positions or
assets. What is actually true is narrower: the SDK exposes this method on its
TradeContext class. That is code organisation, not what the endpoint is, and
the sentence invited readers to assume trading permissions are involved.

The other four sections of this page each say what their context does rather
than where its data comes from; this one now matches. It also left English on
"member profile" after the Chinese had moved to 账户.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant