# 后端运行说明

本目录是公司财务报销与公司走账系统的一期后端服务。0.2.0 起支持两种模式：

- 未配置 `DATABASE_URL`：本地 JSON runtime 试运行；
- 配置 `DATABASE_URL`：PostgreSQL 正式入库，当前云端使用此模式。

## 本地启动

```bash
cd backend
npm install
npm start
```

默认监听：

```text
http://127.0.0.1:8787
```

## 健康检查

```bash
curl http://127.0.0.1:8787/health
```

健康检查会返回：服务版本、是否本地试运行、数据库模式、规则数量。

## 本地 JSON 自测

服务启动后运行：

```bash
npm test
```

自测会验证：

1. 健康检查；
2. 读取报销入库规则；
3. 缺字段校验；
4. 通过 MCP-like 入口创建报销草稿；
5. 生成预览；
6. 本地模拟提交事件。

## PostgreSQL 迁移与云端 DB 自测

配置 `DATABASE_URL` 后：

```bash
npm run db:migrate
npm run test:db
```

`test:db` 会创建一条报销草稿，commit 后写入：

- `intake_draft`
- `reimbursement_order`
- `reimbursement_item`
- `invoice`
- `invoice_link`
- `attachment`
- `audit_log`

真实环境测试后应清理 smoke test 数据，不要把测试报销单留作正式账。

## 云端当前入口

```text
https://wwyl.yipeng.online/finance-reimbursement/
https://wwyl.yipeng.online/finance-reimbursement/health
```

云端 systemd：

```text
company-finance.service
```

云端内部监听：

```text
127.0.0.1:8102
```

## 重要边界

- 本地 JSON 模式只用于调试接口和机器人流程，不等于正式财务入账。
- 云端 PostgreSQL 模式才是当前报销闭环正式入库路径。
- 发票/附件目前登记文件名、路径或 token 引用；不要把密钥、下载 token 或数据库连接串写入文档。
- 旧线上 `/finance/` 看板没有被本次部署覆盖；新系统暂走 `/finance-reimbursement/`。

## 常用接口

```text
GET  /health
GET  /api/intake/intents
GET  /api/intake/rules?intent=record_reimbursement
POST /api/intake/validate
POST /api/intake/preview
POST /api/intake/drafts
GET  /api/intake/drafts/:id
POST /api/intake/drafts/:id/commit
GET  /api/reimbursements
GET  /api/reimbursements/:id
GET  /api/dashboards
GET  /api/dashboards/reimbursements
GET  /api/dashboards/reimbursements/summary
POST /api/subjects/resolve
POST /api/projects/resolve
GET  /mcp/tools
POST /mcp/call
```