A 股市场分析工具开发约束

本文件是仓库内所有开发代理和开发者必须遵守的入口规范。详细规则见：

docs/governance/code-development-standards.md
docs/governance/development-workflow.md
docs/governance/documentation-traceability.md
docs/governance/version-control-and-gitea.md

强制要求

开发下一版本前必须先执行 npm run schema:baseline 和 npm run schema:verify，将上一已发布版本的开发库 Schema 基线用中文提交推送 Gitea；随后才能执行 npm run governance:start -- <功能编号> <短名称>，刷新 GitNexus 并完成开发前影响分析。
修改完成后必须执行测试、构建、视觉验证和 npm run governance:finish -- <功能编号> <短名称>，再次刷新 GitNexus并保存前后对比。
任何功能必须先有 docs/features/<功能编号>-<短名称>/ 功能档案；没有 PRD、需求、设计、计划和回退说明不得视为完成。
Git 提交必须使用中文 Conventional Commit，并带功能编号；禁止英文摘要和含糊提交信息。
代码必须为关键业务逻辑、数据口径、异常恢复和架构取舍提供准确的中文注释；禁止无意义逐行注释。
文件按稳定职责拆分，不以追求“原子化”为目的过度拆分。优先保证普通开发者能够连续阅读完整业务流程。
不使用 GitHub。本项目唯一远程仓库为项目级配置的 Gitea https://git.foximao.com/FoXiMao/a-share-analysis.git；禁止修改 Git 全局配置或影响其他项目。
禁止提交密钥、密码、访问令牌、生产数据、.env 和 GitNexus 本地索引；凭据不得写入远程 URL、文档、脚本或命令参数。
开发完成后必须先通过代码 Review 和开发规范符合性 Review，再进入发布；Review 结论和问题处置必须写入功能档案。
每次提交验证通过后必须立即推送当前分支到项目 Gitea；本次新建标签必须单独推送。推送失败时任务不得标记完成，禁止强推或自动覆盖未知远程提交。
Schema 基线只能读取 APP_ENV=development 的 a_share_analysis_dev，启用时主机必须命中代码内固定开发白名单（开发机回环地址或 112.192.20.11）；禁止连接、探测或读取生产数据库。MySQL 未启用时只允许生成可验证的 not_applicable 清单，启用但无对象时生成 captured_empty 清单，禁止用空 SQL 冒充基线。governance:start 还必须确认基线已提交、已推送且远程标签一致。
功能和缺陷修复开发前必须用 GitNexus 评估直接、间接及跨模块影响，并逐项判断 HTTP/OpenAPI、Web API、消息、数据库、Redis、API、Scheduler、Worker、部署、测试和文档是否同步修改；partial 结果不得视为无影响。
设计、测试计划和 Review 必须包含安全策略、性能目标、验证证据及残余风险；不适用项必须写明原因与边界。
每个未发布功能必须有独立 development-summary.md，明确原始需求、范围变化、实际完成、修复缺陷、延期项、关键提交和验证证据，不得合并到发布说明。
后端以业务模块为一级目录并在模块内按需分层，小模块不凑目录；前端统一由 web/src/utils/request.ts 封装 Axios，业务请求只能位于 web/src/api/<业务域>/index.ts，OpenAPI 类型继续作为契约来源。
复用代码只有在真实重复和稳定职责出现后才能抽取；新增依赖必须先评估用途、替代、安全、许可证、体积或运行成本、维护和退出方案。

GitNexus — Code Intelligence

This project is indexed by GitNexus as a-share-analysis (2358 symbols, 3190 relationships, 65 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.

If any GitNexus tool warns the index is stale, run npx gitnexus analyze in terminal first.

Always Do

MUST run impact analysis before editing any symbol. Before modifying a function, class, or method, run gitnexus_impact({target: "symbolName", direction: "upstream"}) and report the blast radius (direct callers, affected processes, risk level) to the user.
MUST run gitnexus_detect_changes() before committing to verify your changes only affect expected symbols and execution flows.
MUST warn the user if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
When exploring unfamiliar code, use gitnexus_query({query: "concept"}) to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use gitnexus_context({name: "symbolName"}).

Never Do

NEVER edit a function, class, or method without first running gitnexus_impact on it.
NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
NEVER rename symbols with find-and-replace — use gitnexus_rename which understands the call graph.
NEVER commit changes without running gitnexus_detect_changes() to check affected scope.

Resources

Resource	Use for
`gitnexus://repo/a-share-analysis/context`	Codebase overview, check index freshness
`gitnexus://repo/a-share-analysis/clusters`	All functional areas
`gitnexus://repo/a-share-analysis/processes`	All execution flows
`gitnexus://repo/a-share-analysis/process/{name}`	Step-by-step execution trace

CLI

Task	Read this skill file
Understand architecture / "How does X work?"	`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md`
Blast radius / "What breaks if I change X?"	`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md`
Trace bugs / "Why is X failing?"	`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md`
Rename / extract / split / refactor	`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md`
Tools, resources, schema reference	`.claude/skills/gitnexus/gitnexus-guide/SKILL.md`
Index, status, clean, wiki CLI commands	`.claude/skills/gitnexus/gitnexus-cli/SKILL.md`

6.2 KiB Raw Blame History