95 lines
6.0 KiB
Markdown
95 lines
6.0 KiB
Markdown
# 见势 · Veyra
|
||
|
||
AI 量化投资辅助产品。原始交互原型与全栈设计文档保留在根目录；当前交付包括工程基础、开发登录、管理员用户查询与账户初始化。
|
||
|
||
## 已实现
|
||
|
||
- Go 模块化 API、JSON 日志、请求 ID、健康检查、超时与优雅停机。
|
||
- PostgreSQL 建库命令、事务迁移、并发迁移锁及历史迁移 checksum 校验。
|
||
- `veyra_user` / `User`、`veyra_account` / `Account`；主键为 `varchar(36)` UUID，Go 使用 string。
|
||
- 所有表、字段、索引按项目规范命名，包括 `veyra_schema_migration`。
|
||
- Vite + React + TypeScript + Tailwind CSS 4 + shadcn/ui 管理端，暖白、炭黑、焦糖橙主题，构建产物通过 Go embed 嵌入 API 二进制。
|
||
- 管理端读取 API 实际探测结果，十个工作区入口已建立，尚未实现的业务页面明确显示建设中。
|
||
- 管理端登录、HttpOnly Cookie 会话、退出撤销、用户列表；Redis 按来源 IP 和登录名限流，依赖失败时拒绝登录。
|
||
- App 开发登录与 Bearer 会话；管理端和 App 会话互相隔离，数据库只存凭据哈希。
|
||
- 账户创建、列表与汇总；模拟账户初始现金与流水原子入账，金额使用整数分，API 使用十进制字符串。真实记录账户现金为未知。
|
||
|
||
## 启动
|
||
|
||
需要 Go 1.26.2 与支持 Vite 的 Node.js，已提交 Go 和 npm 锁文件。根目录执行：
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
```
|
||
|
||
将 PostgreSQL 用户名与密码填写到 `.env`。默认数据库名称 `veyra`，默认管理数据库 `postgres`；创建数据库需要连接角色具有 CREATEDB 权限。Redis 无用户名，有密码：在本地 `.env` 配置 `REDIS_PASSWORD`，保持 `REDIS_USERNAME` 为空。`PGSSLMODE=disable` 是本地模板值，如服务器要求 TLS 则修改。
|
||
|
||
```sh
|
||
go mod download -C services/api
|
||
npm ci
|
||
make db-create
|
||
make db-migrate
|
||
make admin-create
|
||
make api
|
||
```
|
||
|
||
启动后访问 `http://127.0.0.1:8080`，管理端由 Go embed 提供，页面与 API 同源。需要前端热更新时另开终端运行 `make admin-dev`，访问 Vite 输出的本地地址；开发代理将 `/api` 转发到 `127.0.0.1:8080`。API 可在数据库未配置时启动并如实报告不可就绪。
|
||
|
||
管理端初始登录名与密码由 `.env` 的 `ADMIN_LOGIN` / `ADMIN_PASSWORD` 配置，密码要求 12–72 字节。开发环境的本地 `.env` 已单独生成随机密码，模板不包含密码。`make admin-create` 创建身份，不覆盖已有管理员。App 测试身份使用 `DEV_USER_LOGIN` / `DEV_USER_PASSWORD` 和 `make user-create` 初始化。数据库的登录账号不用于产品登录。
|
||
|
||
已有数据库只需 `make db-migrate` 应用新增的 `000002_identity_account.sql`，无需重新建库。
|
||
|
||
`make build` 先构建前端并复制到 embed 目录，再输出 `bin/veyra-api`、`bin/veyra-db` 和 `bin/veyra-user`。运行 `./bin/veyra-api -env-file .env` 无需外置前端文件或 Node.js。修改前端必须重新构建 Go 二进制；直接 `go build` 不会自动编译前端。清空构建产物的 checkout 仍可编译基础 API，管理端返回明确的 503 提示直到完成前端构建。
|
||
|
||
### 账户 API 示例
|
||
|
||
测试身份初始化后，`POST /api/v1/auth/login` 使用 `login_name` 和 `password` 返回开发访问凭据。后续请求使用 `Authorization: Bearer <access_token>`。
|
||
|
||
`POST /api/v1/accounts` 的模拟账户请求：
|
||
|
||
```json
|
||
{"mode":"simulation","name":"模拟账户","initial_cash":"100000.00"}
|
||
```
|
||
|
||
真实记录账户请求省略 `initial_cash`，返回 `cash_balance: null`、`ledger_status: INCOMPLETE`。同一用户每种模式只可创建一个账户；重复创建返回 409，不重复生成初始资金。`GET /api/v1/accounts` 返回当前用户账户，`GET /api/v1/accounts/{id}/summary` 查询归属当前用户的账户，其他用户的 ID 返回 404。
|
||
|
||
### 开发登录边界
|
||
|
||
密码登录和命令行身份初始化仅在 `APP_ENV=local/test` 开启；其他环境拒绝开发登录。正式 App 短信登录、访问凭据刷新、管理端 MFA 与细分 RBAC 尚未实现。当前会话为 8 小时、服务端可撤销；Cookie 写操作要求同来源 Origin。开发模式可使用 Vite 的同源代理，部署代理的 HTTPS 信任配置将在正式认证阶段实现。
|
||
|
||
```sh
|
||
make test
|
||
make check
|
||
```
|
||
|
||
PostgreSQL 集成测试需显式提供测试数据库，测试在独立临时 schema 内运行并清理：
|
||
|
||
```sh
|
||
VEYRA_TEST_DATABASE_URL='postgres://user:password@host:5432/test_db?sslmode=disable' make test
|
||
```
|
||
|
||
## 目录
|
||
|
||
```text
|
||
apps/admin/ Vite React 管理端
|
||
services/api/cmd/api/ API 入口
|
||
services/api/cmd/db/ 建库与迁移入口
|
||
services/api/cmd/user/ 开发身份初始化入口
|
||
services/api/internal/identity/ 身份领域
|
||
services/api/internal/portfolio/ 账户领域
|
||
services/api/internal/operations/ 服务健康业务
|
||
services/api/internal/platform/ 配置与数据库设施
|
||
services/api/internal/transport/ HTTP 协议适配
|
||
services/api/api/openapi.yaml 当前 HTTP 契约
|
||
```
|
||
|
||
采用显式 SQL 和结构体 db tag，避免 ORM 隐式推断表名。迁移打包到 Go 二进制，已执行迁移不可改写，后续修改新增版本。API 启动不自动建库或迁移。健康检查不会返回连接串和供应商错误细节。
|
||
|
||
## 待完成
|
||
|
||
用户已确认执行首次建库迁移。此次新增第二版迁移和身份初始化需在可访问数据库的终端运行；当前执行环境禁止访问目标内网地址和监听本地端口。单元测试及无监听的 HTTP 测试可以本地执行，真实数据库集成测试只有配置测试连接时才会运行。
|
||
|
||
尚未接入候选审核、交易计划、成交账本、App UI、行情、AI、Worker 或回测。下一步建设候选修订、审核发布与计划闭环，再落实成交账本和风险监控。
|
||
|
||
管理端基础组件按 [shadcn/ui 的 Vite 集成方式](https://ui.shadcn.com/docs/installation/vite)维护在 `src/components/ui`，Tailwind 使用[官方 Vite 插件](https://tailwindcss.com/docs/installation/using-vite)。
|