break
a795ca3650
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m25s
108 lines
3.6 KiB
Markdown
108 lines
3.6 KiB
Markdown
# 君鸿卡管系统
|
||
|
||
Go/Fiber 后端，负责物联网卡与设备、套餐、订单、钱包、分佣、审批、轮询任务及第三方渠道协作。
|
||
|
||
## 前置条件
|
||
|
||
- Go 版本以 `go.mod` 为准。
|
||
- 可访问的隔离 PostgreSQL 与 Redis；仓库当前不提供本地依赖容器。
|
||
- `golang-migrate` 用于数据库迁移。
|
||
- 外部支付、Gateway、企业微信、短信和对象存储按需配置；不做对应操作时可保持未配置。
|
||
|
||
## 初始化配置
|
||
|
||
```bash
|
||
./scripts/setup-env.sh .env.local
|
||
```
|
||
|
||
脚本为交互式向导。启动前至少确认 PostgreSQL、Redis、JWT 和日志路径；本地日志建议写入仓库的忽略目录：
|
||
|
||
```bash
|
||
export JUNHONG_LOGGING_APP_LOG_FILENAME="$PWD/logs/app.log"
|
||
export JUNHONG_LOGGING_ACCESS_LOG_FILENAME="$PWD/logs/access.log"
|
||
```
|
||
|
||
不得复制 Makefile 中的历史数据库连接信息。
|
||
|
||
## 数据库迁移
|
||
|
||
空白隔离库先导入 `scripts/manual_db_release/generated/00_schema_baseline.sql`，再执行 `scripts/manual_db_release/06_mark_schema_migrations.sql` 标记版本 140，最后运行后续迁移；历史 1 至 114 已归档，不能直接对空库执行 `migrate.sh up`。`scripts/migrate.sh` 使用 `DB_*` 参数，与应用的 `JUNHONG_DATABASE_*` 前缀不同；显式传入的 `DB_*` 优先于 `.env`，只连接明确指定的隔离数据库：
|
||
|
||
```bash
|
||
DB_HOST=127.0.0.1 DB_PORT=5432 DB_USER=<USER> DB_PASSWORD=<PASSWORD> \
|
||
DB_NAME=<ISOLATED_DB> DB_SSLMODE=disable ./scripts/migrate.sh up
|
||
```
|
||
|
||
查看版本：
|
||
|
||
```bash
|
||
DB_HOST=127.0.0.1 DB_USER=<USER> DB_PASSWORD=<PASSWORD> \
|
||
DB_NAME=<ISOLATED_DB> ./scripts/migrate.sh version
|
||
```
|
||
|
||
## 构建与启动
|
||
|
||
```bash
|
||
go build ./cmd/api ./cmd/worker
|
||
./scripts/run-local.sh api # API
|
||
./scripts/run-local.sh worker # Worker
|
||
./scripts/run-local.sh both # 两者
|
||
```
|
||
|
||
`run-local.sh` 会加载 `.env.local`。Worker 角色由 `JUNHONG_WORKER_ROLE=all|leader|consumer` 决定。
|
||
|
||
## Smoke
|
||
|
||
API 默认监听 `:3000`。启动后执行：
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:3000/health
|
||
curl -fsS http://127.0.0.1:3000/ready
|
||
```
|
||
|
||
预期统一响应的 `data.status` 分别为 `healthy` 与 `ready`。外部依赖或配置不完整导致进程启动失败时，先查看应用日志。
|
||
|
||
## 日志与定位
|
||
|
||
```bash
|
||
tail -f logs/app.log
|
||
tail -f logs/access.log
|
||
rg '<REQUEST_ID>|<CORRELATION_ID>' logs/app.log logs/access.log
|
||
```
|
||
|
||
实际路径由 `JUNHONG_LOGGING_APP_LOG_FILENAME` 与 `JUNHONG_LOGGING_ACCESS_LOG_FILENAME` 决定。API 与 Worker 共用应用日志配置；访问日志只记录 HTTP 请求。
|
||
|
||
## 重置隔离数据库
|
||
|
||
以下命令会删除并重建整个数据库，只允许显式指向可丢弃的隔离环境：
|
||
|
||
```bash
|
||
JUNHONG_DATABASE_HOST=127.0.0.1 \
|
||
JUNHONG_DATABASE_PORT=5432 \
|
||
JUNHONG_DATABASE_USER=<USER> \
|
||
JUNHONG_DATABASE_PASSWORD=<PASSWORD> \
|
||
JUNHONG_DATABASE_DBNAME=<DISPOSABLE_DB> \
|
||
./scripts/reset_db.sh
|
||
```
|
||
|
||
执行前人工核对主机、端口和库名；不得指向生产或共享环境。
|
||
|
||
## Context 验证
|
||
|
||
```bash
|
||
go run cmd/gendocs/main.go
|
||
openspec doctor --json
|
||
openspec validate --all
|
||
./scripts/context-health.sh
|
||
```
|
||
|
||
自动化测试当前为 N/A（用户决策）；当前验证依赖构建、OpenAPI、OpenSpec、结构检查、smoke、日志和独立审计。执行 Go 命令时的 `GOCACHE`、`GOMODCACHE` 必须位于 `/private/tmp`，不得写入仓库或 `.lh-harness/`。
|
||
|
||
## 文档入口
|
||
|
||
- Agent 导航：[`AGENTS.md`](AGENTS.md)
|
||
- 系统地图：[`ARCHITECTURE.md`](ARCHITECTURE.md)
|
||
- 当前行为：[`openspec/specs/`](openspec/specs/)
|
||
- 工程约束：[`docs/engineering/工程约束.md`](docs/engineering/工程约束.md)
|
||
- 第三方契约：[`docs/integrations/`](docs/integrations/)
|