# CTMS 项目快速上手

## 交互安装入口
- 推荐执行 `./install.sh`，通过键盘 `↑/↓` 选择安装、更新、卸载、资源状态等操作；该入口不接受命令行参数。
- 菜单顶部会常驻显示当前 CTMS 容器部署状态，包括已检测到的环境、Compose 项目和容器运行数量。
- 底层脚本位于 `scripts/`：`install.sh`、`update.sh`、`uninstall.sh`、`status.sh`；状态脚本使用 `docker compose stats --no-stream` 采集资源快照并美化展示。

## 生产部署
- 生产入口：`docker-compose.yaml`
- 初始化方式：`docker compose run --rm backend-init`
- 启动方式：`docker compose up -d --build`
- 运行拓扑：`nginx`、`backend`、`db`
- 对外入口：`nginx` 提供前端静态资源，并同域反代后端 API
- 数据库 schema 来源：Alembic migration，不再依赖 `database/init.sql`
- 默认无任何业务预置数据；生产初始化只确保固定管理员 `admin@huapont.cn / admin123` 存在
- 生产环境必须配置 `LOGIN_RSA_PRIVATE_KEY`；登录密码传输使用 RSA-OAEP 包裹 AES-GCM 密钥，数据库仍只保存 bcrypt 哈希
- 浏览器端加密依赖 WebCrypto 安全上下文；生产访问必须使用 HTTPS，本地 `localhost` 例外
- 当前 challenge 缓存在后端进程内，默认最多保留 1000 个；多实例或多 worker 部署需改为共享缓存或启用粘性会话
- 验证方式：
  - `docker compose config`
  - `curl -i http://127.0.0.1:8888/`
  - `curl -i http://127.0.0.1:8888/health`

## 账号与注册
- 初始化管理员：`admin@huapont.cn / admin123`（通过生产初始化命令显式创建）
- 自助注册：前端 `/register` 提交邮箱、密码、姓名、角色（CRA/PV/IMP/PM）、部门，状态为 PENDING。
- 管理员审核：`/admin/user-approval` 列表查看待审核，支持通过/拒绝；仅 ACTIVE 用户可登录。
- 更多账号：管理员也可在 `/admin/users` 直接创建 ACTIVE 账号，再在项目成员中赋予角色。

## 角色权限概要（前端操作级提示，后端仍最终裁决）
- ADMIN：全权限
- PM：里程碑/任务维护、参与者状态、AE 创建/关闭、Issue 创建/关闭、Finance 创建/审批/支付、IMP 交易、FAQ 维护
- CRA：任务/参与者/AE/Data Query 创建，参与者状态更新，Finance 创建/提交，其他只读
- PV：AE 创建/关闭，Issue 创建/关闭，其余只读
- IMP：IMP 交易/产品/批次维护，其余只读
- 普通成员（无项目角色）：仅浏览

## 访问方式
- 前端：`http://localhost:8888`
- 后端 API：同域 `/api/v1/*`
- `nginx` 负责托管前端静态资源，并将 `/api` 与 `/health` 转发到 `backend`

## macOS 桌面端开发
- 桌面端遵循 `docs/desktop-project-plan.md` 第一阶段边界：Tauri 在线客户端，不内嵌后端、不保存本地业务数据、不做离线同步。
- 开发启动：进入 `frontend/` 后执行 `npm run desktop:dev`。
- 生产构建：进入 `frontend/` 后执行 `npm run desktop:build`；DMG 构建执行 `npm run desktop:bundle:dmg`。
- 首次启动桌面端会要求配置 CTMS 服务端地址，并在保存前检查 `${serverUrl}/health`。
- 生产或非本地服务地址必须使用 HTTPS；本地开发允许 `http://localhost` 或 `http://127.0.0.1`。

## 仓库治理文档
- 分支治理规范：`docs/branch-governance.md`
- 分支环境安装配置：`docs/guides/branch-environment-installation.md`
- 发布检查清单：`docs/guides/release-checklist.md`

## 本地配置
- 本地编辑器配置（如 `.vscode/`）不纳入版本库。
- 前端环境变量请使用 `frontend/.env`，可从 `frontend/.env.example` 复制。
- 根目录 `.env` 不作为当前默认启动流程的提交配置文件。
- Postman 本地环境请基于 `docs/postman/local.postman_environment.example.json` 自行复制，不提交个人环境文件。
- 文档入口见 `docs/README.md`；当前约束集中在分支治理、发布清单和治理审计文档，操作手册集中在 `docs/guides/`，历史交付记录集中在 `docs/reports/` 与 `docs/plans/`。

## 常用流程
1. 用管理员账号登录前端（默认 `admin@huapont.cn / admin123`）。
2. 进入左侧导航「账号治理」「项目治理」进行用户、项目、中心等全局管理；或在“项目列表”选择项目后进入项目内工作区。
3. Dashboard 查看进度、待办；左侧导航进入“里程碑”“任务”等页面。
4. 退出登录或切换项目可通过顶部右侧下拉。

## 管理员全局治理（前端入口）
- 账号治理：`/admin/users`（新建/编辑/启用禁用用户，重置密码需二次确认）
- 项目治理：`/admin/projects`（创建/编辑项目，成员配置 PM/CRA，中心管理）
- 中心管理：`/admin/projects/:projectId/sites`（中心创建/编辑、CRA 绑定、启用停用）

> ADMIN 具备所有 PM 权限，项目内操作与 PM 同步放行。

## 注意
- 登录使用邮箱 + 密码，前端会先获取登录公钥并加密提交；未审核/已拒绝/已停用账号无法登录。
- 令牌与当前项目上下文保存在浏览器 LocalStorage 中，清除后需重新登录/选择项目。
- 若后端重启，确认数据库容器仍健康，前端会弹出错误提示。