# AGENTS.md

本文件用于指导通用代码代理（包括 Codex 类代理）在本仓库中的工作方式。

## 项目定位

本仓库是 **福建水务营收系统** 的技术文档仓库，目标是形成可直接用于评审、交付与实施参考的设计资料。

**当前工作重点不是编写业务代码，而是维护和优化文档体系。**

在未被用户明确要求的情况下，优先执行以下工作：

- 优化现有 Markdown 设计文档
- 对齐概要设计、详细设计、数据库设计、接口设计之间的口径
- 校正章节结构、术语、编号、图表、引用路径和归档关系
- 基于现有资料补全文档，不随意臆造业务规则或技术细节

## 仓库结构

```text
/
├── 00_Management/          # 项目管理、进度跟踪、交付规范、编写指南
├── 01_High_Level/          # 总体设计：系统概述、系统架构、概要设计、系统图谱
├── 02_Detailed/            # 详细设计：主详设、模块设计、CA 安装设计
├── 03_Technical/           # 技术专项：数据库、表结构、接口、安全、部署、加密
├── 04_Appendix/            # 附录与归档资料
├── .claude/                # Claude Code 相关配置
├── .omc/                   # 项目记忆与代理状态
├── .zed/                   # Zed 项目配置
├── assets/                 # 图片、模板等静态资源
├── docs/                   # 研究资料、映射文档、使用指南
├── scripts/                # 文档处理与导出脚本
└── infra/                  # 辅助基础设施
```

## 当前文档组织原则

### 主文档优先

优先维护以下主文档，不要轻易再创建新的平行版本：

- `01_High_Level/03_Summary_Design.md`：概要设计主文档
- `02_Detailed/01_Detailed_Design.md`：详细设计主文档
- `03_Technical/01_Database_Design.md`：数据库设计主文档
- `03_Technical/03_Interface_Design.md`：接口设计主文档
- `03_Technical/04_Security_Design.md`：安全设计主文档
- `03_Technical/05_Deployment_Design.md`：部署设计主文档

如果已有主文档可以承载内容，**优先编辑现有文件，而不是新增“新-xxx”“最终版”“修订版”之类文件**。

### Archive 仅作归档

`04_Appendix/Archive/` 下的内容默认视为历史资料、原始附件、操作手册或数据字典来源：

- 可引用
- 可核对
- 可整理路径
- **不作为新的正式交付主稿直接编辑替代**，除非用户明确要求

### 图片与附件成组维护

移动或重构归档资料时，必须同时检查：

- 同名 Markdown 与 `_images/` 目录是否一起迁移
- 图片相对路径是否仍然有效
- 文档中的内部链接是否需要同步修正

## 工作前必做检查

在修改任何正式文档前，优先查看：

1. `00_Management/01_Project_Progress.md`
2. `00_Management/02_Delivery_Standards.md`
3. `00_Management/03_Task_Checklist.md`
4. 与本次任务直接相关的目标文档

如果任务涉及结构性调整，还应同步查看：

- `00_Management/04_Writing_Guide.md`
- `docs/guides/` 下相关说明

## 文档编写与修改规则

### 语言与风格

- 全部正式文档内容使用中文
- 技术名词、框架名、代码标识符保留原文
- 风格要求专业、克制、可交付，避免口语化和宣传化表述
- 不写与当前项目无关的泛化模板内容

### 以“对齐现状”为第一原则

所有修改必须优先对齐以下事实来源：

- 当前仓库中的正式设计文档
- `04_Appendix/Archive/` 中的需求、手册、历史设计、数据字典
- `docs/guides/BACKEND_CURRENT_STATUS.md`
- `docs/guides/BACKEND_TABLE_MAPPING.md`
- 用户在对话中明确给出的最新口径

如果多个来源冲突，处理优先级通常为：

1. 用户当前明确要求
2. 当前主文档既有统一口径
3. 最新整理后的映射/指南文档
4. Archive 历史资料

如发现冲突且无法自行判定，应先说明冲突点，再继续修改。

### 不要过度发挥

- 不要凭空补充不存在的子系统、模块、接口、表
- 不要为了“显得完整”加入大量无依据的实现细节
- 不要默认加入大段代码示例、部署脚本、DDL、伪代码，除非用户明确要求
- 不要创建多余术语体系；优先沿用仓库现有命名

### 保持文档层级匹配

不同层级文档应保持抽象粒度一致：

- 概要设计：讲清结构、边界、模块职责、关键接口与部署原则
- 详细设计：讲清模块职责、流程、数据、接口、规则、约束
- 技术专项：按数据库、接口、安全、部署等主题展开，不与主文档冲突

不要把详细设计内容硬塞进概要设计，也不要把概要性表述替代详细设计。

## 关键一致性约束

### 项目名称

统一使用：

**福建水务营收系统**

除引用原始资料外，不要混用“营业收费系统”“数智营收管理系统”“客户服务平台”等作为正式系统名称。

### 数据库口径

若当前正式文档已统一到国产数据库方案，应优先保持与主文档一致；发现历史文档残留旧口径时，应按正式主文档修正，而不是反向改回历史版本。

### 模块编号与接口编号

涉及编号时遵循现有正式文档口径：

- 模块编号与接口编号必须可区分
- 接口编号优先采用带 `IF-` 前缀的形式
- 不擅自发明新的编号规则
- 修改某一处编号时，要检查同文档相关表格、目录、图表、正文描述是否同步

### 图表规范

- 所有正式图表优先使用 Mermaid
- 图表必须与正文一致，不能“图一套、文一套”
- Mermaid 节点命名尽量避免容易导致解析异常的写法
- 调整图表时，同时检查导出可用性和可读性

### 引用与链接

- 仓库内文档使用相对路径
- 修改目录后应同步修复引用
- 若引用 Archive 内容，尽量引用整理后的稳定路径

## 修改策略

### 适合直接修改的情形

- 术语统一
- 标题结构优化
- 章节顺序调整
- 表格字段对齐
- 图表与正文一致性修复
- 历史路径修复
- 主文档补充遗漏内容

### 需要先谨慎核对的情形

- 子系统拆分或合并
- 模块编号体系变更
- 数据库选型口径变化
- 大规模改写接口定义
- 归档目录重构
- 删除已有正式内容

遇到上述改动时，应先阅读相关文档上下文，避免只改一处导致全仓库不一致。

## Markdown 与 Marksman 工作流说明

本仓库的 Markdown 编辑与交叉引用检查可配合 Marksman 使用，以提升标题跳转、链接补全、引用检查与重命名体验。

### 适用场景

- 维护多篇 Markdown 设计文档之间的相对链接
- 检查标题锚点、文内链接、跨文档引用是否有效
- 在编辑器内进行标题跳转、引用查找与重命名
- 维护以仓库根目录为工作区的文档导航体验

### 工作区约定

- 仓库根目录中的 `.marksman.toml` 用于标记 Marksman 工作区根
- 如需稳定的跨文档能力，应从仓库根目录打开项目
- Markdown 文档应优先使用相对路径链接，并保持标题命名稳定

### 代理协作要求

- 当任务涉及 Markdown 链接修复、标题锚点检查、跨文档引用核对时，优先结合 Marksman 能力开展排查
- 若本机已安装 `marksman`，可直接用于工作区检查与编辑器集成
- 若本机未安装 `marksman`，应明确提示安装要求，而不是假设相关能力已经存在
- 如需环境自检，可优先使用仓库脚本：`scripts/check-marksman.sh`

### 安装建议

- macOS：`brew install marksman`
- Rust：`cargo install marksman`

### 使用提示

- 命令行查看帮助：`marksman --help`
- 作为语言服务运行：`marksman server`
- 若 macOS 阻止二进制运行，可执行：
  `xattr -d com.apple.quarantine "$(command -v marksman)"`

### 编辑器说明

- Zed 项目配置可通过 `.zed/settings.json` 为 Markdown 启用 Marksman
- 若编辑器未正确识别工作区，优先确认仓库根目录存在 `.marksman.toml`

## 常用工作命令

```bash
make help
make validate
make validate-file FILE=<filename>
make check-mermaid
make validate-mermaid
make check-links
make export-word
make export-pdf
make export-html
make unified-export
npm run check:marksman
npm run marksman:help
npm run marksman:server
```

如仅改动单篇文档，优先使用较小范围校验，而不是每次都跑全量导出。

## 修改后必须做的事

每次完成正式文档修改后，至少执行以下动作中的适用项：

1. 检查目标文档内容是否与上下文一致
2. 检查相关图表、目录、表格、交叉引用是否同步
3. 如属于正式文档的重要修改，更新 `00_Management/01_Project_Progress.md` 的变更记录
4. 如属于明确任务项完成，可同步更新 `00_Management/03_Task_Checklist.md`

## 对通用代码代理的具体要求

你在本项目中应优先表现为：

- 文档架构师
- 一致性审校者
- 归档整理与信息整编助手
- 基于现有资料进行保守补完的编辑者

而不是：

- 擅自扩展需求的产品经理
- 无依据发明实现细节的方案生成器
- 动辄新建文件的“版本制造机”

## 最终目标

确保仓库中的正式文档满足以下要求：

- 结构清晰
- 术语统一
- 图文一致
- 可追溯到来源资料
- 满足甲方交付语境
- 便于后续继续维护、评审与导出