# miniproj

**Repository Path**: kdisi_admin/miniproj

## Basic Information

- **Project Name**: miniproj
- **Description**: 适合使用在一个完整的项目周期的清包管理系统，包含考勤，灵活工作安排
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-23
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# donghuanproj

施工工程管理系统脚手架：
- 后端：Go (`net/http`)，提供打卡、任务分配、工作量汇报、考勤与工作量统计 API
- 数据库：SQLite（默认文件 `backend/data/donghuan.db`）
- 前端：
  - `android-native`：原生 Android App（Kotlin）
  - `web-admin-react`：Web/H5 前端（React + TailwindCSS）
- 权限：`super_admin`、`project_admin`、`general_user`
- 认证：`/api/auth/login` 获取 JWT，业务接口必须使用 `Authorization: Bearer <token>`

## 目录结构

- `backend/` Go 后端
- `frontend/android-native/` 原生 Android App
- `frontend/web-admin-react/` React Web/H5 前端
- `skills/` 项目内技能
- `docs/` 接口与业务说明

## 文档索引

- `docs/api.md`：完整接口文档（Auth、App、Web、项目树管理、进度任务与日志、导出）
- `docs/architecture-and-flow.md`：整体架构与端到端调用流程
- `docs/android-release.md`：Android 发版与签名流程

## 后端启动

```bash
cd backend
go run ./cmd/server
```

服务地址（默认）：`http://localhost:8080`

健康检查（默认）：`GET http://localhost:8080/health`

可选数据库路径配置：
```bash
DB_PATH=./data/donghuan.db go run ./cmd/server
```

可选数据库维护配置（进度操作日志保留天数，默认 `0` 表示不自动清理）：
```bash
DB_PROGRESS_LOG_RETENTION_DAYS=90 go run ./cmd/server
```

可选 JWT 密钥配置：
```bash
JWT_SECRET='replace-with-your-secret' go run ./cmd/server
```

未设置 `JWT_SECRET` 时，服务会自动在数据库目录生成并持久化密钥文件（默认 `backend/data/.jwt_secret`），重启后复用同一密钥。
可选自定义密钥文件路径：
```bash
JWT_SECRET_FILE=./data/custom.jwt_secret go run ./cmd/server
```

可选服务端网络与 CORS 配置：
```bash
# CORS 白名单（逗号分隔）；默认 *
CORS_ALLOW_ORIGINS=https://admin.example.com,https://m.example.com \
# 服务超时
SERVER_READ_HEADER_TIMEOUT=5s \
SERVER_READ_TIMEOUT=15s \
SERVER_WRITE_TIMEOUT=30s \
SERVER_IDLE_TIMEOUT=60s \
# 最大请求头字节数（默认 1048576）
SERVER_MAX_HEADER_BYTES=1048576 \
go run ./cmd/server
```

HTTPS 启动（需要证书）：
```bash
cd backend
SERVER_ADDR=:8443 \
TLS_CERT_FILE=./certs/server.crt \
TLS_KEY_FILE=./certs/server.key \
go run ./cmd/server
```

统一入口地址：`http(s)://localhost:<port>`（不再使用 `5173/5174`）

Go 一键启停（Go + 静态文件，单入口）：
```bash
./scripts/appctl.sh start
./scripts/appctl.sh stop
./scripts/appctl.sh status
./scripts/appctl.sh restart
./scripts/appctl.sh logs
```

HTTPS 一键启动（需要证书）：
```bash
SERVER_ADDR=:8443 \
TLS_CERT_FILE=./backend/certs/server.crt \
TLS_KEY_FILE=./backend/certs/server.key \
./scripts/appctl.sh start
```

Makefile 快捷命令：
```bash
make up       # build 前后端并重启系统
make start    # 启动系统
make start-https TLS_CERT_FILE=... TLS_KEY_FILE=... [SERVER_ADDR=:8443]
make start-https-prod DOMAIN=example.com      # 使用 /etc/letsencrypt/live/<domain> 证书启动
make restart-https-prod DOMAIN=example.com    # 使用正式证书重启
make issue-cert DOMAIN=example.com EMAIL=ops@example.com
make issue-cert-aliyun-auto DOMAIN=example.com ALI_KEY=... ALI_SECRET=... [EMAIL=ops@example.com]
make stop     # 停止系统
make restart  # 重启系统
make status   # 查看状态
make logs     # 查看后端日志
```

说明：
- 启动脚本会直接用 Go 构建并启动 `backend/cmd/server`，不执行 npm。
- 默认托管静态目录 `frontend/web-admin-react/dist`，可通过 `WEB_DIST_DIR` 覆盖。
- 设置 `TLS_CERT_FILE` + `TLS_KEY_FILE` 后，服务会同时开启：
  - HTTPS：`SERVER_ADDR`（默认 `:8443`）
  - HTTP：`HTTP_ADDR`（默认 `:8080`，可设为 `disabled` 关闭）

## 正式证书签发（Let's Encrypt）

前置条件：
- `DOMAIN` 的 A 记录已指向服务器公网 IP。
- `http-01` 方式要求公网可访问本机 `80` 端口（云安全组/防火墙需放通）。
- 如果 `80` 端口不能放通，使用 `CHALLENGE=dns-manual` 按提示配置 DNS TXT 记录。

一键签发：
```bash
make issue-cert DOMAIN=example.com EMAIL=ops@example.com
```

手动 DNS 挑战签发：
```bash
make issue-cert DOMAIN=example.com EMAIL=ops@example.com CHALLENGE=dns-manual
```

签发成功后，以 8443 启动：
```bash
make start-https-prod DOMAIN=example.com
```

自动续期：
```bash
systemctl enable --now certbot-renew.timer
certbot renew
```

## 阿里云 DNS API 自动签发与续期（推荐）

适用于域名在阿里云 DNS（例如 `dns15.hichina.com` / `dns16.hichina.com`）托管的场景。

一键自动签发 + 自动续期 + 自动部署证书：
```bash
make issue-cert-aliyun-auto \
  DOMAIN=proj.example.com \
  ALI_KEY=<AccessKeyId> \
  ALI_SECRET=<AccessKeySecret> \
  EMAIL=ops@example.com
```

说明：
- 使用 `acme.sh --dns dns_ali` 走 DNS-01，避免 `http-01` 的 80 端口拦截问题。
- 证书会安装到：`/etc/letsencrypt/live/<domain>/fullchain.pem` 和 `privkey.pem`。
- 续期由 `acme.sh` cron 自动执行；续期成功后会自动执行：
- `./scripts/appctl.sh restart`（携带 `SERVER_ADDR=:8443` 与证书路径）

默认种子账号（通过 `/api/auth/login` 登录）：
- `super-admin`：超级管理员，拥有全部能力
- `project-admin-001`：项目管理员（默认不自动绑定项目）
- `worker-001`：一般用户，仅用于 App 端个人打卡与汇报

默认登录密码（用于 `/api/auth/login`）：
- `super-admin / super123`
- `project-admin-001 / project123`
- `worker-001 / user123`

可选演示数据（默认关闭，避免删除项目后重启又被回灌）：
```bash
cd backend
SEED_DEMO_PROJECT=1 SEED_SAMPLE_DATA=1 go run ./cmd/server
```

认证接口：
- `POST /api/auth/login`
- `POST /api/auth/refresh`
- `POST /api/auth/logout`
- `GET /api/auth/me`

## 前端启动

### Android 原生 App

```bash
cd frontend/android-native
./gradlew :app:assembleDebug
```

可选：覆盖 Android 端 API 地址（默认 `http://10.0.2.2:8080`）：
```bash
cd frontend/android-native
./gradlew -PANDROID_API_BASE_URL=http://192.168.1.4:8080 :app:assembleDebug
```

Android 正式签名发布请看：`docs/android-release.md`

产物路径：
- `frontend/android-native/app/build/outputs/apk/debug/app-debug.apk`

### Web 管理端（PC，React 推荐）

固定方式：先构建前端静态资源，再由 Go 后端统一托管（不使用 `npm run dev`）。

前端构建（仅用于产出 `dist`）：
```bash
cd frontend/web-admin-react
npm run build
```

启动 Go 服务（统一入口 `8080`）：
```bash
WEB_DIST_DIR=./frontend/web-admin-react/dist ./scripts/appctl.sh start
```

如需 HTTPS：
```bash
WEB_DIST_DIR=./frontend/web-admin-react/dist \
SERVER_ADDR=:8443 TLS_CERT_FILE=... TLS_KEY_FILE=... ./scripts/appctl.sh start
```

如需 HTTPS + HTTP 同时访问（默认即开启）：
```bash
WEB_DIST_DIR=./frontend/web-admin-react/dist \
SERVER_ADDR=:8443 HTTP_ADDR=:8080 TLS_CERT_FILE=... TLS_KEY_FILE=... ./scripts/appctl.sh start
```

### H5 移动端（与 Android App 核心能力对应）

- 统一入口（后端托管前端构建产物）：
  - HTTP: `http://localhost:8080/m/login`
  - HTTPS: `https://localhost:8443/m/login`（证书模式）
- 不使用独立前端开发端口（统一由 Go 托管构建产物）
- 默认示例账号：`worker-001 / user123`

> 说明：`8443` 为非低位端口，一般不需要额外绑定权限。

已覆盖 Android App 核心能力：
- 登录
- 上下班打卡
- 查看我的任务并更新进度
- 提交工作量汇报
- 个人资料维护（查看/修改资料、修改密码）
- 今日队友小组（本地保存）

## 编译（不含 Android）

```bash
make build
```

说明：`make build` / `make frontend` 默认构建 `frontend/web-admin-react`。

可选：
```bash
make backend
make frontend
```

## 构建三端（后端 + Android + Web）

```bash
make backend
(cd frontend/android-native && ./gradlew :app:assembleDebug)
make frontend
```

## 发版流程（固化）

1. 准备版本目录并更新 Android 版本号
```bash
./scripts/prepare-release.sh 0.1.1 101
```

2. 生成三端构建产物并写入哈希清单
```bash
./scripts/capture-release-artifacts.sh 0.1.1
```

3. 在 `release/0.1.1/` 中完成发布材料
- `CHANGELOG.md`
- `CHECKLIST.md`
- `ARTIFACTS.md`
- `packages/`（如含 APK/AAB）

参考：
- `release/README.md`
- `docs/android-release.md`

## 关键业务维度

工作量维度固定为：
- 项目名 `project_name`
- 建筑名 `building_name`
- 楼层 `floor`
- 房间号 `room_no`
- 工作面 `work_face`（如：布管、桥架、放线、端接、机柜安装）

详细接口见 `docs/api.md`（含项目结构树接口、进度日志追溯、Excel 导出接口）。