docs: add zh-CN developer and product oriented README for 电力市场交易系统

README.md

@@ -1 +1,75 @@
-# usefulAgent
+# usefulAgent 电力市场交易系统
+
+一个基于 Next.js 的电力现货交易平台（MVP）。默认 UI 语言为简体中文（zh-CN），货币单位为人民币（CNY）。数据库使用 SQLite（后续可平滑迁移到 Postgres）。
+
+## 功能（MVP）
+- 市场与合约：小时级现货产品（后续可扩展 15 分钟区间）
+- 订单与撮合：限价单，价格-时间优先的连续撮合；支持撤单
+- 成交与结算：成交即时毛额记账（T+0 简化）
+- 市场数据：订单簿与最近成交（初版采用 1s 轮询，后续升级 WebSocket）
+- 角色与权限：Trader、Admin（基础审计与配置）
+
+## 技术栈
+- Next.js 14（App Router, TypeScript）
+- Prisma ORM + SQLite
+- 身份认证：NextAuth（占位，后续完善）
+- 国际化：next-intl（默认 zh-CN）
+- 日期/时区：dayjs / date-fns（zh-CN，本地时区 Asia/Shanghai）
+- UI：Tailwind CSS
+- 工具：ESLint/Prettier、Husky pre-commit、GitHub Actions（CI）
+
+## 本地开发
+> 注：若首次克隆仓库，先完成脚手架初始化与数据库迁移；完成后以下命令可用。
+
+- 环境要求：Node.js >= 18.18
+- 安装依赖：
+  - 使用你偏好的包管理器其一：`pnpm i` 或 `yarn` 或 `npm i`
+- 准备环境变量：
+  - 复制模板：`cp .env.example .env`
+  - 按需填写 `.env` 中的变量（见下文“环境变量”示例）
+- 数据库与迁移：
+  - 生成/更新 Prisma Client：`npx prisma generate`
+  - 运行开发迁移：`npx prisma migrate dev`
+  - 可选：初始化种子数据：`npx prisma db seed`
+- 启动开发服务：
+  - `pnpm dev`（或 `yarn dev` / `npm run dev`）
+
+当你看到本地 http://localhost:3000 打开成功，并展示中文界面，即表示初始化完成。
+
+## 环境变量（.env 示例）
+- DATABASE_URL="file:./prisma/dev.db"
+- NEXTAUTH_SECRET="请生成安全随机值"
+- TZ=Asia/Shanghai
+
+备注：
+- 生成 NEXTAUTH_SECRET 可使用：`node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+- 生产环境请设置 NEXTAUTH_URL 并妥善管理密钥。
+
+## 领域约定
+- 金额单位：数据库与后端以“分”（int）存储与计算；前端以“元”展示。涉及金额运算统一使用 Decimal/Big.js，避免浮点误差。
+- 实时性：MVP 阶段采用 1s 轮询获取订单簿/成交数据；后续将升级为 WebSocket 推送。
+- 撮合策略：价格-时间优先的连续双边限价撮合（Limit Order Book, LOB）。
+- 视觉语义：遵循本地金融惯例——上涨/买单用红，下降/卖单用绿。
+- 时区：统一使用 Asia/Shanghai，日期/时间格式遵循 zh-CN 习惯。
+
+## 目录结构（当前/规划）
+- src/app/：Next.js App Router 页面与路由
+- src/lib/：通用库（时间格式化、金额换算、Prisma 客户端等）
+- prisma/：Prisma schema、migrations 与 seed
+- messages/：多语言文案（默认 zh-CN）
+- src/app/api/：服务端路由与接口（Route Handlers）
+
+## 路线图（Roadmap）
+- v0.1 初始化脚手架（Next.js + Prisma + SQLite + i18n + CI）
+- v0.2 数据库模型与种子（订单、成交、资金流水、审计）
+- v0.3 撮合引擎 V1（内存订单簿 + 持久化）
+- v0.4 市场数据与订单簿 UI、下单/撤单流程
+- v0.5 权限/风控与运维工具
+
+## 贡献指南
+- 代码风格：ESLint + Prettier；提交前由 Husky 运行 `lint` 和 `typecheck`
+- Commit 规范：Conventional Commits（feat/fix/chore 等）
+- PR 说明：请包含变更动机、截图/录屏（如涉及 UI）、测试说明
+
+## 许可证
+本项目使用 MIT License（见 LICENSE）。