Development

开发指南

面向要改代码的人。权威版本是仓库里的 CONTRIBUTING.md， 本页是它的导读与展开。

环境

依赖	版本
Bun	1.2+（唯一的包管理与脚本运行器）
Node.js	^22.18.0 || >=24.12.0（Playwright 需要）

bun install
cp .env.example .env      # 按需填凭据；不填也能起来，只是没有数据
bun run dev               # 单进程：前端 5173 + 内置 API（读取 .env）

bun run dev:all 把前端与后端分开跑（后端 8787），仍然可用。

.env 的取值细节（多账号编号、$ 转义、Cookie 怎么填）全在 配置参考 与 凭据与多账号，不在这里重复。

四道门禁

提交前必须全绿，顺序固定：

bun run test:unit     # 1. Vitest
bun run build         # 2. vue-tsc 类型检查 + 构建
bun run test:e2e      # 3. Playwright（无凭据的空态冒烟）
bunx vp check         # 4. oxlint + oxfmt + tsgolint —— 必须最后跑

嫌麻烦就一条命令（顺序已固定，任一步失败即中断）：

bun run check

vp check 放最后是有原因的：它连 Markdown 表格对齐都管，会让前面刚改过的文件再次变动。 它报格式问题时用 bunx vp check --fix，然后再跑一次确认 0/0。

改了任意 .vue 文件，build 这道是必须跑的 —— vp check 不做模板类型检查， 只靠它会把类型错误放进仓库。

PR 流程

1. 从 main 切分支；分支名用扁平名（fix-xxx、feat-xxx），不要 feat/xxx。
2. 一个 PR 只做一件事。重构与行为变更不要混在同一个 commit 里。
3. 四道门禁全绿后提 PR 到 main，描述里写清「验收标准 → 实测结果」的对照。
4. 合并用 squash。合并后请重新拉 main 并复跑一次门禁 —— CI 与本地环境并不完全等价。

代码铁律

这些规则来自踩过的坑，不是风格偏好。

UI 与样式

• 只用 TDesign Vue Next，不迁移其他组件库，不模仿外部参考站。 CSS 变量一律 --td-*，禁止引入 --ui-* 之类的平行 token 层（两处维护必然漂移）。
• 布局只用 src/assets/layout.css 里的语义化网格原语。组件里禁写断点， 也禁用 t-row / t-col（TDesign 栅格是 12 列，与本项目的列策略冲突）。
• 列策略由「个数」声明、由 App.vue 统一施加：shouldSpanFullRow（≥2 整行）、 isCompactAccounts（≥5 单列紧凑）、metricGridClass、windowContainerClass。 改这些谓词要同时改 App.vue 的绑定与 layout.css 的规则 —— utils.test.ts 里有接线守卫盯着这三处。
• 间距 / 字号一律用 TDesign token，不写裸 px。
• 全局 CSS 改不动 scoped 组件的已有属性（.x[data-v] 的特异性高于 .x）。 断点要改组件已有属性时走变量过桥：值定义在 :root，组件只写 var(--x)。
• 弹窗居中必须 placement="center"（默认 top 会让顶距恒为 20vh）。
• 配色只准改 src/assets/theme.css：组件里不写颜色，那是全站唯一的配色入口。

数值与渲染

• <t-statistic> 只允许出现在 src/components/ui/MetricTile.vue，且必须显式声明精度 （不传 decimal-places 它会原样输出 0–20 位小数）。format.test.ts 有守卫。
• 渲染层禁止 toFixed / Math.round / toLocaleString —— 精度只走 src/format.ts 一个入口。
• 金额先过 truncateMoney（内含 1e-9 浮点补偿）再交给渲染层。
• 卡面货币只显示符号，币种代码只出现在详情弹窗；单位是独立元素； 币种未知时不要猜，只显示数值。

数据模型

• 详情视图统一建模成 AccountDetail（字段恒存在的扁平对象，失败取中性空值）， 平台差异收敛在各自 *Detail.ts 适配器里。Section 组件只负责 cardsOf(data.accounts, toXxxDetail) + <AccountCard>，模板里不认平台专属字段。
• 切片取值用 sliceData / sliceError，不要在调用点写 'data' in x（TS 不收紧调用表达式）。 多个子查询各自容错，避免共用 Promise.all 时一失败全丢。
• 环境变量的单一事实来源是 server/env-vars.ts。新增平台要动三处 （env-vars.ts 登记 + .env.example 说明 + .dev.vars.example 同步）， server/env-vars.test.ts 会断言漂移。

测试

• 单元测试与被测文件同目录；.spec.ts 是 E2E 专用。
• expect 只允许 1 个参数（vitest(valid-expect) 规则会拦）。
• 新增 server/*.test.ts 后确认它被 tsconfig.vitest.json 收进去了，否则会「假通过」。
• 读仓库文件用 resolve(dirname(fileURLToPath(import.meta.url)), …)，不要依赖 cwd。

Commit 与文档语言

• commit message 用中文，格式 <type>: <结论>，正文讲为什么， 不要逐条罗列改了什么文件。
• 设计决策与推导写进 docs/design-baseline.md， 不要只留在 PR 描述里。
• README 有两份：README.md（中文，权威版本）与 README.en.md（英文）。 改动功能 / 环境变量 / 部署步骤时两份一起改；英文版只做翻译， 不引入中文版没有的内容。两份不一致时以中文版为准。

凭据纪律（最重要的一条）

本仓库是公开的，且历史上曾误提交过真实令牌。因此：

1. 绝不把真实 API Key、Cookie、Token 粘进任何入库文件。需要举例时用占位值 （sk-xxxx / AKLTxxxx / example-ns）。
2. 测试夹具里的账号 id、命名空间、代金券码必须是编造的。 不要从真实响应里照抄 —— 命名空间、账号 id 这类值单看不敏感，但组合起来能定位到具体账号。
3. 本仓库历史上曾误提交过真实令牌，已用 git filter-repo 重写全部历史清除。 重写代价极高：所有 commit SHA 变更、已关闭 issue / PR 里引用的旧 SHA 全部失效， 还要强推 + 通知所有协作者重新克隆。不要重蹈覆辙。
4. 提交前自查：git diff --cached 里不应出现任何真实凭据或你个人的站点域名 （演示站地址这类有意公开的除外）。
5. 一旦发现已提交的真实凭据：先到平台吊销，再联系我们清理历史。 清理历史比吊销复杂得多，而且吊销才是真正让凭据失效的动作。

发现安全问题请走私密渠道，见 安全模型。

参与本项目即表示你同意遵守 CODE_OF_CONDUCT.md。