# Alien 3rd Esign 模块开发文档

## 概览
基于 FastAPI 的电子签约子模块，负责店铺合同签约相关的接口、服务与数据访问。当前实现为骨架，需在此基础上补充业务逻辑。

## 目录结构
```
alien_3rd_esign/
├── main.py                    # 应用入口，挂载路由与健康检查
├── api/
│   ├── router.py              # 路由分组，当前仅根路径
│   └── deps.py                # 依赖注入，提供 ContractServer
├── db/
│   └── models/
│       └── contract_store.py  # 店铺合同表模型
├── repositories/
│   └── contract_repo.py       # 合同仓储（待实现）
├── services/
│   └── contract_server.py     # 合同服务层（待实现）
├── schemas/
│   ├── request/               # 请求 Pydantic 模型（待补充）
│   └── response/              # 响应 Pydantic 模型（待补充）
└── __init__.py
```

## 运行与环境
- 依赖外部配置 `alien_gateway.config.settings`，至少包含 `PROJECT_NAME`，以及数据库配置（见上游网关项目）。
- 数据库会话来自 `alien_database.session.get_db`，确保上游已配置 SQLAlchemy Engine/Session。
- 安装依赖后本地运行示例：
  ```
  uvicorn alien_3rd_esign.main:app --host 0.0.0.0 --port 8006 --reload
  ```

## 现有 API
- `GET /api/esign/`：模块存活确认，返回 `{"module": "Contract", "status": "Ok"}`。
- `GET /health`：健康检查，返回 `{"service": "sign", "status": "ok"}`。

## 数据模型
- `ContractStore`（表名 `contract_store`）
  - `store_id` (BigInteger, PK) 店铺 ID
  - `business_segment` (String) 经营板块
  - `merchant_name` (String) 商家姓名
  - `contact_phone` (String) 联系电话
  - `signing_status` (String, 默认“未签署”) 状态：已签署/未签署/已到期
  - `signing_time` (DateTime, 可空) 签署时间
  - `effective_time` (DateTime, 可空) 生效时间
  - `expiry_time` (DateTime, 可空) 到期时间
  - 继承 `AuditMixin`，包含审计字段（创建/更新人、时间等，具体见 `alien_database.base`）。

## 开发指引
- 路由层：在 `api/router.py` 按资源划分路由，通过 `Depends(get_contract_service)` 注入服务。
- 服务层：在 `services/contract_server.py` 编写业务逻辑（状态流转、有效期计算、外部电子签平台集成、权限校验）。
- 仓储层：在 `repositories/contract_repo.py` 实现对 `ContractStore` 的 CRUD、列表分页、状态更新等。
- Schema：在 `schemas/request/` 与 `schemas/response/` 定义 Pydantic 模型，约束字段、枚举和值域。
- 异常与校验：使用 FastAPI/HTTPException 统一错误响应；对输入做类型与业务校验。
- 测试：为服务和仓储编写单元/集成测试，可使用 SQLite 内存库或测试数据库。

## 后续待办（建议）
- 补充合同创建、查询、签署、续签、到期提醒等接口。
- 定义请求/响应 schema 与枚举，完善文档化（可结合 FastAPI OpenAPI/Swagger）。
- 增加仓储实现与事务管理，补齐状态机校验。
- 编写自动化测试与示例请求（如 HTTPie/Thunder Client 集合）。