Imported from fin-research/dashboard (
AGENTS.md). Install upstream withnpx skills add fin-research/dashboard. Copyright stays with the author.
AGENTS.md
Project Overview
债券市场研究全栈应用，提供市场点评、市场热点、二级池周报及融资业务管理。技术栈为 SvelteKit、Svelte 5、TypeScript、Tailwind CSS 4、shadcn-svelte Maia、Bits UI、svelte-sonner、TanStack Table v9、ECharts、Cloudflare Workers/D1/R2/Workflows/Hyperdrive、Neon PostgreSQL 与 AI Gateway。
融资入口 /financing（仪表盘、负债周报、项目、SOP、台账）；管理中心 /management（角色权限配置）与全站个人信息 /profile。
页面入口、兼容路由和模块范围只在 docs/INDEX.md 维护。
Repository Structure
src/routes/：页面与 SvelteKit Worker API。src/components/、src/lib/components/：可复用 UI 组件。src/charts/：ECharts 配置和图表派生。src/api.ts、src/report-view.ts、src/text-report.ts：数据客户端与报告视图派生。src/lib/server/：仅服务端运行的数据访问、AI、快照和台账逻辑。src/lib/bond-ledger/：Excel 解析、校验、格式化与分析。worker/：自定义 Worker 入口和市场点评 Workflow。migrations/：D1 migration；postgres-migrations/：Neonbondschema migration；financing-model-migrations/：Neonfinancing_modelschema migration。authorization-migrations/：旧跨 schema 迁移的历史快照；后续权限 migration、Auth0 与角色授权由 Gateway 维护。auth0/：保留注册配置的历史来源；当前 Auth0 Actions、配置和发布由 Gateway 维护，见 Gateway。scripts/：类型生成、D1 同步、Neon migration 与台账回填。tests/：Node 单元与契约测试，融资原有回归位于tests/financing/。financing-migrations/、scripts/financing/：融资 schema migration 与本地维护命令；原 Excel 与凭证不迁入 Git。
Mandatory Rules
- 修改前先搜索现有页面、组件、图表、派生函数和测试；优先复用，不建立平行实现。
- UI 变更必须读取
DESIGN.md；保持既有桌面布局和移动端模块顺序，不自行引入新设计体系。 - 前端禁止解释性小字和口径扩写，保持简洁标签；交互说明通过控件、状态与布局表达，不另加提示文案。
- 跨服务路由、DATA / InternalData 与身份所有权遵循 共享架构；只改页面时按模块索引读取，不预读其他仓库。
- 市场点评 REST 编排与视觉/文字共用契约、旧资源兼容边界见 市场点评模块；业务加工留在 Dashboard。
- Data 消费端使用
src/data-contracts.ts的 Zod Schema 校验最小 DTO；字段投影与分页遵循 Data API 契约，不透传上游 envelope。债券动态代码与类型筛选见市场点评模块。 - 新闻详情扇出保持有界并发，复用
src/lib/server/data-news.ts和既有 DATA adapter。 - 身份只使用 Gateway 私有入口注入的
locals.user，权限只使用user.authorization；应用不验证 JWT、不回查 Auth0，不另建授权系统。保留记录归属和业务规则。精确认证、路由豁免、失败关闭与模式规则见 SECURITY。 - 一级发行视觉与文字输出必须共用
src/primary-issues.ts；文字报告不得读取 Python 归档文本。 - 热点首次访问只读最近成功快照；只有用户手动生成才调用模型并追加
hotspot_snapshot。旧快照的证据范围以快照自身为准。 - 二级池 Excel 在浏览器 Web Worker 解析，线上校验结构后归档原件并通过 Hyperdrive 单事务直接写入 Neon；不使用导入 Workflow，浏览器不缓存完整台账。
- D1/Neon/R2 所有权及跨仓库 migration 协同遵循 共享数据库；本地连接、日期和导入一致性遵循 DATABASE。
- 生成式 AI 仅通过
src/lib/server/ai-gateway.ts；传输、重试与检索遵循 共享 AI，业务 Prompt、Schema 和例外留在目标模块。 - 融资模型的 Quant / Dashboard 写入分工见 共享数据库，页面契约见 融资模型模块。
- 卖方观点使用研究库检索，授信助手使用独立授信材料库；不得跨用其证据来源和权限。具体检索分别见融资模型模块与 授信助手。
- 不手动编辑生成文件
worker-configuration.d.ts；绑定变化使用pnpm worker:typegen。 pnpm dev不自动同步远程 D1。只有任务明确需要本地证据时才运行pnpm db:sync:remote。- 保留用户已有改动，不做无关重构，不通过删除测试或关闭检查掩盖错误。
- 本地推送前必须通过
pnpm check:quick（差异、Svelte/应用及 Worker 类型检查）；逻辑变更或缺陷修复还须运行直接相关的轻量单元测试，不等待云端首次发现简单错误。纯文档修改只需git diff --check。完整验收保留在 GitHub Actions：任务分支 push 不触发 CI，PR 更新只核验合并队列门禁；准备合并时进入 GitHub merge queue，在最新 main 与队列改动的合并结果上运行Dashboard CI（类型、Python、Node 单元/覆盖率、构建、Playwright 浏览器组件集成测试及截图比较），合并后不重复跑全量 CI。本地默认不重复全量覆盖率、浏览器截图或生产构建，排障需要时可运行；本地通过不能替代当前提交的 CI 通过。 - 每次改完代码后派一个新的子代理负责提交/推送任务分支、创建或更新 PR、加入合并队列并核对最终合并组提交的 CI；推送与 CI 核验属于子代理执行职责。子代理不修改业务代码，失败时返回运行链接和日志，由主代理修复后重新委派。禁止直接推送
main或绕过必需检查；完整流程见 DEVELOPMENT。
CI 等待统一使用 node scripts/wait-ci.mjs <owner/repo> <run-id> <full-sha> <event>；一个运行只启动一次等待，主代理不并行轮询，终态齐备立即结束。候选只生成一次，审阅导入后由普通 CI 严格比较；具体超时、失败和停止条件见 CI 等待与收尾。
Commands
- 安装：
pnpm install - 开发：
pnpm dev - 类型检查：
pnpm typecheck - 推送前快速检查：
pnpm check:quick - 单元测试：
pnpm test - 生产构建：
pnpm build - Worker 本地运行：
pnpm worker:dev - Worker 类型：
pnpm worker:typegen - D1 migration：
pnpm db:migrate:local/pnpm db:migrate:remote - 显式同步远程 D1：
pnpm db:sync:remote - 权限 migration：
pnpm auth:db:migrate默认只读盘点；显式--apply才执行，替换账号需提供经确认的--person-mapJSON。 - Neon migration：
pnpm bond:db:migrate - 融资择时 Neon migration：
pnpm financing-model:db:migrate - 台账回填盘点：
pnpm bond:db:backfill；只有显式增加--apply才写入 - 部署：PR 经合并队列的 GitHub 必需检查后合并到
main，由 Cloudflare Git 自动构建部署；必要时可执行pnpm worker:deploy手动部署同一已验证提交。两种方式均无需再次向用户申请授权；部署后核对线上版本和受影响路由。
Context Routing
跨项目执行与并行工作树规则见 项目组 AGENTS；未在上下文中时读取一次。只加载任务相关文档，跨模块仅加读受影响部分，不重复读取已有上下文。
- 页面、API、业务或定时任务：先按 docs/INDEX.md 定位唯一模块文档与代码，再按任务叠加专题。
- UI、组件、图表、响应式、打印：加读 DESIGN。
- 本仓库分层：加读 ARCHITECTURE；只有跨服务变化才加读共享架构。
- SQL、日期、事务和导入：加读 DATABASE；共享表/存储归属变化才加读共享数据库。
- API / actions：加读 API；身份与权限：加读 SECURITY。
- 测试、开发和交付：加读 DEVELOPMENT。
- AI 调用：加读 共享 AI 与模块 Prompt/Schema；授信助手
credit_answer例外由 CREDIT_ASSISTANT 维护。
融资和管理功能不读取旧 Financing 文档作为当前规范。共享文档总入口为 项目组索引。
权限测试
共享认证架构、各权限范围及测试账号配置见 项目组 AUTH。权限登录与验收只使用程序化 HTTP、单元测试与 CLI，禁止 browser、Chrome、Playwright 和浏览器 MCP。新增测试仅使用匿名和 test@18.cn 两种身份；真实密码只读根目录 .env，不进入测试夹具或日志。
Auth0 租户配置与用户资料服务由 Gateway 维护。Dashboard 只经 IDENTITY: IdentityService 调用，不新增 Auth0 凭据或权限数据库 binding。历史维护脚本不构成运行时身份服务。
测试规范
页面或视觉变更先更新 visual-coverage.json 的证据/明确豁免；有意视觉变化在加入合并队列前主动生成、核对并导入当前 SHA 的 CI baseline 候选，不等待普通 CI 报截图差异。测试新增、合并、覆盖率与视觉回归按 TESTING 执行；不要通过源码样式或控件数量锁定代替行为验证。