Repository navigation
docs(account): document the risk assessment endpoint - #1332
Open
hogan-yuan wants to merge 9 commits into
Open
hogan-yuan wants to merge 9 commits into
hogan-yuan wants to merge 9 commits into
Conversation
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 账户.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
GET /v1/members/me/risk-assessmentto the API Reference, and documents thelongbridge risk-assessmentCLI command and thetrade.risk_assessmentserve method, in en / zh-CN / zh-HK.New
Account / Profilesubgroup — 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 ofpi_end_at/deadlines, or the scale ofrisk, so the docs state that explicitly rather than guessing.approvalsvalues are documented as strings ("false", not boolean).strategy_risk_levelsis 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 jsonexample shows0as 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 toinitializeand names no version.Do not merge before the route ships
GET /v1/members/me/risk-assessmentcurrently returns404000 api not foundin production (verified;/v1/risk/margin-ratioreturns 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.yamlparses;npx vitest runpasses (6 files / 60 tests), including the API-reference loader testautocorrect --lintclean on all new and changed filessrc/cli/trade.rsDepends on: longbridge/openapi#625