0 Fork 0

mirror of https://github.com/tiennm99/miti99bot.git synced 2026-10-05 04:13:59 +00:00

Files

T

tiennm99 ffe9fb22e3 docs: remove completed plans, superseded reports, and journals

All eight plans are completed or cancelled and their behavior is now
described in README. Three reports contradicted shipped code: one
recommended keeping the lolesports gql client over PandaScore, two
analyzed the transport that migration removed. The rest is
pre-implementation research whose conclusions live in the code.

Drop the conventions reference to the deleted schema research.

2026-08-16 22:47:32 +07:00

2.7 KiB

Raw Blame History

Command Parameter Conventions

Overview

Every Telegram command declares optional Parameters metadata. The bot reuses that string in /help and Telegram's native command menu, so it must be short, consistent, and understandable on a phone.

Treat Parameters as display syntax, not as a validation schema. Handlers remain responsible for parsing and validation.

Syntax

Meaning	Format	Example
Required value	`<name>`	`<ticker>`
Required comma-separated values	`<name,...>`	`<option,...>`
Optional value	`[name]`	`[date]`
Optional remaining text	`[name...]`	`[target...]`
Alternatives in an optional group	`[literal	literal ]`

Use only constructs required by the command. Do not introduce a formal schema language or extra punctuation without a user-facing need.

Naming

Use lowercase snake_case.
Prefer one descriptive noun: <ticker>, <quantity>, <champion>.
Include units or currencies when they prevent ambiguity: <vnd_amount>, <usd_to_spend>.
Do not add primitive types such as <quantity:number> or <date:string>.
Keep literal subcommands bare: users, user, cmd.
Put spaces around | in alternatives.
Do not repeat format prose inside a placeholder.
Show punctuation that users must type exactly when omitting it would be error-prone. <ratio(owned:new)> and <option,...> are approved compact shapes.

Examples

/stock_buy <quantity> <ticker>
/lol [date]
/trongtruonghop [target...]
/stats [users | user <username> | cmd <command_name>]
/stock_share_dividend <ratio(owned:new)> <ticker>
/random <option,...>

Change Checklist

When adding or changing a command:

Make Parameters match the handler's accepted argument order.
Keep the parameter string single-line and concise enough for Telegram's command-description limit.
Update handler usage and error text to use the same syntax.
Update registration, handler, /help, and native-menu tests.
Update README or feature documentation when behavior is user-visible.
Follow the stats migration rules in AGENTS.md when a command name changes or a command is deleted.

2.7 KiB Raw Blame History